doocs/md 后端 API 深度解析:Cloudflare Workers + Hono + D1 的账户、云同步与计费架构

原创2026-09-21 15:52:381,749 阅读
文章标签:前端AI 应用

doocs/md 后端 API 深度解析:Cloudflare Workers + Hono + D1 的账户、云同步与计费架构

导读

本文围绕 doocs/md(微信 Markdown 编辑器)的后端服务 @md/api 展开,它基于 Cloudflare Workers + Hono + D1 构建,承载 GitHub 账户登录、文章与偏好设置的增量云同步、预览分享、主题/组件市场、云表情包以及免费/Pro 计费能力。读完本文,你将掌握该后端的完整 API 路由设计、数据流与冲突合并策略,并能依据官方部署步骤从零搭建一套可运行的自部署实例,同时理解图床代理、爱发电 Pro 开通等敏感流程的安全设计。

一、整体架构与数据流

@md/api 的定位是 doocs/md 的「云端大脑」:前端编辑器(apps/web)通过 Bearer JWT 调用 Worker 上的 Hono 路由,Worker 将数据持久化到 Cloudflare D1(SQLite 系)数据库;爱发电(afdian.com)的订单回调则通过 Webhook 进入 Worker,最终更新 users.plan 字段。

前端 ──Bearer JWT──> Worker ──> D1 (users / documents / settings / marketplace_items)
爱发电 ──Webhook──> Worker ──> 更新 users.plan

从 apps/api/src/index.ts 的路由注册可以看出,整个应用被划分为公开区与登录区两层:

  • 公开路由直接挂在根 app 上:/upload(默认图床上传)、/auth/*(GitHub OAuth)、/webhooks/afdian(爱发电回调)、/s/:shareId(只读分享页)、/marketplace(市场浏览)、/emojis(公开清单与资源)。
  • 登录区是一个独立的 api Hono 实例,通过 api.use('*', authMiddleware) 统一做 JWT 校验,再挂载 /me、/sync/*、/share 管理接口与 /notifications。这与 README 中「登录后可用能力」的划分完全对应。

CORS 层是值得注意的设计:中间件从 APP_URL(逗号分隔、支持 * 通配符)读取前端来源白名单,并通过 isAllowedOrigin / isBrowserExtensionOrigin 判定,允许携带凭据(credentials: true),从而同时服务 Web 站点、Gitee Pages、PR 预览域名以及浏览器扩展(详见 apps/api/src/origin.ts 的调用)。

二、能力总览

按 README,该后端提供以下核心能力:

  • GitHub OAuth 登录:签发自有 JWT(HS256,有效期 30 天)。
  • 文章与偏好设置增量同步:/sync/pull 与 /sync/push 两个端点。
  • 预览分享:登录用户可将编辑器预览快照发布为只读链接(/share → GET /s/:id),支持访问密码,默认 1 天过期。
  • 主题 / 组件市场:公开浏览已审核内容;登录后可发布(进入 pending 状态);由 ADMIN_GITHUB_LOGINS 指定的管理员审核通过后上架。
  • 云表情包:公开默认表情包与资源代理;登录用户可管理一个最多 100 项的个人表情包。
  • 免费 / Pro 套餐:Pro 支持更高同步频率与更多配额;免费版同步限 30 次/小时,Pro 限 300 次/小时。
  • 爱发电 Pro 开通:Webhook 自动激活 + 订单号手动激活双通道。
  • 冲突策略:last-write-wins(按 updateDatetime),软删除墓碑保证删除可传播。
  • 数据范围:文章(含 history)+ 偏好白名单;不包含图床密钥、AI 密钥——这两类敏感信息始终留在本地,绝不入云。

三、GitHub OAuth 登录与 JWT 签发

3.1 两步式授权流程

OAuth 流程由 apps/api/src/auth.ts 实现,分为两步:

  1. GET /auth/github:生成随机 state(基于 uuidv4),写入 httpOnly、SameSite=Lax、有效期 600 秒的 Cookie,同时把经过 resolveRedirect 校验的前端来源写入 md_oauth_redirect Cookie,随后 302 跳转 GitHub 授权页(scope 仅申请 read:user)。
  2. GET /auth/github/callback:校验 state 与 Cookie 一致后,用 code 向 GitHub 换取 access token,再调用 GET https://api.github.com/user 获取用户信息,upsertUser 写入/更新 users 表,最后签发 JWT。

关键细节:JWT 不通过 URL query 回传,而是写入 URL fragment(redirect.hash = 'account_token=' + token),避免 token 出现在服务端访问日志中。JWT 使用 Hono 的 sign/verify,算法 HS256,TOKEN_TTL_SECONDS = 60*60*24*30(30 天),载荷包含 sub(内部用户 UUID)与 login。

3.2 认证中间件与 /me

authMiddleware 从 Authorization: Bearer <token> 中解析并 verify JWT,把 userId 注入上下文;校验失败统一返回 401。GET /me(meHandler)返回当前用户信息,其中 plan 经过 getEffectivePlan 实时计算(见 apps/api/src/plan.ts),isAdmin 由 ADMIN_GITHUB_LOGINS 判定:

{
  "id": "…",
  "login": "…",
  "name": "…",
  "avatar": "…",
  "plan": "free",
  "planExpiresAt": null,
  "isAdmin": false
}

四、增量云同步:pull / push 与 LWW 合并

4.1 拉取:GET /sync/pull?since=

pullHandler(apps/api/src/sync.ts)接收毫秒级游标 since,返回该游标之后的所有变更,并给出新的 cursor 供下次轮询:

{ "documents": [], "settings": [], "cursor": 0 }

游标实现依赖 D1 表中每行独立的 server_updated_at 字段(见 apps/api/migrations/0001_init.sql 的 documents / settings 表及其游标索引),服务端按 (user_id, server_updated_at) 高效筛选增量。

4.2 推送:POST /sync/push

pushHandler 的完整校验链如下:

  • 体积预检:Content-Length 超过 SYNC_PUSH_LIMITS.maxRequestBytes(8 MiB)直接返回 413。
  • JSON 解析与结构校验:调用 validatePushPayload,对 documents 与 settings 逐项校验长度/大小/类型,具体上限定义在 apps/api/src/sync-limits.ts:
限制项 上限
单次推送文档数 100
单次推送设置项数 80
文档 id 长度 128 字符
标题长度 500 字节
正文内容 512 KiB
history 条数 20
单条 history 内容 512 KiB
设置项 key 256 字符
设置项 value 1 MiB
单请求总体积 8 MiB
单行 D1 行体积 1.8 MB(为 D1 2MB 行上限预留头部)
  • 配额检查:文档数与总行数(含墓碑行)分别受 SYNC_STORED_DOCUMENT_LIMIT 与 SYNC_STORED_ROW_LIMIT 约束——免费 200 文档/400 行,Pro 2000/4000 行。行级配额的存在,是为了防止「删除+重建」反复消耗活跃文档名额。
  • 合并落库:pushChanges 按 updateDatetime 做 last-write-wins 合并;删除以软删除墓碑(deleted = 1)形式传播,保证多端删除不会复活。响应仅返回本次被接受的记录与新游标。

4.3 同步限流

checkSyncRateLimit 基于 sync_rate_limits 表与 UTC 小时键 hour_key 计数,免费 30 次/小时、Pro 300 次/小时,超限返回 429 并附带 retryAfterSec。前端按约定「先 pull 再 push」,因此一次完整的同步会话通常消耗 2 次配额。

4.4 同步白名单

偏好同步并非全量,白名单维护在 apps/web/src/services/sync/settings.ts。README 明确提醒:新增可同步项必须在此维护,切勿加入任何密钥类字段——这从源头保证了图床密钥、AI 密钥永不离开用户本地。

五、预览分享:只读链接的创建、解锁与过期

5.1 创建 / 更新:POST /share

createShareHandler(apps/api/src/share.ts)接收 postId、htmlSnapshot(含 bodyHtml 与 stylesHtml)与可选的 passwordMode/password/expiresMode/title:

  • 快照经过 sanitizeHtmlSnapshot / sanitizeStylesSnapshot 清洗后才入库,且总大小上限 MAX_SNAPSHOT_BYTES = 2 MiB,超限返回 413。
  • 按 user_id + post_id 去重:分享 id 由 SHA-256(userId:postId) 前 12 位十六进制派生(deriveShareId),同一篇文章重复发布即更新内容,返回 updated: true。
  • 有效期模式:支持 1d / 7d / 30d / never,但免费用户强制 1d(plan === 'pro' ? requested : '1d')。
  • 密码模式:none(无密码)、auto(服务端生成密码并返回)、custom(自定义密码,长度等校验见 parseCustomPassword)。密码经哈希后入库,自动生成密码只在创建响应中返回一次。
  • 频控:免费用户每天(UTC)可创建/更新 2 次(SHARE_CREATE_LIMIT.free = 2),Pro 不限;超限返回 429 与 retryAfterSec。

5.2 只读访问:GET /s/:shareId

viewShareHandler 校验分享存在性与过期时间(过期返回 410 Gone);若设置了密码且访问 Cookie 中无有效访问 token,则返回密码门页(buildShareGateHtml);通过后每次访问递增 view_count,并在页面底部注入作者信息与浏览量(injectShareFooter)。所有分享页响应都带 SHARE_PAGE_CSP 内容安全策略头,降低 XSS 风险。

5.3 解锁:POST /s/:shareId/unlock

unlockShareHandler 校验密码后,签发一个绑定分享 id 的访问 token 写入 httpOnly Cookie。为防暴力破解,按 unlock:<shareId>:<clientIp> 维度限制最多 20 次尝试(UNLOCK_ATTEMPT_LIMIT),超限跳转 ?error=rate_limited。

5.4 管理:GET /share 与 DELETE /share/:id

列表与取消分享均要求 Pro(requireProForShareManage,非 Pro 返回 403 pro_required)。列表返回 id/postId/title/url/viewCount/expiresAt/protected/expired,且不含 HTML 快照,避免大字段无谓传输;删除后链接立即失效。

六、主题 / 组件市场:发布、审核、安装闭环

市场路由集中在 apps/api/src/marketplace.ts,遵循「发布 → 待审 → 上架」流程:

6.1 公开浏览

  • GET /marketplace/themes、GET /marketplace/components:仅返回 approved 状态,支持 q(关键词,最长 64 字符)、sort(popular / newest)、page、pageSize(默认 20,最大 50)与分页元数据 total。
  • GET /marketplace/:id:详情接口,approved 内容公开;pending/rejected 仅作者或管理员可见,其他人一律返回 404。
  • POST /marketplace/:id/install:递增 download_count 并返回完整 payload。

6.2 发布与更新

登录用户 POST /marketplace/themes 或 /marketplace/components 后进入 pending,同时通过 notifyAdminsPending 通知所有管理员。作者可用 PATCH /marketplace/:id 更新(回退为 pending 重新审核)、DELETE /marketplace/:id 删除;GET /marketplace/me 查看自己的作品。

发布/更新均经过 apps/api/src/marketplace-validate.ts 的严格校验,要点:

  • 主题 CSS ≤ 200 KiB(MAX_THEME_CSS_BYTES),组件 JSON ≤ 50 KiB(MAX_COMPONENT_JSON_BYTES),示例 Markdown ≤ 32 KiB;
  • 名称 ≤ 64 字符、slug ≤ 48 字符、描述 ≤ 2000 字符、版本号 ≤ 32 字符;
  • 主题禁止 @import 与外链 url(https://…)(CSS_IMPORT_RE 等规则),从入口杜绝主题注入外部资源。

6.3 管理员审核

ADMIN_GITHUB_LOGINS(逗号分隔、大小写不敏感)命中的用户在 /me 中返回 isAdmin: true,可访问:

  • GET /marketplace/admin/pending:待审列表(支持 type/分页);
  • POST /marketplace/admin/:id/approve:通过并上架;
  • POST /marketplace/admin/:id/reject:驳回(可附 reason,最长 500 字符)。

审核结果会通过 notifyAuthorReviewResult 以站内通知形式反馈作者(对应 marketplace_approved / marketplace_rejected 通知类型)。发布频控为 UTC 日维度:免费 5 次/天、Pro 30 次/天,管理员豁免(相关常量与逻辑见 apps/api/src/marketplace.ts 与 apps/api/src/sync-limits.ts 同目录的测试文件 marketplace-validate.test.ts)。

七、云表情包:默认包 + 个人包

表情模块(apps/api/src/emojis.ts)分为两条线:

  • 公开线:GET /emojis/default 返回默认表情包清单(含元数据:来源、许可证、attribution 等);GET /emojis/assets/:id 代理表情资源,系统资源带长期 immutable 缓存,前端表情加载因此可享受缓存收益。
  • 个人线(均需登录):GET /emojis/me 获取或惰性创建个人表情包;PATCH /emojis/me 修改包名;POST /emojis/me/items 上传单个表情;DELETE /emojis/me/items/:id 删除单个表情;DELETE /emojis/me 删除整个个人包。

个人包上限为 100 项(EMOJI_MAX_ITEMS,见 apps/api/src/emoji-validate.ts),文件格式仅接受 PNG / JPEG / GIF / WebP,单文件最大 5 MiB(UPLOAD_MAX_BYTES)。

表情资源必须与默认图床的 UPLOAD_IMAGES 分开存放,因此部署时需创建两个专用 R2 bucket(见下文部署步骤),并通过 [[r2_buckets]] 绑定为 EMOJI_ASSETS(bucket_name 与 preview_bucket_name 均可按需改名)。

八、免费 / Pro 套餐体系

套餐定义与有效期计算集中在 apps/api/src/plan.ts:

能力 免费 Pro
手动同步 ✅ ✅
自动同步 — 编辑后约 3 秒
同步频率上限 30 次/小时 300 次/小时
分享(新建/更新) 2 次/天 不限
我的分享(管理/取消) — ✅

配套的存储配额为:文档 200(免费)/ 2000(Pro)篇,含墓碑的总行数 400 / 4000;市场发布频控 5 / 30 次每天;图床上传限流(UTC 小时)匿名 60 次、登录免费 120 次、Pro 300 次(见 apps/api/src/upload.ts 与 apps/api/src/upload-rate.ts)。

getEffectivePlan 是全局判定的唯一入口:仅当 plan === 'pro' 且 plan_expires_at > now 时才生效,否则一律回落 free。有效期按 爱发电每赞助 1 个月 = 31 天 Pro 折算(MS_PER_SPONSOR_MONTH = 31*24*60*60*1000),extendPlanExpires 支持在未过期的基础上累加时长。

九、爱发电 Pro 开通:Webhook 自动激活与手动激活

9.1 安全模型:回调内容一律不可信任

由于本服务代码公开托管,README 明确强调 Webhook 回调内容不可信任。因此 afdianWebhookHandler(apps/api/src/webhook.ts)的处理原则是:

  1. 若设置了 AFDIAN_WEBHOOK_TOKEN,仅接受 /webhooks/afdian/<token> 路径,其余路径返回 403;
  2. 从回调 body 中只取订单号 out_trade_no,其余字段(金额、方案、状态)一律忽略;
  3. 用订单号调用爱发电 Open API queryOrder 反查真实订单,仅当 status === 2(已支付)才继续;
  4. 从订单 remark 备注中解析 GitHub 用户名(支持 github:username 前缀或纯用户名,详见 parseGithubLoginFromRemark),命中用户后 activateProFromOrder 开通/顺延 Pro。

因此,伪造回调无法骗取 Pro;设置路径密钥还能防止公开端点被刷量、空耗爱发电 API 配额。

9.2 幂等与手动激活

activateProFromOrder 会先把订单号写入 afdian_orders 表,重复回调因 isOrderProcessed 检查而幂等。手动激活走 POST /sync/activate(需登录):提交订单号后服务端同样反查订单,并校验订单备注中的 GitHub 用户名与当前登录用户一致(不一致返回 403 remark_mismatch),从而兼顾了「他人代付」与「本人自助激活」两类场景。

十、默认图床上传:GitHub / R2 双后端代理

POST /upload(apps/api/src/upload.ts)由 UPLOAD_ENABLED 控制开关(关闭返回 404),通过 UPLOAD_BACKEND 选择后端:

  • GitHub(官方默认):需要 UPLOAD_GITHUB_TOKENS_BUCKETIO(逗号分隔的 GitHub PAT,仅存于服务端 secret);可选 UPLOAD_GITHUB_USERNAME、UPLOAD_GITHUB_REPO_LIST(留空默认 img0–img19)、UPLOAD_GITHUB_BRANCH、UPLOAD_GITHUB_USE_CDN。
  • R2(自行部署可选):创建 R2 bucket 并在 wrangler.toml 配置 [[r2_buckets]],设置 UPLOAD_BACKEND = "r2" 与 UPLOAD_R2_PUBLIC_URL。

上传仅接受 image/* 类型且 ≤ 5 MiB;限流按 UTC 小时计(匿名按 IP 维度 upload:ip:<ip>,登录用户按 upload:user:<id>)。前端在 apps/web/.env 设置 VITE_UPLOAD_VIA_API=true(须与服务端 UPLOAD_ENABLED 同步)后,默认图床即经 POST /upload 代理——GitHub PAT 不经过浏览器,这是该设计的核心安全收益。

十一、从零部署:完整步骤指南

以下步骤严格对应 README 部署章节,均需在仓库根目录执行(pnpm api 映射到 apps/api/package.json 中的脚本)。

11.1 创建 D1 数据库

pnpm api exec wrangler d1 create md-sync

把输出中的 database_id 填入 apps/api/wrangler.toml 的 database_id(当前文件内的 id 为 doocs/md 官方部署实例,fork 自部署务必替换为自有实例)。

11.2 创建表情专用 R2 bucket

pnpm api exec wrangler r2 bucket create md-emoji-assets
pnpm api exec wrangler r2 bucket create md-emoji-assets-preview

自行部署时可修改 wrangler.toml 中 EMOJI_ASSETS 的 bucket_name 与 preview_bucket_name。

11.3 执行数据库迁移

pnpm api db:migrate:local    # 本地开发库
pnpm api db:migrate:remote   # 生产库

迁移脚本位于 apps/api/migrations,0001_init.sql 建立了 users、documents、settings 三张核心表;后续迁移(0002_plan_and_afdian.sql 等)逐步加入计划、分享、市场、通知、表情包相关表结构。

11.4 配置 GitHub OAuth App

在 GitHub → Settings → Developer settings → OAuth Apps 新建应用:

  • Authorization callback URL:https://<your-worker-domain>/auth/github/callback(本地开发:http://localhost:8787/auth/github/callback)

11.5 设置密钥与变量

pnpm api exec wrangler secret put GITHUB_CLIENT_ID
pnpm api exec wrangler secret put GITHUB_CLIENT_SECRET
pnpm api exec wrangler secret put JWT_SECRET     # 任意高强度随机串
pnpm api exec wrangler secret put AFDIAN_API_TOKEN
pnpm api exec wrangler secret put AFDIAN_WEBHOOK_TOKEN  # 可选:Webhook 路径密钥

APP_URL、AFDIAN_USER_ID 等非敏感变量配置在 apps/api/wrangler.toml 的 <a href="https://link.gitcode.com/i/8de901f5a4e8ed622c64dfe20460cb62" target="_blank">vars] 段;本地开发可复制 [.dev.vars.example 为 .dev.vars 并填入密钥。

管理员配置:本地在 .dev.vars 中设置 ADMIN_GITHUB_LOGINS(逗号分隔的 GitHub login,大小写不敏感);生产用 wrangler secret put ADMIN_GITHUB_LOGINS(勿写入 wrangler.toml)。命中用户在 GET /me 中得到 isAdmin: true,并可访问 /marketplace/admin/*。

发布频控与内容约束(UTC 日):免费 5 次/天,Pro 30 次/天;主题 CSS ≤ 200 KB,组件 JSON ≤ 50 KB;主题禁止 @import 与外链 url(https://…)。

默认图床 API 上传:在 wrangler.toml 设置 UPLOAD_ENABLED = "true",并选择后端:

  • GitHub(官方默认):
pnpm api exec wrangler secret put UPLOAD_GITHUB_TOKENS_BUCKETIO   # 逗号分隔 PAT

可选变量:UPLOAD_GITHUB_USERNAME、UPLOAD_GITHUB_REPO_LIST、UPLOAD_GITHUB_BRANCH、UPLOAD_GITHUB_USE_CDN。

  • R2(自行部署可选):创建 bucket 并配置 [[r2_buckets]] 后,设置 UPLOAD_BACKEND = "r2" 与 UPLOAD_R2_PUBLIC_URL。

前端在 apps/web/.env 设置 VITE_UPLOAD_VIA_API=true(并与服务端 UPLOAD_ENABLED 同步)后,默认图床经 POST /upload 代理,GitHub PAT 不经过浏览器。上传限流(UTC 小时):匿名 60 次、登录免费 120 次、Pro 300 次。

11.6 爱发电配置

  1. 在爱发电开发者后台配置 Webhook:https://<your-worker-domain>/webhooks/afdian;若设置了 AFDIAN_WEBHOOK_TOKEN,地址改为 https://<your-worker-domain>/webhooks/afdian/<token>。
  2. 创建 Pro 赞助方案(月/季/年),引导用户在付款备注填写 GitHub 用户名。
  3. 可选:在 wrangler.toml 设置 AFDIAN_PRO_PLAN_IDS 限定可开通的方案 ID。

安全说明:本服务代码公开托管,Webhook 回调内容不可信任。Worker 收到回调后只取订单号,再用爱发电 Open API 反查真实订单(以服务端返回为准)后才开通 Pro,因此伪造回调无法骗取 Pro。建议同时设置 AFDIAN_WEBHOOK_TOKEN 作为路径密钥,防止公开端点被刷量、空耗爱发电 API 配额。

11.7 本地运行 / 部署

pnpm api dev      # 本地 http://localhost:8787
pnpm api deploy   # 部署到 Cloudflare

首次生产发布顺序:创建两个 R2 bucket → 应用 D1 迁移 → 运行经确认的远程种子 → 部署 Worker。后续代码发布只需先应用新增迁移,再部署 Worker。

Worker 改名迁移(md-sync → md-api):本服务的 Cloudflare worker 名已由 md-sync 更名为 md-api。若此前部署过 md-sync,首次 pnpm api deploy 会创建全新的 md-api worker,需要在新 worker 上重新设置所有 secret(见上方第 5 步),自定义域名 md-api.doocs.org 会指向新 worker;确认无误后可在 Cloudflare 控制台删除旧的 md-sync worker。D1 数据库(资源名仍为 md-sync)按 database_id 绑定,数据不受影响。

11.8 前端接入

在 apps/web/.env(参考 apps/web/.env.example)设置:

VITE_SYNC_API_URL=https://<your-worker-domain>
VITE_AFDIAN_PAGE_URL=https://ifdian.net/a/doocs
VITE_AFDIAN_ORDER_BASE=https://ifdian.net

官方 Pro 方案 plan_id(已写入 wrangler.toml 的 AFDIAN_PRO_PLAN_IDS):

档位 plan_id
月付 81efdc48655711f18b6d52540025c377
季付 ced9acca655a11f1a7cc52540025c377
年付 df5084a2655a11f1bea45254001e7c00

十二、设计说明与使用限制

  • 前端约定「先 pull 再 push」,push 仅返回本次被接受的记录与新游标,客户端需以此推进本地游标。
  • 偏好设置同步后会自动应用到当前页面,文章内容则为即时生效(前端订阅同步结果后直接更新编辑器状态)。
  • 同步白名单见 apps/web/src/services/sync/settings.ts,新增可同步项请在此维护,切勿加入任何密钥类字段。
  • 所有限流均以 UTC 时间片(小时/日)为单位,服务端通过 sync_rate_limits、share_rate_limits、marketplace_rate_limits 等表计数,超限响应统一携带 retryAfterSec 供客户端退避。

十三、延伸阅读

登录后查看全文
md