零到全栈 · 卷 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;
}
}
要点三条:
- 证书用
fullchain.pem而不是cert.pem。少了中间证书,桌面浏览器可能正常、手机却报"证书不受信任"。 /.well-known/acme-challenge/必须在 301 之前,且指向一个可写目录。很多"续期总是失败"都是这里被跳转拦掉。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 拿到"可复现的证据"再进下一步。凭"看起来好了"往下走,错误会累积到最后一步才炸,那时你已经分不清是三处里哪一处的问题。