企业官网建设流程全解析

1. 为什么要在 drone+gogs 流水线里统一 AI Key

如果你已经用 drone + gogs 搭了一套轻量级 CI/CD，大概率会遇到一个很具体的麻烦：流水线里想加一点 AI 能力，比如自动生成 commit 摘要、跑代码审查、给构建产物写说明，结果每个 step 都要单独配一遍 Key。今天用某个模型的 Key，明天换一个工具又要改环境变量，改到最后.drone.yml里全是散落的密钥，谁也不敢动。

我这次要解决的就是这件事：在容器化的 drone + gogs 流水线里，用 TaoToken 作为统一的 API 通道，把 Key 收敛到一份settings.json配置骨架里，让流水线内的 AI 工具都从同一个入口取配置。TaoToken 在这里扮演的角色是统一 Key 与 API 通道，你只需要维护一份配置，就能让多个构建步骤复用同一套接入信息。它适合已经在跑自建 CI/CD、想把 AI 能力嵌进构建流程、又不想把密钥散落各处的开发者。

整篇会按这个顺序走：先说清楚问题场景，再把 TaoToken 的前置准备讲明白，然后给出可直接复制的settings.json骨架和.drone.yml挂载方式，接着触发一次流水线验证 Key 注入是否成功，最后把常见的报错逐个排查掉。全程都是容器内的操作，不涉及任何网络层面的额外配置。

需要提前说明的是，本文的配置骨架是围绕「统一 Key 注入」这个目标设计的，不替代你现有的 drone runner 架构，也不改变 gogs 的仓库管理逻辑。你原来的docker-compose.yml和.drone.yml结构可以保留，只是在需要 AI 能力的 step 上多挂一个配置文件。

2. TaoToken 前置准备：拿到统一 Key 与通道地址

在写配置之前，先把 TaoToken 这边的准备工作做完。这一步不复杂，但顺序别搞反，否则后面流水线里会一直报鉴权失败。

首先你需要一个可用的 TaoToken 账号，登录后进入控制台。控制台地址是 https://taotoken.net/console ，登录之后找到 API Keys 管理页面，新建一个 Key。这个 Key 就是后面要写进settings.json的核心凭证。建议按用途命名，比如drone-cicd，方便以后区分是哪个流水线在用。

拿到 Key 之后，确认两件事：一是 API 通道地址，统一用 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 base URL 使用；二是确认你要调用的模型名称，这个在模型对话页面能看到当前可用的模型列表，地址是 https://taotoken.net/models 。如果你后面打算在流水线里跑长期编码类任务，也可以了解一下 Coding Plan 的用法，地址是 https://taotoken.net/coding-plan ，它更适合持续性的代码生成场景。

这里有个容易踩的坑：很多人会把 Key 直接写进.drone.yml的environment里，这样虽然能跑，但密钥就明文躺在仓库里了。正确做法是把 Key 放进 drone 的 secret，或者放进挂载进容器的settings.json，让配置文件本身不进版本库。本文用的是后者，因为settings.json这种骨架更适合多工具复用。

另外提醒一句，TaoToken 的接入文档在 https://taotoken.net/doc ，里面有针对不同工具链的配置示例，遇到不确定的字段可以先翻一下。API Keys 页面在 https://taotoken.net/api-keys ，新建和吊销 Key 都在这里操作。

3. 可复制的 settings.json 配置骨架

这一节是全文的核心。我们要做的，是设计一份settings.json，让它同时满足三个条件：结构清晰、能被多个 AI 工具读取、Key 不硬编码在仓库里。

先看骨架本身。这份配置放在项目根目录的ci/文件夹下，文件名就叫settings.json：

{ "provider": "taotoken", "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "default_model": "claude-sonnet", "timeout_seconds": 60, "tools": { "commit_summary": { "enabled": true, "model": "claude-sonnet", "max_tokens": 512 }, "code_review": { "enabled": true, "model": "claude-sonnet", "max_tokens": 2048 }, "release_note": { "enabled": false, "model": "claude-sonnet", "max_tokens": 1024 } } }

这份骨架的设计思路是这样的：base_url固定指向 TaoToken 的 API 通道，所有工具共用；api_key_env不直接写 Key，而是写一个环境变量名，真正的 Key 由 drone 在运行时注入；tools下面按用途分组，每个工具可以单独开关、单独指定模型和 token 上限。这样你以后加新工具，只需要在tools里加一段，不用动其他配置。

接下来是 Key 的注入方式。在 drone 里，推荐用 secret 来存 Key，然后在.drone.yml的 step 里把它映射成环境变量。先在 drone 的仓库设置里添加一个 secret，名字叫taotoken_api_key，值就是你从控制台拿到的那个 Key。然后在.drone.yml里这样写：

kind: pipeline type: docker name: ai-build steps: - name: ai-commit-summary image: alpine:3.19 environment: TAOTOKEN_API_KEY: from_secret: taotoken_api_key commands: - apk add --no-cache curl jq - cat ci/settings.json | jq '.provider' - echo "key length is ${#TAOTOKEN_API_KEY}"

注意这里没有把 Key 打印出来，只打印了长度，这是为了验证注入成功又不泄露凭证。settings.json通过仓库本身带进工作目录，drone 默认会把仓库 clone 到/drone/src，所以ci/settings.json的相对路径是能读到的。

如果你用的是绑定挂载模式，想让配置文件从宿主机直接挂进容器，可以在 runner 的 volumes 里加一条。但更推荐的做法还是让配置文件跟着仓库走，因为这样配置的版本和代码的版本是对齐的，回滚代码的时候配置也一起回滚。

这里再强调一次：settings.json里绝对不要出现真实的 Key 字符串。api_key_env这个字段的作用就是告诉工具「去哪个环境变量里找 Key」，而不是「Key 是什么」。这个区分是整份骨架能安全进仓库的前提。

4. 触发一次流水线验证 Key 注入与调用链路

配置写完了，接下来要验证它真的能用。验证分两步：先确认 Key 注入成功，再确认能通过 TaoToken 的通道完成一次真实调用。

第一步，提交上面的.drone.yml和ci/settings.json到 gogs 仓库，drone 会自动触发一次构建。如果你之前禁用了默认 clone，记得用你自定义的 pull step 把代码同步到工作目录。构建开始后，打开 drone 的构建日志，找到ai-commit-summary这个 step，你应该能看到类似这样的输出：

taotoken key length is 48

第一行说明settings.json被正确读取，provider字段是taotoken；第二行说明环境变量TAOTOKEN_API_KEY已经被注入，长度符合预期。如果长度是 0，说明 secret 没映射上，回到上一节检查from_secret的名字是否和 drone 里配置的一致。

第二步，做一次真实的 API 调用。在同一个 step 里加一段 curl，走 TaoToken 的通道请求一次模型对话：

- name: ai-call-test image: alpine:3.19 environment: TAOTOKEN_API_KEY: from_secret: taotoken_api_key commands: - apk add --no-cache curl jq - | curl -s -X POST https://taotoken.net/api/v1/messages \ -H "Authorization: Bearer ${TAOTOKEN_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet", "max_tokens": 64, "messages": [{"role": "user", "content": "reply with ok"}] }' | jq -r '.content[0].text'

这段命令做的事情很直接：用注入的 Key 向 TaoToken 的 API 通道发一条最小请求，然后把返回内容里的文本字段提取出来。如果一切正常，日志里会打印出模型返回的简短回复。这一步跑通，就说明从 drone 的 secret 注入、到settings.json的配置读取、再到 TaoToken 通道的调用，整条链路是通的。

实测下来，这个验证动作最好固定成一个独立的 step，每次改配置后都跑一遍。因为 CI/CD 里的 AI 调用一旦失败，往往是在构建后期才暴露，排查成本很高。把它前置成一个快速检查，能省很多时间。

如果你在验证时想直接和模型对话确认通道可用，也可以打开 https://taotoken.net/models 在页面上手动发一条消息，对比一下返回是否正常。页面能通、流水线不通，问题基本就锁定在 Key 注入或配置读取上了。

5. 本篇常见错排查

配置跑不通的时候，报错信息往往不会直接告诉你哪里错了。下面这几个是我在 drone + gogs 环境里遇到过的典型问题，按出现频率排序。

第一个，401 Unauthorized或者invalid api key。这个最常见，原因通常是 secret 名字对不上，或者 Key 复制的时候带了空格。检查方法是在 step 里打印${#TAOTOKEN_API_KEY}，看长度是不是和你在控制台看到的一致。如果长度对但依然 401，去 https://taotoken.net/api-keys 确认这个 Key 没有被吊销，也没有超出配额。

第二个，settings.json读取不到，报no such file or directory。这是因为 drone 的工作目录和你以为的不一样。drone 默认把仓库 clone 到/drone/src，如果你的 step 里cd到了别的地方，相对路径就失效了。解决办法是在命令里用绝对路径/drone/src/ci/settings.json，或者先pwd打印一下当前目录确认位置。

第三个，用了自定义 pull step 之后，配置文件没被同步过来。如果你禁用了默认 clone，改用alpine/git手动 pull，要注意cp的时候把ci/目录也带上。很多人只 copy 了源码目录，漏掉了配置文件，结果 step 里读不到settings.json。检查一下你的cp -R命令覆盖的范围。

第四个，curl返回空或者超时。先确认容器内能解析taotoken.net，可以用nslookup或ping测一下。如果解析正常但请求超时，检查 runner 所在宿主机的出站规则，确认 443 端口是放行的。注意这里说的是容器到外部的正常 HTTPS 出站，不涉及任何特殊网络配置。

第五个，模型名称写错导致model not found。settings.json里的default_model和每个 tool 下的model字段，必须和 TaoToken 当前支持的模型名一致。去 https://taotoken.net/models 核对一下，别凭记忆写。模型名是大小写敏感的，claude-sonnet和Claude-Sonnet可能被当成两个不同的东西。

第六个，drone 的 runner 标签不匹配，step 一直排队不执行。如果你在.drone.yml里指定了node: machine1: runner1，要确认 runner 启动时的DRONE_RUNNER_LABELS和这个值完全一致。标签对不上，step 就会一直卡在 pending 状态，日志里什么都不会有。

把这几个排查点过一遍，基本能覆盖 90% 的配置问题。剩下的如果还搞不定，去 https://taotoken.net/doc 翻一下接入文档，里面有针对不同工具链的完整示例，对照着改通常能定位到差异。

6. 把统一 Key 接入固化进你的流水线

走到这里，你应该已经跑通了一次完整的验证：Key 从 drone secret 注入，settings.json被正确读取，TaoToken 通道返回了正常结果。接下来要做的，是把这套配置固化下来，让它成为流水线的标准动作。

我的建议是，把ci/settings.json作为配置的唯一入口，所有需要 AI 能力的 step 都从这里读参数，而不是各自写各自的。新增工具的时候，只在tools里加一段，然后在.drone.yml里加一个对应的 step，环境变量统一用TAOTOKEN_API_KEY。这样密钥只有一份，配置只有一份，维护成本最低。

如果你后面要在流水线里跑更重的编码任务，比如自动修复 lint 问题、生成测试用例，可以考虑把这类任务单独拆成一个 pipeline，用 Coding Plan 的额度来跑，地址是 https://taotoken.net/coding-plan 。日常的轻量调用，比如 commit 摘要、构建通知，用普通的 API Key 就够了。

最后留一个实用技巧：在settings.json里给每个 tool 加一个enabled开关，调试阶段只开你要测的那个，避免一次触发太多调用把日志刷爆。等确认稳定了再逐个打开。这个习惯在多人协作的仓库里尤其有用，别人看到配置就知道哪些能力是开着的，不用去翻.drone.yml。

配置骨架和验证动作都已经给全了，剩下的就是把它提交到你的 gogs 仓库，触发一次构建，看着日志里打出那个ok。