1d886ce68d
- 新增 TOKEN_ONLY_MODE 配置项，支持跳过 HMAC 签名验证 - 纯 Token 模式下只验证 token 参数，简化配置 - 添加 TOKEN_ONLY_MODE.md 详细文档 - 设置页面显示当前模式状态 - 更新 README.md 说明新功能 - config.example.json 添加 token_only_mode 配置项 适用于 TranspondSms 不支持签名的场景。
238 lines
4.6 KiB
Markdown
238 lines
4.6 KiB
Markdown
# 纯 Token 模式配置指南
|
||
|
||
## 功能说明
|
||
|
||
纯 Token 模式（Token Only Mode）允许短信转发接收端**只验证 token 参数**，跳过 HMAC-SHA256 签名验证。
|
||
|
||
### 适用场景
|
||
|
||
- TranspondSms APP 不支持或不需要 HMAC 签名
|
||
- 快速测试/开发环境
|
||
- 简化配置，降低部署复杂度
|
||
|
||
### 安全性建议
|
||
|
||
- **生产环境建议使用标准模式**（Token + HMAC 签名）
|
||
- 纯 Token 模式下，请确保网络环境可信（内网、VPN）
|
||
- 定期更换 token
|
||
|
||
---
|
||
|
||
## 配置方法
|
||
|
||
### 1. 编辑 `config.json`
|
||
|
||
```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. 重启服务
|
||
|
||
```bash
|
||
./sms_receiverctl.sh restart
|
||
```
|
||
|
||
或使用 systemd：
|
||
|
||
```bash
|
||
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 模式）
|
||
|
||
```json
|
||
{
|
||
"error": "Token 无效"
|
||
}
|
||
```
|
||
|
||
返回：HTTP 401
|
||
|
||
### 缺少 Token（纯 Token 模式）
|
||
|
||
```json
|
||
{
|
||
"error": "缺少 token 参数（纯 Token 模式已启用）"
|
||
}
|
||
```
|
||
|
||
返回：HTTP 401
|
||
|
||
---
|
||
|
||
## 日志记录
|
||
|
||
服务会在日志中记录 Token 验证结果：
|
||
|
||
```
|
||
Token 验证成功: my_simple_token_123
|
||
收到短信: 10086 -> 【移动】验证码是 123456... (ID: 1)
|
||
```
|
||
|
||
---
|
||
|
||
## 切换回标准模式
|
||
|
||
将 `token_only_mode` 设置为 `false` 并重启服务：
|
||
|
||
```json
|
||
{
|
||
"security": {
|
||
"token_only_mode": false
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
./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`)
|
||
|
||
```python
|
||
# 新增配置项
|
||
TOKEN_ONLY_MODE = False
|
||
```
|
||
|
||
### 接收逻辑 (`app.py`)
|
||
|
||
```python
|
||
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` - 本文档
|