doocs/md 后端 API 深度解析:Cloudflare Workers + Hono + D1 的账户、云同步与计费架构
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(公开清单与资源)。 - 登录区是一个独立的
apiHono 实例,通过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 实现,分为两步:
GET /auth/github:生成随机state(基于uuidv4),写入httpOnly、SameSite=Lax、有效期 600 秒的 Cookie,同时把经过resolveRedirect校验的前端来源写入md_oauth_redirectCookie,随后 302 跳转 GitHub 授权页(scope 仅申请read:user)。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)的处理原则是:
- 若设置了
AFDIAN_WEBHOOK_TOKEN,仅接受/webhooks/afdian/<token>路径,其余路径返回403; - 从回调 body 中只取订单号
out_trade_no,其余字段(金额、方案、状态)一律忽略; - 用订单号调用爱发电 Open API
queryOrder反查真实订单,仅当status === 2(已支付)才继续; - 从订单
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 爱发电配置
- 在爱发电开发者后台配置 Webhook:
https://<your-worker-domain>/webhooks/afdian;若设置了AFDIAN_WEBHOOK_TOKEN,地址改为https://<your-worker-domain>/webhooks/afdian/<token>。 - 创建 Pro 赞助方案(月/季/年),引导用户在付款备注填写 GitHub 用户名。
- 可选:在
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-apiworker,需要在新 worker 上重新设置所有 secret(见上方第 5 步),自定义域名md-api.doocs.org会指向新 worker;确认无误后可在 Cloudflare 控制台删除旧的md-syncworker。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供客户端退避。
十三、延伸阅读
- 后端入口与路由总览:apps/api/src/index.ts
- 认证与 JWT:apps/api/src/auth.ts
- 同步与配额:apps/api/src/sync.ts、apps/api/src/sync-limits.ts
- 分享全链路:apps/api/src/share.ts(含测试 apps/api/src/share.test.ts)
- 计费与限流:apps/api/src/plan.ts、apps/api/src/activate.ts
- 市场审核:apps/api/src/marketplace.ts、apps/api/src/marketplace-validate.ts
- 数据库结构:apps/api/migrations/0001_init.sql