GitDiagram 首页

GitDiagram

只需几秒，即可将任意公开或私有 GitHub 仓库转换为可交互的架构图（architecture diagram）。

你也可以在 GitHub 链接中将 hub 替换为 diagram，直接打开对应仓库的架构图。

功能特性

以架构为先的图表：将仓库目录树、README 以及有界的源码片段转换为系统级图谱，而非仅仅绘制文件夹结构。
可交互的源码链接：点击任意组件即可在 GitHub 上打开对应的真实文件或目录。
流式生成：在图谱规划的同时，你可以即时看到解释文本的逐步输出。
私有仓库支持：在浏览器本地提供 GitHub token；私有产物使用独立的、受保护的存储命名空间。
导出：复制 Mermaid 源码，或将渲染后的图表下载为 PNG。
提供商可选：默认使用 OpenAI，同时为自托管部署提供 OpenRouter。

技术栈

应用层：Next.js 16 App Router、React 19、TypeScript、Tailwind CSS、Radix UI
生成 API：同源 Next.js Route Handlers，部署于 Vercel 的 Bun 运行时
存储：使用 Cloudflare R2 存储图表产物
协作：使用 Upstash Redis 处理配额记账、取消、锁以及短期失败状态
AI：通过 AI_PROVIDER 选择 OpenAI 或 OpenRouter
数据分析：PostHog
部署：Vercel 是当前唯一在线运行时；同时保留一份离线的 Railway / Docker 方案作为灾难恢复

不存在独立的 FastAPI 实现、Postgres 数据库或 Neon 运行时。

生产架构

Vercel 同时托管界面与生成端点：

/api/generate/cost：在有界地获取 GitHub 内容之后估算一次运行开销，同源且限流。
/api/generate/stream：通过 Server-Sent Events 流式输出解释与图谱进度。
/api/generate/cancel：记录经过认证的、同源的取消信号。
/api/diagram-state：读取与写入持久化的结果契约。
/api/healthz：提供轻量级的部署健康检查。

长时间运行的生成任务使用 300 秒的 Vercel 函数预算，但设置了更短的应用层截止时间，以便配额对账与持久化仍能按时完成。请求使用明确的上游截止时间、重试、结构化日志、心跳以及分布式取消机制，而非进程本地状态。

默认托管的 OpenAI 流水线使用一次 GPT-5.6 Luna 请求，中等推理强度，生成基于源码的图谱与简短的流式概述。模型返回的是精简图谱，不包含冗余描述或类型说明。图谱会被验证并以确定性方式编译；额外的 Luna 调用仅保留用于结构修复，或在 18 秒慢请求之后进行一次恢复。慢连接会在其替代请求开始前被取消；其不可用的部分用量会计入估算成本。托管的 GPT-5.6 请求显式启用 Fast 模式（service_tier: "priority"）；估算包含该档位的溢价，最终成本以实际服务的模型与档位为准。用户自带 key 仍使用标准服务及其配置的模型。显式的模型覆盖与 OpenRouter 保留两阶段流水线。输出 token 的估算会预占配额，但不限制提供商的输出。

同一个 Next.js 应用也可构建为一个极小的、非 root 的独立 Docker 镜像，用于 Railway。并未保留任何在线的 Railway 服务、源码连接或 Railway 域名。仓库内提交的 Dockerfile 与 railway.json 是一份冷启动恢复方案，可在不复活第二套后端实现的情况下重新构建完整应用。详见 docs/deployment-failover.md。

生成原理

GitDiagram 通过 GitHub API 获取仓库的默认分支、递归目录树与 README。被截断的目录树以及超大的输入会在模型开始工作前被拒绝。
GitDiagram 获取有界的、经过完整性校验的源码片段。选取策略优先选择具有实质内容的运行时模块，在长文件中分散采样，并保留被采样调用的 import 绑定关系。
一次托管的 Luna 请求流式输出一段简短的架构概述，随后输出严格的图谱：分组、节点、边、形状、标签以及仓库路径。显式的模型覆盖与用户自带 key 仍保留独立的解释 / 图谱流程。
服务端会验证标识符、图谱连通性、各项限制，以及每个链接路径是否真实对应仓库内容。无效输出会附带聚焦的反馈进行重试。
一个确定性的编译器将验证后的 AST 转换为 Mermaid，并进行完整的文本转义与 GitHub 专属链接生成。
浏览器对源码进行清洗，在严格安全模式下渲染 Mermaid，对生成的 SVG 进行清理，并再次强制执行链接白名单。
成功的产物与终态审计信息会被持久化，以便后续访问无需再次调用模型即可重新打开图表。

完整的 Mermaid 解析器仍保留在测试套件中，作为编译器契约测试。它刻意不加载到生产环境生成函数中，从而在不影响图谱校验与浏览器安全的前提下保持服务端包体精简。

状态

成功的公开生成结果：以仓库为键的 R2 对象
成功的私有生成结果：通过服务端密钥派生的独立 R2 命名空间
免费配额与活跃的取消令牌：Upstash Redis
未保存产物的终态失败：短期 Upstash 状态
并发写入：分布式锁 + 最新会话胜出的持久化策略

私有仓库

在顶部导航中选择 Private Repos，并提供一个能读取目标仓库的、细粒度的 GitHub 个人访问令牌（PAT）。该令牌仅随相关的同源请求发送，绝不会嵌入到公开的图表链接中。

本地开发

精确的前置条件与环境细节，请参阅 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 PAT 或 GitHub App 为可选项，但强烈建议配置，以获得更高的 GitHub API 配额。

在提交 Pull Request 之前，运行完整的本地检查：

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

贡献

欢迎贡献。请通过聚焦的描述与验证说明提交 Issue 或 Pull Request。

致谢

灵感来自 Romain Courtois 的 Gitingest。

ahmedkhaleel2004/gitdiagram

AI智能总结