profile-summary-for-github 配置指南：API Token 与运行时参数详解

profile-summary-for-github 配置指南：API Token 与运行时参数详解

【免费下载链接】profile-summary-for-githubTool for visualizing GitHub profiles项目地址: https://gitcode.com/gh_mirrors/pr/profile-summary-for-github

本篇文章以 Documentation/Usage.md 为核心，系统讲解 GitHub 用户画像可视化工具profile-summary-for-github的完整配置方式：从 GitHub API Token 的生成与注入，到unrestricted、free-requests-cutoff、gtm-id等运行时参数的语义与用法。读完本文，你将掌握该项目的全部配置项及其底层生效机制，能够独立部署并针对不同场景（个人使用、公开服务、限流控制）进行定制。

一、配置入口概述

profile-summary-for-github 是一个基于 Javalin 的 Kotlin Web 服务，用于抓取 GitHub 用户数据并可视化展示（详见 README.md 与 Main.kt 中的路由与启动逻辑）。它的配置不依赖外部配置文件，而是全部通过 Java 系统属性（-D参数）或环境变量注入，由 Config.kt 统一读取。启动命令的基本形态为：

java -D参数名=参数值 -jar target/profile-summary-for-github-jar-with-dependencies.jar

其中profile-summary-for-github-jar-with-dependencies.jar是 pom.xml 中 maven-assembly-plugin 打出的包含全部依赖的可执行 Jar（finalName为profile-summary-for-github，assembly 插件追加jar-with-dependencies分类器），打包方式参见 Documentation/Building.md。

二、API Token 配置：突破 GitHub API 限流

2.1 不配置 Token 的默认限制

项目本身不限制请求次数，但 GitHub API 对匿名访问有严格的限流。按照官方文档，如果不设置任何 API Token，每小时大约只能获得 50 次请求配额（源码 GhService.kt 的注释中则指出空 Token 对应 60 次请求）。对于需要抓取多个用户、多个仓库的公开服务来说，这个配额几乎无法支撑正常访问。

2.2 配置单个 Token

要使用 API Token 运行应用，首先需要在 GitHub 的设置页面生成一个 Personal Access Token（在 GitHub 账户 Settings → Developer settings → Personal access tokens 中创建，Scope 至少需要能读取用户与仓库信息）。

生成后，通过-Dapi-tokens系统属性传入：

java \ -Dapi-tokens=your-token \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

2.3 配置多个 Token：成倍提升限流

官方文档特别强调：可以使用逗号分隔的 Token 列表来提升总限流额度：

java \ -Dapi-tokens=<Token A>,<Token B>,<Token C> \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

从源码看，这一机制在 GhService.kt 中实现：Config.getApiTokens()返回的字符串被split(",")拆分为多个 Token，每个 Token 各自构建一个带 OAuth2 凭证的GitHubClient，并分别封装出RepositoryService、CommitService、UserService、WatcherService四类服务实例。每次真正发起 GitHub API 调用时，都会通过：

val repos: RepositoryService get() = repoServices.maxByOrNull { it.client.remainingRequests }!!

动态选取当前剩余请求数最多的那个客户端，实现多 Token 之间的自动轮询与负载均衡；而remainingRequests则是所有客户端剩余配额的求和。因此每多一个 Token，公开服务的可用配额就近似线性增加，这正是“多 Token 提升限流”的底层原理。

2.4 环境变量注入方式（Heroku / Docker）

Config.kt 的读取逻辑是先查环境变量、再回落（fallback）到系统属性。环境变量的命名规则为：参数名转大写、连字符-替换为下划线_。因此api-tokens对应环境变量API_TOKENS，gtm-id对应GTM_ID。

这意味着同样的配置在 Documentation/Docker.md 描述的 Docker 部署场景下写作：

docker run \ -it \ --rm \ --name profile-summary-for-github \ -p 7070:7070 \ -e "API_TOKENS=<My Token A>,<My Token B>" profile-summary-for-github

而在 Heroku（项目根目录提供 Procfile 与 system.properties）上，则应直接配置同名环境变量。

三、核心运行时参数详解

除api-tokens外，Documentation/Usage.md 还定义了三个关键参数，均通过-D传入、由 Config.kt 解析。

3.1 unrestricted：放开用户限制

默认情况下，服务出于 GitHub API 配额保护的考虑，只会为满足条件的用户生成画像（详见下文限流逻辑）。如果你希望允许为任意 GitHub 用户构建画像，可以传入：

java \ -Dunrestricted=true \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

源码中Config.unrestricted()通过getProperty("unrestricted")?.toBoolean() == true解析，即只有显式传入true才生效（Config.kt）。在 UserService.kt 中，unrestricted是决定“能否加载用户画像”的最高优先级条件——只要它为真，就不再检查缓存与剩余配额，直接放行抓取。

3.2 free-requests-cutoff：免费请求阈值

当服务对外开放时，你可以在剩余请求数达到某个阈值后，要求用户先给 GitHub 仓库点 Star 才能继续使用。阈值通过-Dfree-requests-cutoff设置，其值表示“剩余请求数降到多少时开始触发 Star 要求”：

java \ -Dfree-requests-cutoff=1000 \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

例如设置为1000，意味着当 GitHub API 剩余配额降至 1000 次以下时，应用开始引导用户 Star 仓库以换取继续使用的资格。该值由 Config.kt 中的freeRequestCutoff()解析为整数，默认未设置时为null。

3.3 gtm-id：启用 Google Tag Manager

项目内置了 Google Tag Manager（GTM）统计埋点支持。只要传入一个合法的 GTM ID，该功能即被启用：

java \ -Dgtm-id=GTM-XXXXXX \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

从 Main.kt 的全局路由钩子可以看到，服务会在每次响应后把Config.getGtmId()的值（未配置则为空字符串）写入名为gtm-id的 Cookie，供前端统计脚本读取使用。若不需要统计功能，省略该参数即可。

3.4 参数速查表

四、配置参数的底层读取机制

所有参数最终都由 Config.kt 统一收敛，其核心是两个私有方法：

private fun getProperty(name: String): String? = getHerokuProperty(name) ?: System.getProperty(name) private fun getHerokuProperty(envStr: String) = ProcessBuilder().environment()[envStr.uppercase().replace("-", "_")]

• 优先读环境变量：ProcessBuilder().environment()拿到当前进程环境变量表，把参数名转大写、-替换为_后查表；
• 回落到 Java 系统属性：环境变量不存在时，才使用-Dxxx=yyy传入的系统属性。

这一设计让同一份配置代码同时兼容三种运行形态：本地java -D... -jar直接运行、Docker-e环境变量注入、以及 Heroku 环境变量配置，无需为不同部署方式编写不同的配置加载逻辑。

五、参数如何影响请求放行：完整链路

配置项不是孤立存在的，它们共同决定“某个用户的画像是否会被生成”。从 UserService.kt 可以看到核心判断逻辑：

val canLoadUser = Config.unrestricted() || (userCacheJson != null) || remainingRequests() > 0

即满足以下任一条件即可加载用户画像：

1. unrestricted=true：管理员显式放开限制，任何用户均可生成画像；
2. 命中本地缓存：该用户画像在 6 小时缓存有效期内（见 CacheService.kt，数据存放在 HikariCP 连接的内存 H2 数据库中，diffInHours <= 6视为命中），无需再消耗 GitHub API 配额；
3. 仍有剩余配额：GhService.remainingRequests（所有 Token 剩余请求数之和）大于 0。

当前端通过/api/can-load做预检查时（Main.kt），会先执行不消耗 API 请求的canLoadUserQuick，避免在配额耗尽时让用户干等。同时 Main.kt 对/api/*施加了应用层限流（每个客户端每 10 分钟 20 次请求），与 GitHub API 配额形成双重保护。

配合 GhService.kt 的两个后台定时任务，整个限流体系闭环运转：每 2 分钟主动 Ping 一次 GitHub API 以校准各 Token 的剩余配额；每 500 毫秒通过 WebSocket 将实时剩余配额推送给所有在线前端，让用户直观看到当前服务负载。

六、组合实战：完整启动命令

综合以上配置，一个面向公开服务、配置了多 Token 与统计埋点的完整启动命令如下：

java \ -Dapi-tokens=<Token A>,<Token B> \ -Dunrestricted=false \ -Dfree-requests-cutoff=1000 \ -Dgtm-id=GTM-XXXXXX \ -jar target/profile-summary-for-github-jar-with-dependencies.jar

• 若只做个人本地体验、配额压力小，可省略unrestricted与free-requests-cutoff；
• 若部署为完全公开的在线服务，建议配置多个 Token 并提供free-requests-cutoff引导用户 Star；
• 访问地址默认为http://localhost:7070（端口由 Main.kt 的Config.getPort() ?: 7070决定）。

七、注意事项与适用前提

• Token 的权限范围：所生成的 Token 至少需要具备读取用户资料、仓库列表、提交记录与 Star 数（watchers）的权限，因为画像统计依赖这些数据（UserService.kt 中的generateUserProfile会并行抓取非 Fork、非空仓库的提交、语言与 Star 数据）。
• 多 Token 必须是不同账户：GitHub 限流按账户计，同一账户生成的多个 Token 不会叠加配额。
• 内存缓存特性：缓存存放在内存 H2 数据库中，进程重启即清空；但 6 小时的有效期设计能显著降低热门用户的重复抓取开销。
• 本文章节中的匿名限流数值（约 50 次/小时）来自官方文档，实际额度以 GitHub 当前策略为准；源码注释中提到的空 Token 60 次请求可作为参考。
• 参数名大小写敏感：系统属性写法全部为小写连字符（如free-requests-cutoff），环境变量写法则全部大写加下划线，二者不可混用。

通过本文的配置组合，你可以把 profile-summary-for-github 从“个人玩具”升级为配额充足、带统计能力、具备限流保护的稳定公开服务。相关配置文件与实现源码均在本仓库中，可对照 Config.kt、GhService.kt、UserService.kt 进一步深入阅读。

【免费下载链接】profile-summary-for-githubTool for visualizing GitHub profiles项目地址: https://gitcode.com/gh_mirrors/pr/profile-summary-for-github