开发时前后端各跑一个端口,用户访问 localhost。上线后只有一个域名、一个 443 端口,静态页面、接口、图片、证书都要在这一个入口里安排清楚。Nginx 就是这道门。
图 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:5000 | Spring 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 上线检查清单
nginx -t 通过,reload 后首页 200。
- 刷新任意前端路由不 404。
/api/health 返回 200,后端日志无异常。
- HTTPS 证书有效期大于 30 天,HTTP 自动跳 HTTPS。
- 上传 21MB 文件返回 413,20MB 成功。
- 重启服务器后,Nginx 与后端都自动起来。
14.9 本章练习
- 用 Nginx 部署一个 Vue 构建产物,验证刷新子路由不 404。
- 把
/api 代理到本地 5000,故意停掉后端,观察 502 并查 error.log。
- 申请证书,配置 HTTP 跳 HTTPS,用
curl -I 验证。
下一章把前面所有内容串起来,做一个完整的学习平台。