# artalk-cf —— 跑在 Cloudflare 上的 Artalk 评论后端 + RSS 订阅机器人

自研的 **Artalk API v2 兼容服务端**，以及合并进来的 **RSS 订阅机器人（rss-robot）**，
一起跑在 **Cloudflare Workers + D1 + KV** 上，零服务器、零运维、免费额度内。

> **状态：已上线** → `https://api.200181.xyz`
> D1 `artalk-cf`（`78140776-2bfd-439a-8b05-c3eebe5d5b47`）｜ KV `RSS_KV`（`d7f86a0fb43f4450a10b786fc2635128`）
> 管理员账号 `admin`（后台登录用邮箱+密码，见「部署」）
>
> **两个后台都可用**：`/admin/` 自研管理面板 ｜ `/sidebar/` 官方 Artalk 后台
> **评论前端一行不用改**：继续用官方 Artalk 客户端（博客里打包的 2.8.7），换后端只改 `hugo.toml` 一行 `server`。

---

## 目录

1. [这个项目是什么](#这个项目是什么)
2. [技术选型](#技术选型)
3. [模块分布](#模块分布)
4. [数据模型](#数据模型)
5. [部署](#部署)
6. [接到博客上](#接到博客上)
7. [评论数据迁移](#评论数据迁移)
8. [性能与免费额度](#性能与免费额度)

---

## 这个项目是什么

两件事，各对应一个原本独立的仓库，现在合并进同一个 Worker：

| 子项目 | 来源 | 职责 | 路径 |
|---|---|---|---|
| **artalk-cf** | 自研 | Artalk API v2 兼容评论后端（44 路径 / 54 操作已实现 46 个） | `/api/v2/*` |
| **rss-robot** | 迁移自 EdgeOne 的 `api/*.js` | RSS 订阅抓取 + 友链/友圈 + 公众号内容 | `/api/*`（不含 `/api/v2`） |

两者共存于一个 Worker、一个 D1、一个 KV，互不冲突：
Artalk 客户端只打 `/api/v2/*`，RSS 模块只打 `/api/*`（非 v2），路径天然隔离。

---

## 技术选型

### 整体判断：为什么是 Cloudflare Workers + D1，而不是自建服务器

| 考量 | 结论 |
|---|---|
| 成本 | 免费版够用（Workers 10 万请求/天、D1 读 500 万行/天、存储 5GB），博客评论量级远用不满 |
| 运维 | 无服务器、无 SSH、无进程守护；`wrangler deploy` 一条命令发布 |
| 大陆可用性 | 见下方「已知取舍」——这是唯一的短板 |

### 逐项选型与理由

**1. 运行环境：Cloudflare Workers（免费版）**

- 全球边缘函数，`fetch` 入口 + `scheduled` 定时入口
- **致命限制**：**没有 TCP socket** → 无法直连 SMTP 发邮件、无法跑原生 bcrypt，这两点直接决定了后续选型（见下）
- 单请求 CPU 预算约 10ms（免费版），驱动了「读写分流 + 覆盖索引 + 计数缓存」一系列优化

**2. 数据库：D1（Cloudflare 的 SQLite 边缘库）**

- 兼容 SQLite 语法，`wrangler d1 execute` 直接跑 SQL，批量导入零成本
- 读写分离：**D1 Sessions API + 只读副本**（`first-primary` 写 / `first-unconstrained` 读）
- 免费额度：读 500 万行/天、写 10 万行/天。**这是本项目最需要盯的资源**（2026-10-03 曾被打爆过一次，见性能章节的「打爆复盘」）

**3. KV（键值存储）：RSS 订阅与验证码通行证**

- RSS 的 `feeds_config` / 抓取游标 / 失败退避、人机验证的通行证、管理员通知节流，全放 KV
- 理由：这些是「低频读、高频写、无关系」的数据，放 D1 会白白烧行数额度

**4. 语言：TypeScript + Wrangler**

- 与 Workers 官方工具链天然契合；`tsc --noEmit` 做类型检查
- 不引入任何运行时依赖（`package.json` 里只有 `@cloudflare/workers-types`、`typescript`、`wrangler` 三个 devDependencies）
- 需要原生缺失的东西就自己写：`MD5`（Gravatar hash）、`Markdown 子集解析`、`PBKDF2`（用 WebCrypto）

**5. 鉴权：无状态 HMAC-SHA256 token + PBKDF2 密码**

- token 用 `TOKEN_SECRET` 做 HMAC 签名、7 天过期，无状态不落库
- 密码 PBKDF2-SHA256 12 万轮（WebCrypto 实现）；兼容读取 `(md5)` 和明文（仅迁移期）
- **不用 bcrypt** 是因为 Workers 没有 Node 的 native 依赖、也不值得为一个算法引进包

**6. 邮件：Resend 的 HTTP API（而非 SMTP）**

- Workers 无 TCP，SMTP 连不上；Resend 免费 3000 封/月
- 全程 `ctx.waitUntil()` 异步 + try/catch，发信失败绝不影响评论落库

**7. 人机验证：自研「一键验证」（PoW + 行为信号），而非 Turnstile/reCAPTCHA**

- 第三方脚本在大陆加载不稳定，失败会卡死评论提交；还会把访客指纹送给第三方
- 自研版：浏览器静默算 20~80ms 的 PoW（sha256 前缀 4 个 0），命中可疑信号才让访客「点一下」，再可疑才回退图形验证码
- 挑战无状态（HMAC 签名不写库），通行证放 KV 不占 D1 额度

**8. 前端：零重写，直接复用官方产物**

- 客户端 + 官方后台（`/sidebar/`）是 Artalk v2.8.7 的预构建产物，内置在 `public/` 里
- 自研管理面板 `/admin/` 用**纯原生 JS + 零依赖**（补齐官方后台缺的「待审视图」「关键词搜索」等）

### 已知取舍（有意为之）

| 项 | 取舍 | 影响 |
|---|---|---|
| 大陆 → CF 边缘 ~170ms 延迟 | CF 免费版在大陆无节点，流量被送到 LAX | 加 `<link rel="preconnect">` 省掉 0.5s TLS 握手，立竿见影 |
| 页面标题自动抓取 | 不做（跨境请求收益低） | 标题改为发评论时从 `page_title` 落库 |
| 邮箱验证码登录 / 社交登录 | 不做 | 管理员走密码登录，不受影响 |
| `url_resolver` | 必须保持 false | 开启会重写 page_key，现有 `/20210911.html` 全失配 |

---

## 模块分布

```
artalk-cf/
├── wrangler.toml            ★ Worker 配置：D1/KV/静态资源/域名/cron/变量
├── schema.sql               ★ 建表（10 张表 + 覆盖索引）
├── 部署清单.md              ★ 照着敲的部署步骤（含域名那一坑）
├── .dev.vars.example        本地开发机密模板（复制成 .dev.vars）
│
├── src/                     ===== 服务端（TypeScript）=====
│   ├── index.ts             入口：路由注册 + fetch + scheduled 定时任务
│   ├── router.ts            迷你路由器（路径参数匹配，挂 / 与 /api/v2）
│   ├── rss-api.ts           RSS 模块入口（路由表 + cron 轮转抓取）
│   ├── types.ts             Env / 实体 / 响应类型定义
│   ├── template.generated.ts  设置页 YAML 模板（由官方 conf 生成）
│   │
│   ├── lib/                 ===== 通用库（无 I/O 依赖的纯逻辑）=====
│   │   ├── db.ts            D1 查询封装 + 限流 + 验证码状态
│   │   ├── cook.ts          实体 → API 输出（对应官方 dao/cook.go）
│   │   ├── session.ts       token 签发/校验 + 密码 + 管理员判定
│   │   ├── md5.ts           MD5（Gravatar hash，Workers 没有）
│   │   ├── md.ts            Markdown 子集 → HTML（先转义再解析，防 XSS）
│   │   ├── util.ts          时间 / CORS / 响应 / 校验工具
│   │   ├── errors.ts        ★ 统一错误出口（技术错误翻译成人话 + 机器码）
│   │   ├── human.ts         人机验证：PoW 挑战 + KV 通行证
│   │   ├── mail.ts          邮件发送（Resend HTTP API）
│   │   ├── admin-notify.ts  管理员提醒邮件（带节流）
│   │   └── rss/             ===== RSS 订阅子系统 =====
│   │       ├── cron.ts      每小时轮转抓取（66 源 ÷ 22 = 3 小时一轮）
│   │       ├── fetch.ts     抓取（超时/重试/代理回退/熔断）
│   │       ├── discover.ts  feed 地址自动发现
│   │       ├── parse.ts     RSS/Atom 解析
│   │       ├── greetings.ts 问候语/每日一图
│   │       ├── notify.ts    更新推送（飞书 webhook 等）
│   │       ├── proxy-health.ts  国内代理（SCF）体检
│   │       └── util.ts      RSS 工具
│   │
│   └── routes/              ===== 路由处理器（按业务域分组）=====
│       ├── public.ts        conf / 验证码 / 投票 / pv / setup / healthz
│       ├── comments.ts      评论 CRUD + 列表与树（含人机验证门）
│       ├── user.ts          用户 / 登录 / 合并 / SSO
│       ├── admin.ts         设置 / 站点 / 页面 / 用户 / 消息 / 统计 / 导入导出 / 上传
│       ├── human.ts         人机验证端点（challenge / verify / status）
│       └── rss/             ===== RSS 路由 =====
│           ├── feeds.ts     订阅源管理
│           ├── links.ts     友链/友圈
│           ├── results.ts   抓取结果 / 文章
│           ├── media.ts     随机图 / 评论机器人
│           ├── greeting.ts  问候语
│           ├── misc.ts      鉴权 / 健康检查
│           ├── tools.ts     favicon / 代理 / cron / 部署状态 / 邮件
│           └── wechat.ts    微信公众号内容
│
├── public/                  静态资源（优先级高于 Worker，改这里不用动 Worker 代码）
│   ├── index.html           /           入口页（健康状态 + 两个后台入口）
│   ├── admin/               /admin/     自研管理面板（原生 JS，6 个视图）
│   │   ├── admin.css        设计令牌 + 全部组件样式
│   │   ├── admin.js         仪表盘/评论/页面/用户/设置/状态
│   │   └── fonts/           Press Start 2P + JetBrains Mono
│   ├── sidebar/             /sidebar/   官方 v2.8.7 管理后台（Vue 预构建）
│   ├── dist/                官方 v2.8.7 客户端与插件
│   └── feed.html            /feed/      RSS 订阅源管理页
│
└── tools/                   工具脚本（开发/部署/自检）
    ├── deploy.sh            一键部署
    ├── import_artrans.py    .artrans → D1 SQL（批量迁移）
    ├── import_delta.py      增量导入
    ├── gen_template.py      从官方 conf YAML 生成设置模板常量
    ├── selftest.ts          纯逻辑自检（MD5/时间/Markdown/密码/token/YAML）
    ├── smoke.sh             冒烟测试
    ├── preview-mail.ts      邮件样张预览
    ├── mailtest.ts          发信测试
    └── check-*.mjs / probe-*.mjs / shot-*.mjs / measure-*.mjs
                             无头浏览器（CDP）测量/回归脚本，调试评论前端用
```

### 数据流一览

```
浏览器（博客评论区 / 后台 iframe）
   │  /api/v2/*（评论）/ /api/*（RSS）
   ▼
Worker fetch（src/index.ts）
   ├─ /api/* 且非 /api/v2/*  → rss-api.ts（RSS 子系统）
   └─ 其余 → router.ts 分发到 routes/*
        │
        ├─ 读请求  → D1 只读副本（first-unconstrained）
        ├─ 写请求  → D1 主库（first-primary）
        └─ 通行证  → KV（人机验证 / RSS 游标 / 通知节流）
   │
scheduled（cron）
   ├─ 0 * * * *   → RSS 轮转抓取（每小时 22 源）
   └─ 17 3 * * *  → 评论 GC（限流/验证码清理 + healthz 缓存刷新 + 代理体检）
```

---

## 数据模型

**10 张表**（`schema.sql`），时间统一存 unix 毫秒，输出时按 `Asia/Shanghai` 格式化：

| 表 | 用途 | 关键字段 |
|---|---|---|
| `sites` | 站点 | name（唯一）、urls |
| `pages` | 页面 | key（=page_key 如 `/20210911.html`）、site_name、pv、vote |
| `users` | 用户 | name+email（唯一）、password（pbkdf2/md5/明文兼容）、徽章、头衔 |
| `comments` | 评论 | rid（父节点）、root_id（顶层祖先）、is_pending/pinned/verified、软删除 deleted_at |
| `votes` | 投票 | target_id + user_id + type 唯一 |
| `notifies` | 通知 | user_id、comment_id、is_read/is_emailed |
| `settings` | 键值配置 | key（主键）、value（frontend_conf / admin_users 等） |
| `rate_limits` | 限流 | bucket（如 `comment:1.2.3.4`）、count、expires_at |
| `captcha_passes` | 验证码通过状态 | ip（主键）、expires_at |
| `captcha_challenges` | 验证码题目 | answer_hash（只存哈希） |

**覆盖索引**（性能关键，见下）：

- `idx_comments_page_list` — 列表 `ORDER BY is_pinned DESC, created_at DESC` 专用
- `idx_comments_children` — 子评论 `root_id IN (...)` 专用
- `idx_comments_site_list` — 站点级列表

`root_id` 语义与官方一致：顶层为 0，子孙为该顶层评论的 id。列表默认 `nested` 模式——取一页顶层，再捞回全部子孙交给前端组树。

---

## 部署

**完整步骤看 [`部署清单.md`](部署清单.md)**（照着敲约 10 分钟）。快速版：

```bash
cd blog-admin && npm install
npx wrangler login
npx wrangler d1 create artalk-cf      # 把返回的 database_id 填进 wrangler.toml
npx wrangler secret put TOKEN_SECRET
npx wrangler secret put ADMIN_PASSWORD
npx wrangler d1 execute artalk-cf --remote --file=./schema.sql
npx wrangler deploy
curl -X POST https://<worker>/api/v2/setup
```

### ★ 域名这一步有个坑，动手前先看

**Cloudflare Worker 的自定义域名要求「域名的 NS 托管在 Cloudflare」。**
而 `usj.cc` 的 NS 在 DNSPod（还挂着又拍云 + 腾讯云 EdgeOne 调度）——**千万不要为了评论 API 把整站 NS 搬去 Cloudflare**，会弄坏现有国内双 CDN 链路。

本项目用的是 **`api.200181.xyz`**（NS 本来就在 Cloudflare）：

```toml
[[routes]]
pattern = "api.200181.xyz"
custom_domain = true
```

`*.workers.dev` 地址在大陆基本不通，只能自测。四种域名方案取舍见 `部署清单.md` 第 9 步。

### 机密清单（不写进仓库）

| Secret / 变量 | 用途 |
|---|---|
| `TOKEN_SECRET` | 登录 token 签名 |
| `ADMIN_PASSWORD` | 管理员密码 |
| `RESEND_API_KEY` | 邮件（可选） |
| `MAIL_FROM` / `MAIL_ADMIN` | 邮件发件人 / 收件人（可选） |

---

## 接到博客上

`E:\GitHub\blog\hugo.toml`：

```toml
[params.artalk]
  server = "https://api.200181.xyz"   # ← 只改这一行
  site = "优世界"                      # 必须与 SITE_DEFAULT 一致
```

客户端调用 `${server}/api/v2/...`，`pageKey` 用 `.RelPermalink`（`/20210911.html`），与 D1 的 `page_key` 完全对应，**不需要改任何模板或前端代码**。

---

## 评论数据迁移

### 方式一：批量 SQL（推荐）

Worker 逐条 INSERT 会产生几千次 D1 往返，免费版单请求 CPU 只有 10ms 容易超时，所以走 `wrangler d1 execute --file`：

```bash
python tools/import_artrans.py       # 读 .artrans，只导「优世界」，生成 SQL
bash tools/import-out/run.sh --remote
```

脚本做了：按 site_name 过滤、按「昵称+邮箱」重建用户、保留原始 id 与 rid 关系、rid 回填与 root_id 计算分三趟做（与导入顺序无关）、最后自检打印各表条数。

### 方式二：后台界面导入

登录 `/sidebar/` → 迁移页 → 上传 `.artrans`（小数据量可用）。

### ⚠️ 别踩的坑

- `url_resolver` 保持 false，否则 page_key 被重写，评论区变空
- 导出里 `created_at` 为 Go 零值（`0001-01-01`）的 6 条会被兜底成当前时间

---

## 性能与免费额度

### 免费额度够不够（3440 条评论 / 138 篇文章）

| 资源 | 免费额度 | 你的用量 | 结论 |
|---|---|---|---|
| Workers | 10 万请求/天 | 评论量级一天最多几千 | ✅ |
| D1 存储 | 5 GB | 评论约几 MB | ✅ |
| D1 读 | 500 万行/天 | 一次列表查询几十行 | ✅ |
| Workers CPU | 10 ms/请求 | 列表查询含 markdown 渲染，需观察 | ⚠️ |

### 分层耗时（中国大陆网络实测）

| 项 | 耗时 |
|---|---|
| 冷连接 TLS 握手 | ~0.51s |
| 连接复用后端到端 | ~190ms |
| 1 次 D1 查询 | 8~20ms |

**真正的瓶颈是「大陆 → CF 边缘」这段（~170ms），不是数据库。** 改善：博客里加 `<link rel="preconnect" href="https://api.200181.xyz">`，省掉 0.5s TLS 握手，成本最低。

### 打爆复盘（2026-10-03 D1 额度用尽）

D1 免费版读额度（500 万行/天，UTC 00:00 = 北京 08:00 重置）被一次打爆，实测 525 万行。定位与修复：

1. **取证**：CF GraphQL `d1QueriesAdaptiveGroups`（维度名是 `query`）按 `sum_rowsRead` 排序，锁定 `COUNT(*)` + `LEFT JOIN users` 是无索引全表扫
2. **修复**：
   - 三个覆盖索引（`idx_comments_page_list` / `_children` / `_site_list`）
   - 计数 KV 缓存（只在增删/审核时失效）
   - 列表/计数不再无谓 JOIN users
   - 两个 COUNT 合并成一条 `COUNT(*) + SUM(CASE ...)`
3. **教训**：改动前**先本地预览 + 冒烟测试**，别拿线上打爆的额度再跑测试

### 自查方法

打开 <https://api.200181.xyz/api/v2/healthz> 看三个字段：

- `colo` —— 请求落在哪个 CF 机房（决定 RTT）
- `region` / `primary` —— 查询由主库还是副本处理
- `mail` —— 邮件是否已配置（`"on"`）

---

## 安全

- 登录 token：HMAC-SHA256 签名，无状态、7 天过期；改密码写 `token_valid_from` 让旧 token 立即失效
- 密码：PBKDF2-SHA256 12 万轮；兼容 `(md5)` / 明文（仅迁移）
- 后台接口全部走 `requireAdmin`，未登录 403
- 评论软删除（`deleted_at`），误删可从 D1 恢复
- CORS 白名单 + 预检处理；写接口走 D1 计数限流
- 验证码答案只存哈希；人机验证挑战 HMAC 签名无状态
- 顶层 fetch 兜底：任何漏网异常也带 CORS + 人话错误，不给读者甩「Failed to fetch」