LLM Fence

中文

English

中文

English

Appearance

快速开始 ​

LLM Fence 是一个面向团队的 LLM API 代理，在客户端和上游模型服务之间提供认证、路由、策略控制、请求日志和 AI 审计。

前置条件 ​

  • MongoDB：用于保存管理员用户、运行配置、业务 Key、请求日志和审计日志。
  • MongoDB 副本集或分片集群：管理端部分写操作使用事务；普通 standalone mongod 会导致服务拒绝启动。
  • 应用主密钥：通过环境变量提供，用于业务 Key HMAC、session token HMAC，以及 Provider / 审计 LLM 密钥加密。

下载二进制 ​

从 GitHub Releases 下载对应平台 zip 包并解压。解压后先按下面步骤准备 llm-fence.toml、MongoDB 副本集和应用主密钥，再启动服务。

  • Windows：llm-fence.exe
  • Linux：llm-fence

启动配置 ​

启动配置是服务进程启动前必须读取的本地文件，文件名固定为 llm-fence.toml，放在运行 llm-fence 命令的工作目录下。它只保存“启动时就必须知道”的信息：HTTP 监听地址、内置管理端开关、浏览器访问源、管理端 Cookie 策略和 MongoDB 连接。

Provider、模型、processor、审计等会变更的运行配置不写在这个文件里，而是在首次初始化后保存到 MongoDB。

在解压目录复制 llm-fence.example.toml 为 llm-fence.toml：

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"

本地 HTTP 开发时，cookie_secure 应设为 false；生产 HTTPS 部署时应设为 true。public_origin 用于生成 OAuth 回调地址，frontend_origin 用于登录和回调成功后的页面跳转。

准备 MongoDB 副本集 ​

开发环境可以使用单机副本集：

bash
mongod --replSet rs0 --dbpath /path/to/mongo-data

首次启动前初始化一次副本集：

bash
llm-fence --init-mongo-replica-set

如需指定副本集名称：

bash
llm-fence --init-mongo-replica-set my-rs

连接串需要带上副本集参数，例如 mongodb://localhost:27017?replicaSet=rs0。

设置应用主密钥 ​

生成 32 字节 base64 密钥：

bash
openssl rand -base64 32

Windows PowerShell：

powershell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

启动前设置环境变量：

bash
export LLM_FENCE_SECRET_KEY_ID=local-v1
export LLM_FENCE_SECRET_KEY=<base64-encoded-32-byte-key>
powershell
$env:LLM_FENCE_SECRET_KEY_ID = "local-v1"
$env:LLM_FENCE_SECRET_KEY = "<base64-encoded-32-byte-key>"

首次部署后不要随意修改 LLM_FENCE_SECRET_KEY。当前版本不支持多主密钥、自动重加密或 KMS。

启动服务 ​

bash
# Windows
.\llm-fence.exe

# Linux
chmod +x llm-fence
./llm-fence

server.admin_ui = true 时，浏览器访问 http://localhost:3000/ 打开内置管理端。

默认部署方式是后端二进制内置并托管管理端前端。如果你要把前端静态文件和后端 API 分开部署，例如前端走 Nginx / CDN、后端只暴露 /api/admin/* 和 /v1/*，请参考前后端分开部署。

首次初始化 ​

  1. 打开管理端页面。
  2. 创建第一个 super_admin 管理员。
  3. 在初始化向导中配置运行配置，或调用 POST /api/admin/config/bootstrap 导入 JSON。
  4. 在管理端创建 Provider、模型和业务 Key。

业务 Key 明文只在创建或轮换时返回一次；服务端只保存 HMAC 哈希和脱敏值。

测试代理 ​

bash
curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer sk-your-business-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

Anthropic 格式：

bash
curl -X POST http://localhost:3000/v1/messages \
  -H "x-api-key: sk-your-business-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":128,"messages":[{"role":"user","content":"hello"}]}'

下一步 ​