ahmedkhaleel2004/gitdiagram

[](https://gitdiagram.com/)  [](https://ko-fi.com/ahmedkhaleel2004) # GitDiagram 在几秒钟内将任何 GitHub 仓库转换为交互式图表以进行可视化。 你也可以在任何 Github URL 中将 `hub` 替换为 `diagram` 来访问其图表。 ## 🚀 功能 - 👀 **即时可视化**：将任何 GitHub 仓库结构转换为系统设计 / 架构图 - 🎨 **交互性**：点击组件可直接导航到源文件和相关目录 - ⚡ **快速生成**：由 GPT-5 系列模型提供支持，使用 OpenAI 处理用户提供的浏览器密钥，可选使用 OpenRouter 进行自托管部署 - 🖼️ **导出选项**：复制 Mermaid 代码或将生成的图表下载为 PNG ## ⚙️ 技术栈 - **前端**：Next.js, TypeScript, Tailwind CSS, ShadCN - **后端**：FastAPI (Railway) 或 Next.js Route Handlers，通过环境变量明确选择 - **存储**：Cloudflare R2（图表工件）+ Upstash Redis（配额和故障摘要） - **AI**：OpenAI 或 OpenRouter（通过 `AI_PROVIDER`） - **部署**：Vercel（前端）+ Railway（后端） - **CI/CD**：GitHub Actions - **分析**：PostHog, Api-Analytics ## 🧭 生产架构 - **Vercel** 托管 Next.js 前端 - **Railway** 在生产环境中运行长期存在的 FastAPI 生成后端 - **Cloudflare R2** 存储成功的图表工件 - **Upstash Redis** 存储免费配额状态和短暂的终端故障摘要 - **OpenAI `gpt-5.4-mini`** 是默认的服务端生成模型 现在已经没有 Postgres 或 Neon 运行时路径了。 ## 🔄 生成后端 GitDiagram 支持两种生成后端： - `fastapi`：外部 FastAPI 服务 - `next`：仓库内的 Next.js Route Handlers，在进程内验证 Mermaid，可以使用内置的 Bun 运行时配置部署在 Vercel 上 前端路由是明确的： - `NEXT_PUBLIC_GENERATION_BACKEND=fastapi`，并设置 `NEXT_PUBLIC_GENERATE_API_BASE_URL=https:///generate`，用于生产环境路径 - 或者 `NEXT_PUBLIC_GENERATION_BACKEND=next` ## 🗂️ 状态存储位置 - **成功生成**：每个仓库工件对应一个 R2 对象 - **没有保存工件的终端故障**：Upstash Redis TTL 摘要 - **每日免费配额**：Upstash Redis 哈希 - **私有仓库持久化**：从提供的 GitHub token 派生的独立 R2 命名空间 ## 🤔 关于 我创建这个项目是因为我想为开源项目做贡献，但很快意识到它们的代码库太庞大了，我无法手动深入分析，所以这个工具帮助我入门——但它肯定还有更多的用例！ 给定任何公开（或私有！）的 GitHub 仓库，它会使用 GPT-5 系列模型生成 Mermaid.js 图表。默认设置通过 OpenAI 使用 GPT-5.4 mini，而自托管操作员可以选择通过环境配置将后端指向 OpenRouter。 ## ⚙️ GitDiagram 工作原理 当你提交一个 GitHub 仓库 URL 时，GitDiagram 会向 GitHub API 请求该仓库的默认分支、递归文件树和 README，同时过滤掉嘈杂的资产和依赖文件夹。它将仓库快照输入到一个流式生成管道中，其中一次模型传递编写纯英文的架构解释，第二次传递将该解释与文件树转换为包含系统、节点、边和真实仓库路径的结构化图。 该图会根据实际文件树进行验证，如果包含错误路径或无效连接，则会在反馈后重试，然后编译成 Mermaid 并在显示之前再次进行验证。任何与真实路径关联的节点都会变得可点击并链接回 GitHub，最终的解释、图、图表和终端生成状态存储在 Cloudflare R2 和 Upstash Redis 中，以便应用程序可以重新打开现有结果或显示运行在哪里失败。 一个值得了解的实现细节是：Next 后端在 [`src/server/generate/mermaid-validator.ts`](/Users/ahmedkhaleel/repos/gitdiagram/src/server/generate/mermaid-validator.ts) 中进行进程内的 Mermaid 验证，而 FastAPI 后端调用 [`backend/scripts/validate_mermaid.mjs`](/Users/ahmedkhaleel/repos/gitdiagram/backend/scripts/validate_mermaid.mjs) 中由 [`backend/lib/mermaid-validator.ts`](/Users/ahmedkhaleel/repos/gitdiagram/backend/lib/mermaid-validator.ts) 支持的轻量级 Bun 包装器。两者都使用相同的 Mermaid + DOMPurify 引导方法，因此 Railway 后端运行时有意保持为 Python + Bun 混合。 ## 🔒 如何绘制私有仓库图表 你只需点击标题栏中的“Private Repos”并按照说明提供具有 `repo` 范围的 GitHub 个人访问令牌即可。 你也可以按照以下步骤在本地自托管此应用（后端也可以分离！）。 ## 🛠️ 自托管 / 本地开发 有关确切的工具版本、机器设置和验证，请参阅 `docs/dev-setup.md`。 1. 克隆仓库 ``` git clone https://github.com/ahmedkhaleel2004/gitdiagram.git cd gitdiagram ``` 2. 安装根目录依赖 ``` bun install ``` 3. 安装后端 FastAPI 端的依赖 ``` bun run install:backend ``` 这保持了后端的 Python 环境由 `uv` 管理，并从 `backend/bun.lock` 安装后端 Mermaid 验证器的 Bun 依赖。 4. 设置环境变量（创建 .env） ``` cp .env.example .env ``` 然后使用你的后端 AI 凭据和可选的 GitHub 个人访问令牌编辑 `.env` 文件。 使用 `.env.example` 作为必需和可选变量的规范列表。 5. 运行前端 ``` bun run dev ``` 你现在可以在 `localhost:3000` 访问该网站。 这是最简单的本地模式，适用于： - `NEXT_PUBLIC_GENERATION_BACKEND=next` 如果你想要与生产环境一致，只需运行 FastAPI 后端： ``` docker-compose up --build -d docker-compose logs -f api ``` 要从前端使用 FastAPI 后端，请设置： - `NEXT_PUBLIC_GENERATION_BACKEND=fastapi` - `NEXT_PUBLIC_GENERATE_API_BASE_URL=http://localhost:8000/generate` 要使用内置的 Next.js Route Handlers，请设置： - `NEXT_PUBLIC_GENERATION_BACKEND=next` 快速验证： ``` bun run check bun run test bun run build ``` Railway 后端文档：`docs/railway-backend.md`。 ## 贡献 欢迎贡献！请随时提交 Pull Request。 ## 致谢 特别鸣谢 [Romain Courtois](https://github.com/cyclotruc) 的 [Gitingst](https://gitingest.com/) 提供的灵感和样式

标签：AI代码生成, AI助手, AV绕过, Cloudflare R2, DevTools, DNS解析, FastAPI, GitHub Actions, GPT-5, Mermaid, MIT协议, OpenAI, OSV, PNG导出, Railway, ShadCN, SOC Prime, Tailwind CSS, TypeScript, Upstash Redis, Vercel, 交互式图表, 代码可视化, 代码结构分析, 内存规避, 安全插件, 开发工具, 开源项目, 技术架构, 数据管道, 架构可视化, 系统架构图, 系统设计, 自动化攻击, 自动笔记, 请求拦截, 软件工程