Codex
60 lines
5.4 KiB
Markdown
60 lines
5.4 KiB
Markdown
# NC01 Reference
|
|
|
|
NC01 is the current host registered as a UniDesk provider-gateway node. Host maintenance uses `trans NC01 ...`; Kubernetes maintenance uses `trans NC01:k3s ...`.
|
|
|
|
## Source Of Truth
|
|
|
|
- Host k8s/provider config: `config/unidesk-host-k8s.yaml`.
|
|
- Host proxy config: `config/platform-infra/host-proxy.yaml#targets.NC01`; NC01 host-proxy uses `/root/vpn-server` as the VPN server source.
|
|
- HWLAB node/lane config: `config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01`.
|
|
- HWLAB control-plane config: `config/hwlab-node-control-plane.yaml#nodes.NC01`.
|
|
- AgentRun config: `config/agentrun.yaml`, lane `nc01-v02`.
|
|
- NC01 host PostgreSQL config: `config/platform-db/postgres-nc01.yaml`.
|
|
|
|
## UniDesk Server Runtime
|
|
|
|
NC01 runs the UniDesk server/backend-core on Kubernetes in namespace `unidesk`, with `config/unidesk-host-k8s.yaml` as the configuration authority. Recovery, validation and `trans` operations must target `NC01:k3s` and those Kubernetes objects. A Docker Compose project or a container named `unidesk-backend-core` is not the NC01 server runtime and must not be used as recovery evidence. Once the Kubernetes runtime is healthy, do not rebuild, restart or replace it unless the user or owning runbook explicitly requires that action.
|
|
|
|
## Fixed Repos
|
|
|
|
- HWLAB v0.3 fixed repo: `/root/hwlab-v03`; branch and remote come from `config/hwlab-node-lanes.yaml`.
|
|
- AgentRun v0.2 fixed repo: `/root/agentrun-v02`; branch and remote come from `config/agentrun.yaml`.
|
|
- UniDesk source/config authority remains `/root/unidesk`.
|
|
|
|
## Database Boundary
|
|
|
|
NC01 database placement is selected by each owning YAML, not by a host-wide assumption. `config/unidesk-host-k8s.yaml`, `config/agentrun.yaml` and `config/hwlab-node-lanes.yaml` independently declare whether their workloads consume host-native/external PostgreSQL or a lane-local Kubernetes PostgreSQL. Validation must report the selected mode and corresponding Service/SecretRef; it must not require objects belonging to an unselected mode.
|
|
|
|
For HWLAB v0.3, `runtimeStore.postgres.mode` in `config/hwlab-node-lanes.yaml` owns this choice. A platform-service mode uses the YAML-declared external PostgreSQL bridge such as `nc01-host-postgres`; a local-k3s mode uses its lane-local PostgreSQL objects and must report the external bridge as not required. Runtime database Secrets come only from the selected mode's YAML sourceRef and may be reported as presence/fingerprint metadata, never as full values.
|
|
|
|
## Decision Center
|
|
|
|
Decision Center production runs on NC01 k8s in namespace `unidesk`, not on a bare Docker/Compose runtime and not on the old D601 Decision Center path. Runtime objects are `deployment/decision-center` and `service/decision-center`; GitHub storage credentials are distributed through the `decision-center-github-ssh` Secret and must only be reported as object/key presence or fingerprint metadata.
|
|
|
|
The durable store is the GitHub repo `pikasTech/decision-center-data` on branch `main`, with base path `data`. PostgreSQL is the service index/cache, not the durable source of truth. After data migration or repair, validate both layers:
|
|
|
|
- service health shows `storage.primary=github-repo`, `recordCount` and `diaryEntryCount`;
|
|
- `/api/storage/verify` reports cache and repo index counts with zero deltas;
|
|
- the repo worktree HEAD and `git ls-remote origin refs/heads/main` match;
|
|
- `bun scripts/cli.ts decision health`, `decision list` and `decision diary list` succeed through the NC01 k8s entrypoint.
|
|
|
|
When exporting legacy PostgreSQL data, do not stream Markdown bodies as plain JSONL through terminal output. Use a single-line-safe encoding such as hex-encoded JSON per row, write a manifest with row counts and SHA-256, transfer the bundle through `trans download/upload`, then compare canonical source and target hashes before claiming migration complete.
|
|
|
|
## GitHub Token
|
|
|
|
The local GitHub token source is `/root/.unidesk/.env/gh_token.txt`. It must be stored as a bare token and consumed through controlled YAML/sourceRef or temporary non-printing credential helpers. Do not place the token in command argv, logs, committed files, or rendered manifests. NC01 follows the canonical owner-level state and compatibility-symlink contract in [Worktree-Independent Local State](devops-hygiene.md#worktree-independent-local-state); worktrees consume `/root/.unidesk/.env` and `/root/.unidesk/.state` through fixed absolute paths instead of copied local trees.
|
|
|
|
## Public Exposure
|
|
|
|
NC01 HWLAB v0.3 does not require publicExposure unless YAML explicitly declares it and a real FRP token source is available. When publicExposure is absent, control-plane public probe is skipped and must not block runtime readiness.
|
|
|
|
Web-probe sentinel deployments that need public ingress must declare their own YAML publicExposure and Secret sourceRef. Do not create placeholder FRP tokens; a missing `platform-infra/pk01-frp.env` token source is a deployment blocker for FRP-backed public exposure.
|
|
|
|
## Validation Entrypoints
|
|
|
|
- Provider/trans: `scripts/trans NC01 argv true`.
|
|
- NC01 k8s route: `scripts/trans NC01:k3s kubectl get nodes -o wide`.
|
|
- Decision Center: `bun scripts/cli.ts decision health`; drill-down storage verification can be run inside the NC01 `decision-center` Pod against `/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`.
|