docs: main-only workflow, CI-filled versions, dev version format [CI]

AGENTS.md

@@ -6,8 +6,9 @@ MoShiro is a self-hosted network path quality monitor. Backend coordinates Agent
 
 ## Branch and workspace safety
 
-- Treat `main` as the stable release branch and `dev` as the integration branch. Keep ordinary implementation work on `dev` or a feature branch; integrate into `main` through a pull request.
+- `main` is the only working branch (the old `dev` branch is retired and no pipeline uses it). Commit and push to `main` directly; use a pull request when a review is wanted.
-- A push to `main` builds images only if its commit message contains `[CI]` (for a merged PR, put it in the PR or merge commit title). Without `[CI]` nothing is built; use `[CI SKIP]` to skip the pipeline entirely. When squashing or pushing to `main`, add `[CI]` unless a build is explicitly not wanted.
+- A push to `main` publishes development images only if its commit message contains `[CI]` (for a merged PR, put it in the PR or merge commit title). Without `[CI]` nothing is built; use `[CI SKIP]` to skip the pipeline entirely. Backend tests and the web build run on every `main` push and must pass first; `[SKIP TESTS]` skips only the Backend tests.
+- Versions are filled in by CI (`ci/version.sh`): a `vX.Y.Z` tag builds exactly `X.Y.Z`; a `[CI]` build on `main` is `vX.Y.(Z+1)-dev.<N>-<sha7>` (`N` = commits since the latest tag). The `<Version>` in `backend/Directory.Build.props` and the `version` in the `web` `package.json` files are placeholders (`0.0.0-dev`); never bump them by hand.
 - Before editing, inspect `git status`. Preserve pre-existing user changes: do not reset, clean, stash, or include unrelated files in a commit.
 - Do not commit credentials, API keys, registry passwords, or generated runtime data. CI credentials belong in Woodpecker secrets (`zot_secret`, `gitea_token`, `release_signing_key` for signing release manifests). CI registers the signed manifests at `/api/release/offer`, which needs no token because the panel verifies the signature. The release signing private key never goes into the repository or the panel; only the public key in `packaging/update/` does.
 - Keep development OCI images in the `moshiro-dev/` repository path and release images in `moshiro/`. Do not let a development build overwrite release tags such as `latest`.
@@ -40,4 +41,4 @@ Follow the user's requested validation scope. Do not start a full tag/release bu
 
 CI triggers and image tags can change; inspect `.woodpecker/*.yml` and `docs/ops/deployment.md` before changing or describing them. In particular, check the distinction between `[CI]` main builds, `[SKIP TESTS]`, and version-tag releases in the current branch.
 
-A version tag `vMAJOR.MINOR.PATCH` runs the full cross-platform release pipeline. Development image builds and releases must remain isolated in their respective Zot repository paths.
+A version tag `vMAJOR.MINOR.PATCH` runs the full cross-platform release pipeline; it needs no version-bump commit, because CI takes the version from the tag. Development image builds and releases must remain isolated in their respective Zot repository paths.

docs/ops/deployment.md

@@ -23,7 +23,7 @@ scripts/publish.sh <agent|probe|backend|fleet-enroll> <rid>      → backend/art
 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`）。
+构建信息（程序里显示的 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`；仓库里它只是占位（`0.0.0-dev`），CI 构建时由 `ci/version.sh` 写进工作区（见下文「版本号」）。前端的信息由 `web/build-info.mjs` 在构建时写入（版本取自 `web/package.json`，同样由 CI 填写）。Agent、Probe、Backend 启动时都会在日志里打印一行构建信息：版本、tag、提交、构建时间（没设置环境变量的本地构建显示 `unknown`）。
 
 | rid | 目标 | 构建方式 |
 | --- | --- | --- |
@@ -74,25 +74,36 @@ Woodpecker 在 `vMAJOR.MINOR.PATCH` tag 上，由 Windows runner 使用 AotAnywh
 
 ## CI 工作流
 
-### Pull request 与 dev 验证
+### Pull request 与 main 验证
 
-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 中。
+Pull request 和 `main` 的 push 会运行 Backend tests；通过后，独立的 `web-build` workflow 才会构建前端并检查 CSS。提交信息后缀 `[SKIP TESTS]` 只跳过 Backend tests，前端构建仍会运行。Gitea PR 事件的 `CI_COMMIT_MESSAGE` 是 PR 标题，因此在 PR 中跳过测试时，把后缀写入 PR 标题；普通分支 push 则写在 commit message 中。项目只用 `main` 一个工作分支，旧的 `dev` 分支不再被任何流水线使用。
+
+### 版本号
+
+版本都由 CI 填写，仓库里写死的只是占位（`backend/Directory.Build.props` 的 `<Version>` 和三个 `web/**/package.json` 的 `version` 都是 `0.0.0-dev`），发版不需要提交 bump。规则在 `ci/version.sh`：
+
+| 构建 | 版本 | 构建信息里的 tag |
+| --- | --- | --- |
+| 推 `vX.Y.Z` tag（正式版） | `X.Y.Z` | `vX.Y.Z` |
+| `main` 上带 `[CI]` 的 push（开发镜像） | `X.Y.(Z+1)-dev.<N>-<提交前 7 位>` | `v` + 同一个版本 |
+
+开发版本的基准是最近一个 `v*` tag（`X.Y.Z`），`N` 是这个 tag 之后的提交数（`git rev-list --count`），所以同一个提交算出来永远一样，也按语义化版本排在下一个正式版之前，例如 `0.4.1-dev.12-044ce0c`。算版本要拿得到 tag，所以开发镜像的 workflow 克隆时带 `tags: true`。镜像标签不带 `v`（和正式版一致），构建信息和签名清单里的 `tag` 带 `v`。
 
 ### main 开发镜像
 
-`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像。合并 PR 时，请把 `[CI]` 放入 PR 标题或合并提交标题。Backend、Agent、Probe 的 Linux/amd64 镜像会并行构建，并推送到同一个 Zot Registry 下独立的 `moshiro-dev/` 仓库：
+`main` 上只有提交信息包含 `[CI]` 的 push 才构建镜像，并且要等上面的 Backend tests 和 `web-build` 都通过（提交信息写 `[SKIP TESTS]` 可以跳过测试）。合并 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>` |
+| Backend | `registry.oeo.one/moshiro-dev/moshiro-backend:latest` | `registry.oeo.one/moshiro-dev/moshiro-backend:<版本>`（如 `0.4.1-dev.12-044ce0c`） |
-| Agent | `registry.oeo.one/moshiro-dev/moshiro-agent:latest` | `registry.oeo.one/moshiro-dev/moshiro-agent:dev-<12位SHA>` |
+| Agent | `registry.oeo.one/moshiro-dev/moshiro-agent:latest` | `registry.oeo.one/moshiro-dev/moshiro-agent:<版本>` |
-| Probe | `registry.oeo.one/moshiro-dev/moshiro-probe:latest` | `registry.oeo.one/moshiro-dev/moshiro-probe:dev-<12位SHA>` |
+| Probe | `registry.oeo.one/moshiro-dev/moshiro-probe:latest` | `registry.oeo.one/moshiro-dev/moshiro-probe:<版本>` |
 
-Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。
+Dev 镜像目前仅支持 amd64；Agent/Probe 在 `sdk:10.0-alpine-aot` 中构建 `linux-musl-x64` 产物，运行基底为 `runtime-deps:10.0-alpine`。它们不创建 Gitea Release，也不修改正式版 `moshiro/` 仓库中的标签。普通 main push 不会构建镜像。节点和 Backend 判断自己是不是开发构建，看构建信息里的 tag 含 `-dev.`（旧的 `dev-<sha>`、`main-<sha>` 也认）。
 
 ### 正式版发布
 
-推送匹配项目版本的 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release。正式镜像使用 `registry.oeo.one/moshiro/` 路径；Agent、Probe 提供 amd64 与 arm64 多架构标签，稳定版本更新正式仓库自己的 `latest`。这与 `moshiro-dev/` 的 dev `latest` 相互独立。
+在 `main` 上推送 `vMAJOR.MINOR.PATCH` tag 会触发完整跨平台构建、正式 OCI 镜像推送和 Gitea Release，版本取自 tag，不需要先提交版本号。正式镜像使用 `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 中；首次注册/导入、宿主指标挂载与更新器见下文。
 
@@ -261,7 +272,7 @@ chmod 600 .env && curl -fsSL 'https://panel.example.com/install/compose/probe.ya
 - 只读根文件系统、丢掉全部能力、`no-new-privileges`、命名卷；Linux 上用宿主网络（Agent 对外暴露端口，也靠它识别本机公网地址，并只读挂载 `/proc`、`/sys`、`/` 读主机指标）。**Agent 的 compose 只适用于 Linux**；Probe 在 macOS 和 Windows（Docker Desktop）上没有宿主网络，面板给的命令会在 `.env` 里写 `MOSHIRO_NETWORK_MODE=bridge`。
 - 身份和配置在命名卷 `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`。
+- **更新**：`podman compose pull && podman compose up -d`（Docker 用 `docker compose`），只重建镜像变了的容器，身份和配置不动，节点几十秒内重连。想固定版本，在 `.env` 里写 `MOSHIRO_VERSION=<版本号>`；想要更严，写成 `MOSHIRO_VERSION=<版本号>@sha256:<digest>`，digest 取自面板信任页或签名清单（那里有发布签名）。回滚就是改回旧版本再 `up -d`。
 - **信任**：compose 来自面板或 CI 渠道，面板被攻破也改不了镜像地址；但客户端不再验发布签名，拉取靠 TLS 加「注册表可信」这个假设（文档里本来就把 CI、Gitea、注册表放在可信范围内）。compose 不会自动更新（见下节），也没有管理端的「更新」列和确认更新按钮。
 
 **一行安装脚本（备用，Docker 或 Podman，Agent 和 Probe 共用）**：管理端的弹窗里折叠着一条旧的一行命令，先核对脚本哈希再执行，脚本向面板取签名清单、用内置发布公钥验签、按 digest 拉镜像：