feat: add provider ssh tcp data pool
This commit is contained in:
Codex
@@ -30,7 +30,7 @@ CI/CD、GitOps、rollout、artifact 发布、PR 合并后的 DEV/PROD 滚动、P
|
||||
- `server logs` 返回 `logs/` 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。实现必须只读取文件末尾字节，不得为了 tail 先把巨大日志完整读入 CLI 内存。
|
||||
- `server cleanup plan [--min-age-hours N] [--limit N]` 只生成主 server Docker 镜像清理 dry-run 计划，不执行删除；默认 `--min-age-hours 24`，避免把刚发布或刚验证的镜像列为 stale。输出必须包含 `dryRun=true`、`mutation=false`、`policy.deletionExecuted=false`、active containers/images、受保护镜像、candidate stale images、估算释放空间、风险等级、`commandsToReview` 和人工审批清单。计划必须保守白名单：保留 running containers 使用的 image ID，保留 stopped containers 引用的 image ID 直到人工先复核容器，保留 `deploy.json`/`CI.json` 当前 commit-pinned artifact、Compose stable image、上游 digest pin 和 provider-gateway runner image；`protectedStorage` 必须显式列出 PostgreSQL named volume、Baidu Netdisk `.state`、D601 registry storage 和 Docker volumes/host data policy。该入口禁止生成或执行 `docker system prune`、`docker image prune`、`docker builder prune`、`docker volume rm`、`docker compose down -v`、数据库清理或 host data `rm` 命令；未来若增加真实删除，必须另设显式审批参数并先复核 dry-run 输出。
|
||||
- `gc plan|run --confirm|db-trace|policy|remote` 是主 server 和受控 provider 的磁盘高水位一次性缓解与长期防膨胀入口。`plan` 只读输出候选、风险、估算收益和保护对象；`run` 必须显式 `--confirm`；`gc remote <providerId> ...` 通过 UniDesk SSH 透传执行远端 GC，`--target-use-percent N` 会在 `summary.target` 中报告目标水位所需释放量、候选估算、预计水位、缺口和 safe-stop 决策。G14/HWLAB registry retention、受限 core dump、保护对象、safe-stop 线和长期收益表的权威规则见 `docs/reference/gc.md`。
|
||||
- `server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>` 创建异步 job，先构建目标服务镜像，随后在 `.state/locks/server-compose.lock` 串行保护下用 `--no-deps --force-recreate` 替换目标 service 并等待容器 `healthy/running`；该命令用于替代手工删除容器的兜底流程，其中 `dev-frontend-proxy` 只更新主 server dev 入口薄代理，`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 和 `oa-event-flow` 只重建主 server 承载的对应后端，不会重建或删除 database 命名卷。D601 Code Queue 执行面不由 `server rebuild` 管理，Rust backend-core 迭代不得用 `server rebuild backend-core` 在 master server 编译，规则见 `docs/reference/dev-environment.md`。
|
||||
- `server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>` 创建异步 job，先构建目标服务镜像，随后在 `.state/locks/server-compose.lock` 串行保护下用 `--no-deps --force-recreate` 替换目标 service 并等待容器 `healthy/running`；该命令用于替代手工删除容器的兜底流程，其中 `dev-frontend-proxy` 只更新主 server dev 入口薄代理，`todo-note`、`code-queue-mgr`、`project-manager`、`baidu-netdisk` 和 `oa-event-flow` 只重建主 server 承载的对应后端，不会重建或删除 database 命名卷。D601 Code Queue 执行面不由 `server rebuild` 管理；Rust backend-core 常规迭代不得用该命令在 master server 编译，只有明确的 backend-core 主 server 上线例外可以按限流、异步轮询和 health 证据执行，规则见 `docs/reference/dev-environment.md`。
|
||||
- `provider attach <providerId> [--master-server URL] [--up] [--force]` 在新计算节点生成两项配置的 provider-gateway 挂载包：`.state/provider-<ID>.env` 默认只包含 `UNIDESK_MASTER_SERVER` 与 `PROVIDER_ID`，`provider-<ID>.yml` 固定 Docker socket、`pid: "host"`、`restart: always`、只读 `/workspace` 和 SSH 维护私钥挂载；`--up` 会立即执行生成的 `docker compose up -d --build`。`provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]` 是只读多信号健康裁决入口，会把单路径 `provider is not online`、SSH 超时、registry 失败和 service proxy 失败归类成 `runner-local-observation-gap`、`service-degraded`、`provider-degraded` 或 `global-blocker`。默认输出只返回裁决、scope、失败/降级/未知信号和有界 evidence 摘要，完整 evidence 必须显式加 `--full` 或 `--raw`；推荐交叉验证命令仍包含 `debug health`、`debug dispatch <providerId> host.ssh --wait-ms 15000`、`trans <providerId> argv true`、`artifact-registry health --provider-id <providerId>`、`microservice health k3sctl-adapter`、`microservice health code-queue` 和 `codex tasks --view supervisor --limit 20`。
|
||||
- `trans <route> [operation args...]` / `tran <route> [operation args...]` 通过 backend-core 内网 WebSocket broker 和 provider-gateway 的 Host SSH / WSL SSH 维护桥连接目标节点；`route` 基础形态是 provider id，例如 `D601` 或 `G14`，也可以扩展为纯定位路径 `provider:plane[:namespace:resource[:container]]`，例如 `D601:win`、`D601:win/c/test`、`G14:k3s`、`D601:k3s` 或 `G14:k3s:<namespace>:<workload>`。WSL provider 的 Windows plane 固定使用 `win`，不得使用 `win32`；Windows operation 必须显式区分：`ps` 执行 Windows PowerShell heredoc 或一行 PowerShell 命令，`cmd` 执行 cmd.exe/batch，`skills` 发现 Windows skill 目录。需要 Windows cwd 时用 `trans D601:win/c/test ps` 或 `trans D601:win/c/test cmd cd`，CLI 自动设置 UTF-8/Python 编码默认值；`cmd` 额外设置 `chcp 65001`。非交互远端命令优先使用 `trans <providerId> argv ...`；需要 POSIX shell 脚本、管道、变量或循环时优先使用 quoted heredoc 单步传输，例如 `trans G14 script <<'SCRIPT'`、`trans G14:k3s script <<'SCRIPT'` 或 `trans G14:k3s:<namespace>:<workload> script <<'SCRIPT'`，把脚本走 stdin。`script` 只表示 host/k3s POSIX shell，不表示 Windows PowerShell；Windows PowerShell 必须写 `trans <provider>:win ps <<'PS'`。`script -- '<单个字符串>'` 是无需 stdin 的远端 POSIX shell one-liner，例如 `trans G14:/root/hwlab script -- 'cd /root/hwlab && git status --short --branch'`；`script -- <多个 argv>` 才是 direct argv，适合 `trans D601:/path script -- sed -n '1,20p' file` 这类带短横线的单进程命令。顶层 remote option parser 必须保留命令已经开始后的 `--`，不得把它吞成全局选项结束符。需要远端改文本文件时默认优先使用 `<route> apply-patch < patch.diff`；需要可靠传输非文本或整文件时使用 `<route> upload <local-file> <remote-file>` 和 `<route> download <remote-file> <local-file>`，CLI 会按字节数与 SHA-256 自动校验并在 provider-gateway stdin/argv 限制下切换客户端分块策略；需要旧 helper 时显式使用 `<provider>:k3s:<namespace>:<workload> apply-patch-v1` 或 `<providerId> apply-patch-v1`。ssh-like 命令遇到 timeout/kex/255 类失败时，CLI 会在 stderr 追加一行 `UNIDESK_SSH_HINT` JSON，提示 stdin script/argv 重试和 provider triage 交叉验证。
|
||||
- `trans <route> apply-patch < patch.diff` 是默认推荐的远端 patch 入口：本地 TypeScript line-based engine 解析和计算新文件内容，远端 route 只负责读写文件；支持 host workspace、k3s pod workspace、Windows workspace route（例如 `D601:win/c/test`）和 frontend transport，并优先处理长中文/Unicode、低上下文插入、重复块 `@@` 定位等旧 helper 容易失败的场景。`apply-patch` 输出按 Codex 标准文本口径，不套 UniDesk JSON 限制：成功 stdout 为 `Success. Updated the following files:`，失败 stdout 为空、stderr 写失败原因；多文件补丁中途失败时，stderr 只列出第一个失败前已成功执行的 hunk 和失败 hunk，随后按 Codex 语义停止，不继续尝试后续 hunk。v2 兼容常见 MiniMax/MXCX 非标准补丁输入，例如重复 nested `*** Begin Patch` / `*** End Patch` envelope、unified-diff hunk header、Add/Delete 误加 `@@`、Update context 漏掉前导空格，并在 stderr 给出 canonical 写法 hint；parser 或上下文失败时仍坚持唯一 v2 引擎，只提示修正 patch 文本或 hunk context，不自动重试或切换到 `apply-patch-v1`；大块/函数替换因上下文过期失败时，正确动作是重新读取当前目标块、缩小或拆分 Update File hunk 后继续用 `apply-patch`，不得改走 `download`/`upload`、远端 Python/Perl/sed heredoc 或整文件重写。Windows route 复用同一套 v2 核心算法，只把底层读写替换成 PowerShell 文件系统接口；`trans <providerId> apply-patch-v1 [tool args...] < patch.diff` 保留为显式 legacy 入口，直接调用远端注入的 `apply_patch` sh/perl helper；默认 `apply-patch` 不把 v1 当 fallback。
|
||||
@@ -215,7 +215,7 @@ GitHub issue/PR 写操作必须优先使用 `bun scripts/cli.ts gh issue|pr ...
|
||||
|
||||
## SSH Command
|
||||
|
||||
`trans <providerId> [ssh-like args...]` 是面向人的终端透传入口，不包装 JSON 输出，底层等价于 `bun scripts/cli.ts ssh <providerId> ...`。CLI 会在宿主机启动 `docker exec -i unidesk-backend-core backend-core --ssh-broker ...`，broker 只连接 backend-core 的 Docker 内网 `/ws/ssh`，core 再把 stdin/stdout/stderr 流量通过目标 provider 的既有 WebSocket 转发到 provider-gateway，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 `ssh -tt`，带远端命令的会话使用 `ssh -T`；`apply-patch`、脚本 stdin、`py` 和旧 `apply-patch-v1` fallback 这类命令模式不得被伪终端回显或注入控制字符。该入口不新增 core 公网端口，不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的公网边界。
|
||||
`trans <providerId> [ssh-like args...]` 是面向人的终端透传入口，不包装 JSON 输出，底层等价于 `bun scripts/cli.ts ssh <providerId> ...`。CLI 会在宿主机启动 `docker exec -i unidesk-backend-core backend-core --ssh-broker ...`，broker 只连接 backend-core 的 Docker 内网 `/ws/ssh`；core 使用 provider WebSocket 下发 open/dispatch 控制消息，但 stdin/stdout/stderr 数据面必须走 provider 主动连接 main server 的 `host.ssh.tcp-pool` TCP warm pool，provider-gateway 最终执行维护用 SSH 连接宿主或 WSL sshd。TTY 策略固定为交互登录 shell 使用 `ssh -tt`，带远端命令的会话使用 `ssh -T`；`apply-patch`、脚本 stdin、`py` 和旧 `apply-patch-v1` fallback 这类命令模式不得被伪终端回显或注入控制字符。该入口不暴露 database，也不改变 frontend/dev frontend/provider ingress 之外的业务边界；provider data TCP port 是 provider 主动连入的数据面端口，不是计算节点入站要求。
|
||||
|
||||
`trans --help` 和 `trans <providerId> --help` 是本地 JSON 帮助命令，必须快速返回；不能把 `--help` 解析成 Provider ID，不能打开交互 shell，也不能等待 provider 会话。
|
||||
|
||||
@@ -264,11 +264,11 @@ HWLAB Cloud Web Workbench 或 Code Agent 装配类 issue 的 CLI 验证必须贴
|
||||
|
||||
`trans D518` 应表现为登录 D518 WSL 的 shell；`trans D518 hostname` 应像 `ssh D518 hostname` 一样只输出远端命令结果并返回远端 exit code。Provider ID 前的目标选择由 UniDesk 节点清单决定，`-p`、`-i`、`-l`、`-o` 等传统 ssh 传输参数由 provider-gateway 部署配置统一管理，CLI 会兼容性消费这些参数但不会覆盖节点侧维护桥配置。指挥官、CI 预检和其他非交互流程不要依赖 ssh-like 自由拼接；单进程标准写法是 `trans D601 argv true`，多行 shell 逻辑标准写法是 quoted heredoc 单步调用 `trans D601 script <<'SCRIPT'`。
|
||||
|
||||
UniDesk CLI/trans/tran 客户端改进本身是 master server 高频控制入口维护，可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；不要为这类客户端小改强制迁移到 D601 worktree。该例外不改变 master server 禁重型验证规则：仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译、Code Queue runner 实测仍必须在 D601、CI runner 或目标运行面执行。若 `trans`/`tran`/SSH 文件传输遇到 provider-gateway 单次 stdin、argv 或 stdout 限制，先在 CLI 客户端做分块、SHA-256 校验、失败可观测输出和最小真实闭环；只有 client 侧不能解决且有证据时，才改 provider-gateway。`upload`/`download` 成功 JSON 中的 `verified=true`、`verification.automatic=true`、`verification.verified=true` 和 `verification.match.{bytes,sha256}=true` 就是端到端完整性证明，调用方不需要再额外手写 `sha256sum` 比对。
|
||||
UniDesk CLI/trans/tran 客户端改进本身是 master server 高频控制入口维护，可以直接在 `/root/unidesk` 轻量开发、提交并推送 `origin/master`；不要为这类客户端小改强制迁移到 D601 worktree。该例外不改变 master server 禁重型验证规则：仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译、Code Queue runner 实测仍必须在 D601、CI runner 或目标运行面执行，backend-core 主 server 上线受控编译例外按 `docs/reference/dev-environment.md` 单独处理。若 `trans`/`tran`/SSH 文件传输遇到 provider-gateway 单次 stdin、argv 或 stdout 限制，先在 CLI 客户端做分块、SHA-256 校验、失败可观测输出和最小真实闭环；只有 client 侧不能解决且有证据时，才改 provider-gateway。文件传输默认按 1MiB raw chunk 读写，避免 100MiB 大文件被 45KiB 小块和 base64 全量暂存拖慢；`upload`/`download` 成功 JSON 中的 `verified=true`、`verification.automatic=true`、`verification.verified=true` 和 `verification.match.{bytes,sha256}=true` 就是端到端完整性证明，调用方不需要再额外手写 `sha256sum` 比对。
|
||||
|
||||
`scripts/src/ssh.ts` 只承担 route/operation parser、共享远端命令构造、broker 调用和顶层 dispatch。新增或扩展高频 operation 不得继续把完整实现堆进 `ssh.ts`；应按能力拆到专门模块，例如整文件传输放在 `scripts/src/ssh-file-transfer.ts`，再由 `ssh.ts` 和 frontend remote transport 传入共享 command builder/bridge executor。后续新增 operation 也按 `scripts/src/ssh-<capability>.ts` 或等价专门模块组织，帮助文本、合同测试和 reference 与代码同一变更集更新。
|
||||
|
||||
core 只允许声明了 `host.ssh` capability 的 provider 使用 `ssh` 透传或 `host.ssh` dispatch；旧 provider 不支持该能力时必须快速失败并输出错误，不能把未知命令误判成 `echo` 成功。
|
||||
core 只允许声明了 `host.ssh` capability 的 provider 使用 `host.ssh` dispatch；`trans`/`tran`/`ssh` 流式透传还必须要求 provider 声明 `host.ssh.tcp-pool`。旧 provider 不支持该能力时必须快速失败并输出 `provider-gateway-upgrade-required`，提示升级 provider-gateway；不得回落到旧 WebSocket 数据路径。provider 已升级但没有可用 data channel 时，错误应区分 `provider-data-pool-exhausted`、`provider-data-channel-missing` 或 data port 连接失败，并通过 provider labels 的 `providerGatewaySshData*` 字段定位。
|
||||
|
||||
本地 broker 默认等待 provider SSH 会话打开 60000ms，以便在目标节点同时有较多 microservice.http 任务时仍能建立维护会话；需要诊断慢连接时可用 `UNIDESK_SSH_OPEN_TIMEOUT_MS=<ms>` 临时调大，但最小有效值固定为 15000ms，避免把真实离线误判为长时间阻塞。注意 open timeout 只控制“会话打开”阶段，不能绕过 60 秒最外层运行时硬超时。
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ TypeScript 运行时固定为 Bun for CLI, frontend, provider-gateway and TypeSc
|
||||
|
||||
## Network Ports
|
||||
|
||||
`config.json` 中保留 core、frontend、devFrontend、database 和 providerIngress 的端口字段。frontend、devFrontend 与 providerIngress 是面向浏览器/Provider 的公开入口；devFrontend 是 D601 `unidesk-dev` 的薄代理入口，权威规则见 `docs/reference/dev-environment.md`。core 不允许映射公网。database 的 `port` 字段用于 D601 Code Queue 的受限 PostgreSQL 端口映射和公网阻断测试，必须配合 `network.restrictedHostAccess` 的来源白名单限制到 D601 出口地址，不能作为任意公网数据库入口。
|
||||
`config.json` 中保留 core、frontend、devFrontend、database、providerIngress 和 providerData 的端口字段。frontend、devFrontend 与 providerIngress 是面向浏览器/Provider 的公开入口；providerData 是 `host.ssh.tcp-pool` 使用的数据面 TCP 端口，由 provider-gateway 主动连入 main server，默认主机端口为 `18084`、backend-core 容器端口为 `8082`。devFrontend 是 D601 `unidesk-dev` 的薄代理入口，权威规则见 `docs/reference/dev-environment.md`。core 不允许映射公网。database 的 `port` 字段用于 D601 Code Queue 的受限 PostgreSQL 端口映射和公网阻断测试，必须配合 `network.restrictedHostAccess` 的来源白名单限制到 D601 出口地址，不能作为任意公网数据库入口。
|
||||
|
||||
## Auth
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ Production runtime and CI/CD control-plane versioning follow `docs/reference/rel
|
||||
## Services
|
||||
|
||||
- `database` 使用 `postgres:16-alpine`，数据保存到 named volume `unidesk_pgdata_10gb`，当前容量预算为 15 GB，初始化 SQL 位于 `src/components/database/init/`。
|
||||
- `backend-core` 是无状态核心服务，提供 Docker 内网 REST API、provider ingress WebSocket、任务调度入口和数据库访问层。当前 backend-core 是 Rust 服务；Rust 迭代编译边界见 `docs/reference/dev-environment.md`。源码模块结构见 `docs/reference/repo-tree.md`。
|
||||
- `backend-core` 是无状态核心服务，提供 Docker 内网 REST API、provider ingress WebSocket、任务调度入口、provider data TCP pool 入口和数据库访问层。当前 backend-core 是 Rust 服务；Rust 默认迭代编译边界和主 server 上线受控例外见 `docs/reference/dev-environment.md`。源码模块结构见 `docs/reference/repo-tree.md`。
|
||||
- `frontend` 是 production 公开 Web 控制台，提供登录、从 TSX 转译出的 React 应用资产和到 backend-core 的同源代理。
|
||||
- `dev-frontend-proxy` 是主 server 上的 18083 dev UI 薄入口，代理到 D601 `unidesk-dev/frontend-dev`，详细边界见 `docs/reference/dev-environment.md`。
|
||||
- `provider-gateway` 是当前主 server 的本机计算节点代理，通过 WebSocket 主动连到 provider ingress，挂载 `/var/run/docker.sock` 作为自动任务执行主路径，使用 `pid: "host"` 读取节点级进程资源，并周期性上报系统资源指标、进程占用与 Docker daemon 状态；计算节点 provider-gateway 还必须把 egress proxy 仅发布到宿主 loopback `127.0.0.1:18789` 供本节点执行环境出网，维护用 Host SSH / WSL SSH 私钥目录只读挂载到 `/run/host-ssh`，不得作为自动任务调度主路径。
|
||||
@@ -20,7 +20,7 @@ Production runtime and CI/CD control-plane versioning follow `docs/reference/rel
|
||||
|
||||
## Public Exposure Boundary
|
||||
|
||||
Docker Compose 对最终用户只公开 production frontend host port、dev frontend proxy host port 和 provider ingress host port。backend-core REST API 仍不得映射公网；PostgreSQL 和 OA Event Flow 只允许为了受控 Code Queue active/standby 节点使用受限端口映射，并必须由 `network.restrictedHostAccess.allowedSourceCidrs` 生成的 `DOCKER-USER` 规则限制到 D601 出口地址，不能作为浏览器或任意公网客户端入口。浏览器访问 core API 必须通过 frontend 的同源代理完成；dev UI 访问路径见 `docs/reference/dev-environment.md`。
|
||||
Docker Compose 对最终用户只公开 production frontend host port、dev frontend proxy host port 和 provider ingress host port。provider data TCP port 只服务 provider 主动连入的 SSH data channel pool，不是浏览器或任意公网客户端 API。backend-core REST API 仍不得映射公网；PostgreSQL 和 OA Event Flow 只允许为了受控 Code Queue active/standby 节点使用受限端口映射，并必须由 `network.restrictedHostAccess.allowedSourceCidrs` 生成的 `DOCKER-USER` 规则限制到 D601 出口地址，不能作为浏览器或任意公网客户端入口。浏览器访问 core API 必须通过 frontend 的同源代理完成；dev UI 访问路径见 `docs/reference/dev-environment.md`。
|
||||
|
||||
计算节点上的用户服务后端也遵守同一边界：业务容器端口只绑定节点本机地址，并由 provider-gateway 主动连出 WebSocket 后接受 backend-core 的 `microservice.http` 调度访问。主 server 不为用户服务新增面向浏览器的公网反向代理端口；最终用户只通过 UniDesk frontend 的 React 页面访问结构化业务控件。
|
||||
|
||||
@@ -60,7 +60,7 @@ swap 管理不能被强塞进所有热路径。`server start/status` 可以暴
|
||||
|
||||
## Single Service Rebuild
|
||||
|
||||
前端、本机 provider-gateway、dev-frontend-proxy 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要非版本化本地重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `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 <id>`、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 迭代不得在 master server 用 `server rebuild backend-core` 编译，dev/prod backend-core CD 也不得用该命令完成 Rust 构建，必须先走 D601 CI `ci publish-backend-core`，再用 dev/prod artifact consumer 拉取成品镜像。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`。
|
||||
前端、本机 provider-gateway、dev-frontend-proxy 或主 server 承载的 Todo Note/Code Queue Manager/Project Manager/Baidu Netdisk/OA Event Flow 用户服务需要非版本化本地重建时，统一使用 `bun scripts/cli.ts server rebuild <service>`，其中 `<service>` 只能是 `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 <id>`、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`。
|
||||
|
||||
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 <full-sha>`，再用 `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` 都不能作为标准版本发布证据。
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ The dev environment lets users experience the next UniDesk version without inter
|
||||
- Dev is exposed through a separate main-server public port at `http://74.48.78.17:18083/`.
|
||||
- Dev backend/frontend workloads run in D601 native k3s namespace `unidesk-dev`, not in the main-server Compose stack.
|
||||
- Dev backend-core and frontend rollout use pushed Git commits from `origin/master:deploy.json#environments.dev`, not dirty local worktrees.
|
||||
- Rust backend-core check/build must run on D601 CI through `ci publish-backend-core`; dev CD consumes the published image and must not compile Rust.
|
||||
- Rust backend-core check/build defaults to D601 CI through `ci publish-backend-core`; dev CD consumes the published image and must not compile Rust. The only master-server build exception is a reviewed backend-core main-server online operation with explicit concurrency limiting.
|
||||
|
||||
## D601 UniDesk Workspace
|
||||
|
||||
@@ -27,7 +27,7 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v
|
||||
|
||||
固定 workspace 只作为 source truth 预检、fetch、worktree 管理和最终同步入口。实际开发、文档修改、测试补丁和 PR 准备应在固定 repo 下的独立 worktree 中完成，例如 `/home/ubuntu/workspace/unidesk-dev/.worktree/<task>`；该 worktree 必须从最新 `origin/master` 创建，使用任务专属分支或按当前 master-only 规则完成提交，结束前用 `git status` 确认只包含本任务文件。不要把 `/home/ubuntu/workspace/unidesk-dev` 根目录当作并行任务 scratch 区，也不要复用其他任务遗留 worktree。
|
||||
|
||||
Master server 不作为 UniDesk 重型验证机。仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译和 Code Queue runner 实测必须放到 D601、CI runner 或其他获批执行面；master server 只做轻量源码编辑、Git 操作、状态观察和受控调度。
|
||||
Master server 不作为 UniDesk 重型验证机。仓库级 check、Playwright/browser smoke、镜像构建、Rust/Go 编译和 Code Queue runner 实测必须放到 D601、CI runner 或其他获批执行面；master server 只做轻量源码编辑、Git 操作、状态观察和受控调度。唯一例外是 backend-core 主 server 上线：当用户或 issue 明确要求把当前 backend-core 修复上线到主 server 时，可以用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价限流执行 backend-core 专属编译，并必须用异步 job/status/health 证据回写 issue。
|
||||
|
||||
`scripts/cli.ts`、`scripts/trans`、`scripts/tran`、`scripts/src/ssh.ts` 和相邻的 `trans`/`tran`/SSH helper 是主 server 上人工与 Codex 高频使用的控制入口；这类客户端工具链改进可以直接在 master server `/root/unidesk` 轻量修改、提交并推送到 `origin/master`。该例外只覆盖 CLI/trans/tran 客户端源码、帮助、合同测试和对应 reference 文档，不覆盖 `src/components/provider-gateway` 行为变更、镜像构建、仓库级 check、浏览器 smoke 或其他重型验证。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。
|
||||
|
||||
@@ -68,7 +68,9 @@ The persistent dev rollout currently supports:
|
||||
|
||||
## Rust Backend-Core Boundary
|
||||
|
||||
backend-core is implemented as a Rust service for the dev path. The master server may inspect files, run TypeScript CLI checks, render Compose config, dispatch jobs and proxy traffic, but it must not run Rust compilation for backend-core iteration.
|
||||
backend-core is implemented as a Rust service. The default dev and CI path compiles backend-core on D601 CI and consumes commit-pinned artifacts. The master server may inspect files, run TypeScript CLI checks, render Compose config, dispatch jobs and proxy traffic, but it must not run Rust compilation for ordinary backend-core iteration.
|
||||
|
||||
Narrow production-online exception: when a user or issue explicitly asks to put the current backend-core fix online on the main-server Compose runtime, master server may run backend-core-only Rust compilation with constrained parallelism (`CARGO_BUILD_JOBS=1`, `--jobs 1`, or the CLI's equivalent setting) and must use async job/status/health evidence. This exception does not allow repository-wide checks, Rust tests, Go builds, frontend builds, or other service builds on the master server.
|
||||
|
||||
Allowed on the master server:
|
||||
|
||||
@@ -78,15 +80,16 @@ Allowed on the master server:
|
||||
- `bun scripts/cli.ts deploy apply --env dev --service backend-core`
|
||||
- `bun scripts/cli.ts ci run --revision <commit>`
|
||||
- `bun scripts/cli.ts ci run-dev-e2e --wait-ms <ms>`
|
||||
- for reviewed backend-core main-server online only: backend-core-specific `cargo check`/build with `CARGO_BUILD_JOBS=1`, or `bun scripts/cli.ts server rebuild backend-core` followed by `job status` polling and health verification
|
||||
|
||||
Not allowed on the master server for this path:
|
||||
|
||||
- `cargo check`, `cargo build`, `cargo test` or `rustfmt` against backend-core.
|
||||
- repository-wide `cargo check`, `cargo build`, `cargo test`, `rustfmt`, or any Rust command outside the backend-core main-server online exception.
|
||||
- `bun scripts/cli.ts check --rust` without the D601 CI guard.
|
||||
- `bun scripts/cli.ts server rebuild backend-core` as a way to iterate Rust backend-core, because it would build the Rust image in the main-server Docker daemon.
|
||||
- Ad-hoc `docker build` of `src/components/backend-core/Dockerfile` on the master server.
|
||||
- `bun scripts/cli.ts server rebuild backend-core` as a way to iterate Rust backend-core or replace D601 CI artifact flow.
|
||||
- Ad-hoc `docker build` of `src/components/backend-core/Dockerfile` on the master server outside the controlled CLI rebuild exception.
|
||||
|
||||
Rust checking is enabled only when the process is already running inside the D601 CI execution boundary: `UNIDESK_D601_RUST_CHECK=1 bun scripts/cli.ts check --full --rust`. `check --rust` deliberately fails outside that guard with an explicit explanation instead of silently compiling on the wrong host.
|
||||
`check --rust` remains a D601 CI/dev-execution command: `UNIDESK_D601_RUST_CHECK=1 bun scripts/cli.ts check --full --rust`. It deliberately fails outside that guard with an explicit explanation instead of silently compiling on the wrong host; the main-server online exception is handled by the backend-core-specific build/rebuild path, not by weakening `check --rust`.
|
||||
|
||||
## Dev Deploy Path
|
||||
|
||||
|
||||
@@ -32,6 +32,16 @@ Provider Gateway 是计算节点侧容器。它只主动连出到主 server 暴
|
||||
|
||||
SSH 透传只作为维护桥，不作为普通计算任务和自动升级的执行通道。普通任务、Docker 状态采集和 `provider.upgrade` 仍必须走本地 Docker socket；SSH 透传用于节点诊断、人工修复和验证 WSL/宿主维护入口是否可达。
|
||||
|
||||
## SSH Data TCP Pool
|
||||
|
||||
Provider WebSocket 是注册、heartbeat、dispatch、`provider.upgrade` 和短控制消息的主管理通道，不再承载 `trans`/`tran`/`ssh` 的大块 stdin/stdout/stderr 数据面。Host SSH 透传的数据面必须走 provider 主动连到 main server 的 TCP warm pool；provider 仍然只主动连出，不要求计算节点暴露入站端口，也不改变公网 frontend/provider ingress 之外的业务入口。
|
||||
|
||||
标准能力名是 `host.ssh.tcp-pool`。支持该能力的 provider-gateway 会在连接 WebSocket 后按 `PROVIDER_DATA_HOST`、`PROVIDER_DATA_PORT` 和 `PROVIDER_DATA_POOL_SIZE` 建立常驻 TCP 通道池，默认 10 条通道；main server 默认公开 provider data port `18084`，backend-core 容器内监听 `8082`。每条 SSH 会话或文件传输占用一条 data channel，大文件传输不能阻塞其他已空闲通道上的 SSH、小文件或脚本请求；这里不再做应用层队列、fair scheduling 或把大文件分发到控制 WebSocket 的 fallback。池耗尽时必须返回结构化错误，例如 `provider-data-pool-exhausted`，调用方按短查询/重试语义处理，而不是让单个 `trans` 长挂。
|
||||
|
||||
旧 provider 没有声明 `host.ssh.tcp-pool` 时，backend-core 必须让 `/ws/ssh` 快速失败并返回 `provider-gateway-upgrade-required`，提示升级 provider-gateway；不得保留旧的 WebSocket 数据路径作为兼容分支。`provider.upgrade mode=schedule` 本身仍走 provider WebSocket 和 Docker socket，因为升级动作必须在旧 provider 上可达，用于把节点推进到支持 TCP pool 的版本。
|
||||
|
||||
可见性必须跟随通道池。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 已经可用。
|
||||
|
||||
## 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` 记录。
|
||||
@@ -166,6 +176,6 @@ WSL provider 需要调用 Windows-only 工具链时，优先在 WSL 用户的 `~
|
||||
|
||||
维护桥通过真实 WebSocket dispatch 暴露为 `host.ssh` 命令。默认 payload 使用 `mode: "probe"`，远端只执行一个短命令并返回 `UNIDESK_SSH_TEST user=... host=... bridge=host.ssh cwd=...`；需要人工诊断时可以显式使用 `mode: "exec"` 与 `command` 字段执行有界命令。所有 `host.ssh` 执行都必须有超时，stdout/stderr 在 task result 中截断展示；自动升级和普通任务仍必须使用 Docker socket 与 `provider.upgrade`，不得把 WSL SSH 维护桥当成调度通道。
|
||||
|
||||
面向人的终端入口是 `trans <PROVIDER_ID> [ssh-like args...]`。无后续参数时打开远端登录 shell，有后续参数时执行远端命令并返回远端 exit code；该入口走 backend-core 内网 `/ws/ssh` broker 和 provider 既有 WebSocket，不新增公网 core 端口。传统 ssh 传输参数由 provider-gateway 环境变量统一控制，CLI 只负责把 Provider ID 后的远端命令和终端 stdin/stdout/stderr 透传过去。非交互远端命令优先使用 argv 入口：`trans D601 argv true`，或需要 shell 特性时使用 `trans D601 argv bash -lc '<command>'`。WSL 节点需要同时看清 Linux/WSL 与 Windows 两套 skill 时，使用 `trans <PROVIDER_ID> skills`，该命令只通过已建立的维护桥读取 `SKILL.md` 元数据，不要求 provider-gateway 新增业务 API。
|
||||
面向人的终端入口是 `trans <PROVIDER_ID> [ssh-like args...]`。无后续参数时打开远端登录 shell，有后续参数时执行远端命令并返回远端 exit code；该入口的 client 侧仍连接 backend-core 内网 `/ws/ssh` broker，core 只用 provider WebSocket 下发 open/dispatch 控制消息，终端 stdin/stdout/stderr 数据面必须走 provider 主动连接 main server 的 `host.ssh.tcp-pool` TCP warm pool，不新增计算节点入站要求，也不保留旧 WebSocket 数据 fallback。传统 ssh 传输参数由 provider-gateway 环境变量统一控制，CLI 只负责把 Provider ID 后的远端命令和终端 stdin/stdout/stderr 透传过去。非交互远端命令优先使用 argv 入口：`trans D601 argv true`，或需要 shell 特性时使用 `trans D601 argv bash -lc '<command>'`。WSL 节点需要同时看清 Linux/WSL 与 Windows 两套 skill 时，使用 `trans <PROVIDER_ID> skills`，该命令只通过已建立的维护桥读取 `SKILL.md` 元数据，不要求 provider-gateway 新增业务 API。
|
||||
|
||||
验证 WSL SSH 桥时，先在目标 WSL 中启动 sshd 并确保维护公钥写入目标用户的 `authorized_keys`，再确认目标 provider 注册 labels 中 `unideskCapabilities` 包含 `host.ssh`。运行 `bun scripts/cli.ts debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000` 后，结果应在 `debug task latest` 或前端任务历史中显示 `status: succeeded`、`probeLine` 含 `UNIDESK_SSH_TEST`、`exitCode: 0`，并且目标节点 labels 中 `hostSshKeyPresent` 为 true；随后运行 `trans <PROVIDER_ID> argv true` 验证非交互 argv 维护命令，再运行 `trans <PROVIDER_ID> hostname` 验证近似原生 ssh 的远端命令体验。在计算节点本机自测时，使用 remote CLI 透传同一组命令：`bun scripts/cli.ts --main-server-ip 74.48.78.17 debug health`、`bun scripts/cli.ts --main-server-ip 74.48.78.17 debug dispatch <PROVIDER_ID> host.ssh --wait-ms 15000`、`bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> argv true` 和 `bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh <PROVIDER_ID> hostname`；默认 remote CLI 走公网 frontend 登录态，不需要主 server SSH key。健康检查必须能看到该 Provider 在线、`hostSshConfigured=true`、`hostSshKeyPresent=true`、`hostSshTarget` 正确、`unideskCapabilities` 包含 `host.ssh`，probe 必须返回 `UNIDESK_SSH_TEST`，`ssh <PROVIDER_ID> argv true` 与 `ssh <PROVIDER_ID> hostname` 必须 exit code 为 0。如果 D518 这类 WSL 节点没有公网 SSH 入口，也必须通过这个 provider-gateway 自连维护桥完成验证，而不是要求主 server 直接连节点公网 22 端口；旧版 provider 未声明 `host.ssh` 时必须先升级 provider-gateway，否则 core 会拒绝 SSH 透传。
|
||||
|
||||
@@ -62,7 +62,7 @@
|
||||
- src/performance.rs (Request/operation performance sampling and database size reporting)
|
||||
- src/provider_registry.rs (Provider WebSocket lifecycle: register, heartbeat, status, disconnect)
|
||||
- src/task_dispatcher.rs (Task creation, dispatch to providers, wait-for-result)
|
||||
- src/ssh_bridge.rs (SSH session bridging over provider WebSocket)
|
||||
- src/ssh_bridge.rs (SSH control bridge and TCP pool data-channel dispatch)
|
||||
- src/egress_tcp.rs (Egress TCP proxy for provider outbound connections)
|
||||
- src/scheduler.rs (Scheduled task system: cron-like recurring tasks)
|
||||
- src/microservice_proxy.rs (Microservice routing, HTTP proxy, health aggregation)
|
||||
|
||||
@@ -4,7 +4,7 @@ Windows 透传用于让 WSL provider 通过 UniDesk 的 Host SSH / WSL SSH 维
|
||||
|
||||
## Architecture
|
||||
|
||||
标准链路是：本机或计算节点 CLI 调用 `trans <PROVIDER_ID> ...`，main server 的 backend-core 通过 provider-gateway 的既有 WebSocket 把终端流量转给目标 provider，provider-gateway 再用只读挂载的维护私钥连到目标 WSL sshd。进入 WSL 后，Windows-only 工具由 WSL 用户目录下的轻量 wrapper 调用 Windows 可执行文件。
|
||||
标准链路是：本机或计算节点 CLI 调用 `trans <PROVIDER_ID> ...`，main server 的 backend-core 通过 provider WebSocket 下发 SSH open/dispatch 控制消息，终端 stdin/stdout/stderr 数据面走 provider 主动连入 main server 的 `host.ssh.tcp-pool` TCP warm pool，provider-gateway 再用只读挂载的维护私钥连到目标 WSL sshd。进入 WSL 后，Windows-only 工具由 WSL 用户目录下的轻量 wrapper 调用 Windows 可执行文件。
|
||||
|
||||
这条链路分三层维护：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user