ahmedkhaleel2004/gitdiagram

来源：https://github.com/ahmedkhaleel2004/gitdiagram

GitDiagram 主页 (https://gitdiagram.com/)

许可证 Ko-fi (https://ko-fi.com/ahmedkhaleel2004)

GitDiagram

在几秒钟内将任何公共或私有 GitHub 仓库转换为交互式架构图。

你也可以在 GitHub URL 中将 hub 替换为 diagram 来打开其图表。

赞助位： 在开发者积极探索代码库时触达他们。赞助 GitDiagram (https://gitdiagram.com/sponsor)。

功能

• 以架构为核心的图表： 将仓库目录结构、README 和有界源代码片段转换为系统级图谱，而不仅仅是绘制文件夹。
• 交互式源代码链接： 点击组件可打开其在 GitHub 上的真实文件或目录。
• 流式生成： 在图表规划的同时查看解释说明的生成过程。
• 私有仓库： 在浏览器本地提供 GitHub 令牌；私有制品使用单独的受保护存储命名空间。
• 导出： 复制 Mermaid 源码或将渲染的图表下载为 PNG。
• 提供商选择： 默认使用 OpenAI，OpenRouter 可用于自托管部署。

技术栈

• 应用： Next.js 16 App Router、React 19、TypeScript、Tailwind CSS 和 Radix UI
• 生成 API： 运行在 Vercel 的 Bun 运行时上的同源 Next.js 路由处理器
• 存储： Cloudflare R2 用于图表制品
• 协调： Upstash Redis 用于配额记账、取消、锁和短期失败状态
• AI： 通过 AI_PROVIDER 使用 OpenAI 或 OpenRouter
• 分析： PostHog
• 部署： Vercel 是唯一的在线运行时；保留了离线 Railway/Docker 配方用于灾难恢复

没有单独的 FastAPI 实现、Postgres 数据库或 Neon 运行时。

生产环境架构

Vercel 同时服务于 UI 和生成端点：

• /api/generate/cost 在有界 GitHub 数据摄入后估算运行成本，同源并限速。
• /api/generate/stream 使用服务器发送事件流式传输解释说明和图表进度。
• /api/generate/cancel 记录经过身份验证的、同源的取消信号。
• /api/diagram-state 读写持久化的结果契约。
• /api/healthz 提供轻量级的部署健康检查。

长时间运行的生成使用 300 秒的 Vercel 函数预算，并设置了更短的应用截止时间，以便配额协调和持久化仍有时间完成。请求使用显式的上游超时、重试、结构化日志、心跳和分布式取消，而非依赖进程本地状态。

默认的托管 OpenAI 管道使用一次中等推理强度的 GPT-5.6 Luna 请求来生成基于源代码的图表和简短的流式概述。模型返回紧凑的图表，没有冗余描述或类型标注。图表经过验证和确定性编译；额外的 Luna 调用仅用于结构修复或在一次 18 秒的慢请求后的单次恢复。慢连接会在其替代开始前被取消；其不可用的部分使用量作为估算成本计入。托管的 GPT-5.6 请求明确使用快速模式（service_tier: "priority"）；估算包含其溢价，最终成本则使用实际服务的模型和层级。用户提供的密钥保留标准服务及其配置的模型。显式的模型覆盖和 OpenRouter 保留两阶段管道。输出令牌估算预留配额但不设限。

同一个 Next.js 应用也可以构建为用于 Railway 的最小化、非 root 的独立 Docker 镜像。没有保留活跃的 Railway 服务、源连接或 Railway 域名。签入的 Dockerfile 和 railway.json 是一个冷恢复配方，可以在不复苏第二个后端实现的情况下稍后重建完整应用。参见 docs/deployment-failover.md。

生成工作原理

1. GitDiagram 通过 GitHub API 获取仓库的默认分支、递归树和 README。截断的树和过大的输入在模型工作开始前会被拒绝。
2. GitDiagram 获取有界、经过完整性检查的源代码片段。选择优先考虑实质性的运行时模块，在长文件中分布片段，并为采样的调用保留导入绑定。
3. 一次托管的 Luna 请求流式传输一个简短的架构概述，然后是一个严格的图表：分组、节点、边、形状、标签和仓库路径。显式的模型覆盖和用户提供的密钥保留独立的说明/图表流程。
4. 服务器验证标识符、图表连通性、限制以及每个链接路径是否与实际仓库匹配。无效输出会带着集中的反馈被重试。
5. 一个确定性的编译器将验证后的 AST 转换为 Mermaid，进行完全的文本转义和仅限 GitHub 的链接。
6. 浏览器净化源代码，在严格安全模式下渲染 Mermaid，净化生成的 SVG，并再次强制执行链接白名单。
7. 成功的制品和终端审计状态被持久化，以便后续访问可以在不进行另一次模型调用的情况下重新打开图表。

完整的 Mermaid 解析器保留在测试套件中作为编译器契约测试。它被有意地不加载到生产生成函数中，以保持服务器包体积小，同时不削弱图表验证或浏览器安全性。

状态

• 成功的公共生成： R2 对象，按仓库键控
• 成功的私有生成： 使用服务器端密钥派生的单独 R2 命名空间
• 免费配额和活动取消令牌： Upstash Redis
• 没有保存制品的终端失败： 短期的 Upstash 状态
• 并发写入： 分布式锁加上最新会话优先的持久化

私有仓库

在页眉中选择 Private Repos，并提供一个可以读取目标仓库的细粒度 GitHub 个人访问令牌。该令牌仅随相关同源请求发送，永远不会嵌入到公共图表链接中。

本地开发

有关确切的先决条件和环境详情，请参阅 docs/dev-setup.md。

git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
bun install
cp .env.example .env
bun run dev

打开 http://localhost:3000。

至少，需要在 .env 中配置 R2、Upstash 和一个 AI 提供商。GitHub 个人访问令牌或 GitHub App 是可选的，但强烈推荐用于提高 GitHub API 限制。

在打开拉取请求之前，请运行完整的本地检查：

bun run lint
bun run typecheck
bun run test
bun run build

贡献

欢迎贡献。请提出一个专注于描述和验证说明的问题或拉取请求。

致谢

灵感来源于 Romain Courtois (https://github.com/cyclotruc) 的 Gitingest (https://gitingest.com/)。