【笔记】Nginx 核心操作 + 配置解析笔记（适配 Linux+FastAPI / 前端代理场景）
一、Nginx 核心目录（Linux 标准路径）
| 目录 / 文件路径 | 作用 | 常用操作 |
|---|---|---|
/etc/nginx/ | Nginx 主配置根目录 | 存放所有配置文件，核心目录 |
/etc/nginx/nginx.conf | 全局主配置文件 | 配置性能、日志、gzip 等全局规则 |
/etc/nginx/conf.d/ | 业务配置目录 | 存放前端部署、接口代理等业务配置（如你的 fastapi-frontend.conf） |
/etc/nginx/mime.types | 文件类型识别配置 | 默认识别图片 / JS/CSS 等，无需修改 |
/var/log/nginx/ | 日志目录 | access.log（访问日志）、error.log（错误日志），排查问题必备 |
/var/run/nginx.pid | 进程 PID 文件 | 启动后自动生成，用于管理 Nginx 进程 |
/usr/share/nginx/html/ | Nginx 默认静态目录 | 存放 50x.html 等默认错误页面 |
/home/dell/react/login-ant/dist | 你的前端静态目录 | Nginx 从这里读取前端 HTML/JS/CSS |
二、Nginx 服务管理命令（最常用，必记）
基于systemctl（Linux 通用），生产环境优先用热重载，避免服务中断
sudo systemctl start nginx # 启动Nginx服务 sudo systemctl stop nginx # 停止Nginx服务 sudo systemctl restart nginx # 重启Nginx（配置修改后生效，会短暂中断） sudo systemctl reload nginx # 热重载Nginx（推荐！生产环境配置修改后用，不中断服务） sudo systemctl enable nginx # 设置Nginx开机自启（生产环境必配） sudo systemctl disable nginx # 关闭开机自启 sudo systemctl status nginx # 查看运行状态（active(running)为正常，failed为失败） 状态解读
active (running)：正常运行，可对外提供服务；inactive (dead)：未启动，需执行 start 命令；failed：启动失败，优先看错误日志排查。
三、Nginx 配置验证 & 日志查看（排查问题核心）
1. 配置合法性验证（修改配置后必做，避免启动失败）
sudo nginx -t # 核心命令！验证所有配置语法/路径是否正确 - 成功提示：
nginx: configuration file /etc/nginx/nginx.conf test is successful - 失败提示：会标注错误行号 + 原因（如路径不存在、语法错误），按提示修改即可。
2. 日志查看命令（实时 / 精准排查，按场景用）
# 访问日志：记录所有前端/接口请求，排查404/转发问题 tail -f /var/log/nginx/access.log # 实时滚动查看（最常用，f=follow） tail -n 100 /var/log/nginx/access.log # 查看最近100行 grep "/api" /var/log/nginx/access.log # 搜索/api相关请求 grep "192.168.10.110" /var/log/nginx/access.log # 搜索指定IP请求 # 错误日志：记录启动失败/502/权限错误，优先排查 tail -f /var/log/nginx/error.log # 实时滚动查看（启动失败/502必看） tail -n 50 /var/log/nginx/error.log # 查看最近50行错误 # 日志清理（日志过大时用，不删除文件，避免Nginx写入失败） echo "" > /var/log/nginx/access.log echo "" > /var/log/nginx/error.log 四、Nginx 配置修改标准流程（生产环境防错）
所有配置修改必须按此流程，避免服务故障！
- 编辑配置文件（用 vim，新手也可用 nano）
sudo vim /etc/nginx/nginx.conf # 编辑全局主配置 sudo vim /etc/nginx/conf.d/fastapi-frontend.conf # 编辑你的前端/代理配置（最常用） 2.验证配置合法性（必做）
sudo nginx -t 3.生效配置（生产环境用热重载）
sudo systemctl reload nginx 4.验证效果（访问前端 / 接口，检查是否符合预期）
常用 vim 编辑快捷键（修改配置必备）
i # 进入编辑模式（可输入/修改内容） Esc # 退出编辑模式（准备保存/退出） :wq # 保存并退出（修改完成后用） :q! # 不保存强制退出（修改错误时用，回滚原配置） /关键词 # 搜索配置中的关键词（如/api、gzip，按n跳至下一个） 五、核心配置文件全解析
（一）全局主配置：/etc/nginx/nginx.conf（全局生效，所有业务继承）
# 1. 进程管理配置 user root; # 运行用户，保持和你环境一致，避免权限问题 worker_processes auto; # 工作进程数，auto=匹配CPU核心数（生产环境最优，比固定1高效） error_log /var/log/nginx/error.log warn; # 错误日志：路径+级别（warn减少日志量，生产环境推荐） pid /var/run/nginx.pid; # PID文件路径，Linux标准 # 2. 事件驱动配置（并发处理） events { worker_connections 1024; # 单进程最大连接数，支撑你的双网口场景足够 use epoll; # Linux高性能IO模型，提升并发处理能力（生产环境必加） } # 3. 全局HTTP配置（核心，所有业务server继承） http { include /etc/nginx/mime.types; # 引入文件类型识别配置，识别图片/JS等 default_type application/octet-stream; # 默认文件类型，无需修改 # 🌟 生产环境核心性能优化（必配，提升传输/并发速度） sendfile on; # 高效文件传输，跳过用户进程，减少IO开销，提升静态资源（图片/JS）速度 tcp_nopush on; # 配合sendfile，减少TCP分片，优化大文件（图片）传输 tcp_nodelay on; # 小数据包立即发送，适配API接口转发，和tcp_nopush不冲突 keepalive_timeout 60s; # TCP长连接超时，复用连接减少握手开销，单设备访问更快 keepalive_requests 100; # 单个长连接最多处理100个请求，避免资源占用 client_max_body_size 100M; # 允许上传大文件/图片（按需调整，解决413上传过大错误） # 日志格式（生产环境标准，记录请求IP/状态/路径等） log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/access.log main; # 访问日志按main格式记录 # 🌟 全局gzip压缩（所有业务共享，图片/JS/接口JSON都压缩） gzip on; # 开启gzip压缩，核心：减小传输体积30%-60% gzip_min_length 1k; # 大于1k才压缩，避免小文件浪费服务器资源 gzip_comp_level 6; # 压缩级别1-9，6兼顾速度和压缩比（图片首选） gzip_vary on; # 告诉浏览器/代理缓存压缩文件，避免重复压缩 gzip_http_version 1.1; # 兼容主流HTTP协议版本 gzip_types # 需压缩的文件类型（核心：包含所有图片+前端资源+JSON） image/jpeg image/jpg image/png image/gif image/webp image/svg+xml text/css text/javascript application/javascript application/json text/plain text/xml; include /etc/nginx/conf.d/*.conf; # 引入conf.d下所有业务配置（核心：分离全局和业务） } （二）业务配置：/etc/nginx/conf.d/fastapi-frontend.conf（8080 端口，双网口适配）
# 业务配置：前端React部署 + FastAPI/api+/static代理（双网口8080端口） server { listen 8080; # 前端对外访问端口，浏览器访问 IP:8080 server_name _; # 匹配所有IP/域名，适配双网口192.168.10.120/10.10.12.160，无需单独配置 server_tokens off; # 安全优化：隐藏Nginx版本号，避免漏洞攻击 root /home/dell/react/login-ant/dist; # 你的前端静态资源根目录（Nginx从这读前端文件） index index.html; # 前端默认首页，SPA入口文件 # 🌟 1. 前端SPA路由处理（解决React/Vue history模式刷新404，核心！） location / { try_files $uri $uri/ /index.html; # 匹配规则：先找文件→找文件夹→跳index.html，由前端JS处理路由 expires 1d; # 前端本地静态资源（JS/CSS/图片）缓存1天，提升加载速度 add_header Cache-Control "public, max-age=86400"; # 强化浏览器缓存，配合expires } # 🌟 2. FastAPI API接口代理（/api开头的业务请求，如登录/查询） location /api { proxy_pass http://127.0.0.1:8002; # 转发到FastAPI本地地址（127.0.0.1比外网IP稳定，无网络损耗） # 保留客户端原始信息（FastAPI可获取真实IP/请求头） proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 客户端真实IP，FastAPI可通过此头获取 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 允许Cookie跨域携带（配合FastAPI的CORS，保持登录态，核心！） proxy_cookie_path / /; proxy_http_version 1.1; proxy_set_header Connection ""; # 代理超时时间（避免后端接口响应慢，Nginx提前断开连接） proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # 🌟 3. FastAPI静态资源代理（/static开头，后端的静态文件/图片） location /static { proxy_pass http://127.0.0.1:8002; # 转发到FastAPI的/static目录 proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; expires 7d; # 后端静态资源缓存7天 add_header Cache-Control "public, max-age=604800"; } # 🌟 4. 图片专属精细化代理（优先级高于/static，图片最优配置） location ~* /static/.*\.(jpg|jpeg|png|gif|webp|svg)$ { proxy_pass http://127.0.0.1:8002; # 转发到FastAPI图片源 expires 30d; # 图片几乎不修改，缓存30天（最大化减少请求，提升速度） # 强缓存：浏览器30天内直接用本地缓存，不向服务器发请求 add_header Cache-Control "public, max-age=2592000, immutable"; access_log off; # 关闭图片访问日志（图片请求量大，减少磁盘IO开销） log_not_found off; # 关闭图片404日志，进一步减少日志量 } # 错误页面配置（提升用户体验） error_page 404 /index.html; # 404跳前端index.html，避免SPA白页 error_page 500 502 503 504 /50x.html; # 5xx服务器错误跳Nginx默认错误页 location = /50x.html { root /usr/share/nginx/html; # Nginx默认错误页目录 } } 配置核心关键词记忆
| 配置关键词 | 核心作用 | 常用场景 |
|---|---|---|
listen | 设置 Nginx 监听端口 | 前端 8080、默认 80/443 |
server_name | 匹配访问的 IP / 域名 | _匹配所有，双网口必用 |
root | 静态资源根目录 | 前端 dist、Nginx 默认 html |
location | 路径匹配规则 | /匹配根路径、/api匹配接口 |
try_files | SPA 路由处理，解决刷新 404 | 前端location /中必配 |
proxy_pass | 反向代理核心，转发请求 | /api//static代理到 FastAPI |
gzip | 开启压缩，减小传输体积 | 全局 http 块，图片 / JS 必压缩 |
expires | 浏览器缓存时间 | 静态资源 / 图片，长期缓存减少请求 |
add_header | 添加响应头 | 缓存、跨域、强缓存 |
client_max_body_size | 限制上传文件大小 | 解决 413 上传过大错误 |
六、Nginx 常见问题排查
1. Nginx 启动失败（systemctl status nginx显示 failed）
# 步骤1：查看错误日志（最直接，定位原因） tail -f /var/log/nginx/error.log # 步骤2：重新验证配置（检查语法/路径错误） sudo nginx -t # 常见原因：配置语法错误、路径不存在、端口被占用 2. 前端访问 404 / 刷新白页（SPA 路由问题）
- 检查
location /中是否有：try_files $uri $uri/ /index.html; - 确认
root路径是前端打包后的 dist 目录，路径无拼写错误。
3. 接口报 502 Bad Gateway（代理 FastAPI 失败）
# 步骤1：检查FastAPI是否正常运行 sudo systemctl status fastapi # 步骤2：检查Nginx代理地址是否正确（必须是127.0.0.1:8002） grep "proxy_pass" /etc/nginx/conf.d/fastapi-frontend.conf # 步骤3：测试服务器本地能否访问FastAPI curl http://127.0.0.1:8002/api/hello # 常见原因：FastAPI未启动、代理端口写错、FastAPI未绑定0.0.0.0 4. 图片 / 文件无法访问（403/404）
# 步骤1：检查FastAPI的/static目录是否存在+权限正常 ls -l /home/dell/react/login-ant/backend/static # 步骤2：检查Nginx图片代理规则是否匹配FastAPI图片路径 grep -E "jpg|png|webp" /etc/nginx/conf.d/fastapi-frontend.conf # 步骤3：检查Nginx运行用户是否有目录读写权限 chown -R root:root /home/dell/react/login-ant/backend/static # 适配你的root用户 5. 上传图片 / 文件报 413 Request Entity Too Large
- 修改
/etc/nginx/nginx.conf中的client_max_body_size，增大限制（如 100M）； - 热重载 Nginx：
sudo systemctl reload nginx。
6. 跨域错误（No 'Access-Control-Allow-Origin' header）
- 优先检查FastAPI 的 CORS 配置（必须允许 Nginx 的 IP:8080）；
- 无需在 Nginx 加跨域头，代理后由 FastAPI 的 CORS 兜底即可。
七、联动操作（Nginx+FastAPI + 服务器）
1. FastAPI 服务管理（后端重启 / 日志查看）
sudo systemctl start fastapi # 启动FastAPI sudo systemctl stop fastapi # 停止FastAPI sudo systemctl restart fastapi # 重启FastAPI（配置/代码修改后） sudo systemctl status fastapi # 查看FastAPI状态 journalctl -u fastapi -f # 查看FastAPI实时日志（排查后端接口问题） 2. 服务器端口开放（双网口场景，确保 8080 端口可访问）
sudo ufw allow 8080/tcp # 开放Nginx前端8080端口（核心，双网段设备都需要） sudo ufw allow 8002/tcp # 可选，Nginx代理后可关闭，仅服务器本地访问即可 sudo ufw reload # 重启防火墙生效 sudo ufw status # 查看已开放端口 3. 配置生效验证（双网段测试，确保所有功能正常）
- 192.168.10.110 设备：访问
http://192.168.10.120:8080，前端 + 接口 + 图片正常； - 10.10.11.120 设备：访问
http://10.10.12.160:8080，前端 + 接口 + 图片正常； - 浏览器 F12→Network：图片 / JS 显示
compressed（gzip 生效）、刷新显示304（缓存生效）。
八、核心操作口诀（快速记忆，避免出错）
- 配置修改先备份，验证合法再重载；
- 启动失败看日志，502 查后端，404 查路由；
- 生产环境用 reload，不用 restart 防中断；
- 图片压缩配 gzip，长期缓存设 expires；
- 双网口用 server_name _，所有 IP 全匹配；
- SPA 路由加 try_files，刷新 404 全解决。
九、FastAPI 配套 CORS 配置（必配，避免跨域）
from fastapi.middleware.cors import CORSMiddleware app = FastAPI() # 允许Nginx的双网口访问地址 origins = [ "http://192.168.10.120:8080", "http://10.10.12.160:8080", ] app.add_middleware( CORSMiddleware, allow_origins=origins, # 允许的前端地址 allow_credentials=True, # 必须开启，配合Cookie携带 allow_methods=["*"], # 允许所有请求方法（GET/POST等） allow_headers=["*"], # 允许所有请求头 ) # FastAPI必须绑定0.0.0.0，所有网口可访问 uvicorn.run(app, host="0.0.0.0", port=8002)
