# v0.2 Postgres 稳定外部服务规格

`hwlab-v02-postgres` 是 v02 独立 Postgres StatefulSet，使用外部稳定镜像 `postgres:16-alpine` 的本地 registry 版本，内部端口 `5432`。

## 在系统中的职责划分

- 为 `hwlab-cloud-api` 提供 v02 独立 durable runtime store、migration ledger、agent/gateway/evidence 等持久化表。
- 与 `hwlab-dev`/`hwlab-prod` 数据隔离；v02 使用独立 namespace、Service、PVC、database/user 和 SecretRef。
- 不向公网开放，不由普通用户或 Code Agent 直连。

## 内部架构

- `StatefulSet/hwlab-v02-postgres` 挂载 `data` PVC 到 `/var/lib/postgresql/data`。
- `ConfigMap/hwlab-v02-postgres-init` 提供初始化 SQL 和 `hwlab_schema_migrations` ledger。
- `Secret/hwlab-v02-postgres` 提供 `POSTGRES_PASSWORD`；`Secret/hwlab-cloud-api-v02-db` 提供 cloud-api 使用的 `database-url`。
- `Service/hwlab-v02-postgres` 提供 ClusterIP DNS。

## API 接口说明

| 接口 | 说明 |
| --- | --- |
| TCP `hwlab-v02-postgres.hwlab-v02.svc.cluster.local:5432` | Postgres wire protocol，仅内部服务使用。 |
| `POSTGRES_DB=hwlab_v02`、`POSTGRES_USER=hwlab_v02` | v02 独立数据库身份。 |
| `hwlab-cloud-api /health/live` DB readiness | 对外展示 DB env、schema、auth、readiness 和 migration ledger，不打印 Secret。 |

## 测试规格

## T1

阅读 docs/reference/spec-v02-postgres.md，然后用 cli 手动测试以下内容：查询 StatefulSet、Service、PVC 和 SecretRef 名称，确认全部在 `hwlab-v02` namespace，且不输出 Secret 值。

## T2

阅读 docs/reference/spec-v02-postgres.md，然后用 cli 手动测试以下内容：访问 `hwlab-cloud-api /health/live`，确认 DB readiness ready、runtime adapter 为 Postgres、migration ledger 存在。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| 独立 StatefulSet/PVC | 已实现 | `hwlab-v02-postgres` 在 v02 namespace。 |
| 初始化 schema/migration ledger | 已实现 | ConfigMap 包含 `0001_cloud_core_skeleton`。 |
| cloud-api DB SecretRef | 已实现 | `hwlab-cloud-api-v02-db/database-url`。 |
| 自动备份/恢复 | 未实现 | 当前 spec 未定义备份服务。 |
| 多副本 HA | 未实现 | 当前为单副本 StatefulSet。 |