docs: reorganize into design, security, api, ops and dev; drop stale designs; refresh the diagrams [CI]

- Group docs by category with an index (docs/README.md); fix every link, code comment and the protocol conformance test that read docs/protocol.md. - access.md and security.md rewritten to what is implemented: removed the unadopted member-proof chain, roles and recovery key that do not exist, the old implementation order and the budgets; gaps now carry a status. - enrollment, deployment, api: the install flow is the static, hash-checked script with environment variables; no default admin. - README and architecture: new topology and update-flow diagrams (operator passkey, CI signing, registry feed, auth and trust modules).
2026-10-08 19:37:56 +08:00
1 parent 636a784043
commit e014a19554
@@ -36,7 +36,7 @@ dotnet test --solution MoShiro.slnx
 dotnet publish src/MoShiro.Backend -c Release -r <RID> -p:PublishAot=true
 ```

-例如 `<RID>` 可为 `win-x64`、`linux-x64` 或 `linux-arm64`。NativeAOT 发布需要对应平台的 C/C++ 工具链。仓库根目录的 `scripts/publish.sh backend <RID>` 可构建单个平台的 Backend 可执行文件；容器发布由 Woodpecker tag 流水线完成，详见 [`../docs/deployment.md`](../docs/deployment.md)。
+例如 `<RID>` 可为 `win-x64`、`linux-x64` 或 `linux-arm64`。NativeAOT 发布需要对应平台的 C/C++ 工具链。仓库根目录的 `scripts/publish.sh backend <RID>` 可构建单个平台的 Backend 可执行文件；容器发布由 Woodpecker tag 流水线完成，详见 [`../docs/ops/deployment.md`](../docs/ops/deployment.md)。

 正式发布通过 Woodpecker tag 流水线生成 Linux/amd64 与 Linux/arm64 OCI 镜像，容器内监听 `8080`，数据写入挂载的 `/data` 卷。Agent 与 Probe 的多平台二进制包单独发布，不包含在 Backend 镜像中。

@@ -49,6 +49,6 @@ cd backend
 dotnet run --project src/MoShiro.Backend -- --urls http://localhost:5000
 ```

-没有默认管理员：第一次打开面板时按页面引导自己创建管理员、注册 passkey、建立信任根，页面要的认领码写在后端日志里（或用 `MoShiro__ClaimCode` 指定）。`MoShiro__InitialAdminUser` / `MoShiro__InitialAdminPassword` 只给自动化用。数据目录、公开地址、Cookie 和 CORS 等设置通过 `MoShiro` 配置节传入；完整配置说明见 [`../docs/deployment.md`](../docs/deployment.md)。站点默认需要登录，可在管理端修改公开设置。
+没有默认管理员：第一次打开面板时按页面引导自己创建管理员、注册 passkey、建立信任根，页面要的认领码写在后端日志里（或用 `MoShiro__ClaimCode` 指定）。`MoShiro__InitialAdminUser` / `MoShiro__InitialAdminPassword` 只给自动化用。数据目录、公开地址、Cookie 和 CORS 等设置通过 `MoShiro` 配置节传入；完整配置说明见 [`../docs/ops/deployment.md`](../docs/ops/deployment.md)。站点默认需要登录，可在管理端修改公开设置。

-OpenAPI 文档由构建生成到 `openapi/v1.json`。API 设计和端点说明见 [`../docs/api.md`](../docs/api.md)；项目总览见仓库根目录的 [`README.md`](../README.md)。
+OpenAPI 文档由构建生成到 `openapi/v1.json`。API 设计和端点说明见 [`../docs/api/api.md`](../docs/api/api.md)；项目总览见仓库根目录的 [`README.md`](../README.md)。
@@ -29,7 +29,7 @@ dotnet publish agent/src/MoShiro.Agent -c Release -r <RID> -p:PublishAot=true
 dotnet publish fleet/tools/fleet-enroll -c Release -r <RID> -p:PublishAot=true
 ```

-也可在仓库根目录运行 `bash scripts/publish.sh agent <RID>` 和 `bash scripts/publish.sh fleet-enroll <RID>`。部署包和平台说明见 [`../../docs/deployment.md`](../../docs/deployment.md)。
+也可在仓库根目录运行 `bash scripts/publish.sh agent <RID>` 和 `bash scripts/publish.sh fleet-enroll <RID>`。部署包和平台说明见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。

 ## 注册与运行

@@ -47,7 +47,7 @@ fleet-enroll --server https://<backend> --join <token> --name <agent-name> --ide
 moshiro-agent --config /etc/moshiro/agent.json
 ```

-容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/deployment.md`](../../docs/deployment.md)。也可使用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-agent:<version>`，自动选择 Linux amd64 或 arm64 镜像。镜像同时包含 `fleet-enroll`；可通过 `--entrypoint /usr/local/bin/fleet-enroll` 执行首次注册。容器默认读取命名 volume 中的 `/etc/moshiro/agent.json` 与身份文件；建议使用宿主网络，Linux ICMP 优先使用普通用户 ping socket，内核 ping_group_range 需允许映射后的 GID。镜像以 UID/GID 1654 运行，新命名 volume 由引擎按镜像目录初始化权限。
+容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。也可使用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-agent:<version>`，自动选择 Linux amd64 或 arm64 镜像。镜像同时包含 `fleet-enroll`；可通过 `--entrypoint /usr/local/bin/fleet-enroll` 执行首次注册。容器默认读取命名 volume 中的 `/etc/moshiro/agent.json` 与身份文件；建议使用宿主网络，Linux ICMP 优先使用普通用户 ping socket，内核 ping_group_range 需允许映射后的 GID。镜像以 UID/GID 1654 运行，新命名 volume 由引擎按镜像目录初始化权限。

 不传 `--config` 时默认读取 `/etc/moshiro/agent.json`。Agent 默认监听控制端口 `7443/tcp`，数据端口 `7443/udp` 和 `7444/tcp`；防火墙和面板中的节点端口配置需与本地配置一致。`reporting.host_stats` 可关闭主机状态上报；启用时只上报资源使用等汇总数据，不包含主机名、进程或 IP。

@@ -58,6 +58,6 @@ IPv6 线路需要 Agent 实际绑定 IPv6。新配置的默认 `listen.bind` 为
 - 每个 Probe 使用独立的 TLS 会话和数据密钥；Probe 断开时对应的会话资源会释放。
 - 数据面会校验会话认证、重放窗口和速率限制；无效数据包会静默丢弃。
 - 测量引擎和协议由 `backend/shared/` 提供；节点身份、注册和连接由 `backend/fleet/` 提供。
- 详细安全边界与拓扑见 [`../../docs/architecture.md`](../../docs/architecture.md)，协议说明见 [`../../docs/protocol.md`](../../docs/protocol.md)，部署见 [`../../docs/deployment.md`](../../docs/deployment.md)。
+- 详细安全边界与拓扑见 [`../../docs/design/architecture.md`](../../docs/design/architecture.md)，协议说明见 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)，部署见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。

 Docker 与 rootless/rootful Podman 共用 `packaging/compose/agent/compose.yaml`，配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。
@@ -23,7 +23,7 @@
 2. **安全默认值**：Fleet 永远不提供 exec、shell、文件读写、远程下发代码这类方法；节点只响应本地注册过的方法（本地策略 `allow_methods` 还能收窄）；调用对方不支持的方法在本地直接返回 `fleet_unsupported`。
 3. **权限分离**：注册（`fleet-enroll`，一次性）和常驻业务进程是两个进程；常驻进程不含注册代码，也不使用 `HttpClient`。
 4. **NativeAOT**：节点侧只依赖 BCL，泛型扩展点通过产品传入的 `JsonTypeInfo<T>` 序列化，不使用反射。
-5. **更新不在 Fleet 里**：节点进程没有自更新能力。容器节点的签名更新由宿主机上的更新器完成，见 [`docs/deployment.md`](../../docs/deployment.md)；纯二进制节点的更新是待办，见 [`TODO.md`](../../TODO.md)。
+5. **更新不在 Fleet 里**：节点进程没有自更新能力。容器节点的签名更新由宿主机上的更新器完成，见 [`docs/ops/deployment.md`](../../docs/ops/deployment.md)；纯二进制节点的更新是待办，见 [`TODO.md`](../../TODO.md)。

 ## 身份

@@ -56,7 +56,7 @@
 - JSON-RPC 2.0；方法名 `领域.动作`，`fleet.*` 保留给框架，产品用自己的前缀（MoShiro 是 `moshiro.*`）。
 - 二进制帧 `u8 channel | 正文`：`0`–`15` 框架保留，产品从 `16` 开始。
 - 错误：`error.data.code` 为 snake_case，框架的以 `fleet_` 开头，产品可以扩展。
- **方法必须声明**：每个方法在声明表（`MethodTable`）里写明发起方、请求还是通知、哪些角色可以参与；不存在双向方法，同一个方法名在一个平面里只有一个发起方。`RpcRouter` 在注册、分发和发送三处核对，违规回 `fleet_protocol_violation`，超过上限断开连接。详见 [`docs/security.md`](../../docs/security.md) 第 8 节。
+- **方法必须声明**：每个方法在声明表（`MethodTable`）里写明发起方、请求还是通知、哪些角色可以参与；不存在双向方法，同一个方法名在一个平面里只有一个发起方。`RpcRouter` 在注册、分发和发送三处核对，违规回 `fleet_protocol_violation`，超过上限断开连接。详见 [`docs/security/security.md`](../../docs/security/security.md) 第 8 节。
 - 与传输无关：同一套路由跑在 wss 上，也跑在 TLS 帧（`u32 长度 | u8 类型 | 正文`）上。

 | 保留方法 | 方向 | 说明 |
@@ -25,7 +25,7 @@ public sealed partial class TrustFileContext : JsonSerializerContext;
 /// <summary>
 /// 节点的信任根：安装命令里带来的创世指纹和属主，在注册时固定到本地，之后 Backend 改不了。
 /// 操作员集合的新版本随期望状态下发，节点只接受从固定的创世出发、签名完整、版本更新的链。
-/// 属主只是被固定和保存：节点现在没有 extension，等做 extension 时由节点本地强制（见 docs/access.md 第 8 节）。
+/// 属主只是被固定和保存：节点现在没有 extension，等做 extension 时由节点本地强制（见 docs/security/access.md 第 9 节）。
 /// </summary>
 public sealed class TrustAnchor : IServerVerifier
 {
@@ -20,7 +20,7 @@ public sealed record OperatorKey(string CredentialId, byte[] PublicKeySpki);
 public sealed record OperatorSet(int Version, string Previous, string RpId, IReadOnlyList<string> Origins, IReadOnlyList<OperatorKey> Keys, IReadOnlyList<byte[]>? Servers = null);

 /// <summary>
-/// 信任根：操作员（passkey）→ 操作员集合 → 节点本地固定的属主。设计见 docs/access.md 第 7 节。
+/// 信任根：操作员（passkey）→ 操作员集合 → 节点本地固定的属主。设计见 docs/security/access.md 第 8 节。
 /// 安装命令里带着创世指纹和属主（passkey 的凭证 id）：节点把它们固定在本地，之后只认从创世出发、由操作员 passkey 签过名的集合版本，
 /// 属主必须是集合里的凭证。Backend 能转发集合，但签不出新的版本，也改不了节点已经固定的东西。
 /// 全是纯函数，只用 BCL，节点和 Backend 共用。语句是 <c>key=value</c> 的文本，第一行是带版本的标题；签名覆盖整段文本。
@@ -7,7 +7,7 @@ namespace Fleet.Identity;

 /// <summary>
 /// 验证一次 WebAuthn 断言（<c>navigator.credentials.get</c> 的结果）。只支持 ES256（P-256 的 ECDSA），纯函数，只用 BCL：
-/// 面板用它验证 passkey 登录，节点以后用它验证 passkey 签出的委托（docs/access.md 第 7 节）。
+/// 面板用它验证 passkey 登录，节点验证操作员集合的签名也用它（docs/security/access.md 第 8 节）。
 /// 不解析 CBOR——注册时的 attestation 解析只在 Backend 里。
 /// </summary>
 public static class WebAuthnAssertion
@@ -13,7 +13,7 @@ Backend ──任务──> Agent <──测量会话──> Probe

 Probe 用 `probe.json` 读取面板地址（`fleet.server`）、身份目录（`fleet.identity_dir`，由 `fleet-enroll` 注册时生成）和本地测试限制。连上面板之后，面板下发要连接的 Agent 列表；Probe 将列表缓存到同目录的 `agents.json`，面板暂时连不上时靠它继续测量。身份目录里有私钥，请限制访问权限，不要提交到版本控制。

-容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/deployment.md`](../../docs/deployment.md)；Probe 也可以用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-probe:<version>`，容器默认读取 `/etc/moshiro/probe.json`，命名 volume 保存身份配置和缓存，镜像以 UID/GID 1654 运行。
+容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)；Probe 也可以用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-probe:<version>`，容器默认读取 `/etc/moshiro/probe.json`，命名 volume 保存身份配置和缓存，镜像以 UID/GID 1654 运行。

 ## 构建

@@ -30,7 +30,7 @@ dotnet build probe/src/MoShiro.Probe -c Release
 dotnet publish probe/src/MoShiro.Probe -c Release -r <RID> -p:PublishAot=true
 ```

-也可在仓库根目录运行 `bash scripts/publish.sh probe <RID>`，再使用 `scripts/package.sh probe <RID>` 生成部署包。支持平台和安装流程见 [`../../docs/deployment.md`](../../docs/deployment.md)。
+也可在仓库根目录运行 `bash scripts/publish.sh probe <RID>`，再使用 `scripts/package.sh probe <RID>` 生成部署包。支持平台和安装流程见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。

 ## 配置与运行

@@ -54,6 +54,6 @@ moshiro-probe --config /etc/moshiro/probe.json

 - Probe 只执行编译进程序的测量模块。它不落盘测量数据，也不能执行命令或自行更新（更新由宿主机上的更新器完成，Probe 只写清单和请求文件）。
 - 测量模块由 `backend/shared/MoShiro.Measurement/` 与 Agent 共用；Probe 负责发起连接、调度任务和记录本端数据。
- 测量模型和协议细节见 [`../../docs/measurement.md`](../../docs/measurement.md) 与 [`../../docs/protocol.md`](../../docs/protocol.md)；整体架构见 [`../../docs/architecture.md`](../../docs/architecture.md)。
+- 测量模型和协议细节见 [`../../docs/design/measurement.md`](../../docs/design/measurement.md) 与 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)；整体架构见 [`../../docs/design/architecture.md`](../../docs/design/architecture.md)。

 Docker 与 rootless/rootful Podman 共用 `packaging/compose/probe/compose.yaml`，配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。
@@ -8,7 +8,7 @@ using MoShiro.Protocol;
 namespace MoShiro.Backend.Api;

 /// <summary>
-/// 信任根（docs/access.md 第 7 节）：操作员集合由 passkey 签名，节点从安装命令里固定的创世指纹出发验证它；
+/// 信任根（docs/security/access.md 第 8 节）：操作员集合由 passkey 签名，节点从安装命令里固定的创世指纹出发验证它；
 /// 带操作员委托的加入码也在这里创建——委托是 passkey 对「这个码」签的，面板自己签不出来。
 /// </summary>
 public static class TrustEndpoints
@@ -6,7 +6,7 @@ namespace MoShiro.Backend.Api;

 /// <summary>
 /// 一行安装脚本：<c>packaging/install/</c> 下的 <c>install.sh</c> 和 <c>install.ps1</c> 作为嵌入资源打进 Backend，<b>原样返回，不替换任何值</b>。
-/// 静态，所以它的 SHA-256 在一个版本内固定：CI 构建时算出来写进签名的发布清单，面板给的命令先核对哈希再执行（docs/access.md 第 15 节）。
+/// 静态，所以它的 SHA-256 在一个版本内固定：CI 构建时算出来写进签名的发布清单，面板给的命令先核对哈希再执行（docs/security/access.md 第 10 节）。
 /// 角色、面板地址、代码都走命令里的环境变量。
 /// </summary>
 public static class InstallScripts
@@ -2,7 +2,7 @@ namespace MoShiro.Backend.Application;

 /// <summary>
 /// 能力（capability）：一项具体的权限。端点声明自己需要哪一项，<see cref="Principal.Has"/> 是唯一的判断入口，
-/// 会话、API key 都走它。设计见 docs/access.md 第 2 节。
+/// 会话、API key 都走它。设计见 docs/security/access.md 第 3 节。
 /// </summary>
 public static class Capability
 {
@@ -38,7 +38,7 @@ public static class Capability
    public const string EventsRead = "events.read";
    public const string OpsMetrics = "ops.metrics";

-    // 预留：外部 webhook 回调和数据拉取（docs/access.md 5.4），目录里先存在，实现放后面
+    // 预留：外部 webhook 回调和数据拉取（docs/security/access.md 6.3），目录里先存在，实现放后面
    public const string DataExport = "data.export";
    public const string WebhooksRead = "webhooks.read";
    public const string WebhooksManage = "webhooks.manage";
@@ -22,7 +22,7 @@ public sealed record PasskeyAssertion(string CredentialId, string AuthenticatorD
 /// <summary>
 /// passkey 的注册与登录（WebAuthn，ES256，attestation 当 none）。挑战只在内存里，一次有效、5 分钟过期；
 /// 登录是「可发现凭证」：不需要先输用户名，凭证 id 找到用户。验证断言的纯函数在 <see cref="WebAuthnAssertion"/>（节点以后也用）。
-/// 设计见 docs/access.md 第 3 节。
+/// 设计见 docs/security/access.md 第 4 节。
 /// </summary>
 public sealed class PasskeyService
 {
@@ -20,7 +20,7 @@ public sealed record TrustState(bool Initialized, string? Genesis, int Version,
 /// <summary>
 /// 信任根的 Backend 一侧：保存操作员集合的链、给操作员出下一版的语句、验证他签回来的版本。
 /// Backend <b>不持有任何签名的能力</b>：每一版都要操作员的 passkey 触碰；节点从安装命令里固定的创世指纹出发自己验链，
-/// 所以 Backend 在这里的验证只是不收垃圾，不是信任的来源。设计见 docs/access.md 第 7 节。
+/// 所以 Backend 在这里的验证只是不收垃圾，不是信任的来源。设计见 docs/security/access.md 第 8 节。
 /// </summary>
 public sealed class TrustService : IOperatorTrustSource, IDisposable
 {
@@ -9,7 +9,7 @@ public sealed record RegisteredCredential(byte[] CredentialId, byte[] PublicKeyS

 /// <summary>
 /// 解析并校验 WebAuthn 注册（<c>navigator.credentials.create</c> 的结果）。只接受 ES256；attestation 一律当 <c>none</c> 处理：
-/// 不验设备证明，信任浏览器的实现（docs/access.md）。CBOR 解析只在 Backend 里，节点不带。
+/// 不验设备证明，信任浏览器的实现（docs/security/access.md）。CBOR 解析只在 Backend 里，节点不带。
 /// </summary>
 public static class WebAuthnRegistration
 {
@@ -3,7 +3,7 @@ using System.Xml.Linq;
 namespace MoShiro.Backend.Tests;

 /// <summary>
-/// 依赖规则（docs/project-layout.md 第 3 节）：由测试在构建期强制。
+/// 依赖规则（docs/dev/project-layout.md 第 3 节）：由测试在构建期强制。
 /// 读取仓库里所有 .csproj 和源文件，违反规则就失败。
 /// </summary>
 public sealed class ArchitectureTests
@@ -8,7 +8,7 @@ using MoShiro.Backend.Application;

 namespace MoShiro.Backend.Tests;

-/// <summary>能力模型（docs/access.md 第 2 节）：每个管理端点声明能力；密钥只能拿到自己拥有能力的子集；写蕴含读。</summary>
+/// <summary>能力模型（docs/security/access.md 第 3 节）：每个管理端点声明能力；密钥只能拿到自己拥有能力的子集；写蕴含读。</summary>
 [Collection("probe-e2e")]
 public sealed class CapabilityTests
 {
@@ -4,7 +4,7 @@ using System.Text.RegularExpressions;
 namespace MoShiro.Backend.Tests;

 /// <summary>
-/// 对照 docs/api-guidelines.md 检查运行时生成的 OpenAPI 文档：operationId、路径风格、错误响应格式、字段命名。
+/// 对照 docs/api/api-guidelines.md 检查运行时生成的 OpenAPI 文档：operationId、路径风格、错误响应格式、字段命名。
 /// 新增端点违反规范时，这里会直接失败（等价于文档里的 <c>eng/check-openapi</c>）。
 /// </summary>
 [Collection("backend")]
@@ -85,7 +85,7 @@ public sealed class SoftwarePasskey : IDisposable
    private static byte[] Text(string text) => [.. Head(3, Encoding.UTF8.GetByteCount(text)), .. Encoding.UTF8.GetBytes(text)];
 }

-/// <summary>passkey 登录：注册、登录、拒绝各种错误的断言、只能管理自己的 passkey。设计见 docs/access.md 第 3 节。</summary>
+/// <summary>passkey 登录：注册、登录、拒绝各种错误的断言、只能管理自己的 passkey。设计见 docs/security/access.md 第 4 节。</summary>
 [Collection("probe-e2e")]
 public sealed class PasskeyTests
 {
@@ -39,7 +39,7 @@ public sealed class ProtocolDeclarationTests
    public void EveryDeclaredMethod_IsDocumented()
    {
        string root = FindRoot();
-        string docs = File.ReadAllText(Path.Combine(root, "docs", "protocol.md")) + File.ReadAllText(Path.Combine(root, "backend", "fleet", "README.md"));
+        string docs = File.ReadAllText(Path.Combine(root, "docs", "design", "protocol.md")) + File.ReadAllText(Path.Combine(root, "backend", "fleet", "README.md"));
        string[] missing = [.. s_table.Methods.Select(m => m.Name).Distinct().Where(n => !docs.Contains($"`{n}`", StringComparison.Ordinal))];
        Assert.Empty(missing);
    }
@@ -84,7 +84,7 @@ public sealed class ProtocolDeclarationTests
    private static string FindRoot()
    {
        string? dir = AppContext.BaseDirectory;
-        while (dir is not null && !File.Exists(Path.Combine(dir, "docs", "protocol.md")))
+        while (dir is not null && !File.Exists(Path.Combine(dir, "docs", "design", "protocol.md")))
        {
            dir = Path.GetDirectoryName(dir);
        }
@@ -6,7 +6,7 @@ using MoShiro.Protocol;

 namespace MoShiro.Backend.Tests;

-/// <summary>时间段、步长与数据源的规划：与 docs/query.md 里的表格逐行对应。</summary>
+/// <summary>时间段、步长与数据源的规划：与 docs/design/query.md 里的表格逐行对应。</summary>
 public sealed class QueryPlanningTests
 {
    private const long Second = 1000;
@@ -15,7 +15,7 @@ namespace MoShiro.Backend.Tests;

 /// <summary>
 /// 信任根：操作员（passkey）签操作员集合；安装命令里带着创世指纹和属主（都是公开值），节点注册时验证面板的集合并固定在本地。
-/// 设计见 docs/access.md 第 7 节。
+/// 设计见 docs/security/access.md 第 8 节。
 /// </summary>
 [Collection("probe-e2e")]
 public sealed class TrustTests