pikasTech-unidesk/docs/reference/g14-platform-db.md

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、HWPOD 和未来 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 script -- 'systemctl status postgresql'
trans G14 script -- '/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。
• hwpod_v03 / hwpod_v03_app：HWPOD v0.3 迁移后的平台库目标；HWPOD 不应继续拥有自带 DB。

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

k3s 桥接

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

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

目标地址固定为 10.42.0.1:5432。bridge 最低验证标准是 namespace-local Service/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。
• hwpod-v03-db/database-url 指向 hwpod_v03。

这些 SecretRef 的源凭据来自 G14 host 的 platform DB credentials file，不再从旧 lane-local Postgres Secret 派生。迁移完成后，旧的 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 和 live health：

bun scripts/cli.ts hwlab nodes control-plane status --node G14 --lane v03
curl -fsS http://74.48.78.17:20667/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 script -- 'npm run gitops:ts:check'
trans G14:/root/hwlab-v03 script -- '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。

旧自有 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 不再存在：

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

备份与恢复

备份脚本固定在 G14 host：

trans G14 script -- 'systemctl status g14-platform-db-backup.timer'
trans G14 script -- '/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 可见，且 Endpoints 或 EndpointSlice 至少一条 bridge 路径可见。
• 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。