主站

知识库

quartz-prepublish-readiness

4分钟阅读

知识库站点发布前验收要点

原则

隐私审阅完成不是部署验收完成。先检查公开副本及索引，再测试真实部署语义；本机审阅服务只提供报告，不代表正式站点可用。未经发布许可不修改线上路由、不上传预览到公网。

本轮核验结果

  • 现有 Wrangler 4.149.0 对独立 Quartz 配置执行 deploy —dry-run 成功，仅本地打包，未发布。
  • Worker 将 /a/ 前缀剥离后转发给 ASSETS，却没有重写下游 Location。用实际 Worker 模块和模拟资产响应复现：/a/notes.html 得到 /notes，/a/notes 得到 /notes/，会跳出知识库路径。修复须处理同源重定向并保留 query，不改第三方重定向。
  • 路由只配置 /a/*；Worker 里的 /a 重定向未被这一模式覆盖。正式入口须单独覆盖 /a 或由主站显式跳转，防止主站/知识库路由冲突。
  • 静态 HTML 内链检查：139885 次本地引用，64 个缺失目标候选，其中有代码位置样式引用，不能全部当真实坏链。1 个缺失图片目标 assets/landscape-latest.png 已确认缺文件，需定位是否模板引用再处理。
  • 缺 robots.txt，首页缺显式 canonical。baseUrl 已包含域名及 /a 子路径，RSS/sitemap 文件存在；上线前核验 URL 与预期可索引范围。
  • Worker 未显式加安全响应头。适合纯静态知识库的基线：nosniff、Referrer-Policy、Permissions-Policy、防被嵌入；CSP 先在本地/报告模式测试，不能直接禁止 Quartz 的内联脚本、样式和外部 KaTeX。
  • 不缓存真实不存在的页面为 200；验证 404、无扩展名链接、目录尾斜杠、深层刷新、SPA 跳转、搜索索引请求。
  • 保留 Cloudflare 默认重新验证缓存；只有内容哈希命名的资产适合长期 immutable。索引与 HTML 不能盲目长期缓存。
  • 模板站点图标未见隐私；默认分享图仍显示 Quartz 品牌，属于模板标识，不是凭据；更换为站点自己的公开分享图是展示完善，不是安全门禁。
  • 项目内没有独立 Wrangler 依赖，本次使用主站已有 CLI 验证。长期维护需固定部署工具版本/入口，避免隐式借用另一个项目的 node_modules。
  • 正式发布前固定产物清单及哈希，避免其他 Agent 更新知识库时打包到未审阅的新内容；保存旧版本、路由快照、回滚说明。只部署独立 Worker，不改主站 KV/三十问数据。

来源

官方说明要点：Quartz 需要正确配置 baseUrl，托管环境须处理无 .html 的链接；Cloudflare 静态资产默认进行 HTML 规范化重定向；默认缓存为重新验证并带 ETag；run_worker_first/Worker 生成的响应应在 Worker 中验证和设置自定义响应头，不能仅依赖 _headers。

原始缺失目标清单只保存在本地运行目录，不作为公开文档附件。该文档是研究结论，不是发布成功证明。

关系图谱