目录一、nginx 是什么反向代理 vs 正向代理容易混二、Ubuntu 下 nginx 的安装与目录结构三、软连接机制 —— nginx 站点启用的核心原理图为什么要分两个目录标准命令四、配置文件结构server / location / server_name4.1 server_name —— 多站点靠域名分流的关键4.2 location —— 路径匹配规则4.3 proxy_pass —— 反向代理 结尾斜杠的坑4.4 透传请求头4.5 try_files —— SPA history 模式必备五、HTTPS 配置5.1 证书从哪来5.2 证书文件5.3 HTTPS server 块写法5.4 HTTP → HTTPS 301 跳转六、常用调试与维护命令排错思路一、nginx 是什么nginx 是一个Web 服务器 / 反向代理服务器。它在生产部署里通常干两件事静态托管把前端打包出来的dist/文件直接返回给浏览器。反向代理把/api这类请求转发给后端应用进程比如 uvicorn、gunicorn、Node 服务。它本身不跑你的业务代码只负责接客、分发、转交。反向代理 vs 正向代理容易混类型代理谁谁知道它存在典型场景正向代理代理客户端服务端不知道真实客户端翻墙、爬虫 IP 池反向代理代理服务端客户端不知道真实后端nginx 转发到 uvicorn二、Ubuntu 下 nginx 的安装与目录结构Ubuntu / Debian 用 apt 安装sudoaptupdatesudoaptinstall-ynginx装完之后这些路径是固定的路径作用一般要不要动/usr/sbin/nginx主程序二进制不动/etc/nginx/nginx.conf主配置文件全局一般不动里面 include 下面两个目录/etc/nginx/sites-available/可用站点目录实体配置文件存这在这里新建/编辑站点配置/etc/nginx/sites-enabled/已启用站点目录只放软连接用软连接控制启用谁/etc/nginx/conf.d/另一种站点配置目录部分发行版用这个看主配置 include 的是哪个/var/log/nginx/日志access.log、error.log看日志用/run/nginx.pid主进程 PID不用管Ubuntu 默认nginx.conf里有一句include /etc/nginx/sites-enabled/*;所以 nginx 启动时只会读sites-enabled/下的文件不读sites-available/。三、软连接机制 —— nginx 站点启用的核心sites-available/和sites-enabled/之间靠符号链接symlink软连接关联这是 nginx 站点管理的标准玩法。原理图你写的真实配置文件 /etc/nginx/sites-available/my-site ← 实体文件内容在这 │ │ ln -s 建立软连接 ▼ /etc/nginx/sites-enabled/my-site ────────► 指向左侧实体文件 │ │ nginx.conf: include /etc/nginx/sites-enabled/*; │ 所以 nginx 只看 sites-enabled 下的文件 ▼ nginx 加载这份配置 → 生效为什么要分两个目录sites-available/是仓库所有写过的站点配置都存这里删了就没了。sites-enabled/是开关里面只放指向 available 的软连接。有软连接 启用删软连接 停用实体文件还在 available没丢。好处不用删配置文件只删软连接 / 建软连接就能开关站点特别适合临时下线维护、多项目并存场景。标准命令# 启用一个站点建软连接sudoln-s/etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/my-site# 停用一个站点只删软连接实体文件保留sudorm/etc/nginx/sites-enabled/my-site# 改完任何配置后先测语法再重载不中断服务sudonginx-tsudosystemctl reload nginx四、配置文件结构server / location / server_name一份站点配置长这样骨架server{listen80;# 监听端口server_name example.com;# 匹配哪个域名root /var/www/dist;# 静态文件根目录index index.html;location /api/{# 路径匹配块proxy_pass http://127.0.0.1:8000;# 反代到后端}location /{try_files$uri$uri/ /index.html;# SPA 路由 fallback}}4.1 server_name —— 多站点靠域名分流的关键nginx 一个进程能管多个server块靠server_name域名决定这个请求给谁。这是虚拟主机的核心浏览器请求 http://app.example.com/ │ ▼ nginx(80端口)收到请求 │ │ 看请求头里的 Host 字段app.example.com │ 在所有 server 块里找 server_name 匹配的 ▼ 命中 server_name app.example.com 的那个块 → 走它的配置所以同一台服务器、同一个 80 端口可以同时承载a.example.com、b.example.com、c.example.com三个完全独立的站点互不干扰。server_name _下划线是个特殊用法_不会匹配任何真实域名作为兜底默认 server。当请求的域名没匹配上任何 server 块时nginx 把请求扔给它。单站点时代常用多站点时不推荐依赖它。4.2 location —— 路径匹配规则location决定URL 路径走哪条路。匹配优先级从高到低类型写法说明精确匹配location /xxx完全相等才命中优先级最高前缀长location ^~ /assets/前缀匹配命中后不再查正则正则location ~* \.png$正则匹配~*不区分大小写~区分前缀普通location /api/普通前缀匹配优先级最低典型组合/api/反代后端、/assets/静态缓存、/兜底返回 index.html。4.3 proxy_pass —— 反向代理 结尾斜杠的坑location /api/{proxy_pass http://127.0.0.1:8000;# 结尾不带斜杠}结尾带不带斜杠行为完全不同这是 nginx 最经典的坑proxy_pass 写法转发给后端的路径后端路由该写成http://127.0.0.1:8000;不带斜杠原样保留/api/xxx/api/xxxhttp://127.0.0.1:8000/;带斜杠剥掉/api/前缀变成/xxx/xxx记忆口诀proxy_pass 带 URI带斜杠 替换不带 URI 原样转发。前后端路由前缀必须对齐这个行为否则一定 404。4.4 透传请求头反代时后端默认拿不到客户端真实 IP要手动透传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;Host原始域名。X-Real-IP客户端真实 IP否则后端看到的是 nginx 的 127.0.0.1。X-Forwarded-ForIP 链路。X-Forwarded-Proto原始协议 http/https后端要知道是不是 HTTPS 才能生成正确的回调 URL。4.5 try_files —— SPA history 模式必备Vue/React 用 history 路由模式时前端 URL 是http://域名/result/123但服务器上根本不存在/result/123这个文件直接刷新会 404。location / { try_files $uri $uri/ /index.html; }含义先按完整路径找文件$uri再当目录找$uri/都找不到就返回 index.html。这样所有非静态文件请求都回退到前端入口由前端路由器在浏览器里解析。这是 SPA 的标准写法。五、HTTPS 配置5.1 证书从哪来三种主流来源来源工具特点Let’s Encryptcertbot免费、自动续期、命令行管理路径在/etc/letsencrypt/live/域名/腾讯云/阿里云免费证书控制台申请下载免费、有效期 1 年、到期需手动续、下载 zip 上传到服务器商业付费证书各 CA 厂商付费、有 OV/EV 验证腾讯云免费证书的关键限制一张证书只覆盖申请时填的域名可带 www。子域名不通用每个子域名要单独申请一张证书。如果要用一张证书覆盖所有子域名需要通配符证书*.example.com腾讯云免费证书不支持需付费购买。5.2 证书文件Nginx 用的证书通常是两个文件文件内容fullchain.pem或xxx_bundle.crt证书链域名证书 中间证书nginx 用ssl_certificate指向它privkey.pem或xxx.key私钥nginx 用ssl_certificate_key指向它腾讯云下载的 Nginx 格式 zip 里对应的就是xxx_bundle.crt和xxx.key。5.3 HTTPS server 块写法server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; root /var/www/dist; 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; } }5.4 HTTP → HTTPS 301 跳转用户习惯输入http://要自动跳到https://。单独写一个 80 端口的 server 块干这事server { listen 80; server_name example.com; return 301 https://$host$request_uri; # 永久重定向到 HTTPS }这样访问http://example.com/xxx会自动跳https://example.com/xxx。六、常用调试与维护命令# 测试配置语法改完必跑不报错才 reloadsudonginx-t# 重载配置不中断服务平滑生效sudosystemctl reload nginx# 重启 nginx万不得已用会瞬断sudosystemctl restart nginx# 查看状态sudosystemctl status nginx# 看错误日志排查 404/502/配置问题第一手资料sudotail-50/var/log/nginx/error.log# 看访问日志sudotail-50/var/log/nginx/access.log# 实时跟踪日志CtrlC 退出sudotail-f/var/log/nginx/error.log排错思路现象排查方向nginx -t报错配置语法问题按错误行号定位浏览器 502 Bad Gateway后端进程没起 / 端口错 / 后端崩了查journalctl -u 后端服务名浏览器 404root路径错 / dist 没 build /try_files没配接口 404proxy_pass结尾斜杠配错 / 后端路由前缀不匹配HTTPS 证书报红证书域名不匹配覆盖范围/ 证书过期 / 证书链不全静态资源 403nginx workerwww-data对 dist 目录无读权限或父目录无ox