---
name: unidesk-nginx
description: >-
  UniDesk Nginx 负载均衡与请求日志服务运维技能。用户提到 Nginx、platform-infra nginx、
  nginx-lb-logger、PK01 Nginx、HTTP 负载均衡、NGINX_ROUTES、多负载端口、JSONL 请求日志、
  logger API、日志查询下载清理或 LOGGER_API_KEY 时使用。
---

# UniDesk Nginx

通过 `platform-infra nginx` 运维 owning YAML 选择的 Nginx host-Docker target。
所有正式变更走受控 CLI，不直接修改 PK01 Compose、容器、systemd 或日志文件。

## 权威入口

- 配置真相：`config/platform-infra/nginx.yaml`。
- 受控实现：`scripts/src/platform-infra-nginx.ts`。
- 通用镜像 Demo：`/root/demo/nginx-lb-logger`。
- 开发边界：`docs/reference/platform-infra.md`。
- PK01 边界：`docs/reference/pk01.md`。

涉及 YAML 职责拆分时同时加载 `$unidesk-ymalops`。
涉及跨 host 现场修改或验证时同时加载 `$unidesk-daddev` 与 `$unidesk-trans`。

## 高频入口

```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
bun scripts/cli.ts platform-infra nginx status --target PK01
```

`apply --confirm` 默认返回异步 job。
只用返回的 `job status` 命令短轮询，禁止改成长 SSH 连接等待完整传输和验证。

## 操作顺序

1. 读取 owning YAML，确认 target、routes、资源、镜像产物和 Secret `sourceRef`。
2. 运行 `plan`，要求镜像、Compose 插件和 Secret 摘要均有效。
3. 配置变更先运行 `apply --dry-run`，确认 mutation 为 false。
4. 用户要求部署时运行 `apply --confirm`，跟踪返回的异步 job 到终态。
5. 运行正式 `status`，要求镜像 ID、健康接口、日志状态和测试后端清理均通过。

完整操作与配置变更见 [references/operations.md](references/operations.md)。
失败分层和已确认陷阱见 [references/troubleshooting.md](references/troubleshooting.md)。

## 不可越过的边界

- PK01 Nginx 默认只允许只读诊断：
  - 只有用户在当前请求中明确要求修改 PK01，才允许变更版本、owning YAML、Compose、容器、systemd、路由、端口、Secret 绑定或运行状态；
  - 泛化的修复、恢复、部署和排障请求不构成 PK01 变更授权。
- 通用镜像只在 NC01 构建；Master server 和 PK01 不执行镜像构建。
- PK01 正式部署只走 `platform-infra nginx apply`，不使用 Demo Compose 代替。
- target、监听端口、上游、资源、日志上限和 API key 来源只写 owning YAML。
- Nginx 配置使用 `NGINX_*`，日志收集和管理配置使用 `LOGGER_*`。
- API key 只披露 sourceRef、key 名、presence 和 fingerprint，禁止打印明文。
- 除健康接口外，logger API 必须传入 `X-API-Key`。
- JSONL 只能由 Nginx `access_log` 写入；验证器不得生成或补写日志。
- PK01 验证只发送四个串行请求，不执行压力测试。
- 验证后端必须是临时 host Python/systemd 服务，不能放进容器。
- 验证退出后必须删除后端脚本和 unit，只保留 Nginx 容器。
- 本机临时 HTTP 制品源由 CLI 创建和撤销，不得作为常驻下载服务。

## 关闭标准

- `backendSequence` 与 `loggedSequence` 都是
  `backend-1,backend-2,backend-1,backend-2`。
- 未认证 logger API 返回 `401`。
- info、tail、download 和 clear 均成功。
- `status.summary.ok=true`、健康状态为 `200`、镜像 ID 匹配。
- `activeTestBackends=0`，测试脚本和 systemd unit 不存在。
- 本机临时 HTTP 目录和进程已经撤销。
