性能与缓存

v1.5.2 减少重复扫描、内容下载与磁盘写入。缓存默认启用，无需增加 cacheEnabled 或 cacheTTL 配置。

内容什么时候更新

事件	行为
首次启动	克隆或更新 Git 仓库，完成后预热菜单
定时同步，没有提交变化	保留菜单与文章缓存
同步到新提交	失效相关缓存，重新预热菜单
普通配置变更	重载配置并刷新内容版本
重启	创建新的服务实例版本，重新建立缓存

浏览器在页面加载与文章访问时检查内容版本。版本不变时复用菜单、配置与文章；已经打开的正文不会自动实时替换，同步完成后重新打开文章或刷新页面即可查看更新。

配置变更边界

站点标题、排序和首页等普通配置可以重载。修改仓库地址、分支、监听端口或环境变量后需要重启。容器只读挂载配置时，在宿主机修改文件；采用替换文件的编辑方式后，应确认容器内看到的新内容。

静态资源与 PDF

JS/CSS 使用内容哈希 URL。哈希匹配的资源可以长期缓存，升级后会使用新的 URL。代理应保留应用返回的缓存头。

PDF 只渲染可见和附近页面，最多同时执行两个渲染任务；离屏画布与离开页面后的任务会被释放。首次下载 PDF 文件仍取决于文件大小和网络。

访问统计

重复打开缓存文章仍会通过轻量请求增加访问次数。统计在内存累积，每 5 秒原子写入，正常退出时保存剩余数据。强制终止或断电可能丢失最后约 5 秒的统计。

统计与 Git 缓存是单进程文件存储。多个实例不要同时写入同一数据目录或 Git 工作目录；多实例统一统计需要另行设计共享存储。

如何观察

在浏览器开发者工具的 Network 面板查看 /api/version、菜单和文章请求。相同版本的重复访问应减少菜单和正文下载。不要开启「Disable cache」来验证正常缓存效果。

更多排查步骤见 常见问题。