# App 公共服务部署、升级与迁移

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

## 三个独立程序

- huohua-app-agent：local SDK，单 App、loopback、本地 SQLite。
- huohua-app-service：central 公共服务，多 App、京东云内网 HTTPS、独立 PostgreSQL，每 App schema。
- huohua-app-transfer：离线双向数据迁移。不会自动切路由或删除源数据。

App 业务后端可用任意语言，通过 HTTP 调用。程序由平台维护编译，业务 AI 不需要公共实现源码。每个 App 和测试/正式环境分配独立身份与密钥。

```text
huohua-app-agent -config /etc/huohua-app/config.local.json
huohua-app-service -config /etc/huohua-app/config.central.json
```

本地首次启动配置不含真实平台连接也可验证用户/会话；要打通推广码及火花投递，需由平台注入 config.platform.example.json 所示参数。central 的每个 apps 项可使用相同平台配置字段。模板中的ID、地址均须换成真实预置值。

## 集中模式数据与路由

HUOHUA_APP_DATABASE_URL 使用标准 PostgreSQL URL，不带 Prisma schema 查询参数。生产用独立 App 数据库，不复用火花或游戏运行库；角色可创建本服务 schema，不对 App 业务服务器开放数据库。

注册表为 huohua_app_control，保存 App 到平台机器身份/数字ID的固定映射、凭据摘要和配置指纹；业务 schema 为 hha_ 加 app_id 的 SHA256 前32位。游戏使用另一套注册表和schema，App实现不引用游戏工程。

App 配置由受控部署系统维护，公开网页不提供密钥或配置写权限。首次配置后不自动换绑平台身份；新增 App 将配置由部署自动化写入并启动新版本实例。启停、轮换或配置变更使旧实例失效，需要入口摘流和滚动部署；停用不删除历史数据。

每 App 默认6000请求/分钟、16并发；每实例最多64并发业务请求；每 App PostgreSQL 池最多4连接且不保留空闲连接。后台4个发送工作协程、有界队列、按App轮询。业务模块首次授权访问时加载；集中服务重启后，后台有界轮询已存在的App事件表，发现到期积压时恢复投递，无需等待新的玩家请求。修改事务使用App级数据库事务锁，跨实例保证幂等及首次关系一致，不同App互不占用同一锁。

目前未证明支持任意数量活跃 App。上线按实际用户、事件频率压测，监控连接数、锁等待、队列及请求耗时；必要时按App配置和内网路由分片。不能只按 App 数量估算机器容量。

## 内网与回调

central 支持 tlsCertFile/tlsKeyFile，最低TLS1.2；直接监听私有IP时必须配置TLS。也可在内网 Nginx 入口终止TLS，程序监听127.0.0.1:8099。模板见 deploy，安全组仅放行授权 App 后端。

local 的监听地址必须loopback。App 后端公网回调入口将平台原始签名头和原始JSON正文转发至 /v1/apps/{appId}/platform/promotion-codes；此接口使用平台签名，不使用运行Bearer。平台任务领取后的码下发沿用既有火花推送协议：X-Game-Id、X-Game-Type=self_app、X-Game-Timestamp、X-Game-Signature，正文含action/cdkey/game_id。兼容名称仅在平台适配中保留。

推广码暂停后，本地记录不能被旧的启用回调重新打开。服务还会使用平台签名分页读取 /api/bounty/app/promotion-codes，循环全量核对已启用与禁用状态；每页最多100条，完整扫描后间隔1分钟再扫描。游标重启归零以安全重扫，不依赖旧ID递增来判断禁用更新。推送用于及时生效，拉取用于补齐丢失回调。平台配置回调URL指向可信入口，不能把本机地址写成跨云可直接访问。代码下发、禁用及历史补发由火花部署/集成流程配置；管理人员只审核，不新增人工传字段工作台。

事件由公共服务以同一签名规则调用 /api/bounty/app/report，仅 self_app 可访问；服务端内部适配历史数据结构。首次有效回执必须确认收到归因事实，才视为成功投递。正式App当前需已启用才能通过平台机器认证；测试使用独立、授权启用的测试App，不提前启用待审生产App。

## 备份与切换

SQLite使用旧版agent的 -backup 生成新绝对路径快照；备份命令不启动HTTP监听或后台投递。备份，包含WAL已提交数据。PostgreSQL用pg_dump及恢复演练。备份含账号关联和会话，应按平台数据权限保存，不上传到公开文档站。

已有数据切换必须停止该 App 业务写入、回调及事件发送工作，再备份。central 下线相关App并停掉有关工作进程；工具的 offline-confirm 只是操作者确认，不会代停云端程序。

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

工具使用 HUOHUA_APP_DATABASE_URL；配置须是单App local配置。PostgreSQL目标业务表必须为空；反向迁移SQLite必须新文件。传输用户关联、会话、码、首次关系、权益状态、幂等键和事件队列，单事务写入并逐表摘要复核。注册身份与密钥由部署配置管理，不复制密钥。

核对后更新业务服务地址、凭据和回调，启动唯一新端恢复流量。不同时向两端写入；新端已产生数据时，回滚也要停写并反向迁移到空目标，不能直接恢复旧快照丢弃新关系或重复发权益。

## 网站与审核API

App 网站产物是 .artifacts/sites/app，完整上传，包含JSON、Markdown、示例和下载，不只上传HTML。公网文档站不代理 /v1/apps/，该路径只在内网运行服务上；/api/sdk/applications/{category}/代理火花后端；管理员接口不公开代理。

入驻和联调直接使用统一应用协议v3，旧公共路径已移除。申请身份及接入地址由独立后端自动生成和保存，详见[统一应用自动入驻](统一应用自动入驻.md)。任务、奖励与钱包沿用现有业务审核规则。

## 真实环境验收

先完成本地双App隔离、重复事件/码、重启和双向迁移，再验证京东云域名/证书/安全组及实际回传。第三方登录仍需独立适配；穿山甲广告支持范围及入口约束见0.3.0文档，不能用本地签名夹具证明真实渠道已联调。缺少真实云环境时仅报告本地验证完成。

## 0.2.0 认证与前缀升级

先按《登录名密码与统一用户ID.md》初始化平台前缀台账、登记已有App和游戏前缀，再通过控制API获取每App分配结果，替换配置模板的ap。prefix启动绑定后不可换绑。默认由公共服务验证登录名密码，不需要App另写密码系统。当前产品只用password，不启用外部主体直传或第三方登录；不存在历史玩家时不新增迁移工作。

启动自动迁移数据库版本2；先备份并停旧写入，旧ID保留，新注册遵循公式。密码计算在事务外并受并发限制，登录与改密最终事务复核凭据版本。双向迁移包括password_accounts、auth_buckets、id_formula_binding及会话凭据版本；备份含密码哈希，应限制访问。禁止用旧二进制直接降级打开新库。

## 0.3.0账号状态与权益广告

接入前读取[账号状态与公共权益广告](账号状态与公共权益广告.md)。账号注销、禁用/恢复和全部会话撤销已提供；广告与礼包按受控配置直接发入公共权益字段，App通过预留/确认/取消消费。管理及广告回调使用独立managementTokenEnv；普通运行令牌不具备该权限。穿山甲与腾讯优量汇直连均已适配；优量汇须配置独立密钥、networkAppId与adUnitId，真实渠道仍需逐App验收。

## 0.4.0广告流程

广告按SDK完成通知先发奖，后台异步验真；正常和异常数据均发送火花，由广告数据核查页面人工处理。接入必读[广告先发奖异步验真与火花核查](广告先发奖异步验真与火花核查.md)。不自动追回、不自动封禁，广告上报不自动触发赏金结算。