企业官网建设流程全解析

1. 为什么自托管 Flarum 还要折腾 Traefik 和统一 Key

Flarum 是一个轻量级开源论坛程序，界面干净、插件机制成熟，适合做小团队内部社区或产品用户交流区。它的部署门槛不算高，但真正落地时会遇到两个绕不开的问题：一是反向代理和 HTTPS 证书管理，二是论坛里接入 AI 能力时，多个插件各写各的 API Key，维护起来很乱。

我这次的目标很明确：用 Docker Compose 把 Flarum、MySQL、Nginx 编排起来，Traefik 负责自动签发 Let's Encrypt 证书并做反向代理，然后把论坛内 AI 插件请求的 Base URL 统一指向 TaoToken，用一个 Key 管理所有模型调用。这样做的直接好处是，论坛管理员不用在多个插件后台反复填 Key，也不用担心某个插件把 Key 写死在代码里。

适合谁看？如果你已经有一台能跑 Docker 的服务器，域名解析也做好了，想搭一个带 AI 能力的轻论坛，这篇可以跟着做。如果你只是单纯想学 Traefik 的 label 写法，或者想了解 Flarum 的容器化目录拆分，也能拿到可复制的配置片段。

整个链路的核心检索词是「Docker Traefik Flarum 容器化部署」，我会把 Compose 文件、Traefik 动态配置、Nginx 配置、以及 AI 插件 Base URL 的改法都写清楚。实测下来，从零到论坛能访问，大概 20 分钟；加上 AI 插件调通，再多 10 分钟。

先说一下整体架构：Traefik 监听 80 和 443，通过 Docker provider 自动发现容器 label，把forum.example.com的流量转发到 Nginx 容器的 80 端口；Nginx 再把 PHP 请求 fastcgi 给 PHP-FPM 容器；PHP-FPM 容器里跑 Flarum 代码，连 MySQL 容器。AI 插件在 Flarum 后端发起 HTTP 请求，Base URL 指向 TaoToken 的 API 地址。

这个架构里，Traefik 不直接碰 PHP，只做七层路由和证书；Nginx 只做静态文件和 fastcgi 转发；PHP-FPM 只跑业务逻辑。职责清晰，排障也容易定位。

2. TaoToken 前置准备：Base URL、Key 与模型 ID 三件套

在改 Flarum 插件之前，先把 TaoToken 这边的三件套准备好。所谓三件套，就是 Base URL、API Key、Model ID。任何 OpenAI 兼容的客户端接入，都离不开这三个东西。

Base URL 用https://taotoken.net/api，注意这里不加任何查询参数。API Key 需要到控制台创建，路径是https://taotoken.net/console/api-keys。创建时给 Key 起个名字，比如flarum-forum，方便以后按项目区分。创建完复制出来，只显示一次，丢了就重新建。

Model ID 取决于你想让论坛的 AI 插件干什么。如果是做帖子摘要、自动回复、内容审核，常用的是gpt-4o-mini这类性价比高的模型；如果要做复杂推理，可以选gpt-4o或claude-3-5-sonnet。具体可用列表在模型对话页面能看到，地址是https://taotoken.net/models。你可以在那里先发一条测试消息，确认 Key 和模型都能通，再去改论坛配置。

这里要提醒一句：不要把 Key 直接写进 Flarum 的config.php或者插件的 PHP 文件里。正确做法是写进.env文件，然后通过 Docker Compose 的env_file注入到 PHP 容器，插件里用getenv()读取。这样 Key 不会进 Git 仓库，换 Key 也不用改代码。

如果你用的是 Claude Code 这类编码工具做论坛插件开发，可以在本地先配好settings.json，把 Base URL 和 Key 写进去，这样本地调试插件时也能走 TaoToken。但生产环境的 Flarum 容器里，还是走环境变量最稳。

另外，TaoToken 的 Coding Plan 适合长期做插件开发和 Agent 调用的场景，如果你打算给论坛加多个 AI 功能，比如自动打标签、智能推荐、内容风控，可以考虑用 Coding Plan 来统一管理调用额度。入口在https://taotoken.net/coding-plan。

准备好这三样之后，先别急着改 Flarum。用 curl 在服务器上测一下，确认网络和鉴权都没问题。命令如下：

curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

如果返回 JSON 里有choices字段，说明 Key 和网络都正常。如果返回 401，检查 Key 是否复制完整；如果返回 404，检查 Base URL 是不是写成了https://taotoken.net/api/v1之外的其他路径。这一步过了，再往下走。

3. 可复制配置：Compose、Traefik 动态配置与 Flarum 环境变量

这一节是全文的核心，所有配置都可以直接复制。先建目录结构：

mkdir -p /opt/flarum/{conf,logs,wwwroot,data} cd /opt/flarum

然后写docker-compose.yml。这里用 Traefik 的 Docker provider，通过 label 自动发现服务。MySQL 不暴露端口到宿主机，只在内网通信。PHP-FPM 和 Nginx 通过env_file读取.env。

version: "3.8" services: traefik: image: traefik:v2.11 container_name: traefik restart: always ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - ./conf/traefik.yml:/etc/traefik/traefik.yml:ro - ./conf/dynamic.yml:/etc/traefik/dynamic.yml:ro - ./data/acme.json:/acme.json networks: - traefik mysql: image: mysql:8.0 container_name: flarum-mysql restart: always environment: MYSQL_DATABASE: flarum MYSQL_USER: flarum MYSQL_PASSWORD: ${FLARUM_DB_PASS} MYSQL_ROOT_PASSWORD: ${FLARUM_DB_ROOT_PASS} volumes: - ./data/mysql:/var/lib/mysql networks: - traefik php: image: php-fpm-flarum:8.2 container_name: flarum-php restart: always env_file: .env volumes: - ./wwwroot:/wwwroot - ./logs:/var/log networks: - traefik nginx: image: nginx:1.25-alpine container_name: flarum-nginx restart: always volumes: - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro - ./wwwroot:/wwwroot - ./logs:/var/log/nginx labels: - "traefik.enable=true" - "traefik.http.routers.flarum.rule=Host(`forum.example.com`)" - "traefik.http.routers.flarum.entrypoints=websecure" - "traefik.http.routers.flarum.tls.certresolver=letsencrypt" - "traefik.http.services.flarum.loadbalancer.server.port=80" networks: - traefik networks: traefik: external: true

注意traefik网络需要提前创建：

docker network create traefik

接着写 Traefik 静态配置conf/traefik.yml：

entryPoints: web: address: ":80" http: redirections: entryPoint: to: websecure scheme: https websecure: address: ":443" providers: docker: exposedByDefault: false file: filename: /etc/traefik/dynamic.yml certificatesResolvers: letsencrypt: acme: email: admin@example.com storage: /acme.json httpChallenge: entryPoint: web

动态配置conf/dynamic.yml可以留空或者放中间件，比如安全头：

http: middlewares: security-headers: headers: stsSeconds: 31536000 contentTypeNosniff: true browserXssFilter: true

然后在 nginx 的 label 里加上traefik.http.routers.flarum.middlewares=security-headers@file即可。

.env文件内容如下，注意FLARUM_APP_URL要写完整 HTTPS 地址：

FLARUM_DB_HOST=flarum-mysql FLARUM_DB_NAME=flarum FLARUM_DB_USER=flarum FLARUM_DB_PASS=change_me_db_pass FLARUM_DB_ROOT_PASS=change_me_root_pass FLARUM_APP_URL=https://forum.example.com FLARUM_APP_DEBUG=false TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=gpt-4o-mini

Nginx 配置conf/nginx.conf关键部分：

server { listen 80; server_name forum.example.com; root /wwwroot/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass php:9000; fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }

PHP 镜像需要自己构建，Dockerfile 基于php:8.2-fpm-alpine，安装pdo_mysql、mbstring、gd、zip等扩展。构建命令：

docker build -t php-fpm-flarum:8.2 -f Dockerfile .

Flarum 代码用 Composer 下载到wwwroot：

composer create-project flarum/flarum ./wwwroot --stability=stable

然后修改wwwroot/config.php，让它从环境变量读取数据库和 URL：

<?php return [ 'debug' => getenv('FLARUM_APP_DEBUG') === 'true', 'database' => [ 'driver' => 'mysql', 'host' => getenv('FLARUM_DB_HOST'), 'database' => getenv('FLARUM_DB_NAME'), 'username' => getenv('FLARUM_DB_USER'), 'password' => getenv('FLARUM_DB_PASS'), 'charset' => 'utf8mb4', 'collation' => 'utf8mb4_unicode_ci', 'prefix' => 'flarum_', 'port' => '3306', ], 'url' => getenv('FLARUM_APP_URL'), 'paths' => [ 'api' => 'api', 'admin' => 'admin', ], ];

启动：

docker compose up -d

到这里，论坛本身应该能通过https://forum.example.com访问了。接下来处理 AI 插件的 Base URL。

4. 验证请求：curl 测通 TaoToken 与容器日志排查路由

论坛起来之后，先别急着装 AI 插件。先用 curl 在 PHP 容器内部测一下 TaoToken 的连通性，因为容器内的 DNS 和宿主机可能不一样。

进入 PHP 容器：

docker exec -it flarum-php sh

然后在容器里执行：

curl -s -X POST $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": "hello"}], "max_tokens": 20 }'

如果返回choices，说明容器内网络和鉴权都通。如果卡住或超时，检查服务器出网是否正常，以及TAOTOKEN_BASE_URL是否写成了https://taotoken.net/api而不是带/v1的路径。TaoToken 的 OpenAI 兼容接口，Base URL 就是https://taotoken.net/api，客户端会自动拼/v1/chat/completions。

接着验证 Traefik 路由。用 curl 从外部访问：

curl -I https://forum.example.com

应该返回 200 或 302，并且证书是有效的。如果返回 404，检查 Traefik 的 label 里traefik.http.routers.flarum.rule的域名是否和实际访问域名一致。如果返回 502，检查 Nginx 容器是否在traefik网络里，以及loadbalancer.server.port是否写成了 80。

查看 Traefik 日志：

docker logs traefik --tail 50

正常会看到Adding route for forum.example.com和证书签发的日志。如果证书签发失败，检查 80 端口是否被占用，以及域名解析是否指向这台服务器。

查看 Nginx 日志：

docker logs flarum-nginx --tail 50

如果看到connect() failed (111: Connection refused) while connecting to upstream，说明 Nginx 找不到 PHP 容器，检查fastcgi_pass php:9000里的服务名是否和 Compose 里的服务名一致。

查看 PHP 日志：

docker logs flarum-php --tail 50

如果 Flarum 报数据库连接错误，检查.env里的FLARUM_DB_HOST是否写成了flarum-mysql，以及 MySQL 容器是否健康。

最后验证 AI 插件。在 Flarum 后台安装一个支持自定义 Base URL 的 AI 插件，比如flarum/ai或类似的扩展。在插件设置里，把 API Base URL 填成https://taotoken.net/api，API Key 填成.env里的TAOTOKEN_API_KEY，Model 填gpt-4o-mini。保存后，在论坛发一个测试帖，触发 AI 摘要或回复功能。

如果插件报local proxy failed，说明插件可能走了本地代理或者 Base URL 写错了。如果报reading choices错误，说明返回的 JSON 结构不对，检查 Model ID 是否在 TaoToken 支持列表里。如果报 401，检查 Key 是否有多余空格。

实测下来，最容易踩的坑是 Base URL 多写了/v1。TaoToken 的 Base URL 是https://taotoken.net/api，客户端自己会拼/v1。如果你写成https://taotoken.net/api/v1，就会变成/api/v1/v1/chat/completions，直接 404。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

这一节把可能遇到的报错集中列一下，方便对照。

401 Unauthorized：最常见。原因通常是 Key 复制不完整、Key 被撤销、或者请求头里Authorization格式不对。正确格式是Bearer sk-xxx，注意 Bearer 后面有一个空格。如果你在 Flarum 插件里填 Key，有些插件会自己加Bearer，这时候你只填sk-xxx就行。排查方法：用 curl 在容器里直接测，排除插件干扰。

local proxy failed：这个报错通常出现在插件尝试走本地代理，但代理没启动或者端口不对。如果你没有配代理，检查插件的 HTTP 客户端设置里是否误开了 proxy。另外，有些插件会读取HTTP_PROXY环境变量，如果容器里设了这个变量但代理不可用，也会报这个错。解决办法：在.env里确保没有HTTP_PROXY和HTTPS_PROXY，或者在 Compose 里显式设为空。

reading choices 错误：一般是返回的 JSON 里没有choices字段。可能原因有三个：Model ID 写错、Base URL 写错、或者请求体格式不对。先用 curl 测通，确认返回结构里有choices。如果 curl 通但插件报错，检查插件是否在请求里加了额外参数导致 TaoToken 拒绝。比如有些插件会传functions或tools，如果模型不支持就会报错。

OAuth 相关报错：如果你用的是 Claude Code 或者某些需要 OAuth 的工具，可能会遇到 token 过期。TaoToken 的 API Key 是长期有效的，不需要 OAuth 刷新。如果你在插件里看到 OAuth 报错，说明插件可能默认走了 Anthropic 官方接口，需要把 Base URL 改成 TaoToken 的地址，并且把认证方式从 OAuth 改成 API Key。

容器间 DNS 解析失败：如果 PHP 容器里ping flarum-mysql不通，检查两个容器是否在同一个 Docker 网络里。Compose 里定义的traefik网络是 external 的，所有服务都要显式加入。如果 MySQL 容器没加入，PHP 就找不到它。

Traefik 证书签发失败：检查 80 端口是否被其他程序占用，以及域名是否解析到这台服务器。Let's Encrypt 的 HTTP challenge 需要 80 端口可访问。如果服务器前面还有一层 CDN 或防火墙，需要放行 80 和 443。

Flarum 安装后静态资源 404：检查 Nginx 配置里的root是否指向/wwwroot/public，以及try_files是否正确。Flarum 的入口文件在public/index.php，静态资源在public/assets。

AI 插件保存设置后不生效：Flarum 有缓存，改完配置后需要清缓存：

docker exec -it flarum-php php flarum cache:clear

如果还不行，检查插件的设置是否写进了数据库，而不是只存在内存里。

6. 统一 Key 接入后的维护建议与 CTA

论坛跑起来之后，维护上还有几个点可以优化。第一，把.env文件权限设为 600，避免其他用户读到 Key。第二，定期在 TaoToken 控制台检查 Key 的使用量，如果发现异常调用，及时撤销重建。第三，如果论坛有多个 AI 插件，尽量让它们共用同一个 Base URL 和 Key，通过 Model ID 区分功能，这样管理起来最简单。

如果你后续要给论坛加更多 AI 能力，比如自动审核、智能推荐、多语言翻译，可以考虑用 TaoToken 的 Coding Plan 来统一管理调用。入口在https://taotoken.net/coding-plan，适合长期编码和 Agent 场景。

排障和接入过程中，最常用的两个页面是 API Keys 管理页https://taotoken.net/console/api-keys和接入文档https://taotoken.net/doc。前者用来创建和撤销 Key，后者有各语言的接入示例。如果你不确定某个模型是否可用，去模型对话页面https://taotoken.net/models发一条测试消息，比看文档更直接。

最后说一个实际经验：Flarum 的插件生态里，AI 类插件质量参差不齐，有些插件会把 Base URL 写死在代码里。遇到这种插件，要么改插件源码，要么换一个支持自定义 Base URL 的。改源码时，把https://api.openai.com替换成https://taotoken.net/api即可，注意不要多写/v1。改完记得清缓存，并且用docker logs flarum-php观察请求日志，确认请求真的发到了 TaoToken。

整个链路跑通后，你得到的是一个带自动 HTTPS、统一 AI Key 管理的自托管论坛。后续换模型、换 Key、加插件，都只需要改.env和插件设置，不用动容器编排。这套配置我用了几个月，稳定性没问题，唯一要注意的是 Let's Encrypt 证书续期，Traefik 会自动处理，但记得acme.json权限要设为 600，否则 Traefik 启动会报错。