SmsReceiver-go

短信转发接收端 Go 版本 - 基于 Flask 版本的完整重写，生产级优化

✨ 功能特性

核心功能

• ✅ 短信接收 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 下载对应平台的二进制文件:

# 赋予执行权限
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

# 初始化配置
make init

# 编译
make build

# 运行
make run

方式 3: Docker 部署

使用 Docker Hub 镜像（推荐）:

# 拉取镜像
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

从源码构建:

# 构建镜像
make docker-build

# 运行容器
make docker-run

# 查看日志
make docker-logs

或使用 docker-compose:

docker-compose up -d

使用生产环境 Docker Compose（推荐）:

# 复制配置文件
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: 从源码编译

go build -o sms-receiver main.go

⚙️ 配置

初始化配置:

make init

或手动创建 config.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

生成密码哈希（推荐）

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 信息（可选）

响应:

{
  "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: 内容或号码搜索

响应:

{
  "success": true,
  "data": [...],
  "total": 100,
  "page": 1,
  "limit": 20
}

需要登录认证。

3. 获取统计信息

GET /api/statistics 或 GET /api/v1/statistics

响应:

{
  "success": true,
  "data": {
    "total": 100,
    "today": 10,
    "week": 50,
    "verified": 80,
    "unverified": 20
  }
}

需要登录认证。

4. 健康检查

GET /health

响应:

{
  "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:

[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

管理命令:

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:

./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  # 实时查看日志

📚 文档

• 开发文档 - 详细的开发指南和 API 文档
• 优化报告 - 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 仓库
• 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 版本功能