docs: rewrite README and AGENTS.md etc..
This commit is contained in:
justme committed
1 parent
cc64df3e70
commit
a9bf849697
22 files changed
+514
-665
No files matched your search
@@ -14,7 +14,7 @@ Probe ──TLS 控制 / QUIC Datagram、TCP 测量──> Agent ──长连接
|
||||
|
||||
## 构建
|
||||
|
||||
需要 .NET SDK 10。为应用 根目录的 `global.json` 的 SDK 设置，请从 `backend/` 目录构建：
|
||||
需要 .NET SDK 10（版本见根目录 `global.json`）。从 `backend/` 目录构建：
|
||||
|
||||
```sh
|
||||
cd backend
|
||||
|
||||
@@ -19,11 +19,11 @@
|
||||
|
||||
## 设计原则
|
||||
|
||||
1. **与业务无关**：产品通过扩展点接入：元数据类型、RPC 方法、发件箱消息类型、期望状态文档类型。
|
||||
2. **安全默认值**：Fleet 永远不提供 exec、shell、文件读写、远程下发代码这类方法；节点只响应本地注册过的方法（本地策略 `allow_methods` 还能收窄）；调用对方不支持的方法在本地直接返回 `fleet_unsupported`。
|
||||
3. **权限分离**：注册（`fleet-enroll`，一次性）和常驻业务进程是两个进程；常驻进程不含注册代码，也不使用 `HttpClient`。
|
||||
4. **NativeAOT**：节点侧只依赖 BCL，泛型扩展点通过产品传入的 `JsonTypeInfo<T>` 序列化，不使用反射。
|
||||
5. **更新不在 Fleet 里**：节点进程没有自更新能力。Quadlet 装的节点和 Backend 由退出后 systemd 重新拉镜像、脚本装的节点由宿主机上的更新器验签更新，见 [`docs/ops/deployment.md`](../../docs/ops/deployment.md)；纯二进制节点的更新是待办，见 [`TODO.md`](../../TODO.md)。
|
||||
1. 与业务无关：产品通过扩展点接入：元数据类型、RPC 方法、发件箱消息类型、期望状态文档类型。
|
||||
2. 安全默认值：Fleet 永远不提供 exec、shell、文件读写、远程下发代码这类方法；节点只响应本地注册过的方法（本地策略 `allow_methods` 还能收窄）；调用对方不支持的方法在本地直接返回 `fleet_unsupported`。
|
||||
3. 权限分离：注册（`fleet-enroll`，一次性）和常驻业务进程是两个进程；常驻进程不含注册代码，也不使用 `HttpClient`。
|
||||
4. NativeAOT：节点侧只依赖 BCL，泛型扩展点通过产品传入的 `JsonTypeInfo<T>` 序列化，不使用反射。
|
||||
5. 更新不在 Fleet 里：节点进程没有自更新能力。Quadlet 装的节点和 Backend 由退出后 systemd 重新拉镜像、脚本装的节点由宿主机上的更新器验签更新，见 [`docs/ops/deployment.md`](../../docs/ops/deployment.md)；纯二进制节点的更新见 [路线图](../../docs/roadmap.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/security.md`](../../docs/security/security.md) 第 8 节。
|
||||
- 方法必须声明：每个方法在声明表（`MethodTable`）里写明发起方、请求还是通知、哪些角色可以参与；不存在双向方法，同一个方法名在一个平面里只有一个发起方。`RpcRouter` 在注册、分发和发送三处核对，违规回 `fleet_protocol_violation`，超过上限断开连接。详见 [`docs/security/security.md`](../../docs/security/security.md) 第 6 节。
|
||||
- 与传输无关：同一套路由跑在 wss 上，也跑在 TLS 帧（`u32 长度 | u8 类型 | 正文`）上。
|
||||
|
||||
| 保留方法 | 方向 | 说明 |
|
||||
@@ -79,9 +79,9 @@ connect(wss) → fleet.challenge → fleet.auth → fleet.hello → 状态同步
|
||||
|
||||
本地策略：`allow_methods`、`max_frame_bytes`、`max_inflight`。
|
||||
|
||||
**可靠发件箱**：产品 `EnqueueAsync` → 有界队列（按字节和条数；满时 `DropOldest` 或 `Reject`）→ 发送 → 服务端收件箱（`IInbox`）持久化后 `fleet.outbox.ack` → 移除。至少一次，按 `msg_id`（UUIDv7）去重；在途数据默认限 4 MiB；丢弃会累计缺口，通过 `OnGap` 通知产品。只在内存里，不落盘。
|
||||
可靠发件箱：产品 `EnqueueAsync` → 有界队列（按字节和条数；满时 `DropOldest` 或 `Reject`）→ 发送 → 服务端收件箱（`IInbox`）持久化后 `fleet.outbox.ack` → 移除。至少一次，按 `msg_id`（UUIDv7）去重；在途数据默认限 4 MiB；丢弃会累计缺口，通过 `OnGap` 通知产品。只在内存里，不落盘。
|
||||
|
||||
**期望状态同步**：服务端 `IStateProvider<TDoc>` 给每个节点算 `{version, doc}`，变化时 `NotifyChanged` 推送；节点 `StateHandler<TDoc>` 调和后返回 `{applied_version, rejected[]}`。下发的是**完整快照**，天然幂等，重连后服务端总会重发当前版本。`rejected[]` 带结构化原因（`unsupported`、`budget_exceeded`、`policy_denied`），面板可以直接展示。
|
||||
期望状态同步：服务端 `IStateProvider<TDoc>` 给每个节点算 `{version, doc}`，变化时 `NotifyChanged` 推送；节点 `StateHandler<TDoc>` 调和后返回 `{applied_version, rejected[]}`。下发的是完整快照，天然幂等，重连后服务端总会重发当前版本。`rejected[]` 带结构化原因（`unsupported`、`budget_exceeded`、`policy_denied`），面板可以直接展示。
|
||||
|
||||
## 点对点会话
|
||||
|
||||
@@ -100,6 +100,6 @@ connect(wss) → fleet.challenge → fleet.auth → fleet.hello → 状态同步
|
||||
|
||||
- `ModuleHost`：按依赖顺序启动模块、相反顺序停止，隔离故障，重启时退避。
|
||||
- `NodeConfig`：源生成 JSON 读取，环境变量覆盖，启动时校验。
|
||||
- `ConfigStore`：常驻进程里**唯一**允许写文件的地方，只能写配置目录，写入原子替换、权限 0600；父目录不存在会创建。
|
||||
- `ConfigStore`：常驻进程里唯一允许写文件的地方，只能写配置目录，写入原子替换、权限 0600；父目录不存在会创建。
|
||||
- `ServiceShell`：SIGTERM、Ctrl+C，systemd `sd_notify`、OpenWrt procd（前台运行）和 Windows 服务。
|
||||
- 服务端接口：`IFleetStore`（节点、令牌、公钥、状态版本）、`IStateProvider<TDoc>`、`IInbox`、`INodeEventSink`、`IEnrollmentHook`。MoShiro 把 `IFleetStore` 放进自己的 `moshiro.db`，和业务数据由同一个单写入者写入。
|
||||
@@ -19,7 +19,7 @@ Agent 测量连接失败时，Probe 按 1、2、4、8、16 秒递增等待，再
|
||||
|
||||
## 构建
|
||||
|
||||
需要 .NET SDK 10。为应用 根目录的 `global.json` 的 SDK 设置，请从 `backend/` 目录构建：
|
||||
需要 .NET SDK 10（版本见根目录 `global.json`）。从 `backend/` 目录构建：
|
||||
|
||||
```sh
|
||||
cd backend
|
||||
@@ -38,7 +38,7 @@ dotnet publish probe/src/MoShiro.Probe -c Release -r <RID> -p:PublishAot=true
|
||||
|
||||
### OpenWrt 原生一键部署
|
||||
|
||||
管理端「添加 Probe」提供 **OpenWrt · 原生二进制** 命令，支持 ARM64/x86_64，以 root 执行即可注册并配置 procd。支持 dev/release 自动验签更新、失败回滚，不需要容器；详见 [部署文档](../../docs/ops/deployment.md#原生一键安装与自动更新)。
|
||||
管理端「添加 Probe」提供 OpenWrt · 原生二进制 命令，支持 ARM64/x86_64，以 root 执行即可注册并配置 procd。支持 dev/release 自动验签更新、失败回滚，不需要容器；详见 [部署文档](../../docs/ops/deployment.md#原生一键安装与自动更新)。
|
||||
|
||||
下面是手动注册方式；现代面板需同时传入面板提供的 `--genesis` 和 `--controllers`，否则默认属主检查会拒绝启动。
|
||||
|
||||
|
||||
Reference in new issue
Block a user