rungent构建
部署
在生产环境运行 rungent。本页讲 Docker 镜像和全部环境变量、数据库、密钥、反向代理、多副本,以及模型链:一个模型失败时 rungent 依次换下一个。
嵌入式的 rungent 随你的 JavaScript 应用一起部署,它的选项见 JavaScript。在其他语言写的 API 旁边,rungent 作为独立服务 rungent serve 运行:用环境变量配置,状态存在 Postgres 里,放在已经为你的产品服务的反向代理后面。
browser ─> reverse proxy (console.example.com)
├─ /rungent/v0/*, /mcp, /skill.md, /llms.txt, /.well-known/… ─> rungent serve ─> Postgres
└─ everything else ──────────────────────────────────────> your API
rungent serve ─(the user's credential + Rungent-Assertion)─> your API
运行#
docker run -d --name rungent -p 8080:8080 --env-file rungent.env ghcr.io/rungent/rungent-server:v0.4.0
镜像按每个发布版本打标签(v0.4.0),另有 latest。镜像以 node 用户在 8080 端口运行 rungent serve。不用 Docker 的话,npx rungent serve 在 Node.js 24 上运行同一个服务。
GET /healthz 返回 ok;即使 rungent 放在某个前缀下,它也在根路径上,镜像的健康检查就调用它。收到 SIGTERM 时,服务停止接收请求,等正在进行的运行结束后退出。要基于你自己的基础镜像构建,对 rungent 仓库 packages/rungent 下的 Dockerfile 传入 --build-arg BASE_IMAGE=… --build-arg RUNGENT_VERSION=0.4.0。
配置#
有五个必填变量:
| 变量 | 是什么 |
|---|---|
RUNGENT_URL |
rungent 对外提供服务的公开 URL,即断言的 iss。代理在根路径提供 rungent 时为 https://console.example.com。 |
RUNGENT_HOST_ORIGIN |
你产品的公开 origin,即断言的 aud。你的 API 按它校验。 |
RUNGENT_SIGNING_KEY |
rungent 的 Ed25519 私钥 JWK,带 kid,JSON 格式:也就是 rungent keys generate 写出的那个文件。 |
RUNGENT_SECRET |
32 字节或更长(openssl rand -base64 48),用来加密管理员保存的模型 API key。 |
RUNGENT_DATABASE_URL |
postgres://…;单实例且有持久卷时也可以用 sqlite:<path>。 |
其余都是可选的:
| 变量 | 是什么 |
|---|---|
RUNGENT_HOST_BASE_URL |
rungent 不经公开 origin 访问你 API 时的地址(http://api.internal:8000)。断言里写的仍是公开 origin。 |
RUNGENT_HOST_OPENAPI |
你的 OpenAPI 3.1 文档的路径或 URL。默认 /api/openapi.json。 |
RUNGENT_MODELS |
默认的模型链,一个 JSON 数组。不设的话,在管理员保存一条链之前,运行都会失败。 |
RUNGENT_NAME |
助手的名字。默认 Assistant。 |
RUNGENT_INSTRUCTIONS |
加进系统提示词的产品事实;@/path/to/file 表示读取一个文件。 |
RUNGENT_PRODUCT_NAME、RUNGENT_PRODUCT_SUMMARY |
你的 OpenAPI 需要登录才能读时,/skill.md 和 /llms.txt 给未登录调用方展示的产品名称和简介。 |
RUNGENT_SKILL_NAME、RUNGENT_SKILL_GUIDE |
/skill.md 里的 name,以及放在最前面的手写指南(或 @path)。 |
RUNGENT_CLI_COMMAND、RUNGENT_CLI_PACKAGE、RUNGENT_CLI_INSTALL |
文档里提到的你自有品牌的 CLI:命令名、npm 包,或一行自由格式的安装命令(三者都有时以它为准)。后两个需要先设第一个。 |
RUNGENT_MCP_INSTRUCTIONS |
MCP 客户端在 initialize 时收到的说明,或 @path。默认是 skill 指南。 |
RUNGENT_MCP_AUTHORIZATION_SERVERS |
向 MCP 客户端公布的 OAuth 签发方,逗号分隔。 |
RUNGENT_KNOWLEDGE_DIR、RUNGENT_KNOWLEDGE_BASE_URL |
启动时建索引的 Markdown 文档,以及这些页面所在的 URL。见搜索与知识。 |
RUNGENT_HOST_KEYS |
你的 API 签 Rungent-Host-Assertion 所用公钥 JWK 的 JSON 数组。 |
RUNGENT_PREVIOUS_SECRET |
轮换之前的旧 secret。 |
RUNGENT_BASE_PATH |
rungent 放在某个路径下时,所有路由的前缀。 |
RUNGENT_MAX_STEPS |
每次运行的模型步数上限。默认 16。 |
PORT |
监听端口。默认 8080。 |
变量缺失、不是合法 JSON 或超出范围时,服务在启动时就停下,给出写明变量名的消息,退出码为 2。把 RUNGENT_SIGNING_KEY、RUNGENT_SECRET、RUNGENT_PREVIOUS_SECRET、RUNGENT_DATABASE_URL 和 RUNGENT_MODELS(里面有 API key)放在你的密钥存储里。
数据库与密钥#
生产环境用 Postgres。rungent 把对话、确认、延迟任务、设置和知识索引都存在那里,放在自己的 rungent_* 表中,启动时自动创建和升级。请给它单独的数据库或 schema。SQLite 不能被多个副本共享。
签名密钥及其轮换见以用户身份调用。要轮换设置用的 secret,把新值设为 RUNGENT_SECRET、旧值设为 RUNGENT_PREVIOUS_SECRET,然后部署:新 secret 用于加密,两个都能解密;已保存的设置在第一次读取时用新 secret 重新加密。一旦有运行读取过设置,就可以去掉 RUNGENT_PREVIOUS_SECRET。如果设置是用 rungent 已经没有的 secret 加密的,请求会返回 503 settings_unreadable,直到管理员调用 DELETE /rungent/v0/settings。
路由 rungent 的路径#
把你产品 origin 上的这些路径原样转给 rungent,其余的转给你的 API:
| 路径 | 提供什么 |
|---|---|
/rungent/v0/* |
助手的 HTTP API 及其事件流 |
/mcp |
基于 streamable HTTP 的 MCP |
/skill.md、/llms.txt |
从你的目录生成的文档 |
/.well-known/rungent-keys.json |
rungent 的公钥 |
/.well-known/oauth-protected-resource/mcp |
仅在设置了 RUNGENT_MCP_AUTHORIZATION_SERVERS 时 |
运行以 server-sent events 流式输出,所以要关掉响应缓冲,并允许长时间读取。nginx 的写法:
location ~ ^/(rungent/v0/|mcp$|skill\.md$|llms\.txt$|\.well-known/(rungent-keys\.json|oauth-protected-resource/mcp)$) {
proxy_pass http://rungent:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_buffering off;
proxy_read_timeout 1h;
}
Authorization 和 Cookie 请求头要原样转发:它们就是用户的凭据。要把 rungent 放在 /assistant 下,设置 RUNGENT_BASE_PATH=/assistant 和 RUNGENT_URL=https://console.example.com/assistant,代理 /assistant/,并给 Web 客户端传 createClient({ baseUrl: '/assistant' })。
运行多个副本#
多个副本可以共用一个 Postgres:一次确认只执行一次,同一段对话不会同时被两个副本驱动。有两样东西只存在单个副本的内存里:
- MCP 会话。 把带同一个
Mcp-Session-Id的请求都路由到同一个副本(粘性会话,或在 Kubernetes Service 上设sessionAffinity: ClientIP)。落到别的副本会得到404 session_not_found,客户端随即开一个新会话。 - 模型休息状态。 每个副本各自发现某个模型端点在失败。
在 Kubernetes 上,用 Deployment 运行这个镜像,变量来自一个 Secret:
containers:
- name: rungent
image: ghcr.io/rungent/rungent-server:v0.4.0
ports: [{ containerPort: 8080 }]
envFrom: [{ secretRef: { name: rungent-env } }]
readinessProbe: { httpGet: { path: /healthz, port: 8080 } }
选择模型#
rungent 通过一条模型链调用模型:按顺序尝试的一组端点。第一个额度用完或被限流时,同一轮对话接着交给下一个,用户最多看到一句“模型繁忙,重试中”。你配置的链是默认值;管理员可以在运行时替换它。
createRungent({
// ...
models: {
chain: [
{ id: 'qwen', provider: 'openai-compatible', model: 'qwen3-max',
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1', apiKey: process.env.DASHSCOPE_API_KEY },
{ id: 'claude', provider: 'anthropic', model: 'claude-sonnet-4-5', apiKey: process.env.ANTHROPIC_API_KEY, vision: true },
],
},
});
使用 rungent serve 时,RUNGENT_MODELS 以 JSON 形式存放同样的数组。
| 字段 | 是什么 |
|---|---|
id |
必填,在链中唯一,1 到 64 个字符。保存的设置按它保留端点的 key。 |
provider |
openai-compatible(任何 OpenAI 风格的聊天 API:DashScope、DeepSeek、vLLM、LiteLLM)、openai 或 anthropic。 |
model |
服务商的模型 id。 |
baseURL |
openai-compatible 必填;其他服务商可用来指向代理或网关。 |
apiKey |
服务商的 key。不填时,openai 和 anthropic 读取 OPENAI_API_KEY 和 ANTHROPIC_API_KEY。 |
vision |
模型能读图片。带图片的轮次优先发给这些端点;其他端点收到的是代替每张图片的一条说明。 |
temperature、maxOutputTokens |
每次调用这个端点时一并发送。 |
cooldownSeconds |
{ quota?, rateLimit?, error? }:失败的端点休息多久。 |
providerOptions |
传给服务商,按服务商名字分组。{ 'openai-compatible': { enable_thinking: false } } 能让 Qwen 的推理模型保持快速。 |
嵌入式部署时,链中的一项也可以是任意 AI SDK 语言模型 { id, languageModel },比如通过 agents/models/ai-sdk 使用的 Workers AI。它只存在于代码里,设置页面中只读显示。
模型失败时#
超时、408、5xx、网络错误或无法使用的回答,会在同一个端点上重试,最多 4 次。其他任何失败,以及最后一次重试失败,都会把这一步交给下一个端点,失败的端点进入休息:
| 失败 | 休息多久 | cooldownSeconds 键 |
|---|---|---|
额度用完:402,或回答中提到额度 |
6 小时 | quota |
被限流:429 |
60 秒 | rateLimit |
| 其他 | 5 分钟 | error |
所有端点都在休息时,运行以 model_unavailable 结束。休息状态只存在于单个进程中。把纯文本模型放在最前、视觉模型放在后面,普通轮次就能保持便宜,同时还能读懂用户附上的截图。
让管理员修改模型链#
在只有管理员能进的页面上渲染 rungent/react 里的 ModelSettings。管理员可以增删端点、调整顺序;key 只能写不能读,Reset to defaults 会回到你配置的那条链。保存需要用户身份里有 rungent:admin scope,在服务端检查。对应的接口是 GET、PUT 和 DELETE /rungent/v0/settings(HTTP API)。保存的 key 在写入数据库之前用 secret 加密。
检查#
npx rungent check --openapi https://console.example.com/api/openapi.json通过。- 用某个用户的令牌请求
GET /rungent/v0/catalog,列出的是这个用户的操作。 - 通过面板发起的写操作会弹出确认卡,你的 API 日志记下
actor = rungent和确认 id。 /skill.md能正常显示,编码 Agent 能连上/mcp。
接下来#
测试针对你的部署衡量 Agent 的表现。