BrianNguyen29/Ferrum-Gate

# FerrumGate [](https://github.com/BrianNguyen29/Ferrum-Gate/actions/workflows/ci.yml) [](./LICENSE) [](https://www.rust-lang.org/) [Tiếng Việt](./README.vi.md) · [文档](./docs/README.md) · [快速开始](./docs/guides/quickstart.md) · [速查表](./docs/guides/cheatsheet.md) · [运维指南](./docs/guides/operator.md) · [安全模型](./docs/guides/security-model.md)

FerrumGate 是一个专为 AI agent 设计的治理网关，它用基于意图、一次性的能力（capability）替代了常规的常驻工具访问权限——从而确保每一个操作都经过策略检查、做好了回滚准备并记录了来源溯源。 ## 为什么需要网关？ 传统的 API key 只能回答*“谁可以调用这个？”*，却无法回答*“agent 想要做什么？”*、*这是否在允许范围内？*，或者*“我们能将其回滚吗？”*。 FerrumGate 部署在 agent 和工具之间，将每一次副作用转化为一个受控的生命周期：编译意图、评估策略、生成受限能力、准备回滚、执行、验证，并记录来源溯源。**Agent 不直接拥有对生产系统的常驻直接权限。** 它们获得的是执行特定操作的狭窄、短时且可解释的许可，并且在副作用发生之前就已内置了回滚和血缘机制。 ## 三大支柱 **受限** — 没有常驻权限。每一个能力都绑定到一个明确的意图、特定的资源以及一个 ≤ 300 秒的 TTL。一旦被使用或过期，该租约即刻失效。 **可审计** — 策略决策、能力授予、执行尝试以及最终状态都会被记录为一条溯源链。证据在设计上只能追加。 **可逆** — 在任何适配器执行副作用之前，系统就已准备好回滚和恢复契约。如果验证失败，系统可以进行补偿或回滚，而不是留下一个残缺的变更状态。 ## 快速开始 前置条件：Rust stable、`cargo`、`make`、`curl`。 ``` # 构建并运行开发 gateway FERRUMD_BIND_ADDR=127.0.0.1:18080 \ cargo run -p ferrumd -- --config configs/ferrumgate.dev.toml # 检查 liveness curl http://127.0.0.1:18080/v1/healthz # 10 分钟完整演练 cat docs/guides/quickstart.md ``` ## 执行生命周期  每一个修改性操作都会遵循一个最小血缘链：**Intent → PolicyEvaluated → CapabilityMinted → ActionProposalSubmitted → SideEffectPrepared → ToolCallPrepared → ToolCallExecuted → SideEffectVerified → Terminal state**（已提交、已补偿、已回滚或失败）。由存储支持的转换、隔离令牌以及血缘门控共同确保了此执行顺序。未知的修改性工具将被默认安全关闭，除非被显式绑定。 ## 适配器与入口 FerrumGate 为常见的 agent 副作用提供了受控的适配器，每个适配器都具备沙箱机制、白名单以及回滚契约： - **Filesystem** — 写入、删除、移动、复制、追加、chmod、目录创建/删除，附带沙箱和快照功能。 - **Git** — commit、branch 创建/删除、tag 创建/删除，附带代码库根目录白名单。 - **HTTP** — 基于 rustls 客户端的修改性操作，无重定向、有界超时、SSRF 防护以及重放恢复契约。 - **SQLite** — 基于文件的修改性操作，附带数据库根目录白名单和验证门控。 - **Mail draft** — 草稿创建/更新/删除，附带收件人和内容绑定。**不执行发送邮件操作。** 入口与工具： - `ferrumd` — 网关 daemon - `ferrumctl` — 用于检查健康状态、就绪状态、审计、策略、审批、生命周期发件箱、备份/恢复的 CLI - `ferrum-mcp-server` — MCP stdio 服务器（向 MCP 客户端暴露网关工具） - `ferrum-migrate` — 从 SQLite 到 PostgreSQL 的迁移工具 - `ferrum-stress` — 可机器解析的压测/冒烟测试场景 - `ferrum-tui` — 终端运维仪表盘 ## 项目状态 - **稳定** — 意图生命周期、策略评估、能力生成、回滚准备/验证/补偿、SQLite 写入队列、溯源链、bearer/scoped/OIDC/agent 身份验证。 - **已实现** — filesystem、HTTP、Git、SQLite、mail draft 适配器；S3 适配器（实验性）；`ferrumctl` CLI；`ferrum-stress`；`ferrum-tui`；Prometheus 指标；速率限制；Helm chart。 - **Beta** — PostgreSQL runtime（已在本地和 CI 环境中进行实测）。生产环境下的 HA/多节点拓扑需由运维人员自行管理，本仓库不提供。 - **实验性** — MCP Streamable HTTP / SSE 传输。 - **未实现/超出范围** — 多租户、托管服务、邮件发送、合规认证、MCP 可恢复性。 ## 文档 如果您刚接触本项目，建议按以下顺序阅读： 1. [核心概念](./docs/guides/concepts.md) 2. [快速开始](./docs/guides/quickstart.md) 3. [适配器参考](./docs/guides/adapter-reference.md) 4. [安全模型](./docs/guides/security-model.md) 5. [运维指南](./docs/guides/operator.md) 6. [生产环境须知](./docs/PRODUCTION_NOTES.md) 其他参考： - [API 指南](./docs/guides/api.md) · [MCP 集成](./docs/guides/mcp-integration.md) · [演示流程](./docs/guides/demo-flows.md) - [策略编写](./docs/guides/policy-authoring.md) · [故障排除](./docs/guides/troubleshooting.md) - [常见问题](./docs/guides/faq.md) · [路线图](./docs/ROADMAP.md) - [Helm Chart](./deploy/helm/ferrumgate/README.md) · [监控配置](./configs/monitoring/README.md) ## 开发与验证 ``` make fmt # formatting make check # cargo check make lint # clippy make test # tests make docs # link validation make validate # expanded gate make audit # dependency audit make secret-scan ``` 请查阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解相关规范。如果您是 AI 助手，请查阅 [AGENTS.md](./AGENTS.md) 了解工作区限制与工具信息。 ## 许可证 [Apache-2.0](./LICENSE)

标签：AI代理网关, Rust, Streamlit, 可视化界面, 审计日志, 治理, 测试用例, 网络流量审计, 自定义请求头, 访问控制, 通知系统