到了第7篇整个HOJ部署链条里就剩前端这一块没落地了。前几篇我们在CentOS上装了宝塔、配好了数据库和中间件、把后端服务容器化跑起来了但如果前端不发布整个在线判题系统依然只是“后端API活着”的状态浏览器里什么都没有。这一篇我会把前端如何构建、如何打成Docker镜像、如何通过宝塔发布容器以及上线后最常见的白屏、登录失效、路由404这几个坑一次讲明白。先说结论HOJ前端虽然可以直接把构建产物丢到宝塔Nginx里用但在整个项目选择容器化部署的前提下我更建议把前端也打成镜像。原因倒不是“容器化听起来高级”而是后续升级、回滚、迁移都要方便得多——一个镜像就是一整套运行环境不需要在新服务器上重新装Node、装依赖、改Nginx配置。不过前端镜像的坑也恰恰藏在“把静态文件塞进Nginx”这个看似简单的动作里比如SPA路由回退、API反向代理、WebSocket升级少配一行都可能导致上线后页面打不开。1. 前端镜像在整个HOJ部署里解决什么问题1.1 HOJ前后端分离后的目录关系很多第一次部署HOJ的同学会把整个项目当成一个单体应用来理解。实际上HOJ的前端和后端是彻底分离的后端由若干个Spring Cloud微服务组成负责处理业务逻辑、判题调度、数据存储前端则是独立的Vue项目负责页面渲染和用户交互。前端构建完之后就是一批纯静态文件HTML、JS、CSS、图片它本身不跑业务代码所有数据都要通过HTTP请求打到后端网关。这就带来一个很关键的问题静态文件放在哪里、谁来提供HTTP服务。常见的做法有两种一种是直接用宝塔面板自带的Nginx来托管dist目录另一种就是我们现在要做的把dist目录连同Nginx一起打进Docker镜像。两种方案在功能上没有本质区别但容器化之后前端服务的“运行环境”变成了镜像的一部分换一台机器部署时只需要拉镜像、起容器不再需要关心目标机器上有没有Nginx、Nginx配置是否合理。1.2 为什么不用宝塔自带的Nginx直出dist这不是说宝塔Nginx不好而是从维护角度考虑非容器化的方案会引入“配置漂移”的问题。比如你在一台服务器上手动改了Nginx配置把/api/反向代理到某个地址三个月后另一台服务器重新部署时很容易漏掉这个配置项。而把Nginx配置写进镜像等于把部署文档里的“软性要求”变成了“硬性约束”任何人拿到同一个镜像启动出来的前端服务行为都是一致的。当然容器化之后的容器端口要映射到宿主机如果你宝塔面板自身的Nginx占用了80端口就会冲突。这个我后面会专门讲实际操作时一般把前端容器映射到8010、8080这类高位端口再用宝塔的“反向代理”把域名流量转发过去或者干脆停掉宝塔Nginx让前端容器直接监听80。2. 打包前端前的三处预检查Node版本、仓库子项目、配置地址2.1 选Node 18还是Node 20更稳妥HOJ前端源码对Node版本的兼容性不算苛刻但我建议优先使用Node 18 LTS或Node 20 LTS。为什么强调版本因为前端依赖里有些锁文件是由特定npm/pnpm版本生成的Node版本差异过大时安装依赖可能因为原生模块编译失败而中断。我的原则是“能在自己电脑上构建成功就在容器里用同一套Node版本”。比如本地用node -v查出来是v18.20.4那镜像构建阶段就用node:18-alpine作为基础镜像。这样能最大程度复现本地构建环境少踩“本地能出包、容器里报错”的坑。2.2 源码里有哪些前端工程需要分别打包HOJ整个前端源码由一个多包仓库管理里面通常包含面向用户的前台站点frontend和面向管理员的后台站点admin。这两个站点是两套独立工程构建命令可能不同。我第一次部署时只构建了前台结果后端管理页面怎么都打不开后来才发现管理员界面需要单独构建。建议拉到源码后先看根目录的package.json和README找到类似build:front、build:admin这种脚本名。如果你拉取的版本没有拆分也可以通过观察目录结构判断一般frontend目录对应普通用户端admin目录对应管理端。两个都构建出来再分别做成两个镜像或者合并到一个镜像里HOJ官方倾向于拆成两个容器这样管理端和用户端可以独立升级。2.3 后端地址与WebSocket地址不要写localhost部署前端时最容易犯的错误就是在环境配置文件里把后端地址写成http://localhost:8080。这个配置在你自己电脑上构建、本地联调时是没问题的因为浏览器访问的也是localhost。但一旦部署到服务器页面是用户在浏览器打开的这时候前端代码里的localhost指向的是用户自己的电脑而不是你的后端服务器结果必然是接口全部超时。正确的做法是区分“客户端可访问的地址”和“服务端内部通信地址”。比如你的服务器公网IP是1.2.3.4后端网关端口映射为8080那前端环境配置文件里就应该写http://1.2.3.4:8080并确保后端网关已处理好跨域。如果配了域名就直接写https://api.your-domain.com。许多用户反馈“后端都部署好了前端登录没反应”八成就是这里写成了localhost。HOJ还会用WebSocket推送消息和判题结果所以WebSocket的地址也要一并修改通常是ws://或wss://协议不能漏掉。漏配WebSocket的话前端页面能打开但判题状态不会实时刷新表现得很像系统卡死。3. 前端镜像的Dockerfile长什么样每一步在干什么3.1 构建阶段为什么必须把install和build分成两步前端镜像的核心是“多阶段构建”即先在带Node环境的镜像里把项目构建成静态文件再把静态文件拷入轻量的Nginx镜像。这一步可以显著缩小最终镜像体积——Node镜像动辄几百MB甚至1GB而Nginx的alpine镜像只有几十MB。我先给一份我在HOJ部署中实际用到的Dockerfile作为参考具体项目结构不同命令会有差异# 第一阶段构建 FROM node:18-alpine AS build-stage WORKDIR /app # 先复制依赖清单利用Docker缓存加快构建 COPY package.json package-lock.json ./ RUN npm install # 再复制全部源码 COPY . . RUN npm run build:front # 第二阶段运行 FROM nginx:alpine AS production-stage # 把构建产物复制到Nginx的静态文件目录 COPY --frombuild-stage /app/dist /usr/share/nginx/html # 覆盖自定义Nginx配置 COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]拆成两个阶段的好处不只是体积小。你可能发现我把COPY package.json和COPY . .分开了这是因为Docker构建有缓存机制只要package.json和锁文件没变npm install这一步会命中缓存不用每次重新装依赖。改一行源码重新构建镜像时只有后续的COPY . .和npm run build会重新执行构建速度快非常多。3.2 运行阶段为什么拷贝dist而不是拷贝源码运行阶段我选用的是nginx:alpine而不是继续用Node。因为前端构建完成后的产物是静态文件不需要Node进程去跑Nginx这样高性能的HTTP服务器来处理静态资源更合适。有人会问如果项目里有服务端渲染需求怎么办HOJ这类Vue SPA单页应用不涉及所以肆无忌惮地走纯静态托管即可。这里有一个需要注意的点COPY --frombuild-stage /app/dist /usr/share/nginx/html这行命令要求构建结果一定在/app/dist如果你的HOJ前端构建输出目录不同比如是build就需要同步修改。可以在本地执行一次构建观察生成的目录名再写Dockerfile。3.3 Nginx配置SPA回退、API反代、WebSocket升级静态文件拷进去只是第一步真正决定前端能不能正常工作的是Nginx配置。HOJ前端走的是Vue Router的history模式这种模式下浏览器访问/login、/problem/123这类具体的路由时Nginx如果没找到对应的物理文件就会直接返回404。所以必须有SPA回退规则server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; # 前端路由回退统一交给index.html location / { try_files $uri $uri/ /index.html; } # 反向代理后端API location /api/ { proxy_pass http://backend-gateway:8080; 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; } # WebSocket代理 location /ws/ { proxy_pass http://backend-gateway:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }这里backend-gateway是后端服务在Docker网络里的主机名如果你的后端容器名不是这个改成实际的容器名或IP。X-Forwarded-Proto $scheme这行尤其重要它告诉后端“用户实际是通过http还是https访问的”。如果漏掉这一行即使用了HTTPS域名后端生成的Cookie可能仍是http类型导致登录后Session无效。4. 在宝塔上发布镜像容器并解决跨容器通信4.1 打包与推送镜像的常用命令Dockerfile就绪后在源码目录执行docker build -t hoj-frontend:latest .如果服务器上没有镜像仓库可以先把镜像导成tar包再拷贝到目标服务器或者直接在目标服务器上构建。实际操作中我一般在家目录建一个hoj-build文件夹把源码放进去在服务器上一键构建省去上传镜像的流量。构建完成后先本地验证一次docker run -d --name hoj-frontend-test -p 8010:80 hoj-frontend:latest curl -I http://127.0.0.1:8010curl -I能看到HTTP状态码200说明Nginx正常返回。如果返回404多半是静态文件路径不对返回502则可能是后端反代地址配错。4.2 容器网络里“后端能ping通但浏览器打不开”的问题HOJ官方通常会用Docker Compose把多个服务编排起来自动创建一个网络所有服务之间可以通过容器名互通。但如果你用宝塔的“Docker管理器”逐个创建容器默认网络可能是bridge模式几个容器在逻辑上是可以通信的不过“能ping通”不代表“HTTP请求能通”因为后端服务可能只监听了特定端口或者容器网络策略拒绝了连接。我建议把同一套服务的容器都放到同一个自定义网络里这样配置更清晰。先创建网络docker network create hoj-network启动后端容器时指定--network hoj-network启动前端容器时也指定同一个网络docker run -d --name hoj-frontend \ --network hoj-network \ -p 8010:80 \ -v /opt/hoj/frontend-config:/usr/share/nginx/html/static:ro \ hoj-frontend:latest这里的挂载我先解释一部分后面单开一小节详述。总之容器之间用网络名互访端口映射用的是宿主机端口两者不要混淆。如果你启动容器后发现页面能打开但接口报502先进前端容器里测试一下后端服务名是否解析正确docker exec -it hoj-frontend sh wget -q -O- http://backend-gateway:8080/actuator/health能拿到JSON说明容器间网络是通的问题多半出在Nginx的proxy_pass路径上。4.3 用数据卷挂载config.js实现改配置不重建HOJ前端会把一些运行时可变配置放进独立的JavaScript配置文件常见的是static/config.js或public/config.js里面包含后端地址、WebSocket地址、CDN开关、站名等等。如果这个配置被打死在镜像里每次改后端IP或者换域名都要重新构建镜像很麻烦。我的做法是在宿主机准备一个配置目录比如/opt/hoj/frontend-config/config.js然后把目录挂载进容器的static目录。容器启动时宿主机上的config.js会覆盖镜像里的默认配置。这样以后迁移域名或后端地址只需要改宿主机上的文件然后重启容器不需要重新build镜像。上面的docker run命令中-v /opt/hoj/frontend-config:/usr/share/nginx/html/static:ro就是这个目的。需要注意挂载目录要提前创建并放入正确的config.js否则容器会把空目录挂进去可能顶掉原有的默认配置造成页面连默认配置都没有直接白屏。5. 上线后的故障排查清单白屏、登录失败、页面4045.1 白屏先看浏览器Network再进容器验证前端镜像发布后我见过最多的反馈就是“页面白屏”。白屏的排查顺序很重要不要一上来就怀疑Nginx配置。先打开浏览器F12看Console和Network。如果Console里报“Failed to fetch”或“跨域”相关错误是后端地址配置不对或跨域未处理。如果Custom上加载的JS文件返回404可能是构建产物路径和Nginx的root路径不匹配。如果页面加载出来但空白且Console无报错有可能是Vue运行时异常常见原因是config.js里的必填字段缺失。进容器确认静态文件位置也很简单docker exec -it hoj-frontend ls /usr/share/nginx/html如果文件存在再用curl在容器内访问一下http://127.0.0.1/看是否返回HTML。如果容器内正常而外部访问白屏问题往往出在容器端口映射或宿主机防火墙。5.2 登录失败重点检查Cookie和X-Forwarded-Proto登录失败这个坑我在多个项目里都遇到过。前端把用户名密码提交到后端后端成功返回但下一次请求又提示未登录。原因一般是Cookie的属性问题。后端在Set-Cookie时没有标记Secure但前端实际是HTTPS访问浏览器就会拒绝保存Cookie。这种情况要检查Nginx是否正确传递了X-Forwarded-Proto后端才能感知到当前请求是HTTPS从而生成Secure Cookie。如果后端本身只暴露HTTP地址而前面还有一层HTTPS网关那也要确保网关把所有请求转发给容器时保留X-Forwarded-Proto请求头。另一类登录失败原因是前端配置了不正确的WebSocket地址导致登录成功后Socket连接建立失败前端误判为登录状态不同步。所以登录排查时不要只看Login接口还要看/ws/请求是否握手成功。5.3 404SPA路由模式与try_files顺序404有两种情况一种是刷新某个具体页面时404比如刷新/problem/1000会404但点进页面没问题。这是典型的SPA回退没有配置好try_files没有正确落到index.html。修复方式就是保证有location / { try_files $uri $uri/ /index.html; }另一种是访问后端接口返回404比如请求GET /api/health返回404。这种情况要检查前端请求路径和后端路由是否完全匹配。HOJ后端接口通常以网关路由为前缀比如/api/或/gateway/如果Nginx反代时写了location /api/但proxy_pass http://backend:8080后面没有加路径那/api/health会原样转发给后端而后端可能不认/api/health这个路径就会404。通常需要在proxy_pass里做路径重写location /api/ { proxy_pass http://backend-gateway:8080/; proxy_set_header Host $host; }proxy_pass结尾的/会把/api/前缀去掉比如前端请求/api/health转发到后端就是/health。至于是去掉前缀还是保留前缀取决于后端网关的路由规则这个要看HOJ项目的具体实现。6. 发布前值得顺手做的镜像瘦身与安全收尾6.1 用多阶段构建精简镜像我在第3节已经演示了多阶段构建。如果你拿到的源码里已经有现成Dockerfile推荐直接使用官方维护的版本不要自己另搞一套。但如果你想自定义记住核心原则构建阶段用全功能镜像运行阶段用最小镜像。nginx:alpine的镜像体积很小且自带常用工具维护成本低。构建时还可以缓存PNPM或Yarn的依赖目录进一步加速。比如使用PNPM时构建阶段先执行RUN pnpm config set store-dir /pnpm-store COPY pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile这样依赖会被缓存后续构建只需要改源码不需要重新解析锁文件和下载全部依赖。6.2 避开80端口冲突与可观测性小配置如果你的服务器上宝塔自身Nginx已经占了80端口前端容器再映射80端口就会失败。最简单的办法是把前端容器映射到高位端口比如8010然后在宝塔“网站”里添加反向代理把需要对外访问的域名或路径转发到http://127.0.0.1:8010。这样宝塔Nginx负责接收80/443的HTTPS流量再转到我们的前端容器容器内部仍然是80端口互不冲突。如果不想额外套一层代理也可以停掉宝塔Nginx直接让前端容器映射宿主机80端口但这样宝塔的网页管理功能可能会受影响不建议新手这么做。我更倾向于“域名入口统一由宝塔Nginx管理里面转发到各个应用容器”的布局。容器启动后记得加上--restartalways防止服务器重启后前端容器没有自动拉起。这条参数在宝塔Docker管理界面里也有对应选项。6.3 后端网关和前端location如何保持一致最后再强调一个细节前端请求的路径前缀必须和后端网关配置一致。很多同学独立部署时前端写/api/后端网关的路由前缀是service-api结果自然对不上。在改Nginx之前先用curl手动验证一条后端接口的地址curl http://127.0.0.1:8080/actuator/health然后逐步模拟前端请求路径比如带前缀访问curl http://127.0.0.1:8010/api/actuator/health如果Nginx反代配置正确能得到和后端一样的JSON。这比盲改配置高效得多。另外静态资源的缓存策略也可以顺手优化带hash的JS/CSS资源可以设置长期缓存index.html设置为不缓存或短缓存这样用户更新页面时能及时拿到新版本。Nginx里可以这样区分location /static/ { expires 30d; add_header Cache-Control public, immutable; } location /index.html { add_header Cache-Control no-cache; }说实话HOJ部署到这个阶段整套系统已经算是“能跑”了。前端镜像的构建本身不难难点全在运行时的路径匹配、网络连通和Cookie这类“看不见的细节”上。我在帮别人排查时发现90%的问题都出在三个地方config.js里的地址写错、Nginx缺少SPA回退、反向代理路径不一致。如果按这套流程做下来还是有问题建议先把容器日志打开docker logs -f hoj-frontend再配合浏览器F12的Network面板一步步确认静态资源、API请求、WebSocket连接分别卡在哪一环。容器化部署的好处就是“环境和代码一起打包”排错时可以大胆删掉容器重建不用担心在服务器上留下什么清理不干净的残留文件。前端这一步跨过去HOJ就算是真正交付了。