feat: add code queue deploy cli

2026-05-16 04:10:02 +00:00
parent 502f5971b1
commit 88516cec6a
10 changed files with 888 additions and 15 deletions
@@ -0,0 +1,50 @@
+# Code Queue Deploy
+
+`bun scripts/cli.ts codex deploy <commitId>` 是 D601 Code Queue 的正式部署入口。命令只在主 server 工作区执行；它会立即返回异步 job id，后台 job 通过 backend-core 的 `host.ssh` dispatch 在 D601 完成实际部署。
+
+## Command
+
+```bash
+bun scripts/cli.ts codex deploy <commitId>
+bun scripts/cli.ts job status <jobId> --tail-bytes 30000
+```
+
+- `commitId` 必须是已经 push 到 remote 的 7-40 位 hex commit SHA。
+- `--provider-id D601` 是默认值；当前部署路径只支持 D601 active instance。
+- `--timeout-ms N` 控制后台部署总超时，默认 `900000`。
+- `--skip-build` 只用于已确认目标镜像已在 D601 Docker 和 k3s containerd 中存在的诊断场景；正式部署默认必须构建镜像。
+
+## Pipeline
+
+部署 job 的步骤固定为：
+
+1. 在 D601 `/home/ubuntu/unidesk` 中 `git fetch` remote，并用 `git archive <commitId>` 导出 tracked files 到 `/tmp/unidesk-codex-deploy-src-*`。
+2. 用 `rsync --delete` 同步导出的 repo 到 `/home/ubuntu/cq-deploy`，保留 `.state/`、`logs/`、`.git/`、`node_modules/` 和 `dist/`。
+3. 在 `/home/ubuntu/cq-deploy` 构建 `unidesk-code-queue:d601`。
+4. `docker save` 镜像并导入 k3s containerd：`docker exec -i unidesk-v8s-server ctr -n k8s.io images import -`。
+5. `kubectl apply -f src/components/microservices/v3sctl-adapter/v3s/code-queue.k8s.yaml`，其中包含 Code Queue 和 `d601-tcp-egress-gateway`。
+6. `kubectl -n unidesk rollout restart deployment/d601-tcp-egress-gateway deployment/code-queue` 并等待 rollout 完成。
+7. 通过 `bun scripts/cli.ts microservice health code-queue` 等价的 backend-core 路径验证 live health。
+
+## Observability
+
+`codex deploy` 本身不阻塞等待部署结束。返回 JSON 中的 `statusCommand` 和 `tailCommand` 是唯一状态入口。后台 job 的 stderr 是 JSONL progress，每个长步骤会记录远端 `/tmp/unidesk-codex-deploy-*.log` 和 sentinel 文件；失败时 `job status` 会显示最后日志尾部。
+
+`job status` 到 `succeeded` 后，还要用以下命令做 live 验证：
+
+```bash
+bun scripts/cli.ts microservice health code-queue
+bun scripts/cli.ts microservice proxy code-queue '/api/tasks/overview?limit=5&transcriptLimit=1&compact=1&afterSeq=0&preferId='
+```
+
+## Boundaries
+
+Code Queue 由 D601 v3s/k8s 控制面代管，不再通过 `server rebuild` 或手工 `docker compose up` 作为正式部署路径。`codex deploy` 可以在 Code Queue 自身正在执行任务时运行；服务重启后由 restart-recovery 恢复任务状态，不能等待当前 Code Queue task 退出后再部署。
+
+## TCP Egress Gateway
+
+D601 k3s Pod 不能依赖主 server 公开 `15432`/`4255` 作为直连 TCP 入口；PostgreSQL 也不会自动使用 HTTP proxy 环境变量。`code-queue.k8s.yaml` 因此提供一个通用 `d601-tcp-egress-gateway`：
+
+- Pod 内业务只访问集群内 Service：`d601-tcp-egress-gateway.unidesk.svc.cluster.local:15432` 和 `:4255`。
+- gateway 通过 D601 provider-gateway egress proxy 的 HTTP CONNECT 转发到底层 TCP 目标。
+- 新增 TCP 依赖时只扩展 `TCP_EGRESS_ROUTES`，不要在业务容器里散落公网直连地址或 ad hoc 隧道脚本。