RouteVerge Backend

RouteVerge 后端服务，基于 Cloudflare Workers + Cloudflare D1 架构构建。负责设备激活准入、单设备一次性卡密兑换、Telegram Bot 配合 Cloudflare Turnstile 人机验证，以及可视化的 Admin 管理控制台。

---

核心特性

• 后台可动态配置最低版本：最低允许激活的 App 版本持久化至 D1（settings 表），在管理后台直接修改保存即生效，无需重新部署 Worker；支持语义化版本校验与向下兼容默认值。
• 现代化双栏与移动端卡片化后台：
  • PC / 宽屏：双栏等高对齐，各自独立滚动，固定 Sticky 表头，左右利用率高。
  • 手机端：自动切换单列布局，表格自动转换为响应式数据卡片，防止长 deviceId 撑破页面，无全局横向滚动。
  • 列表高度自适应当前视口，避免数据量大时页面无限纵向拉长。
• 卡密与设备生命周期管理：
  • 批量生成 16 位格式化卡密（XXXX-XXXX-XXXX-XXXX）。
  • 支持直接删除未使用的激活码使其即时作废。
  • 已兑换激活码保持审计保留，绑定对应设备 ID 与激活时间。
  • 支持解绑已激活设备及维护设备备注。
• Telegram Bot + Turnstile 验证：
  • 用户可在 Telegram Bot 获取绑定验证链接。
  • 通过 Cloudflare Turnstile 验证后生成 8 位时效验证码供 App 输入绑定。

---

技术架构

• 运行环境: Cloudflare Workers (ES Module)
• 数据库: Cloudflare D1 (SQLite)
• 依赖: 纯 Web 标准 API 与轻量 Wrangler CLI 工具链，零额外重型第三方依赖

---

快速上手

1. 安装依赖

npm install

2. 创建 Cloudflare D1 数据库

npx wrangler d1 create nfc_activation

执行后会输出 database_id，请妥善保存。

3. 配置 wrangler.toml

复制项目根目录下的配置示例：

cp wrangler.example.toml wrangler.toml
# Windows PowerShell:
# Copy-Item wrangler.example.toml wrangler.toml

编辑 wrangler.toml，填入：

• database_id: 上一步创建的 D1 数据库 ID
• TURNSTILE_SITE_KEY: Cloudflare Turnstile 站点密钥
• PUBLIC_BASE_URL: Worker 公网域名（例如 https://your-domain.com）
• ADMIN_TG_IDS: 允许在 Telegram 中使用管理员命令的 Telegram User ID（英文逗号分隔）

4. 初始化数据库 Schema

# 本地测试环境
npx wrangler d1 execute nfc_activation --local --file schema.sql

# 远程线上生产环境
npx wrangler d1 execute nfc_activation --remote --file schema.sql

注意（已有生产数据库平滑升级）： 如果您是从旧版数据库升级，无需重建或清空原有数据表，仅需在 D1 执行以下增量迁移即可：

CREATE TABLE IF NOT EXISTS settings (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

INSERT INTO settings (key, value, updated_at)
VALUES ('min_activation_version', '1.6.1', strftime('%Y-%m-%dT%H:%M:%f+08:00', 'now', '+8 hours'))
ON CONFLICT(key) DO NOTHING;

---

环境变量与 Secrets 配置

生产环境涉及的敏感凭据请通过 wrangler secret put 单独注入，切勿硬编码提交到 Git：

# 生成管理员密码的 SHA-256 哈希值
node -e "crypto=require('crypto'); console.log(crypto.createHash('sha256').update('your-admin-password').digest('hex'))"

# 注入 Worker Secrets
npx wrangler secret put ADMIN_PASSWORD_HASH
npx wrangler secret put ADMIN_SESSION_SECRET
npx wrangler secret put CODE_HASH_PEPPER
npx wrangler secret put BOT_TOKEN
npx wrangler secret put TG_WEBHOOK_SECRET
npx wrangler secret put TURNSTILE_SECRET

Secret 名称	说明
ADMIN_PASSWORD_HASH	管理员登录密码的 SHA-256 哈希值（小写十六进制）
ADMIN_SESSION_SECRET	用于签名 Admin Cookie 会话的随机私钥
CODE_HASH_PEPPER	激活码与验证码加盐哈希的 Pepper 密钥
BOT_TOKEN	Telegram Bot API Token
TG_WEBHOOK_SECRET	Telegram Webhook Secret Token（请求头防伪校验）
TURNSTILE_SECRET	Cloudflare Turnstile 校验 Secret Key

---

Telegram Bot Webhook 设置

Worker 部署完成后，需将 Telegram Bot 的 Webhook 指向 Worker 服务：

$TelegramBotToken = "your-bot-token"
$WebhookSecret = "your-tg-webhook-secret"
$WebhookUrl = "https://your-worker-domain/telegram/webhook"

Invoke-RestMethod "https://api.telegram.org/bot$TelegramBotToken/setWebhook" `
  -Method Post `
  -ContentType "application/json" `
  -Body (@{ url = $WebhookUrl; secret_token = $WebhookSecret } | ConvertTo-Json)

---

本地开发与发布命令

# 语法与类型合法性检查
npm run check

# 本地模拟运行 (默认加载 .dev.vars)
npm run dev

# 部署预览预检 (Dry-Run)
npx wrangler deploy --dry-run

# 正式部署到 Cloudflare
npm run deploy

---

客户端 (Android App) 对接配置

在 Android 客户端的配置或资源文件中填入：

activationBaseUrl=https://your-worker-domain
telegramBotUsername=your_bot_username

---

开源协议

本项目采用 GPL-3.0 许可协议开源。