1d886ce68d
- 新增 TOKEN_ONLY_MODE 配置项，支持跳过 HMAC 签名验证 - 纯 Token 模式下只验证 token 参数，简化配置 - 添加 TOKEN_ONLY_MODE.md 详细文档 - 设置页面显示当前模式状态 - 更新 README.md 说明新功能 - config.example.json 添加 token_only_mode 配置项 适用于 TranspondSms 不支持签名的场景。
256 lines
6.7 KiB
Markdown
256 lines
6.7 KiB
Markdown
# 短信转发接收端
|
||
|
||
基于 TranspondSms Android APP 的短信转发接收后台
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **登录验证** - 需要登录才能查看和管理短信
|
||
- ✅ **Token/Secret 可选配置** - 支持在 config.json 中配置多个 API Token
|
||
- ✅ **接收 Android APP 转发的短信** - POST multipart/form-data
|
||
- ✅ **HMAC-SHA256 签名验证** - 可选的安全机制
|
||
- ✅ **纯 Token 认证模式** - 跳过签名验证，只验证 token（查看 [TOKEN_ONLY_MODE.md](TOKEN_ONLY_MODE.md)）
|
||
- ✅ **SQLite 数据库存储**
|
||
- ✅ **Web 管理界面** - 查看实时短信、日志、统计
|
||
- ✅ **时区支持** - 自动转换为本地时间（默认 Asia/Shanghai）
|
||
- ✅ **RESTful API 支持**
|
||
- ✅ **自动刷新** - 短信列表30秒自动刷新
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd /root/.openclaw/workspace/sms-receiver
|
||
|
||
# 启动服务
|
||
python3 app.py
|
||
```
|
||
|
||
服务将运行在 `http://127.0.0.1:9518`
|
||
|
||
## 配置说明
|
||
|
||
### config.json 配置文件
|
||
|
||
创建或编辑 `config.json` 文件：
|
||
|
||
```json
|
||
{
|
||
"server": {
|
||
"host": "0.0.0.0",
|
||
"port": 9518,
|
||
"debug": true
|
||
},
|
||
"security": {
|
||
"enabled": true,
|
||
"username": "admin",
|
||
"password": "admin123",
|
||
"session_lifetime": 3600,
|
||
"secret_key": "default_secret_key_change_me",
|
||
"sign_verify": true,
|
||
"sign_max_age": 3600000
|
||
},
|
||
"sms": {
|
||
"max_messages": 10000,
|
||
"auto_cleanup": true,
|
||
"cleanup_days": 30
|
||
},
|
||
"database": {
|
||
"path": "sms_receiver.db"
|
||
},
|
||
"timezone": "Asia/Shanghai",
|
||
"api_tokens": [
|
||
{
|
||
"name": "默认配置",
|
||
"token": "default_token",
|
||
"secret": "your_secret_here",
|
||
"enabled": true
|
||
},
|
||
{
|
||
"name": "设备1",
|
||
"token": "device1_token",
|
||
"secret": "device1_secret",
|
||
"enabled": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
| 项 | 说明 | 默认值 |
|
||
|----|------|--------|
|
||
| `security.enabled` | 是否启用登录验证 | true |
|
||
| `security.username` | 登录用户名 | admin |
|
||
| `security.password` | 登录密码 | admin123 |
|
||
| `security.session_lifetime` | 会话有效期（秒） | 3600 |
|
||
| `security.secret_key` | Flask 会话密钥 | - |
|
||
| `security.sign_verify` | 是否验证签名 | true |
|
||
| `security.sign_max_age` | 签名最大有效时间（毫秒） | 3600000 |
|
||
| `api_tokens` | API Token 配置列表 | - |
|
||
| `timezone` | 时区 | Asia/Shanghai |
|
||
|
||
### API Token 配置
|
||
|
||
每个 Token 配置包含：
|
||
|
||
- `name`: 配置名称（可选）
|
||
- `token`: Token 值，需要在 TranspondSms APP 中填写
|
||
- `secret`: 密钥，可选，填写后启用签名验证
|
||
- `enabled`: 是否启用此 Token
|
||
|
||
**注意**：
|
||
- Token 和 Secret 都是可选的
|
||
- 不填 Secret 时跳过签名验证
|
||
- 可以配置多个 Token 供多个设备使用
|
||
- enabled 为 false 时该 Token 不可用
|
||
|
||
## 配置 TranspondSms APP
|
||
|
||
在 Android APP 的"网页通知"配置中：
|
||
|
||
### 基础配置（无 Token）
|
||
|
||
- **Token (URL)**: `http://your-server-ip:9518/api/receive`
|
||
- **Secret**: 留空
|
||
|
||
### 使用 Token 配置
|
||
|
||
如果你在 `config.json` 中配置了 Token：
|
||
|
||
- **Token (URL)**: `http://your-server-ip:9518/api/receive`
|
||
- **Secret**: 根据你要使用的 Token 配置填写
|
||
|
||
**注意**：TranspondSms APP 的设置中，没有专门的 Token 字段。你需要通过以下方式传递 Token：
|
||
|
||
1. **方法一**：在 URL 中携带 Token
|
||
```
|
||
http://your-server-ip:9518/api/receive?token=your_token
|
||
```
|
||
|
||
2. **方法二**：在 Secret 字段中填写 `<token>|<secret>`
|
||
```
|
||
my_token|my_secret
|
||
```
|
||
然后修改代码解析这个格式（需自行实现）
|
||
|
||
**当前实现**：在短信接收时，TranspondSms APP 会发送一个 `token` 参数，系统会自动匹配对应的 secret。
|
||
|
||
目前 TranspondSms APP 的 Token 参数默认会放在请求的 query string 中：
|
||
```
|
||
POST /api/receive?token=your_token
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
如需传递多个设备的不同 Token，在 APP 中添加多个网页通知配置即可。
|
||
|
||
## 登录功能
|
||
|
||
### 默认登录信息
|
||
|
||
- **用户名**: admin
|
||
- **密码**: admin123
|
||
|
||
首次使用后，请立即修改 `config.json` 中的 `security.username` 和 `security.password`。
|
||
|
||
### 会话管理
|
||
|
||
- 会话默认有效期：1小时（3600秒）
|
||
- 超时后需要重新登录
|
||
- 可以通过 `security.session_lifetime` 调整
|
||
|
||
### 禁用登录
|
||
|
||
如果不需要登录验证，设置 `config.json`：
|
||
|
||
```json
|
||
{
|
||
"security": {
|
||
"enabled": false
|
||
}
|
||
}
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 接收短信
|
||
|
||
```
|
||
POST /api/receive?token=your_token
|
||
Content-Type: multipart/form-data
|
||
|
||
参数:
|
||
- token: API Token（可选，用于匹配 secret）
|
||
- from: 发送方手机号（必填）
|
||
- content: 短信内容（必填）
|
||
- timestamp: 时间戳（毫秒，可选）
|
||
- sign: 签名（可选）
|
||
- device: 设备信息（可选）
|
||
- sim: SIM 卡信息（可选）
|
||
```
|
||
|
||
### 查询短信列表（需要登录）
|
||
|
||
```
|
||
GET /api/messages?page=1&limit=20
|
||
```
|
||
|
||
### 查询统计信息（需要登录）
|
||
|
||
```
|
||
GET /api/statistics
|
||
```
|
||
|
||
## 时区配置
|
||
|
||
系统默认使用 `Asia/Shanghai` 时区（UTC+8）。
|
||
|
||
在 `config.json` 中修改时区：
|
||
|
||
```json
|
||
{
|
||
"timezone": "America/New_York"
|
||
}
|
||
```
|
||
|
||
支持的时区名称参考：https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||
|
||
## 安全建议
|
||
|
||
1. **修改默认密码**：首次使用后立即修改登录密码
|
||
2. **修改 Secret Key**：修改 `security.secret_key` 为随机字符串
|
||
3. **使用 HTTPS**：生产环境建议配置反向代理（Nginx + Let's Encrypt）
|
||
4. **启用签名验证**：设置 Token 的 secret 启用签名，防止伪造请求
|
||
5. **会话超时**：设置合理的 `session_lifetime`
|
||
|
||
## 默认配置说明
|
||
|
||
| 配置 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| 端口 | 9518 | Web 服务监听端口 |
|
||
| 数据库 | sms_receiver.db | SQLite 数据库文件 |
|
||
| 时区 | Asia/Shanghai | 武汉时间 UTC+8 |
|
||
| 会话有效期 | 3600 秒 | 1小时 |
|
||
| 最多保留短信 | 10000 条 | 超过自动清理 |
|
||
| 自动刷新间隔 | 30 秒 | SMS 列表自动刷新时间 |
|
||
|
||
## 项目文件
|
||
|
||
```
|
||
/root/.openclaw/workspace/sms-receiver/
|
||
├── app.py # Flask 主应用
|
||
├── config.json # 配置文件（需创建）
|
||
├── config.py # 配置加载器
|
||
├── database.py # SQLite 数据库模型
|
||
├── sign_verify.py # HMAC-SHA256 签名验证
|
||
├── requirements.txt # 依赖包
|
||
├── templates/ # HTML 模板
|
||
│ ├── login.html # 登录页面
|
||
│ ├── index.html # 主页（短信列表）
|
||
│ ├── message_detail.html # 短信详情
|
||
│ ├── logs.html # 接收日志
|
||
│ ├── statistics.html # 统计信息
|
||
│ └── error.html # 错误页面
|
||
└── README.md # 本文档
|
||
```
|
||
|