# 08 GPT模板其它服务器最新版对齐交接 2026-04-18

这份文档给“其它服务器上的 Codex / 接手同学”使用。

目标不是让对方自己猜，而是让对方直接知道：

1. 这次要同步的是哪一条线
2. 哪些文件必须一起更新
3. 上线后先验什么
4. 出现异常时先查哪里

## 1. 先定边界

这次不是“从老模板迁到 GPT 模板”。

前提是：

1. 目标服务器原本就是 GPT 模板
2. 目标服务器也在跑 `videoGpt1`
3. 现在要做的是把它对齐到当前这台机器的最新 GPT 主线版本

这次同步的不是老模板，也不是全站所有样式。

这次同步的是：

1. `videoGpt1` 这条 GPT 模板线
2. GPT 模板详情 / 播放 / 搜索页 SEO 修复
3. slug-only 详情兜底
4. sitemap 修复
5. 前台详情异常补充日志

不要混入：

1. `1001-1005` 老模板
2. 其它组还没更新到当前 GPT 主线版本的站
3. 与 GPT 模板无关的历史试验文件

## 2. 这次同步的核心目标

把“原本也是 GPT 模板”的其它服务器，对齐到当前主线，重点保证下面 5 件事：

1. slug-only 详情页不要再硬 `404`
2. `/detail/pinyin-xxx` 这类链接能兜底到真实详情页
3. sitemap 主入口和视频分页正常
4. GPT 模板搜索页 / 播放页 / 详情页主标题正常
5. 如果前台详情页再出现 ThinkPHP 错页，能在日志里抓到异常栈

## 3. 必须同步的代码文件

下面这些文件建议按“必须同步”处理，不要只挑一半。

### 3.1 路由与详情兜底

- [SiteContext.php](/www/wwwroot/diff-maccms/SEONexus/code/app/services/SiteContext.php)
- [VideoService.php](/www/wwwroot/diff-maccms/SEONexus/code/app/services/VideoService.php)
- [router.php](/www/wwwroot/diff-maccms/SEONexus/code/app/home/config/router.php)

这一组负责：

1. 域名上下文正确落到 GPT 站
2. `/detail/:strPinyin`
3. `/detail/pinyin-:strPinyin`
4. slug-only 详情 fallback
5. 播放路由的详情取数兼容

### 3.2 sitemap 修复

- [VideoSiteMapLogic.php](/www/wwwroot/diff-maccms/SEONexus/code/app/task/logic/VideoSiteMapLogic.php)
- [SiteMapLogic.php](/www/wwwroot/diff-maccms/SEONexus/code/app/task/logic/SiteMapLogic.php)

这一组负责：

1. sitemap 目录递归创建
2. 详情 URL slug 规范化
3. 空 slug 回退

### 3.3 前台异常抓栈

- [ExceptionHandle.php](/www/wwwroot/diff-maccms/SEONexus/code/app/ExceptionHandle.php)

这一项是这次补的关键兜底。

作用：

1. 当前台 detail / play 类请求再出现 ThinkPHP 错页
2. 自动记录 host、url、route 参数、UA、异常 message、file、line
3. 方便后续按时间点抓栈

### 3.4 GPT 模板详情 / 播放 / 搜索页模板

- [getVideoInfo.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/video/getVideoInfo.html)
- [getVideoPlayUrl.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/video/getVideoPlayUrl.html)
- [dplayer.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/player/engine/dplayer.html)
- [title.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/detail_main/title.html)

搜索页：

- [search_header_simple.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/search/search_header_simple.html)
- [search_header_seo.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/search/search_header_seo.html)
- [search_header_rich.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/search/search_header_rich.html)
- [search_header_centered.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/search/search_header_centered.html)
- [search_header_media.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/search/search_header_media.html)

播放页：

- [play_01.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/play/play_01.html)
- [play_02.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/play/play_02.html)
- [play_03.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/play/play_03.html)
- [play_04.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/play/play_04.html)
- [play_05.html](/www/wwwroot/diff-maccms/SEONexus/code/app/home/view/videoGpt1/module/play/play_05.html)

## 4. 推荐同步顺序

不要乱序，建议按下面顺序做：

1. 先同步服务层与路由：
   - `SiteContext.php`
   - `VideoService.php`
   - `router.php`
2. 再同步 sitemap：
   - `VideoSiteMapLogic.php`
   - `SiteMapLogic.php`
3. 再同步 GPT 模板：
   - `getVideoInfo.html`
   - `getVideoPlayUrl.html`
   - 搜索页模板
   - 播放页模板
   - `detail_main/title.html`
4. 最后同步异常处理：
   - `ExceptionHandle.php`

原因：

1. 先保证路由和取数能通
2. 再保证 sitemap 不继续产坏链
3. 再保证页面展示层正常
4. 最后补抓栈，方便后续继续盯

## 5. 其它服务器接手 Codex 的执行步骤

### 第一步：先确认该服务器是不是同一条 GPT 模板线

先确认目标站是否真的使用 `videoGpt1`。

如果不是，就不要直接照搬这份文档。

如果是，就按“同模板线升级”处理，不要按“跨模板迁移”处理。

### 第二步：同步上面的必须文件

如果是同一套 GPT 模板代码目录，优先直接按文件覆盖同步。

如果是人工搬运，至少保证：

1. 服务层 3 个文件一起到位
2. sitemap 2 个文件一起到位
3. GPT 模板文件整组到位
4. `ExceptionHandle.php` 最后到位

### 第三步：清理运行时缓存

同步完代码后，至少做一次运行时清理，避免旧编译模板或旧路由缓存继续干扰。

重点关注：

1. 模板缓存
2. runtime 缓存
3. sitemap 输出缓存

如果接手的 Codex 不确定怎么清，就先只做安全清理，不要删业务数据。

### 第四步：先验 4 类 URL

每台 GPT 服务器完成最新版对齐后，至少要验这 4 类：

1. 首页
2. 搜索页
3. 详情页
4. 播放页

## 6. 上线后最小验收清单

### 6.1 详情页兜底

至少抽查 2 类：

1. 正常详情 URL
2. slug-only / pinyin 详情 URL

例如：

```text
/detail/pinyin-xxxxx
/film/slug/id
/movie/id-slug
```

通过标准：

1. 返回 `200`
2. canonical 正常
3. 页面主 `h1` 正常
4. 不再硬跳 ThinkPHP 错页

### 6.2 搜索页

通过标准：

1. 搜索页 `h1` 有内容
2. 不再空标题
3. 搜索结果页 title / canonical 正常

### 6.3 播放页

通过标准：

1. 播放页主标题正常
2. 标题不再掉成空值
3. 能从播放页正常回到详情页

### 6.4 sitemap

至少验：

1. `/sitemap.xml`
2. `/sitemap_index.xml`
3. `/sitemap-main.xml`

通过标准：

1. 返回 `200`
2. 能打开
3. 详情 URL 不再明显带空 slug

## 7. 推荐验收命令

### 看状态码

```bash
curl -I -L -s 'https://example.com/detail/pinyin-xxx'
```

### 看 nocache

```bash
curl -I -L -s 'https://example.com/detail/pinyin-xxx?__nocache=1'
```

### 抽取 title / canonical / h1

```bash
curl -L -s 'https://example.com/detail/pinyin-xxx' | rg -o '<title>.*?</title>|<link rel=\"canonical\".*?>|<h1[^>]*>.*?</h1>' -N
```

## 8. 如果仍出现 ThinkPHP 错页，先怎么查

这次已经补了前台 detail/play 异常日志。

如果其它服务器也同步了 [ExceptionHandle.php](/www/wwwroot/diff-maccms/SEONexus/code/app/ExceptionHandle.php)，下次再出现：

## 9. 蜘蛛池 MD 远程推送补充说明

如果其它服务器也要同步“蜘蛛池 MD 自动生成 + 远程推送”，这次已经支持：

1. Gitee 推送
2. GitHub 推送
3. 计划任务自动生成

### 9.1 后台系统配置里现在能看到的 GitHub 参数

进入“系统配置”后，搜索 `SPIDER_MD_GITHUB`，应该能看到：

1. `SPIDER_MD_GITHUB_ENABLED`
   - `0` 表示关闭
   - `1` 表示开启
2. `SPIDER_MD_GITHUB_OWNER`
   - 仓库所属用户名或组织名
   - 例如：`yourname`
3. `SPIDER_MD_GITHUB_REPO`
   - 仓库名，不带 owner
   - 例如：`seo-spider-md`
4. `SPIDER_MD_GITHUB_BRANCH`
   - 目标分支
   - 默认建议：`main`
5. `SPIDER_MD_GITHUB_ROOT`
   - 仓库内子目录
   - 默认可填：`seo-spider-md`
   - 如果想直接写仓库根目录，可以留空
6. `SPIDER_MD_GITHUB_TOKEN`
   - GitHub Token
   - 建议使用细粒度 Token
   - 至少给当前仓库 `Contents: Read and write`

### 9.2 最小可用配置

如果只想先跑通 GitHub 推送，最少需要填：

1. `SPIDER_MD_GITHUB_ENABLED=1`
2. `SPIDER_MD_GITHUB_OWNER`
3. `SPIDER_MD_GITHUB_REPO`
4. `SPIDER_MD_GITHUB_BRANCH`
5. `SPIDER_MD_GITHUB_ROOT`
6. `SPIDER_MD_GITHUB_TOKEN`

注意：

1. 只开 `ENABLED=1` 但没填 owner / repo / token，不会真正推送成功
2. `root` 只是远程目录，不是本地目录
3. GitHub 和 Gitee 可以并行开启，互不冲突

### 9.3 计划任务怎么接

这次已经补了计划任务种子命令：

```bash
php think plan:seed:domain-spider-md
```

作用：

1. 自动写入一条 `GENERATE_DOMAIN_SPIDER_MD` 计划任务
2. 默认是 `禁用` 状态，不会一落地就乱跑
3. 你可以进后台计划任务页再手工启用

执行逻辑：

1. 任务 code：`GENERATE_DOMAIN_SPIDER_MD`
2. 任务内容：生成蜘蛛池 MD
3. 如果配置了 Gitee / GitHub，就会同步推送远程文件

### 9.4 其它服务器上线后先验什么

至少先验下面 4 件事：

1. 后台系统配置能搜到 `SPIDER_MD_GITHUB_*`
2. 执行一次蜘蛛池 MD 生成后，摘要里能看到 GitHub 配置状态
3. 若已填 Token，生成记录里能看到 GitHub 推送结果
4. 若开了计划任务，后台计划任务列表里能看到 `GENERATE_DOMAIN_SPIDER_MD`

### 9.5 如果后台看不到 GitHub 配置项

优先排查：

1. 是否已同步 [SpiderMdConfigHelper.php](/www/wwwroot/diff-maccms/SEONexus/code/app/common/helper/SpiderMdConfigHelper.php)
2. 是否已同步 [SystemConfig.php](/www/wwwroot/diff-maccms/SEONexus/code/app/admin/controller/SystemConfig.php)
3. 是否打开过一次“系统配置”列表页

当前版本里，系统配置列表页会自动把 `SPIDER_MD_GITHUB_*` 与 `SPIDER_MD_GITEE_*` 默认项补进数据库。

## 10. Spider MD 异步任务窗口补充说明

这次还额外补了 `Spider MD` 的异步任务消费器。

意义是：

1. 后台点“生成并推送 / 强制重生成”后，不再只是创建一个 `queued` 任务
2. 任务会真正进入 `running`
3. 前台任务窗口会持续看到：
   - 当前阶段
   - 进度百分比
   - 实时日志
   - 失败原因

### 10.1 这次同步时必须注意的文件

- [DomainImportAsyncTaskLogic.php](/www/wwwroot/diff-maccms/SEONexus/code/app/task/logic/DomainImportAsyncTaskLogic.php)

如果漏掉这个文件，现场最常见的表现就是：

1. 后台按钮点了
2. 任务号也出来了
3. 但状态一直停在 `queued`
4. 进度条始终 `0%`
5. 日志窗口只显示“任务已入队，等待执行”

### 10.2 现场正确现象

同步后，Spider MD 任务窗口里应该能看到：

1. `status: running`
2. `progress_percent` 持续变化
3. 日志里出现：
   - 已载入多少个域名
   - `[1/32] ... [2/32] ...`
   - `已推送 GitHub：part-001.md`
   - 如果失败，会直接显示失败原因

### 10.3 后台复制体验补充

这次 Vue 后台还补了：

1. 主表右侧固定 `一键复制MD`
2. 复制内容只保留 `.md` 直链
3. 不再复制 `summary.json / summary.html`

如果其它服务器更新后发现：

1. 要横向滚很远才能看到按钮
2. 复制出来的是页面链接不是 md 直链

说明 `SEONexusAdmin` 最新代码还没有同步到位。

1. 先记下精确时间
   - 例如：`2026-04-18 14:23:15 +08:00`
2. 记下完整 URL
3. 去 runtime 日志里搜：
   - `frontend_detail_exception`

重点看：

1. `host`
2. `url`
3. `route.strPinyin`
4. `route.intVId`
5. `exception_message`
6. `exception_file`
7. `exception_line`

## 9. 给其它服务器 Codex 的接手话术

可以直接复制这段给对方：

```text
这次不是把别的模板迁到 GPT。

目标服务器原本也是 GPT 模板，现在要做的是把它对齐到当前最新 GPT 主线版本。

请只处理 videoGpt1 相关代码，不要混入 1001-1005 老模板。

必须一起同步：
1. app/services/SiteContext.php
2. app/services/VideoService.php
3. app/home/config/router.php
4. app/task/logic/VideoSiteMapLogic.php
5. app/task/logic/SiteMapLogic.php
6. app/ExceptionHandle.php
7. app/home/view/videoGpt1/video/getVideoInfo.html
8. app/home/view/videoGpt1/video/getVideoPlayUrl.html
9. app/home/view/videoGpt1/module/detail_main/title.html
10. app/home/view/videoGpt1/module/player/engine/dplayer.html
11. app/home/view/videoGpt1/module/search/ 下 5 个搜索页模板
12. app/home/view/videoGpt1/module/play/ 下 5 个播放页模板

更新完成后先验：
1. 首页
2. 搜索页
3. 详情页
4. 播放页
5. sitemap.xml / sitemap_index.xml / sitemap-main.xml

重点确认：
1. slug-only 详情不再 404
2. 搜索页 h1 正常
3. 播放页 h1 正常
4. canonical 正常
5. 如再出现 ThinkPHP 错页，去查 frontend_detail_exception 日志
```

## 10. 接手前建议先看

先看这些文档再动代码：

1. [README.md](/www/wwwroot/diff-maccms/SEONexus/docs/gpt-template-seo/README.md)
2. [00-GPT模板SEO公共总览-2026-04-18.md](/www/wwwroot/diff-maccms/SEONexus/docs/gpt-template-seo/00-GPT模板SEO公共总览-2026-04-18.md)
3. [07-GPT模板交接说明-2026-04-18.md](/www/wwwroot/diff-maccms/SEONexus/docs/gpt-template-seo/07-GPT模板交接说明-2026-04-18.md)

## 11. 一句话结论

> 其它服务器如果原本也是 GPT 模板，现在要对齐到当前最新版，不要只改几个模板文件，必须把路由、服务层、sitemap 和异常抓栈一起同步，否则最容易出现“页面样式像更新了，但 slug 详情 / sitemap / 偶发异常仍停在旧版本”的半更新问题。