1. 为什么自建 Confluence 后还要折腾 Base URL
很多团队用 Docker 把 Confluence 跑起来之后，第一反应是「能打开就行」。但真正开始接入内部工具链时，问题就冒出来了：Confluence 里配置的 Base URL 指向的是http://localhost:8090或者某个内网 IP，而你在外面访问用的是域名；更麻烦的是，当你想让 Confluence 里的宏、插件、Webhook 去调用统一的模型 API 通道时，请求发出去的目标地址是写死在 Base URL 上的，改不动。
我试过在一个小团队的知识库里做这件事：Confluence 负责文档沉淀，同时希望它能通过 REST API 把页面内容送到统一的大模型通道做摘要、翻译、问答索引。结果发现 Confluence 的 Base URL 一旦设错，连它自己的健康检查都过不了，更别说让外部服务回调进来。
所以这篇要解决的核心问题是：用 Docker Compose 把 Confluence 跑起来之后，如何把它的 Base URL 正确指向 TaoToken 的统一 API 通道，并验证一次请求真的能通。
先说清楚 TaoToken 是什么、能做什么、适合谁。TaoToken 是一个统一的大模型 API 接入层，你可以把它理解成一个「API 网关 + Key 管理 + 模型路由」的组合。它对外暴露一个兼容 OpenAI 风格的 Base URL，你拿一个 Key 就能调用多个模型，不用为每个模型单独申请账号、单独记 endpoint。适合的人群很明确：自建知识库、自建 Wiki、自建内部工具的开发者，尤其是那些希望把模型能力嵌进现有系统、又不想维护一堆 Key 的人。
Confluence 本身不直接「调用大模型」，但它的 REST API 和插件体系可以。你要做的是让 Confluence 所在的容器网络能访问到 TaoToken 的 API 地址，并且把 Confluence 的 Base URL 配置成外部可访问的域名，这样回调、Webhook、健康检查才不会互相打架。
这里有个容易混淆的点：Confluence 的 Base URL 和 TaoToken 的 Base URL 是两个东西。前者是 Confluence 自己对外暴露的地址，后者是模型 API 的入口。本文要改的是 Confluence 的 Base URL，让它指向一个稳定的、外部可达的地址，同时让容器内的服务能通过这个地址访问到 TaoToken。两者配合，才能完成「知识库 + 模型通道」的闭环。
如果你只是想把 Confluence 跑起来看个页面，那确实不需要这么麻烦。但只要涉及自动化、回调、插件调用外部 API，Base URL 就是绕不过去的第一道坎。下面从 Docker Compose 的环境变量开始，一步步把配置写清楚。
2. TaoToken 前置准备：Key、Base URL 与容器网络
在动 Confluence 的配置之前，先把 TaoToken 这边的三件套准备好：Base URL、API Key、Model ID。这三个东西后面会反复出现，缺一个请求就通不了。
Base URL 用https://taotoken.net/api，注意这里不带任何查询参数，就是干净的 API 根路径。API Key 需要你去控制台生成，路径是https://taotoken.net/console，进去之后找到 API Keys 页面，新建一个 Key，复制出来保存好。Model ID 取决于你要调哪个模型，比如常见的对话模型、代码模型，具体以文档里的模型列表为准，文档地址是https://taotoken.net/doc。
这里要强调一个容器场景下的关键问题：Confluence 跑在 Docker 容器里，容器内的localhost指的是容器自己，不是宿主机。所以如果你在 Confluence 的配置里写http://localhost:8090，它永远指向容器内部；如果你写http://127.0.0.1:xxxx去访问 TaoToken，同样会失败，因为 TaoToken 是外部服务，不在这个容器里。
正确的做法有两种。第一种是让容器直接走公网访问https://taotoken.net/api，前提是容器所在网络能出网。第二种是在 docker-compose 里配置extra_hosts，把域名映射到宿主机或网关 IP，适合内网有统一出口的场景。本文以第一种为主，因为最简单、最少踩坑。
还有一个细节：Confluence 的健康检查会去请求它自己配置的 Base URL。如果你把 Base URL 设成一个容器内访问不到的地址，右上角就会一直提示Can't check base URL。所以 Base URL 必须是一个「容器内能解析、外部也能访问」的地址。通常的做法是用一个真实域名，配合反向代理（比如 Traefik 或 Nginx），让域名在容器内外都能解析到正确的入口。
把这三件套记下来：
| 项目 | 值 | 用途 |
|---|---|---|
| Base URL | https://taotoken.net/api | 模型 API 入口 |
| API Key | 控制台生成 | 身份认证 |
| Model ID | 文档查询 | 指定模型 |
准备好之后，先别急着改 Confluence，先用一条 curl 命令在宿主机上验证 TaoToken 通道本身是通的。这一步能排除掉 Key 错误、网络不通等基础问题，避免后面把锅甩给 Confluence 配置。
curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的ModelID", "messages": [{"role": "user", "content": "ping"}] }'如果返回里有choices字段，说明通道没问题。如果返回 401，说明 Key 不对；如果连接超时，说明网络出口有问题。这一步过了，再进 Confluence 的配置。
3. 可复制配置：docker-compose 环境变量与 Base URL 片段
这一节是全文的核心，给出可以直接复制粘贴的配置。分两部分：docker-compose 的环境变量，以及 Confluence 的 Base URL 设置。
先看 docker-compose。下面这份配置基于 Confluence 官方镜像，用 MySQL 作为存储后端，同时把 TaoToken 相关的环境变量注入进去。注意extra_hosts这一段，它保证容器内能解析到你的域名。
version: '3' services: confluence: image: atlassian/confluence-server:7.19.6 container_name: confluence restart: unless-stopped ports: - "8090:8090" - "8091:8091" environment: - ATL_TOMCAT_SCHEME=https - ATL_TOMCAT_SECURE=true - ATL_TOMCAT_PROXYNAME=wiki.example.com - ATL_TOMCAT_PROXYPORT=443 - TAOTOKEN_BASE_URL=https://taotoken.net/api - TAOTOKEN_API_KEY=${TAOTOKEN_API_KEY} - TAOTOKEN_MODEL_ID=${TAOTOKEN_MODEL_ID} volumes: - ./data:/var/atlassian/application-data/confluence - ./mysql-connector-java-8.0.28.jar:/opt/atlassian/confluence/confluence/WEB-INF/lib/mysql-connector-java-8.0.28.jar extra_hosts: - "wiki.example.com:127.0.0.1" networks: - confluence-net networks: confluence-net: driver: bridge配套的.env文件，把敏感信息和可变项抽出来：
TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_MODEL_ID=你的ModelID DOMAIN=wiki.example.com这里有几个参数要解释清楚。ATL_TOMCAT_PROXYNAME和ATL_TOMCAT_PROXYPORT是告诉 Confluence 它跑在反向代理后面，外部访问用的是 443 端口、https 协议。如果不设这两个，Confluence 的健康检查会报Tomcat 配置不正确，提示 scheme 应为 https、proxyPort 应为 443。
extra_hosts里的wiki.example.com:127.0.0.1是为了让容器内解析域名时指向本机，配合反向代理使用。如果你的反向代理不在宿主机上，把127.0.0.1换成代理的实际 IP。
接下来是 Confluence 的 Base URL 设置。这个不在 docker-compose 里，而是在 Confluence 启动后的管理后台，或者直接改配置文件。配置文件路径是data/confluence.cfg.xml，找到hibernate.connection.url附近，或者搜索confluence.base.url。
<property name="confluence.base.url">https://wiki.example.com</property>如果你希望 Confluence 里的插件或脚本调用 TaoToken，可以在 Confluence 的「一般配置」里增加自定义变量，或者直接在插件的配置里写：
{ "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "你的ModelID", "timeout": 30000 }这个 JSON 片段可以放在 Confluence 的宏配置、或者你自建的插件配置里。注意baseUrl结尾不要带/v1，具体路径在请求时拼接。
改完配置后，重启容器：
docker-compose down docker-compose up -d等 Confluence 启动完成（通常需要 1-2 分钟），再进管理后台确认 Base URL 已经生效。如果右上角还有警告，先别慌，下一节会讲怎么验证和排查。
4. 验证请求：从容器内发起一次真实调用
配置写完不代表通了，必须验证。验证分两步：先确认 Confluence 自己的 Base URL 健康检查过了，再确认容器内能访问 TaoToken。
第一步，进容器内部，用 curl 请求 Confluence 自己的 Base URL：
docker exec -it confluence bash curl -sS -o /dev/null -w "%{http_code}" https://wiki.example.com如果返回200或302，说明 Base URL 配置正确，容器内能解析并访问到这个域名。如果返回000或超时，说明extra_hosts或反向代理有问题。
第二步，在同一个容器内，请求 TaoToken 的 API：
curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "'"$TAOTOKEN_MODEL_ID"'", "messages": [{"role": "user", "content": "Confluence 连通性测试"}] }'注意这里用了环境变量拼接，因为容器内已经注入了TAOTOKEN_API_KEY和TAOTOKEN_MODEL_ID。如果返回的 JSON 里有choices数组，并且message.content有内容，说明整条链路通了。
成功的结果大概长这样：
{ "id": "chatcmpl-xxxx", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "连通性测试成功" }, "finish_reason": "stop" } ] }看到choices就说明请求被正确处理了。如果返回401，检查 Key 是否过期或拼写错误；如果返回404，检查 Base URL 是否多了或少了/v1；如果返回model not found，检查 Model ID 是否和文档一致。
第三步，回到 Confluence 管理后台，看右上角的健康检查提示是否消失。如果还有Can't check base URL，说明 Confluence 内部请求 Base URL 时走了不同的网络路径，需要检查 Tomcat 的server.xml配置，确认proxyName、proxyPort、scheme三个值和实际访问方式一致。
验证通过后，你可以进一步在 Confluence 里建一个测试页面，用 REST API 把页面内容发到 TaoToken 做摘要，确认业务层面的调用也正常。这一步不是必须的，但能帮你提前发现权限、超时、字符编码等问题。
5. 常见报错排查：401、local proxy failed、reading choices
这一节把实际部署中最容易撞上的几个报错列出来，对照着查。
报错一：401 Unauthorized
{"error":{"message":"Invalid API key","type":"invalid_request_error"}}原因通常是 Key 不对。检查三件事：Key 是否复制完整（有没有漏掉前缀）、Key 是否在控制台被禁用、环境变量是否真的注入到容器里。用docker exec -it confluence env | grep TAOTOKEN确认变量存在。如果变量存在但值不对，检查.env文件有没有被 docker-compose 正确读取。
报错二：local proxy failed
curl: (7) Failed to connect to taotoken.net port 443: Connection refused或者容器内报local proxy failed。这通常是容器网络出口问题。先确认宿主机能访问https://taotoken.net/api，如果宿主机能通、容器不通，检查 docker 的网络模式。默认 bridge 网络下容器应该能出网，如果不行，检查宿主机的 DNS 配置，或者在 docker-compose 里显式指定 DNS：
dns: - 8.8.8.8 - 1.1.1.1报错三：reading choices 相关解析失败
KeyError: 'choices'或者日志里出现reading 'choices'。这说明请求发出去了，但返回的 JSON 结构里没有choices字段。常见原因是 Base URL 写错了，比如写成了https://taotoken.net/api/v1/chat/completions作为 Base URL，然后代码又拼了一次路径，导致请求打到了错误的 endpoint。正确的 Base URL 是https://taotoken.net/api，具体路径由客户端库拼接。
报错四：OAuth 或认证跳转
OAuth callback failed如果你在 Confluence 里配置了 SSO 或 OAuth 登录，Base URL 改动后回调地址会变。需要去对应的身份提供商后台，把回调地址更新为新的 Base URL。这个和 TaoToken 无关，但经常和 Base URL 改动一起出现，所以列在这里。
报错五：Tomcat 配置不正确
Tomcat server.xml 配置不正确：scheme 应为 'https' proxyName 应为 'wiki.example.com' proxyPort 应为 '443'这是 Confluence 健康检查的经典报错。解决办法是在 docker-compose 里加上ATL_TOMCAT_SCHEME、ATL_TOMCAT_SECURE、ATL_TOMCAT_PROXYNAME、ATL_TOMCAT_PROXYPORT四个环境变量，值分别对应https、true、你的域名、443。改完重启容器。
排查的时候有个通用思路：先分层，再定位。网络层用curl测连通性，认证层看 401/403，应用层看返回结构。不要一上来就改代码，先把每一层单独验证通过。
6. 长期使用建议与接入入口
配置跑通之后，还有几件事值得提前做，能省掉后面很多麻烦。
第一，把 Key 和 Model ID 放在.env里，不要硬编码进 docker-compose 或代码。.env文件加入.gitignore，避免误提交。团队协作时，每个人用自己的 Key，方便审计和限额。
第二，给 Confluence 的 Base URL 配一个稳定的域名，不要用 IP。IP 一变，所有回调、Webhook、健康检查全挂。域名配合反向代理，证书用 Let's Encrypt 自动续期，基本不用管。
第三，如果你打算在 Confluence 里做更多模型相关的自动化，比如页面自动摘要、评论情感分析、文档问答索引，建议把调用逻辑封装成一个内部服务，Confluence 只负责触发，不直接持有 Key。这样 Key 轮换、模型切换都不用动 Confluence。
第四，定期检查 TaoToken 控制台的用量和 Key 状态。控制台地址是https://taotoken.net/console，API Keys 页面可以看每个 Key 的调用情况。如果发现异常调用，及时禁用并重建。
如果你还在选型阶段，想先试试模型对话的效果，可以直接打开https://taotoken.net/api对应的对话入口体验一下，确认模型输出符合预期再接入。如果是要长期跑编码、Agent 类任务，建议直接上 Coding Plan，省得后面频繁调整配额。接入文档在https://taotoken.net/doc，里面有各语言的示例代码和参数说明。
回滚检查也别忘了。改 Base URL 之前，先备份data/confluence.cfg.xml和docker-compose.yml。改完之后如果出问题，把备份文件还原，docker-compose down && docker-compose up -d就能回到之前的状态。这个习惯在自建服务里特别重要，因为 Confluence 启动慢，出问题排查起来很费时间。
最后一步，把验证过的 curl 命令存成一个脚本，比如check-connectivity.sh，每次改完配置跑一遍。脚本内容就是前面那两条 curl，一条测 Confluence 自己的 Base URL，一条测 TaoToken。两条都返回预期结果，才算配置完成。
