推送通道

推送通道页维护 6 个厂商通道（APNs、FCM、华为、小米、OPPO、vivo）的启用位与凭据字段。当前实现是配置存储 + 校验：保存、脱敏回读、启用前必填校验；厂商下发未实现，通道测试会如实返回 implemented=false / delivered=false。真实离线通知仍走既有推送 webhook。

概念​

• 读取返回 secretsSet、configured、missingFields，不返回敏感明文。
• 保存时敏感字段传 **** 开头表示保持原值；启用但缺必填字段返回 4xx。
• 写入未知通道/未知字段返回 4xx，避免拼写错误静默生效。
• 响应包含 deliveryImplemented=false，页面必须如实展示，不得显示“已发送”。

前置条件​

• 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#push（tab #push：推送通道）。
• 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
• 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
• 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

1. 查看现有配置

   确认每个通道的 configured、enabled 与 missingFields。

2. 按通道保存

   只提交目标通道；敏感字段首次填写或轮换时传新值。

3. 启用前校验

   补齐必填字段后再 enabled=true；缺字段会 4xx。

4. 诚实测试

   通道测试只返回配置/缺失字段与 implemented=false；真实通知走 webhook 推送测试。

参数表​

示例​

配置 APNs 并查看脱敏回读​

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/push/channels" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"channel":"apns","enabled":true,"fields":{"teamId":"TEAM123456","keyId":"KEY1234567","bundleId":"com.example.im","privateKey":"-----BEGIN PRIVATE KEY-----\\nMIIE...\\n-----END PRIVATE KEY-----"}}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/push/channels" \
  -H 'X-Admin-Secret: dev-admin'

# 通道测试：implemented=false，不伪造成功
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/push/channels/apns/test" \
  -H 'X-Admin-Secret: dev-admin'

真实离线通知：webhook 推送测试​

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/push/test" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"userId":"alice","title":"测试推送","body":"这是一条测试通知"}'

常见问题​

配置了 APNs 为什么手机没收到？​

厂商下发未实现，配置不会触发真实推送；请用 webhook 推送通道或等待后续版本。

secret 显示 **** 怎么确认？​

服务端只回脱敏值；需要更换时提交新值。不要尝试读取明文。

为什么保存报 4xx？​

常见原因是未知通道/字段、启用但缺必填字段；响应会指出缺失字段。

通道测试为什么 delivered=false？​

诚实返回：当前只校验配置，不执行厂商发送。

相关链接​

• 控制台功能索引：31 个模块与入口
• 运营后台指南：Admin API 全量参数与响应
• 应用与密钥：应用隔离与密钥轮换
• 推送统计
• 消息路由
• 推送 Open API