GithubReadmeEnsemble (GRE)

GRE 是一个“胶水层”项目，用于把多种 GitHub Readme API 应用粘合在一起并通过 Docker 暴露统一入口。目前集成了：

• anuraghazra/github-readme-stats：统计卡片服务，对应路由 /anuraghazra/github-readme-stats.
• ryo-ma/github-profile-trophy：奖杯卡片服务，对应路由 /ryo-ma/github-profile-trophy.

未来可以在同一模式下继续追加更多应用。

目录结构

• server/：GRE 的 Express 入口，会复用 stats 的 API handler，并通过反向代理转发到 Deno 版 trophy。
• github-readme-stats/ 与 github-profile-trophy/：上游项目源码，仅用于本地/容器运行，已经在 .gitignore 中忽略，需自行 git clone。
• Dockerfile 与 docker-compose.yml：构建/运行 GRE。
• DOCKER.md：更详细的 Docker 指南。
• AGENTS.md：协作者指南，说明了项目约定。

本地开发

1. 克隆本仓库后，在根目录执行：

   git clone https://github.com/anuraghazra/github-readme-stats.git
   git clone https://github.com/ryo-ma/github-profile-trophy.git

2. 安装依赖：

   npm install
   (cd github-readme-stats && npm ci --omit=dev --ignore-scripts)

   本地运行需要 Node.js 22+ 与 Deno 1.42+。

3. 复制环境变量：

   cp .env.example .env.local
   # 填写 PAT_1、PAT_2...，以及可选的 PORT/TROPHY_PORT

4. 启动 GRE：

   npm start
   # 或 NODE_ENV=development npm start

   服务监听在 http://localhost:9103，可用以下请求测试：

   curl "http://localhost:9103/anuraghazra/github-readme-stats/api?username=anuraghazra"
   curl "http://localhost:9103/ryo-ma/github-profile-trophy/?username=ryo-ma"

Docker 运行

1. 按上面步骤准备好两个上游仓库源码，并创建 .env.local（确保配置了 PAT_1，可以追加 PAT_2 以缓解 GitHub API 限流）。

2. 构建并启动：

   docker compose up -d --build

   Compose 会以单个服务 gre 暴露端口 9103，内部还会自动启动子进程来运行两个项目。

更多参数、环境变量说明可查看 DOCKER.md。

访问白名单

GRE 默认只允许 huangwb8 这个用户名访问卡片接口。如果需要调整，编辑 .env.local 中的 GRE_ALLOWED_USERS（逗号分隔）。该设置会同时作用于：

• /anuraghazra/github-readme-stats/api 及其子路由（pin、top-langs、wakatime 等）。
• /ryo-ma/github-profile-trophy/ 代理入口。

当传入的 username 不在名单内时，接口会返回 HTTP 403，并在响应体里列出已允许的用户。若某些路由（例如 gist 卡片）不依赖 username，仍可使用 WHITELIST、GIST_WHITELIST 等上游变量进一步收紧权限。

如何获取 PAT（PAT_1）

1. 登录 GitHub，打开右上角头像 → Settings → 左侧最底部 Developer settings。
2. 在 Personal access tokens 中选择 Fine-grained tokens 或 Tokens (classic)，点击 Generate new token。
3. 填写名称（例如 gre-self-host），可选设置过期时间；权限保持最小化即可：
   • Fine-grained token：选择要访问的仓库（或 “All repositories”），在 Permissions 中仅勾选 Contents: Read-only。
   • Classic token：开启 repo:public_repo 即可（若完全不需要私仓数据，可以取消其它勾选）。
4. 提交后 GitHub 会展示一次性 token，将其复制到 .env.local 中的 PAT_1=。
5. 如需更高的速率，可继续生成额外 token 并分别填入 PAT_2、PAT_3……GRE 会按顺序轮询使用它们，并在内部自动映射到 github-profile-trophy 所需的 GITHUB_TOKEN1/2/... 环境变量。

安全提示：.env.local 已在 .gitignore 中，不会被提交；但仍请妥善保管，不要在 issue、日志或截图中泄漏。