架构总览

LLM Fence 是一个 Rust 实现的 LLM API 代理。主服务同时承载代理 API、内置管理端、管理 API 和运行配置加载。

启动流程

load llm-fence.toml
  -> load LLM_FENCE_SECRET_KEY
  -> connect MongoDB and verify transaction support
  -> ensure indexes
  -> load runtime_configs.active
  -> decrypt runtime secrets
  -> build RuntimeState
  -> mount /api/admin, /v1 and optional admin UI

llm-fence.toml 只保存启动前必须知道的信息。Provider、模型、processor、审计和上游超时等运行配置保存在 MongoDB runtime_configs.active。

请求链路

Client
  -> Salvo router
  -> RuntimeInjector
  -> AuthMiddleware
  -> Chat Handler
  -> ModelResolver
  -> PreProcessor pipeline
  -> AdapterFactory / LlmAdapter
  -> upstream provider
  -> PostProcessor pipeline
  -> response
  -> Observer pipeline async

如果运行配置尚未初始化，RuntimeInjector 会让代理 API 返回未初始化错误，管理端仍可用于首次配置。

入口层

src/main.rs

• 读取 llm-fence.toml。
• 支持 --init-mongo-replica-set 初始化开发用单机副本集。
• 支持 release 构建下通过 --admin-docs 临时开启 OpenAPI / Swagger。
• 挂载代理 API：/v1/chat/completions、/v1/responses、/v1/messages、/v1/models。
• 根据 server.admin_ui 决定是否在 / 挂载内置管理端前端。

配置层

src/config/mod.rs

• BootstrapConfig：从 llm-fence.toml 读取启动配置。
• Config：由启动配置和 MongoDB 运行配置合成的运行时快照。
• ProviderConfig：使用 supported_formats 和 auto_convert 控制格式支持与转换。
• SecretString：避免 secret 在 Debug 输出中泄露。

src/db/runtime_config.rs

• 读取和替换 runtime_configs.active。
• 使用 MongoDB transaction 将旧配置归档到 runtime_config_revisions。
• 加密 / 解密 Provider 和 processor 中的 secret。
• 校验 processor 白名单、Provider 字段和审计配置结构。

管理面

src/control_api/

• /api/admin/* 管理 API。
• admin_session HttpOnly Cookie 认证。
• 写请求使用 X-CSRF-Token 防护。
• OpenAPI 文档由 Salvo oapi 生成，release 默认不挂载。

管理端前端位于 app/，构建产物通过 include_dir 嵌入二进制。

认证层

src/middleware/auth.rs

• OpenAI 格式：Authorization: Bearer <key>。
• Anthropic 格式：x-api-key: <key>。
• 业务 Key 不保存明文，认证时用当前 LLM_FENCE_SECRET_KEY 计算 HMAC 后查询 api_keys.client_key_hash。

路由层

src/router/resolver.rs

根据请求模型名遍历运行配置中的 Provider 和 model，解析出：

• Provider 配置
• Model 配置
• 上游模型名
• 格式转换决策

适配器层

src/adapter/

文件	职责
base.rs	LlmAdapter trait
factory.rs	按 Provider 类型创建 adapter
format/generic.rs	通用请求构造、认证头和 endpoint 处理
provider/newapi.rs	NewAPI / OneAPI 兼容上游
provider/deepseek.rs	DeepSeek 上游
provider/llm_fence.rs	LLM Fence 链式转发

处理器层

src/processor/

处理器	阶段	功能
client_guard	Pre	客户端类型识别与 Key 白名单校验
model_guard	Pre	模型白名单校验
ip_guard	Pre	IP/CIDR 白名单校验
format_converter	Pre/Post/Stream	OpenAI 与 Anthropic 格式互转
stream_usage	Stream	流式用量处理
request_logger	Observer	请求日志写入 MongoDB
audit	Observer	AI 旁路审计

数据库层

src/db/

文件	职责
mongo.rs	MongoDB 连接、事务能力检测、副本集初始化
client_key.rs	业务 Key 哈希存储、创建、更新、软删除和轮换
runtime_config.rs	运行配置、版本归档、secret 加密
request_log.rs	请求日志
audit_log.rs	审计日志
admin_settings.rs	管理后台设置
operation_log.rs	管理操作日志

主要依赖

Crate	用途
salvo / salvo-oapi	HTTP 框架和 OpenAPI
mongodb	配置、Key、用户和日志存储
reqwest	上游 HTTP 调用
anyllm_translate	OpenAI / Anthropic 格式转换
aes-gcm	secret 加密
argon2	管理员密码哈希
tracing	结构化日志