# 前端站群 nginx 配置目录说明

这份文档用于把服务器目录里的 nginx 模板整理规则同步回 `SEONexus/docs`，避免后续出现：

1. 代码仓里说一套
2. 服务器目录里放一套
3. 接手时又不知道到底该复制哪份

## 当前正式发布入口

前端站群服务器目录中，当前长期正式发布入口是：

- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-最终发布版.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-最终发布版.txt)

如果目标是：

1. 真正复制到站群站点里
2. 替换线上站点伪静态
3. 作为后续默认模板继续迭代

那么优先从这份开始，不要再从旧模板复制。

## 当前长期规则

### 1. 搜索页

真实搜索入口至少存在两种：

1. `/get-index`
2. `/get/index`

因此正式模板里必须同时兼容这两种路径。

搜索页规则：

1. cache key 必须带 `$args`
2. 否则不同关键词会串缓存
3. 线上排障时应看到：
   - `X-Cache-Mode: with-args`

### 2. 详情页 / 播放页 / 分类页 / 榜单页

这类动态页规则：

1. cache key 不带 `$args`
2. 保持缓存稳定
3. 避免无意义 query 参数打碎缓存

线上排障时常见：

1. `X-Cache-Mode: path-only`
2. `X-Cache-Status: HIT / MISS / STALE`

### 3. 所有动态页

都支持人工排障参数：

- `?__nocache=1`

用途：

1. 只用于人工排障
2. 强制跳过前端缓存
3. 便于确认“代码未生效”到底是不是缓存误判

正常响应头表现：

1. `X-Cache-Status: BYPASS`
2. `X-Cache-Mode: bypass`
3. `X-Cache-Bypass: 1`

## 推荐排障顺序

以后再遇到“前端像没更新”“搜索页像串页”“蜘蛛看起来异常”时，先按这个顺序走：

1. 先看 `X-Cache-Status`
2. 再看 `X-Cache-Mode`
3. 再看 `X-Managed-Spider`
4. 若仍怀疑前端缓存顶旧 HTML，用 `?__nocache=1`
5. 如果 `?__nocache=1` 正常，而普通访问异常，优先清前端缓存

## 目录内文件角色

### 当前正式版

- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-最终发布版.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-最终发布版.txt)

### 当前可用组合版

- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-受管蜘蛛放行版-动态页安全缓存.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-受管蜘蛛放行版-动态页安全缓存.txt)

说明：

1. 这是当前可用的组合版模板
2. 与最终发布版功能接近
3. 保留作过程版本参考

### 历史版本

- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态.txt)
- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-百度放行版.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-百度放行版.txt)
- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-受管蜘蛛放行版.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-受管蜘蛛放行版.txt)
- [/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-动态页安全缓存版.txt](/www/wwwroot/diff-maccms/前端站群服务器nginx配置/站点伪静态-动态页安全缓存版.txt)

这些文件都保留了顶部版本说明。

如果不是为了：

1. 对比历史演进
2. 回看当时为什么这么改
3. 查某个阶段的专项版本

就不要直接从这些旧文件复制上线。

## 接手时只记一条

如果目标是正式发线上：

1. 从 `站点伪静态-最终发布版.txt` 开始
2. 搜索页一定兼容 `/get-index` 和 `/get/index`
3. 先看响应头，再怀疑代码