企业官网建设流程全解析

使用 litellm-helm 在 Kubernetes 上部署 LiteLLM Proxy：参数、数据库、迁移与运维实践

【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm

LiteLLM Proxy 是一个统一的多模型 AI 网关，能以 OpenAI 兼容格式对外提供 100+ 家 LLM 提供商的接入能力。本文以仓库中的 litellm-helm Helm Chart 为核心，讲解如何在 Kubernetes 集群中一键部署 LiteLLM Proxy，并围绕主密钥管理、代理配置 ConfigMap、PostgreSQL（独立部署或复用外部实例）、Prisma 数据库迁移 Job 与管理员 UI 访问这五大主题展开。读完本文，你将掌握该 Chart 全部核心参数的用法、生产环境的关键取舍，以及如何用 Helm/ArgoCD 驱动一套可持续升级的 LiteLLM Proxy 部署。

说明：本文面向社区版 litellm-helm Chart（Chart 版本 1.1.3，对应 appVersion v1.85.1，见 Chart.yaml）。该 Chart 由社区维护，如果遇到 Bug 建议向仓库提交 issue；生产环境大规模部署更推荐参考 Docker 与 Kubernetes 的官方生产部署建议。

前置条件

安装本 Chart 需要满足以下版本门槛：

• Kubernetes 1.21+
• Helm 3.8.0+

另外还需要根据你的数据库选型准备额外前提：

• 若使用db.deployStandalone（默认开启），底层基础设施需要支持PV（PersistentVolume）供应，因为随 Chart 一起部署的独立 PostgreSQL 实例要持久化数据。
• db.useStackgresOperator目前尚未实现，即使将其置为true也不会生效；若未来启用，需要集群中已预先安装 Stackgres Operator——该 Chart 不会替你安装缺失的 Operator。

快速安装：默认一套起

Chart 默认开启db.deployStandalone，即随 Proxy 一起在命名空间内拉起一个单实例 PostgreSQL（基于 Bitnami postgresql 子 Chart），因此开箱即可完成部署：

helm repo add litellm oci://ghcr.io/berriai/litellm-helm # 或直接使用仓库内 Chart 源码 helm install litellm ./helm/litellm-helm

首次安装时，Chart 会生成一个随机的 Master Key 并写入<RELEASE>-litellm-masterkeySecret；后续helm upgrade会复用该 Secret 中的值，不会轮换主密钥（详见下文“Master Key 机制”一节）。

安装完成后，通过helm status的 NOTES（模板见 templates/NOTES.txt）可以找到访问方式：ClusterIP场景默认使用kubectl port-forward将 4000 端口映射到本地。

Proxy 部署参数详解

镜像、副本与服务

关于replicaCount有一个值得注意的实现细节：在 templates/deployment.yaml 中，当 KEDA 或 HPA 开启时，模板会跳过spec.replicas的渲染，交由自动扩缩器接管副本数。这一点与 values.yaml 中autoscaling/keda的配置相互呼应（详见后文“自动扩缩容”小节）。

resources默认刻意留空，目的是让 Chart 能装在 Minikube 这类小型集群上、且升级不会让 Pod 一直 Pending；但生产环境建议按“每个 worker 约 1 CPU 与 4Gi 内存”设定 requests/limits（values.yaml 中注明了该经验值，并提示结合--num_workers同步放大）。低于该水位，流量与数据库连接增多后 Pod 很容易被 OOMKilled。

健康检查探针

Chart 为网关容器注入了三类探针，可在 values.yaml 中分别覆盖path、initialDelaySeconds、periodSeconds、timeoutSeconds、successThreshold、failureThreshold：

• livenessProbe：存活探针，默认路径/health/liveliness，默认每 15 秒探测、连续 5 次失败重启。
• readinessProbe：就绪探针，默认路径/health/readiness，默认每 10 秒探测、连续 3 次失败摘除流量。
• startupProbe：启动探针，默认路径/health/readiness，默认每 10 秒一次、最多容忍 30 次失败（最长约 300 秒），避免慢启动容器被误杀。

这些默认值均来自 values.yaml，而渲染后的 httpGet 探针挂到名为http的容器端口上（见 templates/deployment.yaml）。

优雅下线与生命周期钩子

values.yaml 提供了一个值得在生产启用的运维细节：通过lifecycle.preStop.httpGet指向/health/drain端点实现优雅下线——该端点会把 Pod 标记为 NotReady，并只在进行中的请求真正结束后才放行，而不是像固定sleep那样总是等待最坏时长。由于/health/drain默认关闭，需要先在proxy_config.general_settings里设置enable_drain_endpoint: true；同时 kubelet 调用 preStop 钩子时不携带 Proxy 凭据，若健康端口可从其他 Pod 访问，还应设置drain_endpoint_token（或环境变量DRAIN_ENDPOINT_TOKEN），并让钩子通过X-Drain-Token请求头发送同一值。缺少或错误的 token 会得到 401 且不产生副作用。terminationGracePeriodSeconds默认 90 秒，应略高于GRACEFUL_SHUTDOWN_TIMEOUT（默认 30s），为 SIGTERM 后的清理留出余量。

Master Key 机制：从自动生成到外部 Secret

LiteLLM Proxy 的 Master Key 是管理员访问的关键凭据，Chart 提供了三种取值方式：

其底层逻辑可在 templates/secret-masterkey.yaml 中看到：只要未显式提供masterkeySecretName，模板会先lookup命名空间中已存在的<fullname>-masterkeySecret；若找到则b64dec解码复用其中的masterkey值，找不到才用printf "sk-%s" (randAlphaNum 18)生成新随机密钥。这正是“首次安装生成、之后升级永不轮换”的原因。在 templates/deployment.yaml 中，该 Secret 的值会以secretKeyRef方式注入为PROXY_MASTER_KEY环境变量，并被默认配置里的os.environ/PROXY_MASTER_KEY引用（见下节）。

若想完全自管密钥，可先创建自己的 Secret，再通过masterkeySecretName/masterkeySecretKey指向它，Chart 便不再生成-masterkeySecret。

代理配置：proxy_config、ConfigMap 与 os.environ 引用

LiteLLM Proxy 通过一份 YAML 配置（model_list、router_settings、general_settings 等）描述“路由哪些模型、用什么凭据、开什么功能”。

从 values 渲染 ConfigMap（默认方式）

Chart 默认把 values 中的proxy_config渲染成 ConfigMap 并挂载进 Pod。相关参数：

默认的proxy_config长这样：

proxy_config: general_settings: master_key: os.environ/PROXY_MASTER_KEY model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: eXaMpLeOnLy

注意master_key的取值是os.environ/PROXY_MASTER_KEY——这是 LiteLLM 配置中引用环境变量的标准写法，Proxy 启动时会从PROXY_MASTER_KEY环境变量（即上一节注入的 Secret 值）读取真实密钥。生产环境切勿把明文密钥写死在proxy_config的 values 里，因为那样密钥会进入 Helm release 与 ConfigMap。

渲染逻辑见 templates/configmap-litellm.yaml：模板对.Values.proxy_config做deepCopy后toYaml输出为 ConfigMap 的config.yaml键。而 templates/deployment.yaml 会以subPath: config.yaml方式把该键挂载到容器的/etc/litellm/config.yaml，同时给容器注入启动参数--config /etc/litellm/config.yaml（可用--num_workers声明 worker 数）。此外，Pod 模板上的注解checksum/config会对 ConfigMap 内容做sha256sum，配置一旦变化即触发滚动升级，无需手动重启。

更丰富的真实配置示例可以参考仓库内 litellm/proxy/example_config_yaml/ 目录下的 20+ 份 YAML（含 simple_config.yaml、azure_config.yaml、load_balancer.yaml 等）。

复用既有 ConfigMap

如果希望配置完全脱离 Helm 生命周期管理，可以关闭自动渲染并指向已有对象：

proxyConfigMap: create: false name: my-litellm-config key: config.yaml # 此模式下 proxy_config 被忽略

挂载机制不变——只要 ConfigMap 中存在名为config.yaml的键即可。

注入敏感配置：environmentSecrets 与 environmentConfigMaps

Proxy 所需的 API Key、数据库密码等凭据，最好以“Secret/ConfigMap → 环境变量”的方式注入，而不是写进 proxy_config。Chart 提供两个数组参数：

在 templates/deployment.yaml 中，这些对象分别通过envFrom.secretRef与envFrom.configMapRef展开。注入后的变量就可以在proxy_config中用os.environ/<Env Var Name>引用。官方 README 给出的示例 Secret 结构如下：

apiVersion: v1 kind: Secret metadata: name: litellm-envsecrets data: AZURE_OPENAI_API_KEY: TXlTZWN1cmVLM3k= type: Opaque

使用时在 values 里声明：environmentSecrets: [litellm-envsecrets]，随后配置中写api_key: os.environ/AZURE_OPENAI_API_KEY。同理，非机密类配置可用 ConfigMap：

apiVersion: v1 kind: ConfigMap metadata: name: litellm-env-configmap data: SOME_KEY: someValue ANOTHER_KEY: anotherValue

Kubernetes Secret 的 value 需要 base64 编码（echo -n 'value' | base64），如需查看原始值可用base64 --decode。Chart 在 values.yaml 中还建议了与之互补的envVars、extraEnvVars与logLevel（注入LITELLM_LOG，默认INFO）等直接环境变量入口——注意直接env:条目在 Kubernetes 中优先于envFrom:来源，从 Secret/ConfigMap 注入同名变量时可能被覆盖。

企业版计费计量：billingMetrics（可选）

对于持有企业 License 的部署，该 Chart 支持“可计费请求计量”（billable-request metering）：Proxy 统计发往推理、MCP 与 A2A 端点的成功请求，并通过mTLS把计数器推送到 LiteLLM 的采集端点。

启用步骤：先创建存放客户端证书的 Secret（Chart不会代建证书，只负责把已有证书只读挂载进容器，私钥不经过环境变量，避免泄露）：

kubectl create secret tls litellm-billing-metrics-mtls --cert=client.crt --key=client.key

然后在 values 中开启：

billingMetrics: enabled: true

从源码看，开启后 templates/_helpers.tpl 会注入LITELLM_BILLING_METRICS_ENDPOINT、LITELLM_BILLING_METRICS_CLIENT_CERT、LITELLM_BILLING_METRICS_CLIENT_KEY（以及可选的_CA_CERT、_EXPORT_INTERVAL_MS）环境变量，并把 Secret 以只读方式挂载到/etc/litellm/billing-mtls（和可选的-ca目录）。为防止“静默不导出”，模板对endpoint与secretName使用了required校验：缺失或把 endpoint 置空时，helm install阶段会直接渲染失败，而不是部署一个永远不推送计数的 Proxy。

数据库选型：随包部署还是复用外部 PostgreSQL

LiteLLM Proxy 需要 PostgreSQL 存储虚拟 API Key、Spend Log、Team/用户等管理数据。Chart 支持三种方式：

方式一：随包部署（deployStandalone）

默认db.deployStandalone=true会拉取 postgresql 子 Chart（版本 14.3.1，见 Chart.yaml 的 dependencies），并同步创建<release>-dbcredentialsSecret 供 Proxy 与迁移 Job 使用（见 templates/secret-dbcredentials.yaml）。涉及参数：

• postgresql.*：透传给 Bitnami postgresql 子 Chart 的全部配置，默认值见 values.yaml。
• postgresql.auth.*：数据库账号密码。默认值是NoTaGrEaTpAsSwOrD——务必通过命令行覆盖：

  helm install litellm ./helm/litellm-helm \ --set postgresql.auth.postgres-password=<强密码> \ --set postgresql.auth.password=<强密码>

• postgresql.image.*：随包 Postgres 的镜像。

关于镜像有一个重要坑：Bitnami 已从docker.io/bitnami下架了带版本号的 tag，并把归档构建迁移到docker.io/bitnamilegacy，因此子 Chart 自带的镜像默认值已无法拉取。本 Chart 把随包 Postgres 钉死在bitnamilegacy/postgresql:16.2.0-debian-12-r6，与子 Chart 发布时使用的构建一致，从而保证既有安装的数据目录布局不变。该镜像不再接收更新，因此仅适合“快速起步”；正式环境应把 Postgres 跑在 Chart 之外，用db.useExisting指向它。

请务必保持postgresql.image.tag钉死：docker.io/bitnami/postgresql仍发布浮动的latest，若让随包 Postgres 以不同的主版本启动，会直接对着它读不了的旧数据目录启动，报错database files are incompatible with server，且没有原地回退的办法——跨大版本必须先用旧镜像 dump、再用新镜像 restore。为此，Chart 在渲染dbcredentialsSecret 时（templates/secret-dbcredentials.yaml 调用的litellm.validateBundledPostgresImageTag，定义于 templates/_helpers.tpl）会执行校验：tag 为空或为latest时直接fail拒绝渲染。

方式二：复用外部 PostgreSQL（useExisting）

将db.useExisting置为true后，需要先准备一个含凭据的 Secret（下方示例中的默认名称为postgres）：

apiVersion: v1 kind: Secret metadata: name: postgres data: # "postgres" 用户的密码 postgres-password: <some secure password, base64 encoded> username: litellm password: <some secure password, base64 encoded> type: Opaque

相关参数：

在 templates/deployment.yaml 中，DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_HOST、DATABASE_NAME都会从该 Secret 经secretKeyRef注入，DATABASE_URL则默认通过带$(VAR)占位符的连接串在容器启动时解析。values.yaml 还支持额外的只读副本参数：db.readReplicaUrl、db.secret.readReplicaUrlKey与db.secret.readReplicaEndpointKey，可将DATABASE_URL_READ_REPLICA/DATABASE_READER_HOST指向只读端点（适合 Aurora 风格的读写分离）。官方特别提醒：若只读连接串内嵌凭据，优先用readReplicaUrlKey从 Secret 取值，避免明文出现在 rendered Pod spec 与 Helm release Secret 中。

内置 Redis：跨 Pod 协调（可选）

注：Redis 配置细节主要在 values.yaml 中说明，README 正文未展开，此处作为对生产能力的补充。

Redis 是 Proxy 的协调存储：负责跨 Pod 的 tpm/rpm 限流、Spend 追踪与 Pod 锁管理器。将redis.enabled置为true会部署随包 Redis 子 Chart（版本 18.19.1，见 Chart.yaml），自动注入REDIS_HOST/REDIS_PORT/REDIS_PASSWORD环境变量，并在 templates/configmap-litellm.yaml 中自动往general_settings追加coordination_redis块（若你自己已在proxy_config里定义了该块，则以你的为准）。若redis.sentinel.enabled开启，则会改渲染sentinel_nodes+service_name组合。若要接入已有 Redis，保持enabled: false并自行注入REDIS_HOST等环境变量即可；coordination_redis仅与协调相关，与 LLM 响应缓存（需在配置中设cache: true）相互独立。随包 Redis 的镜像同样被重定向到bitnamilegacy/redis:7.2.4-debian-12-r9。

自动扩缩容与稳定性

Chart 同时支持基于内置的 HPA（autoscaling）与基于事件的 KEDA（keda），两者互斥，同时开启只会以 KEDA 渲染的副本为准。扩展入口位于 templates/hpa.yaml 与 templates/keda.yaml。

• autoscaling：默认关闭；minReplicas=1、maxReplicas=100。文档推荐的targetCPUUtilizationPercentage为 60；CPU 目标不宜设得过高，因为新副本要先过掉 startupProbe（最多约 300 秒）才承接流量，过高的阈值会在接近饱和时才扩容、滞后数分钟。
• values.yaml 中刻意不给内存目标设值：Prisma 查询引擎的常驻内存是“高水位”型——它会一路涨到 Pod 历史最坏写入量且不回落，导致按内存扩容的副本只升不降（ratchet 效应）。内存应作为resources下的供应下限，而非扩缩容信号。
• pdb：开启后为 Deployment 提供自愿中断保护；minAvailable与maxUnavailable必须二选一，两者都设时minAvailable优先。
• terminationGracePeriodSeconds默认 90 秒；strategy可用于配置 RollingUpdate（如maxUnavailable: 0、maxSurge: 1）。

KEDA 场景还可在keda.triggers里声明 Prometheus 等触发源，并配置cooldownPeriod、pollingInterval与scaleDown/scaleUp策略（values.yaml 中提供了带注释的完整样例）。

数据库迁移 Job：schema 谁来做

数据库表结构的创建与升级由一个独立的一次性 Job负责，而不是让每个副本在启动时竞争执行。相关参数：

其模板见 templates/migrations-job.yaml：Job 的容器以command: ["python", "litellm/proxy/prisma_migration.py"]启动（对应源码 litellm/proxy/prisma_migration.py），并把DISABLE_SCHEMA_UPDATE显式置为"false"强制执行迁移。

与 Job 配合的两个关键设计（源码中均有体现）：

1. Proxy 副本跳过 schema 自检：当migrationJob.enabled=true时，templates/deployment.yaml 会给 Proxy 注入DISABLE_SCHEMA_UPDATE=true，从而关闭 Proxy 启动时的prisma db push，避免 N 个副本在每次滚动发布时互相竞争同一数据库。该覆盖项被刻意放在 envVars/extraEnvVars 之后渲染，防止用户自定义的同名变量把它顶掉。
2. GitOps 双钩子支持：ArgoCD 场景使用argocd.argoproj.io/hook: PreSync（在同步应用前先跑迁移）；纯 Helm 场景可开启migrationJob.hooks.helm.enabled使用pre-install,pre-upgrade钩子。两者都配了BeforeHookCreation/before-hook-creation删除策略，保证每次部署前旧的迁移 Job 会被清除。values.yaml 中另外提供了两个安全兜底：migrationJob.activeDeadlineSeconds=1800（整个 Job 的墙钟预算，共享给所有重试，防止迁移阻塞时helm upgrade/GitOps 控制器无限期卡死，可置null恢复不设限）、migrationJob.disableSchemaUpdate（跳过 schema 迁移并让 Job 以 0 退出）。

访问 Admin UI 与密钥取回

填入端点与主密钥

部署就绪后，浏览器访问ingress.*发布的 URL，页面会要求Admin Configuration配置：

• Proxy Endpoint：填入从litellmPod 视角看的内网 Service URL。使用默认 Service 设置时，应填http://<RELEASE>-litellm:4000。
• Proxy Key：填入masterkey参数值；若安装时未指定，则是 Chart 首次安装时随机生成、存储在<RELEASE>-litellm-masterkeySecret 中的sk-...字符串。

通过 kubectl 取回主密钥

忘记主密钥时可用如下命令从 Secret 读取：

kubectl -n litellm get secret <RELEASE>-litellm-masterkey -o jsonpath="{.data.masterkey}"

注意该命令输出的仍是 base64 编码，需要解码后使用（如... | base64 --decode）。再次强调：该值只在首次安装时生成，之后的helm upgrade都会复用 Secret 中已有值，升级不会导致主密钥轮换。

Admin UI 的已知限制

截至本文写作时，Admin UI无法通过界面新增模型。原因在于：添加模型需要更新config.yaml，而该文件来自挂载的 ConfigMap，对运行中的 Pod 是只读的。这是当前 Helm Chart 的架构性限制，而非 Admin UI 本身的功能缺陷。需要变更模型路由时，应回到proxy_config（或外部 ConfigMap）修改并重新helm upgrade，借助上文提到的checksum/config注解自动触发滚动更新。

常见生产问题速查

总结与延伸阅读

litellm-helm 的价值在于把“LiteLLM Proxy + PostgreSQL + 迁移 Job”打包成一套可直接helm install、又能渐进式替换外部依赖的部署单元。要点可归纳为四条主线：

1. 配置即代码：proxy_config渲染进只读 ConfigMap，模型/路由变更走helm upgrade滚动生效；API Key 一律通过os.environ/...引用注入的环境变量，避免明文入库。
2. 密钥自动管理：Master Key 首次生成、升级复用，也可完全交给外部 Secret。
3. 数据库两态：deployStandalone适合体验与 CI，生产建议useExisting指向托管 PostgreSQL，并注意镜像 tag 钉死与跨版本迁移策略。
4. 迁移与 GitOps：Prisma schema 迁移由独立 Job 承担，天然支持 ArgoCD PreSync 与 Helm pre-install/pre-upgrade 两种编排。

对某一类配置想深入了解时，可对照源码继续钻研：values.yaml（所有参数与注释）、templates/（渲染逻辑）、helm/litellm-helm/tests/（Chart 自测用例）、litellm/proxy/example_config_yaml/（LiteLLM 侧真实配置样例）。若 Chart 版本与 Proxy 镜像需要同步升级，直接修改 Chart.yaml 中的appVersion或覆盖image.tag即可。

【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm