一同看（YiTongKan）项目文档 版本：2026-04-24 · Cloudflare 迁移完成后的当前生产形态

React + Vite Tailwind + MUI/Radix Cloudflare Workers D1 × 21 KV R2 Queues Durable Objects Analytics Engine

配套文档：环境.md（密钥/账号/踩坑） · migration-tasks.md（阶段进度） · docs/d1-shards.md（分片细节） · docs/analytics-grafana.md

1. 系统概览

一同看是一个视频/图文内容聚合站，原架构为单机 PHP + MySQL（149.28.233.43），为承载 ~100 万 DAU 的目标，整体迁移到 Cloudflare 无服务器栈。

关键设计决策

2. 运行时拓扑

2.1 域名 / 服务映射

2.2 生产机

两台机每 10 分钟跑 ytk_sync.sh（149 用 videocenter，108 用 yzm），把增量行 POST 到 /admin/sync，再做第二遍 backfill（填时长/大小/下载地址）。

3. 前端（React + Vite）

3.1 技术栈

• React 18 + Vite + TypeScript（仓库 gayapp/YitongkanV2，由 Figma Make 初始化）
• Tailwind CSS v4（@tailwindcss/vite 插件）
• UI 组件：MUI + Radix UI（Dialog / Dropdown 等 headless 原语）+ lucide-react 图标 + motion/react 动画
• i18n：8 语言（zh-CN / zh-TW / en / vi / es / pt / ja / de），全部在 src/app/i18n/translations.ts 单文件 TypeScript 对象里，非 JSON
• 构建：npm run build（Vite 出到 dist/），CF Pages 自动部署到 ytk.yitongcs.com

3.2 目录结构（frontend/src/）

main.tsx                         Vite 入口
app/
  App.tsx                        路由分发 + 顶层状态
  components/                    各业务组件（*.tsx）
  context/                       React Context providers（Router / Language / User）
  hooks/                         自定义 hooks
  i18n/
    translations.ts              8 语言 UI 文案
    aboutContent.ts              关于/隐私/条款长文
    errorMap.ts                  后端 code → 本地化 message
imports/                         Figma Make 导入资源
lib/
  api.ts                         Workers API 客户端 + 数据类型
  fingerprint.ts                 Fingerprint.com 集成
styles/                          全局样式

3.3 与后端的契约

• 所有 API 以 /api/ 开头，发到 ytk-api.yitongcs.com
• 登录态：Authorization: Bearer base64(${userId}:${token})，token 存 localStorage 的 ytk_uid / ytk_token；服务端在 KV user:{token} 持久化身份 JSON
• 旧接口（/api/Gv/*、/api/Video/*、部分 /api/content/*/play 与 /download）由 Workers 透传到 PHP_ORIGIN
• 人机校验用前端滑块（/api/auth/slider-challenge），不再走 PHP 验证码

4. Workers API 层

4.1 代码结构（workers/src/）

index.ts                 主路由分发（1500+ 行，按前缀分支）
types.ts                 Env / 数据类型
do/                      Durable Object（CounterAggregator）
middleware/
  cors.ts                CORS 头
  fetch.ts               6s 超时包装
  metrics.ts             AE 上报（每请求）
  proxy.ts               proxyToPhp 白名单透传
routes/
  base.ts                /api/base/bootstrap
  content.ts             /api/content/* （热门列表 + 缓存 epoch）
services/
  auth / avatar / comments / content / dbproxy / domainshare
  email / favorites / feedback / filters / fingerprint
  history.ts             ★ 观看历史（分片 + 时长自愈）
  history_archive.ts     90 天归档到 R2 + 校验
  media / notifications / order / pay / profile
  search_log / shards.ts ★ 分片路由工具
  slider / usersite / views / votes / alerts
utils/
  cache.ts               边缘 caches.default 封装
  response.ts            JSON / CORS 响应包装

4.2 路由清单（~60 个端点）

公共 / 基础

• GET /api/base/bootstrap — 启动配置（60s edge cache）
• GET /api/auth/slider-challenge · POST /api/auth/slider-verify
• GET /api/auth/test-domain · POST /api/auth/report-test-domain

登录 / 注册

• POST /api/auth/register|login|logout
• POST /api/auth/referral — 邀请码

会员

• GET /api/member/me — 资料 + VIP 状态
• GET /api/member/vip|flow · GET /api/member/invite/stats|list
• GET/PATCH /api/member/profile · PATCH /api/member/password
• POST /api/member/avatar（R2）· POST /api/member/bind-uc
• POST /api/member/email/send-code|verify
• POST /api/member/order/create

收藏（D1 / DB_FAV）

• GET /api/member/favorites · GET /api/member/favorites/check · POST /api/member/favorites

观看历史（D1 分片 × 16）

• GET/POST/DELETE /api/member/history
• GET /api/member/history/archive — 查询归档（>90d）

站内信 / 反馈 / 评论

• GET /api/member/notifications · GET /api/member/notifications/unread-count · POST /api/member/notifications/read-all
• POST /api/member/feedback · GET /api/member/feedback/list
• GET/POST /api/comments（分片 by content_id%4）

搜索 / 内容 / 媒体

• GET /api/search/trending|recent · POST /api/search/log
• GET /api/content/gv?page=&page_size=&type=&sort=latest|favorites|random&seed=（60s edge + 600s KV，epoch 失效）
• GET /api/content/gv/:id · GET /api/content/gv/:id/play · GET /api/content/gv/:id/download
• GET /api/content/mv|tv|pic · GET /api/content/{sec}/:id · /play
• GET /api/content/search?wd=&section=&page=
• GET /api/Gv/list?page=（老版 App 兼容；/api/Gv/view · /api/Video/getVideoUrl 透传 PHP）
• /api/Gv/* · /api/Video/* — 透传到 PHP
• /api/media/* — m3u8 签名回源

管理 / 同步（双重门禁：X-Sync-Key header + CF-Connecting-IP IP 白名单）

默认白名单 = SYNC_ALLOWED_IPS（149.28.233.43 + 108.61.23.146 + 173.208.185.170 + 63.141.249.154，后两个是外部收藏同步源）；验证逻辑在 middleware/admin_auth.ts。

• GET /admin/sync/status — 当前 KV 游标 sync:max_tp_id
• POST /admin/sync · POST /admin/sync-meta — 批量 UPSERT / 回填 meta（10min cron 调用）
• GET /admin/videos/missing-duration|missing-meta — 列出缺字段的 GV 行
• POST /admin/videos/backfill-duration — m3u8 EXTINF 解析补时长（日 cron 也走这条）
• POST /admin/favorites/import — 收藏批量 / 增量导入；body {mode, uid?, rows[]}，mode ∈ {append, upsert, replace}，单次上限 1000 行；append 走 INSERT OR IGNORE（幂等），upsert 冲突更新 metadata，replace 先按 uid 清空再插入
• POST /admin/init-favcount / init-search-log / init-comments — 一次性迁移脚本，幂等回放
• POST /api/admin/history/archive · POST /api/admin/archive/verify · POST /api/admin/archive/snapshot-checksums — 归档 / 校验 / 月度 checksum 转存
• POST /api/admin/notifications/create — 管理员发站内信 / 广播
• GET /api/admin/metrics/alerts — 手动触发 alert sweep（?webhook_test=1 测试联通）

4.3 中间件管线

5. 数据库说明

5.1 D1 实例清单（24 个）

5.2 主库 ytk 表结构

videos — GV 视频

CREATE TABLE videos (
  id               INTEGER PRIMARY KEY,
  type             INTEGER DEFAULT 0,
  index_pic_path   TEXT,
  orgfile          TEXT,
  md5              TEXT UNIQUE,            -- UPSERT 冲突目标
  ts_480_path, ts_720_path, ts_1080_path TEXT,
  end_time         TEXT,
  scheck           INTEGER DEFAULT 0,
  -- 运行时 ALTER 追加列
  size_bytes       INTEGER DEFAULT 0,
  download_path    TEXT DEFAULT '',
  duration_seconds INTEGER DEFAULT 0,
  favorites_count  INTEGER DEFAULT 0
);
INDEX: type, end_time, favorites_count DESC, orgfile

其他主库表

• legacy_mv / legacy_tv / legacy_tv_episodes / legacy_images — 老版影/剧/剧集/图集，source_id 对应原 MySQL id
• feedback — 意见反馈，单表含状态机（open / replying / closed）
• site_config / hotlinks — 站点全局配置 + 防盗链 IP 白名单

5.3 分片数据库 schema

ytk-favorites

CREATE TABLE favorites (
  uid, section, content_id,
  title, cover, year, duration_seconds, added_at,
  PRIMARY KEY (uid, section, content_id)
);
INDEX idx_fav_uid_added (uid, added_at DESC)
INDEX idx_fav_content   (section, content_id)

ytk-comments-{0..3}

每分片独立 comments 表，id INTEGER PRIMARY KEY AUTOINCREMENT；跨分片 id 不保证全局唯一，API 总是带 content_id co-route 到同一分片，无歧义。

ytk-search-log

CREATE TABLE search_log (
  query     TEXT PRIMARY KEY,
  count     INTEGER NOT NULL DEFAULT 1,
  last_used INTEGER NOT NULL
);
INDEX idx_search_log_count (count DESC)
INDEX idx_search_log_last  (last_used DESC)

ytk-notifications

整体是"单库"不是分片，但文件名延续了 shard- 前缀，保留不改。

CREATE TABLE notifications (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  userid     INTEGER NOT NULL,   -- 0 广播 / >0 私信
  type, title, content, meta, created_at, expires_at
);
INDEX idx_notif_user_time (userid, created_at DESC)
INDEX idx_notif_expires_at

CREATE TABLE notification_reads (
  userid, notif_id, read_at,
  PRIMARY KEY (userid, notif_id)
);
INDEX idx_notif_reads_user (userid)

ytk-history-{0..15}

CREATE TABLE watch_history (
  uid, section, content_id, episode_id,
  episode_label, title, cover,
  progress, duration_seconds, watched_seconds, watched_at,
  PRIMARY KEY (uid, section, content_id, episode_id)
);
INDEX idx_history_uid_watched (uid, watched_at DESC)
INDEX idx_history_watched_at                           -- 归档 cron 用

5.4 分片路由（services/shards.ts）

historyShard(env, uid)          → env[`DB_HISTORY_${uid % 16}`]
commentsShard(env, contentId)   → env[`DB_COMMENTS_${contentId % 4}`]
allHistoryShards(env)           → D1Database[]   // 16 个
allCommentsShards(env)          → D1Database[]   //  4 个
shardIndex(key, n)              → ((k % n) + n) % n   // 纯函数，负数/NaN 兜底 0

5.5 关键索引与查询模式

5.6 一致性与去重策略

5.7 MySQL 残留

A. Workers 通过 db-proxy（ytk-db.yitongcs.com）直读/直写（workers/scripts/db_proxy.py 实际暴露的表）

B. 外部 cron（149 / 108 上的 ytk_sync.sh）直连 MySQL，增量同步到 D1

6. 对象存储 / KV / 队列 / DO / AE

6.1 R2 桶

6.2 KV Namespace 键空间

按功能域分组，以代码中实际前缀为准：

6.3 Cloudflare Queues（3 条）

6.4 Durable Object

CounterAggregator（src/do/counter.ts）— 单例 DO，接收 Queue 消费端聚合的计数增量，alarm() 每 30s 把汇总数写回 KV。设计上把 "N 次 D1/KV 写" 摊成 "1 次 KV 写"。

6.5 Analytics Engine

• Dataset：ytk_request_events（binding AE）
• 每请求 writeRequestMetric 一条：
  • indexes: [path]（归一化后）
  • blobs: [method, status, country, outcome, rayId]
  • doubles: [durationMs, status, responseBytes]
• 另有 writeCustomEvent 给 queue / cron / admin 非 HTTP 事件使用，outcome = queue|cron|admin 区分
• 查询方：Grafana（Infinity plugin）通过 CF AE SQL API 直读

7. 定时任务与自愈机制

7.1 Cloudflare Cron（wrangler.toml triggers）

7.2 外部 Cron（*/10 * * * * 在 149 和 108）

脚本：workers/scripts/ytk_sync.sh

1. GET /admin/sync/status → 取 KV 游标 sync:max_tp_id
2. SELECT ... FROM tp_video LEFT JOIN tp_legacy_video_meta WHERE id > cursor LIMIT 500
3. 拼 md5 列表，再 SELECT md5, duratio FROM (videocenter|yzm).yzm_video 查时长
4. POST /admin/sync 分批 500 行
5. Backfill 第二遍：GET /admin/videos/missing-meta?limit=500 → 查缺失 → 从上游补 → POST /admin/sync-meta

7.3 视频时长自愈（多层兜底）

历史现状：曾有 192 条旧视频上游 yzm_video.duratio 为 NULL，cron 的 duratio > 0 过滤永远填不回。已全部修复，当前 D1 videos 缺时长数 = 0 / 89,786。

机制（从最即时到最兜底）：

1. 写时回填（services/history.ts#logWatch）— 客户端没传 durationSeconds，从 videos 查一次再写分片
2. 读时水合（services/history.ts#listHistory）— GV 历史行缺时长，批量查 videos 并回写分片
3. 反向回填（心跳 UPDATE）— 客户端心跳带真实时长时（HTML5 解析的 m3u8），若 videos.duration_seconds 为 0 则补齐
4. 管理员 / 定时 m3u8 解析（services/duration_backfill.ts）— 直接抓 450-bit m3u8 求和 #EXTINF（HTML5 播放器同款算法）。端点 POST /admin/videos/backfill-duration 手动触发；日 cron 03:00 自动 100 行/次兜底

8. 可观测性与告警

8.1 Grafana

• 数据源：Cloudflare Analytics Engine SQL（Infinity 插件）+ Prometheus（db-proxy /metrics）
• 主要图表：QPS / p50-p99 latency / 5xx 率 / D1 DB size / Queue 积压 / db-proxy 5xx

8.2 告警规则（每 5 分钟）

8.3 Logpush

Workers 请求日志推到 R2（见 docs/logpush-setup.md），30 天保留；历史排查跨 AE 查询窗口时使用。

9. 内容审核与安全

用户提交的任何自由文本（评论 / 昵称 / 个人简介，未来加头像）都经过两道门：本地消毒 + 远程 AI 审核。SQL 注入在 D1 prepared-statement 层天然免疫，XSS 在 React {text} 渲染层天然转义——这两道门是纵深防御。

9.1 消毒 sanitizeUserText

9.2 AI 审核（aicenter-api.1.gay · 异步模式）

POST https://aicenter-api.1.gay/v1/moderate
headers:
  x-app-id:    ${MODERATION_APP_ID}
  x-timestamp: <unix seconds>
  x-nonce:     <32 hex chars>
  x-signature: HMAC-SHA256( MODERATION_SECRET, `${ts}\n${nonce}\n${sha256(body)}` )
  content-type: application/json
body: { biz_type, biz_id, content }

biz_type 接入矩阵（异步）

pending 存储

• 评论：D1 shard comments.status TEXT DEFAULT 'visible'，新插入行显式 ='pending'
• 资料：KV profile_pending:{uid} = {nickname?, intro?, submittedAt}，TTL 24h（兜底过期防 worker 崩时残留）

可见性过滤

• listComments：WHERE (status='visible' OR user_id=<currentUserId>)，作者自看 pending，别人不见
• listComments 禁止回复 pending 评论（parent 必须已 visible，防 reply-to-own-pending 绕审）
• getProfileWithPending 只在本人调用时把 pending KV 值覆盖到 MySQL 字段；其他场景（评论卡片显示 username 等）读 MySQL 纯净值

9.3 异步审核工作流

评论（services/comments.ts）

POST /api/comments
  ├─ sanitize + validate parent
  ├─ INSERT comments (..., status='pending')
  ├─ ctx.waitUntil(moderateCommentAsync(...))
  └─ return 200 + item (status='pending', pending=true)

moderateCommentAsync (fire-and-forget):
  ├─ moderateText('comment', ...)
  ├─ if reject:  DELETE comments WHERE id=? + createNotification(author)
  ├─ elif pass / softFail:  UPDATE comments SET status='visible'
  └─ never throws (log & resolve)

资料（services/profile.ts）

PATCH /api/member/profile
  ├─ validate
  ├─ commit non-text fields (sex, birthday) to MySQL synchronously
  ├─ sanitize nickname/intro → KV profile_pending:{uid} (TTL 24h)
  ├─ ctx.waitUntil(moderateProfileAsync(...))
  └─ return 200 + profile (含 pending 字段)

moderateProfileAsync (per-field, 独立决策):
  ├─ for each field in {nickname, intro}:
  │    ├─ moderateText('nickname' | 'bio', ...)
  │    ├─ if reject:  drop from KV + notify
  │    └─ elif pass / softFail:  dbUserUpdate + clear KV
  └─ never throws

9.4 Secrets

9.5 SQL 注入 / XSS 防线

10. 分享域名检测 / 裂变拉新

两个系统都围绕"怎样让一个已登录用户把别人拉进来"这件事运作，共用 services/domainshare.ts 里的 TOTP 签名和 tp_share MySQL 表。

10.1 共用基础：TOTP 签名

domain-share.gv.live 上游用 TOTP（RFC 6238，HMAC-SHA1，30s 步长，6 位）校验请求合法性。代码在 services/domainshare.ts#generateTOTP：

counter = floor(now / 30)
hmac    = HMAC-SHA1(DOMAIN_SHARE_SECRET, counter-as-8-byte-BE)
code    = (dynamic-trunc(hmac) & 0x7FFFFFFF) % 10^6
header: X-Dynamic-Token: <6 digits>

Secret 经 wrangler secret put DOMAIN_SHARE_SECRET 布置；PHP 端用 OTPHP 的 Base32 包装在内部一层，线上对等（wrap 抵消）。

10.2 分享域名分配 & 可用性检测（反 wall 基础设施）

为什么需要：CN 大陆会封主域，分享链路常失效。域名池（domain-share.gv.live 维护）实时下发"当前能用"的域名，每个 (uid, device) 拿到可能不同，方便定向封禁。

request.cf → 域名池入参：cfToRegionCarrierCountry() 从 CF 边缘拿 country / region / asOrganization，并做两步归一化：

• region：去掉"省"/"市"/"自治区"/"特别行政区"后缀
• carrier：匹配 移动|联通|电信 / Mobile|Unicom|Telecom|ChinaNet 归类三大运营商

只有 country=CN && region ∉ {HK, MO, TW} && carrier 非空 才真的调 /api/domain/test。

上游端点（domain-share.gv.live 提供）：

• GET /api/domain/assign?site_id=&device_id=&user_id= → {code:1, data:{domain}}（永久分配）
• POST /api/domain/test { site_id, region, carrier } → 下发测试域名
• POST /api/domain/report { site_id, domain, status, device_id, region, carrier, country, ip } → 回报

10.3 分享 URL 暴露

/api/member/me 响应里含 shareDomain: "https://gvm1.fun/?fxid=<uid>"，前端"邀请好友"弹窗 / 战绩页直接用这个 URL 拼二维码或复制链接。未登录或 deviceCode 丢失的老会话返回 null，前端降级展示。

10.4 裂变拉新：fxid 归因与奖励

fxid 归因有两条并行通道：localStorage + body（主）和 HttpOnly cookie（fallback，仅主站生效）。前端入口分布在多个分享域（gvm1.fun / gvm2.fun / … 经 domain-share 动态下发），所以主路径必须不依赖跨站 cookie。

流程（代码：frontend/src/lib/api.ts + workers/src/services/auth.ts）：

1. 引流：A 分享 https://gvm1.fun/?fxid=<A.uid> 给 B
2. 落地：B 打开该 URL，App.tsx 在 mount 钩子里：
   1. storeFxid(A.uid) → 写 localStorage（key: yitongkan.fxid）
   2. rememberReferral(A.uid) → POST /api/auth/referral 设 HttpOnly cookie。仅同站（主站或 pages.dev 预览）才真正发请求；分享域上 rememberReferral 直接 return false 跳过，避免必败的跨域 preflight
   3. 从 URL 剥掉 fxid= 参数并 history.replaceState，防止刷新再触发
3. 注册：B 进注册页，RegisterPage 调 readStoredFxid() 读 localStorage → 作为 body.fxid 塞进 POST /api/auth/register。Workers handler 先信 body.fxid，为空才 fallback 读 cookie：

   let fxid = Number(body.fxid) || 0;
   if (!fxid) fxid = Number(readCookie(request, 'fxid')) || 0;

   拿到 fxid 后：创建 tp_user + 送初始流量（tp_flows）；若 fxid > 0 && fxid ≠ B.id → dbShareCreate 写 tp_share（good=1, is_dood=1）
4. 奖励（feature:workers_register_reward=1 灰度）：dbUserAddVipDays(A.id, N) 给 A 加 VIP 天
5. 反刷单（入站顺序）：
   • ipreg:{ip}（30d）：同 IP 30 天只允许注册一个账号
   • fp:{fingerprint}（7d）：设备指纹去重
   • tp_blacklist 校验
   任一命中 → 注册被拒，fxid 无效

跨域名场景的归因局限（已知取舍）

对冲方式：生成分享链接时让同一用户所有入口走一致的分享域（domain-share 的 /api/domain/assign 对同一 (uid, device) 返回稳定结果，满足这点）。

10.5 邀请战绩

10.6 相关 Secrets / 配置

10.7 风险 / 已知坑

• TOTP 30s 窗口：Worker 和 domain-share 时间漂移 > 15s 会令牌失效。CF 边缘时间精度足够，未触发过
• fxid cookie 只 5h TTL：cookie 通道仅主站有效且 5h 到期；localStorage 主路径不受此限
• feature:workers_register_reward=1 必须单独开：默认 NOT 给邀请者加天，只开 feature:workers_register=1 是注册迁 Workers 但不走奖励

10.8 裂变反作弊（注册流水线）

POST /api/auth/register 按固定顺序跑 7 道检查。不是拒登 vs 放行的二元逻辑 —— 前 4 道硬拒（HTTP 201 业务错），后 3 道失败也让账号创建成功，只把 trial_vip 压到 0。这是刻意设计：让攻击者看不出在哪条规则卡了，同时把奖励经济绑死在 trial_vip > 0 上。

通过全部 7 道的用户：

• trial_vip = now + 3600s（1 小时试用 VIP，常量 REGISTRATION_GRACE_VIP_SECS）
• fp:{visitorId} 立即 markFingerprintSeen（永久标记）
• ipreg:{ip} 立即 markIpRegistered（30 天标记）

"同一设备 / 同一 IP 多久后再算新用户？"（业务答疑）

设备指纹和 IP 的生命周期不同，两道门独立作用：

为什么 fp 选永久 TTL？直译 PHP 的 Cache::set ttl=0。业务侧取舍是"宁可错杀诚实老用户换新机的 trial VIP，也不给刷号者返回试用"。如果以后放宽，改成 { expirationTtl: 86400*180 }（180 天）即可；只涉及 markFingerprintSeen 一行。

邀请者奖励（AND 四条件才给）

• opts.rewardEnabled（KV feature:workers_register_reward=1）
• fxid > 0（归因到合法邀请人）
• vipTime !== 0（被邀请人自己通过了所有反作弊门）
• referrer.id !== newUserId（防自邀）

满足才调：

• dbUserAddVipDays(referrer.id, 1) — 邀请者 VIP +1 天
• dbShareCreate(..., good=1, is_dood=1) — 写 tp_share

登录路径也续 ipreg:{ip} 30 天锁（见 handleLogin 尾部）：老用户登录续锁，防止攻击者"先登录让 IP 看起来有人，再换小号注册绕 IP 门"。

已知局限

• Slider HMAC 挡不住 headless browser 真滑动 —— 挡得住脚本 POST，挡不住专业刷号平台
• Fingerprint.com incognito=false 对隐私模式敏感 —— 老 iOS Safari、某些 Brave 模式会被误判 !clean，trial VIP 被没收；业务侧接受（偏执默认）
• fp:{visitorId} 永久 TTL 的双刃剑 —— 同一真实用户换浏览器 / 清缓存就重置 visitorId，会拿到新 trial VIP（被薅羊毛）；反之老用户真的换设备要新试用也拿不到（被误杀）
• tp_share.good=1 写入即定格 —— 当前没有"被邀请人活跃度不够就把 good 降成 0"的 downgrade 流程；is_dood 字段预留但未使用

11. 开发 / 部署流程

11.1 目录 → 仓库映射

11.2 本地开发

# Workers 本地
cd workers && npm install && npx wrangler dev   # http://localhost:8787

# 前端本地
cd frontend && npm install && npm start         # http://localhost:4200

11.3 部署

# Workers
cd workers
CLOUDFLARE_API_TOKEN=$CLOUDFLARE_TEST_DOMAIN_API_TOKEN npx wrangler deploy
# 成功标志：Deployed ytk-api triggers

# Secrets
wrangler secret put M3U8_KEY      # 签名密钥
wrangler secret put AES_KEY       # 跨域分享

# D1 migration
wrangler d1 execute ytk           --file=schema.sql
wrangler d1 execute ytk-favorites --file=migrations/favorites.sql
wrangler d1 execute ytk-history-0 --file=migrations/shard-history.sql   # × 16
wrangler d1 execute ytk-comments-0 --file=migrations/shard-comments.sql # × 4

# 前端
cd frontend && npm run build
# CF Pages 接 GitHub 自动发布到 ytk.yitongcs.com

11.4 提交规范

feat:     新增功能
fix:      修复 bug
refactor: 重构，不改变行为
chore:    配置 / 依赖 / 脚本
docs:     文档

11.5 四阶段工作流（强制）

1. 分解任务 → 列步骤清单
2. 逐步执行 + 验收（curl / build / SSH）
3. 部署（wrangler deploy）
4. git commit & push

12. 成本预估

12.1 价格基准（Cloudflare 官方，2026-01）

12.2 用量假设（1M DAU 满载）

12.3 月成本估算（1M DAU 满载）

12.4 成本优化杠杆

13. 容量与扩展路径

13.1 当前硬上限

13.2 扩展预案

14. 待办与已知风险

14.1 待办

• frontend/ 仓库的 CI 没接 CF Pages 自动构建，目前手动 npm run build
• /admin/* 管理端点缺少前端管理面板，靠 curl + 脚本操作
• alerts.ts webhook 是临时 URL，应改为 Slack / 企业微信官方 hook
• 头像上传（POST /api/member/avatar）尚未接入 aicenter-api 审核；需要多开一个 /api/callback/moderation 异步回调端点 + 回调签名校验
• X-Sync-Key 共享秘钥需加 IP 白名单（已于 b007399 落地，middleware/admin_auth.ts + SYNC_ALLOWED_IPS）
• 归档 SHA-256 仅存 KV，KV TTL/丢 key 则无法校验（已于 2f14dfd 落地，月度 cron 把 arc:ck:* 转存 R2 checksums/...）

14.2 风险