---
name: sms-onboarding
owner: 老板（外部资源申请）
version: 2
last-updated: 2026-04-23
---

# SOP: 阿里云短信服务

## ✅ 2026-04-23 现状：零等待复用

**xiangqin 已切到 aliyun provider，签名 + 模板 + AK 都复用自 `aliyun.power-app`**：

- `sign_name = "杭州阿空智能科技"`（已审核通过）
- `template_code = "SMS_317151039"`（已审核通过）
- access_key_id / access_key_secret 同 platform 内已备

xiangqin 的 aliyun provider 启动时直接 `vault get aliyun.power-app` 读这四件套，**不需要申请任何新签名 / 模板 / 子账号**。流量起来（>100 条/天）再考虑加 RAM 子账号隔离权限。

生产 systemd 环境变量已配 `XIANGQIN_SMS_PROVIDER=aliyun`（2026-04-22 deploy），真手机号 `xq register` 会收真短信。

---

## 历史路径：全新申请（仅在 `aliyun.power-app` 签名作废时走这条）

⚠️ 涉及外部审核。总耗时 **2-5 天**。

## 一、申请短信签名（耗时 1-3 个工作日）

### 到哪里

https://dysms.console.aliyun.com/overview → 左侧"国内消息" → "签名管理"

### 填什么

- **签名名称**：建议 `xiangqin`（3-12 字）
- **签名类型**：通用（个人/企业都能用）→ 但需要企业认证审核才能加速
- **使用场景**：选"验证码"
- **签名来源**：企事业单位名称或网站名称
- **上传材料**：
  - 企业认证情况下：营业执照（jpg/png）
  - 网站名情况下：ICP 备案截图 + 网站可访问的 URL

### 审核结果

审核通过后 dysms 会给你一个可用的 **SignName** 字符串（例："xiangqin"）。保存下来。

## 二、申请短信模板（耗时 1-2 个工作日）

### 到哪里

同上页面 → "模板管理" → "创建模板"

### 填什么

- **模板类型**：验证码
- **模板名称**：`xiangqin 验证码`
- **模板内容**：
  ```
  您的验证码 ${code}，60 秒内有效，请勿告诉他人。
  ```
  （`${code}` 是变量占位，不要改名 —— xiangqin 代码传 `{"code": "123456"}`）
- **应用场景**：填"用户注册 / 登录"

### 审核结果

拿到 **TemplateCode** 字符串（例："SMS_12345678"）。保存。

## 三、准备凭证

### 查 / 新建 AK/SK

短信 API 调用用**阿里云主账号 AK/SK 或 RAM 子账号 AK/SK**。主账号 AK/SK 已经存 vault：

```bash
vault get aliyun
# credentials.access_key_id / access_key_secret 即是
```

**建议**：给短信服务做一个单独的 RAM 子账号 + 最小权限 policy（只允许 `dysms:SendSms`），避免主 AK 泄漏风险。RAM 创建：https://ram.console.aliyun.com/users

## 四、vault 里建新 platform

```bash
vault set aliyun-sms sign_name <上面拿到的 SignName>
vault set aliyun-sms template_code <上面拿到的 TemplateCode>
# AK/SK 复用 aliyun/main，不用再存一份
```

也可以在 `vault platforms` 里 review 看看。

## 五、切换 provider 到 aliyun

### 改 systemd unit 添加环境变量

```bash
ssh root@112.124.27.213
systemctl edit xiangqin     # override 文件
```

在弹出的编辑器里：
```ini
[Service]
Environment="XIANGQIN_SMS_PROVIDER=aliyun"
```

保存退出。然后：

```bash
systemctl daemon-reload
systemctl restart xiangqin
```

### 验证

```bash
# 本机跑 xq register 用自己真手机号测一次
cd /Users/yarnb/xiangqin
rm -rf /tmp/xq-sms-test
XIANGQIN_CONFIG_DIR=/tmp/xq-sms-test uv run xq register <你真手机号>
# 应该**收到真短信**，内容含"您的验证码 XXXXXX，60 秒内有效"
# 拿到验证码 → xq verify <code> --request-id <...>
```

## 六、回退

```bash
systemctl edit xiangqin
# 删掉 XIANGQIN_SMS_PROVIDER 那行（或改成 mock）
systemctl daemon-reload && systemctl restart xiangqin
```

回退后 mock provider 重新接管，验证码恒 123456。

## 坑 / 注意

- 签名审核拒：最常见原因 = 没企业认证。个人账号申请要提交网站 + 工信部备案
- 模板拒：`${code}` 必须是这个名字，不能用 `${verification_code}` / `${otp}`
- 国内短信频率限制：同一手机号 1 分钟 1 条 / 1 小时 5 条 / 1 天 10 条（平台硬限）
- 成本：约 ¥0.045 / 条（注册量大时要算）
