smsweb/TOKEN_ONLY_MODE.md

纯 Token 模式配置指南

功能说明

纯 Token 模式（Token Only Mode）允许短信转发接收端只验证 token 参数，跳过 HMAC-SHA256 签名验证。

适用场景

• TranspondSms APP 不支持或不需要 HMAC 签名
• 快速测试/开发环境
• 简化配置，降低部署复杂度

安全性建议

• 生产环境建议使用标准模式（Token + HMAC 签名）
• 纯 Token 模式下，请确保网络环境可信（内网、VPN）
• 定期更换 token

---

配置方法

1. 编辑 config.json

{
  "security": {
    "enabled": true,
    "username": "admin",
    "password": "admin123",
    "session_lifetime": 3600,
    "secret_key": "default_secret_key_change_me",
    "sign_verify": true,
    "sign_max_age": 3600000,
    "token_only_mode": true    // 启用纯 Token 模式
  },
  "api_tokens": [
    {
      "name": "测试设备",
      "token": "my_simple_token_123",
      "secret": "",
      "enabled": true
    }
  ]
}

关键配置项

配置项	类型	说明
token_only_mode	Boolean	是否启用纯 Token 模式（默认 false）
token	String	Token 值（TranspondSms 发送的值）
secret	String	在纯 Token 模式下可以为空

2. 重启服务

./sms_receiverctl.sh restart

或使用 systemd：

systemctl restart sms_receiver

---

TranspondSms 配置

标准 Token + 签名模式（默认）

TranspondSms 配置：

Token (URL): http://your-server:9518/api/receive?token=my_token
Secret: my_secret_key

纯 Token 模式

TranspondSms 配置：

Token (URL): http://your-server:9518/api/receive?token=my_simple_token_123
Secret: (留空或随意)

注意：TranspondSms 仍会发送签名参数，但服务端会忽略签名验证，只验证 token 是否匹配。

---

API 行为对比

标准 Token + 签名模式

1. TranspondSms 发送请求：

   • from: 发送方号码
   • content: 短信内容
   • timestamp: 时间戳
   • sign: HMAC-SHA256 签名
   • token: 识别设备

2. 服务端验证：

   • 根据 token 查找对应的 secret
   • 验证 HMAC 签名是否匹配
   • 验证时间戳是否过期
   • 保存短信记录

纯 Token 模式

1. TranspondSms 发送请求（同样参数，但签名被忽略）：

   • from: 发送方号码
   • content: 短信内容
   • token: 识别设备

2. 服务端验证：

   • 只验证 token 是否存在于配置列表中
   • 跳过签名验证
   • 跳过时间戳验证
   • 保存短信记录（标记为 sign_verified: true）

---

错误处理

Token 无效（纯 Token 模式）

{
  "error": "Token 无效"
}

返回：HTTP 401

缺少 Token（纯 Token 模式）

{
  "error": "缺少 token 参数（纯 Token 模式已启用）"
}

返回：HTTP 401

---

日志记录

服务会在日志中记录 Token 验证结果：

Token 验证成功: my_simple_token_123
收到短信: 10086 -> 【移动】验证码是 123456... (ID: 1)

---

切换回标准模式

将 token_only_mode 设置为 false 并重启服务：

{
  "security": {
    "token_only_mode": false
  }
}

./sms_receiverctl.sh restart

---

常见问题

Q: 纯 Token 模式安全吗？

A: 相比标准模式，纯 Token 模式安全性较低（没有签名保护）。建议在内网环境或使用 VPN 的场景下使用。

Q: 纯 Token 模式下还需要配置 secret 吗？

A: 不需要。secret 字段可以为空。

Q: 可以混合使用两种模式吗？

A: 不可以。一个服务实例要么是标准模式，要么是纯 Token 模式。

Q: TranspondSms 不发送签名会怎样？

A: 即使配置了标准模式，如果 TranspondSms 不发送签名，请求会失败（HTTP 403）。此时请使用纯 Token 模式。

---

代码变更

配置文件 (config.py)

# 新增配置项
TOKEN_ONLY_MODE = False

接收逻辑 (app.py)

if app.config['TOKEN_ONLY_MODE']:
    # 纯 Token 模式：只验证 token
    if not token_param:
        return jsonify({'error': '缺少 token 参数'}), 401

    # 查找 token 并验证
    for token_config in app.config['API_TOKENS']:
        if token_config.get('token') == token_param:
            token_valid = True
            break

    if not token_valid:
        return jsonify({'error': 'Token 无效'}), 401
else:
    # 标准 Token + 签名模式
    # ... 原有逻辑

---

相关文件

• config.py - 配置类定义
• config.json - 配置文件
• app.py - 主应用逻辑
• settings.html - 设置页面
• TOKEN_ONLY_MODE.md - 本文档