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,7 +1,7 @@
 # Runbook: Home Assistant maintenance (hass.windy.lan)

 Target: [hass.windy.lan](../hosts/hass.windy.lan.md) (HAOS, `machine: green`)
-Upstream: HAOS 18.1 / Core 2026.8.x / Supervisor 2026.07.5 (verified 2026-08-13)
+Upstream: HAOS 18.1 / Core 2026.8.1 / Supervisor 2026.07.5 (verified 2026-08-14)

 This runbook covers routine Home Assistant maintenance through the **`ha`
 supervisor CLI**. All commands are wrapped by a single script
@@ -26,6 +26,17 @@ The script runs its whole procedure in one remote login (`sudo -n -i bash -s`)
 so the banner appears once, then strips it with `awk` up to the
 `System is ready! Use browser or app to configure.` line.

+**Restart wrapper (verified 2026-08-14, W1N-107):**
+`./ha-maintenance.sh --restart-core --yes` exited 1 with no output in <1s
+and **did not restart Core**. The wrapper pipes a remote script through
+`ssh … 2>/dev/null | awk …`; with `set -uo pipefail`, an ssh failure is
+silent and the pipeline returns empty/exit 1 **before any remote command
+runs**. That is not a MOTD-strip artifact after a successful restart.
+The working restart was
+`ssh -o BatchMode=yes hassio@hass.windy.lan 'sudo -n -i ha core restart'`
+(~131s, `Command completed successfully.`). Treat empty/exit 1 as
+failure; confirm with elapsed time and `ha core info`.
+
 ## Script usage

 ```bash
@@ -33,7 +44,7 @@ cd runbooks/scripts

 ./ha-maintenance.sh                                # read-only health snapshot
 ./ha-maintenance.sh --check-config                 # validate core configuration
-./ha-maintenance.sh --logs core 200                # tail core logs
+./ha-maintenance.sh --logs core 2500               # tail core logs (use 2500 after a restart)
 ./ha-maintenance.sh --logs supervisor              # tail supervisor logs (default 100)
 ./ha-maintenance.sh --logs host 50                 # tail host journald logs
 ./ha-maintenance.sh --logs apps:<slug>             # tail an add-on log
@@ -55,7 +66,7 @@ cd runbooks/scripts
 - `--restore` overwrites the current installation — run only from a planned
  recovery, with the backup verified.

-## Command reference (verified 2026-08-13)
+## Command reference (verified 2026-08-14)

 All verified against the live host. MOTD prepends each command's output; strip
 with the `awk` pattern above or read the last block.
@@ -65,7 +76,7 @@ with the `awk` pattern above or read the last block.
 | Purpose | Command |
 |---|---|
 | General overview | `ha info` |
-| Core version/status | `ha core info` |
+| Core version/status | `ha core info` (this CLI build has no `state:` field; success is a normal info dump) |
 | Core config validation | `ha core check` |
 | Core stats | `ha core stats` |
 | Supervisor status | `ha supervisor info` (incl. add-on list) |
@@ -78,7 +89,7 @@ with the `awk` pattern above or read the last block.
 | Reload stores/versions | `ha refresh-updates` |
 | Job manager | `ha jobs info` |
 | Resolution center | `ha resolution info` |
-| Core logs | `ha core logs -n 100` (`-f` follow, `-b` boot id) |
+| Core logs | `ha core logs -n 100` (`-f` follow, `-b` boot id). Default 100 misses setup; use `-n 2500` after a custom-component restart. `/config/home-assistant.log` may be missing — `ha core logs` is the source of truth. |
 | Supervisor logs | `ha supervisor logs -n 100` |
 | Host journald logs | `ha host logs -n 100` |
 | Add-on logs | `ha apps logs <slug> -n 100` |
@@ -120,14 +131,21 @@ add-on states (any `state: error`?); `resolution info` issues; disk free.

 Expect `Command completed successfully.` before a Core restart.

+`ha core check` / a YAML reload is **not** enough after copying Python
+custom-component files — restart Core.
+
 ### 3. Inspect logs

 ```bash
-./ha-maintenance.sh --logs core 200
+./ha-maintenance.sh --logs core 2500   # after a Core restart / custom-component copy
 ./ha-maintenance.sh --logs supervisor
 ./ha-maintenance.sh --logs apps:core_mosquitto
 ```

+Default `--logs core` (100 lines) is too short to catch coordinator pickle /
+setup errors. `/config/home-assistant.log` may be absent while
+`ha core logs` still has history.
+
 ### 4. Apply updates (mutating)

 ```bash
@@ -155,6 +173,104 @@ booted. After a bad OS update, `ha os boot-slot other` boots the previous slot.
 ./ha-maintenance.sh --backup pre-migration --yes       # named backup
 ```

+### 7. Install or update a custom component (manual zip)
+
+Home Assistant loads custom integrations from
+`/config/custom_components/<domain>/` (on this HAOS host `/config` ≡
+`/homeassistant`). Official lookup:
+`<config>/custom_components/<domain>` then built-in
+`homeassistant/components/<domain>`
+([Integration file structure](https://developers.home-assistant.io/docs/creating_integration_file_structure)).
+A folder named after the domain, with at least `manifest.json` and
+`__init__.py`, is enough. **Restart Core** after copying — `ha core check`
+and a YAML reload do not pick up new Python packages.
+
+This host's live trees are **file copies**, not git clones. Do not
+`git pull` inside `custom_components/`.
+
+#### Official plugin paths (CSG)
+
+[windyboy/china_southern_power_grid_stat README](https://github.com/windyboy/china_southern_power_grid_stat):
+[HACS](https://hacs.xyz/) **or**
+[手动下载安装](https://github.com/windyboy/china_southern_power_grid_stat/releases).
+
+This host uses the zip path. **Do not HACS-update this integration here.**
+HACS still tracks upstream `CubicPill/china_southern_power_grid_stat`
+`v1.2.0` and would overwrite the fork. Releases have no uploaded zip
+assets — use GitHub **Source code (zip)** / zipball of the tag.
+
+Worked SSH example (tag, backup, `rsync`, `__pycache__`, restart):
+[hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) § Manual
+custom-component install.
+
+#### Procedure
+
+1. **Backup the live tree off `custom_components/`.** HA scans every
+   directory under `custom_components/` whose `manifest.json` `domain`
+   matches. A `*.bak-*` folder next to the live tree makes Core import
+   the backup (`No module named '...bak-YYYYMMDD-...'`, W1N-106). CSG
+   backups: `/homeassistant/.csg-backups/`.
+2. **Copy only the inner `custom_components/<domain>/` tree**, not the
+   repo root and not an extra nested folder.
+3. **Wipe `__pycache__` as root.** `rsync --delete` as `hassio` cannot
+   unlink Core-owned `.pyc` (permission denied, exit 23); stale
+   `cpython-314` bytecode can keep the old coordinator in memory until
+   restart. Then restart:
+
+```bash
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i rm -rf /homeassistant/custom_components/<domain>/__pycache__ \
+     /homeassistant/custom_components/<domain>/*/__pycache__ &&
+   sudo -n -i ha core restart'
+```
+
+4. **Wait 1–2 min**, then `ha core info` (this CLI build has no `state:`
+   field; success is a normal info dump). Confirm `manifest.json`
+   `version` matches the tag.
+5. **Read enough Core logs.** Default `ha core logs` is too short to
+   catch setup. Use `-n 2500` (or `--logs core 2500`) and look for
+   `Setting up <domain>` plus the first coordinator errors.
+6. **First poll can time out.** If last-month sensors have numbers but
+   this-month stay `unknown`/`unavailable`, reload the config entry
+   (UI: integration → Reload). Supervisor:
+
+```bash
+# entry id from .storage/core.config_entries (CSG: 01KGCQDSZCF523A9X6SV3BZ1B9)
+ssh -o BatchMode=yes hassio@hass.windy.lan \
+  'sudo -n -i python3 -c "
+import os, urllib.request
+req = urllib.request.Request(
+    \"http://supervisor/core/api/config/config_entries/entry/<ENTRY_ID>/reload\",
+    method=\"POST\",
+    headers={\"Authorization\": \"Bearer \" + os.environ[\"SUPERVISOR_TOKEN\"]},
+)
+print(urllib.request.urlopen(req, timeout=60).status)
+"'
+```
+
+7. **Do not edit the dashboard or `templates/csg_sensors.yaml` for an
+   install.** Entity IDs did not change across v1.3.0/v1.3.1. Template
+   `| float(0)` turns native `unavailable` into fake zeros; that is a
+   follow-up, not part of the zip install.
+
+#### Verify (CSG, after v1.3.1 / W1N-107)
+
+| Check | Expect |
+|---|---|
+| `manifest.json` `version` | `1.3.1` |
+| `ha core logs` after this restart | `Setting up china_southern_power_grid_stat`; **no** `cannot pickle 'mappingproxy'` |
+| Config entry | `state: loaded` |
+| `sensor.0800041935246530_balance` | numeric (may be `0.0`) |
+| `sensor.0800041935246530_this_month_total_usage` | numeric after reload if first poll timed out |
+| Native `*_total_cost` / `current_ladder` | may stay `unknown` (CSG marketing calendar SQL error); dashboard uses template `_2` / `*_ladder_cost` |
+
+`monetary` + `total_increasing` warnings on this-month/year cost sensors
+are a remaining plugin issue, not an install failure.
+
+There is no long-lived `HA_TOKEN` in the agent environment. Read entity
+states via Supervisor (`SUPERVISOR_TOKEN` after `sudo -n -i`) at
+`http://supervisor/core/api/states/<entity_id>`.
+
 ## Command families intentionally NOT scripted

 These exist in `ha` but are either rare, dangerous, or better done in the web
@@ -186,17 +302,18 @@ host for exact syntax.

 The [official HAOS common-tasks docs](https://www.home-assistant.io/common-tasks/os/)
 reference `ha backups list` and `ha host update`. **Neither exists in the
-installed CLI** (2026-08-13): backups are inspected with `ha backups info
+installed CLI** (2026-08-14): backups are inspected with `ha backups info
 <slug>` (a slug is required) and `host` has no `update` subcommand. Trust the
 server CLI (`ha <cmd> --help`) over the docs.

-## Known issues on hass.windy.lan (2026-08-13)
+This CLI's `ha core info` also has no `state:` field (verified 2026-08-14).
+Wait for a successful info dump after restart, not a `state: running` line.

-All items from the original 2026-08-13 health snapshot were resolved same day
-(W1N-70/71/72/73/74/75/76): OTBR and the duplicate SSH add-on uninstalled, all
-resolution-center issues cleared (`ha resolution info` → empty), full backup
-`pre-maintenance-20260813` (slug `411a4ba5`) taken. Remaining known issues
-(documented in [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md)):
+## Known issues on hass.windy.lan (2026-08-14)
+
+2026-08-13 snapshot items were resolved same day (W1N-70/71/72/73/74/75/76):
+OTBR and the duplicate SSH add-on uninstalled, resolution-center empty,
+full backup `pre-maintenance-20260813` (slug `411a4ba5`). Remaining:

 - **Bluetooth hci0 instability (RTL8821CS)**: `bluetooth_auto_recovery`
  power-reset times out every ~2 min; kernel `hci0 hardware error`. No BLE
@@ -204,6 +321,19 @@ resolution-center issues cleared (`ha resolution info` → empty), full backup
  workaround units.
 - `host info` reports `disk_life_time: 10` (boot eMMC ~10% life left) —
  monitor on each snapshot; plan disk replacement / data-disk migration.
+- **Home PPPoE IPv4 to CSG is blackholed** (`curl -4` to
+  `218.19.148.218:443` times out). `end1` IPv6 works (`curl -6
+  https://95598.csg.cn` → HTTP 200). Entry `ip_family: ipv4` still
+  matches the stored option; first post-restart poll can still time out
+  — reload the config entry rather than reinstalling.
+- **WSL HTTP proxy**: LAN `hass.windy.lan:8123` through Mihomo returns
+  empty `502`. Bypass proxy or add `.windy.lan` to `NO_PROXY` before
+  debugging UI/API from the workstation
+  ([hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md) § HTTP proxy
+  gotcha).
+- **No long-lived HA token in the agent environment.** Read entity
+  states via Supervisor (`SUPERVISOR_TOKEN` after `sudo -n -i`) at
+  `http://supervisor/core/api/states/...`, not a committed `HA_TOKEN`.

 ## Pass criteria

@@ -211,4 +341,7 @@ resolution-center issues cleared (`ha resolution info` → empty), full backup
 - Mutating modes refuse to run without `--yes` (incl. `--restore`, `--app`)
 - `--check-config` returns success
 - Update / rollback / restore / reboot confirmed only after explicit `--yes`
+- Custom-component zip install: live `manifest.json` version matches the
+  tag; backups not under `custom_components/`; Core restarted; logs show
+  `Setting up <domain>` without import / pickle errors
 - Update the **Verified** line on [hosts/hass.windy.lan.md](../hosts/hass.windy.lan.md)