windy/vps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
799c175996b9a825f4cd8fdc424a6ca411bac88c
vps/hosts/pgdb.md
T
windyboy eefc803d5f VPS-78: pgdb-health 标为 9 项并更新 last reviewed；pgdb.md Runbooks 行同步 
- runbooks/pgdb-health.md: Last reviewed 2026-08-29 → 2026-09-22；Related systems
  加入 scribe.csg_history 永久归档（job 1010/1011 维护）
- hosts/pgdb.md: Runbooks 行注明 9 项（第 9 项 CSG 归档新鲜度）
2026-09-22 08:49:40 +08:00

62 lines
18 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，**VMID 100**），Debian 13 (trixie)，内核 6.12.105；宿主机 **pve2 `192.168.55.25`**（Proxmox 9.2.2，SSH `root@192.168.55.25`，`onboot: 1`，QEMU guest agent 已装；2026-08-31 补记） |
| Resources | 3 GB RAM（08-30 13:58 由 2G 上调、删除 balloon/ksm/shares 后重启生效）/ 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 | ~603 MB（2026-09-21） | HA recorder（states/events/statistics），客户端 HAOS `192.168.55.11` |
| `scribe` | postgres | ~2851 MB（2026-09-21） | HA scribe 集成（entities/areas/devices 注册表同步 + `states_raw`/`events` hypertable + `csg_history` 长期归档表）；体积由 `sensor_minute` 图表管道主导（2.46 GB 未压缩 chunk），见 Known issues |
| `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`。
- **开机自愈**（2026-08-30）：新增 systemd oneshot `pgdb-compose.service`（enabled，源码在仓库 `compose/pgdb/pgdb-compose.service`）：`After=network-online.target docker.service`，开机后幂等执行 `docker compose up -d`，重试直到 `192.168.55.15:5432` 监听，重试耗尽 `--force-recreate` 兜底（数据在 bind mount，无损）。原因：2026-08-30 开机竞态——docker 恢复容器时 VM IP 尚未可绑（EADDRNOTAVAIL），timescaledb/pgweb 启动失败且 docker 不重试。手动重跑：`sudo systemctl restart pgdb-compose.service`。
- 本机无防火墙（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)（只读健康检查，**9 项**；第 9 项为 CSG 归档新鲜度，2026-09-22 新增）、[pgdb-restore](../runbooks/pgdb-restore.md)（pg_restore 还原）、[pgdb-update](../runbooks/pgdb-update.md)（镜像/compose 升级）。
- **CSG 长期归档（2026-08-29, W1N-243）**：`csg_history` 表（`period date / kind('day'|'month') / usage_kwh / cost / ladder / balance / updated_at`，PK(period,kind)，`GRANT SELECT TO hass`）保存南方电网有价值数据：day = 逐日（昨日用电/费用/阶梯/余额，2026-07-01 起），month = 当月累计（用电/费用，2025-01 起）。由 TimescaleDB 每日任务 **1010**（2026-09-21 起；原 1008）`csg_daily_snapshot()`（**14:30 UTC = 22:30 Asia/Shanghai**；**TS job 非 pg_cron**，本库未装 pg_cron）upsert 维护；计费用 `csg_ladder_cost(kwh, month)` 助手（归档侧唯一计价来源）。回填来源：集成 attributes `history_data`（59 天）+ `by_month`（19 月）——08-29 前唯一残存历史。回滚：`DROP TABLE csg_history` + 删任务（另有迁移前快照表 `csg_history_bak_20260921`）。详见下方 Known issues 2026-09-21。**2026-09-22 v5 补两件事**：① **断档自愈** job **1011** `csg_backfill_missing_days()`（**15:10 UTC = 23:10 Asia/Shanghai**，排在 1010 之后）——只 `INSERT` 缺失日期、`ON CONFLICT DO NOTHING`，**绝不覆盖既有行**，数据源是 `states_raw` 里 `latest_day_kwh` 的 (`latest_day_date`, `value`) 观测对；② day 行费用改为 `csg_ladder_cost_raw` 的**累积边际差分 + 单次 `round(...,2)`**（与 v3 回填同口径），快照表 `csg_history_bak_20260922`，脚本 `compose/pgdb/csg-snapshot-v5.sql`。详见下方 Known issues 2026-09-22。
## Known issues
- 2026-09-22：**CSG day 费用口径统一 + 断档自愈（v5，脚本 `compose/pgdb/csg-snapshot-v5.sql`）**。只读复核发现 `csg_daily_snapshot()` 写 day 费用用的是「昨日用电 × 当前档费率」**单一费率且未舍入**，而 v3 的回填用「当月累积边际差分 + `round(...,2)`」——两套口径混在同一列：当时只差精度（3 行：`2026-08-28` 4.89474 / `09-19` 6.94431 / `09-20` 6.31408，总差 -0.01），但**一旦某个跨档日由夜间任务写出就会破坏「day 费用之和 ≈ 阶梯月费用」**；时限是 2026-09-29 前后跨二档（当时 `csg_current_ladder_remaining_kwh` = 80.6、日均 8.97）。**改动**：① 新增 `csg_ladder_cost_raw(kwh, month)`（无舍入版；直接用 `csg_ladder_cost(c1) − csg_ladder_cost(c0)` 会**二次舍入**，7 月实测 1 天差 0.01）；② `csg_daily_snapshot()` v5 —— day 费用改为 `round(raw(c1) − raw(c0), 2)`，`p_month` 计算**上移到计费之前**并加**跨月守卫**（每月 1 日的 `d` 落在上月，此时 `m_usage` 是新月份累计，不可作起点，否则为负）；③ 数据日期与当日用量改为取**同一实体同一行** `latest_day_kwh`（v3 用它的 `latest_day_date` 定日期、却用 `yesterday_kwh` 取值，两实体可能错配；且 `latest_day_kwh` 归档更全，含 09-06 = 9.29 那条 `yesterday_kwh` 没有的观测）；④ 新增 job **1011** `csg_backfill_missing_days()`（**断档自愈**，insert-only）。**验证**：归一 `UPDATE 3`（与 dry-run 预测一致）；`cost <> round(cost,2)` 的行数 0；`CALL run_job(1011)` 与调度器实跑均 `Success`（1/1/0、`job_errors` 0）；函数签名为 `(job_id integer, config jsonb)`（即 job 1008 失败的根因形态，已显式排除）；两函数手动调用幂等（总行数 103、`max(day period)` 仍 09-20）；各月 `|sum(day cost) − month cost|` = 0.00 / -0.03 / -0.03（**逐日舍入累积，非缺陷**；月行由 `csg_ladder_cost` 单次舍入，是权威值）。回滚：`delete_job(1011)` + `DROP FUNCTION csg_backfill_missing_days/csg_ladder_cost_raw` + 用 v3 脚本重建主函数 + 从 `csg_history_bak_20260922` 恢复行。健康检查新增第 9 项（`runbooks/pgdb-health.md`），专查「最新 day 行日期」——**上游停更时 job 会反复 upsert 同一行、`last_run_status` 仍 `Success`、日期上也无缺口，只有该断言能发现**。
- 2026-09-21：**CSG 快照任务 1008 自创建起从未成功 + 已修复（迁移脚本 `compose/pgdb/csg-snapshot-v3.sql`）**。只读复核发现 `job_stats` 1008 = **294 次运行 / 0 成功 / 294 失败**，`job_errors` 与容器日志一致：`function or procedure "public.csg_daily_snapshot(integer, jsonb)" does not exist. Custom job actions must accept (integer, jsonb) arguments.` 根因：函数实际签名是零参数 `csg_daily_snapshot()`，而 TimescaleDB 自定义 job 动作按名字调用 `schema.proc(job_id integer, config jsonb)`；08-29 那批数据是**手工写入**的，任务本身没写过一行。后果：`csg_history` 的 day 行停在 08-28、month 行停在 08-01，且 2026-08 月行是 08-29 当时的「本月至今」**302.47 kWh / 180.28 元**，而非月终值 **331.22 / 198.65**（账单 198.64）。**修复**：① 不能直接 `DROP FUNCTION`（job 持有依赖，报 `cannot drop ... because background job 1008 depends on it`）→ `delete_job(1008)` → 换 `(job_id integer DEFAULT NULL, config jsonb DEFAULT NULL)` 签名重建 → `add_job` 重挂为 **1010**，排程从 22:00 UTC（=06:00 CST，那时集成还没发布前一日数据）对齐到 **14:30 UTC = 22:30 CST**；② 新增 `csg_ladder_cost(kwh, month)` 助手（夏季 5-10 月 260/600、非夏季 200/400；0.589/0.639/0.889），month 行费用一律由它重算；③ month 行改为**按数据日期 `d` 所属月份归属**——当月用集成本月累计，上月由该月 day 行汇总（不读集成 `last_month_*`，避开翻月瞬态：08-31 16:32 实测读到过 323.49 这种误值），并加「汇总值小于已记录值则不动」的不降级保护；④ 回填 08-29→09-19 共 22 个 day 行（08-29..08-31 取 `states_raw` 里 `yesterday_kwh` 观测值减一天；09-01..09-19 取集成 `this_month_by_day`，其中 09-06 = 9.29 是 scribe 漏采的观测），日费用按「当日用电 × 当日边际档位」计，使 day 费用之和 == 阶梯月费用。**验证**：job 1010 `last_run_status=Success`（1/1/0），`next_start = 2026-09-21 14:30 UTC`；day 行 81 条（07-01..09-19）、month 行 21 条（2025-01..2026-09）；2026-08 = 331.22/198.65、2026-09 = 168.68/99.35；9 月 day 合计 168.68 kWh / 99.33 元（与阶梯 99.35 差 0.02 为逐日四舍五入）。迁移前快照表 `csg_history_bak_20260921`（79 行）保留；旧任务 1008 的 294 条 `job_errors` 作为历史保留（Timescale 的 error retention 任务会自行清理）。差异核对：day 新增 22 条、补 cost 80 条（仅填 NULL，未覆盖既有非空值），month 改 2 条。
- 2026-09-13：**`sensor_minute` 体积构成与压缩窗口（只读诊断，暂不处理）**。`scribe` 库 2.6 GB = `sensor_minute` **2.26 GB**（850 万行 / 16 天，约 56–59 万行/天 = 331 实体 × 1440 分钟 LOCF）+ `states_raw` 290 MB + `events` 1.5 MB；`hass` 库另 406 MB。2.26 GB 中 1.50 GB 是 chunk `[09-03,09-10]`、0.76 GB 是 `[09-10,09-17]`，**都还没到压缩窗口**——TimescaleDB 的 `compress_after` 按 **chunk 结束时间**判断（09-10 结束 + 7 天 = **09-17** 才合格），所以「7 天 chunk + 7 天 compress_after」的设计下限就是盘上常驻近 14 天原始数据；已压缩的 `[08-27,09-03]` 从 1.04 GB → **1.5 MB**（LOCF 重复度极高，~700:1）。任务 1005 健康（30 成功 / 0 失败）。**2026-09-21 复查已通过**：`_hyper_4_6_chunk`（09-03→09-10）`is_compressed=t`（32 kB），`_hyper_4_10_chunk`（09-10→09-17，1557 MB）按 09-24 合格待压，稳态平台期估算不变（≈4–5 GB）；pgdata 实测 3.6 G / 32 G（13%），**无需处理**。可选调优：chunk 间隔 7 天 → 1 天 + `compress_after` → 2 天（`set_chunk_time_interval` 只对新 chunk 生效）。**注意：这是 pgdb 侧对象，HA/scribe 的 `retention_states` 管不到它；HA 侧唯一杠杆是少记/少画（等于砍图）。**
- 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` 列）。
- 2026-08-29：**timescale reader 图表对象**（配套 hass 的 `timescale_database_reader` 集成 + `timescale-plotly-card`，上游 SQL `remmob/timescale_database_reader` `SQL/scribe/01+02` @ `bb8776a`，以 postgres 执行）：`sensor_minute_aggregate` 连续聚合（1 分钟桶，last(state)/last(value)，实时聚合开启）+ `sensor_minute_aggregate_entity` 视图（join `entities`）+ `sensor_minute` hypertable（`minute`/`entity_id`/`state`/`value`，LOCF 前向填充）。任务：1005 `sensor_minute` 压缩（7 天）、1006 `sensor_minute` 保留（10 年）、1007 `every_minute_refresh` 每分钟增量刷新（含 5 分钟回溯窗口修正）。授权：`GRANT SELECT ON sensor_minute_aggregate, sensor_minute_aggregate_entity, sensor_minute, entities TO hass`。种子 19529 行（331 实体，自首个数据点起）。**刻意跳过**了上游脚本对 `states_raw` 的 3 个月保留 + 压缩策略语句——与"`states_raw` 永久归档"定位冲突，如需磁盘回收属用户决策（scribe 自己的压缩任务 1000/1001 未动）。
- 2026-08-29：**`sensor_minute_refresh` 本地补丁（类比 tianqi 补丁，重跑上游 02 SQL 后需重打）**：值 CASE 的 `ELSE 0` → `ELSE NULL`。原因：scribe 对 unavailable 分钟 value 为 NULL，上游刷新过程兜底写 0；对差分模式的用电图，0→计数器回升会把插座的**生命周期累计值**（最高 1588 kWh）算进掉线那一小时。同日一次性清理既有脏 0：头部占位行 DELETE 505 行（各实体首次非零分钟之前的 value=0）；`sensor.%_energy` 与温湿度实体的 value=0 → NULL（10+16 行，物理上不可能的真 0，图表渲染为断点）。功率实体的中途 0 是真实待机读数，保留。
- `hass` 库的 recorder 表仍为普通表（无 hypertable）；`scribe` 集成负责时间序列历史（`states_raw` + `events` hypertable）。
## Verification history
- 2026-08-31：**13:58 重启根因确认，非停电**（W1N-263）：pve2（`192.168.55.25`）任务日志显示 08-30 **13:58:00 `root@pam` 在 PVE Web UI 修改 VM 100 配置**（`-delete allow-ksm,balloon,shares -memory 3072`），**13:58:06 点 Reboot**（`qmreboot` → 客机 13:58:08 干净 ACPI 关机 → 13:58:13 自动重启）。宿主机全程在线（08-30 09:00 开机至今连续运行 1d12h+），`.66.26` PVE 及各 VM 均无重启——排除停电。HA recorder 在窗口（13:58:46–47）报 2 次 `Connection refused`，DB 恢复后自动重连，**无数据丢失**（`hass.states`/`scribe.states_raw` 13:55–14:02 逐分钟无缺口，recorder 内存队列吸收回写）。13:58:47 三容器已起，13:58:56 自愈单元 `pgdb-compose.service` 执行成功——本次自愈按设计工作。同日下午 12:54–12:55 另有一次**客机内自重启**（无 PVE 任务，工作站 SSH 会话相邻）。08-29 22:19→08-30 09:00 宿主机停机 10h41m 为**干净关机**（systemd 有序关闭，非停电）。
- 2026-08-30：**开机竞态故障 + 修复**（W1N-260）：09:01 开机后 docker 恢复容器时绑定 `192.168.55.15:5432/8081` 失败（EADDRNOTAVAIL）→ timescaledb/pgweb 停摆至 12:16，pg-backup 开机备份失败（解析不到 timescaledb）→ unhealthy。12:22 `docker compose up -d --force-recreate` 修复（三容器回 `database_default`、端口发布、今日备份、pgweb 恢复）；用户重启 HA Core 后写入管道恢复。12:43 新增开机自愈 unit `pgdb-compose.service`（enabled，已实测幂等 reconcile）。pgdb-health 8 项全绿。
- 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。
- 2026-08-29：**CSG 长期归档 + recorder 365d**（W1N-243）：建 `csg_history` 表 + attributes 回填（逐日 59 + 逐月 19）+ 每日任务 1008（函数 v2：最新有值行读取、日费用阶梯回退）；hass `purge_keep_days` 30→365（备份 `configuration.yaml.bak-20260829-purge365`）。见 Linear vps W1N-243。
Reference in New Issue View Git Blame Copy Permalink