# 受控操作

## 配置路由

- 只在 `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 和临时目录。

## 部署与验收

```bash
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。
- 成功后运行：

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

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

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