单游戏独立部署与升级

2026-10-26目录更新：源码工程为runtime/game；从仓库根执行pnpm build:docs生成运行下载包及文档站，发行包位于.artifacts/releases/game，文档站位于.artifacts/sites/game。原deploy模板、运行配置及线上/本地持久数据保持原位置；按新代码目录构建，不移动数据库、上传或用户资产。这里描述操作，不自动执行。

每个游戏独立后端配一个公共服务实例，不按五游戏共享。可复用同一只读二进制版本；配置、环境变量、端口、数据库、运行目录和服务账号分别配置。

生产目录示例

/opt/huohua-game-service/releases/0.4.0/huohua-game-service

/opt/huohua-game-service/current -> releases/0.4.0

/etc/huohua-game-service/game-ab/config.json

/etc/huohua-game-service/game-ab/service.env

/var/lib/huohua-game-service/game-ab/game.db

game-ab是部署实例名。配置中的databasePath明确指向上述独立绝对路径，同机其他游戏采用不同端口。凭据环境文件仅允许维护账号访问。用户、礼包、存档及中转同步已实现；完整配置和联调流程见《完整接入与联调》。

deploy/huohua-game-service@.service为systemd实例模板。按每游戏创建对应系统用户和目录，示例hh-game-ab；使用较短的部署实例名，避免超过系统用户名限制。服务实例只可写自身数据目录。此工程不自动安装服务、不更改系统账号。

数据库与备份恢复

使用纯Go SQLite驱动、WAL和FULL同步，单个连接串行本地写入，数据库放本机持久磁盘，不放对象存储、共享网络文件系统或临时目录。其他游戏和玩法代码不得直接写公共数据库。

启动按user_version迁移，目前版本3（从版本1/2原位迁移）；拒绝高于程序支持版本的数据库。首次建立固定gameID，错用别的游戏数据库会拒绝启动。上线前按实际并发压测，不能据SQLite选型承诺未经验证的吞吐。

生成含已提交WAL数据的一致性快照（目标必须为不存在的绝对路径；命令仍需本游戏配置和凭据环境，不调用微信）：

./huohua-game-service -config /etc/huohua-game-service/game-ab/config.json \

  -backup /var/backups/huohua/game-ab-20261021.db

命令使用VACUUM INTO，不直接复制正在写入的数据库主文件。备份含账号、OpenID及会话摘要，按敏感业务数据限制访问与保留周期。

恢复时停止该游戏公共服务，确认进程退出和连接关闭，将当前数据库及其WAL/SHM一并保存为故障副本；在干净数据目录恢复快照，保留原配置gameID，以原游戏配置启动并核对账号与会话，再恢复流量。不要把旧WAL/SHM混到恢复文件旁边。先在隔离环境演练，程序不会自动覆盖或删除数据库。

升级及回滚

发布包包含二进制、版本、校验和、文档和兼容说明，不包含源码或密钥。每游戏独立验证、重启和回滚；游戏开发任务无权修改公共发布目录。

0.4.0兼容0.3.1的单game配置，不配置features时新模块关闭；启用新模块参考config.features.example.json。升级前先使用旧版本备份数据库及配置，再启动新版本并核对readyz和capabilities。单实例重启会短暂不可用，调用方应处理连接失败。

未来迁移采用兼容性扩展，二进制回滚不等于数据库回滚；较旧程序无法读取新schema时应停止，不强制降低user_version。Windows和Linux数据库文件备份均应验证完整性及游戏绑定。

中转独立部署

使用huohua-relay二进制、relay.example.json和deploy/huohua-relay.service。数据库与游戏数据库分开，内部绑定为__huohua_relay__，不能与任一游戏共用文件。TLS回调反向代理参考relay-nginx.example.conf；只开放所需公网POST入口，游戏事件路径保持内网。

两类服务都支持-version和-backup；中转仅传递事件及回执，不持有微信密钥。升级前备份两类数据库，版本3不能由只支持版本2的0.3.1打开；不可手动降user_version。