docs(dev): prefer NC01 for general builds

2026-07-13 14:05:49 +02:00
parent a1049195f5
commit 21567bafbf
3 changed files with 76 additions and 15 deletions
@@ -1,18 +1,48 @@
-# D601 Dev Environment
+# 开发与构建执行环境

-This document is the authoritative source for the persistent `unidesk-dev` environment, the public dev frontend port, `deploy apply --env dev`, and the Rust backend-core build boundary. Release-line and dev-lane governance is owned by `docs/reference/release-governance.md` and [GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6). If the same dev-environment rule would need edits in `AGENTS.md`, `docs/reference/cli.md`, `docs/reference/deploy.md`, `docs/reference/ci.md`, `docs/reference/deployment.md`, `docs/reference/e2e.md` or `TEST.md`, keep the detailed rule here and leave only a short cross-reference elsewhere.
+本文档是以下事项的权威出处：

-## Goal
+- NC01、D601 与 Master server 的构建执行面边界；
+- 持久化 `unidesk-dev` 环境；
+- 公开开发前端端口；
+- `deploy apply --env dev`；
+- Rust backend-core 构建边界。

-The dev environment lets users experience the next UniDesk version without interrupting production:
+发布线和开发 lane 治理由 `docs/reference/release-governance.md` 与
+[GitHub issue #6](https://github.com/pikasTech/unidesk/issues/6) 负责。
+同一规则需要出现在其他入口时，详细规则保留在本文档，其他文档只留简短交叉引用。

- Production stays on the normal public frontend at `http://74.48.78.17:18081/`.
- 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 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
+开发环境用于在不干扰生产环境的前提下体验下一版本 UniDesk：
+
+- 生产环境继续使用 `http://74.48.78.17:18081/` 的正常公开前端。
+- 开发环境通过独立的 Master server 端口 `http://74.48.78.17:18083/` 暴露。
+- 开发后端和前端工作负载：
+  - 运行在 D601 原生 k3s 的 `unidesk-dev` namespace；
+  - 不运行在 Master server Compose stack。
+- 开发 backend-core 和前端 rollout：
+  - 使用 `origin/master:deploy.json#environments.dev` 中已推送的 Git commit；
+  - 不使用脏 worktree。
+- Rust backend-core 检查和构建：
+  - 仍通过 `ci publish-backend-core` 使用其拥有的 D601 CI；
+  - 开发 CD 只消费已发布镜像，不编译 Rust。
+- Master server 唯一的构建例外是经过审查并显式限制并发的 backend-core 主服务上线操作。
+
+## 通用构建执行面
+
+- Master server 只负责轻量源码编辑、Git 操作、状态观察和受控调度。
+- 通用 Docker 镜像、仓库级检查、浏览器验证及 Rust/Go/前端重型构建默认使用 NC01。
+- D601 不再是通用构建首选，只在以下事实明确成立时使用：
+  - owning CI 或 Tekton 流水线固定运行在 D601；
+  - 目标产物必须进入 D601 node-local registry 或原生 k3s；
+  - 任务需要 D601 自有硬件、workspace 或运行面；
+  - 用户明确指定 D601。
+- D601 离线不得阻塞与 D601 无关的通用镜像构建；此类任务直接切到 NC01。
+- NC01 上的临时构建目录和容器只用于验证，不成为源码或部署真相。
+- 构建产物必须回到项目声明的镜像标签、registry、Git 或可审计交付路径。
+
+## D601 UniDesk 工作区

 `D601:UniDesk` 的固定开发 workspace 是 D601 节点上的 `/home/ubuntu/workspace/unidesk-dev`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/unidesk.git`。所有需要在 D601 上改 UniDesk 代码、做轻量语法/命令形态验证、验证 `trans`/`tran`/Code Queue runner、收敛分布式敏捷实验补丁的工作，都应先进入这个目录。

@@ -27,7 +57,15 @@ 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 必须通过 `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> --from origin/master` 从最新 `origin/master` 创建，让 `.worktreecopy` 中声明的本地配置白名单自动复制到新 worktree。使用任务专属分支或 detached worktree 隔离当前改动，结束前用 `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 操作、状态观察和受控调度。唯一例外是 backend-core 主 server 上线：当用户或 issue 明确要求把当前 backend-core 修复上线到主 server 时，可以用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价限流执行 backend-core 专属编译，并必须用异步 job/status/health 证据回写 issue。
+- Master server 不作为 UniDesk 重型验证机：
+  - 默认执行面是 NC01、CI runner 或目标运行面；
+  - 重型验证包括仓库级 check 和 Playwright/browser smoke；
+  - 重型构建包括镜像构建和 Rust/Go 编译；
+  - Code Queue runner 实测也遵循同一执行面边界；
+  - 只有 owning pipeline 或目标运行面固定属于 D601 时才使用 D601；
+  - 唯一例外是用户或 issue 明确要求的 backend-core 主服务上线；
+  - 该例外使用 `CARGO_BUILD_JOBS=1`、`--jobs 1` 或 CLI 内置等价方式限制并发；
+  - 结果必须用异步 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 或其他重型验证。除非用户明确要求，CLI 改动不做单元测试、合同测试或新增测试脚本。涉及 provider-gateway 代码时仍必须遵循 provider-gateway 版本和远程升级规则。

@@ -116,7 +154,11 @@ The persistent dev environment follows the shared Git-backed deployment hygiene
 Use this sequence for backend-core Rust and frontend dev work:

 1. Preflight the fixed workspace, then create the task-scoped worktree with `bun scripts/cli.ts dev-env worktree add .worktree/<task> --branch <branch> --from origin/master`; keep unrelated parallel changes separated with `git status`/`git diff`.
-2. On the master server, limit validation to diff review and concrete-file lightweight syntax checks such as `bun --check <specific-file>`. Run repository-level checks, type checks, Compose checks, frontend checks and all Rust checks on D601, CI or another approved execution surface.
+2. Master server 只执行 diff 审查和具体文件的轻量语法检查。
+   - 轻量语法检查示例是 `bun --check <specific-file>`。
+   - 仓库级检查和类型检查默认在 NC01、CI 或目标运行面执行。
+   - Compose 检查、前端检查和 Rust 检查遵循同一执行面边界。
+   - 仅 D601 owning pipeline 使用 D601。
 3. Commit the code from the task worktree and merge/push it to `origin/master` through the chosen lightweight PR or direct integration path; `deploy apply --env dev` cannot deploy unpushed local changes.
 4. Update `deploy.json` `environments.dev.services` so `backend-core` and `frontend` point at the pushed commit, then commit and push that manifest update.
 5. Preflight backend-core publication: `bun scripts/cli.ts ci publish-backend-core --commit <full-sha> --dry-run`. The result must have no `blockedScopes`, `wouldBuildOnD601=true`, D601 `unidesk-ci` Tekton runner metadata, D601 registry target `127.0.0.1:5000/unidesk/backend-core`, required labels for service id/source repo/source commit/Dockerfile, and `recommendedAction` pointing to the real publish command.