diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md index ab6dca8c..7481cb92 100644 --- a/docs/reference/deployment.md +++ b/docs/reference/deployment.md @@ -62,6 +62,10 @@ swap 管理不能被强塞进所有热路径。`server start/status` 可以暴 前端、本机 provider-gateway、dev-frontend-proxy 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要非版本化本地重建时，统一使用 `bun scripts/cli.ts server rebuild `，其中 `` 只能是 `backend-core`、`frontend`、`dev-frontend-proxy`、`provider-gateway`、`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 或 `oa-event-flow`。对 `database`、`filebrowser`、`filebrowser-d601`、`code-queue`、`k3sctl-adapter` 或未知对象，CLI 必须返回结构化 `unsupported-server-rebuild`，不得创建 job、不得执行 Compose mutation，也不得把对象强行转成源码构建服务。需要按 commit 上线或恢复到 desired-state 时必须改用 `bun scripts/cli.ts deploy apply --service `、backend-core artifact CD、`deploy apply --env dev|prod --service frontend|baidu-netdisk|decision-center|mdtodo|claudeqq` artifact consumer，或 dev-only `deploy apply --env dev --service code-queue` artifact consumer；直管微服务也不能把脏工作树或手工重建作为部署真相。`server rebuild frontend`、`server rebuild baidu-netdisk`、`server rebuild project-manager`、`server rebuild oa-event-flow`、`server rebuild todo-note` 和 `server rebuild code-queue-mgr` 都只作为维护/非标准路径保留，不得作为标准发布完成证据。Rust backend-core 常规迭代和 dev artifact CD 不得在 master server 用 `server rebuild backend-core` 替代 D601 CI；唯一例外是已提交的 backend-core 修复需要上线到主 server Compose runtime 时，可以用 `server rebuild backend-core` 受控编译并替换该服务，要求限流并发、异步 job/status 轮询、容器 health 验证和 issue 证据回写。D601 Code Queue 执行面、File Browser、FindJob、Pipeline、MET Nonlinear 和 ClaudeQQ 部署在计算节点，不属于主 server Compose 可重建服务；其中 D601 Code Queue 执行面不得再通过 `codex deploy` 或维护通道直连 D601 部署，且本阶段 prod artifact deploy/rollout/manifest mutation 仍 unsupported。特例冻结清单和下一阶段删除判断见 `docs/reference/cicd-standardization.md`。 +backend-core 的 Dockerfile 必须把 Rust 依赖构建和业务源码构建拆开：先只复制 `Cargo.toml` / `Cargo.lock`，用临时 `src/main.rs` 填充 release 依赖层；再复制真实 `src/` 并编译最终 `backend-core` 二进制。这样同一 builder 上只改业务源码时可以复用依赖层，避免每次重新编译全部 crate。该缓存策略只改善后续源码迭代；全新 builder 的第一次冷编译仍然需要下载和编译依赖，若要把第一次也做快，长期方案应是预构建依赖 builder image、BuildKit registry cache 或由 CI 发布 commit-pinned runtime image 后让部署侧只 pull 成品镜像。 + +临时 dummy `main.rs` 会生成同名 `target/release/backend-core`，这是 backend-core Dockerfile 的固定坑。源码层在编译真实代码前必须删除旧 `target/release/backend-core`、对应 `.d` 文件和 `unidesk-backend-core-*` fingerprint；只执行 `cargo clean -p` 不一定会清到 dummy binary。若忘记清理，最终镜像可能复制 dummy binary，表现为容器启动后立刻 exit 0、日志为空、health 一直失败。重建 backend-core 后必须以容器 health 和真实 `/health` 或等价 core 入口确认，不得只看 Docker build `Built`。 + frontend 改动必须明确上线到公网：修改 `src/components/frontend/src/`、`src/components/frontend/public/style.css`、frontend 使用的共享 TSX/TS 模块或 WebUI 导航后，标准发布顺序是先把 pushed commit 交给 `bun scripts/cli.ts ci publish-user-service --service frontend --commit `，再用 `bun scripts/cli.ts deploy apply --env dev --service frontend` 和 `bun scripts/cli.ts deploy apply --env prod --service frontend` 消费同一个 commit-pinned artifact。公网 WebUI 的 `/app.js` 是 `unidesk-frontend` 镜像内运行时 bundle；只改工作区文件、只跑 `bun run check`、只跑 `Bun.build`、只刷新浏览器或只 `server rebuild frontend` 都不能作为标准版本发布证据。 frontend 的 artifact 上线顺序为：先运行必要的轻量本地校验或 D601 CI；然后发布 `127.0.0.1:5000/unidesk/frontend:`；再用 dev/prod `deploy apply` 消费该 artifact；最后验证 dev `frontend-dev` 和 prod `frontend` 的 `/health.deploy.commit`、image label、`UNIDESK_DEPLOY_*` metadata 都等于 requested commit。若必须手工复现维护路径，等价 Docker Compose 命令只能是固定 project/env 的 `docker compose --env-file .state/docker-compose.env -f docker-compose.yml -p unidesk build frontend`，随后 `docker compose --env-file .state/docker-compose.env -f docker-compose.yml -p unidesk up -d --no-deps --force-recreate frontend`；手工路径仍必须做同样的健康检查，不得改用全栈 `up --build`、`down`、删除容器或重启 database/backend-core 来“顺手上线”前端。 diff --git a/docs/reference/provider-gateway.md b/docs/reference/provider-gateway.md index c278fa4d..4cb4ad30 100644 --- a/docs/reference/provider-gateway.md +++ b/docs/reference/provider-gateway.md @@ -42,6 +42,14 @@ Provider WebSocket 是注册、heartbeat、dispatch、`provider.upgrade` 和短 可见性必须跟随通道池。provider-gateway labels 应上报 `providerGatewaySshDataTransport=tcp-pool`、目标 host/port、desired pool size、ready/claimed/connecting/total channel 数和最近错误；`debug health`、frontend raw JSON 和 issue 证据应优先用这些字段判断是 provider 未升级、data port 不通、池耗尽还是目标 host SSH 本身失败。只看到 provider 在线或 `host.ssh` 可用，不等于 TCP data pool 已经可用。 +### TCP Pool Development Notes + +TCP pool 的长期方向是把 `trans`/`tran` 变成真正并发的短连接工具，而不是给单条 Provider WebSocket 继续叠队列。backend-core 只用 provider WebSocket 下发 open/dispatch/exit 等控制帧，stdin/stdout/stderr 数据帧必须走已预热的 TCP channel；每个 SSH 会话、脚本、文件传输或 Windows 透传命令独占一条 channel，结束后释放回池。池耗尽、channel 丢失、data port 不可达和 provider 版本过旧都必须是结构化快速失败；禁止把请求排进应用层队列后长时间不返回。 + +当前默认池大小是 10 条，设计上优先覆盖高频短 SSH、并发小文件和单个大文件不阻塞其他请求的场景。已验证的目标状态是：D601 这类 WSL provider 上 10 路并发 `trans ... argv bash -lc 'sleep 2'` 不再出现 `provider ssh tcp data pool has no idle channel`、stderr 为空、每一路 stdout 都包含命令开始和结束输出，结束后 labels 回到 `ready=desired`、`claimed=0`。当前仍存在端到端固定开销，10 路并发短命令的墙钟可能明显高于远端命令自身耗时；这属于后续连接建立、broker 调度、WSL SSH spawn 或 provider 启动路径的性能优化范围，不能用队列、门禁或隐藏重试掩盖。 + +开发中最容易踩的坑是把“依赖层在线”误判成“数据面可用”。`host.ssh` 只证明 provider 能执行维护 SSH；`host.ssh.tcp-pool`、`providerGatewaySshDataPoolReady`、`providerGatewaySshDataPoolClaimed` 和 `providerGatewaySshDataPoolLastError` 才能证明 TCP 数据池状态。另一个坑是输出尾部丢失：backend-core broker 在收到 `ssh.data` 后必须把 stdout/stderr 写入并 flush，再处理 `ssh.exit`，否则短命令可能 rc=0 但最后一段 stdout 没到调用端。第三个坑是 session 释放：`ssh.exit`、错误和超时路径都必须释放 claimed channel，避免下一批并发请求看到假性的池耗尽。 + ## WSL Compute Node Deployment WSL 计算节点和普通外部计算节点使用同一套 provider ingress 协议：节点不暴露入站端口，只需要从 WSL 主动连出到 `ws://74.48.78.17:18082/ws/provider`。已验证的 WSL 节点命名口径是短设备编号，例如 `PROVIDER_ID=D601` 与 `PROVIDER_NAME=D601` 保持一致；新增 WSL 节点必须替换为唯一 ID，避免把旧节点状态覆盖到同一条 `unidesk_nodes.provider_id` 记录。