架构与开发
源码与入口
| 路径 | 职责 |
|---|---|
worker/src/index.ts | Webhook、HTTP、Cron 入口 |
worker/src/bot | 命令、回调和会话处理 |
worker/src/services | 数据读取与监控 |
worker/src/db | D1 数据访问 |
worker/src/api | REST 路由及管理权限验证 |
webapp | Next.js Web App |
Webhook 使用 POST /webhook。配置 WEBHOOK_SECRET 后，Worker 校验 Telegram 的
X-Telegram-Bot-Api-Secret-Token 请求头。
GET /api/health 用于健康检查；/api/admin/* 必须验证 Cloudflare Access JWT。
本地开发
需要 Node.js 22+、Bun 和独立的开发 Bot。在仓库根目录执行：
cd worker
bun install
npx wrangler dev
先在本地 D1 应用当前 checkout 需要的 migrations，按编号逐个执行；不要只应用初始表结构就启动新增监控功能。 本地迁移命令形式为：
npx wrangler d1 execute dolphin-bot-db --local --file=migrations/0001_init.sql
开发凭据使用本地 .dev.vars，生产凭据通过 Wrangler Secrets 注入。
必须配置自己的 TELEGRAM_BOT_TOKEN 与 WEBHOOK_SECRET；不要提交其值。
在另一终端从仓库根目录执行：
cd webapp
bun install
bun run dev
验证与发布边界
在 worker/ 执行 bun run build 进行 Wrangler dry-run 检查，不会部署 Worker。
正式应用发布需核对当前 migrations、D1/KV、Cron、Webhook secret、Mini App URL 和 Access 策略。
文档发布不更换 Telegram Webhook，也不修改管理权限。
本文档源码位于 docs/site/content/。在 docs/site/ 运行
npm ci && npm run build 构建独立的静态文档，发布及回滚说明见同目录 README.md。