一个基于 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
VISIT_DEDUP_TTL_SECONDS	否	访问计数去重窗口（秒），默认 600
MYSQL_URL	否	MySQL 连接串；用于访问计数与请求日志持久化
UVICORN_RELOAD	否	是否开启热重载，默认开启（1/true/yes）

所有接口支持通过 key 查询参数覆盖默认的 CNB_API_TOKEN，用于访问私有仓库：

/stars/your-org/your-repo?key=your_cnb_token

未提供 key 时会继续使用 .env 中的 CNB_API_TOKEN（仅限 api.cnb.cool）。缓存会按 token 隔离，避免混用私有数据。

端点	方法	所需权限	调用方
/{repo}	GET	repo-basic-info:r	RepoService/IssueService/StarService/PullService/ForkService
/{slug}/-/contributor/trend	GET	repo-code:r	CommitService/CodeService/ContributorService
/{repo}/-/members	GET	repo-manage:r	CommitService
/{repo}/-/issues	GET	repo-notes:r	IssueService/RepoService
/{repo}/-/pulls	GET	repo-pr:r	PullService/RepoService
/{repo}/-/build/logs	GET	repo-cnb-trigger:r	BuildService
/{repo}/-/releases/latest	GET	repo-code:r	ReleaseService
/{repo}/-/releases	GET	repo-code:r	ReleaseService
/{repo}/-/git/tags	GET	repo-contents:r	TagService
/{slug}/-/stars	GET	repo-basic-info:r	StarService
/{repo}/-/forks	GET	repo-base-info:r	ForkService
/{repo}/-/packages	GET	repo-basic-info:r	PackageService
/{repo}/-/git/contents/{path}?ref={branch}	GET	repo-code:r	RandomService

端点	方法	所需权限	调用方
/users/{username}	GET	公开	UserService
/users/{username}/calendar	GET	公开	CalendarService
/users/{username}/activities	GET	公开	UserService
/{repo}/-/git/usage	GET	公开	RepoService
/api/version	GET	公开	VersionService

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

部分徽章默认带 icon，可用 icon= 关闭默认图标，或用 icon=xxx 覆盖。

接口详情与参数以 /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）。