justme/MoShiro
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
Files
7ee860cb2713cc55f653ea2a96607306338f326e
MoShiro/docs/deployment.md
T
justme a9f562441f
ci/woodpecker/push/main-amd64-build Pipeline was successful
Details
feat!: probes generate their own keys and enroll with a join token; node and peer keys are separate [CI]
2026-10-07 16:57:34 +08:00

307 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 部署
节点（Agent、Probe）是单个 NativeAOT 可执行文件，没有运行时依赖，只需要系统的 OpenSSL 3（`libssl.so.3`）。启动时会自检，缺少时第一步就明确报错。
## 1. 构建与打包
### IPv6 状态诊断
Agent 和 Probe 在 hello 初始化及心跳中上报 IPv6 检测结果，包括监听状态、全局地址、默认路由和网络命名空间。容器可提供只读宿主 `/proc` 挂载，附带宿主网络状态。只传布尔状态，不传 IP 或网卡名称。Docker 和 Podman 推荐宿主网络模式；自定义桥接网络时，需要启用 IPv6 并提供 `/proc` 宿主挂载，前端会提示宿主和容器网络状态是否不同。
### 启用 IPv6 测量
升级 Backend、Agent、Probe 后，在管理端的 Agent 编辑页保留 IPv4 地址，并填写 IPv6 地址或带 AAAA 记录的域名。未填写 IPv6 地址的 VPS 只采集 IPv4；Probe 没有 IPv6 路由或 IPv6 连接失败时，IPv4 会话继续工作。
Agent 的新默认监听地址为 `::`（双栈）；现有 `agent.json` 如果显式配置了 `0.0.0.0`，需要在宿主机改为 `::` 并重启节点。系统不支持 IPv6 套接字时，新默认值退回 IPv4 监听。防火墙需允许 IPv6 的 `7443/tcp`、`7443/udp`、`7444/tcp`（自定义端口时用实际端口）；容器推荐宿主网络。管理端的「IPv6 监听」显示节点实际是否启用。
原来的 SQLite 数据库自动迁移，旧原始块、指标和测试结果继续属于 IPv4。先升级 Backend，再升级节点，最后填写 IPv6 地址；旧 Agent 不会上报 IPv6 支持，Backend 不会给它安排第二条会话。
上线后，在管理端的 Probe / Agent 页面查看「IPv6 诊断」。它显示检测网络范围、全局地址和默认路由；机器有 IPv6 但容器没有时，检查是否使用宿主网络。没有填 Agent IPv6 测量地址时，诊断仍会上报，但面板不会建立该 Agent 的 IPv6 测量线路。
```text
scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid> → backend/artifacts/publish/<project>/<rid>/
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` 和当前时间自动设置环境变量 `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 | 目标 | 构建方式 |
| --- | --- | --- |
| `linux-x64`、`linux-arm64` | Debian/Ubuntu glibc 服务器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
| `linux-musl-x64`、`linux-musl-arm64` | Alpine、amd64 OpenWrt、aarch64 OpenWrt 路由器 | Windows CI 主机通过 AotAnywhere 交叉编译 |
| `osx-x64`、`osx-arm64` | Intel Mac、Apple Silicon | Windows CI 主机通过 AotAnywhere 交叉编译；发布包未做 Developer ID 签名或 Apple 公证 |
| `win-x64`、`win-arm64` | Windows x64、ARM64 | Windows CI 主机上的 Visual Studio C++ 工具链 |
macOS 的 Apple Silicon 产物带临时 ad-hoc 签名，Intel 产物未签名。通过浏览器下载时，macOS Gatekeeper 可能阻止启动；面向普通用户分发前需要 Developer ID 签名和 Apple 公证。MIPS 不在当前目标列表中（见 `project-layout.md`）。
仓库内的 `scripts/publish.sh` 面向本机目标平台；Woodpecker 的 tag 流水线在 Windows runner 上构建 Agent、Probe 和 `fleet-enroll` 的所有发布目标，Backend OCI 镜像仍在 Linux runner 上构建。
## Backend 容器
Backend 使用 OCI 标准镜像，通过 `registry.oeo.one/moshiro/moshiro-backend:<version>` 分发，支持 `linux/amd64` 和 `linux/arm64`。容器使用 glibc NativeAOT 单文件程序（动态链接，运行时要加载 libssl；musl 的静态产物做不到），基底为 `mcr.microsoft.com/dotnet/runtime-deps:10.0`（Debian），以非 root 用户运行，在 `8080/tcp` 提供 HTTP 服务；数据库和原始数据统一写入 `/data`。程序启用 InvariantGlobalization，无需 .NET 运行时或 ICU；时间查询使用 UTC。SQLite 从固定版本的官方源码编译并静态链接，不再随镜像携带 `libe_sqlite3.so`。将 `/data` 挂载为持久卷，并在反向代理处配置 HTTPS。
在部署目录保存此仓库的 `compose.yaml`，先通过部署平台的环境变量或密钥管理设置 `MOSHIRO_ADMIN_PASSWORD`（可选设置 `MOSHIRO_ADMIN_USER`、`MOSHIRO_VERSION`），然后启动：
```sh
docker compose up -d
```
Compose 将容器端口只绑定到宿主机 `127.0.0.1:8080`，适合由同机 HTTPS 反向代理转发；数据保存在命名卷 `moshiro-backend-data`（Docker 和 Podman 通用，`podman compose` 也可以用同一份文件）。首次启动成功创建管理员后，改密应在管理端完成。
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 文档在普通开发构建中生成。
健康检查端点为 `GET /healthz`。容器定义见 [`../packaging/container/Backend.Containerfile`](../packaging/container/Backend.Containerfile)。
## 节点二进制发布
Woodpecker 在 `vMAJOR.MINOR.PATCH` tag 上，由 Windows runner 使用 AotAnywhere 并行构建 Agent/Probe 的 Linux glibc、Linux musl、macOS 和 Windows 产物。Agent 包还包含一次性注册工具 `fleet-enroll`。Linux 归档带有安装脚本和 systemd/OpenWrt 单元；Windows 产物为 `.zip`，Linux/macOS 产物为 `.tar.gz`。Linux musl 的 Agent 与 Probe 二进制还会打包为 OCI 镜像，基底为 `mcr.microsoft.com/dotnet/runtime-deps:10.0-alpine`，支持 `linux/amd64` 和 `linux/arm64`；所有平台仍提供对应归档。所有平台产物和 OCI 镜像发布成功后，CI 会创建对应的 Gitea Release，并附上压缩包和 SHA-256 校验文件。macOS 产物目前未签名/公证。安装说明见 [`../backend/agent/README.md`](../backend/agent/README.md) 与 [`../backend/probe/README.md`](../backend/probe/README.md)。
## CI 工作流
### Pull request 与 dev 验证
Pull request 和 `dev` push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。
### main 开发镜像
`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `moshiro-dev/` 仓库：
| 镜像 | 滚动标签 | 固定提交标签 |
| --- | --- | --- |
| 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，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。
### 正式版发布
推送匹配项目版本的 `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/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`。使用 `packaging/compose/agent`、`probe` 下的标准 Compose 模板，配置和身份放在命名 volume 中；首次注册/导入、宿主指标挂载与更新器见下文。
Agent 和 Probe 的默认发布配置：NativeAOT、完整裁剪、`OptimizationPreference=Size`、符号剥离、相同方法体折叠、InvariantGlobalization；关闭 Server/Concurrent GC、异常栈、EventSource、调试、Hot Reload、HTTP tracing、HTTP/3 和 .NET Metrics。JSON 全部使用源码生成上下文，禁用反射序列化回退；LINQ 使用体积优化实现。HTTP/3 裁剪不影响现有 HTTP/WebSocket/TLS 连接，也不影响程序自身上报的监控指标。
`fleet-enroll` 使用同一套体积优化开关。Fleet 共享库已声明 AOT 兼容，由 Agent、Probe、Backend 或注册工具的最终发布一起裁剪；GC 和运行时功能开关配置在各可执行项目中。
历史实测体积（后续以各 RID 的 CI 产物为准）：
| 程序 | linux-musl-x64 | linux-x64 | win-x64 |
| --- | --- | --- | --- |
| 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。
## 2. 安装
解压 tar.gz，在解压目录里运行 `install.sh`（POSIX sh，root 运行；Debian、Ubuntu、Alpine、OpenWrt 都测试过）：
```sh
# Agent（服务器）：注册并启动
./install.sh agent --server https://panel.example.com --join <加入令牌> --name hk-1
# Probe（家宽网络里的机器或 OpenWrt 路由器）：用面板里 probe 角色的加入令牌注册，密钥由它自己生成
./install.sh probe --server https://panel.example.com --join <加入令牌> --name home-1
./install.sh uninstall agent|probe [--purge] # --purge 同时删除身份（节点需要重新注册）
```
| 位置 | 内容 | 所有者 |
| --- | --- | --- |
| `/usr/lib/moshiro/` | 二进制 | root，0755：采集进程不能改写自己的可执行文件 |
| `/etc/moshiro/` | `agent.json` 或 `probe.json`、身份（`node.json`、`node.key`、`tls.pfx`）、`agents.json` | `moshiro` 用户，0750 |
安装脚本会：检查 OpenSSL、创建 `moshiro` 用户（`useradd`、busybox `adduser`，OpenWrt 没有这些时直接写 `/etc/passwd`）、安装二进制和服务文件；缺少配置时只安装、不启动，并打印下一步。
### systemd（`packaging/systemd/*.service`）
以 `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/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/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` 安装、以 `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/moshiro`，没有重启和错误日志。
没有验证的：arm64 构建、真正的 OpenWrt 设备（有 procd 和真实的内存/闪存限制）、跨公网的真实线路。
实测常驻内存（RSS，回环，默认模板，稳定后）：Linux 上 Probe 约 21 MB、Agent 约 23 MB；Windows 上约 22 MB、25 MB。
### 跨机器的真实链路（Windows Probe → WSL2 里的 Agent 和 Backend）
`scripts/smoke-wsl.py` 用 Windows 上的 NativeAOT Probe 连 WSL2 里的 Agent（真实的虚拟网络，两端的单调时钟原点相差约 38 小时），并用 `tc netem` 在 WSL 里注入故障。结果（Probe 的 RTT 基线约 0.4 ms）：
| 注入 | 期望 | 实测 |
| --- | --- | --- |
| Agent→Probe 方向 10% 丢包、30 ms ± 5 ms 延迟（egress netem，只匹配 7443/7444） | 丢包在下行，下行抖动变大 | `loss.down` 8.2%、`loss.up` 0；`jitter.down.p95` 8.7 ms、`jitter.up.p95` 0.18 ms；RTT +31 ms；TCP：`tcp.rtt.p99` 1.2 s、`tcp.slow` 28.8%、`tcp.retrans` 5.9%（Agent 一侧内核计数） |
| Probe→Agent 方向 10% 丢包、20 ms ± 3 ms 延迟（ingress + ifb） | 丢包在上行 | `loss.up` 9.4%、`loss.down` 0；`jitter.up.p95` 5.2 ms、`jitter.down.p95` 0 |
| 8 秒黑洞（tc ingress drop 7443/7444） | UDP 连续丢包 ~80 个；TCP 不丢包，只有几秒的长尾 | UDP 最长连续丢包 80（10 Hz × 8 s）；`tcp.rtt.max` 9.5 s、`tcp.stall_max` 9.6 s |
| `hy2_ladder`（10/25/50/100 Mbit/s） | 无丢包 | `train.loss` 0.006%、`train.jitter.p95` 0.64 ms、可持续 100 Mbit/s |
| 杀掉 Agent / 杀掉 Probe 再启动 | 自动恢复 | Agent 重启后 2.1 s 恢复在线并重新连上 Probe；Probe 重启后 0.5 s 重新连上 |
验证中发现并修掉的两个问题：
- **Probe 重启后，Agent 沿用了上一个会话的记录**：Probe 重启之后序号从 0 开始，Agent 里同一个序号的旧 t2/t3 还在，于是真正的上行丢失被算成了下行丢失（黑洞测试里 `loss.up` 0、`loss.down` 7.4%）。现在新的 Probe 会话开始时 Agent 清空所有流的记录。
- **TCP 回显的几秒中断被记成丢包**：Probe 像 UDP 那样等 2 秒就把没有回复的行交出去，TCP 随后才到的回复没有行可以回填，最严重的长尾反而在 RTT 里看不到（黑洞期间 `tcp.rtt.max` 只有 4 ms）。现在 TCP 的行等回复，30 秒仍然没有才当作连接已断（t4 缺失）。
没有覆盖的：Windows 上的 Agent（需要给 Windows 防火墙加入站规则）、NAT 重绑定。跨公网的线路见下一节。
### 跨公网的真实线路（广东移动家宽 → 日本 IIJ 的 VPS）
2026-10-03 在一条真实线路上试跑过：家宽机器（Debian 13，用户态运行，没有公网 IPv4 入站）跑 Probe 和 Backend，VPS（Debian 12，1 核 470 MB，上面本来就跑着 xray、hysteria2、caddy 等服务）跑 Agent。
```text
浏览器 / 本机前端 ──► https://<公网域名> ──隧道（Cloudflare Tunnel 之类）──► 家宽机器: Backend (:29181)
家宽机器: Probe ──WSS 到 https://<公网域名>──► Backend（身份、Agent 列表）
家宽机器: Probe ──TCP/UDP 7443、TCP 7444──► VPS: Agent
VPS: Agent ──WSS 到 https://<公网域名>──► Backend
```
做法和要点：
- **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` 里的 `fleet.server` 就是面板地址，Probe 用它连面板，Agent 列表由面板下发；密钥由 Probe 注册时自己生成，身份目录（`node.json`、`node.key`、`tls.pfx`）在 `fleet.identity_dir`。
- **小 VPS 把 `limits.max_total_mbps` 调低**（试跑时用 100）；Agent 常驻约 23 MB，VPS 上原有的服务不受影响，结束后删除 `/opt/…`、停掉进程即可，没有留下任何东西。
- 家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，SSH 地址要跟着换；面板走隧道的域名，不受影响。
- 本地电脑没有直连 VPS 的路径时，用家宽机器当跳板（`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force`，密码放环境变量，不写进文件）。
**常驻（开机自启）**：
- 家宽机器（没有 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 归属服务查一次，展示在国旗和运营商图标上（`MoShiro__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `MoShiro__CorsOrigins` 放行前端的来源（见 [web/README.md](../web/README.md)）。
实测（Probe 在广东移动家宽，Agent 在日本 IIJ）：
| 项目 | 结果 |
| --- | --- |
| 延迟 p50 / p95 / p99 | 107 / 107 / 114 ms |
| 丢包 | 上行 0%，下行 8.1%（`hy2_ladder` 在 10、25、50、100 Mbit/s 四档下的丢包都是 8～10%，与速率无关：随机丢包，不是限速） |
| 抖动 p95（上 / 下） | 0.9 / 5.2 ms |
| TCP | 重传 1.9%（批量传输时 5.8%），RTT 最大 412 ms |
| `reality_session` | 建连成功率 100%，TCP 建连 p95 115 ms，TLS 握手 p95 117 ms，30 秒长连接无重置；4 秒批量传输峰值 133 Mbit/s、中位数 90 Mbit/s（Agent 上限 100） |
| 评分 | REALITY 82（含按需测试）、Hy2 42 |
| Agent 主机状态 | CPU 1.5%，内存 274 / 493 MB，已运行约 20.5 天 |
这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。
## 容器部署（Docker / Podman 共用命名 volume）
镜像和 Compose 配置共用。普通用户执行 Podman 即为 rootless，使用命名 volume 不需要 `keep-id` 或手动 `chown`。Agent 的配置、原有身份和缓存保存在 `moshiro-agent-config`，Probe 保存在 `moshiro-probe-config`，更新状态使用独立的 `moshiro-<role>-status` volume，在业务容器内只读。不会重新生成已有身份。更新/重建容器不删除 volume；不要使用 `compose down -v`，该参数会删除数据。
**用脚本部署和更新（rootful Podman 或 Docker，推荐）**：`packaging/container/deploy-node.sh` 可以重复运行，每次都会拉取镜像并固定到 digest、把配置迁移到当前版本需要的样子（例如旧的 `listen.bind` 为 `0.0.0.0` 的 Agent 改成 `::`，这样 IPv6 线路才能建立）、重装单元和更新器，然后重启节点；已有的身份不会动，更新策略沿用上次的。
```sh
# 首次部署（需要 root；脚本和 packaging/ 里的 systemd/、update/ 放在一起）
sudo sh deploy-node.sh agent --image-repo registry.oeo.one/moshiro/moshiro-agent --server https://<backend> --join <token> --name <name>
sudo sh deploy-node.sh probe --image-repo registry.oeo.one/moshiro/moshiro-probe --server https://<backend> --join <probe 令牌> --name <name>
# 之后更新节点：不带参数
sudo sh deploy-node.sh agent
```
节点上看不到公网 IPv6 地址，所以 Agent 的 `ipv6_host` 要在管理端手动填，Backend 才会让 Probe 去拨 IPv6。下面是不用脚本的手动步骤。
在 `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/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":"::"}}
JSON
podman compose up -d
```
Probe 在 `packaging/compose/probe` 下，和 Agent 一样先用 `fleet-enroll` 注册：`podman compose run --rm --entrypoint /usr/local/bin/fleet-enroll probe --server https://<backend> --join <probe 令牌> --name <name> --identity-dir /etc/moshiro/probe-id`，再写 `probe.json`（`{"fleet":{"server":"https://<backend>","identity_dir":"/etc/moshiro/probe-id"}}`），然后 `podman compose up -d`。已有部署迁移时，应把原配置与身份原样复制进 volume，不重新注册。要换密钥就在面板吊销再重新注册。Docker 与 Podman 各自管理 volume，切换引擎不会自动共享数据。
纯 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 用根目录的 `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 没有独立目标任务入口。
### 定时重启
Agent 和 Probe 每天固定时刻有序退出一次，由服务管理器拉起（所有 systemd 单元和 OpenWrt 的 procd 脚本都是「总是重启」，正常退出也会被拉起）。节点只是自己退出，没有任何执行命令的能力；重启期间测量会中断几十秒。
- **在管理端控制**：系统 → 设置 →「定时重启」，开关、时刻和时区（默认**开**，北京时间 04:30）。保存后马上通知所有在线节点，新连上的节点会补发。
- **节点本地覆盖**：节点本地写了就以本地为准（面板的设置对它不生效）。`agent.json` 或 `probe.json` 里加 `"restart_at": "04:30+08:00"`，或者设置环境变量 `MOSHIRO_RESTART_AT`（优先）。写法 `HH:mm`（按 UTC）、`HH:mmZ` 或 `HH:mm±hh:mm`；写错了启动时就会报错。Probe 的容器同样可以用环境变量。
- 启动后不满 10 分钟不会触发，所以重启之后不会立刻又重启一次。日志里有 `restart scheduled at=… source=panel|local` 和 `stopping result=scheduled_restart`。
- Windows 上没有自带的服务单元，需要服务管理器配置为退出后重启。
### Agent 的系统指标挂载
Agent 的 Compose 模板已经包含以下只读挂载和环境变量，systemd 示例也采用相同配置：
| 宿主来源 | 容器路径 | 配置 | 指标 |
| --- | --- | --- | --- |
| `/proc` | `/host/proc` | `HOST_PROC=/host/proc` | CPU、内存、累计网络流量、瞬时收发速率、运行时长 |
| `/sys` | `/host/sys` | `HOST_SYS=/host/sys` | 网卡驱动报告的链路速率 |
| `/` | `/host/root` | `HOST_ROOT=/host/root` | 宿主根文件系统容量和已用空间 |
| `/etc/os-release` | `/etc/os-release` | 无 | 宿主发行版 |
系统目录不加 `:z` 或 `:Z`，容器统一设置 `--security-opt label=disable`。读取失败的指标返回空值；配置了 `HOST_ROOT` 但没有挂载时不会改读容器 overlay 根分区。未设置这些环境变量时，原生进程继续读取本机默认路径。
磁盘指标是根文件系统容量，不是所有硬盘合计，也不采集磁盘 I/O。链路速率是参与流量统计的接口速率合计，单位 Mbit/s，不是互联网测速结果；任一接口不支持读取速率时显示空值。接口仍按名称排除回环、容器、网桥和部分隧道，复杂 bonding/VLAN 配置可能存在重复计数。主机名、硬件型号、MAC/IP 不作为资源指标上报。
Probe 保持现有功能，只上报系统、架构与节点状态，不上报 CPU、内存、磁盘或网卡指标。因此 Probe 的 Compose 模板只需要配置目录和 `/etc/os-release` 挂载；从 Agent systemd 示例改为 Probe 时，去掉 `/proc`、`/sys`、`/` 挂载及 `HOST_*` 环境变量。
## 容器节点的更新（Agent、Probe）
更新器支持 rootless Podman 用户服务、rootful Podman 和 Docker 系统服务。配置、身份和更新请求通过命名 volume 传递，不需要指定宿主数据目录。短时辅助容器读取请求、写入独立状态 volume；辅助镜像必须已在本机拉取，更新器不会自动拉取辅助镜像。配置、公钥和已安装版本记录留在容器外。
Rootless Podman 普通用户安装示例（先将对应 rootless 服务单元复制到用户 systemd 目录）：
```sh
sh packaging/update/install-updater.sh agent --user \
--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`，单元选择 `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/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。管理端仍能看到可更新、更新中、已回滚和无效清单状态。纯二进制更新器尚未实现。
## Backend 签名更新
Backend 也会收到 CI 发布的签名清单，但只提示管理端，不会自动重启。管理员确认精确的清单序号后，宿主更新器才会备份 Backend 数据 volume、按清单 digest 拉取镜像、重启服务并检查 `/healthz`；失败时恢复旧镜像和数据库备份。确认和发布通过同一个锁串行处理，避免确认过期版本。
`MOSHIRO_UPDATE_CHANNEL=auto` 时，`MOSHIRO_IMAGE_NAMESPACE=moshiro-dev` 选择 `dev`，`moshiro` 选择 `release`。CI 发布流水线使用对应 channel 签名并登记到 Backend webhook。旧版 Backend 不识别 Backend 清单，因此首次升级需按常规部署流程引导一次；该期间 CI 对这类旧版面板的明确“不认识 backend 组件”响应会提示引导信息，其他 webhook 错误仍会令发布失败。
更新器以手动策略运行，并通过独立状态 volume 将状态只读挂载回 Backend：
```sh
sudo packaging/update/install-updater.sh backend --engine podman \
--volume moshiro-backend-data --status-volume moshiro-backend-status \
--helper-image registry.oeo.one/moshiro-dev/moshiro-backend:<version> \
--image-repo registry.oeo.one/moshiro-dev/moshiro-backend \
--unit moshiro-backend.service --policy manual --channel dev \
--health-url http://127.0.0.1:29181/healthz
```
Backend 服务需要将 `moshiro-backend-status` 挂载到 `/data/update-status:ro`，并将镜像引用文件 `/etc/moshiro-update/backend.image` 作为 `IMAGE_FILE` 提供给 systemd 单元。release 实例使用 `--channel release` 及 `registry.oeo.one/moshiro` 仓库。更新请求由管理端确认后写入状态接口，不要启用全局 Podman 自动更新 timer。
Reference in new issue View Git Blame Copy Permalink