Files

OpenClaw Agent 74c6e25063 chore: restructure repo as worker collection

2026-03-23 12:58:51 +08:00

5.1 KiB

Raw Blame History

SmsReceiver Worker（前后端分离版）

将 SmsReceiver-go 迁移到 Cloudflare Worker + Pages + D1 的 Worker 化实现。目标是把「短信接收 API + 管理界面」拆分为独立的 API 服务与静态前端，提升部署弹性、跨域能力与运维简洁度。

开发目的

Worker 化：摆脱传统服务器进程部署，使用 Cloudflare Worker 作为 API 运行环境。
前后端分离：前端使用 Pages 静态托管，API 单独在 Worker 上运行，天然解耦。
低运维成本：无需自建数据库与运行时，D1 提供托管 SQLite 体验。
部署可重复：通过 wrangler + 配置文件完成快速部署与迁移。
兼容原协议：保留原 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

cd worker
npm install

编辑 wrangler.toml：

database_id
vars: ADMIN_USER / ADMIN_PASS_HASH / SESSION_SECRET / HMAC_SECRET

初始化 D1 表结构：

npx wrangler d1 execute smsreceiver --file=schema.sql

本地调试：

npx wrangler dev

发布：

npx wrangler deploy

2) 部署 Pages UI

将 pages/public/ 作为静态站点部署到 Cloudflare Pages。

修改 pages/public/app.js：

const API_BASE = "https://你的-worker域名"

部署完成后即可访问管理后台。

3) 密码 hash 生成

当前登录逻辑：HMAC_SHA256(password, SESSION_SECRET)

生成方式：

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）

运行：

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

本地开发流程（推荐）

在 worker/ 中使用 wrangler dev 启动本地 API。
在 pages/public/ 中修改前端并直接用静态服务器预览。
API_BASE 指向本地 API 或临时 Worker 域名。
测试完成后分别部署 Worker 与 Pages。

注意事项

UI 与 API 部署后跨域必须使用 SameSite=None; Secure Cookie。
D1 为 SQLite 兼容，但限制与云端事务特性不同于本地。
API Token 与 HMAC 密钥要妥善保管。

License

内部项目使用，按需扩展。

5.1 KiB Raw Blame History Unescape Escape