1. Rancher 部署里环境变量到底解决什么问题在 Rancher 里跑工作负载环境变量是最容易被低估的一环。很多人第一次接触 Rancher 环境变量是因为 Pod 起不来、日志里报鉴权失败或者本地跑得好好的镜像一放进集群就连接超时。Rancher 环境变量能做什么简单说它把配置从镜像里剥离出来让同一份镜像在开发、测试、生产环境用不同参数运行而不用重新构建。适合谁适合所有用 Rancher 管理 Kubernetes 工作负载、又需要接入外部 API 服务的开发和运维同学。我这次要解决的场景很具体团队在 Rancher 上部署了一批内部工具和 Agent 服务这些服务都要调用大模型 API。早期做法是把 Key 硬编码进镜像或者写进 ConfigMap 明文结果轮换一次 Key 就要重新打包、重新发版还容易在多个命名空间里漏改。后来统一改成通过 Rancher 环境变量注入配合 TaoToken 的统一 Key 通道一次配置、多服务复用轮换时只改一处。Rancher 环境变量的配置入口有两类一类是 Rancher 自身组件比如 cattle-system 里的 rancher deployment另一类是用户自己的工作负载。前者常用kubectl set env临时调或者 Helm 的extraEnv持久化后者则在 Rancher UI 的「环境变量」标签页或 Deployment YAML 的env字段里配置。本文重点放在用户工作负载上因为这才是日常部署最常碰到的部分同时也会带上 Rancher 自身组件的对照写法方便你区分两者。需要提前说清楚一个边界环境变量适合放非敏感配置和需要灵活切换的参数。真正敏感的 Key更稳妥的做法是配合 Secret 引用而不是把明文直接写进 YAML。下面我会两种都演示你可以按自己的安全要求选。2. TaoToken 前置统一 Key 与 API 通道准备在把 Key 注入 Rancher 之前得先有一个可用的 Key 和明确的接入地址。TaoToken 在这里扮演的是统一 API 通道的角色你拿到一个 Key就能通过同一个入口调用多种模型不用为每个模型单独维护一套鉴权和地址。对 Rancher 这种多服务部署场景来说好处是环境变量只需要维护一份API_KEY和一个BASE_URL服务代码里不用写死具体厂商。第一步是拿到 Key。登录控制台后进入 API Keys 页面创建建议按环境或按服务拆分多个 Key比如rancher-dev、rancher-prod这样某个环境泄露时可以单独吊销不影响其他环境。创建后立刻复制保存页面刷新后通常不再完整显示。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_envAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_env接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_env第二步是确认接入地址。API 基础地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为BASE_URL使用。很多接入失败是因为把带 UTM 的官网地址误当成了 API 地址这两者要分清楚官网是给人看的API 是给程序调的。第三步是本地先验证 Key 可用再往 Rancher 里塞。这一步能帮你把「Key 本身有问题」和「Rancher 配置有问题」两类故障分开省掉大量排查时间。本地验证用一条 curl 就够curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json | head -c 500如果返回模型列表说明 Key 和网络都通。如果返回 401检查 Key 是否复制完整如果超时检查集群或本机出网策略。这一步过了再进 Rancher 配置心里就有底了。3. 可复制配置Rancher Deployment 环境变量片段现在进入正题。Rancher 里给工作负载加环境变量最直接的方式是编辑 Deployment YAML。下面是一份可以直接改改就用的片段包含明文和 Secret 引用两种写法你可以按需取舍。apiVersion: apps/v1 kind: Deployment metadata: name: ai-agent-demo namespace: default spec: replicas: 1 selector: matchLabels: app: ai-agent-demo template: metadata: labels: app: ai-agent-demo spec: containers: - name: agent image: your-registry/ai-agent:1.0.0 env: # 方式一明文注入适合非敏感配置 - name: TAOTOKEN_BASE_URL value: https://taotoken.net/api - name: TAOTOKEN_MODEL value: claude-3-5-sonnet # 方式二从 Secret 引用适合敏感 Key - name: TAOTOKEN_API_KEY valueFrom: secretKeyRef: name: taotoken-secret key: api-key ports: - containerPort: 8080对应的 Secret 这样创建注意用stringData可以直接写明文kubectl 会自动做 base64 编码apiVersion: v1 kind: Secret metadata: name: taotoken-secret namespace: default type: Opaque stringData: api-key: sk-你的实际Key如果你更习惯命令行也可以直接kubectl -n default create secret generic taotoken-secret \ --from-literalapi-keysk-你的实际Key在 Rancher UI 里操作的话路径是进入集群 → 工作负载 → 找到目标 Deployment → 编辑 → 环境变量 → 添加变量。UI 里同样支持「来自 Secret」的引用方式选好 Secret 和 key 即可效果和 YAML 一致。UI 适合快速改YAML 适合纳入 GitOps 版本管理团队协作建议后者。这里有个容易忽略的点环境变量名建议统一加前缀比如TAOTOKEN_避免和镜像里已有的变量冲突。我见过因为变量名撞车导致服务读到了错误地址的情况排查起来很费时间。4. 验证请求与成功结果确认配置保存后Rancher 会自动滚动更新 Pod。接下来要确认三件事变量注入了、服务能读到、请求能通。先看 Pod 是否正常起来kubectl -n default get pods -l appai-agent-demo状态是Running且READY 1/1才算正常。如果一直CrashLoopBackOff多半是变量缺失导致启动失败先看日志。确认环境变量真的进了容器kubectl -n default exec deploy/ai-agent-demo -- env | grep TAOTOKEN预期能看到类似输出TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELclaude-3-5-sonnet TAOTOKEN_API_KEYsk-xxxx注意如果 Key 是通过 Secret 注入的这里会显示实际值所以别在共享终端里随便执行避免泄露。最后在容器内发一次真实请求验证整条链路kubectl -n default exec deploy/ai-agent-demo -- sh -c curl -s $TAOTOKEN_BASE_URL/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {\model\:\$TAOTOKEN_MODEL\,\messages\:[{\role\:\user\,\content\:\ping\}]} 返回里带choices字段和内容就说明 Rancher 环境变量注入、Secret 读取、TaoToken 通道全部打通。如果只想快速验证模型是否可用也可以直接在模型对话页面手动发一条消息对照结果。5. 本篇常见错误排查配置过程中踩坑是常态下面这几个是我和团队实际遇到频率最高的。变量没生效容器里读不到。最常见原因是改了 Deployment 但没触发滚动更新或者改的是错误的命名空间。确认kubectl -n namespace get deploy里的副本数和更新时间必要时手动kubectl rollout restart deploy/ai-agent-demo。Secret 引用报CreateContainerConfigError。通常是 Secret 名字或 key 写错或者 Secret 和 Pod 不在同一命名空间。Secret 是命名空间级别的资源跨命名空间引用需要额外处理别想当然。请求返回 401。先确认 Key 有没有多余空格或换行Secret 里粘贴时很容易带上。再确认Authorization头格式是Bearer key中间一个空格。请求超时或连接被拒。检查集群出网策略、NetworkPolicy 是否放行了到taotoken.net的流量。有些集群默认限制出网需要单独配置。Rancher 自身组件变量被覆盖。如果你改的是cattle-system里的 rancher deployment用kubectl set env设的变量会在下次 Helm 升级时被覆盖。要持久化得写进 Helm 的extraEnv。验证当前值可以用kubectl -n cattle-system exec rancher-pod -- env | grep CATTLE变量名大小写问题。环境变量在 Linux 容器里区分大小写taotoken_api_key和TAOTOKEN_API_KEY是两个变量代码里读哪个就配哪个别混。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔跑个脚本上面的配置就够了。但如果是在 Rancher 上长期跑编码类 Agent、需要稳定调用模型建议把 Key 管理和调用方式再规范一层。一是按服务拆分 Key每个 Agent 用独立 Key方便审计和吊销。二是把BASE_URL、MODEL这类非敏感变量放 ConfigMapKey 放 Secret职责分开。三是把 Deployment YAML 纳入 Git 仓库环境变量变更走 PR 流程避免有人在 UI 上随手改导致配置漂移。对于需要长期编码、跑 Agent 工作流的场景可以了解下 Coding Plan它更适合高频、持续的调用模式配合 Rancher 环境变量注入能做到一次配置、多副本复用。相关入口Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_env模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_env接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentrancher_env最后留一个实用习惯每次改完环境变量别只看 Pod 起来了就完事一定进容器env | grep确认一遍再发一次真实请求。这两步花不了一分钟但能挡掉后面几小时的排查。