Codex
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
---
|
||
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 目录和进程已经撤销。
|