mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update sub2api pk01 host-docker runbook

Browse Source
This commit is contained in:
Codex
2026-06-29 03:09:56 +00:00
parent 484936e0f7
commit 631bbada5d
4 changed files with 45 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/pk01.md
+4 -2
View File
@@ -66,11 +66,13 @@ PK01 may act as the public Caddy edge for several YAML-declared UniDesk services
If one public service fails while other services still work, restore the missing route through that service's YAML-controlled apply/public-exposure command, not by replacing the whole Caddyfile. A diagnostic check may list managed block markers with `grep '^# BEGIN unidesk managed ' /etc/caddy/Caddyfile` and run `sudo caddy validate --config /etc/caddy/Caddyfile`, but those checks are evidence only; durable repair belongs to the owning CLI.
In this mode, public ports `80` and `443` belong to Caddy. The existing `pikanode` container must be bound to a loopback HTTP port and used only as the apex PikaPython/PikaNode upstream. The `api.pikapython.com` site must reverse proxy directly to the YAML-declared FRP remote port, so API traffic follows `client -> PK01 Caddy -> PK01 frps remote port -> D601 frpc -> D601 Sub2API`. It must not pass through pikanode or a master-server reverse proxy.
In this mode, public ports `80` and `443` belong to Caddy. The existing `pikanode` container must be bound to a loopback HTTP port and used only as the apex PikaPython/PikaNode upstream. Public platform routes must be read from their owning YAML. For the current Sub2API PK01 host-Docker target, `api.pikapython.com` uses `publicExposure.mode=pk01-local` and API traffic follows `client -> PK01 Caddy -> 127.0.0.1:<YAML local upstream port> -> PK01 host-Docker Sub2API`. For k3s external-active targets, the route may instead be `client -> PK01 Caddy -> PK01 frps remote port -> target frpc -> target Sub2API`. Neither path may pass through pikanode or a master-server reverse proxy.
Caddy binary installation is also YAML-controlled. If `publicExposure.pk01.caddyDownloadProxyUrl` is set, PK01 Caddy downloads must use that proxy URL; the PK01 loopback provider egress proxy is the preferred source. A slow or failing Caddy download should first be treated as missing proxy use, not as a reason to keep retrying a naked GitHub release download.
The public certificate depends on DNS. The `api.pikapython.com` record must resolve to the YAML-declared PK01 public address before Caddy can complete ACME issuance. If the DNS record is absent or stale, local probes such as PK01 `127.0.0.1:<frp-remote-port>` and public-IP remote-port checks can prove the FRP data path, but final `https://api.pikapython.com` validation remains blocked until DNS is corrected.
The public certificate depends on DNS. The `api.pikapython.com` record must resolve to the YAML-declared PK01 public address before Caddy can complete ACME issuance. If the DNS record is absent or stale, local probes such as PK01 loopback app health checks, loopback Caddy `--resolve` checks, or target-specific FRP remote-port checks can prove parts of the data path, but final `https://api.pikapython.com` validation remains blocked until DNS is corrected.
For PK01 host-Docker Sub2API, `platform-infra sub2api status --target PK01` and `validate --target PK01` are the first-line app and edge checks. If a unified OpenAI-compatible key returns `account_select_failed` or `no available accounts` while a Sub2API WebUI account test succeeds, distinguish account test from gateway scheduling: the WebUI test loads one account directly, while gateway traffic uses the API key's group and the `account_groups` join table. Check the admin account availability view and the group membership for the target accounts, and verify public `/v1/responses` with a key fingerprint only. Do not print admin passwords, API keys, or account credentials while diagnosing this path.
## Host PostgreSQL