AI OSS Rank Worker 故障排除¶

常见问题¶

问题 1: 前端显示 "null 天前" 或 "最后更新：null 天前"¶

症状：

网站上的 AI 项目显示 "最后更新：null 天前"
浏览器 Console 可能显示 daysSinceLastCommit 为 null

原因： 当项目超过 90 天没有提交时，Worker 使用 since 参数查询 GitHub API，由于超出时间范围返回空结果，导致 lastCommitAt 为 null。

解决方案： Worker 现已添加回退机制：

首先使用 since 参数查询最近 90 天的提交
如果没有结果，则不带 since 参数重新查询
确保始终能获取到最后一次提交日期

验证修复：

# 1. 检查 API 返回
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh" | jq '.metrics | {lastCommitAt, daysSinceLastCommit}'

# 应该返回:
# {
#   "lastCommitAt": "2025-06-04T16:09:23Z",
#   "daysSinceLastCommit": 121
# }

# 2. 如果 lastCommitAt 仍为 null，重新同步项目
cd tools/ai-oss-rank-worker
npm run sync:repo owner/repo

# 3. 再次检查 API
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh" | jq '.metrics.daysSinceLastCommit'

受影响的项目：

超过 90 天未更新的项目
不活跃或已归档的项目

问题 2: 同步失败，显示 "Worker is not accessible"¶

症状：

✗ Worker is not accessible at https://ai-oss-rank-worker.jimmysong.io
✗ Please check:
✗   1. Worker is deployed and running
✗   2. Custom domain is configured (if using)
✗   3. Network connectivity

原因： 环境变量 WORKER_URL 设置了错误的值，或者自定义域名未配置。

解决方案：

选项 1: 使用 workers.dev 域名（推荐）

# 清除错误的环境变量
unset WORKER_URL

# 或者显式设置正确的 URL
export WORKER_URL=https://ai-oss-rank-worker.jimmysong.workers.dev

# 然后重试
cd tools/ai-oss-rank-worker
npm run sync:repo owner/repo

选项 2: 配置自定义域名 如果想使用 ai-oss-rank-worker.jimmysong.io：

在 Cloudflare Dashboard 配置自定义域名：
Workers & Pages → ai-oss-rank-worker
Settings → Domains & Routes → Add Custom Domain
输入：ai-oss-rank-worker.jimmysong.io
等待 DNS 生效（1-2 分钟）
测试连接：

curl https://ai-oss-rank-worker.jimmysong.io/healthz

更新环境变量：

export WORKER_URL=https://ai-oss-rank-worker.jimmysong.io

问题 3: Manifest 没有包含新添加的项目¶

症状：

添加了新的 AI 资源到 content/*/ai/
但 https://jimmysong.io/data/ai-projects-manifest.json 中找不到

原因： Cloudflare Pages 构建时没有运行 generate:ai-manifest 脚本。

解决方案：

# 1. 本地测试 manifest 生成
cd /path/to/website
npm run generate:ai-manifest

# 2. 检查输出
cat static/data/ai-projects-manifest.json | jq '.projectCount'
cat static/data/ai-projects-manifest.json | jq '.projects[] | select(.repo == "owner/repo")'

# 3. 如果本地正常，检查 package.json
cat package.json | grep generate:ai-manifest

# 应该看到:
# "build": "npm run generate:ai-manifest && npm run generate-analysis && ..."

# 4. 提交并推送，触发 Cloudflare Pages 构建
git add content/*/ai/new-project/
git commit -m "feat: add new project"
git push

# 5. 等待构建完成（2-3分钟），然后验证
curl https://jimmysong.io/data/ai-projects-manifest.json | jq '.projectCount'

问题 4: 前端不显示健康度指标¶

症状：

页面加载，但没有显示健康度徽章或指标
浏览器 Console 没有错误

可能原因和解决方案：

1. 数据尚未同步到数据库

# 同步项目
cd tools/ai-oss-rank-worker
npm run sync:repo owner/repo

# 验证数据
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh"

2. Front matter 缺少 github 字段

# content/zh/ai/project/index.md
---
title: "项目名称"
github: "https://github.com/owner/repo"  # 必需！
---

3. JavaScript 未正确加载

打开浏览器 DevTools → Network 标签
搜索 ai-health-indicators.js
确认文件已加载（状态 200）
检查 Console 是否有 JavaScript 错误

4. 缓存问题

# 清除浏览器缓存
# 或强制刷新: Ctrl+Shift+R (Windows/Linux) 或 Cmd+Shift+R (Mac)

问题 5: 健康度评分不准确¶

症状：

评分显示为 0 或异常低
标签不正确（如活跃项目显示为 Inactive）

原因： 数据过期或 GitHub API 数据不完整。

解决方案：

# 1. 重新同步项目
cd tools/ai-oss-rank-worker
npm run sync:repo owner/repo

# 2. 检查 GitHub API 数据
curl "https://api.github.com/repos/owner/repo" | jq '{stars, forks, open_issues, pushed_at}'

# 3. 验证 Worker 计算的评分
curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh" | jq '.scores'

# 4. 如果仍有问题，检查评分算法
# 参考: tools/ai-oss-rank-worker/src/config.ts

调试技巧¶

检查 Worker 日志¶

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

实时查看 Worker 的请求和错误。

本地测试 Worker¶

cd tools/ai-oss-rank-worker
wrangler dev --local --port 8787

然后访问 http://localhost:8787/healthz 测试。

检查数据库内容¶

cd tools/ai-oss-rank-worker

# 查询特定项目
wrangler d1 execute ai-oss-rank --command="SELECT repo_slug, locale, score_overall, recent_commits, last_commit_at FROM ai_projects WHERE repo_slug = 'owner/repo'"

# 查看所有项目数量
wrangler d1 execute ai-oss-rank --command="SELECT COUNT(*) as total FROM ai_projects"

# 查看最近更新的项目
wrangler d1 execute ai-oss-rank --command="SELECT repo_slug, analyzed_at FROM ai_projects ORDER BY analyzed_at DESC LIMIT 10"

测试 GitHub API¶

# 检查仓库信息
curl "https://api.github.com/repos/owner/repo"

# 检查提交历史
curl "https://api.github.com/repos/owner/repo/commits?per_page=1"

# 检查贡献者
curl "https://api.github.com/repos/owner/repo/contributors?per_page=1"

# 检查 API 限流
curl -H "Authorization: Bearer $GITHUB_TOKEN" "https://api.github.com/rate_limit"

联系支持¶

如果以上方法都无法解决问题，请提供以下信息：

问题描述：具体的症状和错误信息
项目信息：GitHub 仓库 URL
API 响应：

curl "https://ai-oss-rank-worker.jimmysong.workers.dev/api/health/owner/repo?locale=zh" | jq .

浏览器 Console 日志：截图或复制错误信息
Worker 日志：wrangler tail 的输出