From 74c6e25063bccd192cb5fec6d52b5bee4a6291f9 Mon Sep 17 00:00:00 2001 From: OpenClaw Agent Date: Mon, 23 Mar 2026 12:58:51 +0800 Subject: [PATCH] chore: restructure repo as worker collection --- README.md | 228 ++---------------- smsreceiver-worker/README.md | 220 +++++++++++++++++ .../pages}/public/app.css | 0 .../pages}/public/app.js | 0 .../pages}/public/index.html | 0 .../worker}/migrate_sqlite_to_d1.py | 0 .../worker}/package-lock.json | 0 .../worker}/package.json | 0 .../worker}/schema.sql | 0 .../worker}/src/index.ts | 0 .../worker}/src/middlewares/auth.ts | 0 .../worker}/src/routes/auth.ts | 0 .../worker}/src/routes/logs.ts | 0 .../worker}/src/routes/messages.ts | 0 .../worker}/src/routes/receive.ts | 0 .../worker}/src/routes/stats.ts | 0 .../worker}/src/utils/common.ts | 0 .../worker}/src/utils/db.ts | 0 .../worker}/src/utils/session.ts | 0 .../worker}/src/utils/sign.ts | 0 .../worker}/tsconfig.json | 0 .../worker}/wrangler.toml | 0 22 files changed, 237 insertions(+), 211 deletions(-) create mode 100644 smsreceiver-worker/README.md rename {pages => smsreceiver-worker/pages}/public/app.css (100%) rename {pages => smsreceiver-worker/pages}/public/app.js (100%) rename {pages => smsreceiver-worker/pages}/public/index.html (100%) rename {worker => smsreceiver-worker/worker}/migrate_sqlite_to_d1.py (100%) rename {worker => smsreceiver-worker/worker}/package-lock.json (100%) rename {worker => smsreceiver-worker/worker}/package.json (100%) rename {worker => smsreceiver-worker/worker}/schema.sql (100%) rename {worker => smsreceiver-worker/worker}/src/index.ts (100%) rename {worker => smsreceiver-worker/worker}/src/middlewares/auth.ts (100%) rename {worker => smsreceiver-worker/worker}/src/routes/auth.ts (100%) rename {worker => smsreceiver-worker/worker}/src/routes/logs.ts (100%) rename {worker => smsreceiver-worker/worker}/src/routes/messages.ts (100%) rename {worker => smsreceiver-worker/worker}/src/routes/receive.ts (100%) rename {worker => smsreceiver-worker/worker}/src/routes/stats.ts (100%) rename {worker => smsreceiver-worker/worker}/src/utils/common.ts (100%) rename {worker => smsreceiver-worker/worker}/src/utils/db.ts (100%) rename {worker => smsreceiver-worker/worker}/src/utils/session.ts (100%) rename {worker => smsreceiver-worker/worker}/src/utils/sign.ts (100%) rename {worker => smsreceiver-worker/worker}/tsconfig.json (100%) rename {worker => smsreceiver-worker/worker}/wrangler.toml (100%) diff --git a/README.md b/README.md index 77fa5f1..3d14a55 100644 --- a/README.md +++ b/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 - 管理后台 +-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. 新建 `-worker/` 目录 +2. 保持 `worker/ + pages/ + README.md` 结构一致 +3. 在本总览 README 中追加条目 diff --git a/smsreceiver-worker/README.md b/smsreceiver-worker/README.md new file mode 100644 index 0000000..77fa5f1 --- /dev/null +++ b/smsreceiver-worker/README.md @@ -0,0 +1,220 @@ +# 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/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 + +内部项目使用，按需扩展。 diff --git a/pages/public/app.css b/smsreceiver-worker/pages/public/app.css similarity index 100% rename from pages/public/app.css rename to smsreceiver-worker/pages/public/app.css diff --git a/pages/public/app.js b/smsreceiver-worker/pages/public/app.js similarity index 100% rename from pages/public/app.js rename to smsreceiver-worker/pages/public/app.js diff --git a/pages/public/index.html b/smsreceiver-worker/pages/public/index.html similarity index 100% rename from pages/public/index.html rename to smsreceiver-worker/pages/public/index.html diff --git a/worker/migrate_sqlite_to_d1.py b/smsreceiver-worker/worker/migrate_sqlite_to_d1.py similarity index 100% rename from worker/migrate_sqlite_to_d1.py rename to smsreceiver-worker/worker/migrate_sqlite_to_d1.py diff --git a/worker/package-lock.json b/smsreceiver-worker/worker/package-lock.json similarity index 100% rename from worker/package-lock.json rename to smsreceiver-worker/worker/package-lock.json diff --git a/worker/package.json b/smsreceiver-worker/worker/package.json similarity index 100% rename from worker/package.json rename to smsreceiver-worker/worker/package.json diff --git a/worker/schema.sql b/smsreceiver-worker/worker/schema.sql similarity index 100% rename from worker/schema.sql rename to smsreceiver-worker/worker/schema.sql diff --git a/worker/src/index.ts b/smsreceiver-worker/worker/src/index.ts similarity index 100% rename from worker/src/index.ts rename to smsreceiver-worker/worker/src/index.ts diff --git a/worker/src/middlewares/auth.ts b/smsreceiver-worker/worker/src/middlewares/auth.ts similarity index 100% rename from worker/src/middlewares/auth.ts rename to smsreceiver-worker/worker/src/middlewares/auth.ts diff --git a/worker/src/routes/auth.ts b/smsreceiver-worker/worker/src/routes/auth.ts similarity index 100% rename from worker/src/routes/auth.ts rename to smsreceiver-worker/worker/src/routes/auth.ts diff --git a/worker/src/routes/logs.ts b/smsreceiver-worker/worker/src/routes/logs.ts similarity index 100% rename from worker/src/routes/logs.ts rename to smsreceiver-worker/worker/src/routes/logs.ts diff --git a/worker/src/routes/messages.ts b/smsreceiver-worker/worker/src/routes/messages.ts similarity index 100% rename from worker/src/routes/messages.ts rename to smsreceiver-worker/worker/src/routes/messages.ts diff --git a/worker/src/routes/receive.ts b/smsreceiver-worker/worker/src/routes/receive.ts similarity index 100% rename from worker/src/routes/receive.ts rename to smsreceiver-worker/worker/src/routes/receive.ts diff --git a/worker/src/routes/stats.ts b/smsreceiver-worker/worker/src/routes/stats.ts similarity index 100% rename from worker/src/routes/stats.ts rename to smsreceiver-worker/worker/src/routes/stats.ts diff --git a/worker/src/utils/common.ts b/smsreceiver-worker/worker/src/utils/common.ts similarity index 100% rename from worker/src/utils/common.ts rename to smsreceiver-worker/worker/src/utils/common.ts diff --git a/worker/src/utils/db.ts b/smsreceiver-worker/worker/src/utils/db.ts similarity index 100% rename from worker/src/utils/db.ts rename to smsreceiver-worker/worker/src/utils/db.ts diff --git a/worker/src/utils/session.ts b/smsreceiver-worker/worker/src/utils/session.ts similarity index 100% rename from worker/src/utils/session.ts rename to smsreceiver-worker/worker/src/utils/session.ts diff --git a/worker/src/utils/sign.ts b/smsreceiver-worker/worker/src/utils/sign.ts similarity index 100% rename from worker/src/utils/sign.ts rename to smsreceiver-worker/worker/src/utils/sign.ts diff --git a/worker/tsconfig.json b/smsreceiver-worker/worker/tsconfig.json similarity index 100% rename from worker/tsconfig.json rename to smsreceiver-worker/worker/tsconfig.json diff --git a/worker/wrangler.toml b/smsreceiver-worker/worker/wrangler.toml similarity index 100% rename from worker/wrangler.toml rename to smsreceiver-worker/worker/wrangler.toml