短信服务
本章介绍短信通道的配置：通道建立、签名与模板绑定、测试发送、故障切换。
功能入口：控制台 →「短信服务」。该页面仅超级管理员可见。
1. 开始之前：签名与模板需提前报备
短信签名与模板须先在各服务商的控制台完成资质认证与报备，审核时间由服务商与提交材料决定，应提前确认。
这是外部流程，不在本系统内完成。请在计划上线时间之前预留出这段周期，否则配置完成也无法实际发送。
2. 当前支持的场景
登录验证码按认证场景配置；流程或云端通知使用其支持的通知模板。验证码模板与通知模板用途不同，不应混用。
页面顶部的「场景覆盖概览」显示各场景当前由哪些通道承载。未配置时显示「未配置，该场景短信不可用」。
3. 通道
短信通过「通道」发送。一个通道对应一个服务商账号，可建立多个通道。
支持的服务商：腾讯云、阿里云、华为云、百度智能云、火山引擎、云片，以及用于联调的假通道。
3.1 通道列表
列表显示名称、类型、启用状态、优先级、签名、绑定数量。
优先级与故障切换：数值越小优先级越高。发送时按优先级顺序尝试，前一个通道失败则自动切换到下一个。配置多个通道可提升发送的可靠性。
删除通道时，若其下存在模板绑定，确认框会说明这些绑定将被一并删除。
3.2 三个页签的顺序
新建通道的工作区分三个页签，且有先后顺序：
| 页签 | 内容 |
|---|---|
| 通道设置 | 服务商、凭据、签名、限流等 |
| 模板绑定 | 场景与短信模板的对应关系 |
| 测试发送 | 实际发送验证 |
必须先保存通道设置，才能管理模板绑定与测试发送。 未保存时后两个页签处于锁定状态，界面提示「请先保存通道设置，才能管理模板绑定与测试发送」。
4. 通道设置
| 配置项 | 说明 |
|---|---|
| 通道名称 | 必填，便于识别 |
| 服务商类型 | 见上 |
| 启用该通道 | 开关 |
| 优先级 | 数值越小越优先 |
| 短信签名 | 必填。须是已在服务商完成报备的签名 |
| 地域 / Endpoint | 可选择预设，或直接输入。华为云须填写完整地址 |
| AccessKey 环境变量名 | 见下方说明 |
| AccessSecret 环境变量名 | 见下方说明 |
| 附加密钥环境变量名 | 可选 |
| 每小时发送上限 / 每日发送上限 | 发送量限制 |
不同服务商另有各自的专属字段，例如 SDK 应用标识、短信通道号、短信账号、签名标识等。云片只需填写 AccessKey 环境变量名，其余凭据字段可留空。
4.1 凭据的填写方式
🔴 这里填写的是服务器环境变量的名称，不是密钥本身。
界面提示为「密钥本身放在服务器环境变量里，这里只填变量名，不填密钥明文」。
具体做法：由部署人员在服务器上将密钥设置为环境变量，然后在此填写该变量的名称。若填错变量名，验证步骤会失败。
注意这与外部目录同步的凭据填写方式不同，后者是直接填写密钥值。两处不要混淆。
4.2 验证凭据并获取签名
配置界面按三步引导：
- 填写凭据；
- 验证并获取：点击后向服务商探活，并拉取该账号下已报备的签名与模板列表。成功时提示已获取的签名与模板数量；
- 确认地域与签名：从拉取到的列表中选择。
未填写凭据即点击验证时，提示「请先填写凭据后再验证」。
部分服务商不支持通过接口拉取列表（需按标识单独查询、需要额外鉴权、或联调假通道无远程数据），此时界面会提示手工填写已报备的签名名称。服务商账号下尚无已报备签名时，同样需手工填写。
截图展示本地通道配置；真实短信发送还需要服务商审核通过的签名、模板与有效凭据。
短信场景的本地与云端路由
新增短信通道的服务商与凭据设置
5. 模板绑定
模板绑定定义"某个场景使用哪个短信模板发送"。
| 配置项 | 说明 |
|---|---|
| 场景 | 当前仅「登录验证码」 |
| 类别 | 验证码类、通知类、营销类 |
| 模板 Code | 从拉取到的模板列表中选择；该服务商不支持拉取时手工填写 |
| 参数模式 | 具名参数、顺序参数、整段内容 |
| 参数名顺序 | 选择顺序参数模式时，按模板中变量出现的顺序添加参数名 |
选择模板后界面显示模板内容预览，以及该模板在服务商侧的审核状态（已通过、审核中、未通过、未知）。
审核状态为「审核中」或「未通过」的模板无法实际发送，须等待服务商审核通过。
6. 测试发送
在「测试发送」页签向指定手机号实际发送一条短信，验证整条链路是否通畅。
测试通过的标准：收到短信，且签名显示正确、内容与模板一致。
7. 配置示例
- 在服务商控制台完成签名与模板的报备，等待服务商审核通过；
- 请部署人员在服务器上设置存放密钥的环境变量；
- 在本页点击「新增通道」，填写通道名称并选择服务商类型；
- 填写凭据对应的环境变量名，点击「验证并获取」；
- 从拉取到的列表中选择地域与已报备的签名；
- 设置优先级与发送上限，保存；
- 切换到「模板绑定」页签，新增一条绑定：场景选「登录验证码」，选择模板，按模板变量配置参数模式与顺序；
- 切换到「测试发送」，向自己的手机号发送一条，确认收到且签名正确；
- 如需提升可靠性，重复以上步骤建立第二个通道，设置较大的优先级数值作为备用。
8. 使用限制与注意事项
| 限制 | 说明 |
|---|---|
| 签名与模板须提前报备 | 周期由服务商审核决定，须提前规划 |
| 当前仅支持登录验证码场景 | 其他场景尚未开放 |
| 凭据填写的是环境变量名 | 不是密钥本身，需部署人员配合 |
| 未保存通道设置时后两页签锁定 | 须先保存 |
| 部分服务商不支持拉取列表 | 需手工填写签名与模板标识 |
| 审核未通过的模板无法发送 | 须等待服务商审核 |
9. 相关章节
云端签名与模板
「短信服务」可查看云端提供的可用签名与模板目录，目录由云端管理，本实例只读。云服务未启用时云端目录不可用；本地通道仍按原配置管理。
发送场景已有本地绑定时走本地，没有本地绑定时才走云端。新增登录页短信标签还要求相应短信认证方式实际安装、配置并启用，仅配置短信通道不会自动增加登录方式。
相关开关与积分见开通云服务与 KimpoAI。