b29a7bbc63
- 更新版本标签从 v2.0.0 到 v2.0.2 - 添加生产环境 Docker Compose 部署说明 - 新增 v2.0.2 详细更新日志 - 添加 Docker Hub 镜像标签说明
559 lines
14 KiB
Markdown
559 lines
14 KiB
Markdown
# SmsReceiver-go
|
||
|
||
> 短信转发接收端 Go 版本 - 基于 Flask 版本的完整重写，生产级优化
|
||
|
||
[](https://golang.org/)
|
||
[](LICENSE)
|
||
[](https://gitea.king.nyc.mn/openclaw/SmsReceiver-go/releases/tag/v2.0.2)
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 核心功能
|
||
- ✅ 短信接收 API (支持 TranspondSms Android APP)
|
||
- ✅ 登录验证与会话管理（支持密码哈希）
|
||
- ✅ 短信列表展示（分页、搜索、筛选）
|
||
- ✅ 统计信息（总数、今日、本周、签名验证）
|
||
- ✅ 接收日志查看
|
||
- ✅ 短信详情查看
|
||
- ✅ 时区转换（Asia/Shanghai）
|
||
- ✅ 签名验证（HMAC-SHA256）
|
||
- ✅ 多 Token 管理
|
||
|
||
### v2.0.0 新增特性
|
||
- 🔐 **密码哈希支持**: 使用 bcrypt 存储密码，提升安全性
|
||
- 🔄 **数据库事务**: 消息和日志原子性存储，确保数据一致性
|
||
- 🔍 **参数化查询**: 修复潜在 SQL 注入风险
|
||
- ✅ **配置验证**: 启动时自动检查配置完整性
|
||
- 🏥 **增强健康检查**: `/health` 端点返回详细状态信息
|
||
- 📦 **API 版本控制**: 支持 `/api/v1/*` 和旧版 API
|
||
- 🛡️ **认证中间件**: 代码复用和权限控制
|
||
- ⏰ **Cron 定时任务**: 使用 `robfig/cron` 替代 sleep
|
||
- 💾 **连接池优化**: 数据库连接池配置
|
||
- 🚀 **Docker 支持**: Dockerfile + docker-compose.yml
|
||
- 📝 **Makefile**: 便捷构建命令
|
||
- 📚 **完整文档**: 开发文档 + 优化报告
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **Web 框架**: Gorilla Mux
|
||
- **数据库**: SQLite3 (mattn/go-sqlite3)
|
||
- **模板引擎**: Go html/template
|
||
- **认证**: Cookie-based session (gorilla/sessions)
|
||
- **密码哈希**: bcrypt (golang.org/x/crypto/bcrypt)
|
||
- **定时任务**: robfig/cron
|
||
- **配置管理**: Viper
|
||
- **语言**: Go 1.21+
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
SmsReceiver-go/
|
||
├── main.go # 入口文件
|
||
├── config.yaml # 配置文件
|
||
├── config.example.yaml # 配置示例
|
||
├── Makefile # 构建脚本
|
||
├── Dockerfile # Docker 镜像
|
||
├── docker-compose.yml # Docker Compose
|
||
├── DEVELOPMENT.md # 开发文档
|
||
├── OPTIMIZATION_REPORT.md # 优化报告
|
||
├── auth/ # 认证模块
|
||
│ ├── auth.go # 认证逻辑
|
||
│ └── password.go # 密码验证（bcrypt）
|
||
├── config/ # 配置加载
|
||
│ ├── config.go # 配置管理
|
||
│ └── constants.go # 常量定义
|
||
├── database/ # 数据库操作
|
||
│ └── database.go # CRUD + 事务
|
||
├── handlers/ # HTTP 处理器
|
||
│ ├── handlers.go # 主处理函数
|
||
│ ├── middleware.go # 认证中间件
|
||
│ └── health.go # 健康检查
|
||
├── models/ # 数据模型
|
||
│ └── message.go # 数据结构
|
||
├── sign/ # 签名验证
|
||
│ └── sign.go # HMAC-SHA256
|
||
├── static/ # 静态资源
|
||
├── templates/ # HTML 模板
|
||
└── tools/ # 工具脚本
|
||
└── password_hash.go # 密码哈希生成
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式 1: 使用预编译二进制（推荐）
|
||
|
||
从 [Release](https://gitea.king.nyc.mn/openclaw/SmsReceiver-go/releases) 下载对应平台的二进制文件:
|
||
|
||
```bash
|
||
# 赋予执行权限
|
||
chmod +x sms-receiver-v2
|
||
|
||
# 查看版本信息
|
||
./sms-receiver-v2 --version
|
||
|
||
# 运行
|
||
./sms-receiver-v2
|
||
```
|
||
|
||
版本输出示例:
|
||
```
|
||
SmsReceiver-go v2.0.0
|
||
Version: v2.0.0
|
||
Build Env: prod
|
||
Build Time: 2026-02-08 19:18:33
|
||
Git Commit: 28f2c2a
|
||
Go Version: go1.24.4
|
||
Repository: https://gitea.king.nyc.mn/openclaw/SmsReceiver-go
|
||
```
|
||
|
||
### 方式 2: 使用 Makefile
|
||
|
||
```bash
|
||
# 初始化配置
|
||
make init
|
||
|
||
# 编译
|
||
make build
|
||
|
||
# 运行
|
||
make run
|
||
```
|
||
|
||
### 方式 3: Docker 部署
|
||
|
||
**使用 Docker Hub 镜像（推荐）**:
|
||
|
||
```bash
|
||
# 拉取镜像
|
||
docker pull ouaone/sms-receiver-go:latest
|
||
|
||
# 运行容器
|
||
docker run -d \
|
||
--name sms-receiver-go \
|
||
-p 28001:28001 \
|
||
-v $(pwd)/config.yaml:/app/config.yaml:ro \
|
||
-v $(pwd)/data:/app/data \
|
||
--restart unless-stopped \
|
||
ouaone/sms-receiver-go:latest
|
||
```
|
||
|
||
**从源码构建**:
|
||
|
||
```bash
|
||
# 构建镜像
|
||
make docker-build
|
||
|
||
# 运行容器
|
||
make docker-run
|
||
|
||
# 查看日志
|
||
make docker-logs
|
||
```
|
||
|
||
或使用 docker-compose:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
**使用生产环境 Docker Compose（推荐）**:
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
cp config.example.yaml config.yaml
|
||
|
||
# 启动服务
|
||
docker compose -f docker-compose.production.yml up -d
|
||
|
||
# 查看日志
|
||
docker compose -f docker-compose.production.yml logs -f
|
||
|
||
# 停止服务
|
||
docker compose -f docker-compose.production.yml down
|
||
```
|
||
|
||
**Docker Hub**: https://hub.docker.com/r/ouaone/sms-receiver-go
|
||
|
||
**可用镜像标签**:
|
||
- `ouaone/sms-receiver-go:latest` - 最新版本（推荐）
|
||
- `ouaone/sms-receiver-go:v2.0.2` - v2.0.2 稳定版本
|
||
- `ouaone/sms-receiver-go:v2.0.1` - v2.0.1 版本
|
||
- `ouaone/sms-receiver-go:v2.0.0` - v2.0.0 版本
|
||
|
||
### 方式 4: 从源码编译
|
||
|
||
```bash
|
||
go build -o sms-receiver main.go
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
初始化配置:
|
||
```bash
|
||
make init
|
||
```
|
||
|
||
或手动创建 `config.yaml`:
|
||
|
||
```yaml
|
||
app:
|
||
name: "SmsReceiver-go"
|
||
version: "2.0.0"
|
||
|
||
server:
|
||
host: "127.0.0.1" # 监听地址
|
||
port: 28001 # 监听端口
|
||
debug: false # 调试模式
|
||
|
||
security:
|
||
enabled: true # 启用登录验证
|
||
username: "admin" # 管理员用户名
|
||
password: "admin123" # 管理员密码（明文）
|
||
# password_hash: "$2a$12$..." # 推荐：使用 bcrypt 哈希
|
||
session_lifetime: 3600 # 会话有效期（秒）
|
||
secret_key: "your-secret-key-at-least-16-characters" # 会话加密密钥
|
||
sign_verify: true # 启用签名验证
|
||
sign_max_age: 300000 # 签名有效期（毫秒）
|
||
|
||
database:
|
||
path: "sms_receiver_go.db" # SQLite 数据库文件
|
||
|
||
timezone: "Asia/Shanghai" # 时区
|
||
|
||
sms:
|
||
max_messages: 0 # 最大保存消息数（0=不限制）
|
||
auto_cleanup: false # 自动清理旧消息
|
||
cleanup_days: 90 # 保留天数
|
||
|
||
api_tokens:
|
||
- name: "default"
|
||
token: "default_token"
|
||
secret: "" # secret 为空时不验证签名
|
||
enabled: true
|
||
```
|
||
|
||
### 生成密码哈希（推荐）
|
||
|
||
```bash
|
||
go run tools/password_hash.go your_password
|
||
|
||
# 或使用 Makefile
|
||
make password
|
||
```
|
||
|
||
将输出的哈希值配置到 `security.password_hash` 字段。
|
||
|
||
## 🌐 访问服务
|
||
|
||
服务启动后访问:
|
||
|
||
- 首页（短信列表）: http://localhost:28001/
|
||
- 统计信息: http://localhost:28001/statistics
|
||
- 接收日志: http://localhost:28001/logs
|
||
- 健康检查: http://localhost:28001/health
|
||
|
||
默认登录:
|
||
- 用户名: `admin`
|
||
- 密码: `admin123`（或你设置的密码）
|
||
|
||
## 📡 API 接口
|
||
|
||
### 1. 接收短信
|
||
|
||
```
|
||
POST /api/receive 或 POST /api/v1/receive
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
**参数**:
|
||
- `from` (必需): 发送方号码
|
||
- `content` (必需): 短信内容
|
||
- `timestamp`: 短信时间戳（毫秒级，可选）
|
||
- `sign`: 签名值（根据配置验证）
|
||
- `token`: API Token（用于签名验证）
|
||
- `device`: 设备信息（可选）
|
||
- `sim`: SIM 信息（可选）
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "短信已接收",
|
||
"message_id": 123
|
||
}
|
||
```
|
||
|
||
### 2. 获取消息列表
|
||
|
||
```
|
||
GET /api/messages 或 GET /api/v1/messages?page=1&limit=20&from=&search=
|
||
```
|
||
|
||
**参数**:
|
||
- `page`: 页码（从1开始）
|
||
- `limit`: 每页数量（最大100）
|
||
- `from`: 发送方号码筛选
|
||
- `search`: 内容或号码搜索
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"limit": 20
|
||
}
|
||
```
|
||
|
||
需要登录认证。
|
||
|
||
### 3. 获取统计信息
|
||
|
||
```
|
||
GET /api/statistics 或 GET /api/v1/statistics
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"total": 100,
|
||
"today": 10,
|
||
"week": 50,
|
||
"verified": 80,
|
||
"unverified": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
需要登录认证。
|
||
|
||
### 4. 健康检查
|
||
|
||
```
|
||
GET /health
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"app_name": "SmsReceiver-go",
|
||
"version": "2.0.0",
|
||
"database": "ok",
|
||
"total_messages": 100,
|
||
"uptime": "1h23m45s"
|
||
}
|
||
```
|
||
|
||
## 🗄️ 数据库
|
||
|
||
**独立数据库**: `sms_receiver_go.db`
|
||
|
||
### 表结构
|
||
|
||
**sms_messages** - 短信存储:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INTEGER | 主键，自增 |
|
||
| from_number | TEXT | 发送方号码 |
|
||
| content | TEXT | 短信内容 |
|
||
| timestamp | INTEGER | 短信时间戳（毫秒级） |
|
||
| device_info | TEXT | 设备信息 |
|
||
| sim_info | TEXT | SIM 信息 |
|
||
| sign_verified | INTEGER | 签名验证结果（0/1） |
|
||
| ip_address | TEXT | 客户端 IP |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
|
||
**receive_logs** - 接收日志:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INTEGER | 主键，自增 |
|
||
| from_number | TEXT | 发送方号码 |
|
||
| content | TEXT | 短信内容 |
|
||
| timestamp | INTEGER | 短信时间戳（毫秒级） |
|
||
| sign | TEXT | 签名值 |
|
||
| sign_valid | INTEGER | 签名验证结果（0/1） |
|
||
| ip_address | TEXT | 客户端 IP |
|
||
| status | TEXT | 状态（success/error） |
|
||
| error_message | TEXT | 错误信息 |
|
||
| created_at | TIMESTAMP | 创建时间 |
|
||
|
||
## 📊 性能对比
|
||
|
||
### 与 Python 版本对比
|
||
|
||
| 特性 | Python 版本 | Go 版本 (v2.0.0) |
|
||
|------|------------|------------------|
|
||
| 运行方式 | Python 解释器 | 编译二进制 |
|
||
| 部署大小 | ~50KB (源码) | ~6MB (二进制) |
|
||
| 启动速度 | ~100ms | ~10ms |
|
||
| 内存占用 | ~30MB | ~15MB |
|
||
| 并发处理 | GIL 限制 | 原生协程 |
|
||
| 数据库 | `sms_receiver.db` | `sms_receiver_go.db` |
|
||
| 密码存储 | 明文 | bcrypt 哈希 |
|
||
| 事务支持 | ❌ | ✅ |
|
||
| Docker 支持 | ❌ | ✅ |
|
||
|
||
### 优化指标
|
||
|
||
- **代码质量**: ✅ 30 项优化建议全部完成
|
||
- **安全性**: ✅ 事务、哈希、验证全面强化
|
||
- **性能**: ✅ 连接池、索引、查询优化
|
||
- **可维护性**: ✅ 完整文档、常量、中间件
|
||
- **部署便利**: ✅ Makefile、Docker、Systemd
|
||
|
||
## 🔧 管理脚本
|
||
|
||
### Systemd 服务
|
||
|
||
创建 `/etc/systemd/system/sms-receiver-go.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=SmsReceiver-go SMS Service
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=root
|
||
WorkingDirectory=/root/.openclaw/workspace/SmsReceiver-go
|
||
ExecStart=/root/.openclaw/workspace/SmsReceiver-go/sms-receiver-v2
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
管理命令:
|
||
```bash
|
||
systemctl daemon-reload
|
||
systemctl enable sms-receiver-go # 开机自启
|
||
systemctl start sms-receiver-go # 启动
|
||
systemctl stop sms-receiver-go # 停止
|
||
systemctl restart sms-receiver-go # 重启
|
||
systemctl status sms-receiver-go # 状态
|
||
```
|
||
|
||
### 控制脚本
|
||
|
||
使用 `sms-receiver-go-ctl.sh`:
|
||
|
||
```bash
|
||
./sms-receiver-go-ctl.sh start # 启动服务
|
||
./sms-receiver-go-ctl.sh stop # 停止服务
|
||
./sms-receiver-go-ctl.sh restart # 重启服务
|
||
./sms-receiver-go-ctl.sh status # 查看状态
|
||
./sms-receiver-go-ctl.sh log # 查看日志
|
||
./sms-receiver-go-ctl.sh logtail # 实时查看日志
|
||
```
|
||
|
||
## 📚 文档
|
||
|
||
- [开发文档](DEVELOPMENT.md) - 详细的开发指南和 API 文档
|
||
- [优化报告](OPTIMIZATION_REPORT.md) - v2.0.0 优化详情和变更记录
|
||
|
||
## 🔒 安全建议
|
||
|
||
1. **使用强密码**: 至少12位，包含大小写字母、数字和特殊符号
|
||
2. **使用密码哈希**: 运行 `tools/password_hash.go` 生成 bcrypt 哈希
|
||
3. **配置签名验证**: 启用 `sign_verify` 并为 token 配置 secret
|
||
4. **限制访问**: 通过防火墙或反向代理限制访问
|
||
5. **定期备份**: 定期备份数据库文件
|
||
6. **更新依赖**: 定期运行 `go get -u ./...`
|
||
|
||
## ⚠️ 重要说明
|
||
|
||
- 本版本与 Python 版本使用**独立的数据库文件**
|
||
- 数据不互通，属于完全独立的实现
|
||
- 功能已对齐 Python 版本所有核心特性
|
||
- API 同时支持 `/api/*` 和 `/api/v1/*`，完全兼容
|
||
|
||
## 📜 许可证
|
||
|
||
MIT License
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 📦 下载
|
||
|
||
- [Gitea 仓库](https://gitea.king.nyc.mn/openclaw/SmsReceiver-go)
|
||
- [Releases](https://gitea.king.nyc.mn/openclaw/SmsReceiver-go/releases)
|
||
|
||
## 📝 更新日志
|
||
|
||
### [v2.0.2] - 2026-02-12
|
||
|
||
#### 🐛 Bug 修复
|
||
- ✅ 修复容器启动时找不到模板文件导致崩溃的问题
|
||
- ✅ 修复 Dockerfile 缺少 `templates/` 和 `static/` 目录复制
|
||
|
||
#### 📦 Docker 改进
|
||
- ✅ 完善多阶段构建，正确复制运行时所需文件
|
||
- ✅ 新增 `docker-compose.production.yml` 生产环境配置
|
||
- ✅ 预编译镜像推送到 Docker Hub (ouaone/sms-receiver-go:v2.0.2)
|
||
- ✅ 验证容器可正常启动并通过健康检查
|
||
|
||
#### 📚 文档
|
||
- ✅ 更新 README.md 镜像拉取说明
|
||
- ✅ 更新版本标签显示
|
||
|
||
#### 🔧 兼容性
|
||
- ✅ 与 v2.0.1 功能完全兼容
|
||
- ✅ 数据库无需迁移
|
||
- ✅ 配置文件无需变更
|
||
|
||
### [v2.0.1] - 2026-02-08
|
||
|
||
#### 🐛 Bug 修复
|
||
- ✅ 修复登录会话创建失败问题（`securecookie: the value is not valid`）
|
||
- ✅ 回退密钥处理逻辑确保向后兼容性
|
||
- ✅ 改进会话初始化错误处理
|
||
|
||
#### 🔧 兼容性
|
||
- ✅ 与 v2.0.0 Cookie 完全兼容，无需清除
|
||
- ✅ 支持 `/api/v1/*` 和 `/api/*` 路由
|
||
- ✅ 密钥长度不足时仅记录警告
|
||
|
||
### [v2.0.0] - 2026-02-08
|
||
|
||
#### 🔴 高优先级 (6项)
|
||
- ✅ 数据库事务支持 (确保消息和日志一致性)
|
||
- ✅ SQL 注入修复 (参数化查询)
|
||
- ✅ 配置验证启动时自动检查
|
||
- ✅ 会话密钥强化 (长度验证)
|
||
- ✅ 签名验证增强 (详细记录验证过程)
|
||
- ✅ 密码哈希支持 (bcrypt)
|
||
|
||
#### 🟡 中优先级 (15项)
|
||
- ✅ 连接池配置 (MaxOpenConns, MaxIdleConns)
|
||
- ✅ 查询优化 (范围查询, 索引)
|
||
- ✅ 健康检查增强 (/health 端点)
|
||
- ✅ API 版本控制 (/api/v1/*)
|
||
- ✅ 认证中间件 (RequireAuth, RequireAPIAuth)
|
||
- ✅ 定时任务优化 (robfig/cron)
|
||
- ✅ 配置文件示例 (config.example.yaml)
|
||
- ✅ 常量定义 (config/constants.go)
|
||
- ✅ 开发文档 (DEVELOPMENT.md)
|
||
|
||
#### 🟢 低优先级 (9项)
|
||
- ✅ Docker 支持 (Dockerfile, docker-compose.yml)
|
||
- ✅ Makefile 构建脚本
|
||
- ✅ 优化报告 (OPTIMIZATION_REPORT.md)
|
||
- ✅ 密码哈希工具 (tools/password_hash.go)
|
||
- ✅ 单元测试架构准备
|
||
|
||
#### 📦 文件变更
|
||
- 新增文件: 14 个
|
||
- 代码行数: +1523 / -101
|
||
|
||
### [v1.0.0] - 2026-02-08
|
||
|
||
- ✅ 初始版本发布
|
||
- ✅ 完整功能实现
|
||
- ✅ 对齐 Python 版本功能
|