docs: record CSG v1.3.1 zip install and correct ha-maintenance restart failure

ha-maintenance.sh --restart-core --yes exited 1 in <1s without restarting Core. Empty output is ssh failure hidden by 2>/dev/null + pipefail, not a MOTD-strip after a successful restart. Direct `ha core restart` is the working path.
2026-08-14 22:31:31 +08:00
parent 1dc880362d
commit eda6536ddb
2 changed files with 264 additions and 36 deletions
@@ -1,3 +1,4 @@
+[hosts/hass.windy.lan.md#8DF6]
 # hass.windy.lan — Home Assistant (HAOS)

 ## Role and access
@@ -110,31 +111,125 @@ getent hosts hass.windy.lan

 ## Local patches (custom components)

-**`china_southern_power_grid_stat` configurable IP family (verified 2026-08-14, W1N-105):**
-`/config/custom_components/china_southern_power_grid_stat` is a file copy of
-GitHub `windyboy/china_southern_power_grid_stat` `main` (`a433e8c`, W1N-105 +
-P1; the fork's default branch was renamed `master` → `main` on 2026-08-14).
-Earlier live trees: `de01914` (W1N-103), `eb8b174` (W1N-102). The live client
-uses HA `async_get_clientsession` with a stored `ip_family` option (`auto` /
-`ipv4` / `ipv6`; default `auto`, which does IPv4/IPv6 happy-eyeballs). The
-network step is now part of Add Entry (and reauth), not only the options flow.
-Entry `01KGCQDSZCF523A9X6SV3BZ1B9` is `ip_family: ipv4`. Backups:
-`china_southern_power_grid_stat.bak-20260814-w1n102` (HACS/`requests`),
-`china_southern_power_grid_stat.bak-20260814-w1n104` (`eb8b174`), and
-`china_southern_power_grid_stat.bak-20260814-w1n105` (`de01914`). HACS still
-tracks `CubicPill/china_southern_power_grid_stat` — a HACS update would
-overwrite this fork. This directory is a file copy, not a git clone; do not
-`git pull` in place.
+### Manual custom-component install (this host)
+
+Home Assistant loads custom integrations from
+`<config>/custom_components/<domain>/` (HAOS: `/config` ≡ `/homeassistant`).
+A folder named after the integration domain, containing at least
+`manifest.json` and `__init__.py`, is enough; Core must be restarted after
+copying files. Official HA lookup order:
+`<config>/custom_components/<domain>` then built-in
+`homeassistant/components/<domain>`.
+See [Integration file structure](https://developers.home-assistant.io/docs/creating_integration_file_structure).
+
+This host **does not git-clone** custom components. The live tree is a file
+copy. Do not `git pull` on HA.
+
+**Official plugin path** (from
+[windyboy/china_southern_power_grid_stat README](https://github.com/windyboy/china_southern_power_grid_stat)):
+HACS **or** [手动下载安装](https://github.com/windyboy/china_southern_power_grid_stat/releases).
+This host uses the latter. Releases here have no uploaded zip assets; use
+GitHub's **Source code (zip)** / zipball of the tag.
+
+**UI (Samba / File editor / Studio Code Server):**
+
+1. Download Source code (zip) from the GitHub Release.
+2. Extract. Copy only the inner
+   `custom_components/china_southern_power_grid_stat/` tree — not the repo
+   root, not a nested extra folder.
+3. Place it at `/config/custom_components/china_southern_power_grid_stat/`.
+4. Restart Core (**Settings → System → Restart**).
+5. First install only: **Settings → Devices & services → Add integration**.
+
+**SSH from the workstation** (verified 2026-08-14, W1N-107). Replace `v1.3.1`
+with the tag being installed:
+
+```bash
+TAG=v1.3.1
+STAGE=/tmp/csg-${TAG}-deploy
+mkdir -p "$STAGE"
+gh api "repos/windyboy/china_southern_power_grid_stat/zipball/${TAG}" \
+  > "$STAGE/src.zip"
+unzip -q "$STAGE/src.zip" -d "$STAGE"
+SRC=$(find "$STAGE" -type d -path '*/custom_components/china_southern_power_grid_stat' | head -1)
+# expect .../custom_components/china_southern_power_grid_stat
+
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i mkdir -p /homeassistant/.csg-backups &&
+   sudo -n -i cp -a /homeassistant/custom_components/china_southern_power_grid_stat \
+     /homeassistant/.csg-backups/china_southern_power_grid_stat.bak-$(date +%Y%m%d)-manual'
+
+rsync -a --delete \
+  -e 'ssh -o BatchMode=yes' \
+  "$SRC/" \
+  hassio@hass.windy.lan:/homeassistant/custom_components/china_southern_power_grid_stat/
+
+# --delete cannot remove Core-owned __pycache__; wipe as root, then restart
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i rm -rf /homeassistant/custom_components/china_southern_power_grid_stat/__pycache__ \
+     /homeassistant/custom_components/china_southern_power_grid_stat/*/__pycache__ &&
+   sudo -n -i ha core restart'
+```
+
+Wait until Core is up (`ha core info` returns, typically 1–2 min; this CLI
+build does not print a `state:` field).
+Then:
+
+```bash
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i cat /homeassistant/custom_components/china_southern_power_grid_stat/manifest.json'
+# version must match the tag
+
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i ha core logs -n 2500' | grep -E 'china_southern_power_grid_stat|cannot pickle' || true
+```
+
+**Host constraints (do not skip):**
+
+- Backups **must** live in `/homeassistant/.csg-backups/`. A `*.bak-*`
+  directory next to the live folder is scanned as the same domain and Core
+  fails with `No module named '...bak-YYYYMMDD-...'`.
+- Do not install this fork via HACS on this host. HACS still tracks
+  `CubicPill/china_southern_power_grid_stat` `v1.2.0`; a HACS update would
+  overwrite the live copy.
+- First poll after restart can time out to CSG over IPv4; if this-month
+  sensors stay `unknown` while last-month filled, reload the config entry
+  (UI: integration → Reload, or supervisor
+  `POST /core/api/config/config_entries/entry/<id>/reload`).
+- `runbooks/scripts/ha-maintenance.sh --restart-core --yes` can print
+  nothing and exit 1 in under a second **without restarting Core**. The
+  wrapper's ssh line discards stderr (`2>/dev/null`); with `pipefail`,
+  an ssh failure yields empty stdout + exit 1 before any remote command
+  runs. Do not treat that as a completed restart. Confirm with elapsed
+  time (~2 min for a real restart) and `ha core info`. Prefer
+  `ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i ha core restart'`.
+
+Full command family: [runbooks/home-assistant-maintenance.md](../runbooks/home-assistant-maintenance.md).
+
+### `china_southern_power_grid_stat` live tree
+
+**v1.3.1** (`55a293fc`, verified 2026-08-14, W1N-107): manual zipball of
+GitHub release
+[v1.3.1](https://github.com/windyboy/china_southern_power_grid_stat/releases/tag/v1.3.1)
+copied to `/config/custom_components/china_southern_power_grid_stat`.
+Earlier trees: v1.3.0/`69f13c90` (W1N-106), `a433e8c` (W1N-105), `de01914`
+(W1N-103), `eb8b174` (W1N-102). Backups:
+`/homeassistant/.csg-backups/` (w1n102/104/105/106/107).
+
+v1.3.0 crashed the coordinator on first refresh
+(`TypeError: cannot pickle 'mappingproxy' object` in
+`copy.deepcopy(self._config)` under Python 3.14 / HA 2026.8.1). v1.3.1
+wraps those `deepcopy` calls with `dict(...)`. Post-restart 22:13 CST:
+entry `loaded`, no pickle traceback. Native this-month sensors filled after
+reloading entry `01KGCQDSZCF523A9X6SV3BZ1B9` (`ip_family: ipv4`). Native
+cost/ladder sensors can stay `unknown` because CSG
+`get_month_daily_cost_detail` returns a marketing-system SQL error; the
+dashboard uses template ladder/cost entities instead. Do not change
+`templates/csg_sensors.yaml` or the 电力监控 dashboard for an install.

 Home PPPoE IPv4 to CSG is still blackholed (`curl -4` to `218.19.148.218:443`
 times out). `end1` IPv6 is enabled (`ipv6.method: auto`); from HA,
 `curl -6 https://95598.csg.cn` returns HTTP 200 via `240e:f9:8060::1:16`.
-After this deploy, Core started 16:07:15 CST; first `verify_login` timed out,
-reload of the entry then succeeded (`state: loaded` at 16:08:50) and CSG
-sensors updated. Some cost/ladder sensors stay `unknown` because CSG's own
-`get_month_daily_cost_detail` calendar API returns a marketing-system SQL
-error — transport to `95598.csg.cn` is working. Re-apply after any
-HACS/`CubicPill` update.

 **`tianqi` weather recorder patch (verified 2026-08-13, W1N-75):**
 `/config/custom_components/tianqi/weather.py` has a local patch adding
@@ -184,6 +279,6 @@ fails.

 ## Related docs

- [runbooks/home-assistant-maintenance.md](../runbooks/home-assistant-maintenance.md) — `ha` CLI maintenance runbook + [script](../runbooks/scripts/ha-maintenance.sh)
+- [runbooks/home-assistant-maintenance.md](../runbooks/home-assistant-maintenance.md) — `ha` CLI maintenance runbook + [script](../runbooks/scripts/ha-maintenance.sh); custom-component zip install is §7
 - [docs/lan-overview.md](../docs/lan-overview.md) — LAN map and gw port-forward
- [hosts/dns.windy.lan.md](dns.windy.lan.md) — `hass.windy.lan` / `hass.local` rewrites
+- [hosts/dns.windy.lan.md](dns.windy.lan.md) — `hass.windy.lan` / `hass.local` rewrites