【笔记】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 配置修改标准流程（生产环境防错）

所有配置修改必须按此流程，避免服务故障！

1. 编辑配置文件（用 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（缓存生效）。

八、核心操作口诀（快速记忆，避免出错）

1. 配置修改先备份，验证合法再重载；
2. 启动失败看日志，502 查后端，404 查路由；
3. 生产环境用 reload，不用 restart 防中断；
4. 图片压缩配 gzip，长期缓存设 expires；
5. 双网口用 server_name _，所有 IP 全匹配；
6. 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)