私有仓库也敢画GitDiagram 本地部署与 Token 配置全流程【免费下载链接】gitdiagramVisualize any GitHub codebase: free interactive architecture diagrams and one-minute explainer videos. Replace hub with diagram in any GitHub URL.项目地址: https://gitcode.com/GitHub_Trending/gi/gitdiagram把任意 GitHub URL 中的hub换成diagram几秒后你就得到一张可交互、可点击跳转源码的架构图——这是 GitDiagram 最出圈的玩法。但公开仓库人人可读私有仓库才是大多数团队真正想画的东西内部服务怎么分层、模块之间谁依赖谁、新人要从哪个文件读起。社区里关于 GitDiagram 私有仓库的文章并不少但多数停在支持私有仓库一句话上对 Token 怎么生成、存哪里、私有数据怎么隔离语焉不详。本文直接以仓库源码为准从环境准备、.env配置、细粒度 PAT 的权限最小化到私有产物的存储隔离与首次生成验证完整走一遍私有仓库也敢画的本地部署链路。先纠正一个过时的认知它其实是一个单进程应用不少社区文章把 GitDiagram 描述成Next.js FastAPI 前后端分离架构这是早期版本的印象与当前仓库不符。在 docs/architecture.md 中技术栈一节写得非常明确There is no separate FastAPI implementation, Postgres database, or Neon runtime.整个项目就是一个 Next.js 应用UI 与生成 API 跑在同一个进程里/api/generate/*是同源same-origin的 Route Handler部署在 Vercel 的 Bun runtime 上没有第二个后端进程没有要额外安装的数据库。这对本地部署是重大利好——你要拉起来的只有一个 dev server依赖项里甚至不需要自建 Postgres而是用托管式的 Cloudflare R2 与 Upstash Redis。本地环境准备Node.js 与 Bun版本要求不是装个最新版就行仓库里锁得相当死。package.json 的engines与packageManager字段engines: { bun: 1.3.14 2, node: 22.x }, packageManager: bun1.3.14docs/dev-setup.md 进一步说明Node.js 建议22.12及以上用于运行工具链22.22.2及以上才能跑完整测试套件jsdom 30Bun 锁定1.3.14CI、Dockerfile 与packageManager全部一致并且明确警告暂时不要升到 Bun 1.4——它会重写bun.lock。安装与启动bun install cp .env.example .env bun run devbun install的prepare脚本会启用.githooks/下的 pre-push 钩子推送前自动跑格式、lint、类型检查等快速校验。bun run dev实际调用的是 scripts/dev-turbo.sh即bun run --bun next dev --turbo。启动后打开http://localhost:3000即可。想要生产模式自检则bun run build bun run start完整校验序列lint / typecheck / test / build在 dev-setup 文档的 Verify 一节与 CI 完全一致。.env存储凭据与 AI 凭据是两条独立主线.env.example 是每个配置项的单一事实来源注释详尽。按作用可分成两组必填项存储与协调生成出的架构图不是只活在内存里会持久化到 R2配额、取消信号、分布式锁和短生命周期的失败状态放在 Upstash Redis。R2_ACCOUNT_ID R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY R2_PUBLIC_BUCKET R2_PRIVATE_BUCKET CACHE_KEY_SECRET UPSTASH_REDIS_REST_URL UPSTASH_REDIS_REST_TOKEN注意R2_PUBLIC_BUCKET与R2_PRIVATE_BUCKET是两个不同的桶——公开仓库与私有仓库的产物物理隔离这是后面私有数据安全的关键一环。CACHE_KEY_SECRET不只是缓存密钥它还参与私有命名空间的 HMAC 派生与 GitHub 登录 cookie 的加密必须设置且保密。AI 凭据二选一即可。AI_PROVIDERopenai OPENAI_API_KEY OPENAI_MODELgpt-6-luna或走 OpenRouterAI_PROVIDERopenrouter OPENROUTER_API_KEY OPENROUTER_MODELopenai/gpt-5.6-terra OPENROUTER_SITE_URLhttp://localhost:3000 OPENROUTER_APP_NAMEGitDiagram此外有两个可选配置与本文主题直接相关一是GITHUB_PAT/GITHUB_PATS逗号或换行分隔的 Token 池作用是提高 GitHub API 的速率限额并在 src/server/github-auth.ts 中按轮询方式轮流使用二是GITHUB_CONNECT_*系列用于开启Continue with GitHub登录私有仓库的体验。速率限制方面默认服务器付费的生成是每 IP 8 次/小时基础设施级限制 60 次/小时而自带 API Key 的调用者不受限流——这点对自托管同样适用。PAT 生成权限最小化的官方模板GitDiagram 对该给你什么权限有明确预期这个预期直接写进了前端代码。src/components/private-repos-dialog.tsx 会在你点开 GitHub access 弹窗时把创建 Token 的页面 URL 预填好tokenUrl.search new URLSearchParams({ name: GitDiagram, description: Read selected repositories to generate architecture diagrams, expires_in: 30, contents: read, ...(repository ? { target_name: repository.split(/)[0]! } : {}), }).toString();也就是说官方推荐的 Token 是细粒度fine-grained个人访问令牌且参数已经替你定好名字叫 GitDiagram、30 天过期、contents权限为read、资源范围默认指向你要画的那个仓库。手动创建时照此办理即可GitHub Settings → Developer settings → Fine-grained personal access tokens → Generate new tokenResource owner 选仓库所属账号Repository access 只勾选目标仓库不要选 All repositoriesPermissions 里把Contents 设为 Read-onlyMetadata 的只读访问会自动附带过期时间设为 30 天以内然后生成并把令牌粘贴到 GitDiagram 的弹窗中保存。这是典型的权限最小化GitDiagram 只需要读文件树、README 与少量源码片段完全不需要写权限、issue 权限或账号级权限。弹窗里的数据用途说明也写得很直白Token 会保存在受保护的浏览器 cookie 里 30 天仓库内容会发送给 AI 提供方以生成图表。如果是组织仓库可能还需要组织管理员审批这次安装。私有仓库的隐私边界四条代码级防线「私有仓库也敢画」的信心不来自口号而来自源码里层层设防的边界。逐个看防线一匿名调用者永远借不到服务器的凭据。src/server/generate/github.ts 的fetchGithubData在拿到仓库元数据后立刻判断if (isPrivate !hasCallerGithubPat) { throw new Error(PRIVATE_REPOSITORY_AUTH_REQUIRED_ERROR); }注释说得更直白服务器配置的 App 安装令牌或 PAT 池可以提高公开请求的速率限额但must never become authorization for an anonymous caller——你给服务器配了高权限 Token它也只能用来读公开数据绝不会成为你画别人私有仓库的通行证。防线二过期或受限的 Token 不会阻塞公开仓库。同一个文件里的getGithubData捕获 401/403/404当调用者带了一个失效的 Token 时会回退到无 Token 的公开读取并标记usedPublicFallback。这意味着你把一个过期 Token 粘贴进去私有仓库画不了但公开仓库的体验不受影响错误信息也保持收敛不会泄露服务器能看到什么。防线三私有产物在独立的命名空间里且用 Token 本身做隔离密钥。src/server/storage/cache-key.ts 定义了读写位置的规则公开产物存public/v1/{user}/{repo}.json私有产物存private/v1/{namespace}/{user}/{repo}.json其中 namespace 是createHmac(sha256, secret).update(trimmedPat).digest(hex);即以CACHE_KEY_SECRET为密钥、以访问者自己的 PAT 为输入做 HMAC。这样即使两个不同的人画同一个私有仓库产物也落在不同的命名空间互不可见读取时getReadLocations也只在携带 Token 的情况下先查私有桶再查公开桶。提供给 MCP 等匿名调用的 src/server/storage/artifact-store.tsgetPublicDiagramArtifact则被限定只能读公开桶从接口层面杜绝了越权路径。防线四凭据本身 HttpOnly 化。src/server/http/request-credentials.ts 把 PAT 写入gitdiagram_github_patcookie属性为httpOnly、sameSite: strict、path: /api、有效期 30 天设置 PAT 的同时会清除已建立的 GitHub OAuth 连接保证同一时刻只有一个 GitHub 凭据生效。浏览器 JS 永远读不到这个 cookie它只在同源 API 请求时随请求带往服务器。最后排错时可以直接对照 src/features/diagram/github-access.ts 的错误文案映射表Private repository?、This repository needs GitHub access、Update your GitHub token、Your token needs repository access、We couldnt read this repositorys files——分别对应「仓库确实是私有的」「需要提供 Token」「Token 已失效」「Token 权限不足」「读取文件树失败」按提示逐项排查即可。首次生成私有仓库架构图从输入 URL 到完成在首页输入私有仓库地址注意 src/features/diagram/github-url.ts 的解析器相当宽容支持https://github.com/owner/repo任意页面深链tree/blob/issues 等、gitgithub.com:owner/repo.git的 SSH 形式以及owner/repo简写。点击生成后会先弹出 GitHub access 对话框按上一节的方式粘贴 PAT 保存再触发生成。生成过程走 src/app/api/generate/stream/route.ts 的 SSE 流式通道先拉取默认分支的递归文件树与 README超大仓库的截断树会做顶层目录补读README 超过 750 KB 直接拒绝再抓取有界、经过完整性校验的源码片段交由模型产出「一段流式架构讲解 一张严格图分组/节点/边/形状/仓库路径」服务器会对标识符、连通性、每个链接路径做二次校验无效输出会带着针对性反馈重试最后经确定性编译器生成 Mermaid。浏览器端以securityLevel: antiscript、htmlLabels: false渲染并用 DOMPurify 二次消毒节点点击只允许跳转 GitHub。验证成功的标志有三点图上每个组件都能点击直接跳到对应的 GitHub 文件或目录可导出 PNG 或复制 Mermaid 源码再次访问同一仓库时直接命中 R2 产物不再触发一次模型调用——这也是自托管时最直观的画成功且持久化成功的证明。如果生成报错对照上一节错误文案表Update your GitHub token就去 GitHub 重新生成并覆盖保存Your token needs repository access说明 Token 的 Repository access 范围没包含该仓库回 GitHub 编辑 Token 的范围This repository needs GitHub access则说明请求里根本没带上 Token回到弹窗重新粘贴。小结本地部署让敢画变成可审计私有仓库的架构图本质上是把代码结构这种高价值数据交给了一个 AI 生成管道。GitDiagram 的本地部署把整条链路收回到自己手里单进程 Next.js 应用省去后端与数据库的运维负担R2_PUBLIC_BUCKET与R2_PRIVATE_BUCKET双桶隔离公开与私有产物HMAC 派生的命名空间保证每个 Token 只能读回自己的图HttpOnly cookie 保证浏览器侧拿不到凭据而代码里服务器凭据绝不授权匿名调用者的红线让自托管者可以放心地把自己的 PAT 配进.env去提升 API 限额而不必担心它变成别人的钥匙。照着这份流程走一遍你会得到一张私有仓库的架构图以及一整套可以讲给团队听的数据边界。【免费下载链接】gitdiagramVisualize any GitHub codebase: free interactive architecture diagrams and one-minute explainer videos. Replace hub with diagram in any GitHub URL.项目地址: https://gitcode.com/GitHub_Trending/gi/gitdiagram创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考