# 44-老模板环境核对与后台报错说明 - 2026-04-19

## 目的

这份文档专门记录 `2026-04-19` 这次环境核对结论，解决两个后台报错的判断混乱问题：

1. `读取真实站外 summary 骨架失败`
2. `读取 SEO 结果观察面板失败`

结论先说：

> 当前核心问题不是老模板代码，也不是 `domain` 表本身，而是当前 `video2` 库缺少 `seo_external_snapshot` 表，同时相关 migration 尚未执行。

---

## 一、今天实际核对了什么

按固定顺序核对：

1. `migrate:status`
2. `domain` 表字段状态
3. `seo_external_snapshot` 是否存在
4. 当前库里的 migration 记录表情况

特别约束：

- `migrate` 只能由 `www` 用户执行

今天的 `migrate:status` 也是按这个约束执行的。

---

## 二、`migrate:status` 结果

今天已确认下面 3 条 migration 当前都是 `down`：

1. `20260119132713 AddBaiduTokenToVideoTable`
2. `20260410010000 CreateSeoExternalSnapshotTable`
3. `20260410020000 OptimizeSeoExternalSnapshotIndexes`

这说明：

1. `d_baidu_token` 这类字段补充没有执行
2. `seo_external_snapshot` 建表没有执行
3. `seo_external_snapshot` 的索引优化也没有执行

---

## 三、当前库的实际状态

当前 `.env` 已确认连接的是：

- `DB_NAME = video2`

### 1. `domain` 表

今天已确认：

- `domain` 表存在
- 基础字段如：
  - `d_domain`
  - `t_id`
  存在

但今天没有查到：

- `d_baidu_token`

### 2. `seo_external_snapshot` 表

今天已确认：

- `seo_external_snapshot` 表不存在

这和后台报错完全一致。

---

## 四、为什么“真实站外 summary 骨架失败”

触发链路是：

1. 后台接口：
   - [Site.php getDomainExternalSeoRealSummary](/www/wwwroot/VideoSource2/code/app/admin/controller/Site.php:2941)
2. 调用：
   - [DomainExternalSeoRealSummaryHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoRealSummaryHelper.php:7)
3. 它一上来先走：
   - `buildAutoSnapshotSummary($days)`
4. 这一步内部又调用：
   - [DomainExternalSeoSnapshotAnalysisHelper.php](/www/wwwroot/VideoSource2/code/app/common/helper/DomainExternalSeoSnapshotAnalysisHelper.php:7)
5. 该 helper 底层模型：
   - [SeoExternalSnapshotModel.php](/www/wwwroot/VideoSource2/code/app/model/SeoExternalSnapshotModel.php:9)
6. 绑定表名：
   - `seo_external_snapshot`

所以这个报错的根因不是：

- 骨架模板坏了
- provider skeleton 坏了

而是：

- 在进入 skeleton fallback 之前，自动快照分支先查表
- 当前库没有 `seo_external_snapshot`
- 所以直接 SQL 异常

---

## 五、为什么“SEO 结果观察面板失败”

这次也已核对过，后台“SEO 结果观察面板”不是单独一块静态 UI，而是会去读“站外 SEO 观察数据”。

最像当前入口的是：

- [router.php](/www/wwwroot/VideoSource2/code/app/admin/config/router.php:161)
  - `/domain/external/seo/cn/overview`
- [Site.php](/www/wwwroot/VideoSource2/code/app/admin/controller/Site.php:2580)
  - `DomainExternalSeoCnOverviewHelper::buildOverview(...)`

而这个 overview 底层直接依赖：

1. `DomainExternalSeoSnapshotAnalysisHelper::buildSummary(...)`
2. `DomainExternalSeoSnapshotAnalysisHelper::buildIndexMovementSummary(...)`
3. `DomainExternalSeoSnapshotAnalysisHelper::buildKeywordMovementSummary(...)`

这些 helper 的底层数据源仍然是：

- `seo_external_snapshot`

所以这条报错本质上和“真实站外 summary 骨架失败”是同一类问题：

- 观察面板不是单独坏了
- 而是它背后的历史快照表没建起来

---

## 六、当前不要误判的点

### 1. 不要把主矛盾误判成 `domain` 表

当前 `domain` 表的 migration 确实没补齐，`d_baidu_token` 也没进库。

但今天这两个后台报错的第一矛盾不是它。

当前更直接的主矛盾是：

- `seo_external_snapshot` 缺表

### 2. 不要把问题误判成老模板 `1001-1005`

这两个报错属于：

- 后台站外 SEO 观察能力
- migration / 表结构层

而不是：

- 老模板前台 SEO 模板渲染失败

### 3. 不要直接在非 `www` 用户下跑 migrate

今天已经再次确认这条规则要固定下来：

- `migrate` 只能由 `www` 用户执行

---

## 七、当前最稳结论

截至 `2026-04-19` 当前环境，最稳结论是：

1. 当前数据库是 `video2`
2. `domain` 表存在，但相关新增字段未补齐
3. `seo_external_snapshot` 表不存在
4. 对应 migration 当前是 `down`
5. 后台“真实站外 summary / SEO 结果观察面板”这两类报错，根因都优先指向：
   - `seo_external_snapshot` 缺失

---

## 八、后续最稳动作顺序

后续如果要继续推进，不要跳步，按下面顺序：

1. 先 `migrate:status`
2. 再核对 `domain` 表字段
3. 再核对 `seo_external_snapshot` 是否缺失
4. 最后再决定是否执行 migration

执行约束：

- 只能由 `www` 用户执行

---

## 九、一句话交接

> `2026-04-19` 这次后台报错核对已经确认：当前环境主矛盾不是老模板也不是 `domain` 表本身，而是 `video2` 库缺少 `seo_external_snapshot`，且相关 migration 仍是 `down`；后续如果要处理，必须按“先 status、再核字段和缺表、最后由 www 执行”的顺序推进。