8bit-me 架构重构手记

这篇记录本站 2026-08 的架构重构决策：源码私有、站点公开， 托管从 GitHub Pages 迁到 Netlify，框架维持 Astro 7 不动。 所有决策落在 docs/adr/0001-private-source-public-site.md。

问题：仓库该不该公开？

站点的内容是公开作品集（要发简历给 HR 看），但源码是另一个问题： AI 维护的代码 + 完整方案，放在 public 仓库等于把内部设计全部暴露。 GitHub Pages 免费档强制仓库 public——「站点公开」和「源码公开」被绑死了。

解法：仓库 private + 站点 public 分离。访问者只看到渲染产物， 源码只对站主可见。GitHub Pages 免费档不满足，只好换托管。

托管选型：被墙支配的选项

选托管时查了个事实：从国内直连测试——

平台	国内直连
github.io	可达
netlify.app	可达
*.workers.dev / *.pages.dev（Cloudflare）	被墙
*.vercel.app	被墙

先选了 Cloudflare Pages（免费、私有仓构建），上线后发现 Workers 部署 + pages.dev 域名在国内直连不通——自己的站自己都打不开。换成 Netlify： 免费档、GitHub App 连接私有仓、.netlify.app 国内可达。一个隐藏坑： Netlify 2026-07-28 后新建团队默认新项目 private（site protection）， 新站一律 401 登录页，需手动把 Project visibility 改为 Public。

框架为什么维持 Astro 7

「喜欢新技术」和「AI 维护成本低」在这里并不冲突：Astro 7 本身就是 registry 最新主版本，且是唯一满足五条约束的选项（静态站、markdown 内容管线、零迁移成本、v2 canvas 扩展、免费托管）。详细对比见 docs/research/framework-comparison-2026.md。

部署契约（踩过的坑汇总）

1. astro.config.mjs 默认 base 曾是 /8bit-me/（GitHub Pages 子路径）—— 迁移后必须注入 ASTRO_BASE=/，否则产物落到子路径、canonical 错位。
2. 环境变量 ASTRO_SITE 决定 canonical/og:url；不注入就静默指向旧域名。
3. Netlify 上 netlify.toml 的构建设置优先于 UI 配置（官方文档明示）， 于是 typecheck 门禁以 command = "npm run typecheck && npm run build" 的形式写进了仓库，随 code review 一起恢复了。
4. 每次 push main 自动触发生产构建——内容就是代码，写 markdown 即上线。

流程总结

grilling 敲定方向 → ADR 落档 → 双轴 code review（Standards + Spec）→ 修复闭环。这套「决策文档化 + 评审」流程对 AI 维护的项目尤其重要： 将来任何 agent 读 CONTEXT.md + docs/adr/ 就能还原每一条为什么。