docs: add UniDesk Nginx operations skill
This commit is contained in:
Codex
@@ -0,0 +1,70 @@
|
||||
---
|
||||
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 现场修改或验证时同时加载 `$dad-dev` 与 `$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)。
|
||||
|
||||
## 不可越过的边界
|
||||
|
||||
- 通用镜像只在 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 目录和进程已经撤销。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "UniDesk Nginx"
|
||||
short_description: "受控部署、验证和运维 UniDesk Nginx 负载均衡与日志服务"
|
||||
default_prompt: "使用 $unidesk-nginx 按 owning YAML 安全部署并验证 UniDesk Nginx 服务。"
|
||||
@@ -0,0 +1,53 @@
|
||||
# 受控操作
|
||||
|
||||
## 配置路由
|
||||
|
||||
- 只在 `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。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 排障
|
||||
|
||||
## 先看受控状态
|
||||
|
||||
```bash
|
||||
bun scripts/cli.ts platform-infra nginx plan --target PK01
|
||||
bun scripts/cli.ts platform-infra nginx status --target PK01
|
||||
```
|
||||
|
||||
只在受控输出不足时使用 `trans PK01` 做有界只读诊断。
|
||||
诊断不能替代最后一次正式 `status`。
|
||||
|
||||
## Compose 不可用
|
||||
|
||||
- 症状：`docker compose` 不存在或插件 metadata 无效。
|
||||
- 先直接运行 YAML 固定的 Compose 二进制 `version`，再检查 `docker info` 插件警告。
|
||||
- Master 的发行版插件可能依赖较新的 GLIBC，不能直接复制到 Ubuntu 20.04 的 PK01。
|
||||
- 使用 owning YAML 固定的官方静态二进制及 SHA-256，不在 PK01 现场下载漂移版本。
|
||||
|
||||
## 制品传输超时
|
||||
|
||||
- 症状：`trans upload` 大文件长期无进度，或单次 SSH 到 60 秒后退出 `124`。
|
||||
- 正常路径应为本机临时 HTTP 源、PK01 远端 job 和短轮询。
|
||||
- 不要把大镜像改回 base64 分块上传，也不要用长 SSH 等待下载、Docker load 和验证。
|
||||
- apply 结束后检查 `/tmp/unidesk-nginx-artifacts` 不存在，临时 HTTP 端口已释放。
|
||||
|
||||
## Logger API 拒绝
|
||||
|
||||
- `401` 表示没有 `X-API-Key`，属于正常鉴权结果。
|
||||
- `403` 表示 key 不匹配。
|
||||
- 只核对 Secret sourceRef、key 名、presence 和 fingerprint。
|
||||
- 禁止读取远端环境文件并打印明文，也禁止把 key 放进 job 命令参数。
|
||||
|
||||
## 业务端口无响应
|
||||
|
||||
- 先看 YAML routes 是否仍指向已撤除的测试端口。
|
||||
- 验收成功后删除两个测试后端是设计要求，不代表 Nginx 容器异常。
|
||||
- 部署真实应用时只修改 YAML routes，不改镜像源码。
|
||||
- 多端口问题按每个 `listenPort` 独立核对上游，不推断所有端口共享同一组后端。
|
||||
|
||||
## 测试后端残留
|
||||
|
||||
- 正式 status 的 `activeTestBackends` 必须为 `0`。
|
||||
- 检查两个 unit、Python 脚本和 enable symlink 是否仍存在。
|
||||
- 若 apply 失败在验证阶段，优先修复 CLI 的退出清理路径，再重跑受控 apply。
|
||||
- 不把临时后端长期保留为运行依赖。
|
||||
@@ -102,6 +102,7 @@
|
||||
- 优先走 `$unidesk-trans` 的 `trans <route> apply-patch`；
|
||||
- route/cwd 见 `docs/reference/cli.md`。
|
||||
- P0: 专项技能路由：
|
||||
- Nginx 负载均衡、logger API 和 PK01 host-Docker 运维走 `$unidesk-nginx`；
|
||||
- Web/Workbench/Playwright/web-probe 走 `$unidesk-webdev`；
|
||||
- OTel/Tempo/trace 走 `$unidesk-otel`；
|
||||
- Web 哨兵和周期巡检走 `$unidesk-monitor`。
|
||||
|
||||
@@ -195,14 +195,10 @@ Interpretation guide:
|
||||
## Nginx Host-Docker 受控部署
|
||||
|
||||
- PK01 的 Nginx 负载均衡器由 `config/platform-infra/nginx.yaml` 管理。
|
||||
- 日常部署、状态、logger API 和排障统一见 `$unidesk-nginx`。
|
||||
- 部署形态与 PK01 Sub2API 一致，使用 UniDesk YAML-first 的 host-Docker Compose 入口。
|
||||
- 正式命令是 `bun scripts/cli.ts platform-infra nginx apply --target PK01 --confirm`。
|
||||
- apply 默认提交异步 job；长传输、镜像加载和验证不能占用单次 SSH 长连接。
|
||||
- 容器使用 host network，并限制为 `64m` 内存、`0.25` CPU 和 64 个 PID。
|
||||
- 业务监听端口、上游列表、管理端口、日志上限和 logger API key 来源均来自 owning YAML。
|
||||
- PK01 不构建镜像；镜像在 NC01 构建后以 SHA-256 和镜像 ID 校验的产物下发。
|
||||
- 验证期间临时创建两个 loopback host Python/systemd 后端。
|
||||
- 验证固定发送四个串行请求，并核对响应后端与 Nginx JSONL 记录顺序。
|
||||
- 验证 logger API 的未认证拒绝、查询、tail、下载和清理能力。
|
||||
- 验证结束后删除两个后端及其 unit，保留 Nginx 容器和已清空的日志文件。
|
||||
- `platform-infra nginx status --target PK01` 必须报告测试后端活动数为零。
|
||||
|
||||
@@ -327,17 +327,12 @@ This policy must be included in the `sub2api plan` / `apply` manifest rendering
|
||||
## Nginx 负载均衡与 Logger 边界
|
||||
|
||||
- Nginx host-Docker 服务的配置真相是 `config/platform-infra/nginx.yaml`。
|
||||
- 正式入口是 `platform-infra nginx plan|apply|status`，不得用 Demo 脚本直接修改 PK01。
|
||||
- 日常命令、部署、验收和排障统一见 `$unidesk-nginx`。
|
||||
- 正式入口是 `platform-infra nginx plan|apply|status`。
|
||||
- 不得用 Demo 脚本直接修改 PK01。
|
||||
- 镜像由 owning YAML 固定产物路径、SHA-256 和镜像 ID，并在 NC01 构建。
|
||||
- `targets.<id>.runtime.routes` 是业务监听端口与上游的唯一真相。
|
||||
- 一个 target 可以声明一个或多个监听端口，每个端口可以声明一个或多个 HTTP 上游。
|
||||
- CLI 将路由数组渲染为容器的 `NGINX_ROUTES`，不在源码中保存应用专用端口。
|
||||
- Nginx 配置使用 `NGINX_*`，日志收集和管理配置使用 `LOGGER_*`。
|
||||
- logger API key 只允许由 YAML `sourceRef`、`sourceKey` 和 `targetKey` 下发。
|
||||
- API key 输出只披露 presence 与 fingerprint，禁止输出或嵌入受控 job 命令。
|
||||
- 除健康检查外，logger 查询、tail、下载和清理接口均要求 `X-API-Key`。
|
||||
- JSONL 文件由 Nginx `access_log` 写入，验证器不得生成或补写日志。
|
||||
- `LOGGER_MAX_BYTES` 与检查周期必须由 YAML 明确设置，避免日志无限增长。
|
||||
- PK01 验证只发送四个串行请求，不执行压力测试。
|
||||
- 两个验证后端必须是 PK01 host Python/systemd 服务，不能作为容器部署。
|
||||
- 验证退出时必须停止并删除后端脚本和 unit；正式 Nginx 容器继续运行。
|
||||
|
||||
Reference in New Issue
Block a user