docs: add production docker deployment guide

2026-08-02 11:25:49 +08:00
parent 58128b8cb3
commit f9aba0b689
2 changed files with 1153 additions and 0 deletions
@@ -0,0 +1,145 @@
+# 生产环境 Docker 部署说明
+
+## 环境边界
+
+- 生产目录：`/www/wwwroot/sbnews`
+- Git 分支：`dev.1.0.0`
+- API：`api.sbnews.net`
+- Admin：`keislwo.sbnews.net`
+- H5：`web.sbnews.net`
+- MySQL、Redis、域名和 HTTPS 由宿主机/宝塔管理。
+- Docker Compose 负责 Server、Scheduler、Crawler、KB Worker、Admin 和 H5。
+
+生产 MySQL 和 Redis 不放入 Compose：
+
+- MySQL：宿主机 `127.0.0.1:3300`，数据库 `sbnews`。
+- Redis：宿主机 `127.0.0.1:6377`，使用 DB 2。
+- 实际密码只写入 `docker/.env.server.production` 和 `docker/.env.crawler.production`，不提交 Git。
+
+## 首次部署
+
+在源码已经准备到 `/www/wwwroot/sbnews` 后执行：
+
+```bash
+cd /www/wwwroot/sbnews
+git switch dev.1.0.0
+git pull --ff-only origin dev.1.0.0
+
+cp docker/.env.server.production.example docker/.env.server.production
+cp docker/.env.crawler.production.example docker/.env.crawler.production
+chmod 600 docker/.env.server.production docker/.env.crawler.production
+
+# 使用编辑器填写真实密码及 API Key，不要把真实配置提交到 Git。
+sudo docker compose -f docker/docker-compose.prod.yml config -q
+sudo docker compose -f docker/docker-compose.prod.yml up -d --build
+```
+
+## 日常更新
+
+```bash
+cd /www/wwwroot/sbnews
+git status --short
+
+# 为当前线上版本保留可回滚标签
+git tag -f production-stable "$(git rev-parse HEAD)"
+
+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
+```
+
+构建失败时不要删除现有容器和镜像；确认构建成功后再重新创建服务。Compose 不自动执行数据库迁移、SQL 导入或其他破坏性数据操作。
+
+## 宝塔反向代理
+
+宝塔负责三个站点的域名、证书和 HTTPS。各站点反向代理到本机回环地址，Docker 不占用宿主机 80/443。
+
+### api.sbnews.net
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+}
+```
+
+### keislwo.sbnews.net
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5176;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+### web.sbnews.net
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5177;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+在宝塔保存反代配置后执行 Nginx 配置检查并重载服务。不要把 `127.0.0.1:9000`、MySQL 或 Redis 直接配置为公网站点入口。
+
+## 验收
+
+```bash
+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/
+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`、`api-nginx`、`admin`、`uniapp-h5` 均处于运行状态。
+- Scheduler 能产生正常定时任务日志。
+- Crawler 容器已生成 `/etc/cron.d/sport-era-crawler`。
+- KB Worker 能连接 Redis Stream `ai:kb:sync:stream`，没有持续重试错误。
+- Admin 和 H5 刷新子路由不会返回 404。
+- Git 跟踪文件和部署文档中没有真实数据库、Redis 或 AI 密钥。
+
+查看日志：
+
+```bash
+sudo docker compose -f docker/docker-compose.prod.yml logs --tail 100 server api-nginx scheduler crawler kb-worker admin uniapp-h5
+```
+
+## 回滚
+
+确认当前工作区没有人工修改后，切回更新前保留的稳定标签：
+
+```bash
+cd /www/wwwroot/sbnews
+git status --short
+git switch --detach production-stable
+sudo docker compose -f docker/docker-compose.prod.yml up -d --build
+```
+
+回滚完成后，如需继续跟踪生产分支：
+
+```bash
+git switch dev.1.0.0
+```
+
+如果生产密码已经在聊天、日志或其他非私密位置暴露，部署完成后应立即轮换密码，并同步更新两份私有环境文件。