constructorfabric/gears-rust
GitHub: constructorfabric/gears-rust
Gears 是一个用 Rust 开发的安全、模块化的企业级 XaaS 框架和中间件，为构建多租户云服务平台提供可组合的基础设施库。
Stars: 14 | Forks: 19
# Constructor Fabric Gears (Rust)
[](https://scorecard.dev/viewer/?uri=github.com/constructorfabric/gears-rust) [](https://www.bestpractices.dev/projects/12050)
cd gears-rust
make build # Build libraries and example server binary
make test # Run tests
make example # Run toolkit example gear
```
### 运行服务器
Gears 仓库附带了一个示例服务器，用于演示 gears API：
```
# 运行 example server，请参阅 API 文档 @ http://127.0.0.1:8087/cf/docs
make exammple
# 查看 API 文档：
# $ make example
# 访问：http://127.0.0.1:8087/cf/docs
# 检查 server 是否就绪（详细的 JSON 响应）
curl http://127.0.0.1:8087/cf/health
# Kubernetes 风格的 liveness probe（简单的 "ok" 响应）
curl http://127.0.0.1:8087/healthz
```
其他快速开始示例：
```
# 选项 1：使用 SQLite database 运行（推荐用于开发）
cargo run --bin cf-gears-example-server -- --config config/quickstart.yaml run
# 选项 2：不使用 database 运行（no-db 模式）
cargo run --bin cf-gears-example-server -- --config config/no-db.yaml run
# 选项 3：使用 mock 内存 database 运行以进行测试
cargo run --bin cf-gears-example-server -- --config config/quickstart.yaml --mock run
```
### 示例配置 (config/quickstart.yaml)
```
# Constructor Fabric Gears 配置
# 核心 server 配置（global section）
server:
home_dir: "~/.cfgears
# Database 配置（global section）
database:
url: "sqlite://database/database.db"
max_conns: 10
busy_timeout_ms: 5000
# Logging 配置（global section）
logging:
default:
console_level: info
file: "logs/cfgears.log"
file_level: warn
max_age_days: 28
max_backups: 3
max_size_mb: 1000
# 各个 gear 的配置已移至 gears section 下
gears:
api_gateway:
bind_addr: "127.0.0.1:8087"
enable_docs: true
cors_enabled: false
```
### 创建您的第一个 Gear
有关详细信息，请参阅 [TOOLKIT UNIFIED SYSTEM](docs/toolkit_unified_system/README.md) 和 [TOOLKIT_PLUGINS.md](docs/TOOLKIT_PLUGINS.md)。
## 文档
- **[架构清单](docs/ARCHITECTURE_MANIFEST.md)** - 架构的高级概述
- **[Gears](docs/GEARS.md)** - 所有 gears 及其作用的列表
- **[TOOLKIT UNIFIED SYSTEM](docs/toolkit_unified_system/README.md) 和 [TOOLKIT_PLUGINS.md](docs/TOOLKIT_PLUGINS.md)** - 如何添加新的 gears。
- **[贡献指南](CONTRIBUTING.md)** - 开发工作流和编码标准
## 安全性
Gears 在整个软件开发生命周期中应用了深度防御安全策略——从 Rust 的编译时安全保证和自定义架构 lint，到编译时的租户隔离和 PDP/PEP 授权执行，再到 CI 中的持续模糊测试、依赖审计和自动化安全扫描。
有关详细分析，请参阅 **[安全概述](docs/security/SECURITY.md)**，包括：具有编译时租户作用域的安全 ORM、身份验证/授权架构（NIST SP 800-162 PDP/PEP 模型）、90 多条 Clippy deny 级别规则、自定义 dylint 架构 lint、cargo-deny 漏洞检查、ClusterFuzzLite 持续模糊测试、CodeQL/Scorecard/Snyk/Aikido 扫描仪，以及 AI 驱动的 PR 审查机器人。
## FIPS 140-3 支持
使用 `--features fips` 构建的 Gears 会通过一个 **FIPS 140-3 验证的加密模块**来处理 TLS 数据路径上的所有加密操作。该操作运行在单一的 `rustls 0.23` 状态机上，并支持以下三种可插拔的后端之一：
| 目标平台 | 验证模块 | 后端 |
|---|---|---|
| macOS (任意架构) | Apple `corecrypto` 用户空间 Gear (每个操作系统版本都有对应的 CMVP 证书) | 基于 Security.framework + CommonCrypto 的 `cf-gears-rustls-corecrypto-provider` |
| Windows (x86_64) | Microsoft Windows CNG (每个操作系统版本都有对应的 CMVP 证书) | 基于 `bcrypt.dll` + `ncrypt.dll` 的 `rustls-cng-crypto` 的 `fips_provider()` |
所有分支共享同一个 `rustls 0.23` 状态机 —— 只是 `CryptoProvider` 会根据操作系统进行更换。
### 网络传输上的强制要求
使用 `--features fips` 构建时，toolkit-http 客户端在其 `ClientHello` 中**仅**提供 FIPS 批准的算法：
| 类别 | 算法 |
|---|---|
| TLS 版本 | TLS 1.2、TLS 1.3 (不支持 TLS 1.0/1.1) |
| TLS 1.3 加密套件 | `TLS_AES_128_GCM_SHA256`、`TLS_AES_256_GCM_SHA384` |
| TLS 1.2 加密套件 | `ECDHE_{ECDSA,RSA}_WITH_AES_{128,256}_GCM_SHA{256,384}` (×4) |
| 密钥交换 | NIST P-256, P-384 ECDHE |
| 签名 (验证) | ECDSA P-256/P-384, RSA-PSS, RSA PKCS#1 v1.5 (SHA-256/384/512) |
| Hash / HMAC / HKDF | SHA-256, SHA-384 |
| TLS 1.2 扩展主密钥 (RFC 7627) | 根据 NIST SP 800-52 Rev. 2 §3.5 **必需** (`require_ems = true`) |
明确**排除**：ChaCha20-Poly1305、x25519、X25519MLKEM768 / 后量子混合算法、ED25519、MD5、SHA-1。
### 构建与运行时
```
cargo build -p cf-gears-example-server --features fips
```
这是*“使用 FIPS 验证的密码学”* —— Gears 本身并不在 CMVP 验证的 Gears 列表中；这些验证模块属于 Apple、AWS Labs 和 Microsoft。
有关各操作系统的完整细节（算法范围、构建前提条件、验证关卡、运行时 OE 验证、依赖图策略、覆盖和未覆盖的内容），请参阅 **[安全概述 §9](docs/security/SECURITY.md#9-cryptographic-stack--fips-140-3)**。有关架构、生态系统限制、我们拒绝的替代方案以及各操作系统的理由，请参阅 **[FIPS PRD](docs/security/fips/PRD.md)** 以及 [`docs/security/fips/adrs/`](docs/security/fips/adrs/) 中的 ADR。
### 如何验证构建是否符合 FIPS
```
# Wire 级别（检查由外部 TLS server 提供的 ClientHello）：
cargo run -p cf-gears-fips-probe --features fips -- --url https://www.howsmyssl.com/a/check
# 预期：given_cipher_suites 仅包含 AES-GCM suites，given_named_groups
# 仅包含 secp256r1/secp384r1，post_quantum_key_agreement: false。
# 探针启发式算法会打印 `[OK] No ChaCha20 in ClientHello cipher_suites`。
```
```
# macOS+fips 上的链接 — 应该仅包含 Apple frameworks，没有 aws-lc-fips dylib：
otool -L target/debug/cf-gears-example-server | grep -E 'aws|crypto|ssl|ring'
# （预期：仅 /System/Library/Frameworks/Security.framework）
# Runtime — 已加载 corecrypto：
vmmap | grep -E 'corecrypto|Security\.framework'
```
有关完整的四层验证链（链接、运行时、网络传输层、证书验证），请参阅 [`examples/cf-gears-fips-probe/README.md`](examples/cf-gears-fips-probe/README.md)。
### 构建前提条件
- **macOS + fips**：Xcode Command Line Tools + Rust 工具链。不需要 `cmake` / `perl` / `go`（以前在 macOS 上链接 aws-lc-fips 时需要它们；现在通过特定目标的 shim 消除了这些依赖）。
- **Linux + fips**：C 工具链 + `cmake` + `perl` + `go`（`aws-lc-fips-sys` 构建脚本所需）。
- **Windows + fips**：仅原生 Windows 构建需要 MSVC 工具链 + Windows SDK。不需要 `cmake` / `perl` / `go` —— `rustls-cng-crypto` 是对系统 DLL（`bcrypt.dll`、`ncrypt.dll`）的纯 FFI 调用，没有 `build.rs`。在使用 `--target x86_64-pc-windows-msvc` 从 Linux/macOS 主机进行交叉编译时，除了 `rustup target add` 捆绑的标准 MSVC sysroot 以及链接二进制文件所需的 `cargo-xwin` / `lld-link` 外，不需要额外的工具；`make check-windows-fips` 目标仅执行 `cargo check`，因此甚至连这些也不需要。
### 系统 FIPS 模式要求 (Windows)
仅当操作系统本身处于 FIPS 模式时，Windows CNG FIPS 提供程序才会强制执行其 FIPS 批准的算法子集。如果不是这种情况，Gears 的引导过程将**安全关闭（fails closed）**：`toolkit::bootstrap::init_crypto_provider` 会返回 `CryptoProviderError::SystemFipsModeNotEnabled`，并且二进制文件拒绝启动。
通过组策略启用 FIPS 模式：*计算机配置 → Windows 设置 → 安全设置 → 本地策略 → 安全选项 → “系统加密：使用符合 FIPS 的算法进行加密、哈希和签名” → 已启用*。或者通过注册表：
```
reg add HKLM\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy /v Enabled /t REG_DWORD /d 1 /f
```
更改其中任何一项后都需要重新启动。有关 FIPS 模式态势的 Microsoft 参考文档，请参阅 。
### 本项目不声明的内容
- Gears 本身**不**在 CMVP 验证的 Gears 列表中。CMVP 列出的模块是 Apple `corecrypto` (macOS)、AWS-LC FIPS Provider (Linux) 和 Microsoft Windows CNG (Windows)；Gears 只是*使用者*。
- `rustls-cng-crypto` 和 `cf-gears-rustls-corecrypto-provider` 本身均未在 CMVP 列表中 —— 它们都是各自所使用的 CMVP 列出系统模块（分别为 CNG 和 corecrypto）的轻量级封装。信任链来自于底层经过验证的模块，而不是封装的 crate。
macOS / Windows 上的 FIPS 声明仅在当前运行的操作系统版本被系统模块（`corecrypto` / CNG）当前 CMVP 证书的运行环境所覆盖时才有效。请在每次发布时对照 进行验证。
- `rustls-cng-crypto` 是一个较新的、由单一维护者维护的 crate（首次发布于 2024-12）。我们将其固定在 `0.1.x` 版本，并在每次发布时针对 `rustls-symcrypt` 进行重新评估；此选择记录在 [`docs/security/fips/adrs/0003-windows-fips-via-rustls-cng-crypto.md`](docs/security/fips/adrs/0003-windows-fips-via-rustls-cng-crypto.md) 中。
- TLS 协议级别中关于 EMS 之外的 NIST 建议（SP 800-52 Rev. 2）——最低协议版本、证书规范等——是部署方的责任。
- 服务器端 TLS 终止（入站 HTTPS）委托给反向代理，不属于此 FIPS 范围的一部分。
### 架构决策
- [`docs/adrs/toolkit/0004-macos-fips-via-corecrypto-provider.md`](docs/adrs/toolkit/0004-macos-fips-via-corecrypto-provider.md) — 为什么我们基于 Apple corecrypto 构建了自定义 rustls `CryptoProvider`，而不是使用 `native-tls` 或声明 FIPS 仅限 Linux。
- [`docs/adrs/toolkit/0005-fips-feature-target-conditional-shim.md`](docs/adrs/toolkit/0005-fips-feature-target-conditional-shim.md) — 为什么单一的 `fips` 特性设计使用一个空的 shim crate 来编码特定于目标的激活。
- [`docs/security/fips/adrs/0003-windows-fips-via-rustls-cng-crypto.md`](docs/security/fips/adrs/0003-windows-fips-via-rustls-cng-crypto.md) — 为什么今天 Windows+FIPS 要通过 `rustls-cng-crypto` 路由，而不是等待 Microsoft 的 `rustls-symcrypt` 获得 CMVP 验证。
## 配置
### YAML 配置结构
```
# config/server.yaml
# 全局 server 配置
server:
home_dir: "~/.cfgears"
# Database 配置
database:
servers:
sqlite_users:
params:
WAL: "true"
synchronous: "NORMAL"
busy_timeout: "5000"
pool:
max_conns: 5
acquire_timeout: "30s"
# Logging 配置
logging:
default:
console_level: info
file: "logs/cf-gears.log"
file_level: warn
max_age_days: 28
max_backups: 3
max_size_mb: 1000
# 各个 gear 的配置
gears:
api_gateway:
config:
bind_addr: "127.0.0.1:8087"
enable_docs: true
cors_enabled: true
users_info:
database:
server: "sqlite_users"
file: "users_info.db"
config:
default_page_size: 5
max_page_size: 100
```
### 环境变量覆盖
配置支持带有 `CF_` 前缀的环境变量覆盖：
```
export CF_GEARS_DATABASE_URL="postgres://user:pass@localhost/db"
export CF_GEARS_API_GATEWAY_BIND_ADDR="0.0.0.0:8080"
export CF_GEARS_LOGGING_DEFAULT_CONSOLE_LEVEL="debug"
```
## 测试
```
make check # full quality gate (fmt + clippy + test + security)
```
其他测试：
```
make test # unit tests (workspace)
make test-sqlite # integration tests (SQLite, no external DB required)
make e2e-local # end-to-end tests (builds + starts server automatically)
make e2e-docker # end-to-end tests (builds + starts server in Docker)
make coverage-unit # unit test code coverage
make fuzz # fuzz smoke tests (30 s per target)
```
在 **Windows** 上（没有 `make`），请直接使用跨平台 CI 脚本：
```
python tools/scripts/ci.py check # full CI suite
python tools/scripts/ci.py e2e-local # end-to-end tests
python tools/scripts/ci.py fuzz --seconds 60 # fuzz smoke run
```
有关完整的测试策略、覆盖率政策、CI 流水线细节及所有可用命令，请参阅 **[docs/TESTING.md](docs/TESTING.md)**。
## 贡献
有关详细的指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
该项目基于 Apache 2.0 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
标签：Rust, XaaS, 中间件, 企业级框架, 可视化界面, 子域名突变, 无服务器, 测试用例, 生成式AI, 索引, 网络流量审计, 通知系统