doocs/md 后端 API 全解析:基于 Cloudflare Workers + Hono + D1 的账户、云同步与 Pro 计费实现与部署

原创2026-09-21 23:07:182,224 阅读
文章标签:前端富文本开发工具国际化状态管理

doocs/md 后端 API 全解析:基于 Cloudflare Workers + Hono + D1 的账户、云同步与 Pro 计费实现与部署

本篇技术指南以 doocs/md 仓库的后端服务 apps/api/README.md 为骨架,系统拆解这套基于 Cloudflare Workers + Hono + D1 的无服务器 API:GitHub OAuth 登录与自有 JWT、文章/偏好的增量云同步(LWW 冲突合并)、预览分享、主题/组件市场、云表情包、免费/Pro 计费(爱发电开通)以及默认图床代理。读完本文,你将掌握该后端的路由全景、核心实现原理(游标、墓碑、幂等、限流)、全部环境变量与密钥含义,并能按 8 个步骤从零完成本地运行与生产部署,最后将前端接入。

一、整体架构:Worker + Hono + D1

该服务是 doocs/md 微信 Markdown 编辑器的后端 API,包名为 @md/api(见 apps/api/package.json),技术栈为:

  • Cloudflare Workers:无服务器运行时,入口为 apps/api/src/index.ts;
  • Hono:轻量 Web 框架,负责路由、CORS、中间件与请求处理;
  • D1:Cloudflare 的 SQLite 兼容数据库,存放用户、文档、偏好、市场条目等数据;
  • R2:对象存储,用于表情资源与分享页静态资源。

wrangler.toml 中的资源绑定如下(见 apps/api/wrangler.toml):

绑定 资源类型 用途
DB D1(数据库名 md-sync) 核心业务数据
EMOJI_ASSETS R2(bucket md-emoji-assets) 表情资源对象存储
ASSETS Workers Static Assets(./public) 分享页 favicon 等静态资源

README 给出两张核心数据流图,明确了「谁写给谁」:

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

对应到代码中,apps/api/src/index.ts 将路由分为两层:公共路由直接挂在 app 上(CORS 中间件、/upload、/auth、/webhooks/afdian、/s/:shareId、/marketplace、/emojis),需要登录的路由统一挂到子应用 api 上,由 authMiddleware 统一校验 Bearer JWT 并注入 userId。

CORS 部分值得注意:APP_URL 是一个逗号分隔的来源白名单,支持通配符 * 匹配单个主机标签(见 apps/api/src/origin.ts 的 matchPattern)。浏览器扩展的 chrome-extension://、moz-extension://、safari-web-extension:// 来源会被单独放行,保证扩展端也能调用 API。

二、接口全景:公共路由与认证路由

下面按 README 的接口清单逐组整理,并标注对应的处理器实现文件。

认证与账户(apps/api/src/auth.ts)

方法/路径 说明 登录要求
GET /auth/github 跳转 GitHub 授权 否
GET /auth/github/callback OAuth 回调,签发 JWT 后回跳前端(token 在 URL fragment) 否
GET /me 当前用户信息(含 plan、planExpiresAt、isAdmin) 是

增量云同步(apps/api/src/sync.ts、apps/api/src/db.ts)

方法/路径 说明 登录要求
GET /sync/pull?since=<ms> 拉取游标之后的变更 是
POST /sync/push 推送本地变更(LWW 合并) 是
POST /sync/activate 用爱发电订单号手动激活 Pro 是

预览分享(apps/api/src/share.ts)

方法/路径 说明 登录要求
GET /share 列出当前用户的分享(不含 HTML 快照) 是 + Pro
POST /share 创建/更新预览分享(按 user_id + post_id 去重) 是
DELETE /share/:id 取消分享,链接立即失效 是 + Pro
GET /s/:shareId 只读分享页(有密码时需先解锁) 否
POST /s/:shareId/unlock 校验分享密码并写入访问 Cookie 否

主题/组件市场(apps/api/src/marketplace.ts)

方法/路径 说明 登录要求
GET /marketplace/themes 已上架主题列表(支持 q / sort / 分页) 否
GET /marketplace/components 已上架组件列表 否
GET /marketplace/:id 详情(approved 公开;作者/管理员可见 pending/rejected) 否*
POST /marketplace/:id/install 安装(递增 download_count,返回 payload) 否
GET /marketplace/me 我的作品 是
POST /marketplace/themes / POST /marketplace/components 发布(进入 pending) 是
PATCH /marketplace/:id 作者更新(回到 pending) 是
DELETE /marketplace/:id 作者删除 是
GET /marketplace/admin/pending 待审列表 管理员
POST /marketplace/admin/:id/approve / reject 审核 管理员

* 详情接口会尝试解析可选的 Authorization 头,作者或管理员可查看非 approved 状态,其余人一律返回 404(避免泄露未上架内容,见 getMarketplaceItemHandler)。

云表情包(apps/api/src/emojis.ts)

方法/路径 说明 登录要求
GET /emojis/default 默认表情包清单 否
GET /emojis/assets/:id 表情资源(系统资源长期 immutable 缓存) 否
GET /emojis/me 获取或创建个人表情包 是
PATCH /emojis/me 修改个人表情包名称 是
POST /emojis/me/items 上传单个表情(PNG/JPEG/GIF/WebP,最大 5 MiB) 是
DELETE /emojis/me/items/:id 删除个人表情 是
DELETE /emojis/me 删除整个个人表情包 是

其他

方法/路径 说明 登录要求
POST /webhooks/afdian(及 /webhooks/afdian/:token) 爱发电订单 Webhook 否
POST /upload 默认图床上传(GitHub 或 R2,由 UPLOAD_BACKEND 配置) 否(带 token 可识别为登录用户)
通知接口 GET /notifications/、GET /notifications/unread-count、POST /notifications/read-all、POST /notifications/:id/read、DELETE /notifications/ 是

三、GitHub OAuth 登录与 JWT:两步跳转 + 自有令牌

/auth/github 处理器的完整流程(apps/api/src/auth.ts):

  1. 生成随机 state(CSRF 防护),写入 httpOnly Cookie md_oauth_state(有效期 10 分钟);
  2. 把请求中带的可选 redirect 参数通过 resolveRedirect 校验后写入 Cookie md_oauth_redirect——只有落在 APP_URL 白名单内的来源才会被记住;
  3. 跳转 https://github.com/login/oauth/authorize,携带 client_id、回调地址、scope=read:user 与 state。

回调 /auth/github/callback(apps/api/src/auth.ts):

  1. 校验 code 与 state 是否匹配 Cookie;
  2. 用 client_secret 向 GitHub 换取 access_token,再调用 api.github.com/user 获取 GitHub 数字 id、login、name 与头像;
  3. upsertUser 写入/更新 users 表(ON CONFLICT(github_id) 更新,见 apps/api/migrations/0001_init.sql 与 apps/api/src/db.ts 的 upsertUser);
  4. 用 JWT_SECRET 签发 HS256 自有 JWT,payload 含 sub(内部用户 id)与 login,有效期 30 天(TOKEN_TTL_SECONDS = 60*60*24*30);
  5. 回跳到白名单来源,token 放在 URL fragment(#account_token=...)中,避免进入服务端日志。

之后所有受保护接口都要求请求头 Authorization: Bearer <token>,authMiddleware 使用 hono/jwt 的 verify 校验签名,并把 sub 注入 userId(apps/api/src/auth.ts)。校验失败统一返回 401,错误码为 unauthorized 或 invalid_token。

四、增量云同步实现:游标、LWW 与墓碑

同步是这套 API 最核心的能力。前端约定「先 pull 再 push」,服务端围绕服务端时钟游标与客户端更新时间戳做两层合并。

pull:游标增量拉取

GET /sync/pull?since=<ms> 把 since 解析为毫秒游标,从 documents 与 settings 两张表中按 server_updated_at > cursor 查询,并按 server_updated_at ASC 排序后返回(apps/api/src/db.ts 的 pullChanges):

// 响应结构
{
  "documents": [ /* SyncDocument[] */ ],
  "settings":  [ /* SyncSetting[] */ ],
  "cursor": 1728000000000   // 本次返回记录的最大 server_updated_at
}

每次 pull 返回一个新的 cursor,客户端保存后用于下次请求,实现真正的增量同步。两张表都建有 (user_id, server_updated_at) 索引以支撑游标查询。

push:last-write-wins 合并

POST /sync/push 的处理链(apps/api/src/sync.ts):

  1. 限流前置:enforceSyncRateLimit 先查用户套餐并计数(详情见第九节);
  2. 体积检查:Content-Length 超过 SYNC_PUSH_LIMITS.maxRequestBytes(8 MB)直接返回 413;
  3. 结构校验:validatePushPayload(apps/api/src/sync-limits.ts)对每条文档/设置做字段级校验;
  4. 配额检查:推送前统计服务端已有活跃文档数与总行数(含墓碑),超出套餐上限返回 403 document_quota_exceeded;
  5. LWW 写入:pushChanges 逐条对比数据库中已有的 update_datetime(文档)或 updated_at(设置),只有客户端版本更新(或记录不存在)时才写入,从而保证 last-write-wins;
  6. 返回新游标:写入成功后,服务端用当前时间作为新的 server_updated_at,再经 pullChanges 取回被接受的记录与游标返回。

LWW 的判断逻辑在 apps/api/src/db.ts 的 pushChanges 中,文档按 update_datetime 比较:

// 伪代码:LWW —— 仅当客户端版本更新时写入
if (existing && existing.update_datetime >= doc.updateDatetime)
  continue
// INSERT ... ON CONFLICT(user_id, id) DO UPDATE SET ...

软删除墓碑与删除传播

删除操作并不物理删行,而是把 deleted 置 1 保留墓碑记录(documents.deleted INTEGER NOT NULL DEFAULT 0)。这样删除动作本身也能被后续 pull 增量传播到其他设备。为避免墓碑被滥用为存储 DoS,normalizePushDocuments(apps/api/src/sync-limits.ts)会在写入前把已删除文档的 title、content、history 全部清空。

推送校验参数速查

以下限制直接来自 apps/api/src/sync-limits.ts 的 SYNC_PUSH_LIMITS,超限会返回 413 并携带 max 字段:

参数 上限
单次推送文档数 maxDocumentsPerPush 100
单次推送设置数 maxSettingsPerPush 80
文档 id 长度 maxIdChars 128
标题字节数 maxTitleBytes 500 B
内容字节数 maxContentBytes 512 KB
历史条目数 maxHistoryItems 20
单条历史内容字节数 maxHistoryContentBytes 512 KB
设置 key 长度 maxSettingKeyChars 256
设置 value 字节数 maxSettingValueBytes 1 MB
请求体总字节数 maxRequestBytes 8 MB
单文档行估算字节数 maxDocumentRowBytes 1.8 MB(D1 行上限 2 MB 预留余量)

文档/行配额由 apps/api/src/sync-limits.ts 的 SYNC_STORED_DOCUMENT_LIMIT 与 SYNC_STORED_ROW_LIMIT 定义:免费用户活跃文档 200 篇 / 总行 400 行,Pro 用户 2000 篇 / 4000 行。行配额的存在是为了防止「删除 + 新建」反复消耗活跃数上限。另外,D1 单条 SQL 最多绑定 100 个参数,listExistingDocuments 因此按 99 个 id 为一组分块查询(见 apps/api/src/db.ts 的 D1_IN_ID_CHUNK)。

同步数据范围

同步只覆盖文章(含 history)与偏好白名单,不包含图床密钥、AI 密钥。白名单定义在前端 apps/web/src/services/sync/settings.ts 的 SYNC_SETTING_KEYS 数组中,包括主题(theme、themeSettings)、排版偏好(use_indent、use_justify、previewWidth)、UI 偏好(locale、viewMode、previewDevice)、非敏感 AI 参数(openai_type、openai_temperature、openai_max_token)、自定义内容(css_content_config、templates、custom_components、quick_commands)等;而 githubConfig、aliOSSConfig、s3Config 及所有 openai_key_* 均被显式排除。偏好同步后会自动应用到当前页面,文章则即时生效。

五、预览分享:快照、密码与访问控制

分享功能把编辑器预览的 HTML 快照发布为只读链接,实现细节集中在 apps/api/src/share.ts 与 apps/api/src/share-password.ts。

分享 id 与去重

分享 id 由 SHA-256(userId:postId) 取前 12 位十六进制生成(deriveShareId),因此同一用户对同一篇文章只会有一个分享记录:再次 POST /share 即为更新(响应中 updated: true),由数据库唯一索引 idx_shares_user_post (user_id, post_id) 兜底(见 apps/api/migrations/0003_shares.sql)。

过期策略与密码模式

  • 过期模式支持 1d / 7d / 30d / never 四档;免费用户固定为 1d,Pro 用户可自由选择(resolveShareExpiresAt 中 plan === 'pro' ? requested : '1d');
  • 密码模式支持 none(无密码)、auto(服务端生成 8 位密码并返回给发布者)、custom(自定义 4–64 位密码);
  • 密码使用 PBKDF2-SHA256、100,000 次迭代加盐哈希后存储,格式为 pbkdf2:100000:<salt>:<hash>,校验时使用恒定时间比较(apps/api/src/share-password.ts);
  • 分享页响应带有 SHARE_PAGE_CSP 内容安全策略,HTML 快照在入库前经过 sanitizeHtmlSnapshot / sanitizeStylesSnapshot 清洗(apps/api/src/share-sanitize.ts)。

解锁流程

访问受密码保护的分享时,GET /s/:shareId 返回密码门页面;POST /s/:shareId/unlock 校验密码后签发一个分享访问 JWT(typ: share_access)并写入 httpOnly Cookie(路径限定在 /s/:shareId),有效期取「分享过期时间」与「24 小时」的较小值。每个 IP 每小时最多尝试 20 次,超限返回 429 或重定向到 ?error=rate_limited。免费用户每日仅可创建/更新 2 个分享,Pro 不限;「我的分享」列表与管理/取消功能(GET /share、DELETE /share/:id)仅 Pro 可用,接口返回 403 pro_required。

六、主题/组件市场:发布、审核与版本管理

市场采用「公开浏览 + 登录发布 + 管理员审核」的模式(apps/api/src/marketplace.ts):

  • 发布者 POST /marketplace/themes|components 后条目进入 pending,同时向所有登录过的管理员推送 marketplace_pending 站内通知;
  • 管理员通过 GET /marketplace/admin/pending 查看待审列表,approve 后上架并通知作者 marketplace_approved,reject 时须附理由(≤500 字符)并通知作者 marketplace_rejected;
  • 管理员身份由 ADMIN_GITHUB_LOGINS(逗号分隔的 GitHub login,大小写不敏感)判定,见 apps/api/src/marketplace-admin.ts;
  • 作者更新条目(PATCH)后状态回到 pending 重新审核;版本号由服务端自动递增(bumpMarketplaceVersion,从 1.0.0 起 +0.0.1,满 10 进位,见 apps/api/src/marketplace-validate.ts),客户端传入的版本会被忽略;
  • 安装接口递增 download_count 并返回 payload。

发布校验与频控

校验规则集中在 apps/api/src/marketplace-validate.ts:

校验项 限制
主题 CSS 字节数 ≤ 200 KB
组件 JSON 字节数 ≤ 50 KB
示例 Markdown 字节数 ≤ 32 KB
主题禁用 @import 是
主题禁用外链 url(https://…) 是
组件模板禁止 <script>/<iframe>/<form> 等危险标签、on* 事件、javascript: 协议 是
slug 格式 ^a-z0-9?$,≤48 字符,全局唯一(slug 冲突返回 409 slug_taken)
组件名 PascalCase,≤64 字符
primaryColor 仅接受 #RGB / #RRGGBB / #RRGGBBAA 十六进制色值

发布频控按 UTC 自然日计数(marketplace_rate_limits 表):免费 5 次/天、Pro 30 次/天,管理员不受限;免费用户超限响应 429 并带 retryAfterSec(距次日 0 点的秒数)。数据库层面用 UNIQUE(author_id, type, slug) 保证同一作者不能重复发布同名条目(apps/api/migrations/0004_marketplace.sql)。

七、云表情包与资源代理

表情模块包含公开的默认表情包与登录用户私有的个人表情包(apps/api/src/emojis.ts):

  • 默认包:GET /emojis/default 返回清单(含 metadata 的来源、许可证等),GET /emojis/assets/:id 从 R2 读取并回源,系统资源响应 Cache-Control: public, max-age=31536000, immutable(一年不可变缓存),用户资源为 5 分钟缓存;
  • 个人包:GET /emojis/me 在不存在时自动创建,一个用户最多维护 100 项表情(EMOJI_MAX_ITEMS),超限返回 409 item_limit_reached;
  • 上传校验:仅接受 PNG/JPEG/GIF/WebP 四种格式,单文件 ≤ 5 MiB,且会做魔数(magic bytes)嗅探——声明的 MIME 与文件真实字节不一致时返回 mime_mismatch,防止伪装上传(apps/api/src/emoji-validate.ts)。对象 key 形如 user/<userId>/<id>.<ext>,写入 R2 失败会回滚删除对象;
  • 清理:删除单条表情会同时删除 R2 对象;DELETE /emojis/me 批量删除整个包的全部对象。

表情资源必须与默认图床的存储分开,这正是部署时要求单独创建 md-emoji-assets / md-emoji-assets-preview 两个 bucket 的原因。

八、默认图床:GitHub / R2 后端与限流

POST /upload 是默认图床的服务端代理(apps/api/src/upload.ts),由 UPLOAD_ENABLED 开关控制(值为 "true" 或 "1" 时启用)。后端由 UPLOAD_BACKEND 决定:

  • GitHub(官方默认):使用逗号分隔的 PAT 列表轮换上传,仓库名默认 img0–img19(UPLOAD_GITHUB_REPO_LIST 留空时自动生成),可选 CDN 与自定义分支;解析逻辑见 apps/api/src/upload-config.ts 的 parseGithubUploadConfig;
  • R2(自行部署可选):需在 wrangler.toml 配置 [[r2_buckets]],设置 UPLOAD_BACKEND = "r2" 与 UPLOAD_R2_PUBLIC_URL。

上传限流按 UTC 小时计数:匿名 60 次、登录免费用户 120 次、Pro 300 次(UPLOAD_RATE_LIMIT,实现于 apps/api/src/upload-rate.ts)。匿名与登录用户的区分方式是尝试解析可选的 Authorization 头:能解析出有效 JWT 就按用户维度计数并应用套餐限额,否则按 IP 维度计数。文件仅接受 image/*,单文件 ≤ 5 MiB(UPLOAD_MAX_BYTES)。

前端在 apps/web/.env 设置 VITE_UPLOAD_VIA_API=true(需与服务端 UPLOAD_ENABLED 同步)后,图床上传全部经 POST /upload 代理,GitHub PAT 不会经过浏览器。

九、免费 / Pro 套餐与爱发电计费

套餐能力对比

README 的套餐表原样如下:

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

以上额度在 apps/api/src/plan.ts 中均有常量定义:SYNC_RATE_LIMIT = { free: 30, pro: 300 }、SHARE_CREATE_LIMIT = { free: 2, pro: null }(null 表示不限)。同步限流表 sync_rate_limits 以 (user_id, hour_key) 为主键按 UTC 小时桶计数,超限返回 429 并附带 retryAfterSec 与 upgradeRequired(apps/api/migrations/0002_plan_and_afdian.sql)。

套餐有效性的判定在 getEffectivePlan:只有 plan === 'pro' 且 plan_expires_at > Date.now() 才算生效 Pro,过期自动回落免费。爱发电每赞助 1 个月 = 31 天 Pro 有效期(MS_PER_SPONSOR_MONTH = 31*24*60*60*1000),续费从当前到期时间往后顺延(extendPlanExpires)。

爱发电 Webhook 自动激活

README 的安全说明是整个计费设计的核心,值得完整保留:

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

对应实现(apps/api/src/webhook.ts + apps/api/src/afdian.ts):

  1. 若配置了 AFDIAN_WEBHOOK_TOKEN,仅 /webhooks/afdian/<token> 路径通过校验;
  2. 从回调体中只读取 out_trade_no,随后调用爱发电 Open API query-order 反查真实订单,并校验 status === 2(已支付)且 product_type 为 0(常规方案)或 1(一次性商品)——参见 isProEligibleOrder;
  3. 从订单 remark(付款备注)中解析 GitHub 用户名:支持纯用户名、github:用户名 前缀,或取第一个形似 GitHub 用户名的 token(parseGithubLoginFromRemark,见 apps/api/src/plan.ts);
  4. 通过 apps/api/src/plan.ts 的 activateProFromOrder 开通:按 login 查用户(大小写不敏感)、写入 afdian_orders 表保证订单幂等(重复回调不会重复累加时长)、更新 users.plan 与 plan_expires_at,三步用 env.DB.batch 原子执行。

爱发电 Open API 的请求签名采用 MD5(params + ts + user_id 与 token 拼接),时间戳取当前秒级 Unix 时间。

手动激活

登录用户也可在 POST /sync/activate 提交订单号手动激活(apps/api/src/activate.ts)。与 Webhook 的区别在于:手动激活要求备注中的 GitHub 用户名与当前登录用户一致(不一致返回 403 remark_mismatch),因此适合用户忘记开启自动开通或 Webhook 未命中场景;订单幂等逻辑两者共用 afdian_orders 表。

官方 Pro 方案的 plan_id(已写入 wrangler.toml 的 AFDIAN_PRO_PLAN_IDS,仅作参考):

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

十、完整部署指南(8 步)

以下部署步骤全部来自 README,命令基于 pnpm workspace 执行。

1. 创建 D1 数据库

pnpm api exec wrangler d1 create md-sync

把输出的 database_id 填入 apps/api/wrangler.toml 的 database_id。仓库中默认的 database_id 是 doocs/md 官方部署实例,自行部署(fork)时务必替换为自己的 ID。

2. 创建表情专用 R2 bucket

表情资源必须与默认图床的 UPLOAD_IMAGES 分开存放:

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

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

3. 执行迁移

迁移脚本定义在 apps/api/package.json,共 8 个版本:0001_init.sql(users/documents/settings)、0002_plan_and_afdian.sql(套餐列、爱发电订单、同步限流表)、0003_shares.sql(分享)、0004_marketplace.sql(市场)、0005_marketplace_sample_markdown.sql(示例 Markdown 列)、0006_notifications.sql(站内通知)、0007_emojis.sql(表情表)、0008_default_emoji_pack.sql(默认表情包种子数据)。

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

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)

5. 设置密钥与变量

敏感值一律用 wrangler secret put,切勿写入 wrangler.toml:

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/960ccd871990c5115da4b3c0bfc7147c" target="_blank">vars] 中;本地开发可复制 [apps/api/.dev.vars.example 为 .dev.vars 并填入密钥(注意 wrangler 本地会忽略 .dev.vars 中的 APP_URL 等 vars 项,需在 wrangler.toml 维护)。完整的 secret 清单也以注释形式写在 wrangler.toml 末尾。

主题/组件市场审核管理员:本地在 .dev.vars 中设置 ADMIN_GITHUB_LOGINS(逗号分隔的 GitHub login,大小写不敏感);生产用 wrangler secret put ADMIN_GITHUB_LOGINS。匹配的用户在 GET /me 中会得到 isAdmin: true,并可访问 /marketplace/admin/*。

默认图床 API 上传

在 wrangler.toml 设置 UPLOAD_ENABLED = "true",并选择后端:

GitHub(官方默认)

pnpm api exec wrangler secret put UPLOAD_GITHUB_TOKENS_BUCKETIO   # 逗号分隔 PAT

可选变量(均为 wrangler.toml 的 [vars] 或 secret):UPLOAD_GITHUB_USERNAME、UPLOAD_GITHUB_REPO_LIST、UPLOAD_GITHUB_BRANCH、UPLOAD_GITHUB_USE_CDN。

R2(自行部署可选)

  1. 创建 R2 bucket 并在 wrangler.toml 配置 [[r2_buckets]](注意此处是图床 bucket,不要与表情 bucket EMOJI_ASSETS 混淆);
  2. 设置 UPLOAD_BACKEND = "r2" 与 UPLOAD_R2_PUBLIC_URL。

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(不设置则任何已支付方案都可开通)。

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(见上方第 4 步),自定义域名 md-api.doocs.org 会指向新 worker;确认无误后可在 Cloudflare 控制台删除旧的 md-sync worker。D1 数据库(资源名仍为 md-sync)按 database_id 绑定,数据不受影响。

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

apps/web/.env.example 中还有两个可选开关:VITE_ACCOUNT_UI_ENABLED(是否在 UI 显示账户入口,默认已配置 API 即显示)与 VITE_SYNC_UI_ENABLED(是否显示云同步入口,可显式关闭),以及图床代理开关 VITE_UPLOAD_VIA_API=true(需与服务端 UPLOAD_ENABLED 同步)。

十一、说明与设计限制

README 末尾的约定与本仓库实现互相印证,作为收尾要点:

  • 先 pull 再 push:前端约定「先 pull 再 push」,push 仅返回本次被接受的记录与新游标。服务端在 pushChanges 中写入后用「当前时间 - 1ms」为游标回读已接受记录,保证客户端拿到的是服务端权威状态;
  • 偏好同步即时生效:偏好设置同步后会自动应用到当前页面,文章为即时生效;
  • 同步白名单维护:新增可同步项请在 apps/web/src/services/sync/settings.ts 的 SYNC_SETTING_KEYS 中维护,切勿加入任何密钥类字段;
  • 限流表复用:同步、分享、上传、市场发布的频率计数共用 share_rate_limits / sync_rate_limits / marketplace_rate_limits 三张表,按 UTC 时间桶(小时或日)为主键做原子自增,天然支持跨请求计数。

从源码结构看,这套 API 的每个模块都遵循「路由处理器 → 校验/业务逻辑 → D1 数据访问」的分层:路由集中在 apps/api/src/index.ts 及各模块入口,校验与限制(体积、格式、频控、配额)全部前置在写入之前,安全相关逻辑(Webhook 反查、密码加盐哈希、快照清洗、来源白名单)均以「公开代码可被攻击者研究」为前提设计。对于想 fork 自部署的用户,只需替换 D1 database_id、R2 bucket 与全部 secret,即可完整复刻官方后端能力。

登录后查看全文
md