Files

T

Codex 1952014e90 docs: clarify HWLAB v03 public entry validation

2026-06-15 07:56:57 +00:00

11 KiB

Raw Blame History

G14 Platform PostgreSQL

本文是 G14 节点原生 PostgreSQL 平台库的长期参考。它覆盖 host-native PostgreSQL 的定位、连接边界、HWLAB v0.3 接入方式、备份恢复和旧自有 DB 清理入口。Redis 方案暂不纳入当前标准路径。

定位

G14 platform DB 是 G14 host OS 上的原生 PostgreSQL，不是 k3s workload，也不属于 devops-infra namespace。它位于 HWLAB runtime lane、AgentRun 和未来 G14 平台控制能力之下，作为节点级基础设施承载 durable runtime、OpenFGA datastore、平台控制元数据、租约、审计和状态观测。

数据库可以保存一部分 k3s 管理所需的状态，例如节点 inventory、runtime lane registry、operation lease、k3s state observation 和 audit event；它不直接执行 kubectl、Argo、Tekton 或 GitHub 写操作。k3s 写操作仍必须通过 UniDesk 受控 CLI 或对应控制器执行，数据库只作为状态与协调底座。

不要把平台 DB 部署成每个业务 namespace 内的自有 StatefulSet。业务 namespace 只保留指向 host-native PostgreSQL 的 ClusterIP Service/Endpoint 桥接对象和自身 SecretRef。

Host 边界

G14 平台库固定由 systemd 管理：

trans G14 sh -- 'systemctl status postgresql'
trans G14 sh -- '/usr/local/sbin/g14-platform-db-health'

PostgreSQL 只监听 G14 host loopback 与 k3s pod 可达的 node gateway 地址：

127.0.0.1:5432
10.42.0.1:5432

不得开放 0.0.0.0:5432、NodePort、FRP 公网端口或直接公网 DNS。pg_hba.conf 只允许 localhost、k3s pod CIDR 和 service CIDR 通过 SCRAM 认证连接。凭据文件固定在 G14 host：

/root/.config/g14-platform-db/credentials.env

该文件必须保持 root-only；任何 CLI、issue、日志和长期文档只允许输出 secret 是否存在、路径和 redacted 摘要，不得打印完整密码、完整 URI 或可复用凭据。

数据库与角色

平台库当前按用途拆分 database/role：

g14_platform_control / g14_platform_app：G14 节点平台控制元数据、租约、观测和审计。
hwlab_v03 / hwlab_v03_app：HWLAB v0.3 cloud-api durable runtime。
openfga_v03 / openfga_v03_app：HWLAB v0.3 OpenFGA datastore。

postgres 只作为管理数据库保留。新增 runtime lane 时按同一模式分配独立 database/role，不复用业务应用账号访问 g14_platform_control。

HWPOD v0.3 不再有当前 platform DB 目标；hwpod-v03-db、hwpod_v03 和 hwpod_v03_app 出现时只能视为废弃残留，不能作为 SecretRef 完成态或平台库目标保留。

k3s 桥接

业务 Pod 不直接访问 host IP 字面量，而是访问所在 namespace 内的 g14-platform-postgres Service。HWLAB v0.3 的桥接对象在 hwlab-v03 namespace 中：

Service/g14-platform-postgres
EndpointSlice/g14-platform-postgres-host

目标地址固定为 10.42.0.1:5432。bridge 最低验证标准是 namespace-local Service/g14-platform-postgres 存在、固定 EndpointSlice/g14-platform-postgres-host 存在且指向 host PostgreSQL，并且旧 Endpoints/g14-platform-postgres 不存在。不要保留 Endpoints 兼容路径或由它派生的随机 EndpointSlice；最终仍以 runtime /health/live 和 hwlab nodes control-plane status 的真实连接结果为准。

业务 SecretRef 固定使用现有应用 Secret 名称，不迁移为共享明文配置：

hwlab-cloud-api-v03-db/database-url 指向 hwlab_v03。
hwlab-v03-openfga/datastore-uri 指向 openfga_v03。

这些 SecretRef 的源凭据来自 G14 host 的 platform DB credentials file，不再从旧 lane-local Postgres Secret 派生。hwpod-v03-db/database-url 是废弃残留，应该缺席；发现它时用受控清理入口删除，不能为它补 status 可见性或轮换路径。迁移完成后，旧的 repo-owned PostgreSQL bootstrap/ensure 路径已经删除，不能用于轮换 hwlab-cloud-api-v03-db 或 hwlab-v03-openfga。如需重复轮换，必须先补齐平台 DB 专用 UniDesk CLI，让它从 host 凭据文件读取、写入 k3s Secret，并输出 redacted 状态；不得把手写 kubectl create secret 或旧 StatefulSet ensure 路径沉淀成长期流程。

当前运行面验证使用 control-plane status 和选中 node/lane 的 YAML public URL。D601 v0.3 的正式用户入口是 https://hwlab.pikapython.com；裸 IP/FRP 端口只能作为 Caddy/FRP 边缘诊断，不作为当前用户入口验收口径：

bun scripts/cli.ts hwlab nodes control-plane status --node D601 --lane v03
curl -fsS https://hwlab.pikapython.com/health/live | jq '{status, ready, db: {ready: .db.ready, connectionResult: .db.connectionResult}, runtime: {ready: .runtime.ready, queryResult: .runtime.connection.queryResult}}'

任何 CLI 输出都不得泄露 database URL 或 password，只披露 Secret/key 是否存在、字节数、DB 对象是否存在和 rollout/health 结果。

HWLAB v0.3 GitOps

HWLAB v0.3 的 source truth 在 G14:/root/hwlab-v03、branch v0.3。deploy/deploy.yaml 的 lanes.v03.externalPostgres 是 v0.3 使用 G14 platform DB 的声明入口；render 结果必须包含 external-postgres.yaml，并且不得再包含旧 postgres.yaml。

标准验证：

trans G14:/root/hwlab-v03 sh -- 'npm run gitops:ts:check'
trans G14:/root/hwlab-v03 sh -- 'npm run gitops:render -- --lane v03 --out /tmp/hwlab-v03-render-check'
bun scripts/cli.ts hwlab nodes control-plane trigger-current --node G14 --lane v03 --confirm
bun scripts/cli.ts hwlab nodes control-plane status --node G14 --lane v03 --pipeline-run <pipeline-run>

Argo Application hwlab-node-v03 应显示 Synced/Healthy，runtime workloads 中应只保留 service/g14-platform-postgres，不应再出现 statefulset.apps/hwlab-v03-postgres、service/hwlab-v03-postgres 或 configmap/hwlab-v03-postgres-init。

Argo 必须跟踪 Service/g14-platform-postgres 和固定 EndpointSlice/g14-platform-postgres-host。如果 argocd-cm 仍排除或忽略 Endpoints / EndpointSlice，或者旧 GitOps revision 留下了 Endpoints/g14-platform-postgres 与随机派生 EndpointSlice，使用受控入口收敛，不要手工 kubectl delete：

bun scripts/cli.ts hwlab nodes control-plane allow-endpoint-bridge --node G14 --lane v03 --dry-run
bun scripts/cli.ts hwlab nodes control-plane allow-endpoint-bridge --node G14 --lane v03 --confirm

该入口会移除旧 Argo endpoint 资源排除、重启 Argo application controller、删除旧 Endpoints/g14-platform-postgres 和它派生的多余 EndpointSlice，并 hard refresh hwlab-node-v03。收敛后的状态必须是 legacyEndpointsExist=false、hostEndpointSliceExists=true、extraEndpointSlices=[]。

旧自有 DB 清理

迁移到平台 DB 后，v0.3 自有 PostgreSQL StatefulSet、Service、ConfigMap、Secret 和 PVC 都必须清理。GitOps render 不再生成旧 postgres.yaml；如果运行面仍残留旧对象，直接用受控 CLI 清理精确命名资源，不保留兼容路径：

bun scripts/cli.ts hwlab nodes secret cleanup-owned-postgres --node G14 --lane v03 --dry-run
bun scripts/cli.ts hwlab nodes secret cleanup-owned-postgres --node G14 --lane v03 --confirm

该入口只允许 v0.3+ lane 使用，默认 dry-run。它必须先确认：

g14-platform-postgres Service 存在。
清理目标仅为旧 hwlab-v03-postgres StatefulSet、Service、ConfigMap、Secret 和 data-hwlab-v03-postgres-0 PVC。

它不得删除平台 database、平台 role、当前 hwlab-cloud-api-v03-db、当前 hwlab-v03-openfga、OpenFGA/Cloud API Deployment 或当前 platform DB bridge。PVC 删除前必须已经有平台库备份或迁移 dump 可用；迁移 dump 归档在 /var/backups/g14-platform-db/migration-*。

清理后用以下只读检查确认旧自有 DB 不再存在；公开 health 仍走选中 node/lane 的 YAML public URL，D601 v0.3 使用正式域名：

trans G14:k3s kubectl -n hwlab-v03 get statefulset,svc,endpoints,endpointslice,configmap,secret,pvc
curl -fsS https://hwlab.pikapython.com/health/live | jq '{status, ready, environment, db: {ready: .db.ready, connectionResult: .db.connectionResult}, runtime: {ready: .runtime.ready, queryResult: .runtime.connection.queryResult}}'

其中 endpoints/g14-platform-postgres 应为空，endpointslice/g14-platform-postgres-host 应存在且是唯一带 kubernetes.io/service-name=g14-platform-postgres label 的 EndpointSlice。

HWPOD v0.3 DB 残留不属于旧自有 HWLAB Postgres StatefulSet 清理目标，必须用单独的废弃对象清理入口处理：

bun scripts/cli.ts hwlab nodes secret cleanup-obsolete --node G14 --lane v03 --name hwpod-v03-db --dry-run
bun scripts/cli.ts hwlab nodes secret cleanup-obsolete --node G14 --lane v03 --name hwpod-v03-db --confirm

该入口只允许清理已确认不被 workload 引用的 hwpod-v03-db k3s Secret，并同步清理 G14 host PostgreSQL 上同名废弃目标对应的 hwpod_v03 database 与 hwpod_v03_app role；输出只披露对象是否存在、是否删除和退出码，不打印 URI、密码或可复用凭据。清理后 hwpod-v03-db、hwpod_v03、hwpod_v03_app 都应缺席。

备份与恢复

备份脚本固定在 G14 host：

trans G14 sh -- 'systemctl status g14-platform-db-backup.timer'
trans G14 sh -- '/usr/local/sbin/g14-platform-db-backup'

备份目录：

/var/backups/g14-platform-db

目录权限必须允许 postgres 写入备份文件，但不允许普通用户读取。备份文件默认归属 postgres:postgres，权限不应宽于 0640。恢复操作必须先在 issue/运维记录中说明目标 database、源 dump、停机或切换窗口和 SecretRef 影响面；不得把恢复命令写入业务 Pod 或 GitOps hook 作为默认流程。

最小恢复原则：

恢复单个应用 database，不整库覆盖 PostgreSQL cluster。
先恢复到临时 database 做 schema/table/count 校验，再切换业务 SecretRef 或执行受控 rename。
OpenFGA datastore 恢复后必须运行对应版本的 openfga migrate，再重启/观察 OpenFGA Deployment。
恢复完成后运行 /usr/local/sbin/g14-platform-db-health、目标 lane /health/live 和 hwlab nodes control-plane status。

运维判定

平台 DB 可用的最低标准：

postgresql systemd service active。
ss -ltnp 只显示 127.0.0.1:5432 和 10.42.0.1:5432 监听。
/usr/local/sbin/g14-platform-db-health 能列出预期 database。
hwlab-v03 中 g14-platform-postgres Service 可见，EndpointSlice/g14-platform-postgres-host 是唯一 bridge endpoint，旧 Endpoints/g14-platform-postgres 不存在。
hwlab-cloud-api /health/live 返回 status=ok、ready=true、db.connectionResult=connected、runtime.connection.queryResult=durable_readiness_ready。
hwlab nodes control-plane status --node G14 --lane v03 显示 Argo Synced/Healthy，runtime workload 摘要不包含旧自有 Postgres。

Redis 暂停期间，不为 HWLAB v0.3 新增 Redis 原生部署、SecretRef 或 runtime 依赖。后续如确需 Redis，应先单独形成平台级方案，明确是否 host-native、是否 namespace bridge、是否需要持久化、备份与业务隔离，再更新本文和对应 issue。

11 KiB Raw Blame History Unescape Escape