K3S 上用 Helm 部署 HelmChart 与 HelmChartConfig：TaoToken 统一 Key 的 config.toml 骨架

1. 为什么要在 K3S 里用 HelmChart CRD 管 AI KeyK3S 自带一个 Helm Controller它把 Helm 的安装动作变成了 Kubernetes 里的声明式资源。你不再需要登录到某台机器上敲helm install而是写一个kind: HelmChart的 YAML丢进/var/lib/rancher/k3s/server/manifests/目录K3S 启动时会自动把它 apply 进去Helm Controller 再拉起一个 Job 去执行真正的 Helm 安装。这套机制对离线、内网、边缘节点特别友好因为整个流程不依赖外网 Helm 仓库chart 可以提前放进/var/lib/rancher/k3s/server/static/charts/。我这次要解决的场景是集群里跑着好几个 AI 工具命令行助手、代码补全、Agent 框架每个工具都要配 API Key 和 base_url。如果每个工具单独维护一份配置改一次 Key 要动好几处还容易漏。于是我把这些工具的配置统一收敛到一份config.toml里用 HelmChart 部署应用本体用 HelmChartConfig 注入这份统一配置Key 只在一个地方维护。TaoToken 的 API 地址是https://taotoken.net/api它兼容常见的 OpenAI 风格调用所以config.toml里主要就是base_url和api_key两个字段。这篇适合谁已经在用 K3S、想用声明式方式管理 AI 工具配置的运维或者你手上有一台内网机器想离线部署一套带统一 Key 的 AI 工具链。下面从 HelmChart 骨架开始一步步给出可复制的 YAML、config.toml 片段以及验证 CRD 状态和 Key 是否生效的 kubectl 动作。2. TaoToken 前置拿到统一 Key 和接入地址在写 YAML 之前先把 Key 准备好。TaoToken 的控制台里可以创建 API Key这个 Key 就是后面config.toml里要填的值。创建入口在控制台的 API Keys 页面建议按用途命名比如k3s-ai-tools方便以后轮换时定位。拿到 Key 之后你需要确认两件事一是接入地址二是模型名。接入地址用https://taotoken.net/api注意这里不带任何查询参数直接作为 base_url 使用。模型名可以在模型对话页面里试跑一下确认你要用的模型在列表里避免配置写好了却因为模型名不对而报 404。如果你只是想在本地先验证 Key 能不能用可以打开模型对话页面选一个模型发一条消息能正常返回就说明 Key 有效。这一步不用写代码适合先排除 Key 本身的问题。等确认 Key 没问题再进入 K3S 的 YAML 环节。对于长期跑在集群里的编码类工具或 Agent建议单独规划一个 Coding Plan 的额度避免和临时调试共用同一个 Key 导致额度互相挤占。控制台里可以给不同 Key 设置不同的用途标签运维时一眼能看出哪个 Key 是给集群用的。3. 可复制配置HelmChart 与 HelmChartConfig 骨架先明确目录约定。K3S 会自动监听/var/lib/rancher/k3s/server/manifests/下的 YAML文件名必须符合 RFC 1123 子域名规范也就是只能用小写字母、数字、-和.不能有下划线。我踩过的坑就是文件名里带了_结果 Helm Controller 报metadata.name: Invalid value日志在journalctl -u k3s里能看到。所以下面所有文件名都用短横线。3.1 HelmChart 骨架部署 AI 工具本体假设我们要部署一个叫ai-toolbox的应用它需要一个 ConfigMap 来挂载config.toml。HelmChart 负责把 chart 装进集群chart 本身可以放在本地静态目录也可以用完整 HTTPS URL。离线场景推荐放本地# /var/lib/rancher/k3s/server/manifests/ai-toolbox-helmchart.yaml apiVersion: helm.cattle.io/v1 kind: HelmChart metadata: name: ai-toolbox namespace: kube-system spec: chart: https://%{KUBERNETES_API}%/static/charts/ai-toolbox-0.1.0.tgz targetNamespace: ai-tools version: 0.1.0 timeout: 300 failurePolicy: reinstall valuesContent: |- replicaCount: 1 image: repository: your-registry/ai-toolbox tag: 0.1.0 config: mountPath: /etc/ai-toolbox/config.toml几个字段说明一下。chart里的%{KUBERNETES_API}%是 K3S 的特殊变量会被替换成集群内可达的 API Server 地址这样节点不需要外网就能拉到/var/lib/rancher/k3s/server/static/charts/下的 tgz。targetNamespace是 chart 实际部署到的命名空间和 HelmChart 资源本身所在的kube-system是两回事。failurePolicy: reinstall表示安装失败时重装调试阶段比较省心生产环境可以改成abort失败后等人工介入。3.2 HelmChartConfig 骨架注入统一 config.tomlHelmChartConfig 的唯一作用就是给同名的 HelmChart 追加一份 values。它的metadata.name和metadata.namespace必须和对应的 HelmChart 完全一致否则不会生效。下面这份配置把config.toml的内容通过 values 传进去# /var/lib/rancher/k3s/server/manifests/ai-toolbox-helmchartconfig.yaml apiVersion: helm.cattle.io/v1 kind: HelmChartConfig metadata: name: ai-toolbox namespace: kube-system spec: valuesContent: |- config: content: |- [default] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model gpt-4o-mini [tools.code_assistant] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-3-5-sonnet [tools.agent] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model gpt-4o注意spec.set的优先级高于valuesContent。如果你在 HelmChart 里用set写了某个值HelmChartConfig 里的valuesContent是覆盖不掉的。所以统一 Key 这种需要后期灵活修改的内容全部放在 HelmChartConfig 的valuesContent里HelmChart 里不要用set写同样的字段。3.3 config.toml 骨架多工具共用一份 Key上面 values 里的config.content最终会被 chart 渲染成一个 ConfigMap挂载到容器里。config.toml的结构可以按工具分组每个工具都能独立指定模型但base_url和api_key统一指向 TaoToken[default] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model gpt-4o-mini timeout 60 [tools.code_assistant] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-3-5-sonnet max_tokens 8192 [tools.agent] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model gpt-4o temperature 0.2这样设计的好处是轮换 Key 时只改 HelmChartConfig 里的api_key重新 apply 后 Helm Controller 会触发一次 upgrade所有工具同时拿到新 Key。不需要逐个进容器改配置。4. 验证请求CRD 状态与 Key 生效检查YAML 写完后把两个文件放进 manifests 目录K3S 会自动处理。但自动处理不代表一定成功下面这几步是必须做的验证。4.1 检查 HelmChart 和 HelmChartConfig 是否被识别kubectl get helmchart -n kube-system kubectl get helmchartconfig -n kube-system正常输出里应该能看到ai-toolboxHelmChart 的STATUS列最终会变成deployed。如果一直是空或者报错先看 Helm Controller 的 Jobkubectl get job -n kube-system | grep ai-toolbox kubectl logs -n kube-system job/helm-install-ai-toolboxJob 的日志里会打印 Helm 的实际执行过程chart 拉取失败、values 渲染失败都会在这里暴露。4.2 检查目标命名空间里的资源kubectl get all -n ai-tools kubectl get configmap -n ai-tools确认 Pod 是 RunningConfigMap 存在。然后进容器看挂载的config.toml内容kubectl exec -n ai-tools deploy/ai-toolbox -- cat /etc/ai-toolbox/config.toml如果这里看到的api_key还是旧值说明 HelmChartConfig 没生效回去检查metadata.name和metadata.namespace是否和 HelmChart 一致。4.3 验证 Key 真的能调通光看配置文件不够要实际发一次请求。可以在容器里用 curl 打 TaoToken 的接口kubectl exec -n ai-tools deploy/ai-toolbox -- \ curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}返回里带choices字段就说明 Key 和 base_url 都对。如果返回 401检查 Key 是否复制完整返回 404检查模型名是否在 TaoToken 的模型列表里。4.4 检查 AddOn 状态K3S 把 manifests 目录下的资源当作 AddOn 管理可以用kubectl get addon -A这里能看到ai-toolbox对应的 AddOn 是否 ready。AddOn 的状态和 HelmChart 的状态是联动的AddOn 异常时优先看 HelmChart 的 Job 日志。5. 本篇常见错排查5.1 文件名带下划线导致 CRD 创建失败报错长这样Addon.k3s.cattle.io ai_toolbox is invalid: metadata.name: Invalid value: ai_toolbox: a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, - or .解决方式就是把文件名和metadata.name里的下划线全部换成短横线。这个错误不会让 K3S 崩溃但对应的 AddOn 不会创建HelmChart 也不会被处理很容易被忽略。5.2 HelmChartConfig 不生效最常见的原因是metadata.name或metadata.namespace和 HelmChart 对不上。HelmChartConfig 是通过名字关联的名字差一个字符就不会合并。另一个原因是 HelmChart 里用了spec.set写了同一个字段set优先级更高把valuesContent覆盖了。排查时先kubectl get helmchart ai-toolbox -n kube-system -o yaml看spec.set里有没有冲突字段。5.3 chart 拉取失败如果spec.chart用的是外网 URL内网节点会超时。离线环境务必把 tgz 放到/var/lib/rancher/k3s/server/static/charts/然后用%{KUBERNETES_API}%引用。放进去之后确认文件权限可读文件名和spec.chart里的路径完全一致。5.4 Key 生效但工具仍报鉴权失败有时候config.toml内容是对的但工具进程启动时读的是环境变量而不是配置文件。检查 chart 的 Deployment 模板里有没有env覆盖了config.toml的值。环境变量优先级通常高于配置文件这种情况要把环境变量去掉或者让环境变量也指向同一份 Key。5.5 修改 HelmChartConfig 后没有触发升级Helm Controller 监听的是资源变更事件。如果你直接改了 manifests 目录下的文件K3S 会重新 apply正常会触发。但如果你是用kubectl edit改的改完要确认resourceVersion变了。最稳妥的方式还是改文件后等 K3S 自动同步或者手动kubectl apply -f一次。6. 把 Key 收敛到一处之后整套流程跑通后集群里所有 AI 工具的 Key 都来自同一份 HelmChartConfig。轮换 Key 时只改一个文件K3S 自动触发 Helm upgrade各工具重新挂载 ConfigMap。这个模式对离线内网特别合适因为 chart 和配置都在本地不依赖外部仓库。如果你还想在集群外快速验证某个模型是否可用可以直接用模型对话页面试跑不用改集群配置。需要管理多个 Key 或查看额度时控制台里的 API Keys 页面可以按用途分类。对于长期跑 Agent 或编码任务的场景建议单独规划 Coding Plan把稳定额度和临时调试分开避免互相影响。接入文档里有完整的接口说明配置config.toml时遇到字段不确定的地方可以对照查阅。