pikastech
118 lines
6.0 KiB
Markdown
118 lines
6.0 KiB
Markdown
# NC01 参考
|
||
|
||
## 主机身份
|
||
|
||
- `NC01` 就是当前 Codex/UniDesk shell 所在主机，不是另一台远端机器。
|
||
- 当前工作目录 `/root/unidesk`、HWLAB 固定仓库 `/root/hwlab-v03` 和
|
||
AgentRun 固定仓库 `/root/agentrun-v02` 都位于同一台 NC01 主机。
|
||
- `trans NC01 ...` 是访问当前主机的受控 provider route；使用该 route 不会把
|
||
NC01 变成跨主机执行面，也不能据此推断存在远端源码副本、网络边界或第二份状态。
|
||
- 普通本机源码读取、worktree 开发和轻量 Git 操作直接使用上述绝对路径；
|
||
Kubernetes 运维继续使用 `trans NC01:k3s ...`，需要受控 provider 语义的主机
|
||
运维继续使用 `trans NC01 ...`。
|
||
- 文档中的 `Master server`、控制端或当前主机在未由 owning YAML 明确选择其他
|
||
node 时都指 NC01 的逻辑角色，不得误解成 NC01 之外的默认执行节点。
|
||
|
||
## 事实来源
|
||
|
||
- 主机 k8s/provider 配置：`config/unidesk-host-k8s.yaml`。
|
||
- 主机代理配置：`config/platform-infra/host-proxy.yaml#targets.NC01`；NC01 的
|
||
host-proxy 使用 `/root/vpn-server` 作为 VPN server 源码来源。
|
||
- HWLAB node/lane 配置：`config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01`。
|
||
- HWLAB 控制面配置：`config/hwlab-node-control-plane.yaml#nodes.NC01`。
|
||
- AgentRun 配置：`config/agentrun.yaml`，lane 为 `nc01-v02`。
|
||
- NC01 host PostgreSQL 配置：`config/platform-db/postgres-nc01.yaml`。
|
||
|
||
## UniDesk Server 运行面
|
||
|
||
NC01 在 `unidesk` namespace 的 Kubernetes 中运行 UniDesk server/backend-core，
|
||
配置权威是 `config/unidesk-host-k8s.yaml`。恢复、验证和 `trans` 操作必须指向
|
||
`NC01:k3s` 及对应 Kubernetes 对象。Docker Compose project 或名为
|
||
`unidesk-backend-core` 的容器不是 NC01 server 运行面，不能作为恢复证据。
|
||
Kubernetes 运行面 healthy 后，除非用户或 owning runbook 明确要求，不得重建、
|
||
重启或替换。
|
||
|
||
## 固定仓库
|
||
|
||
- HWLAB v0.3：`/root/hwlab-v03`；分支和 remote 来自
|
||
`config/hwlab-node-lanes.yaml`。
|
||
- AgentRun v0.2：`/root/agentrun-v02`；分支和 remote 来自
|
||
`config/agentrun.yaml`。
|
||
- UniDesk 源码和配置权威：`/root/unidesk`。
|
||
|
||
这些路径是 NC01 本机路径。不得因为 owning YAML 同时声明 `node: NC01` 或 CLI
|
||
支持 `trans NC01:<workspace>`，就把它们描述成远端 workspace。
|
||
|
||
## 数据库边界
|
||
|
||
NC01 数据库位置由各 owning YAML 独立选择，不能使用主机级假设。
|
||
`config/unidesk-host-k8s.yaml`、`config/agentrun.yaml` 和
|
||
`config/hwlab-node-lanes.yaml` 分别声明其 workload 使用 host-native/external
|
||
PostgreSQL 还是 lane-local Kubernetes PostgreSQL。验证必须报告选中的模式及对应
|
||
Service/SecretRef，不得要求未选中模式的对象存在。
|
||
|
||
HWLAB v0.3 由 `config/hwlab-node-lanes.yaml` 中的
|
||
`runtimeStore.postgres.mode` 选择数据库模式：
|
||
|
||
- platform-service 模式使用 YAML 声明的 external PostgreSQL bridge，例如
|
||
`nc01-host-postgres`；
|
||
- local-k3s 模式使用 lane-local PostgreSQL 对象，并把 external bridge 报告为
|
||
not required；
|
||
- runtime database Secret 只能来自选中模式的 YAML `sourceRef`；本地来源位于
|
||
`/root/.unidesk/.state/secrets/hwlab/*`，只允许报告 presence/fingerprint，
|
||
不得输出完整值。
|
||
|
||
## Decision Center
|
||
|
||
Decision Center production 运行在 NC01 k8s 的 `unidesk` namespace，不运行在
|
||
裸 Docker/Compose，也不使用旧 D601 Decision Center 路径。运行对象是
|
||
`deployment/decision-center` 和 `service/decision-center`；GitHub storage 凭据通过
|
||
`decision-center-github-ssh` Secret 分发，只允许报告对象/key presence 或
|
||
fingerprint。
|
||
|
||
durable store 是 GitHub 仓库 `pikasTech/decision-center-data` 的 `main` 分支，
|
||
base path 为 `data`。PostgreSQL 只是 service index/cache，不是 durable source of
|
||
truth。数据迁移或修复后同时验证：
|
||
|
||
- service health 显示 `storage.primary=github-repo`、`recordCount` 和
|
||
`diaryEntryCount`；
|
||
- `/api/storage/verify` 报告 cache 与 repo index count 且 delta 为零；
|
||
- repo worktree HEAD 与 `git ls-remote origin refs/heads/main` 一致；
|
||
- `bun scripts/cli.ts decision health`、`decision list` 和
|
||
`decision diary list` 通过 NC01 k8s 入口成功。
|
||
|
||
导出遗留 PostgreSQL 数据时，不得把 Markdown 正文作为普通 JSONL 输出到终端。
|
||
使用单行安全编码，例如每行 hex 编码 JSON；同时生成包含行数和 SHA-256 的
|
||
manifest，经 `trans download/upload` 传输，并在宣称迁移完成前比较 canonical
|
||
source 与 target hash。
|
||
|
||
## GitHub Token
|
||
|
||
本地 GitHub token 来源是 `/root/.unidesk/.env/gh_token.txt`。它必须保存为纯 token，
|
||
并通过受控 YAML/sourceRef 或临时不打印的 credential helper 使用。禁止放入命令
|
||
argv、日志、提交文件或渲染 manifest。NC01 遵循
|
||
[Worktree-Independent Local State](devops-hygiene.md#worktree-independent-local-state)
|
||
中的 owner-level state 与 compatibility symlink 合同；worktree 通过固定绝对路径
|
||
使用 `/root/.unidesk/.env` 和 `/root/.unidesk/.state`，不得复制本地状态目录。
|
||
|
||
## 公网暴露
|
||
|
||
NC01 HWLAB v0.3 只有在 YAML 显式声明 `publicExposure` 且存在真实 FRP token 来源时
|
||
才要求公网暴露。缺少 `publicExposure` 时，控制面跳过 public probe，不得阻塞
|
||
runtime readiness。
|
||
|
||
需要公网 ingress 的 web-probe sentinel 必须声明自身 YAML `publicExposure` 和
|
||
Secret `sourceRef`。不得创建占位 FRP token；依赖 FRP 暴露时，缺少
|
||
`platform-infra/pk01-frp.env` token source 是部署 blocker。
|
||
|
||
## 验证入口
|
||
|
||
- Provider/trans：`scripts/trans NC01 argv true`。
|
||
- NC01 k8s：`scripts/trans NC01:k3s kubectl get nodes -o wide`。
|
||
- Decision Center：`bun scripts/cli.ts decision health`；storage 下钻可在 NC01
|
||
`decision-center` Pod 内调用 `/api/storage/verify`。
|
||
- HWLAB v0.3：
|
||
`bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03 --full`。
|
||
- AgentRun v0.2：
|
||
`bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02`。
|