justme/MoShiro
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

refactor!: rename the project from Monitor to MoShiro [CI]
ci/woodpecker/push/main-amd64-build Pipeline was successful
Details

Browse Source 
Namespaces, assemblies, solution, binaries, images, systemd units, config paths, environment variables, protocol methods and the Linux user are all renamed. Breaking: existing databases, node identities and installed units must be recreated.
This commit is contained in:
justme committed 2026-10-07 02:03:25 +08:00
1 parent 27ac7fb787
commit 2e146d4da7
309 files changed
+1565 -1572
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/deployment.md
+47 -47
View File
@@ -6,10 +6,10 @@
```text
scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid> → backend/artifacts/publish/<project>/<rid>/
scripts/package.sh <agent|probe> <rid> → backend/artifacts/packages/monitor-<role>-<version>-<rid>.tar.gz（附 .sha256）
scripts/package.sh <agent|probe> <rid> → backend/artifacts/packages/moshiro-<role>-<version>-<rid>.tar.gz（附 .sha256）
```
构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MONITOR_TAG`、`MONITOR_COMMIT`、`MONITOR_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器镜像的 `*.NativeBuild.Containerfile` 用同名的 `--build-arg`，CI 脚本会传）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`）。
构建信息（程序里显示的 tag、提交、构建时间）：`publish.sh` 会用 `git describe --tags --always --dirty`、`git rev-parse` 和当前时间自动设置环境变量 `MOSHIRO_TAG`、`MOSHIRO_COMMIT`、`MOSHIRO_BUILT_AT`，直接用 `dotnet publish` 或 CI 构建时自己设置它们（容器镜像的 `*.NativeBuild.Containerfile` 用同名的 `--build-arg`，CI 脚本会传）；不设置就是空，本地构建照常可重复。版本号取自 `backend/Directory.Build.props` 的 `Version`。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`）。
| rid | 目标 | 构建方式 |
| --- | --- | --- |
@@ -24,15 +24,15 @@ macOS 的 Apple Silicon 产物带临时 ad-hoc 签名，Intel 产物未签名。
## Backend 容器
Backend 使用 OCI 标准镜像，通过 `registry.oeo.one/monitor/monitor-backend:<version>` 分发，支持 `linux/amd64` 和 `linux/arm64`。容器使用 musl NativeAOT 单文件程序，基底为 `mcr.microsoft.com/dotnet/runtime-deps:10.0-alpine`，以非 root 用户运行，在 `8080/tcp` 提供 HTTP 服务；数据库和原始数据统一写入 `/data`。程序启用 InvariantGlobalization，无需 .NET 运行时或 ICU；时间查询使用 UTC。SQLite 从固定版本的官方源码编译并静态链接，不再随镜像携带 `libe_sqlite3.so`。将 `/data` 挂载为持久卷，并在反向代理处配置 HTTPS。
Backend 使用 OCI 标准镜像，通过 `registry.oeo.one/moshiro/moshiro-backend:<version>` 分发，支持 `linux/amd64` 和 `linux/arm64`。容器使用 musl NativeAOT 单文件程序，基底为 `mcr.microsoft.com/dotnet/runtime-deps:10.0-alpine`，以非 root 用户运行，在 `8080/tcp` 提供 HTTP 服务；数据库和原始数据统一写入 `/data`。程序启用 InvariantGlobalization，无需 .NET 运行时或 ICU；时间查询使用 UTC。SQLite 从固定版本的官方源码编译并静态链接，不再随镜像携带 `libe_sqlite3.so`。将 `/data` 挂载为持久卷，并在反向代理处配置 HTTPS。
在部署目录保存此仓库的 `compose.yaml`，先通过部署平台的环境变量或密钥管理设置 `MONITOR_ADMIN_PASSWORD`（可选设置 `MONITOR_ADMIN_USER`、`MONITOR_VERSION`），然后启动：
在部署目录保存此仓库的 `compose.yaml`，先通过部署平台的环境变量或密钥管理设置 `MOSHIRO_ADMIN_PASSWORD`（可选设置 `MOSHIRO_ADMIN_USER`、`MOSHIRO_VERSION`），然后启动：
```sh
docker compose up -d
```
Compose 将容器端口只绑定到宿主机 `127.0.0.1:8080`，适合由同机 HTTPS 反向代理转发；数据保存在 Docker 命名卷 `monitor-data`。首次启动成功创建管理员后，改密应在管理端完成。
Compose 将容器端口只绑定到宿主机 `127.0.0.1:8080`，适合由同机 HTTPS 反向代理转发；数据保存在 Docker 命名卷 `moshiro-data`。首次启动成功创建管理员后，改密应在管理端完成。
Backend 的 NativeAOT 发布默认启用 `SqliteStaticLink`，支持 Linux glibc/musl、macOS、Windows 的 x64/arm64 RID；跨平台构建使用 `-p:UseAotAnywhere=true`。SQLite 源码版本、下载年份和 SHA-256 统一配置在根目录 `Directory.Packages.props`，构建会校验下载文件并按 RID 缓存原生对象。普通 JIT 开发构建仍使用 NuGet 原生库。发布 Backend 时设置 `-p:OpenApiGenerateDocuments=false`，API 文档在普通开发构建中生成。
@@ -50,30 +50,30 @@ Pull request 和 `dev` push 会运行 Backend tests；通过后，独立的 `web
### main 开发镜像
`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `monitor-dev/` 仓库：
`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `moshiro-dev/` 仓库：
| 镜像 | 滚动标签 | 固定提交标签 |
| --- | --- | --- |
| Backend | `registry.oeo.one/monitor-dev/monitor-backend:latest` | `registry.oeo.one/monitor-dev/monitor-backend:dev-<12位SHA>` |
| Agent | `registry.oeo.one/monitor-dev/monitor-agent:latest` | `registry.oeo.one/monitor-dev/monitor-agent:dev-<12位SHA>` |
| Probe | `registry.oeo.one/monitor-dev/monitor-probe:latest` | `registry.oeo.one/monitor-dev/monitor-probe:dev-<12位SHA>` |
| Backend | `registry.oeo.one/moshiro-dev/moshiro-backend:latest` | `registry.oeo.one/moshiro-dev/moshiro-backend:dev-<12位SHA>` |
| Agent | `registry.oeo.one/moshiro-dev/moshiro-agent:latest` | `registry.oeo.one/moshiro-dev/moshiro-agent:dev-<12位SHA>` |
| Probe | `registry.oeo.one/moshiro-dev/moshiro-probe:latest` | `registry.oeo.one/moshiro-dev/moshiro-probe:dev-<12位SHA>` |
Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `monitor/` 仓库中的标签。普通 main push 不会构建镜像。
Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。
### 正式版发布
推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/monitor/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `monitor-dev/` 的 dev `latest` 相互独立。
推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/moshiro/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `moshiro-dev/` 的 dev `latest` 相互独立。
Agent 和 Probe 镜像分别发布为 `registry.oeo.one/monitor/monitor-agent:<version>` 与 `registry.oeo.one/monitor/monitor-probe:<version>`，包含 amd64、arm64 多架构索引；也可指定 `:<version>-amd64` 或 `:<version>-arm64`。稳定版本同时更新 `latest`。镜像以非 root 用户（UID/GID 1654）运行，默认读取 `/etc/monitor/agent.json` 或 `/etc/monitor/probe.json`。运行容器时挂载对应配置目录；Probe 还会在该目录写入 `agents.json`，因此目录需可由 1654 用户写入。Agent、Probe 需使用宿主网络以保持节点端口和测量流量行为，并按需添加 `NET_RAW` 能力以执行 ICMP 测量：
Agent 和 Probe 镜像分别发布为 `registry.oeo.one/moshiro/moshiro-agent:<version>` 与 `registry.oeo.one/moshiro/moshiro-probe:<version>`，包含 amd64、arm64 多架构索引；也可指定 `:<version>-amd64` 或 `:<version>-arm64`。稳定版本同时更新 `latest`。镜像以非 root 用户（UID/GID 1654）运行，默认读取 `/etc/moshiro/agent.json` 或 `/etc/moshiro/probe.json`。运行容器时挂载对应配置目录；Probe 还会在该目录写入 `agents.json`，因此目录需可由 1654 用户写入。Agent、Probe 需使用宿主网络以保持节点端口和测量流量行为，并按需添加 `NET_RAW` 能力以执行 ICMP 测量：
```sh
docker run -d --name monitor-agent --restart unless-stopped --network host \
--cap-add NET_RAW -v "$PWD/agent-config:/etc/monitor" \
registry.oeo.one/monitor/monitor-agent:<version>
docker run -d --name moshiro-agent --restart unless-stopped --network host \
--cap-add NET_RAW -v "$PWD/agent-config:/etc/moshiro" \
registry.oeo.one/moshiro/moshiro-agent:<version>
docker run -d --name monitor-probe --restart unless-stopped --network host \
--cap-add NET_RAW -v "$PWD/probe-config:/etc/monitor" \
registry.oeo.one/monitor/monitor-probe:<version>
docker run -d --name moshiro-probe --restart unless-stopped --network host \
--cap-add NET_RAW -v "$PWD/probe-config:/etc/moshiro" \
registry.oeo.one/moshiro/moshiro-probe:<version>
```
宿主机配置目录应允许 UID/GID 1654 读写；Probe 需要写权限来更新 `agents.json`。也可通过 Docker Compose 配置相同的网络、卷和能力。
@@ -86,8 +86,8 @@ Agent 和 Probe 的默认发布配置：NativeAOT、完整裁剪、`Optimization
| 程序 | linux-musl-x64 | linux-x64 | win-x64 |
| --- | --- | --- | --- |
| monitor-probe | 7.7 MB | 7.7 MB | 5.6 MB |
| monitor-agent | 8.4 MB | 8.4 MB | 7.3 MB |
| moshiro-probe | 7.7 MB | 7.7 MB | 5.6 MB |
| moshiro-agent | 8.4 MB | 8.4 MB | 7.3 MB |
| fleet-enroll | 6.4 MB | 6.4 MB | — |
Linux 上比 Windows 大，是因为 .NET 的加密、压缩、网络本机库被静态链接进来。tar.gz 压缩后 Probe 约 3.6 MB。
@@ -108,31 +108,31 @@ Linux 上比 Windows 大，是因为 .NET 的加密、压缩、网络本机库
| 位置 | 内容 | 所有者 |
| --- | --- | --- |
| `/usr/lib/monitor/` | 二进制 | root，0755：采集进程不能改写自己的可执行文件 |
| `/etc/monitor/` | `agent.json` 或 `probe.json`、身份（`node.json`、`node.key`、`tls.pfx`）、`agents.json` | `monitor` 用户，0750 |
| `/usr/lib/moshiro/` | 二进制 | root，0755：采集进程不能改写自己的可执行文件 |
| `/etc/moshiro/` | `agent.json` 或 `probe.json`、身份（`node.json`、`node.key`、`tls.pfx`）、`agents.json` | `moshiro` 用户，0750 |
安装脚本会：检查 OpenSSL、创建 `monitor` 用户（`useradd`、busybox `adduser`，OpenWrt 没有这些时直接写 `/etc/passwd`）、安装二进制和服务文件；缺少配置时只安装、不启动，并打印下一步。
安装脚本会：检查 OpenSSL、创建 `moshiro` 用户（`useradd`、busybox `adduser`，OpenWrt 没有这些时直接写 `/etc/passwd`）、安装二进制和服务文件；缺少配置时只安装、不启动，并打印下一步。
### systemd（`packaging/systemd/*.service`）
以 `monitor` 用户运行，沙箱：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、`PrivateTmp/Devices`、`ProtectKernel*`、`RestrictAddressFamilies=AF_INET AF_INET6`、`RestrictNamespaces`、`MemoryDenyWriteExecute`（NativeAOT 不 JIT）、`SystemCallArchitectures=native`，`MemoryMax`（Agent 128 MB、Probe 64 MB）。
以 `moshiro` 用户运行，沙箱：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、`PrivateTmp/Devices`、`ProtectKernel*`、`RestrictAddressFamilies=AF_INET AF_INET6`、`RestrictNamespaces`、`MemoryDenyWriteExecute`（NativeAOT 不 JIT）、`SystemCallArchitectures=native`，`MemoryMax`（Agent 128 MB、Probe 64 MB）。
- **Agent** 只保留 `CAP_NET_RAW`（ICMP 目标任务用），`/etc/monitor` 只读；Probe 没有任何 capability，只对 `agents.json` 所在的目录可写。
- **Agent** 只保留 `CAP_NET_RAW`（ICMP 目标任务用），`/etc/moshiro` 只读；Probe 没有任何 capability，只对 `agents.json` 所在的目录可写。
- 监听 1024 以下的端口（例如把数据面放到 443）需要在 drop-in 里加 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 和对应的 `CapabilityBoundingSet`。默认端口是 7443/tcp+udp（Probe 控制通道和 UDP 数据面）、7444/tcp。
### OpenWrt（`packaging/openwrt/`）
只支持 Probe（Agent 面向服务器）。`install.sh probe` 安装 `/etc/init.d/monitor-probe`（procd，崩溃自动重启，日志进 logd）并写入 `/lib/upgrade/keep.d/monitor`，sysupgrade 时保留 `/etc/monitor/`。
只支持 Probe（Agent 面向服务器）。`install.sh probe` 安装 `/etc/init.d/moshiro-probe`（procd，崩溃自动重启，日志进 logd）并写入 `/lib/upgrade/keep.d/moshiro`，sysupgrade 时保留 `/etc/moshiro/`。
OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 24.10 之后用 `apk add libopenssl3`）。闪存很小时注意：二进制 7.7 MB，配置只在 Agent 列表变化时才写。路由器上建议把 `probe.json` 的 `limits.max_test_mbps` 调低。
## 3. 验证
`scripts/smoke-linux.sh` 在 Linux 容器里用发布的二进制跑完整链路（后端 → 注册 → Agent → Probe → 数据落库），`MODE=install` 用打包产物和 `install.sh` 安装、以 `monitor` 用户运行。`scripts/smoke-systemd.sh` 在 systemd 容器里验证服务单元。已经验证过：
`scripts/smoke-linux.sh` 在 Linux 容器里用发布的二进制跑完整链路（后端 → 注册 → Agent → Probe → 数据落库），`MODE=install` 用打包产物和 `install.sh` 安装、以 `moshiro` 用户运行。`scripts/smoke-systemd.sh` 在 systemd 容器里验证服务单元。已经验证过：
- Alpine 3.22（musl）、Debian 12（glibc）：直接运行和 `install.sh` 安装都通；
- OpenWrt（官方 rootfs，busybox，无 `install`/`useradd`/`su`）：安装、建用户、卸载、二进制启动和 OpenSSL 自检；
- systemd（Debian 12）：两个服务 active，Agent 只有 `CAP_NET_RAW`、Probe 没有 capability，`NoNewPrivs`、seccomp 生效，Agent 无法写 `/etc/monitor`，没有重启和错误日志。
- systemd（Debian 12）：两个服务 active，Agent 只有 `CAP_NET_RAW`、Probe 没有 capability，`NoNewPrivs`、seccomp 生效，Agent 无法写 `/etc/moshiro`，没有重启和错误日志。
没有验证的：arm64 构建、真正的 OpenWrt 设备（有 procd 和真实的内存/闪存限制）、跨公网的真实线路。
@@ -172,20 +172,20 @@ OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 2
- **Backend 通过隧道暴露**：隧道把一个公网域名转到家宽机器的 `29181`；Backend 监听 `http://0.0.0.0:29181`（只写一个监听地址，同时写 `0.0.0.0` 和 `[::]` 会报地址已被占用），家宽路由器的防火墙不放行这个端口，公网只能经隧道进来。Agent 用 `fleet-enroll --server https://<公网域名>` 注册，之后用 WSS 连回 Backend。
- **经隧道注册之后，检查 Agent 的 `public_host`**：Backend 看到的来源地址是隧道的出口，不是 VPS 的地址，要改成 VPS 的真实地址，Probe 才连得上。
- **Probe 直连面板**：`probe.json` 里的 `server` 就是面板地址（取自 `Monitor__PublicUrl`，没配就用创建它时的请求地址），Probe 用它连面板，Agent 列表由面板下发；先注册还是先创建 Probe 都可以。
- **Probe 直连面板**：`probe.json` 里的 `server` 就是面板地址（取自 `MoShiro__PublicUrl`，没配就用创建它时的请求地址），Probe 用它连面板，Agent 列表由面板下发；先注册还是先创建 Probe 都可以。
- **小 VPS 把 `limits.max_total_mbps` 调低**（试跑时用 100）；Agent 常驻约 23 MB，VPS 上原有的服务不受影响，结束后删除 `/opt/…`、停掉进程即可，没有留下任何东西。
- 家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，SSH 地址要跟着换；面板走隧道的域名，不受影响。
- 本地电脑没有直连 VPS 的路径时，用家宽机器当跳板（`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force`，密码放环境变量，不写进文件）。
**常驻（开机自启）**：
- 家宽机器（没有 root 时）：`~/.config/systemd/user/monitor-backend.service` 和 `monitor-probe.service`，`EnvironmentFile` 指向放配置的 `backend.env`，`Restart=always`，`systemctl --user enable --now …`，再用 `sudo loginctl enable-linger <用户>` 让它们不登录也能起来。Probe 的命令行是 `monitor-probe --config <probe.json 路径>`（默认路径是 `/etc/monitor/probe.json`）。
- VPS：`/etc/systemd/system/monitor-agent.service`，`Restart=always`，加 `NoNewPrivileges`、`ProtectSystem=strict`、`ReadWritePaths=/opt/monitor`、`ProtectHome`、`PrivateTmp`。这是不走安装脚本的手动方式；正式安装用上面的 `packaging/systemd`。
- 日志进 journal：`journalctl -u monitor-agent`、`journalctl --user -u monitor-probe`。重启 Backend 用 `systemctl` 而不是手动再起一个进程，否则会端口冲突。
- 家宽机器（没有 root 时）：`~/.config/systemd/user/moshiro-backend.service` 和 `moshiro-probe.service`，`EnvironmentFile` 指向放配置的 `backend.env`，`Restart=always`，`systemctl --user enable --now …`，再用 `sudo loginctl enable-linger <用户>` 让它们不登录也能起来。Probe 的命令行是 `moshiro-probe --config <probe.json 路径>`（默认路径是 `/etc/moshiro/probe.json`）。
- VPS：`/etc/systemd/system/moshiro-agent.service`，`Restart=always`，加 `NoNewPrivileges`、`ProtectSystem=strict`、`ReadWritePaths=/opt/moshiro`、`ProtectHome`、`PrivateTmp`。这是不走安装脚本的手动方式；正式安装用上面的 `packaging/systemd`。
- 日志进 journal：`journalctl -u moshiro-agent`、`journalctl --user -u moshiro-probe`。重启 Backend 用 `systemctl` 而不是手动再起一个进程，否则会端口冲突。
**国家和运营商**：Backend 用 Probe、Agent 的来源地址向 IP 归属服务查一次，展示在国旗和运营商图标上（`Monitor__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
**国家和运营商**：Backend 用 Probe、Agent 的来源地址向 IP 归属服务查一次，展示在国旗和运营商图标上（`MoShiro__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `Monitor__CorsOrigins` 放行前端的来源（见 [web/README.md](../web/README.md)）。
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `MoShiro__CorsOrigins` 放行前端的来源（见 [web/README.md](../web/README.md)）。
实测（Probe 在广东移动家宽，Agent 在日本 IIJ）：
@@ -203,24 +203,24 @@ OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 2
## 容器部署（Docker / Podman 共用命名 volume）
镜像和 Compose 配置共用。普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `monitor-agent-config`，Probe 保存在 `monitor-probe-config`，更新状态使用独立的 `monitor-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要使用 `compose down -v`，该参数会删除数据。
镜像和 Compose 配置共用。普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `moshiro-agent-config`，Probe 保存在 `moshiro-probe-config`，更新状态使用独立的 `moshiro-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要使用 `compose down -v`，该参数会删除数据。
在 `packaging/compose/agent` 下首次注册，并写配置（下列 `podman` 可替换为 `docker`）：
```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"}}
--server https://<backend> --join <token> --name <name> --identity-dir /etc/moshiro/agent-id
podman compose run --rm -T --entrypoint /bin/sh agent -c 'cat > /etc/moshiro/agent.json' <<'JSON'
{"fleet":{"server":"https://<backend>","identity_dir":"/etc/moshiro/agent-id"},"listen":{"bind":"0.0.0.0"}}
JSON
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，切换引擎不会自动共享数据。
Probe 在 `packaging/compose/probe` 下，将面板下载的身份文件通过标准输入导入 volume：`podman compose run --rm -T --entrypoint /bin/sh probe -c 'umask 077; cat > /etc/moshiro/probe.json' < probe.json`，再 `podman compose up -d`。私钥权限为 600。已有部署迁移时，应把原配置与身份原样复制进 volume，不重新注册或轮换密钥。Docker 与 Podman 各自管理 volume，切换引擎不会自动共享数据。
纯 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 <用户名>`。
纯 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 <用户名>`。
Backend 的 `packaging/compose/backend/compose.yaml` 使用 `monitor-backend-data` 保存数据库和原始数据，设置 `MONITOR_INITIAL_ADMIN_PASSWORD` 后即可启动。首次安装 Podman 与用户 subuid/subgid 映射需要管理员权限，之后普通用户运行无需 sudo。
Backend 的 `packaging/compose/backend/compose.yaml` 使用 `moshiro-backend-data` 保存数据库和原始数据，设置 `MOSHIRO_INITIAL_ADMIN_PASSWORD` 后即可启动。首次安装 Podman 与用户 subuid/subgid 映射需要管理员权限，之后普通用户运行无需 sudo。
### Agent 的系统指标挂载
@@ -247,16 +247,16 @@ Rootless Podman 普通用户安装示例（先将对应 rootless 服务单元复
```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
--volume moshiro-agent-config --status-volume moshiro-agent-status \
--helper-image registry.oeo.one/moshiro/moshiro-agent:<version> \
--image-repo registry.oeo.one/moshiro/moshiro-agent \
--unit moshiro-agent-rootless.service --policy auto
```
使用 Docker 时以管理员运行相同安装命令，去掉 `--user`，加 `--engine docker`，单元选择 `monitor-agent-docker.service`。rootful Podman 去掉 `--user`，单元选择 `monitor-agent-container.service`。Probe 替换角色名。初始化对应 `<role>.image` 为 `IMAGE=<当前镜像引用>` 后启动容器单元。辅助镜像可用本机已有的 digest 引用，避免标签变化。Docker rootless 更新尚未适配。
使用 Docker 时以管理员运行相同安装命令，去掉 `--user`，加 `--engine docker`，单元选择 `moshiro-agent-docker.service`。rootful Podman 去掉 `--user`，单元选择 `moshiro-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`。
更新器依赖 Linux、systemd、OpenSSL、util-linux/flock 和所选引擎。用户部署把配置、公钥和镜像引用放在 `~/.config/moshiro/`、版本记录放在 `~/.local/state/moshiro-update/`；系统部署使用 `/etc/moshiro-update/` 和 `/var/lib/moshiro-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。管理端仍能看到可更新、更新中、已回滚和无效清单状态。纯二进制更新器尚未实现。