feat: share named volumes across Docker and rootless Podman updates [CI]

docs/deployment.md

@@ -201,41 +201,28 @@ OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 2
 
 这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。
 
-## 容器节点的运行（podman + systemd）
+## 容器部署（Docker / Podman 共用命名 volume）
 
-Agent 和 Probe 推荐在宿主机上用 root 的 podman 加 systemd 运行，这样宿主机更新器（下一节）才能重启它们。以 Agent 为例（Probe 把名字和目录换成 `monitor-probe`，配置文件换成 `probe.json`）：
+镜像和 Compose 配置共用。普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `monitor-agent-config`，Probe 保存在 `monitor-probe-config`，更新状态使用独立的 `monitor-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要使用 `compose down -v`，该参数会删除数据。
 
-```ini
-# /etc/systemd/system/monitor-agent-container.service
-[Unit]
-Description=Monitor Agent (podman)
-After=network-online.target
-Wants=network-online.target
+在 `packaging/compose/agent` 下首次注册，并写配置（下列 `podman` 可替换为 `docker`）：
 
-[Service]
-EnvironmentFile=/etc/monitor-update/agent.image        # IMAGE=<仓库>@sha256:<digest>，更新器更新时改写它
-Restart=always
-RestartSec=5
-TimeoutStopSec=30
-ExecStartPre=-/usr/bin/podman rm -f monitor-agent
-ExecStart=/usr/bin/podman run --rm --name monitor-agent --network host --read-only --security-opt no-new-privileges --security-opt label=disable --cap-drop all --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 -v /etc/os-release:/etc/os-release:ro -v /proc:/host/proc:ro -v /sys:/host/sys:ro -v /:/host/root:ro -e HOST_PROC=/host/proc -e HOST_SYS=/host/sys -e HOST_ROOT=/host/root -v /opt/monitor/etc:/etc/monitor ${IMAGE}
-ExecStop=/usr/bin/podman stop -t 20 monitor-agent
-
-[Install]
-WantedBy=multi-user.target
+```sh
+podman compose run --rm --entrypoint /usr/local/bin/fleet-enroll agent \
+  --server https://<backend> --join <token> --name <name> --identity-dir /etc/monitor/agent-id
+podman compose run --rm -T --entrypoint /bin/sh agent -c 'cat > /etc/monitor/agent.json' <<'JSON'
+{"fleet":{"server":"https://<backend>","identity_dir":"/etc/monitor/agent-id"},"listen":{"bind":"0.0.0.0"}}
+JSON
+podman compose up -d
 ```
 
-- **数据目录**（上面挂到容器 `/etc/monitor` 的 `/opt/monitor/etc`）归容器用户（UID/GID 1654），里面放 `agent.json`、身份目录（`fleet-enroll` 注册之后的 `agent-id/`），Probe 放 `probe.json` 和 `agents.json`。`agent.json` 里的 `fleet.identity_dir` 写容器里的路径（例如 `/etc/monitor/agent-id`）。
-- **首次注册 Agent**：`sudo podman run --rm --network host --security-opt label=disable -v <数据目录>:/etc/monitor --entrypoint /usr/local/bin/fleet-enroll <镜像> --server https://<面板> --join <加入令牌> --name <名字> --identity-dir /etc/monitor/agent-id`，再写 `agent.json`。Probe：在管理端创建（或轮换密钥）之后下载 `probe.json`，放进数据目录。
-- **拉取私有镜像**需要 Registry 的登录信息：用 `podman login --authfile /etc/monitor-update/registry-auth.json …` 生成一份只有 root 能读（600）的认证文件，更新器用它拉取，容器本身用不到。
-- **挂载宿主机的 `/etc/os-release`（只读）**：节点读系统名展示在面板上，不挂的话读到的是镜像里的 Alpine。
-- **ICMP 目标任务**要在 `podman run` 里加 `--cap-add NET_RAW`。
-- **经隧道注册之后检查 Agent 的 `public_host`**：面板看到的来源地址是隧道的出口（通常是内网地址），要在管理端改成这台机器自己的公网地址（`PATCH /api/admin/agents/{id}`），Probe 才连得上。
-- `packaging/compose/` 里的 compose 文件可用 `sudo podman compose up -d` 或 `docker compose up -d`；Podman Compose 需要安装 Compose provider。更新靠手动改版本再 `sudo podman compose pull && sudo podman compose up -d`，面板的更新按钮对它不起作用。
+Probe 在 `packaging/compose/probe` 下，将面板下载的身份文件通过标准输入导入 volume：`podman compose run --rm -T --entrypoint /bin/sh probe -c 'umask 077; cat > /etc/monitor/probe.json' < probe.json`，再 `podman compose up -d`。私钥权限为 600。已有部署迁移时，应把原配置与身份原样复制进 volume，不重新注册或轮换密钥。Docker 与 Podman 各自管理 volume，切换引擎不会自动共享数据。
 
-### Podman 的宿主指标与权限
+纯 Compose 使用 `compose pull && compose up -d` 更新镜像；面板自动更新使用下述 systemd 单元和更新器。Rootless Podman 使用 `monitor-<role>-rootless.service`，安装到 `~/.config/systemd/user/`，镜像文件为 `~/.config/monitor/<role>.image`；rootful Podman 使用 `monitor-<role>-container.service`，Docker 使用 `monitor-<role>-docker.service`，安装到 `/etc/systemd/system/`，镜像文件为 `/etc/monitor-update/<role>.image`。所有单元均使用相同的配置和状态 volume 名称。自动启动分别使用 `systemctl --user enable --now <unit>` 或 `sudo systemctl enable --now <unit>`。Rootless 在退出登录后继续运行需管理员执行一次 `loginctl enable-linger <用户名>`。
 
-这里使用 Linux 上的 **rootful Podman**（`sudo podman`），容器内仍以 UID/GID 1654 运行。配置目录需由 1654 用户读写；`label=disable` 不会改变 Unix 文件权限。Rootless Podman 的 UID 映射不同，不能直接沿用 `chown 1654:1654` 的准备步骤。
+Backend 的 `packaging/compose/backend/compose.yaml` 使用 `monitor-backend-data` 保存数据库和原始数据，设置 `MONITOR_INITIAL_ADMIN_PASSWORD` 后即可启动。首次安装 Podman 与用户 subuid/subgid 映射需要管理员权限，之后普通用户运行无需 sudo。
+
+### Agent 的系统指标挂载
 
 Agent 的 Compose 模板已经包含以下只读挂载和环境变量，systemd 示例也采用相同配置：
 
@@ -252,29 +239,24 @@ Agent 的 Compose 模板已经包含以下只读挂载和环境变量，systemd
 
 Probe 保持现有功能，只上报系统、架构与节点状态，不上报 CPU、内存、磁盘或网卡指标。因此 Probe 的 Compose 模板只需要配置目录和 `/etc/os-release` 挂载；从 Agent systemd 示例改为 Probe 时，去掉 `/proc`、`/sys`、`/` 挂载及 `HOST_*` 环境变量。
 
-可直接安装的 unit 模板见 `packaging/systemd/monitor-agent-container.service` 和 `packaging/systemd/monitor-probe-container.service`；它们与上述示例使用相同策略，分别读取 `/etc/monitor-update/agent.image` 与 `probe.image`。在 Linux 虚拟机上运行容器时，采集对象是该 Linux 虚拟机。
-
 ## 容器节点的更新（Agent、Probe）
 
-面板通知、节点验签、宿主机更新，**面板即使被攻破也装不上假镜像**：
+更新器支持 rootless Podman 用户服务、rootful Podman 和 Docker 系统服务。配置、身份和更新请求通过命名 volume 传递，不需要指定宿主数据目录。短时辅助容器读取请求、写入独立状态 volume；辅助镜像必须已在本机拉取，更新器不会自动拉取辅助镜像。配置、公钥和已安装版本记录留在容器外。
 
-```text
-CI 构建并推镜像（Zot）──► ci/release-manifest.sh：对镜像 digest 的清单签名（ECDSA P-256，私钥只在 Woodpecker 密钥 release_signing_key 里）
-        └─ POST /api/admin/releases ──► 面板：只存下并原样转发（不验签）──► 在线的 Agent、Probe（连上时补发）
-                                            节点进程：只把清单和签名写进数据目录的 update/，不执行任何命令
-                                                 │ systemd.path 监视到 offer.sig
-                                                 ▼
-          宿主机 monitor-update（root）：复制到临时目录 → 用本机的发布公钥验签 → 核对组件和镜像仓库 → seq 必须比已安装的大
-                 → status：available / invalid（写进 update-status/，节点随心跳报给面板，管理端「版本」页显示）
-                 → 管理员点「更新」（或本机配置 POLICY=auto）→ podman pull <仓库>@sha256:<digest>（内容寻址，Registry 或链路上换不了）
-                 → 写 IMAGE=… 到 /etc/monitor-update/<组件>.image，重启容器单元；20 秒内没有健康就换回旧镜像（rolled_back）
+Rootless Podman 普通用户安装示例（先将对应 rootless 服务单元复制到用户 systemd 目录）：
+
+```sh
+sh packaging/update/install-updater.sh agent --user \
+  --volume monitor-agent-config --status-volume monitor-agent-status \
+  --helper-image registry.oeo.one/monitor/monitor-agent:<version> \
+  --image-repo registry.oeo.one/monitor/monitor-agent \
+  --unit monitor-agent-rootless.service --policy auto
 ```
 
-- **安装更新器**（每个容器节点一次，root）：`packaging/update/install-updater.sh agent --data-dir /opt/monitor/etc --image-repo registry.oeo.one/monitor/monitor-agent --unit monitor-agent-container.service [--policy auto] [--authfile <Registry 认证文件>]`。它装好 `monitor-update` 脚本和发布公钥，写 `/etc/monitor-update/<组件>.conf`，启用两个 systemd 路径单元。容器单元要用 `EnvironmentFile=/etc/monitor-update/<组件>.image` 和 `${IMAGE}` 启动容器。
-- **镜像仓库、服务名、公钥都在本机配置里**，清单里写什么都不会改变拉取哪个仓库；清单被篡改、签名对不上、组件或仓库不符、`seq` 不比已安装的大（重放旧清单），都会被拒绝，状态是 `invalid`。
-- **业务进程不能改二进制，也不执行命令**：它只能往 `update/` 里放清单和请求；状态在 root 拥有的 `update-status/` 里（只读）。
-- **CI 的配置**：Woodpecker 密钥 `release_signing_key`（发布私钥，PEM）、`release_api_token`（面板的 API 令牌，作用域 `release`，只能登记清单）；环境变量 `RELEASE_API_URL`（面板地址）。没有 `release_signing_key` 就只构建镜像、不发清单。
-- **管理端**：「系统 → 版本」页显示最新发布的 tag、每个节点的更新状态（已是最新、有新版本、更新中、已回滚、清单无效），有新版本的节点有「更新」按钮，也可以「全部更新」。更新策略在节点本机配置：`/etc/monitor-update/<组件>.conf` 里 `POLICY=manual`（默认，等管理员请求）或 `auto`（验签通过就更新）。
-- **发布公钥**在 `packaging/update/release-key.pub.pem`；私钥不入库，请离线备份。更换密钥：节点上换新公钥之后再用新私钥发布。
-- 纯二进制的安装方式（`fleet-updater`、`fleet-release`，见 [fleet/update.md](fleet/update.md)）还没有实现；容器方式优先。
+使用 Docker 时以管理员运行相同安装命令，去掉 `--user`，加 `--engine docker`，单元选择 `monitor-agent-docker.service`。rootful Podman 去掉 `--user`，单元选择 `monitor-agent-container.service`。Probe 替换角色名。初始化对应 `<role>.image` 为 `IMAGE=<当前镜像引用>` 后启动容器单元。辅助镜像可用本机已有的 digest 引用，避免标签变化。Docker rootless 更新尚未适配。
 
+命名 volume 的更新服务由 systemd timer 每 30 秒检查一次。`--policy auto` 验签后自动应用，默认 `manual` 等待面板写入应用请求。清单必须通过 ECDSA P-256 签名校验，组件、镜像仓库和递增 seq 都必须匹配本机配置；镜像按签名清单中的 digest 拉取。更新后观察服务 20 秒，启动失败或崩溃循环会恢复旧镜像引用并重启。无效签名、重放清单、拉取失败不会切换当前镜像。同一组件的更新通过 flock 串行处理。
+
+更新器依赖 Linux、systemd、OpenSSL、util-linux/flock 和所选引擎。用户部署把配置、公钥和镜像引用放在 `~/.config/monitor/`、版本记录放在 `~/.local/state/monitor-update/`；系统部署使用 `/etc/monitor-update/` 和 `/var/lib/monitor-update/`。私有仓库的 `--authfile` 对 Podman 使用其认证文件，对 Docker 使用标准 `config.json`，不改写全局 Docker 配置。旧 `--data-dir` 安装方式保留兼容，但新部署统一使用 `--volume`。
+
+发布私钥只放在 Woodpecker 的 `release_signing_key` secret；发布公钥位于 `packaging/update/release-key.pub.pem`。CI 的 `release_api_token` 只有发布登记权限，`RELEASE_API_URL` 指向面板。面板保存并转发签名清单，Agent/Probe 将它与更新请求写进配置 volume；更新器验签后才调用容器引擎和 systemd。管理端仍能看到可更新、更新中、已回滚和无效清单状态。纯二进制更新器尚未实现。