企业官网建设流程全解析

LiteLLM Agent Control Plane 是一个统一的 AI Agent 控制平面，让你用一个 API 调用 OpenCode、Hermes、Claude Managed Agents、Cursor Agents API、DeepAgents 等多种 Agent 运行时。本文带你把它部署到 Render 云平台，重点讲清它的三阶段多阶段 Dockerfile 构建流程，以及保证服务安全启动的 master key、数据库凭据等关键配置，新手照做即可完成上线。

一、部署前你需要准备什么

在开始之前，先明确三样必备资源：

配置文件中的值支持用os.environ/变量名引用环境变量，所有被引用的环境变量必须在启动前设置好，否则服务直接启动失败——这是 LiteLLM Agent Control Plane 的启动安全设计。官方托管配置刻意保持极简，见 deploy/render.config.yaml。

二、多阶段 Dockerfile 是怎么工作的

项目根目录的 Dockerfile 是一个典型的三阶段构建，最终产物只保留一个极简 Debian 运行时镜像：

1. ui-builder阶段（node:26-bookworm-slim） 在 Dockerfile#L3-L8 中，先复制package.json和package-lock.json并执行npm ci，利用 Docker 层缓存加速依赖安装；再复制整个 UI 源码执行npm run build，产出 Next.js 静态产物。

2. rust-builder阶段（rust:1.90-bookworm） 在 Dockerfile#L10-L15 中复制Cargo.toml、Cargo.lock与src源码，执行cargo build --release --bin lite编译出静态的lite二进制。Rust 编译产物体积小、无运行时依赖，这也是官方强调的低开销 LLM 网关路线：

3. runtime阶段（debian:bookworm-slim） 在 Dockerfile#L17-L34 中，只从前两个阶段拷贝lite二进制、UI 静态文件和两份配置，并设置关键环境变量：

   ENV HOST=0.0.0.0 ENV PORT=4000 ENV LITELLM_CONFIG=/app/deploy.config.yaml ENV LITELLM_UI_DIR=/app/ui

   最后EXPOSE 4000，启动命令为lite serve。注意一个容易踩的坑：编译期include_str!引入的文件（如skills/lite-schedule.md）必须在 Dockerfile 中 COPY 进构建上下文，否则编译或启动会失败。

三、在 Render 上创建 Web Service

在 Render 用本仓库创建一个Web Service（Docker 运行时），按下表填写即可：

健康检查背后的实现非常轻量，src/http/health.rs 中GET /health直接返回{"status":"ok"}，路由注册见 src/http/routes.rs。Render 会自动注入PORT，镜像内已固定HOST=0.0.0.0，所以启动命令不需要任何端口参数。

再加一个Postgres 实例，并为服务设置两个环境变量（建议标记为 secret）：

• LITELLM_MASTER_KEY— 网关鉴权 key，同时负责加密数据库中存储的凭据
• DATABASE_URL— Postgres 连接串

四、启动安全配置：凭据不进配置，只进数据库

这是部署中最重要的一条安全原则：Provider API key 不要写进config.yaml或环境变量。它们应该在服务起来之后，通过 Settings UI（/settings）或 API 添加，加密存库后按请求注入。示例：

curl -X POST $BASE/api/providers/anthropic \ -H "Authorization: Bearer $LITELLM_MASTER_KEY" \ -H "content-type: application/json" \ -d '{"api_key":"sk-ant-...","api_base":"https://api.anthropic.com"}'

模型路由即使不写api_key也合法——只要配置了数据库，key 会在请求时从数据库取（当前凭据目录已支持 anthropic）。

另外注意通配符路由限制：网关只支持一条provider/*通配路由。托管配置把通配符留给anthropic/*，并把gpt-5.5显式列出供 Codex 使用；配两条通配会以only one wildcard model route is supported报错拒启。

五、验证部署是否成功

服务起来后，用三个请求做端到端验证：

BASE=https://<your-service>.onrender.com KEY=$LITELLM_MASTER_KEY curl -s $BASE/health # {"status":"ok"} curl -s $BASE/v1/models -H "Authorization: Bearer $KEY" # 已配置模型列表 # Anthropic 协议 curl -s $BASE/v1/messages -H "Authorization: Bearer $KEY" \ -H "content-type: application/json" \ -d '{"model":"anthropic/claude-sonnet-4-5","max_tokens":32, "messages":[{"role":"user","content":"Reply with exactly: ok"}]}'

/health通了、/v1/models能列出模型、/v1/messages能拿到回复，说明网关、数据库、凭据注入全链路已就绪。之后打开浏览器访问服务地址，用 master key 登录，即可在 UI 里创建 Agent 并把刚部署的运行时接入：

六、踩坑清单（实战总结）

• 子域名创建后不可改：onrender.com子域在服务创建时固定，改服务名不会改 URL；想换子域只能新建服务。
• Docker command 不要自己再套一层 shell：Render 会经 shell 执行命令，再包一层sh -c '...'会被二次包装成错误 token，直接 exit 127；用纯命令lite serve --config /app/deploy.config.yaml即可。
• 构建上下文别漏文件：编译期内联的资源和配置文件都要 COPY，细节见上文。
• 本地调试：不想上云可先在本地用 Docker Compose 跑同款堆栈，compose.yaml 会同时拉起 Postgres 与 LiteLLM Agent Control Plane 服务并自动注册运行时；setup-local.sh 则是一键启动并打开 onboarding 页面的脚本。

写在最后

通过三阶段多阶段 Dockerfile + 最小化托管配置 + 「凭据进库、master key 加密」的启动安全设计，LiteLLM Agent Control Plane 可以在 Render 上几分钟内完成部署。完整的部署说明与验证命令参考 deployment.md，运行时注册与凭据加密实现可分别查看 src/http/provider_credentials.rs 与 src/proxy/credential_crypto.rs。