平台工程

内容子项目「构建时同步」· 独立仓库镜像进 public,新内容自动上线

入档:2026-06-25 来源:把「成为 Prompt 大师」系列(独立仓库、自包含画廊、45MB 图、频繁加期)集成进蛛网之上,作为独立版块 状态:已上线,新增一期=只改系列仓库,下次构建自动上线

一句话总结

当一块内容是独立仓库 + 频繁更新 + 自包含静态站(或大体积素材)时,不要把它拷快照进主站仓库(会让主仓变胖、且每次更新要手动重拷、必然陈旧)。改成构建时同步:构建脚本浅克隆到缓存 → 镜像进 public/(排除 .git) → 主仓只存「拉取逻辑」几行,产物 gitignore。新内容 = 只改子项目仓库,主站下次构建自动带上线,完全不碰主站代码。

决策链(为什么不拷快照)

• 子项目是独立 git 仓库且频繁加期 → 拷快照会立刻陈旧,每期都要手动重拷。
• 素材 45MB → 进主仓会让克隆/CI 变重,且无意义(内容真相在子仓)。
• 子项目是自包含 SPA(相对路径引用素材) → 原样托管在一个子路径即可,无需重写。
• ∴ 选「构建时同步」:与主站已有的「构建时克隆 knowledge-base」同构,架构一致。

实现要点(可照搬)

1. 同步脚本里加一段:缓存存在则 git -C .cache fetch --depth 1 + reset --hard,否则 git clone --depth 1。
2. 镜像进 public/子路径/ 前先清空旧产物,再整盘 fs.cpSync(cache, pub, {recursive, filter}),filter 排除 .git(否则 .git 会被打进 dist 外泄)。
   • filter 正则:!/[\\/]\.git([\\/]|$)/.test(src)
3. .gitignore 同时忽略 .cache/ 和 public/子路径/(都是构建产物,不入库)。
4. 子路径靠托管端目录索引(nginx index index.html; / Pages)解析 /子路径/ → index.html,和静态游戏 /fraud-desk/ 同模式。
5. 首页要展示子项目数据(如最新几期封面)→ 构建期解析子项目产物里的数据数组(如 index.html 里的 var EPISODES=[…]),用 new Function('return '+arr)() 求值(自家内容,合法 JS 字面量)。

坑

• .git 必须排除,否则 Astro 把 public/ 原样拷进 dist/,.git 目录被公开托管。
• 子项目要是私有仓库,CI 克隆需配 token;公开仓库无需。
• 想「秒级上线」需子仓 push → 主站 repository_dispatch;否则靠主站的定时构建(如每 6h)兜底。

教训(可复用)

• 判据:内容「独立演进 + 频繁更新」→ 构建时同步;「一次性 + 稳定」→ 直接拷进 public 即可(如单文件小游戏)。
• 让「新增内容」的动作收敛到内容仓库本身,主站零改动,是可持续发刊的关键。

关联文档

• 知识库网站免备案上线_香港轻量服务器方案 —— 主站本身就是「构建时克隆 knowledge-base + CI 构建 + rsync」,本模式与之同构
• CI从Release抓二进制托管自有服务器_桌面应用国内直连下载_v1 —— 同一「CI 构建时把外部产物拉进 dist 再部署」母题的姊妹篇(这里是内容仓库,那里是二进制 Release)
• 09_平台工程索引
• 每日定时任务自动更新内容板块_首次自动化生产落地_v1 —— 母题延伸:从「同步外部仓库内容」到「定时任务自产数据文件」,同一条可持续发刊管线
• BeatTapper卡点标记器说明 —— 判据另一半的实例:单文件 + 稳定 → 直接拷进 public(与 fraud-desk 同模式),不走构建时同步