rungent v0.5.1
EN中文

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 的表现。

供 Agent 读取: deploy.md编辑此页