# OIP核心节点Rust实现

**Repository Path**: orginone/oip-core-node-rust

## Basic Information

- **Project Name**: OIP核心节点Rust实现
- **Description**: OIP协议核心节点的rust实现
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OIP Core Node — Rust 实现

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.81%2B-orange.svg)](https://www.rust-lang.org)
[![Build Status](https://img.shields.io/badge/build-passing-green.svg)](#)

> OIP（开放互联协议）Core Node 的 Rust 实现。OIP 是一个以权力流转为核心的开放互联协议，本节点是其权力状态机层（L3），提供 VET 签发、转移、监管与审计的全生命周期管理。

---

## 目录

- [项目定位](#项目定位)
- [核心概念](#核心概念)
- [架构概览](#架构概览)
- [快速开始](#快速开始)
- [Crate 结构](#crate-结构)
- [配置](#配置)
- [部署](#部署)
- [开发指南](#开发指南)
- [文档导航](#文档导航)
- [社区与贡献](#社区与贡献)
- [许可证](#许可证)

---

## 项目定位

OIP Core Node 是奥集能开放架构 V6 中的 **L3 权力状态机层**，在六层模型中承上启下：

```
┌──────────────────────────────────────────────┐
│  L6  应用层（oiocns-agent / 第三方应用）       │
├──────────────────────────────────────────────┤
│  L5  服务网关层（API Gateway / BFF）           │
├──────────────────────────────────────────────┤
│  L4  gRPC 接口层（本节点的对外契约）           │
├──────────────────────────────────────────────┤
│  ►  L3  权力状态机层（Core Node — 本项目）     │
├──────────────────────────────────────────────┤
│  L2  存储与索引层（VET/DID/审计 持久化）       │
├──────────────────────────────────────────────┤
│  L1  密码学原语层（Ed25519 / DID / VC）       │
└──────────────────────────────────────────────┘
```

**职责边界**：
- **负责**：VET 签发/撤销/过期/转移、PDP 策略决策、合规检查、全局断路器、审计追溯
- **不负责**：底层存储引擎（由 L2 提供）、UI 交互、业务流程编排（由 L6 应用层负责）

---

## 核心概念

| 概念 | 说明 |
| --- | --- |
| **VET**（Value Exchange Token） | 量化、可转移的权力凭证。OIP 的核心数据结构 |
| **DID** | W3C 去中心化标识符，实体身份锚定 |
| **VC** | Verifiable Credential，可验证凭证（如许可证） |
| **PDP** | Policy Decision Point，策略决策点，输出 ALLOW/DENY |
| **PEP** | Policy Enforcement Point，策略执行点（拦截器） |
| **四种转移法则** | Override（覆盖）/ Workflow（流程）/ Exchange（交换）/ Collaboration（协作） |
| **ForceLevel** | 强制力等级（0-5），Override 法则的比较依据 |
| **布尔盲化** | 所有 DENY 决策对外统一返回 `OIP_4031`，防信息泄露 |

详见 [OIP 术语表](../OIP/docs/oip-glossary.md)。

---

## 架构概览

Core Node 采用 **多 crate workspace + 依赖注入** 架构，所有外部依赖通过 trait 注入，便于测试与替换。

```
                    ┌─────────────────────────────────────────┐
                    │           gRPC Server (mTLS)            │
                    │   VET / Transfer / Regulator / Market   │
                    │            / Audit Service              │
                    └─────────────────┬───────────────────────┘
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        ▼                             ▼                             ▼
┌───────────────┐           ┌──────────────────┐          ┌──────────────────┐
│  VetManager   │           │ TransferEngine   │          │   PdpEngine      │
│  签发/撤销/    │           │ 四种转移法则      │          │  6 阶段验证管道   │
│  过期/级联     │           │ + 2PC Exchange   │          │  + 布尔盲化       │
└───────┬───────┘           └────────┬─────────┘          └────────┬─────────┘
        │                            │                             │
        ▼                            ▼                             ▼
┌───────────────┐           ┌──────────────────┐          ┌──────────────────┐
│ ComplianceEng │           │  CircuitBreaker  │          │  AuditService    │
│ 制裁/司法/标准 │           │  全局断路器       │          │  追溯/默克尔证明  │
└───────────────┘           └──────────────────┘          └──────────────────┘
        │                            │                             │
        └────────────────────────────┼─────────────────────────────┘
                                     ▼
        ┌────────────────┬───────────┴───────────┬────────────────┐
        ▼                ▼                       ▼                ▼
┌──────────────┐  ┌─────────────┐       ┌──────────────┐  ┌─────────────┐
│  StorageAdp  │  │ Distributed │       │ EventPublish │  │ CacheClient │
│  (L2 gRPC)   │  │ Lock(Redis) │       │ (NATS JetStr)│  │ (Redis)     │
└──────────────┘  └─────────────┘       └──────────────┘  └─────────────┘
```

详细架构说明见 [docs/00-overview.md](docs/00-overview.md)。

---

## 快速开始

### 环境要求

- Rust 1.81+（含 cargo）
- Protobuf 编译器 `protoc` 3.0+
- Redis 7+（分布式锁与缓存）
- NATS 2.10+（事件总线，启用 JetStream）
- L2 存储 gRPC 服务（VET/DID/审计 持久化）

### 构建

```bash
git clone <repo-url> oip-core-node-rust
cd oip-core-node-rust
cargo build --release
```

### 生成证书（开发用）

```bash
mkdir -p certs
openssl req -x509 -newkey rsa:4096 -keyout certs/server.key -out certs/server.crt \
  -days 365 -nodes -subj "/CN=localhost"
cp certs/server.crt certs/ca.crt
cp certs/server.key certs/client.key
cp certs/server.crt certs/client.crt
```

### 启动依赖

```bash
docker-compose up -d redis-1 redis-2 redis-3 nats
```

### 启动节点

```bash
OIP_NODE__LISTEN_ADDR=0.0.0.0:50051 \
OIP_L2__ENDPOINT=http://localhost:9090 \
OIP_REDIS__ENDPOINTS='["redis://localhost:6379","redis://localhost:6380","redis://localhost:6381"]' \
OIP_NATS__URL=nats://localhost:4222 \
OIP_TLS__CERT=certs/server.crt \
OIP_TLS__KEY=certs/server.key \
OIP_TLS__CLIENT_CA=certs/ca.crt \
./target/release/oip-server
```

### 使用 CLI

```bash
# 签发 VET
oip --node-addr https://localhost:50051 \
    --ca-cert certs/ca.crt \
    --tls-cert certs/client.crt \
    --tls-key certs/client.key \
    --did-key keys/user.pem \
    vet issue --subject did:oip:testnet:z6Mk... --payload examples/vet.json

# 验证 VET
oip ... vet verify --token <jwt>

# 转移 VET（Exchange 法则）
oip ... transfer lock --seller-vet <vet_id> --buyer-did did:oip:testnet:z6Mk...
oip ... transfer commit --lock-id <lock_id>
```

---

## Crate 结构

本项目是 Cargo workspace，包含 16 个 crate：

| Crate | 说明 | 文档 |
| --- | --- | --- |
| `oip-core` | 核心类型：VET/DID/错误码/常量 | [01-core-and-proto.md](docs/01-core-and-proto.md) |
| `oip-crypto` | 密码学：Ed25519/JWT/JWE/Nonce | [09-crypto-and-security.md](docs/09-crypto-and-security.md) |
| `oip-schema` | VET JSON Schema 校验 | [01-core-and-proto.md](docs/01-core-and-proto.md) |
| `oip-proto` | prost 生成的 gRPC 类型 | [01-core-and-proto.md](docs/01-core-and-proto.md) |
| `oip-storage` | 存储适配器（trait + L2 gRPC client） | [06-storage-lock-eventbus.md](docs/06-storage-lock-eventbus.md) |
| `oip-lock` | 分布式锁（Redis Redlock） | [06-storage-lock-eventbus.md](docs/06-storage-lock-eventbus.md) |
| `oip-eventbus` | 事件总线（NATS JetStream） | [06-storage-lock-eventbus.md](docs/06-storage-lock-eventbus.md) |
| `oip-pdp` | 策略决策引擎 | [04-pdp-engine.md](docs/04-pdp-engine.md) |
| `oip-compliance` | 合规引擎（制裁清单/司法管辖） | [05-compliance-and-regulator.md](docs/05-compliance-and-regulator.md) |
| `oip-vet` | VET Manager（签发/撤销/过期/级联） | [02-vet-manager.md](docs/02-vet-manager.md) |
| `oip-transfer` | Transfer Engine（四种法则+2PC） | [03-transfer-engine.md](docs/03-transfer-engine.md) |
| `oip-regulator` | 监管服务（断路器） | [05-compliance-and-regulator.md](docs/05-compliance-and-regulator.md) |
| `oip-market` | 市场服务（挂牌/发现/要约） | [07-market-and-audit.md](docs/07-market-and-audit.md) |
| `oip-audit` | 审计服务（追溯/默克尔证明） | [07-market-and-audit.md](docs/07-market-and-audit.md) |
| `oip-server` | gRPC 服务运行时（mTLS/拦截器/健康） | [08-server-and-deployment.md](docs/08-server-and-deployment.md) |
| `oip-cli` | 命令行工具 | [08-server-and-deployment.md](docs/08-server-and-deployment.md) |

---

## 配置

配置文件位于 `config/` 目录，支持 TOML + 环境变量覆盖（前缀 `OIP_`，分隔符 `__`）。

```toml
# config/default.toml
[node]
listen_addr = "0.0.0.0:50051"
node_id = "oip-node-1"

[l2]
endpoint = "http://l2-storage:9090"
timeout = "5s"

[redis]
endpoints = ["redis://redis-1:6379", "redis://redis-2:6379", "redis://redis-3:6379"]

[nats]
url = "nats://nats:4222"

[tls]
cert = "/etc/oip/certs/server.crt"
key = "/etc/oip/certs/server.key"
client_ca = "/etc/oip/certs/ca.crt"

[compliance]
sanction_sources = ["UN", "OFAC", "EU"]

[exchange]
lock_ttl = "30m"

[market]
listing_ttl = "168h"  # 7 天
```

环境变量覆盖示例：
```bash
OIP_REDIS__ENDPOINTS='["redis://r1:6379"]' ./oip-server
```

---

## 部署

### Docker

```bash
docker build -t oip-core-node .
docker run -p 50051:50051 \
  -v $(pwd)/config:/etc/oip:ro \
  -v $(pwd)/certs:/etc/oip/certs:ro \
  oip-core-node
```

### Docker Compose

```bash
docker-compose up -d
```

### Kubernetes

生产部署要点：
- Deployment 副本数 ≥ 2，跨可用区反亲和
- HPA 按 CPU 70% 扩缩
- Liveness/Readiness 走 gRPC health check
- Secret 挂载 TLS 证书与节点签名私钥
- ConfigMap 挂载配置文件
- PodDisruptionBudget 保证滚动更新可用

详见 [docs/08-server-and-deployment.md](docs/08-server-and-deployment.md)。

---

## 开发指南

### 环境准备

```bash
# 安装 protoc
brew install protobuf

# 安装 cargo 工具
cargo install cargo-watch cargo-nextest cargo-tarpaulin
```

### 开发循环

```bash
# 热重载开发
cargo watch -x 'run --bin oip-server'

# 运行测试
cargo nextest run
cargo test --doc

# 覆盖率
cargo tarpaulin --out html

# 代码格式化与 lint
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
```

### 提交代码

详见 [AGENTS.md](AGENTS.md)。简要：
1. 创建分支 `feat/xxx` 或 `fix/xxx`
2. 遵循 Conventional Commits
3. 通过 CI（fmt + clippy + test）
4. PR 至少 1 人 review

---

## 文档导航

| 文档 | 内容 |
| --- | --- |
| [docs/00-overview.md](docs/00-overview.md) | 架构总览、技术选型、workspace 结构 |
| [docs/01-core-and-proto.md](docs/01-core-and-proto.md) | 核心数据类型、错误码、Protobuf 接口 |
| [docs/02-vet-manager.md](docs/02-vet-manager.md) | VET Manager：签发/撤销/过期/级联 |
| [docs/03-transfer-engine.md](docs/03-transfer-engine.md) | Transfer Engine：四种转移法则 |
| [docs/04-pdp-engine.md](docs/04-pdp-engine.md) | PDP：6 阶段验证管道 + 布尔盲化 |
| [docs/05-compliance-and-regulator.md](docs/05-compliance-and-regulator.md) | 合规引擎与全局断路器 |
| [docs/06-storage-lock-eventbus.md](docs/06-storage-lock-eventbus.md) | 存储适配器、分布式锁、事件总线 |
| [docs/07-market-and-audit.md](docs/07-market-and-audit.md) | 市场服务与审计服务 |
| [docs/08-server-and-deployment.md](docs/08-server-and-deployment.md) | gRPC 运行时与部署 |
| [docs/09-crypto-and-security.md](docs/09-crypto-and-security.md) | 密码学与安全实现 |
| [AGENTS.md](AGENTS.md) | 代码协作文档（贡献者必读） |

---

## 社区与贡献

欢迎贡献代码、报告问题、提出建议。请先阅读：

- [AGENTS.md](AGENTS.md) — 代码协作规范
- [OIP 协议规范](../OIP/docs/oip-protocol.md) — 协议层规范
- [Core Node 设计方案](../OIP/docs/oip-core-node-design.md) — 详细设计

### 行为准则

本社区遵循 [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)。

---

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。

```
Copyright 2025 OIP Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```