cyberfabric/cyberfabric-core
GitHub: cyberfabric/cyberfabric-core
基于 Rust 的企业级多租户 SaaS 开发平台，通过规范驱动开发和内置安全机制简化高安全要求业务系统的构建。
Stars: 47 | Forks: 52
# Cyber Fabric
[](https://scorecard.dev/viewer/?uri=github.com/cyberfabric/cyberfabric-core)
[](https://www.bestpractices.dev/projects/12050)
**Cyber Fabric** 是一个模块化、高性能的平台，用于使用 Rust 构建现代企业级 SaaS 服务。它提供了一个全面的框架，用于构建可扩展的 AI 驱动应用程序，具有自动 REST API 生成、全面的 OpenAPI 文档以及极其灵活的模块化架构。
**核心理念：**
- **设计即模块**：一切皆为模块——通过网关模式实现可组合、独立的单元，支持可插拔的 worker
- **全方位扩展**：由 [GTS](https://github.com/globaltypesystem/gts-spec) 驱动的扩展点，支持自定义数据类型、业务逻辑和第三方集成
- **SaaS 就绪**：内置多租户、细粒度访问控制、使用量追踪和租户定制功能
- **卓越的云运维**：通过 ModKit 实现生产级可观测性、数据库无关设计、API 最佳实践和弹性模式
- **规范驱动开发**：[行业标准规范模板](docs/spec-templates/README.md)（PRD、Design、ADR、Feature、Upstream Reqs）在编写代码*之前*定义构建内容，确保从需求到实现的可追溯性
- **左移**：在尽可能早的阶段捕获问题——自定义 [dylint](dylint_lints/) 架构检查在编译时强制执行设计规则，Clippy 设置警告为拒绝级别，并在代码进入审查前在 CI 中运行集成 [E2E 测试](#e2e-tests)、模糊测试和安全审计
- **质量至上**：90%+ 的测试覆盖率目标，包括单元测试、集成测试、E2E 测试、性能测试和安全测试
- **通用部署**：单一代码库可运行于云端、本地 Windows/Linux 工作站或移动设备
- **开发者友好**：AI 辅助代码生成、自动 OpenAPI 文档、轻量级 DDD 结构和类型安全的 API
- **使用 Rust 编写**：通过编译时安全和深度静态分析（包括项目特定的 lint）优化常规工程工作，从而在审查/运行时之前预防更多问题。
- **尽可能保持 Monorepo**：将核心模块和契约集中在一处，以实现原子重构、一致的工具链/CI 以及现实的本地构建 + 端到端测试；仅在规模迫使其时分拆。
有关更多详细信息，包括选择 Rust 和 Monorepo 的原因，请参阅完整的架构 [MANIFEST](docs/ARCHITECTURE_MANIFEST.md)。
另请参阅 [REPO_PLAYBOOK](docs/REPO_PLAYBOOK.md)，其中包含仓库级制品（指南、规则、约定等）的注册表。
## 快速入门
### 前置条件
- Rust stable 版本及 Cargo（[通过 rustup 安装](https://rustup.rs/)）
- Protocol Buffers 编译器 (`protoc`)：
- macOS：`brew install protobuf`
- Linux：`apt-get install protobuf-compiler`
- Windows：从 https://github.com/protocolbuffers/protobuf/releases 下载
- MariaDB/PostgreSQL/SQLite 或内存数据库
### CI/开发命令
```
# 克隆 repository
git clone --recurse-submodules
cd cyberfabric-core
make ci # Run full CI pipeline
make fmt # Check formatting (no changes). Use 'make dev-fmt' to auto-format
make clippy # Lint (deny warnings). Use 'make dev-clippy' to attempt auto-fix
make test # Run tests
make example # Run modkit example module
make check # Full check suite
make safety # Extended safety checks (includes dylint/kani)
make deny # License and dependency checks
```
### 运行服务器
```
# 快速助手
make quickstart
# 选项 1：使用 SQLite database 运行（推荐用于开发）
cargo run --bin hyperspot-server -- --config config/quickstart.yaml run
# 选项 2：在无 database 模式下运行（no-db 模式）
cargo run --bin hyperspot-server -- --config config/no-db.yaml run
# 选项 3：使用 mock in-memory database 运行以进行测试
cargo run --bin hyperspot-server -- --config config/quickstart.yaml --mock run
# 检查 server 是否就绪（详细 JSON response）
curl http://127.0.0.1:8087/health
# Kubernetes 风格 liveness probe（简单 "ok" response）
curl http://127.0.0.1:8087/healthz
# 查看 API documentation：
# $ make quickstart
# 访问：http://127.0.0.1:8087/docs
```
### 示例配置 (config/quickstart.yaml)
```
# Cyber Fabric 配置
# 核心 server 配置（global section）
server:
home_dir: "~/.hyperspot"
# 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/hyperspot.log"
file_level: warn
max_age_days: 28
max_backups: 3
max_size_mb: 1000
# 各 module 配置已移至 modules section 下
modules:
api_gateway:
bind_addr: "127.0.0.1:8087"
enable_docs: true
cors_enabled: false
```
### 创建您的第一个模块
详情请参阅 [MODKIT UNIFIED SYSTEM](docs/modkit_unified_system/README.md) 和 [MODKIT_PLUGINS.md](docs/MODKIT_PLUGINS.md)。
## 文档
- **[架构宣言](docs/ARCHITECTURE_MANIFEST.md)** - 架构的高级概览
- **[模块](docs/MODULES.md)** - 所有模块及其角色的列表
- **[MODKIT UNIFIED SYSTEM](docs/modkit_unified_system/README.md) 和 [MODKIT_PLUGINS.md](docs/MODKIT_PLUGINS.md)** - 如何添加新模块。
- **[贡献指南](CONTRIBUTING.md)** - 开发工作流和编码标准
## 安全
Cyber Fabric 在整个开发生命周期中应用深度防御安全策略——从 Rust 的编译时安全保证和自定义架构 lint，到编译时租户隔离和 PDP/PEP 授权执行，再到 CI 中的持续模糊测试、依赖审计和自动化安全扫描。
有关完整分解，请参阅 **[安全概览](docs/security/SECURITY.md)**，包括：具有编译时租户作用域的安全 ORM、认证/授权架构（NIST SP 800-162 PDP/PEP 模型）、90+ 条 Clippy 拒绝级规则、自定义 dylint 架构 lint、cargo-deny 顾问检查、ClusterFuzzLite 持续模糊测试、CodeQL/Scorecard/Snyk/Aikido 扫描仪以及 AI 驱动的 PR 审查机器人。
## 规范模板
Cyber Fabric 使用行业标准规范模板（IEEE、ISO、MADR）来驱动开发。规范在实现*之前*编写，并与代码一起存在于版本控制中。
- **[概览与指南](docs/spec-templates/README.md)** — 模板系统概览、治理、FDD ID 约定和文档放置规则
- **[PRD.md](docs/spec-templates/PRD.md)** — 产品需求文档：愿景、参与者、能力、用例、FR/NFR
- **[DESIGN.md](docs/spec-templates/DESIGN.md)** — 技术设计：架构、原则、约束、领域模型、API 契约
- **[ADR.md](docs/spec-templates/ADR.md)** — 架构决策记录：决策、选项、权衡、后果
- **[FEATURE.md](docs/spec-templates/FEATURE.md)** — 功能规范：流程、算法、状态、需求
- **[UPSTREAM_REQS.md](docs/spec-templates/UPSTREAM_REQS.md)** — 上游需求：从其他模块到本模块的技术需求
## 配置
### YAML 配置结构
```
# config/server.yaml
# 全局 server 配置
server:
home_dir: "~/.hyperspot"
# 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/hyperspot.log"
file_level: warn
max_age_days: 28
max_backups: 3
max_size_mb: 1000
# 各 module 配置
modules:
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
```
### 环境变量覆盖
配置支持使用 `HYPERSPOT_` 前缀的环境变量覆盖：
```
export HYPERSPOT_DATABASE_URL="postgres://user:pass@localhost/db"
export HYPERSPOT_MODULES_api_gateway_BIND_ADDR="0.0.0.0:8080"
export HYPERSPOT_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 scripts/ci.py check # full CI suite
python scripts/ci.py e2e-local # end-to-end tests
python 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) 文件。
标签：API网关, API集成, DevSecOps, OpenAPI, OpenSSF, RESTful API, Rust编程语言, SaaS开发平台, Shift Left, Streamlit, StruQ, XML 请求, 上游代理, 云安全监控, 云运维, 人工智能集成, 企业级开发, 单元测试, 可观测性, 可视化界面, 多层架构, 多租户架构, 安全开发, 开源框架, 持续集成, 提示词优化, 数据库无关, 文档安全, 模块化设计, 测试用例, 端到端测试, 类型系统, 自动化修复, 覆盖率测试, 规范驱动开发, 访问控制, 请求拦截, 软件供应链安全, 远程方法调用, 通知系统, 静态分析, 高性能计算