📁 Nginx 配置文件结构

🗂️ 目录结构总览

nginx/                                           # Nginx 配置目录
│
├── 📖 入口文档（从这里开始）
│   └── 开始阅读.md                               ⭐ 推荐首先阅读
│
├── 📚 核心文档
│   ├── INDEX.md                                  # 文档索引与导航
│   ├── 快速部署指南.md                           # 快速部署手册
│   ├── README.md                                 # 详细配置说明
│   ├── 配置对比.md                               # 新旧配置对比分析
│   ├── 配置规划总结.md                           # 完整规划总结
│   └── 文件结构.md                               # 本文件
│
├── ✅ 使用中的配置（核心文件）
│   └── ruoyi-office.conf                         # 统一配置文件
│
├── ⚠️ 已弃用的配置（仅供参考）
│   ├── default.conf                              # Nginx 原始配置（已弃用）
│   ├── ruoyi-office-doc.conf                     # VitePress 旧配置（已弃用）
│   └── web-antd.conf                             # Vben 旧配置（语法错误，已弃用）
│
└── 🔧 工具脚本
    └── deploy-nginx-config.sh                    # 自动化部署脚本

📋 文件分类详解

1️⃣ 入口文档（必读）

📄 开始阅读.md

• 用途: 快速入门指南，3分钟快速了解和部署
• 适合: 所有用户，首次使用
• 内容: 快速开始、常见问题、命令速查
• 优先级: ⭐⭐⭐⭐⭐

2️⃣ 核心文档（推荐阅读）

📄 INDEX.md

• 用途: 文档索引与导航中心
• 适合: 需要查找特定文档的用户
• 内容: 完整的文档列表、快速参考、配置更新流程
• 优先级: ⭐⭐⭐⭐

📄 快速部署指南.md

• 用途: 详细的部署步骤和故障排查
• 适合: 实际部署时参考
• 内容: 一键部署、检查清单、常用命令、故障排查
• 优先级: ⭐⭐⭐⭐⭐

📄 README.md

• 用途: 完整的配置说明文档
• 适合: 需要深入了解配置的用户
• 内容: 配置架构、特性说明、部署步骤、常见问题
• 优先级: ⭐⭐⭐⭐

📄 配置对比.md

• 用途: 新旧配置对比和改进说明
• 适合: 想了解为什么要更换配置的用户
• 内容: 配置对比、性能对比、语法错误修复、迁移建议
• 优先级: ⭐⭐⭐

📄 配置规划总结.md

• 用途: 完整的配置规划总结报告
• 适合: 需要全局了解项目规划的用户
• 内容: 规划概述、架构设计、技术决策、验收标准
• 优先级: ⭐⭐⭐

📄 文件结构.md

• 用途: 文件结构说明（本文件）
• 适合: 需要了解文件组织的用户
• 内容: 目录结构、文件分类、阅读路径
• 优先级: ⭐⭐

3️⃣ 配置文件

✅ 使用中的配置

📝 ruoyi-office.conf

• 用途: 统一的 Nginx 配置文件（唯一使用的配置）
• 适合: 部署到服务器的配置文件
• 内容:
  • VitePress 文档站点配置（根路径 /）
  • Vben Admin 管理后台配置（子路径 /web）
  • 完整的性能优化（Gzip、缓存）
  • 安全配置（隐藏文件保护）
  • 健康检查接口
• 状态: ✅ 生产使用中
• 位置:
  • 本地：nginx/ruoyi-office.conf
  • 服务器：/data/nginx/conf/conf.d/ruoyi-office.conf

⚠️ 已弃用的配置（不要使用）

📝 default.conf

• 用途: Nginx 原始默认配置
• 状态: ⚠️ 已弃用
• 问题: 基础配置，缺少性能优化
• 替代: ruoyi-office.conf

📝 ruoyi-office-doc.conf

• 用途: VitePress 文档独立配置
• 状态: ⚠️ 已弃用
• 问题: 独立配置，会与其他配置冲突
• 替代: ruoyi-office.conf

📝 web-antd.conf

• 用途: Vben Admin 独立配置
• 状态: ❌ 已弃用（有语法错误）
• 问题:
  • 语法错误: location 指令直接放在文件顶层，必须在 server 块内
  • 错误信息: nginx: [emerg] "location" directive is not allowed here
• 替代: ruoyi-office.conf

4️⃣ 工具脚本

🔧 deploy-nginx-config.sh

• 用途: 自动化部署脚本
• 功能:
  1. ✅ 自动备份现有配置
  2. ✅ 上传新配置文件
  3. ✅ 删除旧配置文件
  4. ✅ 验证配置语法
  5. ✅ 重新加载 Nginx
  6. ✅ 验证部署结果
  7. ✅ 失败自动回滚
• 使用:

  chmod +x deploy-nginx-config.sh
  ./deploy-nginx-config.sh

• 优先级: ⭐⭐⭐⭐⭐

🎯 文档阅读路径

路径1: 快速部署（推荐）

适合：想快速部署的用户

开始阅读.md → 快速部署指南.md → 执行部署脚本
   (3分钟)         (5分钟)           (1分钟)

总耗时: 约 10 分钟

路径2: 深入了解后部署

适合：想深入了解再部署的用户

开始阅读.md → README.md → 配置对比.md → 快速部署指南.md → 执行部署
   (3分钟)     (10分钟)     (10分钟)        (5分钟)         (1分钟)

总耗时: 约 30 分钟

路径3: 全面学习

适合：想全面了解配置规划的用户

开始阅读.md → INDEX.md → README.md → 配置对比.md → 配置规划总结.md → 快速部署指南.md → 执行部署
   (3分钟)     (5分钟)    (10分钟)     (10分钟)        (15分钟)           (5分钟)         (1分钟)

总耗时: 约 50 分钟

路径4: 故障排查

适合：部署遇到问题的用户

快速部署指南.md - 故障排查 → README.md - 常见问题 → 检查日志
      (5分钟)                     (5分钟)           (按需)

📊 文件依赖关系

开始阅读.md
    │
    ├─→ 快速部署指南.md ⭐ 推荐
    │       │
    │       ├─→ deploy-nginx-config.sh（部署脚本）
    │       ├─→ ruoyi-office.conf（配置文件）
    │       └─→ 故障排查部分
    │
    ├─→ INDEX.md
    │       │
    │       └─→ 指向所有其他文档
    │
    ├─→ README.md
    │       │
    │       ├─→ 配置架构说明
    │       ├─→ 部署步骤详解
    │       └─→ 常见问题
    │
    ├─→ 配置对比.md
    │       │
    │       ├─→ 新旧配置对比
    │       ├─→ 性能改进
    │       └─→ 语法错误修复
    │
    └─→ 配置规划总结.md
            │
            ├─→ 整体规划概述
            ├─→ 技术决策说明
            └─→ 验收标准

🗂️ 服务器端文件组织

部署前（旧配置）

/data/nginx/conf/conf.d/
├── default.conf                # Nginx 默认配置
├── ruoyi-office-doc.conf       # VitePress 配置
└── web-antd.conf               # Vben 配置（语法错误）

问题:

• ❌ web-antd.conf 语法错误
• ⚠️ 配置分散，难以管理
• ⚠️ 可能存在端口冲突

部署后（新配置）

/data/nginx/conf/conf.d/
├── ruoyi-office.conf           # ✅ 统一配置（使用中）
└── backup-20260121-153000/     # 备份目录
    ├── default.conf            # 旧配置备份
    ├── ruoyi-office-doc.conf   # 旧配置备份
    └── web-antd.conf           # 旧配置备份

优势:

• ✅ 只有一个配置文件
• ✅ 旧配置已备份
• ✅ 配置语法正确
• ✅ 易于管理和维护

🎨 文档类型图标说明

图标	说明
📖	入口文档
📚	核心文档
📄	文档文件
📝	配置文件
🔧	工具脚本
✅	使用中/正确
⚠️	已弃用/警告
❌	错误/禁止使用
⭐	推荐/重要

📏 文件大小参考

文件	大小	说明
开始阅读.md	~5KB	快速入门
快速部署指南.md	~15KB	详细步骤
INDEX.md	~12KB	文档索引
README.md	~18KB	详细说明
配置对比.md	~25KB	对比分析
配置规划总结.md	~35KB	完整总结
ruoyi-office.conf	~5KB	配置文件
deploy-nginx-config.sh	~2KB	部署脚本

🔄 版本管理

当前版本: v2.0

版本	日期	说明
v2.0	2026-01-21	统一配置方案，修复语法错误
v1.0	2026-01-20	初始版本，独立配置文件

版本变更

v1.0 → v2.0:

• ✅ 修复 web-antd.conf 语法错误
• ✅ 合并 3 个配置文件为 1 个
• ✅ 添加完整的性能优化
• ✅ 提供自动化部署脚本
• ✅ 完善文档体系

💡 使用建议

对于首次使用者

1. ⭐ 阅读 开始阅读.md（3分钟）
2. ⭐ 阅读 快速部署指南.md（5分钟）
3. ⭐ 执行 deploy-nginx-config.sh（1分钟）
4. 验证部署结果

对于需要深入了解的用户

1. 阅读 开始阅读.md
2. 浏览 INDEX.md 了解文档结构
3. 阅读 README.md 了解详细配置
4. 阅读 配置对比.md 了解改进
5. 执行部署

对于维护人员

1. 掌握 快速部署指南.md 中的所有命令
2. 理解 README.md 中的配置说明
3. 熟悉 配置规划总结.md 中的技术决策
4. 定期查看服务器日志

对于遇到问题的用户

1. 查看 快速部署指南.md 的故障排查部分
2. 查看 README.md 的常见问题部分
3. 检查 Nginx 错误日志
4. 尝试回滚配置

🎯 快速命令索引

部署相关

# 一键部署
./deploy-nginx-config.sh

# 验证配置
ssh root@127.0.0.1 'docker exec nginx nginx -t'

# 重新加载
ssh root@127.0.0.1 'docker exec nginx nginx -s reload'

查看相关

# 查看配置
ssh root@127.0.0.1 'cat /data/nginx/conf/conf.d/ruoyi-office.conf'

# 查看日志
ssh root@127.0.0.1 'docker exec nginx tail -f /var/log/nginx/ruoyi-office-access.log'

# 查看备份
ssh root@127.0.0.1 'ls -lh /data/nginx/conf/conf.d/backup-*'

测试相关

# 测试文档站点
curl -I http://127.0.0.1/

# 测试管理后台
curl -I http://127.0.0.1/web

# 测试健康检查
curl http://127.0.0.1/health

---

提示: 建议从 开始阅读.md 开始！ 🚀