# sw2 Docker 部署

后端镜像发布至 `harbor.fuhua91.com/game/sw2-backend:<版本>`，前端镜像发布至 `harbor.fuhua91.com/game/sw2:<版本>`。发布服务器需先通过 `docker login harbor.fuhua91.com` 配置两个镜像仓库的 push/pull 权限；也可将本应用的 Docker 登录配置放在部署根目录的 `harbor-docker/` 下，脚本优先使用该配置。脚本在替换容器前完成两个镜像的推送、拉取和摘要校验，并使用 Harbor 返回的摘要启动容器。前端独立发布入口位于前端仓库 `deploy/`，也支持直接指定 Harbor 版本拉取部署。

沿用 226 服务器 `/www/wwwroot/live.fuhua91.com` 的 Docker 网络、持久化目录和宝塔反向代理结构。使用独立的 `sw2-backend`、`sw2-frontend`、`sw2-net`，兼容服务器现有 Docker 18.06，不依赖 Compose。

## 目录与端口

部署根目录为 `/www/wwwroot/sw2.fuhua91.com`：

- `config/config.yaml`：后端运行配置，挂载到 `/data/conf`，UID 1000 可写。
- `runtime.env`：SDK 兼容参数，通过 Docker `--env-file` 加载，权限 600。
- `log/`、`uploads/`：日志与文件持久化目录。
- `releases/<commit>/`：已校验的发布包；`current-release` 记录当前版本。
- 后端仅绑定 `127.0.0.1:9602`，前端仅绑定 `127.0.0.1:9601`。
- 宝塔 `sw2.fuhua91.com` 代理至 9601，前端容器将 `/api/` 转发至后端并去除前缀，支持 WebSocket、SSE 和文件上传。

测试数据库为 `sw9`，由 `sw8` 副本完成自动迁移验证。程序和部署入口会自动识别旧商务库并完成整套升级；已有 `disable_auto_migrate` 配置不会跳过商务升级。平台别名为 `lx/hw/yq/oa`，其中三个 SDK 别名连接 `game_lx/game_hw/game_yq` 测试库，Redis 沿用当前关闭状态。生产配置使用 `admin.app.env: production`，关闭开发 Swagger。七条常规任务启用（四条商务/区服日汇总、预警检测、两条有效端刷新），两个历史回填停用。**使用同一 sw9 时只运行一个调度实例，切换到服务器前停止本机的后端服务。**

## 全自动数据库升级

将主数据库配置为准备接管的旧商务库，然后正常部署或启动程序即可。程序不创建空库替代旧数据，不需要手动运行 SQL、建立索引、回填角色映射或执行旧表清理。部署脚本中的 `-migrate` 与直接启动后端使用同一条自动流程。

执行顺序：识别旧库并取得迁移锁 → 备份受影响的数据 → 转换旧框架 → 执行全部增量迁移和索引 → 校验结构、数据记录和商务角色 → 备份待清理表 → 删除明确名单中的旧表 → 再次校验 → 开放业务接口及调度任务。首次接管前，旧程序应处于正常发布停写状态；检测到迁移期间账号发生变化时会停止清理。

阶段进度、失败原因、备份摘要和完成时间记录在 `sys_business_upgrade_state`，迁移版本仍记录在 `sys_schema_migrations`。同库的多个新实例会等待同一把锁。建索引不设置总超时，日志每 10 秒报告当前阶段；在全部步骤完成前，业务服务不会就绪。

备份自动写入配置文件旁的 `migration-backups/`，在当前 Docker 部署中对应 `/www/wwwroot/sw2.fuhua91.com/config/migration-backups/`。目录权限为 700、文件为 600，不对外提供下载。备份包含受转换影响的系统数据、待删除旧表及其结构；只新增索引的原始业务大表保留在原库，其旧结构以注释写入备份。渠道主键扩容涉及的 `tab_promote` 同时备份数据。备份完整写入并校验 SHA-256 后才允许清理，历史备份不会随容器替换删除。

旧角色映射会一次性回填到 `sys_authorities.business_level`，之后创建商务账号只按稳定的等级标识查角色。角色可改名，复制角色不复制该标识，内置商务角色禁止删除。旧用户 ID、角色 ID、权限关联及主键自增高水位保持迁移约定，不因移除映射表再次编号。

当前自动清理名单为 79 张：19 张旧框架归档、26 张迁移前备份、23 张旧 SnailJob 表、4 张旧代码生成/演示表、2 张旧预警去重备份，以及 5 张已归档的 `sw_kra_*` 迁移辅助表。正常业务表和两个必要的迁移状态表保留；原 156 表的已迁移库升级后为 78 表。初次迁移时沿用旧任务启停状态，已运行的新商务库则保持现有任务设置。

发生中断后，重新启动或重新部署会根据持久化状态继续：尚未提交数据的旧框架转换可重新创建空目标结构，已提交的数据不会再次映射 ID，已有索引会校验后跳过，部分完成的清理使用原来的完整备份继续。验证失败、备份损坏或发现外键/视图等依赖时保留原表并报告原因。数据库已改变时，部署脚本只在旧版本通过结构检查后才允许回退到旧镜像。

[框架转换 SQL](../migrations/legacy-framework.sql) 与 [清理 SQL](../migrations/cleanup-legacy.sql) 是程序内嵌的执行内容，供审阅和应急排查，正常部署无需手工调用。可选的只读诊断命令：

```bash
/app/kratos-admin -conf /data/conf/config.yaml -check-schema
```

## 构建与发布

Windows 本机安装 Go、Node、pnpm、tar，先提交源代码，再执行：

```powershell
.\deploy\docker\build-package.ps1
```

输出位于 `.cache/deploy/sw2-<commit>.tar.gz` 及对应 SHA-256 文件。后端交叉编译为 Linux amd64，前端执行生产构建；包内只含二进制、前端产物、Dockerfile 和部署配置，真实运行配置及环境变量不进入镜像或 Git。

通过 SSH 将包上传到 226，校验 SHA-256 后解压到 `releases/<commit>/`。首次部署准备上述私有配置文件，保持 `admin.router_prefix` 为空，主库填写待接管的旧商务数据库。SDK 环境变量名称为 `SW_SDK_AUTH_CODE`、`SW_SDK_MIGRATE_AUTH_CODE`、`SW_SDK_TABLE_PREFIX`，值从已有私有运行配置取得。

```bash
bash /www/wwwroot/sw2.fuhua91.com/releases/<commit>/deploy.sh <commit> --build-only
# 构建和容器配置检查通过后，停止连接同一 sw9 的本机后端。
bash /www/wwwroot/sw2.fuhua91.com/releases/<commit>/deploy.sh <commit>
```

脚本先构建和检查镜像，再停止当前受管容器，保留一份停止的 `-previous` 容器。迁移或健康检查失败时，先检查旧版本是否兼容当前数据库，再决定是否恢复前一组容器。配置、备份和上传文件不随镜像替换；完整数据库升级在独立迁移容器中自动执行。

迁移不设置总等待时限，日志记录每一步的名称、结果和耗时；耗时索引完成前不会启动业务服务。业务容器退出或重启时进入兼容性检查后再处理回退。切换数据库前需备份运行配置；镜像回退不会自动还原数据库连接配置或撤销已执行的数据库迁移，回退版本需兼容当前结构和迁移版本。

首次接入域名时，备份宝塔原站点配置，再安装 `bt-nginx-sw2.fuhua91.com.conf` 至 `/www/server/panel/vhost/nginx/`，执行 `/www/server/nginx/sbin/nginx -t` 通过后重载。模板保留证书验证目录，当前监听 HTTP；后续由宝塔为 sw2 单独配置匹配域名的证书。

验证首页、静态资源、`/api/health`、登录状态、商务接口和任务启停/执行日志。回退版本可执行 `bash /www/wwwroot/sw2.fuhua91.com/deploy.sh <旧commit>`；数据库迁移及业务数据不由镜像回退脚本撤销。