开发指南
架构与适配层
仓库分工
| 目录 | 是什么 |
|---|---|
server/ | Workers 运行时适配层，Node 里模拟 D1 / DO / Cron / Assets |
src/ | 业务代码，与 CF 原版保持一致，方便跟随上游更新 |
test/ | node --test 测试 |
scripts/ | 构建脚本 |
适配层做了什么
| Workers 的东西 | 在 Node 里换成 |
|---|---|
| D1 | SQLite（server/d1.js） |
| Durable Objects | 单进程实例，落盘到 do-storage.json（server/durable.js） |
| Cron Triggers | 按 UTC 对齐的 setInterval（server/index.js） |
| Workers Assets | 静态文件（server/assets.js） |
| 请求上下文 | 一个带 cf-ipcountry 头等模拟字段的假 ctx（server/runtime.js） |
D1 适配器
D1 底层就是 SQLite，本项目只用到 prepare / bind / first / all / run 几个 API，server/d1.js 用 better-sqlite3 实现同接口，SQL 语句无需任何修改。
语义对齐要点：
first()无结果时返回null（D1 行为）all()返回{ success, results, meta }run()返回{ success, meta: { changes, last_row_id }, changes }bind参数自动归一化：undefined→null、boolean→0/1、Date→毫秒时间戳
WAL 模式和基本 PRAGMA 也在这一层设置。
Durable Objects
原版用 DO 做实时广播和广播门控。移植版用一个单进程实例模拟，落盘到 do-storage.json，所以数据不丢但不共享（只有一个进程）。
Cron
原版的 wrangler.toml 里的 triggers.crons，在移植版里是 server/index.js 里一个按 UTC 对齐的 setInterval。当前有三个：
| 表达式 | 做什么 |
|---|---|
*/1 * * * * | 离线检测 + 资源负载告警检测 |
0 * * * * | 数据清理（表轮换），保留 history_retention_days 天 |
0 0 * * 0 | 每周数据清理 |
0 12 * * * | 服务器到期检测 |
静态资源
server/assets.js 读文件返回，前端产物来自 npm run build:frontend（Vite）。
为什么要这么绕
为了跟随上游。src/ 里是原版的业务逻辑，重写意味着丢掉主题生态和探针协议。这层间接换来的是：上游更新时只需检查适配层，业务代码跟着同步即可。完整数据表清单见仓库 API.md；迁移原理见这是什么。
在 GitHub 上修改这一页最后更新 2026-09-25