windy/vps

Files

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

5.9 KiB

Raw Blame History

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（只读健康检查）、pgdb-restore（pg_restore 还原）、pgdb-update（镜像/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。

5.9 KiB Raw Blame History Unescape Escape