跳转至

Nginx 核心操作速查

用途：供 AI 助手快速查阅并配置/排查 Nginx。场景：反向代理 K8s/Docker 服务、静态站点、HTTPS。 版本基线：Nginx 1.30.6 stable / 1.31.8 mainline（核对日期 2026-11-11，来源：官网 nginx.org） 更新日期：2026-11-11

1. 安装与服务管理

sudo apt install nginx           # Ubuntu 官方源版本偏旧但够用
sudo systemctl start/stop/reload/restart nginx
sudo nginx -t                # 语法检查（改配置后必做，reload 前必做）
sudo nginx -T                # 输出完整生效配置（排查 include 合并结果）

需要最新稳定版（如 1.30.6）时，添加 nginx.org 官方仓库：按 nginx.org/en/linux_packages.html 配置后 apt install nginx（nginx.org 源默认装 mainline，stable 需指定 nginx-stable 包）。

2. 目录结构（Ubuntu）

路径 作用
/etc/nginx/nginx.conf 主配置
/etc/nginx/sites-available/ 站点配置（编辑这里）
/etc/nginx/sites-enabled/ 生效站点（软链接过来）
/etc/nginx/conf.d/*.conf 附加配置
/var/log/nginx/access.log / error.log 日志
/var/www/html/ 默认静态根目录 
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/   # 启用站点
sudo rm /etc/nginx/sites-enabled/default    # 去掉默认页
sudo systemctl reload nginx

3. 常用配置模板

3.1 反向代理（最常用，代理后端 API/TTS 服务）

server {
    listen 80;
    server_name tts.example.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # WebSocket / 流式响应（TTS 音频流常用）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
        client_max_body_size 50m;      # 上传大文件调大
    }
}

3.2 负载均衡

upstream backend {
    least_conn;                         # 或 ip_hash（会话保持）
    server 192.168.100.11:5000 max_fails=3 fail_timeout=30s;
    server 192.168.100.12:5000 backup;
}
server {
    location / { proxy_pass http://backend; }
}

3.3 HTTPS（Let's Encrypt 一键签发）

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d tts.example.com      # 自动改配置+续期任务

server {
    listen 443 ssl;
    server_name tts.example.com;
    ssl_certificate     /etc/letsencrypt/live/tts.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tts.example.com/privkey.pem;
    # 80 端口自动跳转由 certbot 生成
}

3.4 静态站点 + 缓存与压缩

server {
    listen 80;
    root /var/www/myapp;
    index index.html;
    gzip on;
    gzip_types text/css application/javascript application/json;
    location ~* \.(jpg|png|css|js)$ { expires 7d; }
    location / { try_files $uri $uri/ /index.html; }   # SPA 前端路由兜底
}

4. 排障速查

sudo nginx -t                            # 配置错误第一现场
tail -f /var/log/nginx/error.log         # 错误日志
tail -f /var/log/nginx/access.log        # 访问日志
ss -tlnp | grep :80                      # 端口被谁占（常被 apache/别的进程占）
curl -I http://127.0.0.1                 # 本机验证响应头

常见问题对照：

现象 常见原因
502 Bad Gateway 后端没起/端口错；proxy_pass 指错
504 Gateway Timeout 后端慢，调大 proxy_read_timeout
413 Request Too Large client_max_body_size 太小
配置不生效 没建 sites-enabled 软链；忘了 reload；改前没 -t 通过
WebSocket 连不上 缺 Upgrade/Connection 头

5. AI 助手操作守则

  • 改配置流程固定为：改 sites-available → nginx -t → 通过后 systemctl reload nginx（reload 不断连接，优于 restart）。
  • 每个站点一个独立文件，不把 server 块堆进 nginx.conf。
  • 改前备份：sudo cp /etc/nginx/sites-available/x{,.bak.$(date +%F)}。
  • 代理 K8s NodePort/Ingress 时确认宿主机到集群网络的连通性再下结论。