# SmsReceiver-go

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

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-2.0.0-blue.svg)](https://gitea.king.nyc.mn/openclaw/SmsReceiver-go)

## ✨ 功能特性

### 核心功能
- ✅ 短信接收 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: 使用预编译二进制（推荐）

```bash
# 赋予执行权限
chmod +x sms-receiver-v2

# 运行
./sms-receiver-v2
```

### 方式 2: 使用 Makefile

```bash
# 初始化配置
make init

# 编译
make build

# 运行
make run
```

### 方式 3: Docker 部署

```bash
# 构建镜像
make docker-build

# 运行容器
make docker-run

# 查看日志
make docker-logs
```

或使用 docker-compose:
```bash
docker-compose up -d
```

### 方式 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.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 版本功能