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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_env
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_env
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_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-literal=api-key='sk-你的实际Key'在 Rancher UI 里操作的话，路径是：进入集群 → 工作负载 → 找到目标 Deployment → 编辑 → 环境变量 → 添加变量。UI 里同样支持「来自 Secret」的引用方式，选好 Secret 和 key 即可，效果和 YAML 一致。UI 适合快速改，YAML 适合纳入 GitOps 版本管理，团队协作建议后者。
这里有个容易忽略的点：环境变量名建议统一加前缀，比如TAOTOKEN_，避免和镜像里已有的变量冲突。我见过因为变量名撞车导致服务读到了错误地址的情况，排查起来很费时间。
4. 验证请求与成功结果确认
配置保存后，Rancher 会自动滚动更新 Pod。接下来要确认三件事：变量注入了、服务能读到、请求能通。
先看 Pod 是否正常起来：
kubectl -n default get pods -l app=ai-agent-demo状态是Running且READY 1/1才算正常。如果一直CrashLoopBackOff，多半是变量缺失导致启动失败，先看日志。
确认环境变量真的进了容器：
kubectl -n default exec deploy/ai-agent-demo -- env | grep TAOTOKEN预期能看到类似输出：
TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=claude-3-5-sonnet TAOTOKEN_API_KEY=sk-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这类非敏感变量放 ConfigMap，Key 放 Secret，职责分开。三是把 Deployment YAML 纳入 Git 仓库，环境变量变更走 PR 流程，避免有人在 UI 上随手改导致配置漂移。
对于需要长期编码、跑 Agent 工作流的场景，可以了解下 Coding Plan，它更适合高频、持续的调用模式，配合 Rancher 环境变量注入，能做到一次配置、多副本复用。相关入口：
- Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_env
- 模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_env
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=rancher_env
最后留一个实用习惯：每次改完环境变量，别只看 Pod 起来了就完事，一定进容器env | grep确认一遍，再发一次真实请求。这两步花不了一分钟，但能挡掉后面几小时的排查。
