chore: restructure repo as worker collection
This commit is contained in:
OpenClaw Agent
228
README.md
228
README.md
@@ -1,220 +1,26 @@
|
||||
# SmsReceiver Worker（前后端分离版）
|
||||
# toworker - Worker 化项目合集
|
||||
|
||||
> 将 SmsReceiver-go 迁移到 Cloudflare Worker + Pages + D1 的 **Worker 化**实现。
|
||||
> 目标是把「短信接收 API + 管理界面」拆分为独立的 API 服务与静态前端，提升部署弹性、跨域能力与运维简洁度。
|
||||
> 统一收纳所有 “Worker 化” 项目，按子目录拆分。
|
||||
|
||||
## 开发目的
|
||||
## 子项目列表
|
||||
|
||||
1. **Worker 化**：摆脱传统服务器进程部署，使用 Cloudflare Worker 作为 API 运行环境。
|
||||
2. **前后端分离**：前端使用 Pages 静态托管，API 单独在 Worker 上运行，天然解耦。
|
||||
3. **低运维成本**：无需自建数据库与运行时，D1 提供托管 SQLite 体验。
|
||||
4. **部署可重复**：通过 wrangler + 配置文件完成快速部署与迁移。
|
||||
5. **兼容原协议**：保留原 SmsReceiver-go 的字段、签名逻辑与接入方式。
|
||||
### 1) smsreceiver-worker
|
||||
- 说明：将 SmsReceiver-go 迁移到 Cloudflare Worker + Pages + D1 的前后端分离实现
|
||||
- 目录：`./smsreceiver-worker/`
|
||||
- 文档：`./smsreceiver-worker/README.md`
|
||||
|
||||
## 架构概览
|
||||
## 目录约定
|
||||
|
||||
```
|
||||
[TranspondSms / 客户端]
|
||||
|
|
||||
| HTTP POST (token/sign)
|
||||
v
|
||||
Cloudflare Worker (Hono)
|
||||
|
|
||||
| D1 (SQLite)
|
||||
v
|
||||
数据持久化 + 管理 API
|
||||
|
||||
Cloudflare Pages (静态 UI)
|
||||
|
|
||||
| API_BASE 指向 Worker
|
||||
v
|
||||
管理后台
|
||||
<project-name>-worker/
|
||||
├── worker/ # Cloudflare Worker API
|
||||
├── pages/ # Cloudflare Pages (静态前端)
|
||||
└── README.md # 子项目说明
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
## 备注
|
||||
|
||||
```
|
||||
.
|
||||
├── 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/v1/receive`
|
||||
|
||||
字段：
|
||||
- `from`：发件人
|
||||
- `content`：短信正文
|
||||
- `timestamp`：Unix 时间戳
|
||||
- `token`：API Token
|
||||
- `sign`：签名
|
||||
- `device` / `sim`：设备与卡槽信息（可选）
|
||||
|
||||
## 2. 登录管理后台
|
||||
|
||||
- 访问 Pages URL
|
||||
- 输入 `ADMIN_USER` / 密码
|
||||
- 可查看短信列表、详情、日志、筛选记录
|
||||
|
||||
## 3. 管理 API 端点示例
|
||||
|
||||
- `GET /api/v1/messages`
|
||||
- `GET /api/v1/messages/:id`
|
||||
- `GET /api/v1/logs`
|
||||
|
||||
---
|
||||
|
||||
# 本地开发流程（推荐）
|
||||
|
||||
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
|
||||
|
||||
内部项目使用，按需扩展。
|
||||
后续新增 worker 化项目时：
|
||||
1. 新建 `<name>-worker/` 目录
|
||||
2. 保持 `worker/ + pages/ + README.md` 结构一致
|
||||
3. 在本总览 README 中追加条目
|
||||
|
||||
Reference in New Issue
Block a user