一个基于 FastAPI 的 CNB（cnb.cool）图表与徽章（badge）渲染服务，输出 SVG / PNG，可直接嵌入到 README 或页面中。

• Star / Fork / Issue 历史趋势图（支持多仓库对比）
• 贡献者头像墙（contributors wall）
• 用户活跃度日历图（calendar）
• 徽章（badge）渲染：版本、发布、Star、Fork、License、构建状态等
• 随机图片跳转（从 CNB 仓库目录随机挑选图片）
• Redis 缓存 + 内存缓存降级
• 可选 MySQL 持久化（访问计数与请求日志）

• Python 3.10+
• FastAPI / Uvicorn
• httpx
• matplotlib / pandas / Pillow / lxml
• Redis（可选）
• MySQL（可选）

依赖列表见 requirements.txt。

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

项目启动时会自动加载 .env（通过 python-dotenv）。

最小可用配置：

CNB_API_TOKEN=your_cnb_token

完整环境变量说明如下。

变量	是否必须	说明
CNB_API_TOKEN	推荐	CNB API Bearer Token（避免限流 / 私有数据访问）
CNB_API_BASE_URL	否	CNB API 地址覆盖，默认 https://api.cnb.cool
REDIS_URL	否	启用 Redis 缓存；未提供则使用进程内缓存
CACHE_TTL_SECONDS	否	缓存 TTL（秒），默认 86400
MYSQL_URL	否	MySQL 连接串；用于访问计数与请求日志持久化
UVICORN_RELOAD	否	是否开启热重载，默认开启（1/true/yes）

MYSQL_URL=mysql+pymysql://user:password@127.0.0.1:3306/commitcool

不配置 MYSQL_URL 时：

• 服务仍可运行
• /badge/visit/{repo} 会回退为 unknown
• 请求日志不会落库

python main.py

默认监听：http://0.0.0.0:8000

关闭热重载：

UVICORN_RELOAD=0 python main.py

docker build -t commitcool .
docker run --env-file .env -p 8000:8000 commitcool

启动后访问：

• http://localhost:8000/healthz
• http://localhost:8000/stars/cnb/feedback

• /index.json（结构化分类数据，供前端渲染）
• /healthz

接口详情与参数以 /index.json 为准，public/index.txt 保持简洁说明（包含用户活跃徽章等）。 新增或变更接口时请同步更新 /index.json。

/index.json 额外包含以下元信息：

• commit：完整 SHA
• commit_url：由 repo_url 与 commit 拼接的提交链接

• main.py：启动入口
• app/main.py：FastAPI 应用装配
• app/controllers/：路由层
• app/services/：业务逻辑与渲染
• app/clients/：外部 API 客户端
• app/models/：数据库模型
• app/middlewares/：中间件（日志 / 落库）

本项目采用 MIT License（见 LICENSE）。