跳到正文
零到全栈 · 卷 9 · 卷 9

附录D Nginx配置模板

本合集目录
本章目录

定位:不用通读。上线时按"静态站 / 反向代理 / HTTPS"三种形态各抄一份,改域名与路径即可用。 适用:Ubuntu LTS 上的 Nginx,站点配置放 /etc/nginx/sites-available/,软链到 sites-enabled/。

你要做的事 抄哪一份 卷
只托管前端构建产物(dist/、out/) 模板一 卷 3、卷 4
前端静态 + /api 交给后端进程 模板二 卷 5、卷 7
加上证书、强制跳转 HTTPS 模板三 卷 7
只想抄一段:压缩 / 缓存 / 日志 / 上传大小 第四节「常用片段」 卷 7、卷 8

一、模板一:纯静态站

最常用的一份。前端 next build 静态导出或 vite build 出来的产物,交给 Nginx 直接发。

server {
    listen 80;
    listen [::]:80;
    server_name dudao.example.com;          # 换成你的域名;没有域名就写服务器 IP

    root /srv/dudao/web;                     # 产物目录(里面应该有 index.html)
    index index.html;

    # 关键:找不到文件时回退到 index.html,否则前端路由一刷新就 404
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 带内容哈希的静态资源可以长期缓存(文件名变了 URL 就变)
    location ~* \.(?:js|css|woff2?|png|jpg|jpeg|svg|webp|ico)$ {
        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable";
        access_log off;
    }

    # 隐藏文件一律拒绝(.git、.env 这类不该被下载)
    location ~ /\. {
        deny all;
    }

    access_log /var/log/nginx/dudao.access.log;
    error_log  /var/log/nginx/dudao.error.log warn;
}

三条必须理解的:

指令 为什么这样写
try_files $uri $uri/ /index.html 先当文件找,再当目录找,都没有就交给前端路由。少了这句,/notes/12 刷新必 404
expires + immutable 文件名带哈希时这样做是安全的;index.html 不能这样缓存,否则用户永远拿到旧版本
location ~ /\. .env、.git 泄漏是真实事故,一条正则堵掉

二、模板二:前端静态 + 后端反代

「读到」上线后的真实形态:页面由 Nginx 发,/api 转给 127.0.0.1:8000 上的 FastAPI。

upstream dudao_api {
    server 127.0.0.1:8000;
    keepalive 16;                            # 复用到后端的连接,省掉反复握手
}

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

    root /srv/dudao/web;
    index index.html;

    client_max_body_size 2m;                 # 不设的话默认 1m,稍微大点的请求就 413

    location /api/ {
        proxy_pass http://dudao_api;         # 注意:结尾没有斜杠,/api/notes 原样转过去
        proxy_http_version 1.1;
        proxy_set_header Connection "";      # 配合 keepalive 使用

        # 这四个头不传,后端就不知道真实来源:日志全是 127.0.0.1、Cookie 域错、跳转成 http
        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;

        proxy_connect_timeout 5s;
        proxy_send_timeout    30s;
        proxy_read_timeout    30s;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(?:js|css|woff2?|png|jpg|jpeg|svg|webp|ico)$ {
        expires 30d;
        add_header Cache-Control "public, max-age=2592000, immutable";
        access_log off;
    }
}

proxy_pass 结尾斜杠是最高频的坑,两种写法的差别:

写法 客户端请求 后端收到 什么时候用
proxy_pass http://dudao_api;(无斜杠) /api/notes /api/notes 后端路由本身带 /api 前缀
proxy_pass http://dudao_api/;(有斜杠) /api/notes /notes 后端路由不带前缀,靠 Nginx 剥掉

写错不会报错,只会 404,所以改完一定用 curl -i 看实际打到哪。


三、模板三:HTTPS

证书由 certbot 申请后会自动改写这个文件,所以第一次只要把 80 的配置写对,剩下交给 certbot --nginx。下面是人手写时的目标形态:

server {
    listen 80;
    listen [::]:80;
    server_name dudao.example.com;

    # 续期验证走这个路径,不能被 301 吃掉,否则三个月后证书过期
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;                                # Nginx 1.25.1+ 的写法;更早版本用 listen 443 ssl http2;

    server_name dudao.example.com;

    ssl_certificate     /etc/letsencrypt/live/dudao.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dudao.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;

    # 先别急着开 HSTS:一旦开了,浏览器在 max-age 内拒绝 http 访问,配错就只能等
    # add_header Strict-Transport-Security "max-age=31536000" always;

    root /srv/dudao/web;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        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;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

要点三条:

  1. 证书用 fullchain.pem 而不是 cert.pem。少了中间证书,桌面浏览器可能正常、手机却报"证书不受信任"。
  2. /.well-known/acme-challenge/ 必须在 301 之前,且指向一个可写目录。很多"续期总是失败"都是这里被跳转拦掉。
  3. X-Forwarded-Proto 决定后端生成的链接是 https 还是 http。不传,登录跳转会掉回 http,然后被 301 回来,形成循环。

四、常用片段(抄进 location 或 server 里)

# 压缩:文本类才值得压,图片视频压了反而浪费 CPU
gzip on;
gzip_comp_level 5;
gzip_min_length 1024;
gzip_types text/plain text/css application/javascript application/json image/svg+xml;

# 上传大小(放 server 级;放 location 级就只对该路径生效)
client_max_body_size 2m;

# 自定义日志:八个字段,排查时一次看全
log_format main8 '$remote_addr - [$time_local] "$request" $status $body_bytes_sent '
                 '$request_time $upstream_response_time "$http_user_agent"';
access_log /var/log/nginx/dudao.access.log main8;

# 全站安全头(always 保证错误响应也带上)
add_header X-Content-Type-Options nosniff always;
add_header Referrer-Policy strict-origin-when-cross-origin always;

# 只允许内网访问某个后台路径
location /admin/ {
    allow 10.0.0.0/8;
    deny all;
}
片段 常见误配 后果
gzip_types 忘了加 application/json 接口响应体不压缩,移动网络下明显变慢
client_max_body_size 只在 location /api/upload 里设了 1m 其他接口仍是默认 1m,用户传稍大文件就 413
add_header 没加 always 4xx/5xx 响应没有安全头(很多扫描器就盯这个)
日志格式 只看 $remote_addr 经过代理后全是 127.0.0.1,真实 IP 在 X-Forwarded-For 里

五、改完必做的四步

sudo nginx -t                  # 1. 语法检查,必须先过
sudo systemctl reload nginx    # 2. 平滑重载(reload 不断连接;restart 会断)
curl -I http://你的域名/        # 3. 看状态码与 Server 头
sudo tail -f /var/log/nginx/error.log   # 4. 不对就盯这里,error.log 比 access.log 有用
nginx -t 报错 含义 修法
unknown directive "xxx" 指令拼错,或当前版本不支持该指令 查该版本支持的写法(如 http2 on 与 listen ... http2 的分界)
duplicate location "/api/" 同一个 server 里写了两个相同 location 合并成一个
invalid number of arguments 指令参数个数不对(少了分号也会这样报) 看上一行末尾有没有 ;
cannot load certificate 证书路径错或没读权限 确认 fullchain.pem 路径与 sudo 权限

reload 失败不会中断服务,旧配置继续跑——所以"改完没生效"先看 nginx -t 是否真的过了,再看是不是 reload 了另一个 config。


六、从零到上线的顺序(别乱序)

同一个目标,顺序错了会多花一倍时间,因为每一步的验证手段都依赖前一步。下面是「读到」实际走通的顺序:

步 做什么 完成标志(可自证)
1 安全组/防火墙只开 22,用密钥登进去 ssh -i key dudao@IP 能进,密码登录被拒
2 装 Nginx,访问 http://IP 看到默认欢迎页 curl -I http://IP 返回 200
3 换 root 到自己的产物目录 curl -I http://IP 返回 200 且内容是自己的页面
4 后端 uvicorn 起在 127.0.0.1:8000,curl 本机通 curl -s localhost:8000/healthz 有响应
5 加 location /api/ 反代,nginx -t 过 curl -I http://IP/api/healthz 返回 200
6 解析域名,等 TTL 过半 dig +short 你的域名 返回服务器 IP
7 申请证书,改 443,跑 renew --dry-run 浏览器地址栏是锁,且 curl -I https://域名 200

三个乱序的典型代价:

乱序 后果
先上证书、再做反代 改完 443 又要改一次 server 块,证书重载两遍;且 HTTP-01 验证可能因为 80 被跳转吃掉而失败
先解析域名、再通服务 TTL 已生效但服务没好,你会误判成"域名解析错了",跑去翻 DNS 记录
先反代、再确认后端监听地址 后端监听 0.0.0.0 直接对公网暴露,绕过了 Nginx(也绕过了你配的安全头与限流)

一条判断原则:每一步都用 curl -I 或 dig 拿到"可复现的证据"再进下一步。凭"看起来好了"往下走,错误会累积到最后一步才炸,那时你已经分不清是三处里哪一处的问题。