pikasTech-unidesk/.agents/skills/unidesk-nginx/references/operations.md

受控操作

配置路由

• 只在 config/platform-infra/nginx.yaml 修改运行事实。
• targets.<id>.runtime.routes 支持一个或多个监听端口。
• 每个监听端口支持一个或多个 host、port 上游。
• CLI 把 routes 数组渲染为 NGINX_ROUTES，源码不保存应用专用端口。
• 一个上游是合法配置，不需要保留虚假的第二个上游。

配置 Logger

• LOGGER_PATH 指向容器内 JSONL 文件。
• LOGGER_MAX_BYTES 和检查周期必须明确设置，避免无限增长。
• LOGGER_ADMIN_PREFIX 控制 logger API 前缀。
• apiKey.sourceRef、sourceKey 和 targetKey 是唯一 Secret 来源。
• 健康接口不鉴权；查询、tail、下载和清理均使用 X-API-Key。

镜像与制品

• 镜像源码和本地验证入口位于 /root/demo/nginx-lb-logger。
• 镜像在 NC01 构建并验证单端口、多端口、原始请求恢复、API 和自动清理。
• owning YAML 固定镜像标签、镜像 ID、产物字节数和 SHA-256。
• PK01 使用 YAML 固定的官方静态 Compose 二进制，不能复用 Master 发行版动态插件。
• CLI 通过本机短时 HTTP server 暴露已校验制品。
• Compose 插件先快速 gzip，PK01 解压后校验原始 SHA-256。
• 无论 apply 成功或失败，都撤销本机 HTTP server 和临时目录。

部署与验收

bun scripts/cli.ts platform-infra nginx plan --target PK01
bun scripts/cli.ts platform-infra nginx apply --target PK01 --dry-run
bun scripts/cli.ts platform-infra nginx apply --target PK01 --confirm

• 从 confirmed apply 输出取得 statusCommand。
• 轮询 job 到 succeeded 或 failed，不要重复提交并行 apply。
• 成功后运行：

bun scripts/cli.ts platform-infra nginx status --target PK01

• status 必须确认：
  • 容器正在运行；
  • 当前镜像 ID 等于 YAML 期望值；
  • logger 健康接口返回 200；
  • activeTestBackends 为 0；
  • 输出不包含 API key 明文。

验证后端撤除后，测试业务端口没有活动上游属于预期状态。 部署真实应用前先把 routes 改为真实 host 服务，再走同一受控 apply。