justme/MoShiro

1 Fork 0

Files

T

justme 33b9782a1d

ci/woodpecker/pr/verify Pipeline was successful

Details

ci/woodpecker/pr/web-build Pipeline was successful

Details

ci: tolerate legacy Backend release webhook [CI]

2026-10-07 13:00:35 +08:00

30 KiB

Raw Blame History

部署

节点（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 测量线路。

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），然后启动：

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。

节点二进制发布

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/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 都测试过）：

# Agent（服务器）：注册并启动
./install.sh agent --server https://panel.example.com --join <加入令牌> --name hk-1

# Probe（家宽网络里的机器或 OpenWrt 路由器）：先在面板生成身份（POST /api/admin/probes，只能下载一次）
./install.sh probe --probe-json ./probe.json

./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。

浏览器 / 本机前端 ──► 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 里的 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/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）。

实测（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，该参数会删除数据。

在 packaging/compose/agent 下首次注册，并写配置（下列 podman 可替换为 docker）：

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":"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/moshiro/probe.json' < probe.json，再 podman compose up -d。私钥权限为 600。已有部署迁移时，应把原配置与身份原样复制进 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 的系统指标挂载

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 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：

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。

30 KiB Raw Blame History Unescape Escape

部署