xiaso-flnxi-website/NGINX_NO_CACHE_GUIDE.md

# Nginx 禁用缓存配置指南

## 📋 问题说明

**问题**：首页导航栏"更新日志"功能已添加到代码中，但由于 Nginx 缓存导致浏览器看到的仍是旧版本。

**解决方案**：更新 Nginx 配置，禁用动态内容缓存，同时保持静态资源的合理缓存策略。

---

## 🔧 配置步骤

### 1. 备份现有配置

```bash
# 登录服务器
ssh root@your-server-ip

# 备份当前配置
cp /www/server/panel/vhost/nginx/scs.flnxi.com.conf /www/server/panel/vhost/nginx/scs.flnxi.com.conf.backup.$(date +%Y%m%d_%H%M%S)
```

### 2. 更新 Nginx 配置

将项目中的 `nginx-no-cache.conf` 文件内容复制到服务器：

```bash
# 方式1: 使用 vim 编辑器
vim /www/server/panel/vhost/nginx/scs.flnxi.com.conf

# 方式2: 使用 nano 编辑器
nano /www/server/panel/vhost/nginx/scs.flnxi.com.conf

# 将 nginx-no-cache.conf 的全部内容粘贴进去，保存退出
```

### 3. 测试配置

```bash
# 测试 Nginx 配置语法
nginx -t

# 应该看到类似输出：
# nginx: the configuration file /www/server/nginx/conf/nginx.conf syntax is ok
# nginx: configuration file /www/server/nginx/conf/nginx.conf test is successful
```

### 4. 重载 Nginx

```bash
# 平滑重载 Nginx（不中断服务）
nginx -s reload

# 或者使用 systemctl
systemctl reload nginx
```

### 5. 清除浏览器缓存

**重要**：更新配置后，必须清除浏览器缓存才能看到效果。

#### Chrome/Edge 浏览器：
1. 按 `F12` 打开开发者工具
2. 右键点击刷新按钮
3. 选择"清空缓存并硬性重新加载"

#### Firefox 浏览器：
1. 按 `Ctrl + Shift + Delete`（Mac: `Cmd + Shift + Delete`）
2. 选择"缓存"
3. 点击"立即清除"

#### Safari 浏览器：
1. 按 `Option + Cmd + E` 清空缓存
2. 然后按 `Cmd + R` 刷新页面

### 6. 验证更新

访问网站并检查：

```bash
# 使用 curl 检查响应头
curl -I https://scs.flnxi.com/

# 应该看到以下缓存控制头：
# Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0
# Pragma: no-cache
# Expires: 0
```

在浏览器中访问：
- ✅ 首页导航栏应该显示"更新日志"链接
- ✅ 点击"更新日志"应该跳转到 `/changelog` 页面
- ✅ 页面应该显示完整的版本更新历史

---

## 📝 配置说明

### 缓存策略

新配置采用分层缓存策略：

#### 1. 动态内容（不缓存）
- **适用**：HTML 页面、API 响应、JSON 数据
- **缓存头**：`Cache-Control: no-store, no-cache, must-revalidate`
- **原因**：确保用户始终看到最新内容

#### 2. Next.js 静态资源（长期缓存）
- **适用**：`/_next/static/*` 文件
- **缓存头**：`Cache-Control: public, max-age=31536000, immutable`
- **原因**：这些文件包含版本 hash，永远不会冲突

#### 3. 图片资源（中等缓存）
- **适用**：`/images/*` 文件
- **缓存头**：`Cache-Control: public, max-age=86400`（24小时）
- **原因**：平衡性能和更新频率

### 关键配置项

```nginx
# 禁用代理缓存
proxy_cache off;
proxy_no_cache 1;
proxy_cache_bypass 1;

# 禁用浏览器缓存（动态内容）
add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
add_header Pragma "no-cache" always;
add_header Expires "0" always;
```

---

## 🚀 快速部署命令

如果您想快速部署，可以使用以下一键命令：

```bash
# 备份 + 测试 + 重载（需要手动编辑配置文件）
cp /www/server/panel/vhost/nginx/scs.flnxi.com.conf /www/server/panel/vhost/nginx/scs.flnxi.com.conf.backup.$(date +%Y%m%d) && \
vim /www/server/panel/vhost/nginx/scs.flnxi.com.conf && \
nginx -t && \
nginx -s reload && \
echo "✅ Nginx 配置已更新！请清除浏览器缓存。"
```

---

## 🔍 故障排查

### 问题1：Nginx 配置测试失败

```bash
# 查看错误详情
nginx -t

# 查看错误日志
tail -50 /www/wwwlogs/scs.flnxi.com.error.log
```

**常见原因**：
- 配置文件语法错误
- 证书路径不正确
- 端口冲突

### 问题2：更新后仍看不到新内容

**解决步骤**：
1. 确认 Nginx 已重载：`systemctl status nginx`
2. 清除浏览器缓存（见上文）
3. 使用无痕模式测试
4. 检查 Docker 容器是否运行：`docker-compose ps`
5. 重新构建 Docker 镜像：
   ```bash
   cd /root/xiaso  # 进入项目目录
   docker-compose down
   docker-compose up -d --build
   ```

### 问题3：静态资源加载失败

```bash
# 检查 Next.js 应用是否正常运行
curl http://127.0.0.1:4782

# 检查 Docker 日志
docker-compose logs web
```

### 问题4：SSL 证书错误

```bash
# 检查证书文件是否存在
ls -la /www/server/panel/vhost/cert/scs.flnxi.com/

# 检查证书有效期
openssl x509 -in /www/server/panel/vhost/cert/scs.flnxi.com/fullchain.pem -noout -dates
```

---

## 📊 性能影响

### 禁用缓存的影响

**优点**：
- ✅ 用户始终看到最新内容
- ✅ 便于开发和调试
- ✅ 避免缓存导致的问题

**缺点**：
- ⚠️ 服务器负载略微增加
- ⚠️ 页面加载速度可能略慢（但有 Gzip 压缩和静态资源缓存）

### 优化建议

如果后续网站流量增大，可以考虑：

1. **启用有限缓存**（如 5 分钟）：
   ```nginx
   add_header Cache-Control "public, max-age=300";
   ```

2. **使用 CDN**：将静态资源托管到 CDN
3. **启用 HTTP/2 推送**：优化资源加载
4. **配置 Redis 缓存**：在应用层缓存

---

## 📞 验证清单

部署完成后，请检查以下项目：

- [ ] Nginx 配置测试通过（`nginx -t`）
- [ ] Nginx 已成功重载
- [ ] 浏览器缓存已清除
- [ ] 首页可以正常访问
- [ ] 导航栏显示"更新日志"链接
- [ ] 点击"更新日志"可以正常跳转
- [ ] 更新日志页面内容正确显示
- [ ] "返回首页"链接工作正常
- [ ] HTTPS 访问正常
- [ ] HTTP 自动跳转到 HTTPS
- [ ] 响应头包含正确的缓存控制信息

---

## 📁 相关文件

- **Nginx 配置文件**：`nginx-no-cache.conf`（本项目）
- **服务器配置路径**：`/www/server/panel/vhost/nginx/scs.flnxi.com.conf`
- **Header 组件**：`components/Header.tsx`
- **更新日志页面**：`app/changelog/page.tsx`

---

## 🎯 导航栏功能说明

### 当前导航项

Header.tsx 中定义的导航项：

```typescript
const navItems = [
  { name: '功能特性', href: '#features' },
  { name: '技术规格', href: '#specs' },
  { name: '定价', href: '#pricing' },
  { name: '更新日志', href: '/changelog' },  // ← 已添加
  { name: '联系我们', href: '#contact' },
]
```

### 桌面端显示
- 显示在顶部导航栏
- 蓝色悬停效果
- 直接点击跳转

### 移动端显示
- 点击菜单按钮展开
- 卡片式布局
- 同样的导航项

---

## 💡 注意事项

1. **备份很重要**：修改配置前务必备份
2. **测试后再重载**：使用 `nginx -t` 确保配置正确
3. **清除缓存**：Nginx 配置更新后，必须清除浏览器缓存
4. **生产环境**：如果网站流量大，建议在低峰期更新
5. **监控日志**：更新后关注错误日志，及时发现问题

---

## 📮 获取帮助

如果遇到问题：

1. 查看 Nginx 错误日志：`/www/wwwlogs/scs.flnxi.com.error.log`
2. 查看 Docker 日志：`docker-compose logs -f web`
3. 检查端口占用：`netstat -tulpn | grep :4782`
4. 测试应用直连：`curl http://127.0.0.1:4782`

---

**最后更新**：2025-10-26  
**版本**：v1.0  
**状态**：已测试 ✅