场景
这台服务器上已经住着两个项目。根路径挂着我的博客,/vue-pv/ 挂着另一个项目。
现在我要把自己的报告平台也塞进去,路径定在 /report/,条件只有一条:那两个照常运行,一个字节都不能动。
我以为最费劲的是 Docker。真正卡住我的,是三个斜杠和两个 base。
先弄清楚请求怎么走
一个 nginx 里可以有很多 location,请求进来时,nginx 按前缀最长匹配决定交给谁:
location / → 静态博客
location /vue-pv/ → 另一个项目
location /report/ → 我的平台(静态文件)
location /report-api/ → 转发到 127.0.0.1:3000(后端容器)
图 1:一个 80 端口,四条分支,我的平台只占其中两条
搞懂这个,后面三个坑才有地方放:每个坑,都是这套分流规则里某一环没接上。
坑 1:yum install docker,装出来的不是 Docker
现象:yum install docker 一路跑完,systemctl start docker 却报 unit 不存在。
我的第一反应是装失败了,重装一遍。没用。这次我没急着再动手,先把 docker -v 的输出看了一遍:
podman version 4.9.4
输出的名字根本不是 docker,是 podman。阿里云 Linux 3 跟 RHEL 8 同源,docker 这个包名被 podman 的兼容壳占用了——你装到的只是一个把命令转发给 podman 的壳。
解决分三步:卸掉假壳、配 docker-ce 的源、把源里的 $releasever 改成 8。
第三步一开始我没弄明白:为什么要去改一个变量?
因为 yum 源地址里的 $releasever,会被替换成系统自己的版本号:
baseurl=https://download.docker.com/linux/centos/$releasever/$basearch/stable
CentOS 8 上它替换成 8,阿里云 Linux 3 上替换成 3。而 docker 的源目录只有 7、8、9,没有 3——拼出来是个不存在的地址,报错是 Failed to download metadata for repo 'docker-ce-stable'。
改成 8 能装,是因为 alinux3 和 RHEL 8 是同一套二进制接口(glibc 2.28、rpm 包规范一致),el8 的包在这个系统上跑得起来。
后来我才知道有更正规的解法:阿里云自家有个 dnf-plugin-releasever-adapter 插件,专门把 3 映射成 8。我手改的那条 sed 是一次性的,以后再配别的第三方源还得再改一遍——插件才是能留下去的写法。
这一坑教我的事:命令有输出,跟装对了,是两回事。要看输出里说的是什么。
坑 2:base 和 basename,少一个就白屏
现象:http://ip/report/ 打开,整页空白。
子路径部署要成对改两个地方,它们管的是两件事:
// vite.config.ts:决定打包出来的 index.html 里,assets 路径带不带 /report/ 前缀
base: '/report/'
// 路由:决定 react-router 认不认 /report/ 这个前缀
<BrowserRouter basename="/report">
少改任何一个,现象不一样:
- 只改
base不改basename:首页能开,一刷新或访问/report/tasks/xxx就白屏——路由不认这个前缀 - 只改
basename不改base:首页都开不了——index.html里引用的还是/assets/...,服务器上没有这个目录,全部 404
这两个改没改对,不用打开浏览器猜。npm run build 之后直接看 dist/index.html:
<script type="module" crossorigin src="/report/assets/index-DuAYgdu8.js"></script>
<link rel="stylesheet" crossorigin href="/report/assets/index-B3jvTpKz.css">
图 2:src 里带不带 /report/,一眼就看出来
src 里带 /report/,说明 base 生效了。没带,就是 base 没改或改了没重新打包。
还有一处要提前想好:API 地址写进 .env.production 而不是 .env。VITE_API_BASE=/report-api 只在打包生产包时生效,本地 dev 照旧直连 5173,一套配置两套环境互不打扰。
坑 3:proxy_pass 末尾那个斜杠
现象:页面能开了,接口全 404。
这是三个坑里最不起眼的一个,也是最贵的:
# 带斜杠:把 /report-api/api/report-tasks 转发成 /api/report-tasks ✅
proxy_pass http://127.0.0.1:3000/;
# 不带斜杠:原样带着 /report-api 前缀转发 ❌ 后端没有这个路由
proxy_pass http://127.0.0.1:3000;
nginx 的规则:proxy_pass 带路径(哪怕只有一个 /),就用它替换掉 location 匹配到的前缀;不带,就原样把完整路径递过去。
我的后端挂在 /api/report-tasks,/report-api/api/report-tasks 它当然不认识。
这条规则不用背,把两次的日志摆在一起就看清了。以下是我在服务器上真跑的结果。
带斜杠:
浏览器发出 /report-api/api/report-tasks?page=1
后端收到 /api/report-tasks?page=1 ← /report-api 被替换掉了
图 3:带斜杠,后端收到的是 /api/report-tasks,200
把那个斜杠删掉、nginx -t && nginx -s reload 之后再请求一次:
浏览器发出 /report-api/api/report-tasks?page=1
后端收到 /report-api/api/report-tasks?page=1 ← 原样透传,前缀还在
{"success":false,"error":{"code":"NOT_FOUND",
"message":"接口不存在: GET /report-api/api/report-tasks?page=1"}}
图 4:同一个请求,斜杠没了,前缀就在,直接 404
同一个请求、同一份 nginx 配置,只差一个字符,后端收到的路径就完全变了。这就是那个斜杠的全部含义——它是"替换"和"透传"两个行为的开关。
(这是我特意制造的故障,验完立刻备份回滚,步骤就四条:cp 备份、nginx -t、nginx -s reload、再 curl 一次确认恢复。线上改配置前先备份,这一步别省。)
图 5:改完记得验一遍斜杠回来了没有
这是我服务器上和报告平台相关的四段配置:
# 报告平台前端:静态文件 + SPA 兜底
location /report/ {
root /home/web; # /report/xxx → /home/web/report/xxx
index index.html;
try_files $uri /report/index.html; # 深链/刷新兜底,注意兜底路径要带 /report
}
# 报告平台静态资源(Vite 产物带 hash,内容永不变,可长缓存)
location /report/assets/ {
root /home/web;
expires 30d;
add_header Cache-Control "public, max-age=2592000, immutable" always;
}
# 后端反代
location /report-api/ {
proxy_pass http://127.0.0.1:3000/; # 末尾斜杠 = 去掉 /report-api 前缀
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
顺带一提:服务器上另一个项目用的是 alias 而我用的是 root——root 是把 location 路径拼接在目录后面,alias 是替换掉 location 前缀。用错一个字,路径就多一层或少一层。
这一坑教我的事:nginx 里最贵的字符是斜杠,一个字符的差价是一整个 404。
两个不出声的坑
还有两处,不报错,但迟早咬人,一并记下。
depends_on 只保证"先启动谁",不保证"启动好了"。api 一启动就连数据库,库还在初始化,api 连不上就崩,崩了重启,循环。要写成:
depends_on:
mysql:
condition: service_healthy # 等 mysql 健康检查通过才算就绪
端口暴露。最初的 compose 把 3000 和 3306 都映射到了公网,等于把数据库挂在互联网上。api 只绑 127.0.0.1(nginx 反代在本机,够用了),mysql 的 ports 整个删掉——容器之间走服务名通信,根本不需要宿主机端口。
收尾
现在 /report/ 能访问了,接口通,healthz 返回 dbDriver: "mysql"、env: "production",两个 healthy 挂在 docker compose ps 里。
图 6:列表里的数据都是从 MySQL 查出来的
图 7:3306/tcp 后面没有箭头,说明数据库没有暴露到宿主机
这次最大的收获跟 nginx 关系不大。以前抄配置,抄的是咒语,念了灵就灵;这一次每一行我都能说出它作用在哪一层——哪个改的是打包产物,哪个改的是路由,哪个改的是服务器分流。
这句底气,是三个斜杠换来的。