使用 Docker 搭建 Confluence：把 Base URL 改到 TaoToken 的完整配置

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 跑起来看个页面那确实不需要这么麻烦。但只要涉及自动化、回调、插件调用外部 APIBase 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 设成一个容器内访问不到的地址右上角就会一直提示Cant check base URL。所以 Base URL 必须是一个「容器内能解析、外部也能访问」的地址。通常的做法是用一个真实域名配合反向代理比如 Traefik 或 Nginx让域名在容器内外都能解析到正确的入口。把这三件套记下来项目值用途Base URLhttps://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_SCHEMEhttps - ATL_TOMCAT_SECUREtrue - ATL_TOMCAT_PROXYNAMEwiki.example.com - ATL_TOMCAT_PROXYPORT443 - TAOTOKEN_BASE_URLhttps://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_KEYsk-你的Key TAOTOKEN_MODEL_ID你的ModelID DOMAINwiki.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 nameconfluence.base.urlhttps://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 URLdocker exec -it confluence bash curl -sS -o /dev/null -w %{http_code} https://wiki.example.com如果返回200或302说明 Base URL 配置正确容器内能解析并访问到这个域名。如果返回000或超时说明extra_hosts或反向代理有问题。第二步在同一个容器内请求 TaoToken 的 APIcurl -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 管理后台看右上角的健康检查提示是否消失。如果还有Cant 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 failedcurl: (7) Failed to connect to taotoken.net port 443: Connection refused或者容器内报local proxy failed。这通常是容器网络出口问题。先确认宿主机能访问https://taotoken.net/api如果宿主机能通、容器不通检查 docker 的网络模式。默认 bridge 网络下容器应该能出网如果不行检查宿主机的 DNS 配置或者在 docker-compose 里显式指定 DNSdns: - 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、健康检查全挂。域名配合反向代理证书用 Lets Encrypt 自动续期基本不用管。第三如果你打算在 Confluence 里做更多模型相关的自动化比如页面自动摘要、评论情感分析、文档问答索引建议把调用逻辑封装成一个内部服务Confluence 只负责触发不直接持有 Key。这样 Key 轮换、模型切换都不用动 Confluence。第四定期检查 TaoToken 控制台的用量和 Key 状态。控制台地址是https://taotoken.net/consoleAPI 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。两条都返回预期结果才算配置完成。