5.2 KiB
5.2 KiB
2026-04-19 私有运行产物存储与发布公共规则
这份文档属于全项目公共规则。
适用范围：
SEONexusSEONexusAdmin- GPT 模板
- 老模板
- 以后新增模板或新增后台工作台
目标只有一个：
所有运行时生成的私有数据、中间文件、工作台快照、调试结果、异步任务产物，默认放
storage，不要再放public。
一句话规则
默认判断口径：
- 只要这个文件不是源码，不需要被公网直接访问，就不要放
public - 只要这个文件会反复覆盖、每天新增、按任务生成、按用户生成、按批次生成，就优先放
storage - 只要这个文件包含后台专用信息、运行日志、调试快照、工作台临时结果、导入导出中间态，就必须放
storage - Vue 后台如果要打开
storage文件，走后台鉴权预览接口，不要直接拼公网 URL
哪些必须放 storage
下面这些，默认都属于 storage：
- 蜘蛛日志分析产物
- SEO 观察面板运行快照
latest.summary.json/html这类后台摘要文件- 视频元数据缺失工作台中间结果
- AI 队列任务产物
- 导入新域名后的扫描中间文件
- 手工导入 / 批量导入后的临时文件
- 任务池运行日志
- 异步任务进度文件
- 一键生成后的批次目录
- 调试 JSON
- 人工排障时导出的临时报告
- 只给后台使用的 HTML 片段、JSON 片段、Markdown 片段
判断技巧：
- 会不会每天新增很多份
- 会不会经常被覆盖
- 会不会只在后台看
- 会不会不适合进 Git
只要答案偏向“会”，就应该进 storage。
哪些才允许放 public
只有真正需要公网直接访问、并且可以视为发布资产的内容，才允许放 public。
典型例子：
- 前台页面真正要引用的静态资源
- 模板正式发布资源
- 已确认要对外发布的 SEO 静态页产物
- 前台运行必须直接访问的 js / css / image / font
- 明确设计为公网 URL 的最终发布文件
注意：
public是发布区，不是工作台缓存区public不是临时文件夹public不是后台调试目录public不是“先放一下后面再整理”的地方
Git 提交规则
所有 Codex 和人工协作者，默认遵守下面 6 条：
- 提交前先看有没有运行产物混进变更区
latest/*.json、latest/*.html这类文件先怀疑是运行产物，不要直接提交- 工作台目录如果只是本地运行结果，要加忽略规则，不要入库
- 私有批次目录如果只是中间产物，不要提交
- 真正需要同步的，是代码、配置、文档、模板，不是运行结果
- 看到
public/_admin_templates/...下面不断新增批次文件时，先怀疑设计跑偏
后台查看规则
如果文件放在 storage，后台仍然可以看，但方式要改成：
- PHP 提供受后台登录保护的预览接口
- Vue 后台通过接口读取或打开
- 不要直接把
storage文件暴露成匿名公网链接 - 不要因为“后台想看方便”就把文件搬回
public
当前已经确认的正确方向：
- 私有运行产物留在
storage - 后台通过鉴权接口预览
- 前端只拿相对路径或任务标识，不直接拼公开文件 URL
这条规则为什么重要
如果不这么做，会反复出现这些问题：
- Git 工作区天天脏
- 提交时误把私有数据推到仓库
- 同一类运行产物被多台机器重复覆盖
- 后台临时文件被当成正式发布资源
- 新接手 Codex 看见
public里的数据，误以为那是源码或正式模板 - 公网可直接访问到本不该公开的后台产物
历史兼容处理
如果历史上已经有一批运行产物放在 public，处理顺序是：
- 先改代码，新运行不再写旧路径
- 再把后台读取链路改到
storage - 再评估历史文件是否保留、迁移或移出版本库
- 不要一边继续往旧
public目录写，一边说后面再收口
新 Codex 接手必须先记住
后续任何新的 Codex 会话，看到下面几类需求时，默认先套这条规则：
- “后台生成一个报告”
- “异步任务跑完留个结果”
- “导入后先产出一份中间 JSON”
- “工作台保存当前批次”
- “任务日志保留给后台看”
- “批量生成 Markdown / HTML / JSON”
默认答案：
- 如果不是公网发布资产，就放
storage
当前项目已明确的新增统一口径
- 所有后台运行产物、工作台快照、手工导入中间文件默认落
storage - Vue 后台打开
storage产物时，走后台鉴权预览入口 - 不要再直接拼
publicURL 作为后台查看方式 - 后续如新增“私有数据目录”，也应以
storage为第一落点，而不是在public新建隐藏角落
给后续协作者的最终提醒
如果某条旧规则、旧目录、旧习惯，开始限制 SEO、后台治理、协作效率，或者明显增加误提交风险，不能因为“以前这么干”就继续保留。
先保证：
- 数据边界清晰
- Git 边界清晰
- 公网发布边界清晰
- 后台查看链路清晰
然后再谈兼容和迁移。