diff --git a/backend/ruoyi-admin/src/main/resources/application-dev.yml b/backend/ruoyi-admin/src/main/resources/application-dev.yml
index b6e868f..cc05bc6 100644
--- a/backend/ruoyi-admin/src/main/resources/application-dev.yml
+++ b/backend/ruoyi-admin/src/main/resources/application-dev.yml
@@ -153,37 +153,35 @@ mail:
   # Socket连接超时值，单位毫秒，缺省值不超时
   connectionTimeout: 0
 
---- # sms 短信 支持 阿里云 腾讯云 云片 等等各式各样的短信服务商
-# https://sms4j.com/doc3/ 差异配置文档地址 支持单厂商多配置，可以配置多个同时使用
+--- # sms 短信服务配置（阿里云）
+# 文档: https://sms4j.com/doc3/
+# 阿里云短信控制台: https://dysms.console.aliyun.com/
 sms:
-  # 配置源类型用于标定配置来源(interface,yaml)
+  # 配置源类型: yaml(配置文件) 或 interface(接口配置)
   config-type: yaml
-  # 用于标定yml中的配置是否开启短信拦截，接口配置不受此限制
+  # 是否开启短信拦截（框架层面的限制）
   restricted: true
-  # 短信拦截限制单手机号每分钟最大发送，只对开启了拦截的配置有效
+  # 单手机号每分钟最大发送次数
   minute-max: 1
-  # 短信拦截限制单手机号每日最大发送量，只对开启了拦截的配置有效
+  # 单手机号每日最大发送次数
   account-max: 30
-  # 以下配置来自于 org.dromara.sms4j.provider.config.BaseConfig类中
   blends:
-    # 唯一ID 用于发送短信寻找具体配置 随便定义别用中文即可
-    # 可以同时存在两个相同厂商 例如: ali1 ali2 两个不同的阿里短信账号 也可用于区分租户
-    config1:
-      # 框架定义的厂商名称标识，标定此配置是哪个厂商，详细请看厂商标识介绍部分
+    # ============================================================
+    # 阿里云短信配置（H5接口使用）
+    # 配置名称 "alibaba" 与 h5.sms.sms-config-name 对应
+    # ============================================================
+    alibaba:
+      # 厂商标识（固定值）
       supplier: alibaba
-      # 有些称为accessKey有些称之为apiKey，也有称为sdkKey或者appId。
-      access-key-id: 您的accessKey
-      # 称为accessSecret有些称之为apiSecret
-      access-key-secret: 您的accessKeySecret
-      signature: 您的短信签名
-      sdk-app-id: 您的sdkAppId
-    config2:
-      # 厂商标识，标定此配置是哪个厂商，详细请看厂商标识介绍部分
-      supplier: tencent
-      access-key-id: 您的accessKey
-      access-key-secret: 您的accessKeySecret
-      signature: 您的短信签名
-      sdk-app-id: 您的sdkAppId
+      # -------------------- 以下参数需要替换为真实值 --------------------
+      # AccessKey ID（阿里云控制台 - AccessKey管理）
+      # 建议使用RAM子账号，仅授予短信发送权限
+      access-key-id: ${ALIYUN_SMS_ACCESS_KEY:您的AccessKeyId}
+      # AccessKey Secret
+      access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET:您的AccessKeySecret}
+      # 短信签名（阿里云短信控制台 - 签名管理，需审核通过）
+      # 例如：盘古教育、湖北新华
+      signature: ${ALIYUN_SMS_SIGNATURE:您的短信签名}
 
 
 --- # 三方授权
diff --git a/backend/ruoyi-admin/src/main/resources/application.yml b/backend/ruoyi-admin/src/main/resources/application.yml
index 7be111f..90429d8 100644
--- a/backend/ruoyi-admin/src/main/resources/application.yml
+++ b/backend/ruoyi-admin/src/main/resources/application.yml
@@ -265,16 +265,36 @@ warm-flow:
   # 默认Authorization，如果有多个token，用逗号分隔
   token-name: ${sa-token.token-name},clientid
 
---- # H5短信防刷配置
+--- # H5短信配置（阿里云）
+# ============================================================
+# H5接口短信验证码配置
+# 阿里云短信模板申请: https://dysms.console.aliyun.com/
+# ============================================================
 h5:
   sms:
-    # 是否启用短信发送（false时仅打印日志，用于测试）
+    # ---------- 基础配置 ----------
+    # 是否真正发送短信（false时仅打印日志，用于开发测试）
+    # 生产环境必须设置为 true
     enabled: false
-    # 验证码长度
+    # 阿里云短信配置名称（对应 application-dev.yml 中 sms.blends 下的配置名）
+    sms-config-name: alibaba
+
+    # ---------- 短信模板配置 ----------
+    # 阿里云短信模板ID（需在阿里云控制台申请并审核通过）
+    # 模板内容示例：您的验证码为${code}，${minutes}分钟内有效，请勿泄露给他人。
+    # 登录验证码模板ID
+    login-template-id: ${ALIYUN_SMS_LOGIN_TEMPLATE:SMS_XXXXXX}
+    # 注册验证码模板ID
+    register-template-id: ${ALIYUN_SMS_REGISTER_TEMPLATE:SMS_XXXXXX}
+
+    # ---------- 验证码配置 ----------
+    # 验证码长度（位数）
     code-length: 6
     # 验证码有效期（分钟）
     code-expire-minutes: 5
-    # 同一手机号发送间隔（秒）
+
+    # ---------- 防刷策略配置 ----------
+    # 同一手机号发送间隔（秒），防止频繁发送
     send-interval-seconds: 60
     # 同一手机号每日发送上限
     daily-limit-per-phone: 10
@@ -282,13 +302,9 @@ h5:
     minute-limit-per-ip: 5
     # 同一IP每日发送上限
     daily-limit-per-ip: 50
+
+    # ---------- 黑名单配置 ----------
     # 黑名单封禁时长（分钟）
     blacklist-minutes: 30
-    # 触发黑名单的验证失败次数
+    # 连续验证失败多少次后加入黑名单
     blacklist-trigger-count: 5
-    # 阿里云短信配置名称（对应sms.blends下的配置）
-    sms-config-name: alibaba
-    # 短信模板ID - 登录
-    login-template-id: ''
-    # 短信模板ID - 注册
-    register-template-id: ''
diff --git a/docs/02-技术方案/H5会员接口需求与技术方案.md b/docs/02-技术方案/H5会员接口需求与技术方案.md
index 15990c4..b4d41cf 100644
--- a/docs/02-技术方案/H5会员接口需求与技术方案.md
+++ b/docs/02-技术方案/H5会员接口需求与技术方案.md
@@ -254,48 +254,83 @@ backend/ruoyi-modules/pangu-business/src/main/java/org/dromara/pangu/
 
 ### 3.4 短信服务（阿里云）
 
-复用现有 `sms4j` 模块，配置阿里云：
+复用现有 `sms4j` 模块（版本 3.3.5），集成阿里云短信服务。
+
+#### 阿里云准备工作
+
+| 步骤 | 操作 | 说明 |
+|------|------|------|
+| 1 | 开通短信服务 | [阿里云短信控制台](https://dysms.console.aliyun.com/) |
+| 2 | 创建 AccessKey | 建议使用 RAM 子账号，仅授予 `AliyunDysmsFullAccess` 权限 |
+| 3 | 申请短信签名 | 签名管理 → 添加签名，审核通过后使用 |
+| 4 | 申请短信模板 | 模板管理 → 添加模板，需包含 `${code}` 变量 |
+
+**短信模板示例：**
+```
+验证码为${code}，${minutes}分钟内有效，请勿泄露给他人。
+```
+
+#### 阿里云配置（application-dev.yml）
 
 ```yaml
 sms:
+  config-type: yaml
+  restricted: true
+  minute-max: 1
+  account-max: 30
   blends:
+    # 配置名称 "alibaba" 与 h5.sms.sms-config-name 对应
     alibaba:
       supplier: alibaba
-      access-key-id: ${ALIYUN_SMS_ACCESS_KEY}
-      access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET}
-      signature: 盘古教育
-      template-id: SMS_XXXXXX
+      # AccessKey ID（阿里云控制台 - AccessKey管理）
+      access-key-id: ${ALIYUN_SMS_ACCESS_KEY:您的AccessKeyId}
+      # AccessKey Secret
+      access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET:您的AccessKeySecret}
+      # 短信签名（需审核通过）
+      signature: ${ALIYUN_SMS_SIGNATURE:您的短信签名}
 ```
 
-#### 短信防刷配置（application.yml）
+#### H5短信配置（application.yml）
 
 ```yaml
 h5:
   sms:
-    # 是否启用短信发送（false时仅打印日志，用于测试）
+    # ---------- 基础配置 ----------
+    # 是否真正发送短信（false时仅打印日志，用于开发测试）
     enabled: false
-    # 验证码长度
-    code-length: 6
-    # 验证码有效期（分钟）
-    code-expire-minutes: 5
-    # 同一手机号发送间隔（秒）
-    send-interval-seconds: 60
-    # 同一手机号每日发送上限
-    daily-limit-per-phone: 10
-    # 同一IP每分钟发送上限
-    minute-limit-per-ip: 5
-    # 同一IP每日发送上限
-    daily-limit-per-ip: 50
-    # 黑名单封禁时长（分钟）
-    blacklist-minutes: 30
-    # 触发黑名单的验证失败次数
-    blacklist-trigger-count: 5
-    # 阿里云短信配置名称（对应sms.blends下的配置）
+    # 阿里云短信配置名称
     sms-config-name: alibaba
-    # 短信模板ID - 登录
-    login-template-id: ''
-    # 短信模板ID - 注册
-    register-template-id: ''
+
+    # ---------- 短信模板配置 ----------
+    # 登录验证码模板ID（阿里云控制台申请）
+    login-template-id: ${ALIYUN_SMS_LOGIN_TEMPLATE:SMS_XXXXXX}
+    # 注册验证码模板ID
+    register-template-id: ${ALIYUN_SMS_REGISTER_TEMPLATE:SMS_XXXXXX}
+
+    # ---------- 验证码配置 ----------
+    code-length: 6
+    code-expire-minutes: 5
+
+    # ---------- 防刷策略配置 ----------
+    send-interval-seconds: 60
+    daily-limit-per-phone: 10
+    minute-limit-per-ip: 5
+    daily-limit-per-ip: 50
+    blacklist-minutes: 30
+    blacklist-trigger-count: 5
+```
+
+#### 环境变量配置（推荐）
+
+生产环境建议使用环境变量，避免密钥泄露：
+
+```bash
+# 阿里云短信配置
+export ALIYUN_SMS_ACCESS_KEY=LTAI5tXXXXXXXXXXXXXX
+export ALIYUN_SMS_ACCESS_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+export ALIYUN_SMS_SIGNATURE=盘古教育
+export ALIYUN_SMS_LOGIN_TEMPLATE=SMS_123456789
+export ALIYUN_SMS_REGISTER_TEMPLATE=SMS_987654321
 ```
 
 #### 防刷策略