火山引擎短信配置

Tigshop 支持阿里云、腾讯云、华为云、火山引擎四选一。本文说明火山引擎（smsProvider = 4）从控制台开通到商城后台配置的完整流程。

---

一、火山引擎控制台配置

1. 开通短信服务

登录 火山引擎短信控制台，完成实名认证并开通国内短信。

2. 创建短信应用（获取短信应用 ID）

路径：短信服务 → 应用管理

• 创建短信应用，记录 短信应用 ID（SmsAccount，如 smsAccount00001）。
• 对应商城后台 短信应用 ID 表单项（接口字段 smsVolcengineSmsAccount）。

3. 申请短信签名

路径：签名管理

• 申请签名（如：佰商科技），审核通过后方可发送。
• 签名名称须与商城后台 短信签名 完全一致。

4. 申请正文模板（获取模板 ID）

路径：模板管理

• 按业务场景创建模板，审核通过后记录 模板 ID。
• 火山引擎变量格式为 {变量名}，如 {code}、{order}。

占位符说明
商城数据库存 ${code}、${order}；在「消息管理」详情中会转换为 {code}、{order} 展示，便于你对照控制台建模板。实际发送以火山引擎控制台审核通过的模板为准。

常见场景模板内容参考：

场景	火山引擎控制台模板示例
手机验证码	验证码：{code}（手机绑定，请完成验证），如非本人操作，请忽略本短信
支付成功	购物提醒，您已成功完成订单{order}支付，请留意我们的发货通知
发货通知	亲爱的客户，您购买的货物已通过{shipping_name}发出，单号{code}…
退款成功	亲爱的客户，您购买的货物（订单号：{order}）已完成退款…
商家下单提醒	有新的会员购物提醒，订单号{order}，订单额{fee}，请及时关注

5. 获取 AccessKey ID、SecretAccessKey

登录 火山引擎密钥管理：

1. 创建或查看 AccessKey ID、SecretAccessKey。
2. 为密钥授予短信发送相关权限。
3. 密钥具备费用与发送能力，请妥善保管，勿泄露。

---

二、商城后台配置（对应前端页面）

进入路径

后台 → 设置 → 消息设置 → 通知设置 → 短信通知设置

顶部页签选择 「短信通知设置」（左侧第一个页签，与邮件/钉钉/企业微信并列）。

页面示意

1. 服务商 单选 火山引擎（值为 4）。
2. 填写 AccessKey、短信应用 ID、签名等，点击保存。

表单项与火山引擎控制台对照

前端表单项	是否必填	接口字段	在火山引擎哪里获取	填写说明
AccessKey ID	是	smsVolcengineAccessKey	IAM 密钥管理	标识 API 调用者身份。脱敏回显未改可原样保存；修改时点 「编辑」 填完整值。
SecretAccessKey	是	smsVolcengineSecretKey	同上	用于接口签名鉴权，请妥善保管。
短信应用 ID	是	smsVolcengineSmsAccount	短信控制台 → 应用管理	短信应用 ID，示例：smsAccount00001。
短信签名	是	smsVolcengineSignName	签名管理（已审核）	须在控制台创建并审核通过，如：佰商科技。
商家短信号码	否	smsVolcengineShopMobile	自行填写商家手机号	用于商家接收会员订单等信息，可不填。

保存说明

• 保存接口：POST /adminapi/setting/config/saveNotify
• 后端仅校验火山引擎必填五项；其他服务商字段可空但建议随表单一起提交。
• 切换为火山引擎后，请到 消息管理 更新全部短信场景的 模板 ID。

---

三、消息管理：配置各场景模板 ID

路径：后台 → 设置 → 消息设置 → 消息管理

1. 打开需要发短信的消息类型。
2. 查看只读项：当前短信服务商：火山引擎。
3. 短信模板 ID 填写火山引擎控制台「模板管理」中的 ID。
4. 通知内容 只读；占位符在详情中显示为 {code}、{order} 等，与控制台模板变量名一致即可。

注意	说明
勿沿用阿里云 ID	如 SMS_129764389 在火山引擎无效，必须换成火山模板 ID
变量名一致	控制台模板用 {code}，则业务传参须包含对应字段

---

四、常见问题

现象	可能原因	处理建议
保存提示短信应用 ID 不能为空	未填 smsAccount	在火山引擎应用管理中复制完整应用 ID
发送无 messageId	模板/签名/应用 ID 不匹配	核对应用 ID、签名、模板 ID 均属同一账号且已审核
变量错误	模板变量与传参 JSON 不一致	对照控制台模板变量名检查业务参数
密钥无效	脱敏值被误保存为明文密钥	点「编辑」重新输入完整 AccessKey

技术说明（供排查）： 发送时手机号自动补 +86；模板参数以 JSON 字符串传给火山引擎 SDK；成功以返回 messageId 为准，失败请查后台日志错误码。