doocs/md 后端 API 全解析:基于 Cloudflare Workers + Hono + D1 的账户、云同步与 Pro 计费实现与部署
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):
- 生成随机
state(CSRF 防护),写入 httpOnly Cookiemd_oauth_state(有效期 10 分钟); - 把请求中带的可选
redirect参数通过resolveRedirect校验后写入 Cookiemd_oauth_redirect——只有落在APP_URL白名单内的来源才会被记住; - 跳转
https://github.com/login/oauth/authorize,携带client_id、回调地址、scope=read:user与state。
回调 /auth/github/callback(apps/api/src/auth.ts):
- 校验
code与state是否匹配 Cookie; - 用
client_secret向 GitHub 换取access_token,再调用api.github.com/user获取 GitHub 数字 id、login、name 与头像; upsertUser写入/更新users表(ON CONFLICT(github_id)更新,见 apps/api/migrations/0001_init.sql 与 apps/api/src/db.ts 的upsertUser);- 用
JWT_SECRET签发 HS256 自有 JWT,payload 含sub(内部用户 id)与login,有效期 30 天(TOKEN_TTL_SECONDS = 60*60*24*30); - 回跳到白名单来源,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):
- 限流前置:
enforceSyncRateLimit先查用户套餐并计数(详情见第九节); - 体积检查:
Content-Length超过SYNC_PUSH_LIMITS.maxRequestBytes(8 MB)直接返回 413; - 结构校验:
validatePushPayload(apps/api/src/sync-limits.ts)对每条文档/设置做字段级校验; - 配额检查:推送前统计服务端已有活跃文档数与总行数(含墓碑),超出套餐上限返回 403
document_quota_exceeded; - LWW 写入:
pushChanges逐条对比数据库中已有的update_datetime(文档)或updated_at(设置),只有客户端版本更新(或记录不存在)时才写入,从而保证 last-write-wins; - 返回新游标:写入成功后,服务端用当前时间作为新的
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),超限返回 409item_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):
- 若配置了
AFDIAN_WEBHOOK_TOKEN,仅/webhooks/afdian/<token>路径通过校验; - 从回调体中只读取
out_trade_no,随后调用爱发电 Open APIquery-order反查真实订单,并校验status === 2(已支付)且product_type为 0(常规方案)或 1(一次性商品)——参见isProEligibleOrder; - 从订单
remark(付款备注)中解析 GitHub 用户名:支持纯用户名、github:用户名前缀,或取第一个形似 GitHub 用户名的 token(parseGithubLoginFromRemark,见 apps/api/src/plan.ts); - 通过 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(自行部署可选)
- 创建 R2 bucket 并在
wrangler.toml配置[[r2_buckets]](注意此处是图床 bucket,不要与表情 bucketEMOJI_ASSETS混淆); - 设置
UPLOAD_BACKEND = "r2"与UPLOAD_R2_PUBLIC_URL。
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(不设置则任何已支付方案都可开通)。
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(见上方第 4 步),自定义域名md-api.doocs.org会指向新 worker;确认无误后可在 Cloudflare 控制台删除旧的md-syncworker。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,即可完整复刻官方后端能力。