Nexa-net 整体架构设计

版本: v0.2.0 | 最后更新: 2026-04-16 | 状态: Phase 1-12 完成 ✅

1. 设计哲学

1.1 问题背景

当前的互联网基础设施（HTTP/HTML）是为人类消费设计的，而非机器对机器（M2M）通讯。在自治智能体（Autonomous Agents）大规模协作的场景下，传统方案存在以下问题：

问题	传统方案	影响
数据冗余	文本 JSON 序列化	传输体积大，Token 消耗高
寻址低效	DNS + URL 模式	Agent 需要知道精确地址
认证复杂	API Key / OAuth	需要人工干预配置
结算缺失	外部支付服务	无法实现 M2M 微交易
侵入性强	需要重写 Agent 逻辑	集成成本高

1.2 核心设计原则

Nexa-net 的设计遵循以下核心原则：

1.2.1 非侵入式集成 (Non-invasive Integration)

┌─────────────────────────────────────────────────────────────┐
│                      传统方案                                │
│  ┌─────────┐     需要重写     ┌─────────┐                   │
│  │ Agent A │ ───────────────▶│ Agent B │                   │
│  └─────────┘                 └─────────┘                   │
│       │                           ▲                         │
│       └──── 手动适配 HTTP API ────┘                         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      Nexa-net 方案                           │
│  ┌─────────┐    ┌────────────┐    ┌────────────┐    ┌─────────┐
│  │ Agent A │───▶│Nexa-Proxy A│───▶│Nexa-Proxy B│───▶│ Agent B │
│  └─────────┘    └────────────┘    └────────────┘    └─────────┘
│       │                ▲                  ▲                │
│       └── 本地工具调用 ──┘                  └── 本地工具注册 ──┘
│                    自动路由、加密、结算                        │
└─────────────────────────────────────────────────────────────┘

实现方式： 每个 Agent 节点在本地运行一个轻量级的守护进程——Nexa-Proxy。Agent 只需将 Nexa-Proxy 视为一个名为 nexa_network_call 的本地工具即可。

1.2.2 语义优先 (Semantic-First)

Agent 不通过 URL 寻找目标，而是通过**意图（Intent）**寻找：

# 传统方式：需要知道精确的 URL
response = requests.post("https://api.service-b.com/v1/translate", ...)

# Nexa-net 方式：描述意图，系统自动路由
result = nexa_call(intent="translate English PDF to Chinese", data=pdf_bytes)

1.2.3 零信任安全 (Zero-Trust Security)

在 100% 由机器组成的网络中，传统的密码和 IP 白名单失效。Nexa-net 采用基于密码学的绝对零信任架构：

身份验证： 基于非对称密钥的去中心化标识（DID）
通信加密： 强制双向 TLS（mTLS）
权限控制： 可验证凭证（Verifiable Credentials）

1.2.4 原生经济 (Native Economy)

去中心化网络中，没有免费的算力。Nexa-net 内置微交易机制：

状态通道： Layer 2 高频微支付
预算控制： 防止"死循环调用"耗尽资源
激励对齐： 服务提供者获得 Token 奖励

2. 架构总览

2.1 系统架构图

                                    ┌─────────────────────────────────────┐
                                    │         Nexa-net Network            │
                                    │                                     │
┌──────────────┐                    │  ┌─────────────────────────────┐    │
│   Agent A    │                    │  │      Supernode Cluster      │    │
│  (LangChain) │                    │  │  ┌─────────┐ ┌─────────┐    │    │
└──────┬───────┘                    │  │  │Registry │ │  Relay  │    │    │
       │                            │  │  │ Service │ │ Service │    │    │
       ▼                            │  │  └────┬────┘ └────┬────┘    │    │
┌──────────────┐                    │  │       │           │         │    │
│ Nexa-Proxy A │◄───────────────────┼──┼───────┴───────────┴────────┼────┤
│ ┌──────────┐ │                    │  │     Semantic DHT           │    │
│ │Data Plane│ │                    │  │     STUN/TURN              │    │
│ │Ctrl Plane│ │                    │  └─────────────────────────────┘    │
│ └──────────┘ │                    │                                     │
└──────┬───────┘                    │         ┌─────────────────┐          │
       │                            │         │   P2P Mesh      │          │
       │ Encrypted RPC              │         │  (WebRTC Data)  │          │
       │ over mTLS                  │         └────────┬────────┘          │
       │                            │                  │                   │
       ▼                            │  ┌───────────────┴───────────────┐  │
┌──────────────┐                    │  │                               │  │
│ Nexa-Proxy B │                    │  ▼                               ▼  │
│ ┌──────────┐ │                    │  ┌──────────────┐    ┌──────────────┐│
│ │Data Plane│ │                    │  │ Nexa-Proxy C │    │ Nexa-Proxy D ││
│ │Ctrl Plane│ │                    │  └──────┬───────┘    └──────┬───────┘│
│ └──────────┘ │                    │         │                   │       │
└──────┬───────┘                    │         ▼                   ▼       │
       │                            │  ┌──────────────┐    ┌──────────────┐│
       ▼                            │  │   Agent C    │    │   Agent D    ││
┌──────────────┐                    │  │  (AutoGen)   │    │  (Custom)    ││
│   Agent B    │                    │  └──────────────┘    └──────────────┘│
│   (AutoGen)  │                    │                                     │
└──────────────┘                    └─────────────────────────────────────┘

2.2 组件职责

组件	职责	部署位置
Agent	业务逻辑执行，大模型推理	用户机器/容器
Nexa-Proxy	协议转换、路由、加密、结算	Agent 同机部署
Supernode	语义路由表、NAT 穿透、中继	高可用服务器集群
P2P Mesh	直连通道，降低延迟	Agent 之间

2.3 新增模块 (v0.2.0)

模块	路径	功能
Embedding	`src/discovery/embedding/`	文本向量化，支持 ONNX/Mock 后端
Storage	`src/storage/`	持久化存储，支持 Memory/PostgreSQL/Redis
Security	`src/security/`	审计日志、密钥轮换、速率限制、加密存储
Benchmarks	`benches/`	45 个 Criterion 性能基准测试（含 REST API 延迟）
Test Infrastructure	`tests/common/`	TestProxy (HTTP E2E)、MockNetwork (故障恢复)、TestAgent、TestEnvironment

3. 四层架构模型

Nexa-net 采用分层架构设计，每层职责明确、接口清晰：

┌────────────────────────────────────────────────────────────────┐
│                    Layer 4: Economy Layer                      │
│              资源管理与机器微交易 (M2M Economy)                   │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│    │State Channel│  │Micro-Receipt│  │Token Engine │          │
│    └─────────────┘  └─────────────┘  └─────────────┘          │
├────────────────────────────────────────────────────────────────┤
│                   Layer 3: Transport Layer                     │
│                  传输与协商协议 (RPC Protocol)                  │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│    │  Handshake  │  │Streaming RPC│  │Serialization│          │
│    └─────────────┘  └─────────────┘  └─────────────┘          │
├────────────────────────────────────────────────────────────────┤
│                   Layer 2: Discovery Layer                     │
│               语义发现与能力路由 (Semantic Routing)             │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│    │Capability   │  │  Semantic   │  │    DHT      │          │
│    │   Schema    │  │   Router    │  │             │          │
│    └─────────────┘  └─────────────┘  └─────────────┘          │
├────────────────────────────────────────────────────────────────┤
│                   Layer 1: Identity Layer                      │
│               身份与零信任网络 (Zero-Trust Security)            │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│    │   Nexa-DID  │  │    mTLS     │  │     VC      │          │
│    └─────────────┘  └─────────────┘  └─────────────┘          │
└────────────────────────────────────────────────────────────────┘

3.1 Layer 1: 身份与零信任网络层

详细文档： IDENTITY_LAYER.md

核心职责：

去中心化身份标识（Nexa-DID）
双向 TLS 认证（mTLS）
可验证凭证（Verifiable Credentials）

关键接口：

interface IdentityLayer {
  // 生成新的 DID
  generateDID(): DID;
  
  // 签名数据
  sign(data: bytes, privateKey: Key): Signature;
  
  // 验证签名
  verify(data: bytes, signature: Signature, publicKey: Key): boolean;
  
  // 发放凭证
  issueCredential(subject: DID, claims: Claims): VC;
  
  // 验证凭证
  verifyCredential(vc: VC): boolean;
}

3.2 Layer 2: 语义发现与能力路由层

详细文档： DISCOVERY_LAYER.md

核心职责：

能力清单注册与发现
基于向量语义的路由算法
分布式语义哈希表（Semantic DHT）

关键接口：

interface DiscoveryLayer {
  // 注册能力
  registerCapability(schema: CapabilitySchema): void;
  
  // 注销能力
  unregisterCapability(endpointId: string): void;
  
  // 语义路由
  route(intent: Intent): Candidate[];
  
  // 更新节点状态
  updateNodeStatus(nodeId: DID, status: NodeStatus): void;
}

3.3 Layer 3: 传输与协商协议层

详细文档： TRANSPORT_LAYER.md

核心职责：

动态协议协商
结构化流式 RPC
高效二进制序列化

关键接口：

interface TransportLayer {
  // 建立连接
  connect(target: DID, intent: Intent): Connection;
  
  // 协商协议
  negotiate(connection: Connection): Protocol;
  
  // 执行 RPC 调用
  invoke(connection: Connection, method: string, params: bytes): Stream;
  
  // 关闭连接
  close(connection: Connection): void;
}

3.4 Layer 4: 资源管理与微交易层

详细文档： ECONOMY_LAYER.md

核心职责：

状态通道管理
微交易收据
Token 结算引擎

关键接口：

interface EconomyLayer {
  // 开启状态通道
  openChannel(peer: DID, deposit: Token): Channel;
  
  // 创建微交易收据
  createReceipt(channel: Channel, amount: Token): Receipt;
  
  // 验证收据
  verifyReceipt(receipt: Receipt): boolean;
  
  // 关闭通道并结算
  closeChannel(channel: Channel): Settlement;
}

4. 核心组件

4.1 Nexa-Proxy

Nexa-Proxy 是 Nexa-net 的核心组件，采用 Sidecar 模式部署。

4.1.1 架构设计

┌─────────────────────────────────────────────────────────────┐
│                       Nexa-Proxy                            │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Control Plane                       │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│   │
│  │  │Identity  │ │Discovery │ │Channel   │ │Monitor   ││   │
│  │  │Manager   │ │Client    │ │Manager  │ │& Metrics ││   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘│   │
│  └─────────────────────────────────────────────────────┘   │
│                           │                                 │
│                           ▼                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   Data Plane                          │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│   │
│  │  │RPC       │ │Serializer│ │Encryptor │ │Router    ││   │
│  │  │Engine    │ │          │ │          │ │          ││   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘│   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   Local Interface                     │   │
│  │  ┌──────────────────────────────────────────────────┐│   │
│  │  │  Unix Socket / localhost:port                    ││   │
│  │  │  Tool: nexa_network_call                         ││   │
│  │  └──────────────────────────────────────────────────┘│   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│     Agent       │
│  (LangChain/    │
│   AutoGen/etc)  │
└─────────────────┘

4.1.2 配置示例

# nexa-proxy.yaml
identity:
  did: "did:nexa:1a2b3c4d5e6f..."
  key_file: "/var/lib/nexa/keys/private.key"
  
network:
  supernodes:
    - "supernode1.nexa.net:443"
    - "supernode2.nexa.net:443"
    - "supernode3.nexa.net:443"
  listen_address: "127.0.0.1:7070"
  
capabilities:
  schema_file: "/etc/nexa/capabilities.yaml"
  
economy:
  default_budget: 1000
  max_channel_balance: 10000
  
logging:
  level: "info"
  format: "json"

4.2 Supernode

Supernode 是网络中的高可用节点，负责路由表维护和 NAT 穿透。

4.2.1 服务组件

┌─────────────────────────────────────────────────────────────┐
│                       Supernode                             │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Registry   │  │    Relay     │  │    STUN      │      │
│  │   Service    │  │   Service    │  │   Service    │      │
│  │              │  │              │  │              │      │
│  │ - DHT 存储   │  │ - 消息中继   │  │ - NAT 穿透   │      │
│  │ - 能力索引   │  │ - 流量统计   │  │ - IP 发现    │      │
│  │ - 节点状态   │  │ - 负载均衡   │  │              │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                    Semantic DHT                       │  │
│  │  ┌─────────────────────────────────────────────────┐ │  │
│  │  │  Vector Index (HNSW / IVF)                      │ │  │
│  │  │  - Capability Embeddings                        │ │  │
│  │  │  - Intent Embeddings                            │ │  │
│  │  │  - Similarity Search                            │ │  │
│  │  └─────────────────────────────────────────────────┘ │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

5. 数据流与交互

5.1 完整调用流程

Agent A                Nexa-Proxy A              Supernode              Nexa-Proxy B              Agent B
   │                        │                        │                        │                        │
   │ 1. Tool Call           │                        │                        │                        │
   │───────────────────────▶│                        │                        │                        │
   │ {intent, data, budget} │                        │                        │                        │
   │                        │                        │                        │                        │
   │                        │ 2. Intent Vector       │                        │                        │
   │                        │───────────────────────▶│                        │                        │
   │                        │                        │                        │                        │
   │                        │ 3. Route Candidates    │                        │                        │
   │                        │◀───────────────────────│                        │                        │
   │                        │ [DID_B, DID_C, ...]    │                        │                        │
   │                        │                        │                        │                        │
   │                        │ 4. mTLS Handshake      │                        │                        │
   │                        │────────────────────────────────────────────────▶│                        │
   │                        │                        │                        │                        │
   │                        │ 5. Protocol Negotiate  │                        │                        │
   │                        │◀────────────────────────────────────────────────│                        │
   │                        │                        │                        │                        │
   │                        │ 6. Encrypted RPC Stream                        │                        │
   │                        │────────────────────────────────────────────────▶│                        │
   │                        │                        │                        │ 7. Local Tool Call     │
   │                        │                        │                        │───────────────────────▶│
   │                        │                        │                        │                        │
   │                        │                        │                        │ 8. Result              │
   │                        │                        │                        │◀───────────────────────│
   │                        │ 9. Encrypted Response   │                        │                        │
   │                        │◀────────────────────────────────────────────────│                        │
   │                        │                        │                        │                        │
   │                        │ 10. Micro-Receipt Sign │                        │                        │
   │                        │────────────────────────────────────────────────▶│                        │
   │                        │◀────────────────────────────────────────────────│                        │
   │                        │                        │                        │                        │
   │ 11. Result             │                        │                        │                        │
   │◀───────────────────────│                        │                        │                        │
   │                        │                        │                        │                        │

5.2 时序说明

步骤	描述	耗时目标
1	Agent 调用本地 Nexa-Proxy 工具	< 1ms
2	将意图向量化并查询路由表	< 50ms
3	返回候选节点列表	-
4	与目标建立 mTLS 连接	< 100ms
5	协商传输协议	< 50ms
6-9	执行 RPC 调用并返回结果	取决于任务
10	签署微交易收据	< 5ms
11	返回结果给 Agent	< 1ms

6. 设计决策记录

ADR-001: 选择 Sidecar Proxy 模式

状态： 已采纳

背景： 需要支持多种异构 Agent 框架（LangChain、AutoGen、自定义脚本），不能要求开发者重写核心逻辑。

决策： 采用 Sidecar Proxy 模式，Agent 通过本地接口与 Proxy 通信。

后果：

✅ 非侵入式，现有 Agent 无需修改
✅ 语言无关，任何语言都可以调用本地接口
⚠️ 需要额外部署 Proxy 进程
⚠️ 本地通信有轻微延迟（< 1ms）

ADR-002: 选择二进制协议而非 JSON

状态： 已采纳

背景： Agent 间通讯需要传输大量结构化数据（长文本、图像矩阵等），JSON 文本格式效率低。

决策： 使用 Protobuf/FlatBuffers 作为序列化格式，基于 HTTP/2 或 QUIC 传输。

后果：

✅ 体积缩小 60%-80%
✅ 序列化/反序列化速度提升 10x+
⚠️ 调试不如 JSON 直观
⚠️ 需要 Schema 预定义

ADR-003: 选择联邦制拓扑而非纯 P2P

状态： 已采纳

背景： 100 节点规模的 Agent 社区需要高效的语义路由，纯 P2P 的 DHT 查询延迟不可接受。

决策： 采用带超级节点的联邦制拓扑，Supernode 维护全局语义索引。

后果：

✅ 路由查询延迟 < 50ms
✅ 简化 NAT 穿透问题
⚠️ Supernode 是中心化点（通过多副本缓解）
⚠️ 需要运维 Supernode 集群

ADR-004: 选择状态通道而非链上结算

状态： 已采纳

背景： Agent 间可能产生高频微交易（每秒数千次），直接链上结算延迟高、成本大。

决策： 采用 Layer 2 状态通道，仅在通道开启/关闭时与主链交互。

后果：

✅ 支持 10 万+ TPS
✅ 结算成本接近零
⚠️ 需要锁定保证金
⚠️ 通道管理复杂度增加

6. Nexa 语言集成

Nexa-net 与 Nexa 语言深度集成，形成"语言定义网络行为"的完整闭环。详细设计参见 Nexa 集成设计。

6.1 集成架构概览

┌─────────────────────────────────────────────────────────────────┐
│                    Nexa + Nexa-net 集成架构                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐      ┌─────────────────────────────────┐   │
│  │  Nexa 源码      │      │         Nexa-Proxy              │   │
│  │  (.nx 文件)     │ ──→  │  ┌───────────────────────────┐  │   │
│  │                 │      │  │    AVM 执行引擎            │  │   │
│  │  agent X {...}  │      │  │  (Rust WASM Sandbox)      │  │   │
│  │  flow main {...}│      │  └───────────────────────────┘  │   │
│  └─────────────────┘      │              ↓                   │   │
│                           │  ┌───────────────────────────┐  │   │
│                           │  │    网络能力映射            │  │   │
│                           │  │  - DID 注册               │  │   │
│                           │  │  - 能力发布               │  │   │
│                           │  │  - DAG → 网络拓扑          │  │   │
│                           │  └───────────────────────────┘  │   │
│                           └─────────────────────────────────┘   │
│                                      ↓                          │
│                           ┌─────────────────────────────────┐   │
│                           │         Nexa-net 网络           │   │
│                           │  - 语义路由                      │   │
│                           │  - 状态通道结算                  │   │
│                           │  - 跨 Agent RPC                 │   │
│                           └─────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

6.2 核心映射关系

Nexa 语言概念	Nexa-net 网络实体	映射机制
`agent` 声明	DID 身份	编译时自动生成 DID，注册到网络
`tool` 声明	能力 Schema	发布到语义 DHT，支持意图匹配
`protocol` 声明	RPC 接口契约	定义消息格式与验证规则
`flow` 编排	网络调用拓扑	DAG 操作符映射为网络路由
`@budget` 修饰器	状态通道预算	控制单次调用的经济约束

6.3 DAG 操作符网络映射

Nexa v0.9.7+ 引入的 DAG 操作符与网络层操作对应：

DAG 操作符	网络行为	网络层实现
`>>` (管道)	顺序 RPC 调用	Transport Layer 流式 RPC
`	>>` (分叉)	并行多目标调用
`&>>` (合流)	结果聚合节点	Transport Layer Merge 策略
`??` (条件)	意图路由分支	Discovery Layer semantic_if
`		` (Fire-forget)
`&&` (共识)	多 Agent 投票	Economy Layer 共识结算

6.4 AVM 执行引擎

Nexa v1.0 的 Agent Virtual Machine (AVM) 作为 Nexa-Proxy 的核心执行引擎：

┌─────────────────────────────────────────────────────────────┐
│                    AVM Runtime 架构                          │
├─────────────────────────────────────────────────────────────┤
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐  │
│  │ Scheduler │ │ Memory    │ │ Tool      │ │ Network     │  │
│  │ (Tokio)   │ │ Manager   │ │ Registry  │ │ Interop     │  │
│  └───────────┘ └───────────┘ └───────────┘ └─────────────┘  │
│                              ↓                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              WASM Sandbox (工具执行)                     │ │
│  │  - 资源限制: CPU/内存/文件系统                           │ │
│  │  - 安全隔离: RBAC 权限控制                               │ │
│  │  - 网络访问: 通过 Nexa-net Proxy                        │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

性能对比：

指标	Python 转译器	Rust AVM
编译时间	~100ms	~5ms
启动时间	~500ms	~10ms
内存占用	~100MB	~10MB
并发 Agents	~100	~10000

6.5 标准库网络扩展

Nexa 标准库 (std) 通过 Nexa-Proxy 获得网络能力：

标准库模块	本地能力	网络扩展
`std.http`	本地 HTTP 请求	通过 Proxy 路由，支持跨 Agent 请求
`std.fs`	本地文件操作	分布式文件访问（需权限）
`std.time`	本地时间	网络时间同步
`std.ask_human`	本地 HITL	跨 Agent 人机交互协议

6.6 企业特性集成

Nexa v0.9+ 企业特性与 Nexa-net 的对应：

Nexa 企业特性	Nexa-net 集成点
多层语义缓存 (L1/L2)	Discovery Layer 缓存层
长期记忆系统	Economy Layer 状态存储
知识图谱映射	Discovery Layer 语义索引
RBAC 权限控制	Identity Layer VC 验证
上下文压缩器	Transport Layer 消息优化

7. 相关文档

分层设计文档

身份与零信任网络层 - Layer 1 详细设计
语义发现与能力路由层 - Layer 2 详细设计
传输与协商协议层 - Layer 3 详细设计
资源管理与微交易层 - Layer 4 详细设计

规范文档

协议规范 - 二进制协议格式定义
API 参考 - gRPC/REST API 定义
安全设计 - 威胁模型与安全机制

运维文档

部署运维指南 - 部署拓扑与运维实践
开发者接入指南 - 快速接入指南

参考资料

术语表 - 术语定义与缩写索引
项目路线图 - 里程碑与决策记录

附录: Phase 1-12 重构架构变更

关键架构变更

Phase	变更	说明
Phase 3	DashMap 替换 RwLock+HashMap	`src/discovery/semantic_dht.rs` 中 `RwLock<HashMap<...>>` → `DashMap<...>`，降低锁竞争
Phase 5	AES-256-GCM 加密存储	`src/security/secure_storage.rs` 中 XOR 加密 → AES-256-GCM，工业级加密强度
Phase 5	SecurityManager 协调器	`src/security/mod.rs` 新增统一安全协调入口，整合 audit/key_rotation/middleware/rate_limit/secure_storage
Phase 3	两种 Did 类型冲突解决	`src/types.rs` 中 `Did(String)` vs `Did { method, identifier }` → 统一为 `Did(String)` + 辅助方法
Phase 6	REST API 端点	`src/api/rest.rs` 基于 Axum 实现 7 个端点
Phase 6	gRPC Health Service	`src/api/grpc.rs` 基于 tonic_health 实现标准健康检查
Phase 8	Rust SDK	`src/api/sdk.rs` 提供 NexaClient/NexaClientBuilder
Phase 7	速率限制 middleware	`src/security/rate_limit.rs` Token Bucket + Sliding Window
Phase 7	审计日志集成	`src/security/audit.rs` 结构化安全事件记录
Phase 7	密钥轮换集成	`src/security/key_rotation.rs` 自动/手动密钥轮换机制
Phase 12	Error type boxing	`src/error.rs` 中 `Grpc(#[from] tonic::Status)` → `Grpc(Box<tonic::Status>)`，减少 Result 内存占用
Phase 10	ProxyState 共享 registry	`src/proxy/server.rs` 中 `ProxyState::new()` 的 registry 和 router 改为共享同一个 `Arc<RwLock<CapabilityRegistry>>`，确保 /v1/register 写入对 /v1/discover 可见
Phase 10	TestProxy + MockNetwork	`tests/common/mod.rs` 新增 HTTP E2E 测试基础设施：TestProxy（随机端口 + axum serve + oneshot shutdown）、MockNetwork（模拟网络拓扑 + 可控可用性）
Phase 10	SemanticRouter Arc	`SemanticRouter::with_shared()` 方法接收外部 `Arc<RwLock<CapabilityRegistry>>` 和 `Arc<RwLock<NodeStatusManager>>`，实现 router 与 ProxyState 共享同一实例
Phase 11	REST API 延迟基准	`benches/nexa_bench.rs` 新增 `api_benches` 组：health 1.2ms、register 1.3ms、discover 1.4ms
Phase 12	TODO → NOTE 清理	全部 36 个 TODO 注释按策略替换为 NOTE（stub/placeholder/future 分类），提升注释准确性

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Nexa-net 整体架构设计

目录

1. 设计哲学

1.1 问题背景

1.2 核心设计原则

1.2.1 非侵入式集成 (Non-invasive Integration)

1.2.2 语义优先 (Semantic-First)

1.2.3 零信任安全 (Zero-Trust Security)

1.2.4 原生经济 (Native Economy)

2. 架构总览

2.1 系统架构图

2.2 组件职责

2.3 新增模块 (v0.2.0)

3. 四层架构模型

3.1 Layer 1: 身份与零信任网络层

3.2 Layer 2: 语义发现与能力路由层

3.3 Layer 3: 传输与协商协议层

3.4 Layer 4: 资源管理与微交易层

4. 核心组件

4.1 Nexa-Proxy

4.1.1 架构设计

4.1.2 配置示例

4.2 Supernode

4.2.1 服务组件

5. 数据流与交互

5.1 完整调用流程

5.2 时序说明

6. 设计决策记录

ADR-001: 选择 Sidecar Proxy 模式

ADR-002: 选择二进制协议而非 JSON

ADR-003: 选择联邦制拓扑而非纯 P2P

ADR-004: 选择状态通道而非链上结算

6. Nexa 语言集成

6.1 集成架构概览

6.2 核心映射关系

6.3 DAG 操作符网络映射

6.4 AVM 执行引擎

6.5 标准库网络扩展

6.6 企业特性集成

7. 相关文档

分层设计文档

规范文档

运维文档

参考资料

附录: Phase 1-12 重构架构变更

关键架构变更