标准模板接入
本页适用于 API 自建，托管商户无需部署模板。本页用于配置 partner 管理后台的「游戏接入配置」。站点安装和数据库初始化见交付包内 site/docs/deployment.md；模板下载入口在开放娱乐平台的「模板与工具」。
1. 准备站点与申请信息
先部署站点和独立数据库，确认回调服务可被提供方访问。然后在开放娱乐平台创建 API 自建应用，申请接入。
| 申请字段 | 填写内容 |
|---|---|
| 服务器 IP | partner 服务端调用游戏接口时的出口 IP，仅填一个 IPv4 或 IPv6；不是管理员浏览器的 IP |
| 回调地址 | 提供方可访问的完整 URL，例如 https://operator.example/callback |
| 申请说明 | 说明接入用途及需要审核的信息 |
模板的统一回调路径为 /callback，由 callback_listen 对应的服务监听。使用域名和反向代理时，将 /callback 转发到该监听地址；不要仅因管理后台能打开就认为回调已经连通。模板不会自动推断你的公网域名、出口 IP 或代理配置。
应用基本资料与申请操作见应用与接入申请。
2. 填入应用的凭据
审核通过后，进入开放娱乐平台的「接入应用 → 对应应用」，在接入凭据区域复制下列信息。打开 partner 管理后台的「游戏接入配置」，按表填写。
| 开放娱乐平台提供的信息 | partner 后台字段 | 注意事项 |
|---|---|---|
| 接口地址 | 接口基础地址 | 填写完整基础地址；不要填写开放平台网址、后台网址或追加 /api/v1 路径 |
| code | 合作方 code | 原样复制完整值，包括 code_ 前缀；不要填写字面值 code |
| secret | secret | 使用该 code 对应的当前 secret；重新生成后需在这里更新 |
三个字段必须属于同一个应用。接口地址是游戏 API 入口，不是开放平台页面地址。
3. 检测并保存
「检测连接」使用表单中的接口地址、code 和 secret 发起认证；成功不会保存配置。
「检测并保存」完成同样的验证，成功后保存并立即用于后续请求，无需重启站点。code、secret 和接口地址均可修改。
检测通过只表示认证通过，并不证明回调、游戏服务器和浏览器网络都正常。继续完成下一步联调。
4. 验证游戏与回调
- 在测试站点创建专用测试玩家，确认游戏列表能加载。
- 启动一个游戏，确认浏览器能打开返回的游戏链接。
- 完成一笔测试游戏结算并退出，检查后台游戏记录、钱包流水和回调记录。
- 确认回调成功，余额与结算记录相符。不要使用真实玩家做破坏性测试。
5. 检测失败如何排查
| 现象 | 检查顺序 |
|---|---|
| 超时或无法连接 | 从 partner 服务所在机器检查接口地址、端口、网络路由和防火墙 |
| IP 白名单拒绝 | 核对游戏入口看到的实际连接 IP 与所选应用登记的 IP；不要用浏览器 IP 或自行添加请求头代替 |
| 认证失败 | 核对所选应用是否审核通过、是否启用；重新复制完整 code 和当前 secret，检查服务端时钟 |
| 认证通过但无法游戏 | 查看游戏列表与启动接口响应，检查浏览器到游戏地址及 WebSocket 的连通性 |
| 游戏可启动但回调失败 | 检查完整回调 URL、/callback 代理目标、回调端口、当前 secret 和后台回调记录 |
白名单和密钥变更由运行服务刷新后生效，通常需要数秒。详细规则见签名认证与回调与结算。
6. 后续配置维护
开放平台中修改回调地址或服务器 IP，会更新所选应用的生效配置；回调地址不填入 partner 后台的接口基础地址。
重新生成 secret 后，在 partner 后台更新并「检测并保存」。接口地址发生变更时，按开放平台消息提示同步更新。