Skip to content

AI OSS Rank Worker API 文档

这个脚本用于从 GitHub API 获取项目的最后提交时间，并更新到 Cloudflare D1 数据库中。

✨ 特性

  • 自动重试机制：每个操作失败后自动重试最多 3 次
  • 指数退避：重试延迟逐渐增加（2 秒、4 秒、6 秒）
  • 速率限制处理：检测到 GitHub API 速率限制时自动等待重置
  • 网络错误恢复：处理临时网络故障和 Cloudflare D1 连接问题
  • 进度显示：实时显示处理进度和统计信息

📋 前提条件

  1. GitHub Personal Access Token - 配置访问令牌：

    export GITHUB_TOKEN="ghp_your_token_here"

    创建 Token：https://github.com/settings/tokens - 需要 public_repo 权限

  2. 安装依赖 - 安装必需的包：

    cd tools/ai-oss-rank-worker
npm install

🚀 使用方法

1. 更新缺失的项目（推荐）

只更新 last_commit_at 为 NULL 的项目：

npm run update:commits -- --only-null --remote

或使用便捷脚本：

bash scripts/update-missing-commits.sh

2. 更新所有项目

npm run update:commits -- --remote

3. 更新特定项目

npm run update:commits -- --repo owner/repo-name --remote

例如：

npm run update:commits -- --repo microsoft/autogen --remote

4. 限制处理数量（测试用）

npm run update:commits -- --only-null --remote --limit 10

📊 示例输出

🔍 Fetching projects from D1 database...
   Database: ai-oss-rank (remote)
   Only updating projects with NULL last_commit_at
   Found 44 unique repositories
   Processing limit: None

[1/44] Processing: owner/repo1
  ✓ Updated: 2025-10-04T12:33:20Z

[2/44] Processing: owner/repo2
  ⚠ Attempt 1 failed: D1 Error: fetch failed
  ↻ Retrying in 2s... (2 retries left)
  ✓ Updated: 2025-10-03T15:21:00Z

[3/44] Processing: owner/repo3
  ✗ Repository not found: owner/repo3

============================================================
Summary:
  Total repositories: 44
  Successfully updated: 42
  Failed: 2
  Skipped: 0
============================================================

⚙️ 配置选项

选项 说明 示例
--remote 操作远程 D1 数据库（必须） --remote
--only-null 只更新 NULL 值 --only-null
--limit N 限制处理项目数量 --limit 50
--repo owner/name 更新特定仓库 --repo microsoft/autogen

🔄 重试机制说明

GitHub API 重试

  • 最大重试次数：3 次
  • 重试延迟：1 秒、2 秒、3 秒（线性增长）
  • 不重试的情况：
  • 404 Not Found（仓库不存在）
  • 403 Forbidden（非速率限制的权限问题）

速率限制处理

GitHub API 速率限制：

  • 未认证：60 次/小时
  • 已认证：5000 次/小时

当检测到速率限制时：

  • 自动读取重置时间
  • 如果等待时间 < 1 小时，自动等待
  • 如果等待时间 > 1 小时，跳过该项目

D1 数据库重试

  • 最大重试次数：3 次
  • 重试延迟：2 秒、4 秒、6 秒（指数退避）
  • 常见错误：
  • fetch failed：网络临时故障
  • timeout：连接超时

🐛 故障排查

问题：GITHUB_TOKEN 未设置

错误信息：

❌ Error: GITHUB_TOKEN environment variable is not set

解决方案 - 设置环境变量：

export GITHUB_TOKEN="ghp_your_token_here"

问题：速率限制超出

错误信息：

✗ Rate limit or access forbidden
⏳ Rate limit exceeded. Reset at: 2025-10-04T13:00:00Z

解决方案 - 处理限流：

  1. 等待速率限制重置
  2. 使用 GitHub Personal Access Token 增加限额

问题：D1 连接失败

错误信息：

⚠ Attempt 1 failed: D1 Error: fetch failed
↻ Retrying in 2s... (2 retries left)

解决方案 - 自动重试：

  • 脚本会自动重试
  • 检查网络连接
  • 检查 Cloudflare 服务状态

问题：仓库不存在

错误信息：

✗ Repository not found: owner/repo

原因 - 可能的情况：

  • 仓库已删除或改名
  • 仓库变为私有
  • GitHub URL 配置错误

📝 注意事项

  1. 本地数据库 - 默认情况下本地数据库是空的，必须使用 --remote 标志
  2. 速率限制 - 建议设置 GITHUB_TOKEN 以增加 API 限额
  3. 批量更新 - 大量项目更新时建议分批进行
  4. 网络稳定性 - 重试机制可以处理临时网络问题，但长时间网络故障可能导致失败

🔍 查看当前状态

检查有多少项目缺失 last_commit_at：

npx wrangler d1 execute ai-oss-rank \
  --command "SELECT COUNT(DISTINCT repo_slug) as count FROM ai_projects WHERE last_commit_at IS NULL" \
  --remote --json

查看最近更新的项目：

npx wrangler d1 execute ai-oss-rank \
  --command "SELECT repo_slug, last_commit_at FROM ai_projects WHERE last_commit_at IS NOT NULL ORDER BY last_commit_at DESC LIMIT 10" \
  --remote --json