226 lines
5.2 KiB
Markdown
226 lines
5.2 KiB
Markdown
# SmsReceiver Worker（前后端分离版）
|
||
|
||
> 将 SmsReceiver-go 迁移到 Cloudflare Worker + Pages + D1 的 **Worker 化**实现。
|
||
> 目标是把「短信接收 API + 管理界面」拆分为独立的 API 服务与静态前端，提升部署弹性、跨域能力与运维简洁度。
|
||
|
||
## 开发目的
|
||
|
||
1. **Worker 化**：摆脱传统服务器进程部署，使用 Cloudflare Worker 作为 API 运行环境。
|
||
2. **前后端分离**：前端使用 Pages 静态托管，API 单独在 Worker 上运行，天然解耦。
|
||
3. **低运维成本**：无需自建数据库与运行时，D1 提供托管 SQLite 体验。
|
||
4. **部署可重复**：通过 wrangler + 配置文件完成快速部署与迁移。
|
||
5. **兼容原协议**：保留原 SmsReceiver-go 的字段、签名逻辑与接入方式。
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
[TranspondSms / 客户端]
|
||
|
|
||
| HTTP POST (token/sign)
|
||
v
|
||
Cloudflare Worker (Hono)
|
||
|
|
||
| D1 (SQLite)
|
||
v
|
||
数据持久化 + 管理 API
|
||
|
||
Cloudflare Pages (静态 UI)
|
||
|
|
||
| API_BASE 指向 Worker
|
||
v
|
||
管理后台
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── worker/ # Cloudflare Worker API (Hono + D1)
|
||
│ ├── src/ # API 代码
|
||
│ ├── schema.sql # D1 表结构
|
||
│ ├── migrate_sqlite_to_d1.py # 旧 sqlite 数据迁移脚本
|
||
│ ├── wrangler.toml # Worker 配置
|
||
│ └── package.json
|
||
└── pages/public/ # Cloudflare Pages 静态管理 UI
|
||
├── index.html
|
||
├── app.js
|
||
└── app.css
|
||
```
|
||
|
||
---
|
||
|
||
# 关键设计说明（详细解读）
|
||
|
||
## 1. 前后端分离特性
|
||
|
||
- **API** 与 **UI** 完全解耦。
|
||
- UI 仅为静态资源（HTML/JS/CSS），部署到 Pages；
|
||
- API 只处理数据与鉴权，部署到 Worker；
|
||
- UI 通过 `API_BASE` 指向后端，无需在同域运行。
|
||
|
||
**优势**：
|
||
- UI 部署独立、回滚简单。
|
||
- API 可单独扩容/升级。
|
||
- 适配多域名、CDN 就近访问。
|
||
|
||
## 2. 数据层：D1 (SQLite)
|
||
|
||
- 使用 Cloudflare D1 替代本地 SQLite。
|
||
- 表结构与原 Go 版本保持一致：`sms_messages`、`receive_logs`。
|
||
- 使用 SQL 语句创建表，便于版本迁移与重建。
|
||
|
||
## 3. 兼容原接收协议
|
||
|
||
API 保持字段一致：
|
||
|
||
- `from` / `content` / `timestamp` / `sign` / `device` / `sim` / `token`
|
||
|
||
签名逻辑保持与 Go 版一致：
|
||
|
||
```
|
||
stringToSign = `${timestamp}\n${secret}`
|
||
sign = HMAC-SHA256(stringToSign) -> Base64 -> URL encode
|
||
```
|
||
|
||
## 4. 认证与登录
|
||
|
||
- 使用 `ADMIN_USER` + `ADMIN_PASS_HASH` 登录。
|
||
- 登录密码使用 HMAC-SHA256 生成 hash（与 SESSION_SECRET 绑定）。
|
||
- Cookie 采用 `SameSite=None; Secure`，解决跨域登录。
|
||
|
||
## 5. 查询能力
|
||
|
||
- 支持 `from`、时间区间筛选（start_ts / end_ts）。
|
||
- UI 默认显示当前月，并提供“本月 / 上月 / 全部”。
|
||
- 移动端适配：表格横向滚动，筛选区可滚动。
|
||
|
||
---
|
||
|
||
# 部署指南
|
||
|
||
## 1) 部署 Worker API
|
||
|
||
```bash
|
||
cd worker
|
||
npm install
|
||
```
|
||
|
||
编辑 `wrangler.toml`：
|
||
- `database_id`
|
||
- vars: `ADMIN_USER` / `ADMIN_PASS_HASH` / `SESSION_SECRET` / `HMAC_SECRET`
|
||
|
||
初始化 D1 表结构：
|
||
```bash
|
||
npx wrangler d1 execute smsreceiver --file=schema.sql
|
||
```
|
||
|
||
本地调试：
|
||
```bash
|
||
npx wrangler dev
|
||
```
|
||
|
||
发布：
|
||
```bash
|
||
npx wrangler deploy
|
||
```
|
||
|
||
---
|
||
|
||
## 2) 部署 Pages UI
|
||
|
||
将 `pages/public/` 作为静态站点部署到 Cloudflare Pages。
|
||
|
||
修改 `pages/public/app.js`：
|
||
```js
|
||
const API_BASE = "https://你的-worker域名"
|
||
```
|
||
|
||
部署完成后即可访问管理后台。
|
||
|
||
---
|
||
|
||
## 3) 密码 hash 生成
|
||
|
||
当前登录逻辑：`HMAC_SHA256(password, SESSION_SECRET)`
|
||
|
||
生成方式：
|
||
```bash
|
||
node -e "const c=require('crypto');console.log(c.createHmac('sha256','YOUR_SESSION_SECRET').update('YOUR_PASSWORD').digest('hex'))"
|
||
```
|
||
|
||
将结果写入 `ADMIN_PASS_HASH`。
|
||
|
||
---
|
||
|
||
## 4) 从旧 SQLite 迁移到 D1
|
||
|
||
脚本：`worker/migrate_sqlite_to_d1.py`
|
||
|
||
需要环境变量：
|
||
- `CF_ACCOUNT_ID`
|
||
- `CF_API_TOKEN`
|
||
- `D1_DATABASE_ID`
|
||
- `SQLITE_PATH`（默认 `sms_receiver_go.db`）
|
||
|
||
运行：
|
||
```bash
|
||
cd worker
|
||
python3 migrate_sqlite_to_d1.py
|
||
```
|
||
|
||
---
|
||
|
||
# 使用指南
|
||
|
||
## 1. 客户端上报短信
|
||
|
||
`POST /api/receive`
|
||
|
||
字段：
|
||
- `from`：发件人
|
||
- `content`：短信正文
|
||
- `timestamp`：Unix 时间戳
|
||
- `token`：API Token
|
||
- `sign`：签名
|
||
- `device` / `sim`：设备与卡槽信息（可选）
|
||
|
||
## 2. 登录管理后台
|
||
|
||
- 访问 Pages URL
|
||
- 输入 `ADMIN_USER` / 密码
|
||
- 可查看短信列表、详情、日志、筛选记录
|
||
|
||
## 3. 管理 API 端点示例
|
||
|
||
- `POST /api/auth/login`
|
||
- `POST /api/auth/logout`
|
||
- `GET /api/auth/me`
|
||
- `GET /api/messages`
|
||
- `GET /api/messages/:id`
|
||
- `GET /api/logs`
|
||
- `GET /api/stats`
|
||
- `GET /api/health`
|
||
|
||
---
|
||
|
||
# 本地开发流程（推荐）
|
||
|
||
1. 在 `worker/` 中使用 `wrangler dev` 启动本地 API。
|
||
2. 在 `pages/public/` 中修改前端并直接用静态服务器预览。
|
||
3. API_BASE 指向本地 API 或临时 Worker 域名。
|
||
4. 测试完成后分别部署 Worker 与 Pages。
|
||
|
||
---
|
||
|
||
# 注意事项
|
||
|
||
- UI 与 API 部署后跨域必须使用 `SameSite=None; Secure` Cookie。
|
||
- D1 为 SQLite 兼容，但限制与云端事务特性不同于本地。
|
||
- API Token 与 HMAC 密钥要妥善保管。
|
||
|
||
---
|
||
|
||
# License
|
||
|
||
内部项目使用，按需扩展。
|