# OIP-GoInOne **Repository Path**: orginone/OIP-GoInOne ## Basic Information - **Project Name**: OIP-GoInOne - **Description**: OIP-GoInOne是奥集能开放架构的 代理服务端(网关节点),是整个系统的网关枢纽——所有客户端的入口。OIP-GoInOne树形去中心化部署,每个组织可部署自己的 OIP-GoInOne节点,节点间以树形结构互通。 - **Primary Language**: Rust - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 5 - **Created**: 2026-09-05 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OIP-GoInOne · 统一接入底座 > **文档版本**:v1.1 | **更新**:2026-09-26 | **状态**:正式发布 > **关联**:[OIP-GoInOne-Design.md](../OIP/docs/OIP-GoInOne-Design.md) · [OIP-Protocol.md](../OIP/docs/OIP-Protocol.md) · [OIP.md](../OIP/docs/OIP.md) `OIP-GoInOne` 是开放互联协议(Open Interconnect Protocol, OIP)的 **统一接入底座 / 代理服务端(网关)**,是整个系统的入口枢纽。节点采用**扁平对等(peer-to-peer)联邦**部署:每个组织部署自己的节点,节点间两两直连、各持权威面;所有客户端经 `OIP-GoInOne` 完成认证、路由与上行请求转发。 > Rust 实现(edition 2024;axum + tokio + jsonwebtoken + x25519-dalek + aes-gcm + redis + reqwest + axum-server),对齐 OIP 规范仓库中的设计文档 [OIP-GoInOne-Design.md](../OIP/docs/OIP-GoInOne-Design.md)。 ## 核心能力 | 能力 | 说明 | | --- | --- | | SignalR 实时通道 | `/oip/v1/hub` WebSocket JSON / TXT 线协议 + negotiate 协商;不支持 WebSocket 时降级为 SSE | | DID 认证代理 | JWT access/refresh 轮换(HS256,密钥 ≥ 32 字节,`kid` 随头部下发,支持旧密钥宽限期) | | 安全加密通信 | X25519 密钥协商 + AES-256-GCM 会话加密;`crypto/des.rs` 提供兼容加密 | | 节点握手四步 | hello → ack → negotiate → sync → 建立**对等拓扑**(父子拓扑已移除) | | **跨组织对等路由** | 按 `node.peers` 静态路由与 `peer_grants` 准入寻址,跨节点落点 `/oip/v1/node/forward` | | 服务注册表 | 对等节点 / 服务心跳注册与健康探测 | | 断路器 | 连续失败熔断(Open/HalfOpen/Closed 状态机) | | 限流 | 单实例令牌桶 / 跨实例 Redis 滑动窗口:握手 10/min、登录与刷新 5/min、业务 API 100/min/DID、bootstrap 60/min、全局 5000/min(两种后端实现均参与判定) | | **业务插件接入** | Plugin Registry(§3.7):清单上报/依赖门控/挂载状态机 + bootstrap 挂载树投影 + 启动期挂载一致性自检 | | **运维急停** | `/admin/kill-switch`:HSM(Ed25519)监管签名校验后激活/释放全局断路器,状态经共享键跨实例收敛 | | **可观测** | `/metrics` Prometheus 文本暴露 + 请求/5xx 计数中间件(R9) | | 遗留前端兼容 | `/api/v1/*`、`/graph/*` 前门转译;`/orginone/kernel/*`、`/orginone/anydata/*` 命名空间别名双挂载 | ## 无状态设计 `OIP-GoInOne` 是**无状态网关**(P6 网关无状态、能力降级):进程内 MUST NOT 驻留跨请求的业务状态,因此实例可任意增删、天然支持集群化,无需会话迁移。一切状态按下表外置到权威源或共享缓存层: | 状态类别 | 归属位置 | 说明 | | --- | --- | --- | | 会话映射 / 判定凭据 / 路由表 | 共享缓存层(Redis) | 进程内不驻留,VET 状态变更事件到达即失效(P4 缓存从属于权威源) | | 业务事实与状态 | 本节点的 `OIP-Book`(事实为权威,索引为可重建投影) | 网关只做代理转发与裁定执行,不持有(P1);不再假设全局唯一 Book | | 待投递消息 / 请求日志 | `OIP-Message` | 网关不持久化日志,请求日志异步上报 `OIP-Message` 归集(G8) | | 节点间数据 / 消息同步 | `OIP-Book`(数据)/ `OIP-Message`(消息) | 网关不做节点级同步(P5 对等联邦) | - **网关不落盘**:`OIP-GoInOne` 自身不持久化任何业务数据与访问日志;日志异步上报 `OIP-Message`,上报失败 MUST NOT 阻断业务请求。 - **缓存可失效**:网关缓存 MUST 可被 `OIP-Book` 的权威事件失效,权威状态只在 `OIP-Book`,缓存不得反写。 - **降级不降级为放行**:对端不可达时按 P6 执行能力降级或 fail-closed,MUST NOT 降级为放行。 - **启动期 fail-fast**:`env=production` 而未配置 `redis_uri`、`redis_uri` 已配置但不可达、`auth.jwt_secret` 短于 32 字节、插件挂载一致性自检失败,任一成立即拒绝启动,不进入降级形态。 ## 快速开始 ```bash # 1. 准备配置(模板见 config.example.yaml) cp config.example.yaml config.yaml # 编辑 config.yaml:填写 node.node_did、auth.jwt_secret(≥32 字节)、redis_uri 等 # 2. 构建 / 测试 / Lint(与 CI 门禁一致) cargo build --release --locked # 发布构建 cargo test --all-targets # 单元测试 + tests/cross_service_contract.rs 跨服务契约集成测试 cargo clippy --all-targets -- -D warnings # Lint(零警告) cargo fmt --all --check # 格式检查 # 3. Redis 门控用例(需 REDIS_URI 指向可用实例;CI 以 redis:7 服务提供) REDIS_URI=redis://127.0.0.1:6379 cargo test --lib -- --ignored # 4. 运行(可用 OIP_GOINONE_CONFIG 覆盖配置路径) OIP_GOINONE_CONFIG=config.yaml cargo run ``` ## 配置 配置只经 `config.yaml` 注入:复制模板 `config.example.yaml` 为 `config.yaml` 后填写真实值,`config.yaml` 不入库(`.gitignore` 已排除);配置文件路径可用环境变量 `OIP_GOINONE_CONFIG` 覆盖。凭据一律由部署平台的密钥管理注入,不写入代码。`src/config.rs` 以 `#[serde(deny_unknown_fields)]` 严格解析,未列出的键会被拒绝。 | 键 | 默认值 | 说明 | | --- | --- | --- | | `listen` | (无默认,必填) | HTTP/WS 监听地址;模板为 `"0.0.0.0:8088"` | | `log_level` | `info` | 日志级别(trace/debug/info/warn/error) | | `env` | `development` | 运行环境;`production` 下强制要求 `redis_uri` 非空(P2 状态外置硬门禁) | | `node.node_name` | `本地 goinone 节点` | 节点名称(`node` 段缺省时取该默认值) | | `node.node_did` | `did:oip:local_goinone` | 节点 DID(`node` 段缺省时取该默认值) | | `node.protocol_version` | `v5.24` | 协议版本声明(与 `OIP-Protocol.md` 文档版本一致) | | `node.compliance_level` | `OIP-Core` | 合规级别声明 | | `node.parent_url` | `""` | **已停用**:非空即拒绝启动。父子拓扑已移除,改用 `node.peers` 声明对等路由 | | `node.capabilities` | `vet` / `transfer` / `market` / `audit` / `auth` | 本节点能力清单 | | `node.endpoint` | `""` | 对端可达基址(回程路由与能力令牌 `aud` 推导);对等拓扑必填,不得用回环 | | `node.local_prefixes` | `[]` | 本机承载的 DID 前缀,命中即本地;**不得**写 `did:oip:` 宽前缀 | | `node.local_dids_file` | `""` | 精确 DID 清单文件(`did:oip:` 形态主体);启动期回灌 | | `node.peers` | `[]` | 对等路由:对端 DID ↔ 基址 ↔ 承载前缀;与 `parent_url` 互斥 | | `node.peer_grants` | `{}` | 入站路由登记准入(`endpoints` / `prefixes`);声明了节点面时必须非空,否则拒绝启动 | | `node.require_internal_token` | `false` | 入站令牌门禁;生产建议 `true` | | `node.forward_allowed_operations` | `[]` | `/node/forward` 可直调的 operation 前缀;生产空表回落内置最小白名单 | | `node.capability_tokens` | `enabled=false` | 节点能力令牌(`enabled` / `require` / `ttl_secs` / `allow_any_audience` / `issuer_caps`);对等部署须 `enabled=true` | | `book.base_url` | `""` | 上游 `OIP-Book` 对接地址 | | `book.auth_token` | `""` | `OIP-Book` 内部调用令牌(由密钥管理注入) | | `book.perm_cache_ttl_secs` | `300` | 权限缓存 TTL(秒) | | `book.session_subject_check` | `false` | 会话语义的主体存在性校验(幽灵会话防护);**生产建议开启**。开启后 `verify_access` / `verify_temporary` / `refresh` 按短 TTL 向 Book `GET /oip/v1/target/{did}` 复核主体是否仍存在,被删除主体的令牌被拒(`OIP_4011`) | | `book.subject_cache_ttl_secs` | `60` | 主体存在性缓存 TTL(秒):无事件订阅时即"主体被删除"到"令牌被拒"的最大滞后;`events.mode=nats` 时退化为事件面不可达时的兜底上限 | | `book.subject_unknown_ttl_secs` | `5` | Book 不可达时的短缓存(秒);故障期取 fail-open(放行且不重复探测) | | `data.base_url` | `""` | 数据核地址;留空表示未接入,`DataProxy` 回落节点间转发 | | `data.jwt_secret` | `""` | 与数据核共享的 HS256 密钥(≥32 字节),`OIP-GoInOne` 据此铸造数据核形状令牌 | | `data.token_ttl_secs` | `3600` | 铸造令牌有效期(秒) | | `data.timeout_secs` | `30` | 单次数据核调用超时(秒) | | `auth.jwt_secret` | `""`(必填且 ≥32 字节) | HS256 签名密钥;缺失或过短即拒绝启动 | | `auth.jwt_kid` | `k1` | 当前密钥 ID,随 JWT 头部下发(轮换时递增) | | `auth.jwt_previous_secret` | `""` | 轮换宽限期内作为备用接受验签的旧密钥 | | `auth.access_ttl_minutes` | `15` | Access Token 有效期(分钟) | | `auth.refresh_ttl_days` | `7` | Refresh Token 有效期(天) | | `auth.allow_hs256_fallback` | `false` | 是否接受 HS256 回退;`false` 时用户令牌与节点能力令牌只认 Ed25519 | | `auth.ed25519_private_key` | `""` | 本节点 Ed25519 私钥种子(base64 32B);留空回落 HS256。生产用 `OIP_AUTH_ED25519_KEY` 注入 | | `auth.peer_public_keys` | `{}` | 对端公钥表(键 = 对端 `node.node_did`,值 = base64 32B 公钥);**节点间互信的唯一来源** | | `tls.enabled` | `false` | 启用后以 HTTPS/WSS 对外提供服务(R5) | | `tls.cert_path` / `tls.key_path` | `""`(模板填写 `certs/server.crt` / `certs/server.key`;TLS 关闭时该目录不创建) | TLS 证书与私钥路径(`certs/*.key` 不在库内) | | `proxy.allowed_hosts` | `[]` | 出站代理上游域名白名单;留空不限制域名,仍拦截内网地址 | | `proxy.allow_private` | `false` | 是否允许代理访问内网/回环地址(仅本地调试置 true) | | `cluster.allowed_node_hosts` | `[]` | 跨节点转发目标主机白名单;留空不限制主机,仍拒绝回环/链路本地/组播/保留段 | | `connections.max_connections` | `10000` | 单实例最大连接数 | | `connections.heartbeat_secs` | `30` | 客户端心跳间隔(秒) | | `connections.timeout_secs` | `90` | 服务端超时断开阈值(秒) | | `redis_uri` | `""` | Redis 连接串(会话映射/限流/服务注册/refresh 状态,`env=production` 时必填) | | `events.mode` | `none` | 权威面事件订阅:`none` 不订阅(缓存仅按短 TTL 收敛)/ `nats` 订阅事件后端 | | `events.nats_uri` | `""` | 事件后端地址(与 Book 的 `events.nats_uri` 指向同一 NATS);`mode=nats` 时必填,缺失即拒绝启动。订阅 `oip.events.cache.invalidate` 并据载荷失效本地会话主体缓存(主体被删除/停用即失效,滞后为 0) | | `hsm.public_key` | `""` | base64(STANDARD)Ed25519 监管公钥;留空则 `/admin/kill-switch` 报 ProofInvalid,配置了但非法则在启动期拒绝启动 | > 模板 `config.example.yaml` 未含 `data.*` 与 `cluster.*` 两项:`data.*` 在形态Ⅱ 由内嵌编排层注入;`cluster.allowed_node_hosts` 是节点间对等体白名单加固(留空=不限制主机名,仍拦截回环/链路本地/组播/保留段),需要时按上表在 `config.yaml` 中补充。 > > **平台数值空间**:`belongId` 为纯数字(如 `760429219531726848`)时,前门不再放行,而是交由 Book 按 `platform_spaces` 映射到归属单位后判定(读开放、写限归属单位 + 存储闸)。**必须在 Book 配置该映射**,未登记的平台键读写均拒绝。 ## 对等节点部署(扁平联邦) 本版本**只支持扁平联邦(对等拓扑)**:节点两两直连、各持权威面,路由用 `node.peers` 静态声明。`node.parent_url` / `node.parent_node_did` 已停用,配置非空会在启动期被断言拒绝(见 `src/startup_guard.rs`)。 完整命令、指纹核对、轮换与排障见 [deploy/peer/README.md](deploy/peer/README.md);本节给主干流程与最小配置。 ### 三条结论 1. **公钥必须互相保存,且是双向的。** 节点身份的唯一依据是「DID ↔ 公钥」绑定,接收方靠 `auth.peer_public_keys[iss]` 验签;单向保存会出现「握手能发出、回包验不过」(`OIP_4011`)。最小必要集是**会向你发起节点面请求的对端**,不是全网公钥表:全互联 N 节点每节点 N−1 条,星型则边缘只存中心。 2. **只能走配置文件,没有前端入口。** 节点公钥的唯一来源是 `auth.peer_public_keys`(或整表覆盖的环境变量 `OIP_AUTH_PEER_PUBKEYS`)。前端的 `/oip/v1/auth/auth-key` 是**用户主体**的 DID 登录公钥,注册到那里对节点间认证无效。`node.peer_manifest_file` 的签名 Manifest 只分发**路由**(`serial` / `valid_until` / `peers`),不含公钥。 3. **改完必须重启。** 配置没有热加载;重启后由启动期安全断言做 fail-closed 自检,不合格直接拒绝启动。 ### 最小配置(A 节点视角) ```yaml listen: "0.0.0.0:8088" env: "production" node: node_did: "did:oip:node-a" endpoint: "https://a.oip.example.com" parent_url: "" # 已停用字段;必须留空,对等路由见 peers local_prefixes: ["did:oip:node-a:"] # 本机承载的主体;不要写 did:oip: 宽前缀 require_internal_token: true peers: # 出站路由:哪些 DID 交给谁 - node_did: "did:oip:node-b" endpoint: "https://b.oip.example.com" did_prefixes: ["did:oip:node-b:"] did_exact: [] legacy_dids: false peer_grants: # 入站准入:允许对端登记哪些基址/前缀 "did:oip:node-b": endpoints: ["https://b.oip.example.com"] prefixes: ["did:oip:node-b:"] forward_allowed_operations: # /node/forward 可直调的 operation 前缀 ["message.", "DataNotify", "DataProxy", "Push.local", "relation."] capability_tokens: enabled: true require: false # 换钥完成前先 false,全部就绪后置 true ttl_secs: 120 # 必须 ≥ 90(对端签 120s,接收侧上限 ttl+30) allow_any_audience: false issuer_caps: "did:oip:node-b": [forward] # 只代转发就不要给 sync auth: allow_hs256_fallback: false ed25519_private_key: "" # 由 OIP_AUTH_ED25519_KEY 注入,不写入文件 peer_public_keys: "did:oip:node-b": "" ``` 四个表各管一件事,缺一个就会在对应方向失败:`peer_public_keys` 验身份、`issuer_caps` 定能力、`peer_grants` 定路由登记准入、`peers` 定出站去向。 ### 部署步骤 1. **生成密钥(每节点一次)**:Ed25519,私钥种子 32 字节 `chmod 600`,**禁止跨节点复用**、不进版本库/镜像/compose。 2. **带外交换公钥并核对指纹**:公钥不是秘密,可走任意信道;但必须双方比对 SHA-256 指纹,这是唯一能发现中间人替换的环节。 3. **写本节点身份**:`node.node_did`、`endpoint`、`local_prefixes`(UUID 形态主体改用 `local_dids_file` 精确清单);不要配置 `parent_url` / `parent_node_did`(已停用)。 4. **逐对端写公钥**:`auth.peer_public_keys`,键与对端 `node.node_did` **逐字一致**(大小写、下划线、无尾随空格)。 5. **按用途授能力**:`issuer_caps`——代转发 `forward`、上报路由 `sync`、插件/服务 `service`;不顺手全给。 6. **声明路由与准入**:`peers` + `peer_grants`;`peer_grants` 不能空着(声明了节点面又空表会被启动断言拒绝)。 7. **启动验证**:无令牌转发须 `401/4011`;双向握手 `status=ok, write_allowed=true`;双向消息拿到 `message_id`;数据面读 200。 8. **收紧**:全部对端换成 Ed25519 后把 `capability_tokens.require` 置 `true` 并复验;建议再用旧私钥签一张令牌确认被拒。 ### 验证 ```bash OIP_SELF_SEED="$(cat /etc/oip/a.seed)" \ OIP_PEER_SEED="$(cat /etc/oip/b.seed)" \ node deploy/peer/peer-message-test.mjs \ --self-did did:oip:node-a --self-url http://127.0.0.1:8088 \ --peer-did did:oip:node-b --peer-url https://b.oip.example.com \ --self-subject did:oip:<本端主体> --peer-subject did:oip:<对端主体> \ --data-probe ``` 覆盖两端门禁、双向握手、双向 `message.send` 与数据面读,任一项失败退出码为 1。第二方向用对端私钥签令牌后请求本端,验签与落库路径与真实入站一致。 要在真实网络路径上验证反向方向(NAT / 反向隧道 / 防火墙 / 远端出口),加 `--remote-ssh ` 与远端视角的本端基址 `--self-url-from-remote `,反向条目会标注 `·远端执行`;远端只需 `sh`、`curl`、`openssl`,不需要 Node。详见 [deploy/peer/README.md](deploy/peer/README.md#L330-L351)。 ### 轮换与回滚 - **轮换**:新密钥对 → 公钥带外发给所有对端 → 各对端改 `peer_public_keys` 并重启 → 本节点换 `OIP_AUTH_ED25519_KEY` 并重启 → 双向复验。实现按 DID 单值匹配,不支持同时挂两把公钥,因此公钥更新到私钥更新之间存在短暂验签失败窗口,**安排在同一维护窗口内完成**。 - **回滚**:配置留 `config.yaml.bak.<用途>-<日期>`,覆盖后重启;二进制由部署脚本逐份留 `*.bak.<时间戳>`。撤销某对端只需删除它在 `peer_public_keys` / `issuer_caps` / `peer_grants` / `peers` 的条目,其他节点零影响。 ### 常见错误 | 现象 | 多半是 | | --- | --- | | `4011 验签未通过` | 公钥不匹配;键与对端 DID 不是逐字一致;对端仍在用旧私钥 | | `4011 受众不符` | 出站 `aud` 推导不到本节点,检查 `peer_grants.endpoints` | | `4011 时效超出允许范围` | 接收侧 `ttl_secs` 小于对端签发值 − 30 | | `4031 签发节点未获能力授权` | `issuer_caps` 缺该 DID 或对应能力 | | `4094 跨节点写面互操作缺少版本声明` | 写面请求缺 `x-oip-peer-protocol-version` | | 启动报「peer_grants 为空」 | 声明了节点面但没配准入表 | | 请求没到对端、落回本地 | `local_prefixes` 把对端主体判成本地,或 `peers` 前缀写错 | ### 安全约束 - 私钥只落本机(`0600`),由 `OIP_AUTH_ED25519_KEY` 注入;仓库、镜像、compose 文件里不得出现。 - 公钥可明文传输,但必须带外核对指纹;`OIP_AUTH_PEER_PUBKEYS` 是**整表覆盖不是合并**,生产建议只用 YAML。 - 信任根刻意不做远程可写:能远程改公钥表 = 能远程提权。需要自动化时沿用 Manifest 的签名 + `serial` 水位机制,而不是新增无签名写入端点。 - 能力按最小集授予;`allow_ungranted_peers` 仅限联调,生产 MUST NOT 打开。 ## 持续集成 `.github/workflows/ci.yml` 在 push(`master`/`main`)与 `pull_request` 时执行,运行于 `ubuntu-latest`,工具链 Rust `1.98.1`(含 `rustfmt`、`clippy`),并以服务容器提供 `redis:7`(注入 `REDIS_URI`): ```bash cargo fmt --all --check cargo clippy --all-targets -- -D warnings cargo test --all-targets cargo test --lib -- --ignored # Redis 集成用例 cargo build --release --locked ``` `.github/workflows/contract-check.yml` 执行协议面漂移校验,且为 **fail-closed**:若同级目录不存在 `../OIP/tools/gen_protocol.py`,先尝试 `git clone --depth 1 https://gitee.com/orginone/OIP.git ../OIP`;克隆后仍不可用则报错退出(非跳过)。可用时执行 `python3 ../OIP/tools/gen_protocol.py --check`,任何漂移即失败。`src/protocol_gen.rs`、`src/topics_gen.rs` 由该脚本生成。 ## API 端点 感知设备通过已认证的 `Request { module: "iot", action, params }` 调用 `RegisterCaptureDevice`、`ListDevices` 和 `ConfigureCapture`。调用者身份取当前会话,设备使用按 Book 的严格单位成员口径判定;`iot_read.base_url` 和服务凭据由部署配置提供,不下发给浏览器。内部遥测证明适配器位于 `/internal/iot/telemetry/verify`,需要独立内部凭据及有效设备证明,不作为匿名公共入口。 `src/router.rs` 的 `build()` 为全部端点的唯一装配点;`DECLARED_ROUTES` 是由 `tools/gen_declared_routes.py` 派生的声明表(104 项),供插件挂载一致性门禁与前门转译表使用。CI 运行脚本的 `--check` 与解析器测试,忽略注释中的示例路径,核对声明与实际挂载。协议 REST 表由 `../OIP/spec/routes.json` 生成;只读 POST 的写面例外必须在规范中注明理由,不能仅按 HTTP 方法推断权限。 ### 认证与节点 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/oip/v1/auth/login` | DID 登录,签发 access/refresh token | | POST | `/oip/v1/auth/refresh` | 刷新 access token | | POST | `/oip/v1/auth/token-auth` | 校验既有 accessToken,返回持有者 DID(验证面 D2) | | GET | `/oip/v1/bootstrap` | 匿名节点能力发现 | | POST | `/oip/v1/bootstrap` | 节点能力声明握手 | | POST | `/oip/v1/node/handshake/hello` | 握手第一步:问候 | | POST | `/oip/v1/node/handshake/ack` | 握手第二步:确认身份 | | POST | `/oip/v1/node/handshake/negotiate` | 握手第三步:协商 | | POST | `/oip/v1/node/handshake/sync` | 握手第四步:同步 | | POST | `/oip/v1/node/forward` | 跨节点转发落点(对等路由) | ### 插件与消息接入 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/oip/v1/plugins/register` | 业务服务插件上报(清单入库) | | POST | `/oip/v1/plugins/status` | 插件心跳续报 / 状态查询 | | POST | `/oip/v1/message/register` | `OIP-Message` 服务接入注册 | | POST | `/oip/v1/message/notify` | 消息投递通知接入 | ### 实时通道 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/oip/v1/hub/negotiate` | SignalR 连接协商 | | GET / POST | `/oip/v1/hub` | SignalR 实时通道(WebSocket;浏览器不支持 WebSocket 时降级为 SSE) | | POST | `/orginone/kernel/hub/negotiate`、`/orginone/anydata/hub/negotiate` | 命名空间别名协商 | | GET / POST | `/orginone/kernel/hub`、`/orginone/anydata/hub` | 命名空间别名通道 | ### REST 降级通道(§3.11.7) | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/oip/v1/rest/request`、`/oip/v1/rest/requests` | 通用业务请求 | | POST | `/oip/v1/rest/auth` | 认证 | | POST | `/oip/v1/rest/dataproxy`、`/oip/v1/rest/datanotify`、`/oip/v1/rest/virtualnotify` | 数据代理与通知 | | POST | `/oip/v1/rest/qrauth` | 扫码认证 | | POST | `/oip/v1/rest/httpforward` | HTTP 转发 | | GET | `/oip/v1/rest/online` | 在线列表 | | GET | `/oip/v1/rest/createtemporarytoken` | 铸造临时令牌 | ### System API(§3.11.2a) | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/oip/v1/system/online` | 在线列表 | | GET | `/oip/v1/system/connection-id` | 当前连接 ID | | POST | `/oip/v1/system/temporary-token` | 铸造临时令牌 | | POST | `/oip/v1/system/http-forward` | HTTP 转发 | | POST | `/oip/v1/system/data-share` | 数据分享 | | POST | `/oip/v1/system/load-share` | 加载分享 | ### 命名空间别名与遗留路径 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST / GET | `/orginone/kernel/rest/*`、`/orginone/anydata/*` | 与 `/oip/v1/*` 双挂载的同源别名(`auth`、`tokenAuth`、`createTemporaryToken`、`temporaryTokenAuth`、`qrauth`、`dataShare`、`loadShare`、`dataProxy`、`dataNotify`、`virtualNotify`、`request`、`requests`、`httpForward`、`online`,并含 `tokenauth` 等小写形式) | | ANY | `/api/v1/*`、`/graph/*` | 遗留前端路径别名,由前门转译为内核操作(形态Ⅱ 桌面终端) | ### 运维与探针 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST / GET | `/admin/kill-switch` | 运维急停:POST 需 HSM 监管签名以激活/释放,GET 免签查询断路器状态 | | GET | `/metrics` | Prometheus 指标文本暴露(R9) | | GET | `/healthz` / `/readyz` | 健康检查 | **SignalR Hub 方法**(`HUB_METHODS`,§3.9 G4): | 方法 | 说明 | | --- | --- | | `Auth.Login` | 握手后 DID 认证,返回 connection_id | | `Auth` | 认证 action 分发(`AUTH_METHODS`:`Login` / `Refresh` / `TokenAuth`) | | `TokenAuth` | 校验既有 accessToken,返回持有者 DID(验证面 D2) | | `Request` / `Requests` | 通用业务请求,按插件注册表就近路由(未挂载返回能力降级 G5) | | `DataProxy` / `DataNotify` | 数据代理与数据变更通知 | | `Online` / `Presence.GetOnlineDids` | 在线 DID 查询 | | `GetConnectionId` | 当前连接 ID | | `Ping` | 心跳 | | `Node.RoutingInfo` | 节点拓扑信息 | ## 目录结构 ```text OIP-GoInOne/ ├── Cargo.toml / Cargo.lock # 工程清单与锁定依赖(构建走 --locked) ├── config.example.yaml # 配置模板(config.yaml 不入库) ├── Dockerfile # 生产镜像(多阶段构建,rust:1.98-bookworm → debian:bookworm-slim) ├── docker-compose.yml # 本地编排:oip-goinone + Redis ├── deploy/ # 节点部署示例(edge-read-replica:只读 Book 副本分流;peer:同构对等联邦, │ # 含部署指南 README.md、配置模板与 peer-message-test.mjs 互通测试脚本) ├── deny.toml # cargo-deny 依赖策略 ├── README.md / README.en.md / AGENTS.md ├── .github/workflows/ # ci.yml(构建/测试/Redis 门控)、contract-check.yml(协议面漂移门禁) ├── tests/ │ └── cross_service_contract.rs # 跨服务契约集成测试 └── src/ ├── main.rs # 二进制入口(薄壳,含 JWT 密钥长度校验、插件挂载自检、优雅停机) ├── lib.rs # 库入口(模块声明) ├── auth/ # DID 认证代理(JWT 签发/验证/轮换,refresh 状态存储) ├── breaker.rs # 断路器状态机 ├── clock.rs # 时间抽象(SystemClock / ManualClock) ├── config.rs # 配置加载与校验 ├── connections/ # 连接注册与管理(顶替/心跳/超时) ├── crypto/ # X25519 + AES-256-GCM(cipher)/ JWT(jwt)/ 兼容 DES(des) ├── error.rs # OipError / OipErrorCode 与 HTTP 状态映射 ├── events.rs # 权威面事件订阅(据 OIP-Book `cache.invalidate` 失效本地缓存) ├── handlers/ # HTTP + SignalR Hub 处理器(admin 急停、hub、message、plugin、rest、front_door) ├── hsm.rs # HSM 监管签名校验(急停端点,只持公钥) ├── ids.rs # DID / VET / 连接 ID 生成 ├── metrics.rs # Prometheus 指标(/metrics 文本暴露 + 请求/5xx 中间件) ├── node/ # 节点身份与握手(hello/ack/negotiate/sync) ├── plugin/ # 业务服务插件注册表(清单/依赖门控/挂载状态机/自检) ├── protocol_gen.rs # 协议面生成物(由 OIP 规范仓库经 gen_protocol.py 派生) ├── proxy/ # 上行代理(data / front_door / routes / guard 出站策略) ├── ratelimit.rs # 令牌桶 + Redis 滑动窗口限流 ├── redis_mirror.rs # Redis 状态镜像(内存表为权威,写路径 fire-and-forget 镜像) ├── registry/ # 服务注册表(心跳/健康) ├── response.rs # 统一 OperateResult 响应 ├── router.rs # 路由装配 + DECLARED_ROUTES 声明表 ├── routing/ # 跨组织对等路由(寻址/转发/node/forward 落点) ├── signalr/ # SignalR JSON / TXT 线协议编解码 ├── sse.rs # SignalR 会话注册表(不支持 WebSocket 时降级为 SSE) ├── state.rs # 全局状态与后端选型 ├── topics.rs # 事件主题注册表与主题模式匹配 └── topics_gen.rs # 主题生成物(由 OIP 规范仓库经 gen_protocol.py 派生) ``` ## 测试 | 层级 | 位置 | 说明 | | --- | --- | --- | | 单元测试 | 各模块 `#[cfg(test)]` | JWT 签发/轮换、X25519 协商与 AES-GCM 加解密、断路器、限流、出站策略、SignalR 编解码 | | 路由集成测试 | `src/router.rs` 的 `#[cfg(test)]` | 声明表 ↔ 挂载一致性、命名空间别名可达性(`tower::ServiceExt::oneshot`) | | Hub 端到端 | `src/handlers/hub.rs` 的 `#[cfg(test)]` | JSON 与 TXT 两种线协议的完整会话流程 | | 跨服务契约集成测试 | `tests/cross_service_contract.rs` | 与 `OIP-Book` / `OIP-Message` 的契约面(10 个用例) | | Redis 门控用例 | `#[ignore]` + `REDIS_URI` | 需真实 Redis;未设置时打印跳过信息并返回 | ## 安全基线 - `auth.jwt_secret` 必须 ≥ 32 字节,入口与 AuthService 双重校验,缺失或过短即拒绝启动 - 配置仅经 `config.yaml` 注入(该文件不入库),凭据不得硬编码 - 500 类错误对外返回通用信息,异常详情只进进程内日志;网关不持久化业务数据与访问日志,请求日志异步上报 `OIP-Message` - 认证、bootstrap、节点握手、节点转发、插件与消息接入、REST 与前门业务入口均受限流(单实例令牌桶 / 跨实例 Redis 滑动窗口),并共享全局 5000/min 桶;`/oip/v1/hub` 实时通道、`/admin/kill-switch`、`/metrics` 与健康探针不设端点配额 - 出站代理与跨节点转发各受独立白名单约束,回环 / 私有 / 链路本地(含 `169.254.169.254` 云元数据)/ 组播 / `0.0.0.0/8` / CGNAT / `240.0.0.0/4` 保留段一律拒绝;DNS 解析结果同样复核,防 DNS 重绑定 - `/admin/kill-switch` 的激活与释放必须经 HSM 公钥验签,未配置 `hsm.public_key` 时该端点不可用(返回 ProofInvalid) ## 文档 - 设计文档:[OIP-GoInOne-Design.md](../OIP/docs/OIP-GoInOne-Design.md) - 对等节点部署(公钥交换、配置流程、互通测试):[deploy/peer/README.md](deploy/peer/README.md) - 协议规范:[OIP-Protocol.md](../OIP/docs/OIP-Protocol.md) - 测试策略:[OIP-Test-Strategy.md](../OIP/docs/OIP-Test-Strategy.md) - 协议面生成脚本:[gen_protocol.py](../OIP/tools/gen_protocol.py) - 开发约定:[AGENTS.md](AGENTS.md) - License: MIT 商城交付补齐:`delivery.Append` 接受原件承载字段 `sourceShareId`,由 Book 内部 `/oip/v1/data/check-access` 裁决权限,核验来源、落点副本、发布状态和内容指纹。共享物理分区按 `shareId` 限定读取;重复请求以服务端派生的不可变交付 ID 锚定原始 RFC3339 时间,兼容数据核无时区的本地日期投影,不猜测时区、不重复记账。部署顺序及评审状态见 [本地 RFC](../OIP/docs/rfc/mall-delivery-access-local.md)。必须先部署对应 Book 接口;不能以客户端字段代替授权。 数据代理保留 Collection 文档、查询条件及 Object.Set 内容中的业务 `belongId`;数值物理分区只用于路由和租户令牌,不覆盖应用归属。交付事实中的数字主体编号必须经 Book 查询到实际映射,不接受按编号尾段或分区哈希推断主体。 交付溯源(`delivery.Trace`)的读面按**链上当事人**判定,不复用归属空间 PDP:一跳对 `fromOwnerId` / `toOwnerId` / `originOwnerId` 可见,`originOwnerId` 由 `delivery.Append` 从源跳派生、调用方不可自报。前门每轮调用数据核内部面 `POST /internal/ledger/party-read`(`x-oip-internal-token` 把门),由数据持有方按谓词下推过滤;前门只做 BFS 聚合。逐 owner 调 `check-relation-auth` 会把「链上当事人」错换成「空间读者」——溯源根通常不是下游主体的空间成员,而无关的空间成员又会被放行取行,故不采用。`owners` 由调用方声明、不做全库枚举(响应 `scope=declared`);`delivery.Append` 会向每个当事人与溯源根的分区追加同 `id` 的投影(`receipt: true`),每个主体只声明自身即可重建自己可见的链。历史跳用 `POST /internal/ledger/rebuild-origin` 补投影(只追加、不改写,`apply:false` 仅审计);未补写前按「当事人可见」降级,`trimmed` 如实标注。跨节点投影/读取经 `delivery.Receipt` / `delivery.PartyRead` 走 `/oip/v1/node/forward`,由持有节点按同一谓词复核;默认目标节点 MUST 直接承载该分区。开启 `node.delivery_relay`(或 `OIP_NODE_DELIVERY_RELAY=1`,默认关闭)后允许中间节点多跳转发,受 `node.delivery_relay_max_hops`(默认 2)限制;caller 归因仍由每一跳校验,多跳部署 MUST 逐跳配置 `peer_grants`。自定义 `node.forward_allowed_operations` MUST 包含这两项。`rebuild-origin` 只在本节点执行且只覆盖本节点分区;跨节点历史跳用运维命令 `oip-delivery-backfill --owner [--owner ...] [--apply]`(配置用 `OIP_GOINONE_CONFIG` 指向节点 config.yaml):扫描本节点分区、计算溯源根,并按 `delivery.Receipt` 把投影投递到远端当事人/溯源根;需在各持有节点分别执行,缺省只审计。两项都携带 `caller_did`,对端 MUST 能验证签发节点(能力令牌 + `peer_public_keys`/`peer_grants`);仅静态共享令牌时对端会拒绝声明 caller,投影/读取会如实失败并进 `issues`。 ### 历史失败交付的受控恢复 `tools/repair_application_delivery.py` 只处理明确指定的一次应用分发,默认只审计。先部署 Book 与 GoInOne 修复,再由有正常读写权限的操作人员通过环境变量 `OIP_REPAIR_ACCESS_TOKEN` 提供当前访问令牌,显式填写 `--endpoint`、`--source-space`、`--source-partition`、`--application-id`、`--controller`、`--target-space` 和 `--copy-id`。地址使用 HTTPS(隔离本地测试可使用回环 HTTP),工具拒绝携带凭据的地址和接口重定向。 确认审计结果后,增加 `--apply --backup <新备份文件>` 才执行。工具校验登记主体、原件/副本内容及已知分区覆盖特征,备份后逐条比较并更新,回读通过再调用正常 `delivery.Append` 补记原操作;重复执行仍只有一条交付事实。未知归属、内容变化、权限不足或已记账后仍需改写的记录均拒绝处理。不会新增授权、直接写台账或自动修改云端数据;中途失败保留备份,修正原因后重新审计。备份包含业务数据,应按原数据权限保管。运行工具测试:`python -m unittest discover -s tools -p test_repair_application_delivery.py`(Python 3.9+)。 交付授权前的数字主体和承载编号先经 Book 已登记映射解析为 DID,不拼接 DID 前缀;数字控制主体仍参与归属一致性核验,无法解析的旧分区归属需经受权恢复工具审计修复,不回落为承载空间权限。