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