# 部署

在生产环境运行 rungent。本页讲 Docker 镜像和全部环境变量、数据库、密钥、反向代理、多副本，以及模型链：一个模型失败时 rungent 依次换下一个。

嵌入式的 rungent 随你的 JavaScript 应用一起部署，它的选项见 [JavaScript](javascript.md)。在其他语言写的 API 旁边，rungent 作为独立服务 `rungent serve` 运行：用环境变量配置，状态存在 Postgres 里，放在已经为你的产品服务的反向代理后面。

```text
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
```

## 运行

```bash
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` | 默认的[模型链](#choose-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。见[搜索与知识](search.md#add-your-docs)。 |
| `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 不能被多个副本共享。

签名密钥及其轮换见[以用户身份调用](acting-as-the-user.md#keys-and-rotation)。要轮换设置用的 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 的写法：

```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：

```yaml
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 通过一条**模型链**调用模型：按顺序尝试的一组端点。第一个额度用完或被限流时，同一轮对话接着交给下一个，用户最多看到一句“模型繁忙，重试中”。你配置的链是默认值；管理员可以在运行时替换它。

```ts
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](http-api.md#settings)）。保存的 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`。

## 接下来

[测试](testing.md)针对你的部署衡量 Agent 的表现。
