# 腾讯云短信单文件配置

只需填写 `tencent-sms.json.example` 中的所有占位文字，另存为 `tencent-sms.json`，上传到：

`/etc/data-terminal-cloud/voice-runtime/tencent-sms.json`

`templates.login` 填登录模板 ID，`templates.register` 填注册模板 ID，`templates.change_password` 填修改密码模板 ID，`templates.change_phone` 填更换手机号模板 ID。其他字段填写 SecretId、SecretKey、短信 SDK AppID 和签名名称；保留英文双引号。AppKey 不用填。

更新服务端并应用 `000070_sms_purpose` 迁移后，API 和 worker 重启时会自动读取该文件。无需再拆分密钥或补充其他短信环境变量。文件中的 `enabled` 为 `true` 时开启短信，为 `false` 时关闭；单文件中的短信设置优先于旧版逐项配置，其他业务配置不变。

默认发送一个变量：6 位验证码。已核对当前腾讯云注册模板需要“验证码、有效分钟数”两个变量，单文件的 `template_params.register` 因此设置为 `["code", "expires_minutes"]`，实际发送验证码和 `5`。这部分无需填写真实值，由程序生成；其他三个模板保持默认单变量。

注册/登录共用的入口自动按账号是否已有手机号凭据选择模板，“忘记密码”使用修改密码模板。更换手机号的模板配置和按用途发送能力已支持，但项目目前尚无换号业务接口和页面，登录接口不会接受换号用途。

保存为 UTF-8（支持 Windows 编辑器的 BOM），文件访问权限沿用服务器同目录现有密钥文件，保证 API 和 worker 可以读取。填写后的 `tencent-sms.json` 已被本目录 `.gitignore` 忽略。

## 以下为旧版分文件配置，仅供兼容；使用上面的单文件时无需填写

共需填写 5 项：短信 SDK AppID、审核通过的签名名称、验证码模板 ID、SecretId、SecretKey。现有 AppKey 不需要填写。SaaS 和小程序共用同一套服务端配置。

## 1. 复制并填写文件

保留 `.example` 文件作为空白模板，复制一份并去掉文件名末尾的 `.example`：

| 填好后的文件名 | 需要填写的内容 |
| --- | --- |
| `tencent-sms.env` | 前 3 个配置项：短信 SDK AppID、签名名称、模板 ID |
| `tencent-sms-secret-id` | 仅一行 SecretId，替换原占位文字 |
| `tencent-sms-secret-key` | 仅一行 SecretKey，替换原占位文字 |

两个密钥文件不要写 `SecretId=` 或 `SecretKey=`，不要加引号、注释或其他说明。保存为 UTF-8 无 BOM；Windows 下注意文件名不要被自动加上 `.txt`。

短信 SDK AppID 来自腾讯云短信控制台，不是微信小程序的 `wx...` AppID。签名填写名称，不填写签名 ID。当前短信模板应只有一个变量，用于 6 位验证码，例如“您的验证码为 {1}，5 分钟内有效”。

## 2. 上传到服务器

| 本地填写好的文件 | 服务器保存路径 |
| --- | --- |
| `tencent-sms-secret-id` | `/etc/data-terminal-cloud/voice-runtime/tencent-sms-secret-id` |
| `tencent-sms-secret-key` | `/etc/data-terminal-cloud/voice-runtime/tencent-sms-secret-key` |
| `tencent-sms.env` | `/etc/data-terminal-cloud/tencent-sms.env`（配置备份） |

项目现有 Compose 把服务器 `/etc/data-terminal-cloud/voice-runtime` 只读挂载到容器 `/run/secrets/voice-runtime`，所以 `.env` 模板中的两个路径不用改。

## 3. 接入现有部署配置

把 `tencent-sms.env` 中的配置项合并到服务器部署当前使用的 `.env` 文件；同名项更新原值，不要重复添加，也不要用本模板覆盖整份 `.env`。保留数据库、站点地址、原有主密钥等其他配置。

填写全部参数、上传两个密钥文件，并更新服务端版本后，把 `ONBOARDING_SMS_LOGIN_ENABLED` 改成 `true`。使用现有的完整 Compose 部署命令重新创建 `api` 和 `worker`，使环境变量生效；部署配置需包含项目的 `compose.onboarding.yaml`。仅上传文件或普通重启容器不会自动加载新的环境变量。

文件访问权限沿用同目录现有密钥文件的属主、属组和权限，确保 API 与 worker 运行用户可以读取，其他无关用户不能读取。填好后的密钥文件仅存服务端，不放进小程序或前端代码。此目录的 `.gitignore` 已忽略去掉 `.example` 后的三个文件。

上传完成后，可以只告知文件所在路径，后续检查无需在聊天里粘贴密钥内容。