扩展到 500+ 项目配置指南¶

概述¶

本文档说明如何配置 Worker 以支持 500+ 个项目的每日完整同步。

配置参数¶

Cron 频率¶

[triggers]
crons = ["0 */2 * * *"]  # 每 2 小时整点运行一次

批处理大小¶

const MAX_PROJECTS_PER_RUN = 50;  // 每次处理 50 个项目

性能计算¶

时间规划¶

参数	值
项目总数	500
每次处理数量	50
需要运行次数	500 ÷ 50 = 10 次
Cron 频率	每 2 小时
完成一轮时间	10 次 × 2 小时 = 20 小时
每天运行次数	12 次
每天处理容量	12 × 50 = 600 个项目

执行时间估算¶

每个项目的处理时间：

GitHub API 调用：~1-2 秒
数据库写入：~0.1 秒
总计：~1.5-2.5 秒/项目

50 个项目的总执行时间：

预期时间：50 × 2 秒 = 100 秒（理想情况）
实际并发处理：约 20-25 秒（因为代码使用 Promise.all 等优化）
Cloudflare 限制：30 秒
结论：在安全范围内 ✅

GitHub API Rate Limit¶

限制说明¶

认证请求：5000 次/小时
每个项目：~5-10 个 API 调用（stars, forks, commits, contributors 等）
50 个项目：~250-500 个 API 调用
每 2 小时运行一次：远低于 5000 次/小时限制 ✅

监控建议¶

定期检查 API 使用情况：

curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/rate_limit

返回示例：

{
  "resources": {
    "core": {
      "limit": 5000,
      "remaining": 4750,
      "reset": 1728000000
    }
  }
}

部署步骤¶

1. 更新代码¶

确保以下文件已更新：

✅ wrangler.toml：cron = "0 */2 * * *"
✅ src/worker.ts：MAX_PROJECTS_PER_RUN = 50

2. 部署到 Cloudflare¶

cd tools/ai-oss-rank-worker
wrangler deploy

3. 重置游标（可选）¶

如果想立即开始新的同步周期：

wrangler d1 execute ai-oss-rank --command \
  "UPDATE sync_state SET value = '0' WHERE key = 'full-sync'"

4. 验证部署¶

检查 Cloudflare Dashboard：

进入 Workers & Pages
选择 ai-oss-rank-worker
进入 Triggers 标签
确认 cron 显示：0 */2 * * *

监控和日志¶

实时日志¶

wrangler tail

预期输出：

[CRON] Starting incremental sync at cursor 0/500
[CRON] Processed 50 projects (50 success, 0 failures)
[CRON] Next cursor: 50

查看同步状态¶

wrangler d1 execute ai-oss-rank --command \
  "SELECT key, value, updated_at FROM sync_state WHERE key = 'full-sync'"

输出示例：

┌───────────┬───────┬─────────────────────────┐
│ key       │ value │ updated_at              │
├───────────┼───────┼─────────────────────────┤
│ full-sync │ 150   │ 2025-10-07T06:00:51.123Z│
└───────────┴───────┴─────────────────────────┘

计算进度¶

# 当前进度百分比
echo "scale=2; (cursor / 500) * 100" | bc

故障排查¶

问题：Cron 未运行¶

检查项：

Cron 是否启用？

在 Cloudflare Dashboard 的 Triggers 页面检查

Worker 是否部署成功？

wrangler deployments list

查看错误日志：

wrangler tail --status error

问题：处理速度慢¶

可能原因：

GitHub API 限流：检查 rate limit
数据库写入慢：检查 D1 性能
网络延迟：GitHub API 响应慢

解决方案：

减少 MAX_PROJECTS_PER_RUN 到 30-40
增加 cron 频率到每小时一次（需要调整批大小）

问题：某些项目失败¶

查看失败日志：

wrangler tail | grep "failures"

常见失败原因：

404 错误：仓库不存在或已删除
403 错误：私有仓库或无权限
Rate limit：API 调用过多

性能优化建议¶

当前配置（推荐）¶

Cron：0 */2 * * *（每 2 小时）
批大小：50 个项目
完成时间：20 小时

激进配置（更快同步）¶

如果需要更频繁的更新：

crons = ["0 * * * *"]  # 每小时运行

const MAX_PROJECTS_PER_RUN = 50;

结果：

每天 24 次运行
24 × 50 = 1200 个项目/天
500 个项目在 10 小时内完成

权衡：

✅ 更快的同步速度
❌ 更高的 API 使用率
❌ 更多的 Worker 调用（可能增加成本）

保守配置（减少资源消耗）¶

如果遇到 rate limit 问题：

crons = ["0 */3 * * *"]  # 每 3 小时运行

const MAX_PROJECTS_PER_RUN = 70;

结果：

每天 8 次运行
8 × 70 = 560 个项目/天
500 个项目在 21 小时内完成

成本估算¶

Cloudflare Workers¶

免费额度：100,000 次请求/天
当前使用：12 次/天（cron）+ API 调用
结论：完全在免费额度内 ✅

Cloudflare D1¶

免费额度：5GB 存储，500 万次读取/天
当前使用：~1000 次写入/天，~500 行数据
结论：完全在免费额度内 ✅

GitHub API¶

免费额度：5000 次请求/小时
当前使用：~250-500 次/2 小时 = ~125-250 次/小时
结论：远低于限制 ✅

总结¶

配置优化后：

✅ 500 个项目在 20 小时内完成同步
✅ 每天至少同步一次所有项目
✅ 在 Cloudflare 和 GitHub 限制内
✅ 无需额外成本

下一步：部署并监控第一个完整周期！