chore: sync local latest state and repository cleanup

docs/CONFIGURATION_GUIDE.md

@@ -385,6 +385,111 @@ spring:
 
 ## 🔐 安全配置
 
+### 回调API白名单配置
+
+系统对回调API请求进行IP白名单验证，确保只有受信任的服务器才能调用回调接口。
+
+#### 回调白名单配置项
+
+```yaml
+app:
+  callback:
+    # IP白名单列表，用逗号分隔
+    # 生产环境必须配置，否则启动会失败（fail-fast）
+    whitelist:
+      ips: "203.0.113.1,198.51.100.1,10.0.0.0/8"
+
+    # 宽松模式（仅用于开发/测试环境）
+    # 设为true时跳过IP白名单验证
+    whitelist:
+      permissive: false
+```
+
+#### 环境变量配置
+
+```bash
+# 方式1：直接配置IP白名单（推荐生产环境使用）
+export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.1"
+
+# 方式2：启用宽松模式（仅用于开发/测试）
+export MOSQUITO_CALLBACK_WHITELIST_PERMISSIVE="true"
+
+# Spring配置方式
+export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.1"
+```
+
+#### 生产环境配置示例
+
+```yaml
+# application-prod.yml
+app:
+  callback:
+    whitelist:
+      ips: "${MOSQUITO_CALLBACK_WHITELIST_IPS}"
+      permissive: false
+```
+
+生产环境启动前检查清单：
+
+1. **确认已配置IP白名单**
+   ```bash
+   # 检查环境变量
+   echo $MOSQUITO_CALLBACK_WHITELIST_IPS
+
+   # 如果未配置，启动会失败并报错：
+   # "生产环境回调白名单配置缺失！请配置 mosquito.callback.whitelist.ips 或启用 permissive 模式。"
+   ```
+
+2. **配置CIDR格式IP段**
+   ```bash
+   # 支持CIDR格式（但需注意：系统使用简单字符串分割，不支持严格的CIDR解析）
+   # 推荐列出所有具体IP或使用云服务商的弹性IP
+   export MOSQUITO_CALLBACK_WHITELIST_IPS="203.0.113.1,198.51.100.10,198.51.100.20"
+   ```
+
+3. **常见云服务商IP段**
+   ```bash
+   # 阿里云ECS（需要根据实际配置）
+   export MOSQUITO_CALLBACK_WHITELIST_IPS="10.0.0.0/8,172.16.0.0/12"
+
+   # AWS EC2
+   export MOSQUITO_CALLBACK_WHITELIST_IPS="3.0.0.0/8,18.0.0.0/8"
+   ```
+
+#### 开发/测试环境配置
+
+```yaml
+# application-dev.yml
+app:
+  callback:
+    whitelist:
+      permissive: true  # 跳过白名单验证
+```
+
+或通过环境变量：
+
+```bash
+# 开发环境
+export MOSQUITO_CALLBACK_WHITELIST_PERMISSIVE="true"
+
+# 测试环境（使用测试配置）
+export SPRING_PROFILES_ACTIVE=test
+```
+
+#### 故障排查
+
+| 错误信息 | 原因 | 解决方案 |
+|---------|------|---------|
+| "生产环境回调白名单配置缺失" | 未配置`mosquito.callback.whitelist.ips` | 配置IP白名单或启用permissive模式 |
+| "来源IP不在白名单中" | 回调请求IP不在白名单中 | 将该IP添加到白名单 |
+| "启动失败" | 生产环境未配置白名单 | 配置`MOSQUITO_CALLBACK_WHITELIST_IPS` |
+
+#### 白名单验证逻辑
+
+- 系统启动时如果`permissive=false`且`ips`为空，会抛出异常阻止启动（fail-fast）
+- 每个回调请求都会验证来源IP是否在白名单中
+- 不在白名单中的请求会被拒绝并返回`IP_NOT_WHITELISTED`错误
+
 ### API密钥加密
 
 ```yaml