feat: node updates by restart, auto by default; Podman Quadlet install from the panel alongside compose [CI]

docs/ops/deployment.md

@@ -219,11 +219,32 @@ OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 2
 
 这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。
 
-## 容器部署（Docker / Podman 共用命名 volume）
+## 容器部署（Podman Quadlet 优先，Docker 用 compose）
 
-镜像和 Compose 配置共用。普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `moshiro-agent-config`，Probe 保存在 `moshiro-probe-config`，更新状态使用独立的 `moshiro-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要使用 `compose down -v`，该参数会删除数据。
+普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `moshiro-agent-config`，Probe 保存在 `moshiro-probe-config`，更新状态使用独立的 `moshiro-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要删除这些 volume（`podman volume rm`），会丢身份和配置。
 
-**compose 安装（Agent 和 Probe，推荐）**：管理端「添加 Agent」「添加 Probe」生成加入令牌之后，给出一段命令（面板地址、一次性码、信任根指纹和属主都是公开的值，没有私钥）：建一个目录，把参数写进 `.env`（权限 600），下载面板提供的静态 compose 文件、核对 SHA-256，一致才启动：
+**Quadlet 安装（Agent 和 Probe，Podman 系优先，Linux + Podman 4.6 及以上）**：管理端「添加 Agent」「添加 Probe」生成加入令牌之后，第一条命令就是它（面板地址、一次性码、信任根指纹和属主都是公开的值，没有私钥）：写 env（权限 600）、从面板下载静态的 Quadlet 单元并核对 SHA-256、用一个 drop-in 把镜像仓库指向面板配置的、启动用户服务：
+
+```sh
+mkdir -p ~/.config/moshiro ~/.config/containers/systemd/moshiro-probe.container.d && cat > ~/.config/moshiro/probe.env <<'EOF'
+MOSHIRO_SERVER=https://panel.example.com
+MOSHIRO_JOIN=jt_…
+MOSHIRO_GENESIS=…
+MOSHIRO_CONTROLLERS=…
+# MOSHIRO_UPDATE_POLICY=manual
+EOF
+chmod 600 ~/.config/moshiro/probe.env && curl -fsSL 'https://panel.example.com/install/quadlet/probe.container' -o "$HOME/.config/containers/systemd/moshiro-probe.container" && echo "<sha256>  $HOME/.config/containers/systemd/moshiro-probe.container" | sha256sum -c - && printf '[Container]\nImage=registry.oeo.one/moshiro/moshiro-probe:latest\n' > ~/.config/containers/systemd/moshiro-probe.container.d/10-image.conf && systemctl --user daemon-reload && systemctl --user start moshiro-probe
+```
+
+- 单元是静态的（`packaging/quadlet/moshiro-agent.container`、`moshiro-probe.container`，作为嵌入资源打进 Backend，由 `/install/quadlet/{agent,probe}.container` 原样提供，不含任何一次性的值）。镜像仓库不写死在单元里，由命令里的 drop-in 指定，来自面板的 `MoShiro__NodeImageRegistry` 和 `MoShiro__ImageNamespace`（默认 `registry.oeo.one/moshiro`，开发镜像 `moshiro-dev`）。
+- 只读根文件系统、丢掉全部能力、`no-new-privileges`、命名卷；用宿主网络（Agent 对外暴露端口，也靠它识别本机公网地址），并只读挂载 `/proc`、`/sys`、`/` 读主机指标。
+- 身份和配置在命名卷 `moshiro-<role>-config` 里：镜像入口脚本（`packaging/container/entrypoint.sh`）第一次启动用 `MOSHIRO_SERVER`、`MOSHIRO_JOIN`（和信任根指纹、属主）注册并写配置，之后重启、换新镜像重建容器都不需要再给参数，所以注册成功之后可以把 env 里的 `MOSHIRO_JOIN` 删掉。缺了信任根指纹或属主就不注册（只有还没有信任根的老面板才用 `MOSHIRO_ALLOW_NO_OWNER=1`）。
+- 开机自启：单元的 `[Install]` 已经写了，退出登录后继续运行需要管理员执行一次 `loginctl enable-linger <用户>`。
+- **更新**：见下一节，默认自动。想固定版本，把 drop-in 里的 `:latest` 换成版本号。回滚就是改回旧版本再 `systemctl --user restart moshiro-<role>`。
+- **信任**：和之前一样信任镜像仓库（Podman 校验它的 TLS 证书），面板被攻破也改不了镜像地址，因为单元和命令都有哈希；节点不验发布签名。
+- 没有 Podman 4.6 或不是 Linux：用下面的 compose（Docker）、一行安装脚本或发布的二进制。
+
+**compose 安装（Agent 和 Probe，Docker；Podman 系请优先用上面的 Quadlet）**：管理端「添加 Agent」「添加 Probe」生成加入令牌之后，给出一段命令（面板地址、一次性码、信任根指纹和属主都是公开的值，没有私钥）：建一个目录，把参数写进 `.env`（权限 600），下载面板提供的静态 compose 文件、核对 SHA-256，一致才启动：
 
 ```sh
 mkdir -p moshiro-probe && cd moshiro-probe && cat > .env <<'EOF'
@@ -241,7 +262,7 @@ chmod 600 .env && curl -fsSL 'https://panel.example.com/install/compose/probe.ya
 - 身份和配置在命名卷 `moshiro-<role>-config` 里：镜像入口脚本（`packaging/container/entrypoint.sh`）第一次启动用 `MOSHIRO_SERVER`、`MOSHIRO_JOIN`（和信任根指纹、属主）注册并写配置，之后重启、换新镜像重建容器都不需要再给参数，所以注册成功之后可以把 `.env` 里的 `MOSHIRO_JOIN` 删掉。缺了信任根指纹或属主就不注册（只有还没有信任根的老面板才用 `MOSHIRO_ALLOW_NO_OWNER=1`）。
 - Podman 的开机自启要靠 `podman-restart.service`（`systemctl enable --now podman-restart`；rootless 用 `--user`，并 `loginctl enable-linger`）；Docker 用 compose 里的 `restart: unless-stopped`。
 - **更新**：`podman compose pull && podman compose up -d`（Docker 用 `docker compose`），只重建镜像变了的容器，身份和配置不动，节点几十秒内重连。想固定版本，在 `.env` 里写 `MOSHIRO_VERSION=0.3.3`；想要更严，写成 `MOSHIRO_VERSION=0.3.3@sha256:<digest>`，digest 取自面板信任页或签名清单（那里有发布签名）。回滚就是改回旧版本再 `up -d`。
-- **信任**：compose 来自面板或 CI 渠道，面板被攻破也改不了镜像地址；但客户端不再验发布签名，拉取靠 TLS 加「注册表可信」这个假设（文档里本来就把 CI、Gitea、注册表放在可信范围内）。这条路没有管理端的「更新」列和确认更新按钮，那些依赖宿主机更新器；要有签名验证的更新，用下面的部署脚本。
+- **信任**：compose 来自面板或 CI 渠道，面板被攻破也改不了镜像地址；但客户端不再验发布签名，拉取靠 TLS 加「注册表可信」这个假设（文档里本来就把 CI、Gitea、注册表放在可信范围内）。compose 不会自动更新（见下节），也没有管理端的「更新」列和确认更新按钮。
 
 **一行安装脚本（备用，Docker 或 Podman，Agent 和 Probe 共用）**：管理端的弹窗里折叠着一条旧的一行命令，先核对脚本哈希再执行，脚本向面板取签名清单、用内置发布公钥验签、按 digest 拉镜像：
 
@@ -253,7 +274,7 @@ f=$(mktemp) && curl -fsSL 'https://panel.example.com/install' -o "$f" && echo "<
 
 脚本是静态的（`packaging/install/install.sh` 和 `install.ps1`，嵌入 Backend，不替换任何值），所以它的 SHA-256 在一个版本内固定；角色、面板地址、代码和属主走环境变量。环境变量 `MOSHIRO_NAME`、`MOSHIRO_ENGINE=docker|podman`、`MOSHIRO_DRY_RUN=1`（只打印 run 命令）；Podman 会顺便启用 `podman-restart`。
 
-**用脚本部署和更新（rootful Podman 或 Docker，推荐）**：`packaging/container/deploy-node.sh` 可以重复运行，每次都会拉取镜像并固定到 digest、把配置迁移到当前版本需要的样子（例如旧的 `listen.bind` 为 `0.0.0.0` 的 Agent 改成 `::`，这样 IPv6 线路才能建立）、重装单元和更新器，然后重启节点；已有的身份不会动，更新策略沿用上次的。
+**用脚本部署和更新（Backend；Agent 和 Probe 请用 Quadlet）**：`packaging/container/deploy-node.sh` 可以重复运行，每次都会拉取镜像并固定到 digest、把配置迁移到当前版本需要的样子（例如旧的 `listen.bind` 为 `0.0.0.0` 的 Agent 改成 `::`，这样 IPv6 线路才能建立）、重装单元和更新器，然后重启节点；已有的身份不会动，更新策略沿用上次的。
 
 ```sh
 # 首次部署（需要 root；脚本和 packaging/ 里的 systemd/、update/ 放在一起）
@@ -270,13 +291,13 @@ sudo sh deploy-node.sh backend --channel dev --public-url https://<面板域名>
 sudo sh deploy-node.sh agent
 ```
 
-Agent 的 `public_host` 和 `ipv6_host` 由 Agent 上报自动识别（需要宿主网络，脚本和 Compose 默认如此，监听 `::`），IPv6 不用额外配置。
+Agent 的 `public_host` 和 `ipv6_host` 由 Agent 上报自动识别（需要宿主网络，Quadlet 单元和一行安装脚本默认如此，监听 `::`），IPv6 不用额外配置。
 
-纯 Compose 使用 `compose pull && compose up -d` 更新镜像；面板自动更新使用下述 systemd 单元和更新器。Rootless Podman 使用 `moshiro-<role>-rootless.service`，安装到 `~/.config/systemd/user/`，镜像文件为 `~/.config/moshiro/<role>.image`；rootful Podman 使用 `moshiro-<role>-container.service`，Docker 使用 `moshiro-<role>-docker.service`，安装到 `/etc/systemd/system/`，镜像文件为 `/etc/moshiro-update/<role>.image`。所有单元均使用相同的配置和状态 volume 名称。自动启动分别使用 `systemctl --user enable --now <unit>` 或 `sudo systemctl enable --now <unit>`。Rootless 在退出登录后继续运行需管理员执行一次 `loginctl enable-linger <用户名>`。
+更新见「Podman（Quadlet）节点的更新」：节点退出再被拉起就是更新，默认自动。
 
 Backend 用 `packaging/compose/backend/compose.yaml`（见上文「Backend 容器」），数据库和原始数据在命名卷 `moshiro-backend-data` 里。首次安装 Podman 与用户 subuid/subgid 映射需要管理员权限，之后普通用户运行无需 sudo。
 
-已在 Fedora CoreOS 的 SELinux Enforcing 环境、Podman 6.0.2 rootless 下用同一份 Compose 实测：Agent 注册、宿主指标、Probe 登录和 TLS 连接正常，IPv4/IPv6 ICMP 目标任务收到有效回包，容器保持 `cap_drop: ALL`，未添加 NET_RAW。Linux ICMP 优先使用 datagram ping socket，不依赖外部 ping 程序；需要 `net.ipv4.ping_group_range` 包含容器映射后的 GID（测试环境为 `0 2147483647`）。宿主禁止普通用户 ping 时，需管理员配置该范围；例如 rootful Docker 的用户 GID 1654 可设置 `sysctl -w "net.ipv4.ping_group_range=1654 1654"`。rootless 应使用映射后的宿主 GID，不能直接套用容器 GID。单加 `cap_add: NET_RAW` 不保证非 root 用户获得有效 capability。有原始套接字权限的部署仍保留原有 Ping 回退路径。其他操作系统继续使用 System.Net.Ping。ICMP 目标任务当前由 Agent 执行，Probe 没有独立目标任务入口。
+已在 Fedora CoreOS 的 SELinux Enforcing 环境、Podman 6.0.2 rootless 下用同一套加固设置实测：Agent 注册、宿主指标、Probe 登录和 TLS 连接正常，IPv4/IPv6 ICMP 目标任务收到有效回包，容器保持 `cap_drop: ALL`，未添加 NET_RAW。Linux ICMP 优先使用 datagram ping socket，不依赖外部 ping 程序；需要 `net.ipv4.ping_group_range` 包含容器映射后的 GID（测试环境为 `0 2147483647`）。宿主禁止普通用户 ping 时，需管理员配置该范围；例如 rootful Docker 的用户 GID 1654 可设置 `sysctl -w "net.ipv4.ping_group_range=1654 1654"`。rootless 应使用映射后的宿主 GID，不能直接套用容器 GID。单加 `cap_add: NET_RAW` 不保证非 root 用户获得有效 capability。有原始套接字权限的部署仍保留原有 Ping 回退路径。其他操作系统继续使用 System.Net.Ping。ICMP 目标任务当前由 Agent 执行，Probe 没有独立目标任务入口。
 
 ### 定时重启
 
@@ -289,7 +310,7 @@ Agent 和 Probe 每天固定时刻有序退出一次，由服务管理器拉起
 
 ### Agent 的系统指标挂载
 
-Agent 的 Compose 模板已经包含以下只读挂载和环境变量，systemd 示例也采用相同配置：
+Agent 的 Quadlet 单元已经包含以下只读挂载和环境变量：
 
 | 宿主来源 | 容器路径 | 配置 | 指标 |
 | --- | --- | --- | --- |
@@ -302,9 +323,30 @@ Agent 的 Compose 模板已经包含以下只读挂载和环境变量，systemd
 
 磁盘指标是根文件系统容量，不是所有硬盘合计，也不采集磁盘 I/O。链路速率是参与流量统计的接口速率合计，单位 Mbit/s，不是互联网测速结果；任一接口不支持读取速率时显示空值。接口仍按名称排除回环、容器、网桥和部分隧道，复杂 bonding/VLAN 配置可能存在重复计数。主机名、硬件型号、MAC/IP 不作为资源指标上报。
 
-Probe 也上报同样的汇总数字（`probe.json` 的 `reporting.host_stats` 默认开，设为 `false` 就一个字也不上报，同时可以去掉 `/proc`、`/sys`、`/` 这三个挂载），所以 Probe 的 compose 和 Agent 一样挂载它们并设置 `HOST_*` 环境变量。Docker Desktop（macOS、Windows）上读到的是 Docker 的虚拟机，不是宿主系统本身；Windows 上直接运行的 Probe 和 Agent 用系统调用读 CPU、内存和物理网卡的流量（不读网卡名和地址）；macOS 目前只有磁盘和运行时长。
+Probe 也上报同样的汇总数字（`probe.json` 的 `reporting.host_stats` 默认开，设为 `false` 就一个字也不上报，同时可以去掉 `/proc`、`/sys`、`/` 这三个挂载），所以 Probe 的 Quadlet 单元和 Agent 一样挂载它们并设置 `HOST_*` 环境变量。Docker Desktop（macOS、Windows）上读到的是 Docker 的虚拟机，不是宿主系统本身；Windows 上直接运行的 Probe 和 Agent 用系统调用读 CPU、内存和物理网卡的流量（不读网卡名和地址）；macOS 目前只有磁盘和运行时长。
 
-## 容器节点的更新（Agent、Probe）
+## Podman（Quadlet）节点的更新（Agent、Probe，推荐）
+
+节点跑成一个 Podman Quadlet 单元（`packaging/quadlet/moshiro-agent.container`、`moshiro-probe.container`，Podman 4.6 及以上），更新是**销毁容器、重新拉最新镜像再启动**：节点自己不下载、不替换任何东西，只是有序退出；Quadlet 生成的 systemd 服务用 `podman run --pull always` 启动，所以被拉起时先从镜像仓库拉最新的镜像。**默认自动更新**：面板发现新版本后，节点运行满 10 分钟（防止重启循环）就自己退出重启；想改成在管理端点「更新」才更新，在 env 文件里写 `MOSHIRO_UPDATE_POLICY=manual`。
+
+```text
+CI 推镜像到 registry ─▶ 面板收到 CI 签名的清单 ─▶ 转发给节点（只是「建议」）
+节点：比对清单和自己的版本 ─▶ 心跳报「有新版本」─▶ 管理端显示
+自动（默认）：节点运行满 10 分钟 ─▶ 有序退出；手动（MOSHIRO_UPDATE_POLICY=manual）：管理员点「更新」─▶ 面板请求 ─▶ 节点有序退出
+然后：systemd 重启单元（Pull=always）─▶ 新镜像、新容器
+```
+
+- **安装**（rootless，普通用户）：管理端「添加 Agent / Probe」的第一条命令（Linux + Podman）就是它：env 写进 `~/.config/moshiro/<role>.env`（权限 600），从面板的 `/install/quadlet/<role>.container` 下载单元并核对 SHA-256，用一个 drop-in 把镜像仓库指向面板配置的（开发通道是 `moshiro-dev`），`systemctl --user start`。再让管理员执行一次 `loginctl enable-linger <用户>`。rootful 的路径和改法写在模板开头的注释里。身份和配置仍在命名卷 `moshiro-<role>-config`，换新镜像不丢。
+- **compose 不能自动更新**：compose 的 `restart: unless-stopped` 是引擎直接重启同一个容器，不会拉新镜像（`pull_policy: always` 只在 `compose up` 时生效），容器自己又没法重建自己，所以 compose（Docker）仍是手动 `compose pull && compose up -d`；要自动更新就用 Quadlet。
+- **信任**：信任镜像仓库（`registry.oeo.one`，Podman 校验它的 TLS 证书），并按标签拉取（默认 `latest`，想固定版本就把模板里的标签换成版本号）。节点不验证清单：它不安装任何东西，最多被管理员请求一次重启，和定时重启是同一种能力。
+- **只有设了 `MOSHIRO_UPDATE=restart` 的节点才报告更新状态**（模板里写好了）：别的部署方式退出之后不会重新拉取，开了也不会更新。
+- **别的自动更新方式**：另外启用 `podman-auto-update.timer` 并在模板的 `[Container]` 里加 `AutoUpdate=registry`，Podman 按计划比对镜像 digest 并重启，不依赖面板。
+- **回滚**：新镜像起不来时 systemd 一直重试；把模板里的标签改回旧版本再 `systemctl --user restart` 即可。
+- 测试：`packaging/quadlet` 里的模板用 `/usr/libexec/podman/quadlet -dryrun -user` 检查过（Podman 5.4）；节点一侧的逻辑见 `RestartUpdaterTests`。
+
+## 宿主机更新器（Backend、一行脚本装的节点）
+
+节点的更新走上面的 Quadlet。下面的宿主机更新器现在只服务 Backend 和一行安装脚本装的节点，Backend 改成 Quadlet 之后会一并移除。
 
 更新器支持 rootless Podman 用户服务、rootful Podman 和 Docker 系统服务。配置、身份和更新请求通过命名 volume 传递，不需要指定宿主数据目录。短时辅助容器读取请求、写入独立状态 volume；辅助镜像必须已在本机拉取，更新器不会自动拉取辅助镜像。配置、公钥和已安装版本记录留在容器外。