第一次把本地跑得挺欢的项目搬到服务器上多数人会经历同一个瞬间浏览器敲下域名回车页面白得像一张没写字的纸或者页面出来了接口却清一色 502。我见过太多人卡在这一步本地localhost:8080和localhost:5173一路顺风一上服务器就全线崩盘然后开始怀疑人生——是不是 SpringBoot 版本太高了是不是 Nginx 装错了其实 SpringBoot 前后端分离项目的打包和部署到服务器这件事本身没有多玄学它的难处在于链路长、环节多前端构建产物、后端可执行 Jar、Nginx 静态托管与反向代理、Java 进程常驻、日志与配置分离任何一环没对齐表现都是打不开。这篇就按我自己的实际操作顺序把整条链路从头到尾拆一遍每一步都说明为什么这么做、不这么做会出什么问题。适合刚接触服务器部署的同学也适合部署过几次但总在同一个地方翻车的老手对照排查。1. 上线前先搞清楚生产环境里到底有几个进程在跑1.1 三个进程各管一段别混在一起本地开发时你脑子里其实是两套东西IDEA 里跑着的 SpringBoot 应用占了 8080终端里npm run dev起的 Vite 或 Webpack DevServer占了 5173。开发服务器顺带帮你做了件事——把/api开头的请求转发到 8080所以你在浏览器里看不到跨域问题。到了服务器上这套临时组合要换成正式编制通常是三个东西角色跑什么监听端口职责NginxNginx 主进程80 / 443返回前端 dist 里的静态文件把 /api 请求转发给后端后端服务你打的 SpringBoot Jar8080只对内网或本机业务逻辑、读写数据库数据库/缓存MySQL、Redis3306 / 6379数据存储一般不暴露公网浏览器访问http://your-domain.com/user/list实际发生的事情是请求先到 NginxNginx 看路径不是/api开头就去root指向的目录里找index.html丢回去浏览器执行 JS页面向/api/user/list发请求这次 Nginx 匹配到/api的 location把请求转给127.0.0.1:8080SpringBoot 处理完把 JSON 返回Nginx 再原样吐给浏览器。理解这条链路有两个直接好处。第一你知道 8080 端口根本不需要在云服务器安全组里放行只要 Nginx 能访问到就行少开一个口子少一分风险。第二任何一个环节出问题症状是可以区分的页面打不开多半是 Nginx 或静态文件的问题页面能开但数据空白多半是反向代理或后端的问题。后面第 6 章我会把这张症状对照表铺开讲。1.2 为什么我不建议把 dist 塞进 static 目录网上有一类很流行的省事做法npm run build之后把dist里的东西全丢进src/main/resources/static再打一次 Jar前端后端一个包搞定部署只传一个文件。小项目、内网演示、给客户做原型这么干没问题确实省事。但只要项目稍微正经一点我都不推荐原因有三个迭代成本高。改一行按钮文案要重新npm run build再把产物拷进 Java 工程再走一遍 Maven 打包再传服务器重启进程。前后端分离的初衷就是解耦这么一搞又焊回去了。静态资源性能差。内嵌 Tomcat 提供静态文件的吞吐能力和 Nginx 不在一个量级。Nginx 处理静态文件是它的看家本领零拷贝、高并发连接、高效的 sendfile 都是为这个场景优化的。缓存和压缩控制弱。Nginx 可以针对带 hash 的 JS/CSS 设置一年强缓存对index.html设置不缓存还能开 gzip 甚至预压缩的 gzip_static这些在 Java 侧配置起来要费不少劲。我的做法是/opt/app/frontend放前端 dist/opt/app/backend放 Jar 和外部配置文件职责清清楚楚。这样前端改版只需要覆盖前端目录Java 进程都不用碰后端发版也只需要重启后端服务静态资源一秒都没中断过。1.3 服务器环境清单与目录规划很多人第一步就卡在服务器上要装什么。我列一个最小清单不是每个都必须看你项目用到了什么组件是否需要装在服务器说明JDK必须版本和本地一致推荐 17Jar 编译目标版本不能高于运行版本Nginx必须静态托管 反向代理替代掉开发时的 DevServerMySQL按需也可以用云数据库省去自己装和备份Redis按需缓存、会话、验证码等场景Node.js通常不需要前端在本地或 CI 构建好服务器只收 distMaven通常不需要后端在本地打包好服务器只收 Jar这里有个容易踩的点编译用的 JDK 版本和运行时的 JDK 版本必须兼容。你在本地用 JDK 17 编译出来的 class 文件扔到只装了 JDK 8 的服务器上跑启动瞬间就会报Unsupported class file major version 61这个报错看着吓人本质就是版本对不上。目录我习惯这么规划后面所有命令都基于这套路径你按自己习惯改就行/opt/app/ ├── frontend/ # 前端 dist 内容Nginx 的 root 指向这里 │ ├── index.html │ └── assets/ ├── backend/ │ ├── app.jar # SpringBoot 可执行 Jar │ ├── config/ # 外部配置优先级高于 jar 内部 │ │ ── application-prod.yml │ └── logs/ # 日志落盘位置 └── upload/ # 用户上传文件目录需要写权限提示/opt目录属于系统目录普通用户可能没权限。要么用 root 操作要么提前chown -R youruser:youruser /opt/app把归属改掉后面用 systemd 跑服务时会省事很多。2. 后端打包从 Maven 生命周期到可执行 Jar2.1 spring-boot-maven-plugin 到底做了什么很多人打了几十次包却没搞清楚mvn package之后为什么会多出一个xxx.jar.original。这个文件的存在恰好解释了 SpringBoot 打包的核心机制。Maven 的package阶段默认只干一件事把你的src/main/java编译出来的 class 加进 jar。这个 jar 里没有第三方依赖你直接java -jar会因为找不到 Spring 的类而报NoClassDefFoundError。而 SpringBoot 的spring-boot-maven-plugin会在package之后挂一个repackage目标做三件事把项目自身的 class 和所有依赖 jar 一起塞进新 jar依赖放在BOOT-INF/lib/下把原始的、不含依赖的 jar 重命名保存为.original留个底改写META-INF/MANIFEST.MF把Main-Class设成org.springframework.boot.loader.launch.JarLauncher把你真正的启动类写进Start-Class。所以启动流程是JVM 先跑JarLauncher这个启动器负责构造一个能读取BOOT-INF/lib的类加载器然后再调用Start-Class指向的main方法。理解这一点你就明白两个常见现象了xxx.jar.original不是垃圾别删它可以作为对照如果 pom 里没配这个插件或者被人手动去掉了打出来的 jar 就是跑不起来报错通常是no main manifest attribute。一个可用的插件配置长这样重点是mainClass要写对build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration mainClasscom.example.demo.DemoApplication/mainClass excludes exclude groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /exclude /excludes /configuration /plugin /plugins /buildlombok的 exclude 是可选的它只在编译期起作用运行时不需要排掉能少几十 KB对启动速度有一点点帮助。真正重要的是mainClass——项目里有多个带main方法的类时比如你写过测试用的启动类插件可能猜错显式指定最稳。2.2 多环境配置什么该打进 jar什么必须留在外面配置分离是我认为部署环节里最值得花时间的一件事。做法是application.yml只放公共配置和默认值环境相关的放application-dev.yml、application-prod.yml通过spring.profiles.active激活。# application.yml打进 jar spring: profiles: active: prod application: name: demo server: port: 8080 # application-prod.yml放在外部 config 目录 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: demo_user password: 你的密码 data: redis: host: 127.0.0.1 port: 6379 logging: file: name: /opt/app/backend/logs/app.log为什么生产配置一定要放外面因为数据库密码不该被打进 jar。jar 可能被复制、被下载、被丢进制品库密码跟着走就麻烦了。而 SpringBoot 的外部配置优先级是明确的命令行参数 当前目录下config/目录 当前目录 classpath 下config/ classpath 根目录。所以你在 jar 同级放一个config/application-prod.yml它会自动覆盖 jar 内的同名配置不需要改任何代码。注意外部配置文件的文件名必须和 profile 对得上。激活的是prod文件名就得是application-prod.yml或.properties写成application-product.yml是不生效的而且不会报错只会静默地用了 jar 里的默认值——这是最坑的一类问题后面第 6 章还会提到。2.3 打包命令与几个高频报错命令行打包的标准姿势# 跳过测试打包指定 prod 对应的打包配置如果不涉及资源过滤可以不加 -P mvn clean package -DskipTests -Pprodclean别省。Maven 的增量编译偶尔会留下陈旧 class尤其是你改了包名、删了类之后不 clean 打出来的 jar 里可能还带着老代码排查起来极其浪费时间。在 IDEA 里操作也简单右侧 Maven 面板展开项目Lifecycle下双击clean再双击package等价于上面那条命令。只是 IDEA 默认不会带-DskipTests测试用例跑失败会中断打包。几个我见过最多的报错对应处理方式如下报错信息真实原因处理方式Unsupported class file major version 61编译 JDK 高于运行 JDK统一版本或指定maven.compiler.releaseno main manifest attribute没配 spring-boot-maven-plugin补插件配置Unable to find main class没有带SpringBootApplication的类或包结构不对检查启动类位置打包时中文注释乱码警告平台默认编码是 GBK在 pom 里设project.build.sourceEncodingUTF-8/project.build.sourceEncoding依赖下载卡住 / 超时仓库地址不通或镜像失效检查settings.xml的 mirror 配置第一个报错值得多说一句。有些同学本地换了 JDK 17服务器上还是老的 JDK 8本地编译一切正常上传后启动就炸。判断方法很简单在服务器上java -version和本地 IDEA 里Project Structure的 SDK 版本对一下。如果不方便升级服务器 JDK就在 pom 里把maven.compiler.source和target降到 8但要注意你用的 SpringBoot 版本本身可能已经不支持 JDK 8 了。2.4 上传前先在本地把 jar 跑一遍这一步跳过的人特别多但性价比极高。本地验证的命令java -jar app.jar --spring.profiles.activeprod如果能正常起来、日志里能看到 Tomcat 在 8080 端口启动说明 jar 本身是好的问题一定出在服务器环境上。如果本地都跑不起来那服务器上就更不用试了先把本地问题解决掉。本地验证时把application-prod.yml里的数据库地址改成能连通的地址否则会因为连不上库而启动失败——但这恰恰也是个有用的信号连不上数据库时报的错和 jar 打包错误完全不是一个样子多看几次日志就能一眼分辨。我一般会刻意让本地连一次错误的地址把那个报错记下来上服务器后再看到同样的日志就知道该去查网络和账号权限而不是怀疑打包。3. 前端打包路径、体积与路由模式三个陷阱3.1 构建产物到底是什么为什么不传源码npm run build在 Vue CLI 项目里走的是vue-cli-service build在 Vite 项目里是vite build。不管哪个做的事都类似把.vue单文件组件编译成 JS 渲染函数把 SCSS/LESS 编译成 CSS把模块化的 import 打包合并最后产出一个dist目录。产物结构大致是dist/ ├── index.html ├── assets/ │ ├── index-a1b2c3d4.js │ ├── index-e5f6g7h8.css │ ── vendor-9i0j1k2l.js └── favicon.ico文件名里那串a1b2c3d4是内容哈希内容变了哈希才变这是做长效缓存的基础第 4 章会用到。服务器上绝对不要传源码。原因很直接源码浏览器不认识.vue文件里那些模板语法、import语句都需要构建工具处理而且把源码放到 Web 目录等于把你的业务逻辑、接口地址、甚至注释都公开了。构建这个动作在本地或 CI 完成就好服务器只接收成品。3.2 publicPath / base 配错页面就是一片白这是新手最容易撞的一堵墙症状非常有辨识度HTML 出来了Network 面板里 JS 和 CSS 全是 404页面白屏控制台报Unexpected token 因为服务器对找不到的 js 返回了 index.html浏览器拿 HTML 当 JS 解析。根因是资源引用路径不对。Vue CLI 项目里这个配置叫publicPath// vue.config.js module.exports { publicPath: process.env.NODE_ENV production ? / : /, outputDir: dist, assetsDir: assets, productionSourceMap: false }Vite 项目里叫base// vite.config.js export default defineConfig({ base: /, build: { outDir: dist, sourcemap: false } })/和./的区别很多人搞不清。/生成的是/assets/index-xxx.js从域名根开始找./生成的是./assets/index-xxx.js相对当前 HTML 位置找。什么时候必须改成子路径当你的应用不是部署在域名根目录而是放在http://domain/admin/这种二级路径下时。这时publicPath要写/admin/同时路由器的 base 也要同步设置const router createRouter({ history: createWebHistory(/admin/), routes })两边任何一个漏改都会白屏。判断技巧打开浏览器开发者工具的 Network看那些 404 的请求 URL 是什么。如果请求变成了http://domain/assets/index-xxx.js而你的文件在/admin/assets/下就是publicPath没改如果请求对但页面内容不对检查路由 base。3.3 history 模式刷新就 404根因不在前端Vue Router 默认推荐 history 模式URL 干净http://domain/user/list看起来很舒服。但你在部署后会发现从首页点链接进去一切正常一按 F5 刷新就 404。原因不复杂。点击链接跳转时是前端路由在浏览器内部接管没有向服务器发请求。而按 F5浏览器是真的向服务器请求/user/list这个路径Nginx 去root指向的目录里找名为list的文件或user目录找不到就返回 404。解决方式是让 Nginx 在找不到文件时统一回退到index.htmllocation / { try_files $uri $uri/ /index.html; }这行的意思是先找有没有同名文件再找有没有同名目录都没有就返回index.html剩下的事情交给前端路由。但这行配置有个副作用需要留意它会把真实的 404 也吞掉。比如用户请求/api/not-exist如果这个路径也被location /匹配到就会返回 index.html 而不是 404调试时会误导你。所以location /api/的规则必须写在location /之前让 Nginx 优先匹配它。Nginx 的 location 匹配规则里前缀匹配会优先选最长的那条长度相同时才看书写顺序但写在前面对排查更友好。顺手说一下 hash 模式为什么没这个问题hash 模式的 URL 长这样http://domain/#/user/list#后面的内容浏览器不会发给服务器服务器永远只收到/自然永远能找到index.html。代价是 URL 不好看且对 SEO 不友好。用哪种是取舍不是对错。3.4 打包体积别让首屏卡在 3MB 的 JS 上前端打包体积直接决定首屏速度也决定用户在弱网下的体验。几个见效快的做法路由懒加载。用() import(./views/UserList.vue)替代顶部静态 importWebpack/Vite 会把每个页面拆成独立 chunk首页只加载首屏需要的。关闭 sourcemap。productionSourceMap: false产物能小一大截。sourcemap 只在排查生产问题时有用日常不需要。依赖分包。把vue、element-plus、axios这类不常变的库拆到单独 chunk利用浏览器缓存改业务代码时用户不用重新下载整个包。图片压缩。大图放 CDN 或者用构建插件压一下一张未压缩的 banner 图可能比整个 JS 包还大。Vite 项目里可以用manualChunks做分包build: { rollupOptions: { output: { manualChunks: { vue: [vue, vue-router, pinia], ui: [element-plus] } } } }压缩这件事前端构建工具能做 minify但gzip 交给 Nginx 更划算。构建时生成.gz文件或用 Nginx 的gzip on实时压缩JS/CSS 体积通常能再降 60% 到 70%。这个我们在下一章配。4. 服务器落地Nginx 托管静态资源 反向代理4.1 文件怎么传上去权限怎么给传文件最直接的方式是scp# 传前端 dist 内容 scp -r ./dist/* rootyour-server:/opt/app/frontend/ # 传后端 jar scp ./target/app.jar rootyour-server:/opt/app/backend/ # 传外部配置 scp ./application-prod.yml rootyour-server:/opt/app/backend/config/scp -r ./dist/*里的*是有意写的意思是传目录里的内容而不是把dist这个目录本身搬过去否则路径会变成/opt/app/frontend/dist/index.html和你配置的root对不上。这种小细节出错概率极高传完后随手ls一下确认层级。权限方面Nginx 工作进程通常以nginx或www-data用户运行它需要能读取/opt/app/frontend下的文件。一般chmod -R 755就够了。上传目录/opt/app/upload则需要写权限因为 Java 进程要往里写文件要保证运行 Java 的那个用户在目录上可写否则上传功能会报Permission denied而这个报错很隐蔽往往在用户点上传按钮时才暴露。4.2 一份可以直接抄的 Nginx 配置server { listen 80; server_name your-domain.com; root /opt/app/frontend; index index.html; # 前端静态资源与 SPA 路由回退 location / { try_files $uri $uri/ /index.html; } # 带 hash 的静态资源长缓存 location /assets/ { expires 1y; add_header Cache-Control public, immutable; } # index.html 不缓存保证发版后用户立刻拿到新版本 location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; } # 反向代理后端接口 location /api/ { proxy_pass http://127.0.0.1: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; proxy_connect_timeout 30s; proxy_read_timeout 60s; } # gzip 压缩 gzip on; gzip_min_length 1k; gzip_comp_level 5; gzip_types text/plain text/css application/javascript application/json image/svgxml; gzip_vary on; client_max_body_size 20m; }client_max_body_size那行特别容易漏。Nginx 默认只允许 1MB 的请求体用户传个稍微大点的文件或者图片就直接被拒前端收到的是一段 Nginx 生成的 HTML 错误页而不是 JSON前端解析 JSON 失败报的还是个看不懂的错误。这个坑我在文件上传功能上线当天踩过排查了半小时才发现跟代码一点关系都没有。4.3 反向代理顺手解决跨域但尾斜杠要小心配置了location /api/之后浏览器眼里所有请求都是同源的——页面是http://your-domain.com接口也是http://your-domain.com/api/xxx端口域名协议全一样跨域问题自然消失。这也是为什么生产环境通常不需要在 SpringBoot 里配 CORSCORS 是开发期给 DevServer 用的。但proxy_pass的尾斜杠是个经典陷阱同一个路径带不带斜杠转发结果完全不同# 情况一带斜杠会剥掉 /api 前缀 location /api/ { proxy_pass http://127.0.0.1:8080/; } # 前端请求 /api/user/list - 后端收到 /user/list # 情况二不带斜杠原样透传 location /api/ { proxy_pass http://127.0.0.1:8080; } # 前端请求 /api/user/list - 后端收到 /api/user/list规则很好记proxy_pass后面的地址结尾有斜杠就用它替换掉 location 匹配到的前缀没有斜杠就把完整路径拼上去。所以你得先确认后端接口到底长什么样。如果 Controller 上是RequestMapping(/user)接口是/user/list那前端就该请求/api/user/listNginx 用带斜杠的写法剥掉/api。如果后端配了server.servlet.context-path: /api那前端请求/api/user/listNginx 转发时不能剥前缀就要用不带斜杠的写法。判断错了的症状是清一色 404而 404 的响应体还是 SpringBoot 默认的错误 JSON看着挺像接口不存在很容易往代码方向查。最快的排查方法是直接在后端服务器上 curl# 绕过 Nginx直接问后端确认后端真实路径 curl -i http://127.0.0.1:8080/user/list # 再通过 Nginx 问一次对比路径有没有被改 curl -i http://127.0.0.1/api/user/list两条命令一对比路径差异一目了然。4.4 缓存与 gzip把首屏时间压下去缓存策略的核心思路是按文件是否带 hash 区别对待。带 hash 的index-a1b2c3d4.js内容一变文件名就变所以可以放心让浏览器缓存一年这就是上面location /assets/里immutable的用意。而index.html文件名永远不变如果也缓存一年你发版后用户得强制刷新才能看到新功能所以必须no-cache。gzip_vary on这行也别漏它会响应Vary: Accept-Encoding头告诉中间的缓存服务器同一个 URL 可能有压缩和未压缩两个版本别混用避免出现给不支持 gzip 的客户端返回压缩内容的尴尬。如果你用的是 Vite 或 Webpack 的压缩插件构建时已经生成了.gz文件放在 dist 里那可以在 Nginx 用gzip_static on直接读现成的压缩文件比实时压缩省 CPU。不过这个模块需要 Nginx 编译时带--with-http_gzip_static_module装之前确认一下否则会报unknown directive。改完配置别急着restart先测试再重载nginx -t # 语法检查 nginx -s reload # 平滑重载不中断现有连接reload优于restart前者不会掐断正在处理的请求线上更友好。5. 让后端服务常驻systemd 与 JVM 参数5.1 为什么放弃 nohup改用 systemd很多人第一次部署后端是这么干的nohup java -jar app.jar app.log 21 能用但问题一堆服务器重启后服务不会自动起来进程莫名挂掉后没人拉起来日志全靠自己重定向切割要靠 cronps -ef | grep java找进程号再 kill很容易误杀别的 Java 进程。上线一段时间后你一定会被这些问题烦到。systemd 把这些问题一次性解决开机自启、崩溃自动重启、统一日志管理、systemctl restart一键操作。配置文件的成本只有十几行。5.2 一份可以照抄的 service 文件创建/etc/systemd/system/demo.service[Unit] DescriptionDemo SpringBoot Application Afternetwork.target mysqld.service redis.service [Service] Typesimple Userappuser WorkingDirectory/opt/app/backend ExecStart/usr/bin/java -Xms256m -Xmx512m \ -Duser.timezoneAsia/Shanghai \ -Dfile.encodingUTF-8 \ -jar /opt/app/backend/app.jar \ --spring.profiles.activeprod SuccessExitStatus143 Restarton-failure RestartSec10 StandardOutputappend:/opt/app/backend/logs/stdout.log StandardErrorappend:/opt/app/backend/logs/stderr.log [Install] WantedBymulti-user.target几个关键点值得解释WorkingDirectory必须是 jar 所在目录。因为 SpringBoot 查找外部配置时会看当前工作目录下的 config 目录工作目录设错了外部配置就读不到服务用的还是 jar 里的默认值。这个错误非常隐蔽表现为我明明改了配置文件但没生效。SuccessExitStatus143是给优雅停机用的。Java 进程收到 SIGTERM信号编号 15退出码 12815143时SpringBoot 会执行关闭钩子正常退出。不写这行systemd 会认为进程是被异常杀掉的可能触发不必要的重启。Restarton-failure配合RestartSec10表示失败后等 10 秒再拉起。加延迟是为了避免启动就崩、崩了重启、重启又崩的死循环把 CPU 打满。如果配置错得离谱至少给你留出看日志的时间。启用步骤systemctl daemon-reload # 新增 unit 文件后必须执行 systemctl enable demo # 开机自启 systemctl start demo # 启动 systemctl status demo # 看状态 journalctl -u demo -f # 实时看日志daemon-reload这步漏了systemctl start会报Unit not found很多人以为文件名写错了其实只是没重载。5.3 日志落盘、切割、快速定位日志这块我建议分两层。应用层的日志用logback-spring.xml配置按天切割、保留 15 天、限制单文件大小这样能避免磁盘被日志撑满configuration appender nameFILE classch.qos.logback.core.rolling.RollingFileAppender file/opt/app/backend/logs/app.log/file rollingPolicy classch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy fileNamePattern/opt/app/backend/logs/app.%d{yyyy-MM-dd}.%i.log/fileNamePattern maxFileSize100MB/maxFileSize maxHistory15/maxHistory totalSizeCap3GB/totalSizeCap /rollingPolicy encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n/pattern charsetUTF-8/charset /encoder /appender root levelINFO appender-ref refFILE/ /root /configurationSizeAndTimeBasedRollingPolicy比单纯的TimeBasedRollingPolicy更稳因为它在按天切的基础上还加了单文件大小限制。万一某天报错日志爆炸式增长单日文件也不会大到打不开。totalSizeCap是总的磁盘占用上限超过会自动删最老的这是个保命配置。进程层面的 stdout/stderr 走 systemd 的journalctl好处是可以按时间、按服务过滤不用去翻一堆文件journalctl -u demo --since 10 min ago journalctl -u demo -p err # 只看 error 级别应用日志和进程日志分开排查时思路也更清楚进程起不来、JVM 级别的问题看 journalctl业务逻辑异常、SQL 报错看 app.log。5.4 JVM 参数小内存服务器别乱配JVM 参数看着简单配错了会直接把服务器搞挂。我的经验是遵循物理内存的一半以内这个粗原则服务器内存建议 -Xmx说明1 GB256m 到 384m还要留给 Nginx、MySQL、系统本身2 GB512m最常见的入门配置4 GB1g 到 1.5g可以和数据库同机8 GB 以上2g 到 4g剩余内存给系统和缓存-Xms和-Xmx建议设成一样避免运行期堆反复扩容收缩带来的性能损耗。-Duser.timezoneAsia/Shanghai也很重要否则容器或服务器时区不设的话日志时间戳和数据库里存的时间可能差 8 小时跨天统计数据会很离谱。如果服务总是被系统杀掉看dmesg里有 OOM Killer 的记录通常是堆设得太大加上 Metaspace、线程栈、直接内存实际占用远超-Xmx。2GB 内存的机器上给 SpringBoot 配-Xmx2g是自杀行为一定留出余量。6. 上线后出问题怎么查一张症状对照表6.1 502 和 504先确认后端进程活着Nginx 报 502 Bad Gateway意思是它连不上后端。排查顺序固定别跳步systemctl status demo # 进程在不在 ss -lntp | grep 8080 # 端口有没有在监听 curl -i http://127.0.0.1:8080/actuator/health # 本机能不能通三步能把问题范围缩到很小。systemctl status显示failed就去journalctl -u demo -n 100看启动日志进程活着但 8080 没监听多半是端口配置被外部 yml 覆盖成了别的值本机能通但通过 Nginx 502那就是proxy_pass地址写错了比如写成了外网 IP 或者域名解析不到。504 是超时含义完全不同连上了但后端处理太久没返回。先看proxy_read_timeout够不够默认 60 秒再查是不是接口里有慢 SQL、大批量数据处理或者死循环。这时候看应用日志比看 Nginx 日志有用得多。6.2 白屏和接口 404是两个方向的问题这两类症状经常被混为一谈其实定位方法完全相反症状排查方向常用手段页面完全白屏前端资源加载F12 Network 看 JS/CSS 是否 404页面框架出来了列表空白接口请求F12 Network 看 XHR 请求状态码刷新页面 404点链接正常SPA 路由回退检查 try_files所有接口 404反向代理路径用 curl 对比直连和经代理的路径接口返回 200 但数据是 HTML代理配置或路径错看响应内容开头是不是!DOCTYPE接口返回 200 但数据是 HTML这条值得单独说。当 Nginx 把 API 请求也匹配到了location /并走了try_files ... /index.html就会返回 index.html状态码是 200。前端拿到 HTML 去JSON.parse报的错是Unexpected token 看着像前端 bug实际是 Nginx 匹配顺序的问题。6.3 跨域、Cookie 和上传目录权限部署到生产后跨域一般会消失但有几个例外情况值得说明。一是接口域名和页面域名确实不同比如前端在www.a.com后端在api.b.com。这时候要么在后端配 CORS要么在 Nginx 再套一层转发让它们同源。二是前端请求写的是完整地址http://127.0.0.1:8080/api/xxx而不是相对路径/api/xxx。开发时写完整地址很常见上线前一定要改成相对路径或者用环境变量切换否则用户浏览器会去请求他自己电脑的 8080必然失败。Cookie 相关的问题也很典型登录后接口一直提示未登录。原因往往是SameSite和Secure属性——如果接口在 HTTPS 下而 Cookie 没设Secure或者跨站场景下SameSiteLax阻止了 Cookie 携带登录态就传不过去。统一在 Nginx 层做同源代理能规避绝大部分这类问题。上传功能报错第一件事看目录权限ls -ld /opt/app/upload id appuser确认运行 Java 的用户对上传目录有写权限。另一个高频原因是 Nginx 的client_max_body_size前面提过症状是上传大文件失败、小文件正常。6.4 时区、编码、数据库连接这三件小事这三件事单看都很小叠加起来能让你查一整天。时区问题的典型表现是数据库里存的时间和页面显示的差 8 小时。要同时检查三处JVM 参数有没有-Duser.timezoneJDBC URL 里有没有serverTimezoneAsia/ShanghaiMySQL 服务器本身的时区设置。三处对齐才不会出问题。编码问题表现为中文乱码。除了 JVM 的-Dfile.encodingUTF-8还要注意 MySQL 连接串里的characterEncodingutf8以及数据库表本身的字符集。从请求参数到数据库存储中间任何一环用了 GBK 都可能乱码。数据库连不上则通常是白名单和账号权限问题。云数据库默认只允许特定 IP 访问服务器换了弹性 IP 之后连不上是很常见的情况。报错关键字是Access denied账号密码或权限问题和Connection refused/timeout网络或白名单问题两者指向的方向完全不同看日志时留意区分。7. 用 Docker Compose 把整套环境固化下来7.1 什么时候值得上容器手工部署一套跑通之后如果你手上只有一台服务器一个项目说实话没必要急着上 Docker。但如果出现下面这些情况容器化的收益就很明显了同一台机器要跑多个项目端口、依赖版本互相冲突每次换服务器都要重新装一遍 JDK、Nginx、MySQL步骤繁琐还容易漏团队多人开发需要保证环境一致。容器的核心价值是把环境描述成文件让部署变成一条命令而不是一份容易被遗忘的操作笔记。7.2 后端 DockerfileFROM eclipse-temurin:17-jre WORKDIR /app COPY app.jar /app/app.jar COPY config/ /app/config/ ENV TZAsia/Shanghai ENV JAVA_OPTS-Xms256m -Xmx512m -Duser.timezoneAsia/Shanghai -Dfile.encodingUTF-8 EXPOSE 8080 ENTRYPOINT [sh, -c, java $JAVA_OPTS -jar /app/app.jar --spring.profiles.activeprod]用jre而不是jdk镜像能小两百多 MB运行阶段不需要编译器。ENTRYPOINT用sh -c包一层是为了让$JAVA_OPTS这个环境变量能被正确展开直接写成数组形式的话变量不会替换。注意COPY config/这一行对应的是前文说的外部配置目录容器里的工作目录是/appconfig子目录就在/app/configSpringBoot 能自动识别。7.3 Compose 编排services: backend: build: ./backend container_name: demo-backend restart: unless-stopped environment: - TZAsia/Shanghai volumes: - ./logs:/app/logs - ./upload:/app/upload networks: - demo-net nginx: image: nginx:1.24-alpine container_name: demo-nginx restart: unless-stopped ports: - 80:80 volumes: - ./frontend:/usr/share/nginx/html:ro - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro depends_on: - backend networks: - demo-net networks: demo-net: driver: bridge关键变化是proxy_pass的地址。容器之间通过服务名互相访问所以 nginx.conf 里要改成location /api/ { proxy_pass http://backend:8080/; }原来的127.0.0.1:8080在容器里指向的是 Nginx 容器自己肯定连不上。这个改动是容器化部署最容易忘的一步症状还是 502。另外后端服务不再需要ports映射因为它不需要被宿主机访问Nginx 通过内部网络就能找到它。少映射一个端口就少一个暴露面。日志和上传目录挂载出来是为了容器重建后数据不丢——这点特别重要如果上传文件只存在容器内docker compose down之后文件就一起没了。7.4 我踩过的几个容器化坑第一个是时区。基础镜像默认是 UTC日志时间会差 8 小时必须显式设TZ环境变量光在 JVM 参数里设user.timezone有时候还不够因为部分日志框架读的是系统时区。第二个是文件权限。容器里 Java 进程可能是以非 root 用户跑的挂载出来的宿主机目录属主不对写文件会失败。挂载后记得检查属主必要时在宿主机上chown。第三个是内存限制。如果给容器设了内存上限而 JVM 的-Xmx超出了这个上限容器会被直接杀掉日志里只有一句Killed看不出原因。要么不设容器内存限制要么让-Xmx明显低于限制值。第四个是镜像构建时的网络。构建阶段需要拉基础镜像如果网络不通构建会卡住。这一点提前在当地测试一次比上线当天手忙脚乱要好。我个人现在的习惯是第一次部署用原生方式Nginx systemd跑通、把每个环节都摸清楚第二次开始如果项目数量增多再迁到 Compose。直接上手容器但不懂底层链路出问题时连该看哪个日志都不知道反而更慢。链路清楚之后容器只是把这套链路写进了 YAML 文件里本质没变。