windy/vps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
2d95f87897d86ebc7774d58658a8b5615cd9e2e4
vps/hosts/pgdb.md
T
windyboy 2d95f87897 docs(runbooks): pgdb ops runbooks — health / restore / update + facts refresh (W1N-228) 
- runbooks/pgdb-health.md: read-only health check (8 diagnostics) — containers,
  PG core + HA clients, write activity, TimescaleDB hypertables/compression,
  pgweb auth/bookmarks, daily custom-format backups, disk/fstab, logs
- runbooks/pgdb-restore.md: procedure-type restore (pg_restore -Fc, temp-DB swap,
  approval gates, rollback) — precondition command verified live
- runbooks/pgdb-update.md: gated command reference (pull -> config -q -> up -> verify;
  rollback = /opt/database/run + old volumes)
- index + validate-repo.sh classification updated; hosts/pgdb.md refreshed
  (SSH key auth works, scribe events hypertable, runbook cross-refs)
2026-08-29 14:51:20 +08:00

52 lines
5.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# pgdb — TimescaleDB (PG18, Docker)
## Role and access
| Item | Value |
|---|---|
| Role | TimescaleDB PostgreSQL 18 (Docker) — Home Assistant recorder 后端（`hass`/`scribe` 库） |
| IPv4 | `192.168.55.15` (LAN55) |
| DNS | (none) |
| SSH | `ssh -4 windy@192.168.55.15`（key auth 已验证可用 2026-08-29；agent 沙箱用 `ssh -F /dev/null -o BatchMode=yes`；password auth 亦可） |
| Host | PVE 管理的 QEMU VM（i440FX），Debian 13 (trixie)，内核 6.12.105 |
| Resources | 2 GB RAM / 30 GB disk（26 G 空闲） |
| Docker | 29.7.2；容器 `timescaledb` = `timescale/timescaledb:latest-pg18`（PG **18.6** + TimescaleDB **2.29.2**，Apache-2.0 版） |
| Ports | `192.168.55.15:5432`（PG，IPv4 only）；`192.168.55.15:8081`（pgweb GUI，basic auth） |
## Databases
| DB | Owner | Size | 用途 |
|---|---|---|---|
| `hass` | hass | ~14 MB | HA recorder（states/events/statistics），客户端 HAOS `192.168.55.11` |
| `scribe` | postgres | ~11 MB | HA scribe 集成（entities/areas/devices 注册表同步 + `states_raw` hypertable） |
| `postgres` | postgres | ~9 MB | 默认库 |
## Ops notes
- **Docker compose 管理**（2026-08-29 改造）：`/opt/database/docker-compose.yml`（源码在仓库 `compose/pgdb/`）+ `/opt/database/.env`（0600，密钥）+ `/opt/database/pgweb-bookmarks/`（0600，bookmark 含 DB 密码）。三个服务：
| 服务 | 镜像 | 端口 | 说明 |
|---|---|---|---|
| `timescaledb` | `timescale/timescaledb:latest-pg18` | `192.168.55.15:5432`（IPv4 only） | PG 18.6 + TS 2.29.2；healthcheck pg_isready；`restart: unless-stopped` |
| `pgweb` | `sosedoff/pgweb:latest`（v0.17.0） | `192.168.55.15:8081` | Web GUI：http://192.168.55.15:8081；basic auth（用户名/密码见 .env `PGWEB_AUTH_USER/PASS`）；`--readonly --sessions --bookmarks-only --bookmarks-dir /bookmarks`（v0.17.0 不读 PGWEB_BOOKMARKS_DIR env，必须用 flag）；bookmarks = hass/scribe |
| `pg-backup` | `prodrigestivill/postgres-backup-local:latest`（=PG18 客户端） | — | 每日 02:00（`TZ=Asia/Shanghai`，本地时区）`pg_dump -Fc` 三库 → `/opt/database/backups/{daily,weekly,monthly}`；保留 7 天/4 周/6 月；`BACKUP_ON_START` |
- **数据盘**：`/dev/sdb1`（32G ext4，label `pgdata`）挂载 `/srv/pgdata`，fstab 按 `UUID=c9e12e79-1f66-404c-ab7f-b8809be81d86`（defaults,noatime）持久化（2026-08-29 迁移）。容器 bind mount `/srv/pgdata:/var/lib/postgresql`。
- 容器内 postgres 用户 uid/gid = **70**（Debian 系，非 999）；迁移数据后需 `chown -R 70:70`。
- **密码**：postgres 超级用户已换强密码（hex，存 `/opt/database/.env` 0600，2026-08-29）。HA 用 `hass` 角色不受影响。
- **备份**：由 `pg-backup` 容器接管（2026-08-29），宿主机 cron 与 `/opt/database/pg-backup.sh` 已退役。恢复用 `pg_restore`（custom format）——2026-08-29 已实测还原 hass 库 dump（states 10014 行）成功。
- **认证**：外部连接 scram-sha-256（密码必填，改密码有效）；容器内 loopback 为 trust（官方镜像默认）。
- **回滚**：旧启动命令保留在 `/opt/database/run`（容器无状态，数据在 /srv/pgdata）；旧匿名卷 `9375195843b950f4e04c34872409ca095e1136520dd019a8e86e2794be06c236`（根盘 ~82M）保留作兜底，确认稳定后可 `docker volume rm`。
- 本机无防火墙（ufw/nft/iptables 均未装）——待办：如要彻底隔离可加 ufw 白名单 192.168.55.11。
- `/opt/database/backups/` 根下残留 `*-2026-08-29_1359.dump`（compose 化之前旧备份机制产物）与 `backup.log`——健康检查只看 `daily/`，残留可清理。
- **Runbooks**：[pgdb-health](../runbooks/pgdb-health.md)（只读健康检查）、[pgdb-restore](../runbooks/pgdb-restore.md)（pg_restore 还原）、[pgdb-update](../runbooks/pgdb-update.md)（镜像/compose 升级）。
## Known issues
- 2026-08-29：HA 侧 HACS 集成 `custom_components.scribe`（YAML `scribe: db_url:`，连 `scribe` 库）建表被拒（`permission denied for schema public`，hass 无 CREATE 权限），之后持续报 `relation "entities" does not exist`。**已解决**：① `GRANT CREATE ON SCHEMA public TO hass;`（scribe 库）② 重启 HA Core 触发重跑建表。重启后自动创建 `entities`（1591 行）/`users`/`areas`/`devices`/`integrations`/`states_raw` 表并启用 TimescaleDB 时间序列能力。报错已停止（最后一条 06:06 UTC），`states_raw` 持续写入。2026-08-29 复查：scribe 现有**两个** hypertable——`states_raw`（segmentby `metadata_id`、orderby `time`）与 `events`（segmentby `event_type`、orderby `time`），均 1 维 `time`；压缩已配置（`timescaledb_information.compression_settings` 可见对应行；2.29.x 该视图无 `compression_enabled` 列）。
- `hass` 库的 recorder 表仍为普通表（无 hypertable）；`scribe` 集成负责时间序列历史（`states_raw` + `events` hypertable）。
## Verification history
- 2026-08-29：首次检查（只读）+ 修复 scribe 权限 + 安装夜间备份。见 Linear vps 项目登记。
- 2026-08-29：**compose 改造完成**（W1N-227，用户已验收）：裸 `docker run` → `/opt/database/docker-compose.yml` 三服务（timescaledb + pgweb + pg-backup）；superuser 换强密码；端口收紧 IPv4；备份容器化（TZ=Asia/Shanghai，cron 02:00 本地）；`pg_restore` 还原实测通过；pgweb UI 用户确认可查 hass/scribe 数据。源码在仓库 `compose/pgdb/`。
- 2026-08-29：**运维 runbook 落地**（W1N-228，已验收）：新增 `runbooks/pgdb-health.md`（只读，8 项诊断全绿）、`pgdb-restore.md`（流程式，temp-DB 安全还原 + 审批门）、`pgdb-update.md`（门控命令式，回滚=/opt/database/run + 旧卷）；README 索引与 validate-repo.sh 分类同步更新；runbook 命令已对活主机逐条实测（含 `pg_restore -l` 校验当日 dump）。同日修正：SSH key auth 可用（facts 原记"密钥未安装"已过时）；scribe 新增 `events` hypertable。
Reference in New Issue View Git Blame Copy Permalink