配置指南

LLM Fence 当前分为两层配置：

启动配置：llm-fence.toml，从工作目录读取，包含监听地址、管理端来源和 MongoDB 连接。
运行配置：MongoDB runtime_configs.active 文档，包含上游 Provider、模型、processor、审计和上游超时等可管理配置。

启动配置支持 ${ENV_VAR} 环境变量替换。运行配置中的 secret 字段会加密后写入 MongoDB；读取和导出时会脱敏。

启动配置

toml

[server]
host = "0.0.0.0"
port = 3000
admin_ui = true
public_origin = "http://localhost:3000"
frontend_origin = "http://localhost:3000"
cookie_secure = false
cookie_same_site = "lax"

[mongo]
uri = "mongodb://localhost:27017?replicaSet=rs0"
db = "llm_fence"

[server] 下所有字段都是必填项，缺少字段会启动失败。

字段	说明
`host`	HTTP 监听地址
`port`	HTTP 监听端口
`admin_ui`	是否在 `/` 挂载内置管理端前端
`public_origin`	后端对浏览器暴露的外部地址，用于生成 OAuth 回调地址
`frontend_origin`	管理端页面对浏览器暴露的外部地址，用于登录后跳转
`cookie_secure`	是否给 `admin_session` Cookie 添加 Secure
`cookie_same_site`	Cookie SameSite 策略：`lax`、`strict` 或 `none`

同源部署时 public_origin 和 frontend_origin 通常相同。本地前后端分端口开发时，后端仍使用 public_origin = "http://localhost:3000"，前端可配置为 frontend_origin = "http://localhost:5173"。

MongoDB 要求

LLM Fence 会在启动时检测 MongoDB 部署模式。由于运行配置更新、用户状态变更等管理端写操作依赖 MongoDB transactions，MongoDB 必须运行在副本集或分片集群模式。

开发环境可以初始化单机副本集：

bash

mongod --replSet rs0 --dbpath /path/to/mongo-data
llm-fence --init-mongo-replica-set

生产环境建议使用 3 节点副本集或托管 MongoDB，并配套备份、监控和恢复演练。

应用主密钥

启动前必须设置：

bash

export LLM_FENCE_SECRET_KEY_ID=prod-v1
export LLM_FENCE_SECRET_KEY=<base64-encoded-32-byte-key>

LLM_FENCE_SECRET_KEY_ID 是当前主密钥标识。LLM_FENCE_SECRET_KEY 用于：

业务 Key 的 HMAC-SHA256 哈希。
管理端 session token 的 HMAC。
Provider API Key 和审计 LLM api_key 的加密存储。

首次部署后不要随意修改主密钥，否则已有业务 Key、session 和加密配置将无法验证或解密。

运行配置结构

运行配置通过管理端或 /api/admin/config/* API 管理，基础结构如下：

json

{
  "version": 1,
  "upstream_timeout_secs": 120,
  "processors": {
    "client_guard": { "enabled": true },
    "model_guard": { "enabled": true },
    "ip_guard": { "enabled": true },
    "request_logger": { "enabled": true },
    "format_converter": { "enabled": true },
    "stream_usage_options": { "enabled": true },
    "audit": {
      "enabled": false,
      "sample_rate": 0.01,
      "worker_count": 2,
      "queue_size": 1024,
      "worker_queue_size": 256,
      "body_limits": { "max_request_chars": -1, "max_response_chars": -1 },
      "engines": {
        "llm": {
          "enabled": false,
          "sample_rate": 1.0,
          "url": "https://api.openai.com/v1",
          "api_key": "",
          "model": "gpt-5.4-mini",
          "max_tokens": 2048,
          "thinking": false,
          "timeout_secs": 60,
          "system_prompt": "",
          "truncation": { "max_request_chars": 20000, "max_response_chars": 20000 },
          "preprocess": {
            "enabled": true,
            "pipelines": {
              "codex": { "enabled": true, "processors": [] },
              "cc": { "enabled": true, "processors": [] },
              "default": { "enabled": true, "processors": [] }
            }
          }
        },
        "rule": { "enabled": false, "sample_rate": 1.0 }
      },
      "sink": { "batch_size": 20, "flush_interval_secs": 5 }
    }
  },
  "providers": []
}

写接口使用乐观锁：提交更新时必须携带当前 version，版本不匹配返回 409。每次替换运行配置会写入 runtime_config_revisions 作为历史快照。

Provider

json

{
  "name": "deepseek",
  "type": "deepseek",
  "api_key": "sk-...",
  "base_url": "https://api.deepseek.com",
  "models": [
    { "name": "deepseek-chat", "upstream_model": null }
  ],
  "supported_formats": ["openai"],
  "auto_convert": true
}

字段	说明
`name`	Provider 唯一名称
`type`	`newapi`、`deepseek` 或 `llm-fence`
`api_key`	上游 API Key，写入后加密存储
`base_url`	上游 API 基础地址
`models`	暴露给客户端的模型列表
`supported_formats`	上游原生支持格式：`openai`、`anthropic`
`auto_convert`	是否允许客户端使用非原生格式并自动转换到 `supported_formats[0]`

旧版 accept / send 字段已不再支持。

Processor

当前支持的 processor 名称固定为：

client_guard
model_guard
ip_guard
request_logger
format_converter
stream_usage_options
audit

除 audit 外，普通 processor 只接受 enabled 字段；额外字段会被运行配置校验拒绝。审计配置见 AI 审计模块。

管理 API

常用配置接口：

方法	路径	说明
`GET`	`/api/admin/config`	当前运行配置，secret 已脱敏
`GET`	`/api/admin/config/default`	默认运行配置模板
`POST`	`/api/admin/config/bootstrap`	首次初始化运行配置
`GET/PATCH`	`/api/admin/config/settings/general`	上游超时等通用设置
`GET/POST`	`/api/admin/config/providers`	Provider 列表和创建
`GET/PATCH/DELETE`	`/api/admin/config/providers/{provider_name}`	Provider 详情、更新和删除
`GET/PATCH`	`/api/admin/config/processors/{processor_name}`	单个 processor 配置

管理端写请求除白名单外都需要 admin_session Cookie 和 X-CSRF-Token。

配置指南 ​

启动配置 ​

MongoDB 要求 ​

应用主密钥 ​

运行配置结构 ​

Provider ​

Processor ​

管理 API ​