# 公共服务双模式接入（0.5.0）

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

当前产品接入先遵守[应用类型与登录规则](应用类型与登录规则.md)：TapTap H5/小游戏为taptap（tap.login→code2Session）、微信小游戏为wechat、App为password，不按底层接口可选范围任意混搭。

当前平台与登录方式已分开，仅支持账号密码、微信、TapTap三种；新接入以[三种登录方式](平台与三种登录方式.md)为认证及身份结构的权威说明。

当前0.7.0按全新部署使用，账号返回platform，支持微信和TapTap小游戏登录；具体配置与身份隔离见[TapTap与平台账号接入](TapTap与平台账号接入.md)。不新增旧账号回填、旧库升级或旧SDK适配。

同一套登录、用户 ID、礼包、存档、体力、开屏/激励广告、字段排行榜和火花事件协议，提供两种部署方式。游戏前端始终调用自己的业务后端，公共服务凭据只在后端使用。

## AI 首先选择环境声明的模式

读取 HUOHUA_SERVICE_MODE（local 或 central）、HUOHUA_SERVICE_URL、HUOHUA_GAME_ID、HUOHUA_GAME_TOKEN。这些变量与 SDK_PORTAL_* 接入审核变量分开。

| 项目 | local：本地 SDK | central：内网公共服务 |
| --- | --- | --- |
| 游戏部署动作 | 下载固定版本 ZIP、校验后运行 huohua-game-service | 不下载、不启动 SDK，配置平台提供的服务 URL |
| 访问地址 | http://127.0.0.1:8088 | 平台配置的京东云内网 HTTPS 域名 |
| 数据存储 | 本游戏独立 SQLite | 集中 PostgreSQL，每游戏独立 schema |
| 微信和广告密钥 | 本游戏 SDK 部署环境提供 | 公共服务部署环境提供，游戏调用端无需持有 |
| 接口 | /v1/games/{gameID}/… | 相同路径、请求正文与业务语义 |
| 升级 | 游戏部署端按固定版本升级 | 平台升级集中实例，游戏固定兼容 API 版本 |

缺失模式或地址时报告缺失配置，不替用户猜测。游戏接入端不得更改平台管理的游戏标识、前缀或密钥。中央模式中的 sdkVersion 字段沿用现有控制协议名称，填平台提供的公共服务兼容版本，不表示游戏安装了 SDK。

两种模式只改变部署和调用配置。每个游戏每个环境只启用一个权威数据源，不做双写，不因网络超时自动改为本地发奖。HTTP 调用代码和版本协议共用；已有数据切换必须走离线迁移流程。

## 集中部署

由平台部署系统维护 config.central.example.json 和每游戏配置文件。每游戏文件沿用 config.features.example.json 的身份、微信、功能、中转字段；其中 listen/databasePath 是本地模式兼容字段，在集中模式中不启动本地端口、不打开 SQLite 文件。

```text
huohua-public-service -config /etc/huohua/config.central.json
```

集中模式新增 HUOHUA_PUBLIC_DATABASE_URL，使用标准 PostgreSQL URL（不要包含 Prisma 的 schema 查询参数）。生产使用专用数据库和专用角色；不复用火花业务连接。数据库角色需可创建本服务的 schema 和表，数据库不对游戏后端开放。

游戏注册表在 huohua_control，保存身份、凭据摘要及配置指纹。游戏业务 schema 为 hh_ 加 game_id 的 SHA256 前 32 个十六进制字符。所有业务表、外键、业务幂等键、回调交易和事件均位于对应 schema；连接 search_path 由服务端认证后的游戏确定，客户端不能指定数据库或 schema。

游戏 ID、前缀和微信应用绑定一经注册不能替换；前缀和应用全局唯一。平台配置不接受游戏端任意写入。新增游戏由部署自动化写入受控配置并滚动启动实例，不需要后台人工填写任务字段。配置文件及凭据由平台部署环境管理，不能放在公共文档目录。

每游戏 enabled=false 可停用。轮换令牌时先发布新 tokenEnv，并在 previousTokenEnv 指定旧凭据环境名；完成调用端更新后移除 previousTokenEnv 再发布。运行凭据摘要跨游戏唯一。实例每请求核对注册表状态和指纹；旧配置实例返回 CONFIGURATION_CHANGED，需由负载入口摘除。滚动更新须先准备新实例，再切流并下线旧实例，避免把配置不一致期间的 503 当作游戏业务失败。

注册表、凭据轮换和部署配置是受控平台操作，不属于游戏 AI 的接入 API 权限。已有火花 applicationType/applicationId、运行 game_id 和签名标识的映射仍由平台预置，中转保留独立凭据及已有签名协议。任务提交、清单获取、正反例和后台审核继续走 openapi.json，不改任务结算规则。

## 内网和 TLS

- huohua-public-service 只允许显式私有 IP 或 loopback，禁止 0.0.0.0、公网 IP 默认监听。
- 可设置 tlsCertFile/tlsKeyFile，由程序直接提供 TLS（最低 TLS 1.2）。推荐内网域名、可信证书及京东云同地域 VPC，安全组只放行游戏后端。
- 也可按 public-nginx.example.conf 在内网入口终止 TLS，程序监听 127.0.0.1。实例分布在不同主机时，代理到后端继续使用 TLS；allowPrivateHttp 是明确选择可信私网明文的例外，不是默认设置。
- 文档网站不代理 /v1/games/，静态网站和运行服务分开部署；仅 /api/sdk/ 代理到火花接入控制面。不能将运行密钥或数据库连接打包进站点。
- 游戏公网广告回调入口保留在游戏后端，原样转发 RawQuery 至所选公共服务。前端广告展示不转移到服务端；真实广告位的签名、编码及响应仍须渠道验证。

## 调用、并发与故障

游戏示例使用同一客户端，禁止重定向携带凭据。设置连接和请求超时；401检查凭据，400修改参数，409读取当前状态，429按 Retry-After 退避，5xx和超时保持原业务 ID 查询或重试。不要生成新幂等键来绕过失败。

集中入口默认每游戏 6000 请求/分钟、16 个并发请求，实例最多 64 个业务请求同时执行；可按部署压测调整游戏频率。超过限制返回 429 或 SERVICE_BUSY。每游戏 PostgreSQL 池最多 4 个连接，空闲连接不保留，游戏运行模块按首次授权请求加载。后台采用 8 个发送工作协程和有界队列，避免每游戏各自启动轮询线程；空闲游戏不产生发送任务。

跨实例的修改事务使用游戏级 PostgreSQL 事务锁（5 秒锁等待、12 秒语句上限）保证余额、幂等和队列领取一致。不同游戏的锁独立。热门单游戏的写吞吐因此有明确上限，需按实测评估进一步细化锁；当前实现不能宣称已验证 1 万款活跃游戏容量。当前内存缓存已初始化的游戏模块，需监控活跃游戏数和资源，实例分片通过受控游戏配置和内网入口路由实现。

登录、礼包和体力即时返回；排行榜配置可在业务允许的范围缓存。公共服务持久接收事件后，由现有中转异步投递火花，玩家不等待腾讯云处理。游戏后端自己仍应持久保存待发送业务事件，重试使用原 eventId。

道具/货币的游戏事务与公共事务不跨库合并。礼包 claimId、体力购买 orderId、广告 contextId 必须在游戏数据库建立唯一发放或扣款记录；使用预留、确认、查询、补偿恢复，不因 HTTP 超时重复加钱或加道具。

## 模式切换和回滚

新游戏没有数据时，可直接选择任一模式。已有数据切换按以下顺序操作：

1. 停止该游戏业务写入、广告回调转发和事件发送工作；集中模式将该游戏下线并关闭相关实例/任务，不只停止玩家入口。
2. 使用旧版程序对 SQLite 备份，或用 pg_dump 对 PostgreSQL 备份；保留源数据、配置、版本和回执。迁移前禁止让旧、新服务同时消费队列。
3. 目标必须为空。迁移到 SQLite 时配置全新的数据库文件；迁移到集中服务时先迁移，后启用游戏，避免初始化 common_rules 导致目标非空。
4. 使用同一 game_id 的单游戏配置和目标数据库环境执行迁移工具。--offline-confirm 表示操作者确认全部写入已停，工具不会自动关闭云端进程。

```text
huohua-transfer -direction sqlite-to-postgres -config game.json -offline-confirm
huohua-transfer -direction postgres-to-sqlite -config game-new-path.json -offline-confirm
```

工具复制玩家、会话、礼包、存档、体力、购买、广告、排行榜、幂等记录和所有事件状态，单事务写入目标，修复序列，并输出逐表行数及内容摘要；目标复核失败则保持停写。它不复制中央身份注册表或密钥，不删除源数据，不自动切路由。备份升级前另见部署升级文档。

5. 核对迁移报告、玩家 ID、余额、存档版本、待发事件及终态奖励；修改游戏环境 URL/模式/凭据和回调目标，启动唯一的新服务后恢复流量。
6. 未恢复写入时可直接退回原源；新端已经写入后不能恢复旧快照丢弃新数据，必须再次停写并反向迁移到空目标后回滚。待发事件及幂等记录一并迁移，保留原业务 ID。

## 验收与观测

健康检查 /healthz、数据库就绪 /readyz 不需要令牌；具体游戏能力需认证访问 /capabilities。监控入口请求耗时 p50/p95/p99、429/503、数据库连接与锁等待、失败事件和积压；入口访问日志不得记录 Authorization、微信 code 或广告完整回调参数。

先本地使用独立测试库验证两游戏隔离、重复扣减、奖励幂等、停用和轮换、重启恢复及双向迁移，再到京东云测内网往返与高负载。真实微信、真实广告、云网络和生产备份恢复需要部署环境验收，不能以本地通过代替。