第14章 Nginx 与部署

第 14 节 / 共 17 节 课程:前后端穿透

开发时前后端各跑一个端口,用户访问 localhost。上线后只有一个域名、一个 443 端口,静态页面、接口、图片、证书都要在这一个入口里安排清楚。Nginx 就是这道门。

上线后的真实链路用户浏览器HTTPSNginx :443TLS / gzip / 缓存dist/前端静态/api/反向代理Spring Boot:8080MySQL:3306Nginx 只做两件事:把静态文件高效地发出去;把 /api 请求转给后端。证书、域名、端口、防火墙,任何一项没配对,用户看到的都是“打不开”。
图 14-1 Nginx + Spring Boot + MySQL 部署拓扑

14.1 Nginx 在链路里的位置

用户浏览器 → DNS → Nginx(443)→ 静态文件直接返回,/api 转发给 Spring Boot(5000),/static 可能转发给对象存储。后端不需要直接暴露公网。

路径去向说明
/前端 dist 目录SPA 的 index.html
/assets/前端 dist/assets带 hash 的 js/css,可长缓存
/api/127.0.0.1:5000Spring Boot
/upload/本地目录或 OSS用户上传文件
/static/本地目录或 OSS课程静态页与图片

14.2 安装与目录

# Ubuntu / Debian
sudo apt update
sudo apt install -y nginx
 
# 查看版本与配置
nginx -v
nginx -t
/etc/nginx/nginx.conf 主配置
/etc/nginx/conf.d/*.conf 站点配置(被 include)
/etc/nginx/sites-enabled/ Ubuntu 默认站点
/var/log/nginx/access.log 访问日志
/var/log/nginx/error.log 错误日志

改完配置必须 nginx -t 通过再 reload。直接 restart 会把错误配置带上线,站点立刻 502。

14.3 最小反向代理

server {
    listen 80;
    server_name www.example.com;
 
    root /data/www/www.example.com;
    index index.html;
 
    location / {
        try_files $uri $uri/ /index.html;
    }
 
    location /api/ {
        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;
    }
}

try_files $uri $uri/ /index.html; 是 SPA 的关键:用户直接访问 /course/39 时,磁盘上没有这个文件,Nginx 要返回 index.html,让前端路由接管。否则刷新就 404。

proxy_pass 结尾有没有斜杠会改变路径。location /api/ + proxy_pass http://127.0.0.1:5000; 会保留 /api 前缀;如果写成 http://127.0.0.1:5000/; 会把 /api 去掉。必须和后端映射一致。

14.4 完整站点配置

下面是一个可用的 HTTPS 站点骨架,包含 HTTP 跳转、静态缓存、接口代理、上传大小、超时和日志。

upstream codessp_api {
    server 127.0.0.1:5000;
    keepalive 32;
}
 
server {
    listen 80;
    server_name www.example.com;
    return 301 https://$host$request_uri;
}
 
server {
    listen 443 ssl http2;
    server_name www.example.com;
 
    ssl_certificate /etc/letsencrypt/live/www.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/www.example.com/privkey.pem;
 
    root /data/www/www.example.com;
    index index.html;
 
    client_max_body_size 20m;
 
    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
 
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
 
    location / {
        try_files $uri $uri/ /index.html;
    }
 
    location /api/ {
        proxy_pass http://codessp_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        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_read_timeout 60s;
    }
 
    location /upload/ {
        alias /data/upload/;
        expires 7d;
    }
 
    access_log /var/log/nginx/example.access.log;
    error_log /var/log/nginx/example.error.log;
}

14.5 HTTPS 证书

不要用自签证书上线。用 Let's Encrypt 免费证书,certbot 会自动改配置并配置续期。

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d www.example.com -d example.com
sudo certbot renew --dry-run

证书 90 天有效,续期靠定时任务。要确认 systemctl list-timers | grep certbot 有任务,否则某天会突然过期。域名解析必须指向这台机器,80 端口要能访问,否则签发失败。

14.6 systemd 托管后端

不要用 nohup java -jar 裸跑。用 systemd 管理,开机自启、崩溃重启、日志统一。

[Unit]
Description=codessp backend
After=network.target mysql.service
 
[Service]
User=root
WorkingDirectory=/root
ExecStart=/usr/bin/java -jar /root/codessp.jar
SuccessExitStatus=143
Restart=on-failure
RestartSec=5
StandardOutput=append:/root/nohup.log
StandardError=append:/root/nohup.log
 
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now codessp
sudo systemctl status codessp --no-pager
sudo journalctl -u codessp -n 100 --no-pager

只 enable 不 start,重启后服务还是不会起来;只 start 不 enable,重启后就没了。两个都要做。

Nginx 自己也要 enable。很多“重启服务器后网站打不开”的事故,就是 nginx 服务是 disabled 状态。

14.7 常见错误码

错误常见原因排查
502 Bad Gateway后端没启动/端口不对/被防火墙挡curl 127.0.0.1:5000;看 error.log
504 Gateway Timeout后端处理太久看接口耗时、数据库慢查询
413 Request Entity Too Large上传超过 client_max_body_size调大并同步后端 multipart
404路径不对、SPA 没 fallback、root 配错ls 文件;看 try_files
403权限/目录不可读/SELinux看目录权限与 nginx 用户
证书错误证书过期或域名不匹配openssl s_client 检查

14.8 上线检查清单

  1. nginx -t 通过,reload 后首页 200。
  2. 刷新任意前端路由不 404。
  3. /api/health 返回 200,后端日志无异常。
  4. HTTPS 证书有效期大于 30 天,HTTP 自动跳 HTTPS。
  5. 上传 21MB 文件返回 413,20MB 成功。
  6. 重启服务器后,Nginx 与后端都自动起来。

14.9 本章练习

  1. 用 Nginx 部署一个 Vue 构建产物,验证刷新子路由不 404。
  2. 把 /api 代理到本地 5000,故意停掉后端,观察 502 并查 error.log。
  3. 申请证书,配置 HTTP 跳 HTTPS,用 curl -I 验证。

下一章把前面所有内容串起来,做一个完整的学习平台。