企业官网建设流程全解析

GitHub Profile Analyzer 是一款确定性的 GitHub 个人资料分析器：它通过约 30 次 GitHub API 请求完成一次深度扫描，在 14 个加权维度上为开发者画像打分，并生成完全可解释的报告。本文带你完整拆解它的全栈架构——Next.js 16 + React 19 应用层、Neon serverless PostgreSQL 存储层、Upstash Redis 缓存与限流层，以及部署在 Cloudflare Workers 上的运行层，看看这个组合是怎么跑起来的 🚀

一图看懂技术栈

依赖清单可以在 package.json 中查到；部署配置见 wrangler.jsonc。

应用层：Next.js 16 与 SSE 分析流

项目使用 Next.js 16 的 App Router，页面与接口全部按文件约定路由组织在 src/app/ 下：

• 分析入口：src/app/api/analyze/deterministic/stream/route.ts，以Server-Sent Events（SSE）把每个采集阶段的完成状态实时推给浏览器，你可以"看着"扫描一步步跑完；
• 确定性分析页：src/app/[username]/ProfileClient.tsx 负责发起请求并渲染进度；
• 仪表盘组件：src/components/StatsDashboard.tsx 与 src/components/deterministic/ 下的各标签页（总览、分数、信号、图表）。

一个值得注意的细节：SSE 路由显式声明了force-dynamic，以避免 Next 对 GET 路由做静态优化导致响应被整体缓冲、进度事件无法增量送达。构建侧的调优见 next.config.ts：optimizeCss压缩 CSS、optimizePackageImports按需引入 recharts 和 lucide-react 来减小体积。

分析引擎：一次深度扫描约 30 次 API 请求

核心引擎位于 src/lib/deterministic/engine.ts。"Deep dive" 模式预设了明确的 API 预算：

REST ≤ 34 次 · GraphQL ≤ 10 次 · Search ≤ 2 次 采样前 10 个仓库、每个仓库 3 个 fork、最多 100 条 commit 明细

采集流程（实现在 src/lib/deterministic/fetchers/collect.ts）：

1. 一条批量 GraphQL 查询载入个人主页核心数据：贡献日历、社交图谱、gists、置顶项目与两年贡献历史；
2. 分页 GraphQL 发现仓库，再按每批 4 个补充语言、releases、社区文件、CI 状态与 commit 明细；
3. 周活跃度、Punch Card、贡献者排名等图表数据全部从已取回的数据推导，不额外发请求；
4. 评分规则在 src/lib/deterministic/rules/scoring.ts，异常信号在 src/lib/deterministic/rules/signals.ts。

同一份数据永远产出同样的分数——这是"确定性引擎"与"LLM 每次讲不同故事"的最大区别。

存储层：Neon serverless PostgreSQL 怎么用

数据库访问封装在 src/lib/db.ts，通过@neondatabase/serverless驱动以连接串（DATABASE_WRITE）直连 Neon，并对连接串自动补上sslmode=require。主要数据流：

• 用户表：GitHub OAuth 登录时 upsert，OAuth access token 先用 AES-256-GCM 加密再入库（加解密实现见 src/lib/encryption.ts）；
• 扫描历史：saveScan/saveDeterministicScan用一条 CTE 事务完成"插入 + 只保留最近 10 条"的滚动窗口管理，保证单用户历史不膨胀；
• 统计口径：analytics表记录每次分析的 token 用量与耗时，getAnalyticsSummary只对外暴露聚合值，不泄露用户名。

表结构迁移在 migrations/002_deterministic_scans.sql，可以看到deterministic_scans表用 JSONB 存完整结果，并建有user_id + created_at DESC等索引支撑窗口查询。

缓存与限流：Upstash Redis 的两个角色

Upstash Redis 在项目中身兼两职，封装在 src/lib/redis.ts：

1. 结果缓存：引擎结果以 15 分钟 TTL 写入 Redis（键前缀gitscore:cache:）。未配置 Redis 时全部读写静默降级，缓存读取失败还会触发 src/lib/telegram-alert.ts 的告警通知，而不是让请求直接失败；
2. 滑动窗口限流：src/middleware.ts 中用Ratelimit.slidingWindow(5, "15 m")限制游客 IP——每 15 分钟最多 5 次分析请求，超限返回429，引导用户完成 GitHub 登录解锁无限制访问。

同一个 middleware 还承担安全头注入（HSTS、CSP、X-Frame-Options: DENY等）与 Origin 校验，是所有请求进入 API 前的第一道关卡。

会话与访问控制：JWT + Star-Gate

• 会话：src/lib/auth.ts 用jose签发 HS256 JWT（7 天有效期），写入 HttpOnly Cookiegitscore_session；middleware 在每个 API 请求上先jwtVerify验证身份；
• Star-Gate：src/lib/github/star-gate.ts 实现了一套多级降级策略来验证访客是否给本项目点了 Star——先用用户自己的 OAuth token 直查，再查 Redis 缓存，最后做双向 GraphQL/REST 分页扫描。这是控制分析配额的核心门禁；
• Webhook 加速：GitHub 的watch（Star）事件会推送到 src/app/api/webhooks/github-star/route.ts，路由先用 HMAC-SHA256 校验签名，再把新 Star 状态写入 D1 并失效 Redis 缓存，让下一次验证直接命中。

边缘部署：Cloudflare Workers 上的 Next.js

这是整个架构最有意思的部分：一个 Next.js 全栈应用如何跑在 Edge 上？

• 通过@opennextjs/cloudflare适配器把 Next.js 编译为 Worker，构建脚本npm run deploy即opennextjs-cloudflare build && deploy（见 package.json）；
• wrangler.jsonc 中启用了nodejs_compat兼容标志——因为 OpenNext 的运行时初始化会引用node:async_hooks等 Node 模块；静态资源通过ASSETSbinding 挂载；
• 本地还绑定了一个D1数据库（binding 名DB），专供 Star 追踪场景使用，与 Neon 分工：Neon 管业务主数据，D1 管边缘侧的低延迟小数据；
• Token 池：src/lib/github/http.ts 从GITHUB_TOKENS环境变量读取多个 GitHub token 做轮询分发，摊薄单 token 的 API 配额压力。

本地跑起来：开发步骤速览

git clone https://gitcode.com/gh_mirrors/gi/github-profile-analyzer cd github-profile-analyzer npm install

在.env.local中填入关键变量后即可npm run dev：

完整变量说明见 README.md；回归测试可用npm run test（Vitest），上线冒烟测试见 scripts/smoke-test.mts。

总结：这套组合的价值

GitHub Profile Analyzer 的全栈选型围绕一个约束展开：在 Cloudflare Workers 的子请求与内存预算内，完成一次约 30 次 API 调用的深度分析。为此它用批量 GraphQL 压缩请求数，用 Upstash Redis 挡住重复计算，用 Neon 存下可回溯的历史，再用 SSE 把等待过程变得可见。对想学习"Next.js 部署到 Edge + serverless 数据库 + Redis 限流"这一完整链条的开发者来说，它是一个麻雀虽小、五脏俱全的范本 🐱