外观
故障排查
先保存接口返回的 code 和 requestId,以及当前 sessionId、rewardId、grantId。共享排查记录时隐藏 token、服务端 key、密码和签名原文。
启动失败
| 现象 | 检查顺序 | 处理 |
|---|---|---|
ADMIN_PASSWORD 或邮箱为空 | 根目录 .env 是否存在、变量是否为空、含 # 的值是否加引号 | 填写后重新启动;密码没有 12 位要求 |
修改 .env 后仍无法登录 | 数据库中是否已经有相同邮箱 | seed 不会覆盖已有密码;使用原账号密码,不能靠重复 seed 重置 |
| 找不到 MySQL 命令 | mysqld、mysql、mysqladmin 是否在 PATH | 安装所需工具,或用独立启动命令连接已有数据库 |
| 数据库连接失败 | 数据库端口、URL 编码、账号授权、服务存活 | 检查 .runtime/mysql.log;不要删除数据目录来解决连接问题 |
FFmpeg is required | ffmpeg 是否可执行 | 种子演示视频需要 FFmpeg;媒体检查还需要 ffprobe |
EADDRINUSE / 端口已占用 | 3000、5173、5174、5175 是否被其他实例占用 | 关闭自己先前启动的重复实例,再重试 |
| pnpm 要求重建 modules | 当前 store 配置是否与安装时一致 | 使用相同 --store-dir 或按 pnpm 提示重新安装 |
网页访问失败或跨域失败
- 先访问
/v1/health,确认 API 和数据库正常。 - 检查浏览器请求是否指向正确 origin,路径中是否缺少或重复
/v1。 - 如果浏览器跨域调用 API,将页面的完整 origin 加入
CORS_ORIGINS,例如http://127.0.0.1:5174。 localhost与127.0.0.1是不同 origin,端口也属于 origin 的一部分。- HTTPS 页面请求 HTTP 素材可能被浏览器阻止。生产使用 HTTPS API、素材和回调地址。
只运行文档站不需要 API。文档页面正常而 Swagger、后台或播放器不可达,通常意味着其他服务没有启动。
身份与鉴权
UNAUTHORIZED
- 客户端接口用
Authorization: Bearer <token>;业务后端接口用X-App-Key。不要混用。 - 客户端 token 当前有效期 1 小时。参考 HTTP 客户端可配置
refreshToken,401 时合并刷新并重放原请求一次;业务后端模式需由接入方提供刷新方法或用setToken()换入同身份 token。网络故障和其他错误不会触发无限刷新。 - 服务端 key 轮换后,旧 key 不能再调用业务后端接口。
- 如果应用已暂停,服务器 key 认证也可能失败。
SERVER_IDENTITY_REQUIRED
应用配置为 server_pull 或 server_webhook 时,匿名接入不可用。请由自己的业务后端验证玩家身份,再调用 /server/client-tokens。不要为了绕过此错误把服务端 key 写入 APP。
奖励或会话查不到
会话和奖励属于特定应用及用户身份。检查是否换了 App ID、安装 ID 或 subjectId。这些标识区分大小写。客户端读取其他身份的记录会得到找不到,而不是泄露记录信息。
无广告与频控
NO_FILL
按下面顺序检查后台:
- 应用有效,公开 App ID 正确。
- 广告位 code 存在、处于启用状态、属于该应用。
- 已创建关联正确广告位和素材的投放,并设为
active。 - 当前 UTC 时间位于投放排期内。
- 素材处于 ready 状态,投放配额没有耗尽。
- 视频的有效观看阈值没有超过素材时长;广告位规则变更可能导致继承规则的投放不再可用。
无填充不是观看完成。APP 应展示“暂时没有可用广告”或自己的产品降级方案,不可直接视为广告奖励资格。
FREQUENCY_CAPPED
检查应用每日奖励合计、广告位每日奖励次数、冷却时间及应用时区。冷却从成功 start 起算,普通展示也受冷却限制。未开始的会话会预留配额;已经开始后提前关闭的未合格激励会话也可能保留奖励配额,直到证据窗口清理。不要用新的安装 ID 反复绕过频控;测试时可由后台调整演示应用规则。
SESSION_ACTIVE
同一应用、同一用户只能有一个活跃广告会话。继续已有会话,或有序关闭它后再创建。创建请求超时后先用相同 Idempotency-Key 重试,不要立刻换 key 再创建。
素材无法展示
| 现象 | 常见原因 | 排查 |
|---|---|---|
| 素材 404 | 未发布,或没有有效投放/可用会话 | 后台预览和公开素材读取的权限不同 |
MEDIA_UNAVAILABLE | 数据库记录存在,但文件丢失 | 核对 MEDIA_DIR、容器卷和备份恢复中的素材文件 |
| 视频无法解码 | 实际编码、浏览器能力或文件损坏 | 检查 H.264、yuv420p、AAC,查看浏览器媒体错误 |
| 拖动/续传异常 | 反向代理没有传递 Range,或不支持正确的字节范围响应 | 检查 Accept-Ranges、206 与 Content-Range |
| S3 链接稍后失效 | 使用了过期的 300 秒签名 URL | 重新读取原始素材 API 地址,跟随新跳转 |
看完但仍为 PENDING
complete 事件本身不能产生奖励资格。检查:
- 是否在素材真正可展示时成功调用了
start。 - 是否上报了真实前台可见的
heartbeat,且sequence单调递增。 visibleSeconds是从本会话开始累计的有效前台可见秒数,应单调不减;服务端会计算相邻值的增量。重试同一事件时保持原值,不重置为本次间隔的秒数。- 视频是否以正常速度实际前进;拖动、回放同一片段不会作为新的正常进度累计。
- 页面隐藏、视频暂停、未成功播放时,不应继续累计有效时间。事件请求失败时保留原批次,能否继续播放与测量由应用策略决定,但不能把网络等待本身当成观看证据。
- 批量上报不能突破服务端实际经过时间预算;并非提供很大的秒数就能补回资格。
close的 sequence 必须位于真实播放事件之后。传输乱序可以恢复,但服务端只按连续序号前缀判断资格,缺少早期事件时后续 complete 不会越过缺口发奖。- 新事件应记录原始
elapsedSeconds(从 start 成功后开始的单调时钟,包含暂停/隐藏时段)。重试不得重采样或改写它;跨 showDeadline 的迟到证据必须有原始采样时间,并在 evidenceDeadline 之前补齐。
若参考播放器提示尚有待传事件,保持同一应用及安装身份重连。刷新会保留原事件与序号;不会把关闭页面期间的时间算作观看。遇到 SESSION_EXPIRED 时,播放器先确认服务端同一会话已结束,再归档旧证据并放行新广告;401 或暂时断网继续保留队列。INVALID_EVENT_TIMELINE 表示采样时间与事件顺序矛盾,应排查原始测量,不通过改写旧事件重试绕过检查。
查询 getSession() 获取服务器最新状态。网络恢复并不保证所有离线证据都能被认可,超过服务端时间窗口也不保证补发。
领奖问题
| 错误/状态 | 含义 | 对接处理 |
|---|---|---|
REWARD_PENDING | 资格尚未达到可领取状态,或已被拒绝 | 查询会话/奖励状态,不自动增发资产 |
REWARD_EXPIRED | 首次领取或消费窗口已过 | 明确失败;已领取的同一结果仍按恢复语义处理 |
DELIVERY_MODE_MISMATCH | 使用了其他模式的领取接口 | client_claim 由客户端领取,服务端模式由业务后端处理 |
CLAIMED | 客户端已经取得稳定 grantId | APP 按 grantId 幂等兑现;不代表服务器验证本地资产到账 |
CONSUMED_PENDING_ACK | 业务后端已消费但未确认入账 | 恢复同一 grant,检查业务事务,再 acknowledge |
DELIVERY_PENDING | 回调模式等待交付 | 检查 worker 和后台通知任务 |
请求超时无法证明服务器没处理。保持原 request key、eventId、rewardId、grantId,恢复原操作,不生成新奖励来“补一次”。
回调失败
- 确认 worker 运行,后台“奖励与交付”里确实存在通知任务。
- 公网回调使用 HTTPS 默认 443 端口;拒绝内网地址、URL 用户名密码和重定向。
- 检查 DNS 是否解析到公网地址;当前实现会检查并固定本次连接地址。
- 接收端必须使用原始 HTTP body 验签。不要 JSON.parse 后再 JSON.stringify 作为签名输入。
- 校验时间窗口、通知 ID,并使用所属应用的正确签名 key。
- 接收方应在完成幂等资产事务后返回 2xx JSON:
{"grantId":"原 grantId","status":"fulfilled"}。 - 只返回
200 OK或{ "success": true }不构成有效奖励确认。 - 服务端总请求期限约 8 秒;长任务可以先持久化并由业务处理,但未完成入账不能谎报 fulfilled。
初次失败后按 1 分钟、5 分钟、15 分钟、1 小时、6 小时、24 小时重试,之后进入失败状态供后台处理。重复通知复用稳定 grantId;重试成功也只能发一次奖励。
密钥轮换时,新接口调用使用新 key,但旧订单回调仍使用订单快照中的旧签名 key。轮换期间需要同时保留尚有未完成订单的旧 key,不能只更新接收方配置后立即删除所有旧 key。
详细协议见 Webhook 接入,错误码汇总见 错误参考。
报障信息模板
text
环境:本地 / 测试 / 生产
公开 App ID:
广告位 code:
发生时间(含时区):
接口方法与路径:
HTTP 状态 / code:
requestId:
sessionId / rewardId / grantId:
交付模式:client_claim / server_pull / server_webhook
复现步骤与预期结果:
实际结果:1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
不要附上应用 key、token、Cookie、管理员密码、完整数据库连接字符串。