Initial commit: SMS Receiver Web Service
Features: - Receive SMS from TranspondSms Android APP - HMAC-SHA256 signature verification (optional) - SQLite database storage - Web UI with login authentication - Multiple API tokens support - Timezone conversion (Asia/Shanghai) - Search, filter, and statistics - Auto refresh and session management Tech Stack: - Flask 3.0 - SQLite database - HTML5/CSS3 responsive design
This commit is contained in:
OpenClaw Agent
254
README.md
Normal file
254
README.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 短信转发接收端
|
||||
|
||||
基于 TranspondSms Android APP 的短信转发接收后台
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ **登录验证** - 需要登录才能查看和管理短信
|
||||
- ✅ **Token/Secret 可选配置** - 支持在 config.json 中配置多个 API Token
|
||||
- ✅ **接收 Android APP 转发的短信** - POST multipart/form-data
|
||||
- ✅ **HMAC-SHA256 签名验证** - 可选的安全机制
|
||||
- ✅ **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 # 本文档
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user