sbnews/docs/superpowers/specs/2026-08-02-production-docker-compose-design.md

Sport Era 生产 Docker Compose 设计

1. 目标

在生产服务器 /www/wwwroot/sbnews 中固定使用 dev.1.0.0 分支，通过一份统一的生产 Compose 编排运行 Sport Era 的 API、定时任务、爬虫、AI 知识库 Worker、管理后台和 uni-app H5。

生产环境继续使用宿主机 MySQL、Redis 和宝塔 Nginx。Compose 不管理数据库数据，也不占用宿主机的 80、443 端口。

2. 域名与入口

宝塔 Nginx 负责域名、HTTPS 证书和公网入口，并反向代理到仅在宿主机回环地址监听的容器服务：

域名	服务	反向代理目标
api.sbnews.net	ThinkPHP API	http://127.0.0.1:8000
keislwo.sbnews.net	Admin SPA	http://127.0.0.1:5176
web.sbnews.net	uni-app H5 SPA	http://127.0.0.1:5177

容器不直接处理公网 TLS，也不直接暴露 80、443、9000 等内部服务端口。

3. Compose 服务

新增 docker/docker-compose.prod.yml，Compose 项目名为 sport-era-prod。

3.1 Server

• 使用项目 PHP 8.0 FPM 镜像及 OPcache。
• 挂载 /www/wwwroot/sbnews/server 到 /likeadmin_php/server。
• 挂载私有 PHP 生产环境文件为 /likeadmin_php/server/.env。
• 使用 host 网络访问宿主机 MySQL 和 Redis。
• PHP-FPM 仅监听 127.0.0.1:9000。
• 使用 restart: unless-stopped 和有限大小的 Docker 日志。

3.2 API Nginx

• 使用 host 网络，通过 127.0.0.1:9000 访问 PHP-FPM。
• 仅监听 127.0.0.1:8000。
• 根目录为 /likeadmin_php/server/public。
• 支持 ThinkPHP 路由重写、上传大小限制、静态资源缓存和代理来源信息。
• 挂载生产 Nginx 日志目录。

3.3 Scheduler

• 与 Server 使用同一 PHP 镜像、源码和私有环境文件。
• 使用 host 网络。
• 独立循环执行 php think crontab，间隔 60 秒。
• 不承载 HTTP 请求。

3.4 Crawler

• 复用 docker/crawler/Dockerfile 构建的镜像。
• 使用 host 网络连接宿主机 MySQL、Redis。
• 复用现有 crawler_tasks.yaml 生成容器 cron。
• 持久化 docker/crawler/logs 与 docker/crawler/data。

3.5 KB Worker

• 与 Crawler 复用同一镜像。
• 使用 host 网络连接 MySQL、Redis。
• 持续消费 Redis Stream ai:kb:sync:stream。
• 对文章、帖子、彩票和比赛内容生成知识库文档、切片及 Embedding。
• 保留现有批量大小、阻塞时间和重试参数。

3.6 Admin

• 使用 Node 20 多阶段构建。
• 构建阶段安装锁定依赖并生成 Vite 生产资源。
• VITE_APP_BASE_URL 固定传入 https://api.sbnews.net。
• 运行阶段只保留静态 Nginx 和构建产物。
• Nginx 仅监听 127.0.0.1:5176，并配置 SPA 路由回退。

3.7 uni-app H5

• 使用 Node 20 多阶段构建。
• 构建阶段执行 H5 生产构建。
• VITE_APP_BASE_URL 固定传入 https://api.sbnews.net。
• 修改用户端配置，使生产 API 地址来自构建环境变量，不继续固定指向测试域名。
• 运行阶段只保留静态 Nginx 和 H5 构建产物。
• Nginx 仅监听 127.0.0.1:5177，并配置 SPA 路由回退。

PC 前台不包含在本次生产 Compose 范围内。

4. 网络设计

所有需要访问宿主机 MySQL、Redis 或回环端口的服务采用 host 网络：

• MySQL：127.0.0.1:3300
• Redis：127.0.0.1:6377，数据库编号 2
• PHP-FPM：127.0.0.1:9000
• API Nginx：127.0.0.1:8000
• Admin Nginx：127.0.0.1:5176
• H5 Nginx：127.0.0.1:5177

host 网络避免修改宿主机数据库监听地址和账号授权范围。各 HTTP/FastCGI 端口必须显式绑定回环地址，防止绕过宝塔直接访问。

5. 配置与密钥

生产环境使用两份互不混用的私有配置：

5.1 PHP 配置

文件：docker/.env.server.production

• 使用 ThinkPHP INI 风格配置。
• 包含数据库、Redis 以及 Server 运行所需的其他私有参数。
• 只存在于生产服务器，权限设置为 600。
• 挂载到 Server 和 Scheduler 的项目 .env。

5.2 Crawler 配置

文件：docker/.env.crawler.production

• 使用 dotenv 格式。
• 包含 DQD_DB_*、DQD_REDIS_*、Embedding 及爬虫所需私有参数。
• 由 Crawler 与 KB Worker 共用。
• 只存在于生产服务器，权限设置为 600。

Git 只提交对应的 .example 文件，所有密码使用占位符。.gitignore 必须忽略真实生产配置。

server/config/cache.php 中现存的非空 Redis 默认密码需要清空；各环境必须通过私有 .env 显式提供密码。已经公开或进入源码历史的生产密码应在部署完成后轮换。

6. 持久化与日志

数据	宿主机位置
Server 源码、上传和运行目录	/www/wwwroot/sbnews/server
Crawler 日志	/www/wwwroot/sbnews/docker/crawler/logs
Crawler 锁与运行数据	/www/wwwroot/sbnews/docker/crawler/data
API Nginx 日志	/www/wwwroot/sbnews/docker/log/nginx/prod-logs
MySQL 数据	由宿主机/宝塔管理
Redis 数据	由宿主机/宝塔管理

所有 Compose 服务使用有限大小、有限文件数量的 Docker JSON 日志配置，防止日志无限增长。

7. 发布流程

生产目录固定跟踪 dev.1.0.0：

cd /www/wwwroot/sbnews
git switch dev.1.0.0
git pull --ff-only origin dev.1.0.0
sudo docker compose -f docker/docker-compose.prod.yml config -q
sudo docker compose -f docker/docker-compose.prod.yml up -d --build

Admin 和 H5 每次部署都从当前提交重新构建。Server 继续挂载当前生产目录源码，更新代码后由新容器或现有挂载立即读取；执行统一 up -d --build 保证运行镜像和配置同步。

Compose 不自动执行数据库迁移、SQL 导入或破坏性数据操作。

8. 健康检查与验收

Compose 为 API、Admin 和 H5 配置健康检查。部署后至少执行：

sudo docker compose -f docker/docker-compose.prod.yml ps
curl -f http://127.0.0.1:8000/api/index/config
curl -I http://127.0.0.1:5176/
curl -I http://127.0.0.1:5177/

再通过公网域名检查宝塔反向代理和 HTTPS：

curl -I https://api.sbnews.net/api/index/config
curl -I https://keislwo.sbnews.net/
curl -I https://web.sbnews.net/

同时检查：

• Server、Scheduler、Crawler、KB Worker 均持续运行。
• Scheduler 能产生正常定时任务日志。
• Crawler 的容器 cron 已正确生成。
• KB Worker 已连接 Redis Stream，且没有持续重试错误。
• Admin/H5 刷新子路由不会返回 404。
• Git 跟踪文件中不存在真实数据库、Redis 或 AI 密钥。

9. 回滚

回滚前必须确认生产工作区没有人工修改：

git status --short

切换到已知正常提交并重新构建：

git switch --detach <正常提交ID>
sudo docker compose -f docker/docker-compose.prod.yml up -d --build

恢复跟踪生产分支：

git switch dev.1.0.0

构建失败时不主动删除旧容器或旧镜像，避免构建失败直接中断当前线上服务。

10. 实施文件范围

新增文件：

• docker/docker-compose.prod.yml
• docker/Dockerfile.admin
• docker/Dockerfile.uniapp-h5
• docker/config/nginx/conf.d/sport-era.prod-api.conf
• docker/config/nginx/static/admin.conf
• docker/config/nginx/static/uniapp-h5.conf
• docker/config/php/conf.d/zz-opcache.prod.ini
• docker/config/php/php-fpm.prod.conf
• docker/.env.server.production.example
• docker/.env.crawler.production.example
• admin/.dockerignore
• uniapp/.dockerignore
• docs/生产环境Docker部署说明.md

修改文件：

• .gitignore
• uniapp/src/config/index.ts
• server/config/cache.php
• docs/业务进度管理.md

11. 实施验证边界

本地实施阶段执行静态 Compose 展开和配置检查，不自动执行完整 Admin/H5 构建，也不直接操作生产服务器。所有真实生产密钥由服务器管理员写入私有环境文件。

源码或运行配置修改完成后创建独立 Git 提交，不包含当前工作区中既有的社区页面或其他无关改动。由于会修改 server/config/cache.php，提交后按项目规范同步测试服；生产环境由服务器在 /www/wwwroot/sbnews 拉取并部署。