发布后监控面板一切正常:curl -s 127.0.0.1:8081/actuator/health 每次都返回 {"status":"UP"},负载均衡据此把流量持续打进来。但业务报警在响,大量请求 500,日志里是数据库连接超时。健康检查说「我很好」,实际数据库已经连不上了,这个探针只证明了「Java 进程还活着」。

这是上线阶段最常见的一类问题:开发时只关心代码能不能跑,部署时才发现配置、探针、日志、线程数每一项都要单独设计。健康检查写得太浅,故障时流量不摘;日志不打滚动,几天后磁盘满;容器不给内存上限,进程被系统直接杀掉;停机不等任务结束,用户请求被腰斩。它们不会在本地复现,只在真实流量和真实故障下出现。

这一篇按上线检查的顺序走:配置怎么外置、日志怎么配、健康检查怎么分层、停机怎么做、Tomcat 和容器参数怎么定。前五篇讲的是「服务能跑、能读数据、能鉴权、能跑任务」,这一篇讲的是「它能不能在故障里体面地活着」。

配置外置:同一个 jar,不同环境

原则是「构建一次,到处运行」:jar 里不包含任何环境的地址和密钥,运行时通过外部输入决定连哪个库、开哪个端口、用哪个密钥。这样测试环境的包和生产是同一个,出问题时不用怀疑「是不是打包打错了」。

Spring Boot 的配置优先级从高到低大致是:命令行参数、Java 系统属性、操作系统环境变量、application-{profile}.yml、application.yml。这条顺序决定了「为什么我在 yml 里改了端口,启动还是 8080」——很可能启动脚本里写了 --server.port,命令行把文件覆盖了。

环境变量的名字有转换规则:spring.datasource.url 对应 SPRING_DATASOURCE_URL,点换成下划线,全大写。名字拼错不会报错,只是不生效,所以改完配置要用 /actuator/env 或启动日志确认实际值。密钥类配置用环境变量注入,不要写进 yml,也不要在启动命令里明文拼接,后者会出现在进程列表和history 里。

server:
  port: 8081
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s
  datasource:
    url: jdbc:h2:mem:app;DB_CLOSE_DELAY=-1
    username: SA
    password: ""
  flyway:
    locations: classpath:db/migration
management:
  endpoints:
    web:
      exposure:
        include: health
  endpoint:
    health:
      probes:
        enabled: true
logging:
  file:
    name: logs/app.log

本地启动时用环境变量注入密钥,再跑 jar。Windows 的 PowerShell 写法如下,Linux 用 export,容器里用编排文件的环境变量段:

$env:APP_SECRET = "change-me"
java -jar target/demo-0.0.1.jar --server.port=8081

健康检查和指标依赖 actuator,构建时只需要多这一项,不需要额外的手写端点:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

不要把 profile 当成环境开关的全部。--spring.profiles.active=prod 只是加载 application-prod.yml,真正的差异仍然要写在外部配置里。常见错误是仓库里同时提交了 application-prod.yml 和测试库密码,结果密钥还是进了代码历史。

日志:能查问题,且不撑爆磁盘

日志要回答三个问题:什么时候、哪个请求、发生了什么。至少要有时间戳、级别、线程名、logger 名和消息。生产用 INFO 起步,DEBUG 只在排查时临时打开,并且要能自动恢复,否则一次忘记关闭就会把磁盘写满。

文件日志必须配滚动。按大小和时间滚动的常见配置是单文件 100 兆、保留 30 天、总占用封顶 1 吉字节,这样磁盘占用就有上限。只配 logging.file.name 不会自动滚动,需要一个 logback-spring.xml 定义 appender 和 policy:

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/app.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>logs/app.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
      <maxFileSize>100MB</maxFileSize>
      <maxHistory>30</maxHistory>
      <totalSizeCap>1GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="FILE"/>
  </root>
</configuration>

日志里绝对不能出现密码、令牌、完整的请求头、身份证号和手机号。常见泄露路径有三个:登录接口把密码打进 DEBUG;全局异常把请求体原样打印;访问日志记录了 Authorization 头。脱敏要在写入前做,不能指望事后清理,因为文件一旦落盘就可能被备份、采集、转发。

临时排查时打开 DEBUG,要用外部配置控制,而不是改代码重新打包。比如启动参数加 --logging.level.com.example.demo=DEBUG,排查完重启去掉即可。把级别写死在代码里,下一次出事还想不起来是谁加的,这种技术债最后都变成日志噪音。

多实例部署时,本地文件日志查起来很痛苦,要登到每台机器上 grep。常见做法是把日志输出成 JSON,交给采集组件汇总,按 trace id 串起一次请求。trace id 可以由网关生成,也可以在过滤器里生成并放进 MDC,异步任务要手动传递,否则任务日志和请求日志对不上。

健康检查:活着、能接流量、能干活是三件事

健康检查至少分两层。liveness 回答「进程是不是卡死」,失败时编排系统会重启容器;readiness 回答「能不能接流量」,失败时只摘流量,不重启。把数据库检查放进 liveness 是危险的:数据库短暂抖动会让所有实例一起被重启,故障反而扩大。

Spring Boot 的 actuator 默认只暴露 health,返回体只有一个状态字段,本机实测就是 {"status":"UP"}。这个默认值很浅,只说明应用上下文还活着,不检查数据库。要让它检查数据库,需要把 db 健康指示器放进 readiness 分组:

curl -s 127.0.0.1:8081/actuator/health
{"status":"UP"}
management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: readinessState,db

配置后,/actuator/health/readiness 会在数据库不可用时返回 DOWN,负载均衡据此把实例摘掉;/actuator/health/liveness 只反映进程状态,不会被数据库拖累。这个分组配置和 liveness、readiness 两个路径属于编排平台相关能力,未在本机实测,本机只验证了 /actuator/health 返回 UP。

健康检查还要注意超时。检查数据库时如果连接池已经满,探针自己也会卡住,编排系统等不到响应就判失败,表现和「数据库挂了」一样。给探针单独一条连接或短超时,别让它和业务抢池子。检查逻辑要足够轻,一条 select 1 就够,不要在里面跑统计查询。

另一个常见错误是把健康检查放在需要鉴权的路径下。探针不会带令牌,结果永远 401,编排系统以为服务没起来。白名单要显式包含健康检查路径,且只包含它,不要把整个 /actuator 都放开,env、heapdump 这些端点泄露的信息远超健康状态。

探测频率也要合理。每五秒一次是常见值,太频繁会给数据库增加无谓压力,太稀疏又会让故障发现变慢。探针超时通常设一到三秒,比业务超时短。三个数字(周期、超时、失败阈值)一起决定「多久判定不可用」,发布前要按业务能接受的故障窗口算一遍。

默认的 /actuator/health 只报进程状态,不能直接当 readiness 用。把数据库检查放进 readiness 分组,liveness 保持浅检查;否则数据库一抖,所有实例会被一起重启。

浅健康检查

只回进程状态,实现简单,不会被依赖拖垮,适合 liveness。代价是数据库或缓存挂了仍然报健康,流量继续打进来,故障从一个实例扩散到整个集群。

深健康检查

检查数据库、缓存等关键依赖,故障时主动摘流量,适合 readiness。代价是探针变慢,依赖短暂抖动就会影响可用容量,探测频率和超时要算清楚。

停机与流量:先摘流量,再等请求

发布的理想过程是:新实例启动,readiness 通过,加入负载均衡;旧实例从负载均衡摘除,等待正在处理的请求结束,再退出。顺序错了就会出现 502:旧实例已经被杀,新实例还没就绪,中间没有可用节点。

server.shutdown=graceful 让 Tomcat 停止接收新连接,并等待已接收的请求完成,等待上限由 spring.lifecycle.timeout-per-shutdown-phase 决定。这个值要大于最慢请求的耗时,但不能无限大,否则发布永远卡住。常见设置是 30 秒,长任务另算。

容器平台还需要一个 preStop 钩子,让「摘流量」和「发停止信号」之间有几秒间隔,给负载均衡更新节点状态的时间。没有这个间隔,停止信号到得太快,仍然会有少量请求打到正在退出的实例。这个配置属于 Kubernetes 能力,未在本机实测。

多实例还会放大数据库迁移的问题。每个实例启动都跑 Flyway,先到的拿锁执行,后到的等待。滚动发布时如果等待时间不够,后启动的实例会失败并反复重启。稳妥做法是把迁移拆成发布流水线里的独立步骤,应用启动时只校验版本,不执行变更。

回滚也要提前想好。旧代码配新表结构通常还能跑,新代码配旧表结构往往直接报错,所以数据库变更要做成「先加字段、再发代码、最后删旧字段」的多步过程,而不是一次改完。发布出问题时先回滚代码,再评估数据结构,不要两个一起回。

Tomcat 线程与连接数:别让排队变成超时

内嵌 Tomcat 有三个关键参数。server.tomcat.threads.max 是工作线程上限,默认 200;server.tomcat.accept-count 是当所有线程都忙时,等待队列的长度,默认 100;server.tomcat.max-connections 是同时保持的连接数上限,默认 8192。三个数一起决定高并发下的表现。

线程数不是越大越好。每个线程占栈内存,200 个线程大约占几百兆虚拟内存;线程太多上下文切换也变多。判断依据是请求里有多少阻塞等待:如果大量时间在等数据库或远程接口,线程可以适当多一些;如果是纯计算,线程数接近核心数就够。调到 400 以上要有压测数据支撑,不能凭「怕不够」。

accept-count 满了之后,新连接会被拒绝,客户端看到的是连接超时或 reset,而不是 503。这个现象容易被误判成网络问题。看 Tomcat 的线程和连接指标,或者直接观察 max-connections 是否打满,比抓包快。

前面有 Nginx 时,还要处理转发头。Nginx 用 proxy_set_header X-Forwarded-For 和 X-Forwarded-Proto 把真实 IP 和协议传进来,应用侧设置 server.forward-headers-strategy=framework 才会读取。不配的话,应用拿到的客户端 IP 全是代理地址,生成的跳转链接也可能是 http,导致重定向循环或混合内容。

location / {
    proxy_pass http://127.0.0.1:8081;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 35s;
}

proxy_read_timeout 要大于应用的优雅停机等待时间,否则代理会先断开,应用还在等请求结束,用户看到的是 504。两边超时要对齐,这是发布时 502 和 504 反复出现的一个常见原因。

JDK 21 还可以开启虚拟线程,把 spring.threads.virtual.enabled 设为 true,让阻塞 IO 不再占用平台线程。它适合大量等待外部接口的场景,但要注意 synchronized 块导致的线程固定,以及某些驱动的兼容性。默认不开,先用平台线程和压测数据说话,确认瓶颈在等待而不是 CPU,再考虑切换。

容器:内存、时区、编码

部署时的产物其实很少,理清之后就没那么容易漏文件。下面这四层就是运行现场的全部,镜像或服务器上不该再多出别的可变文件:

target/demo-0.0.1.jar:唯一的构建产物
外部配置:环境变量与命令行参数
logs/:滚动日志,挂载出去或交给采集
db/migration:跟着 jar 走的迁移脚本

容器不给内存上限,进程会按宿主机内存去算堆大小,可能申请到远超预期的内存,最后被系统杀掉。Java 在容器里应该显式设置堆上限,常见写法是 -XX:MaxRAMPercentage=75,让堆占容器限额的 75%,剩下的留给元空间、线程栈、直接内存和系统。

被 OOMKilled 时,应用日志往往什么都没有,因为进程是被内核直接杀掉的。退出码是 137,编排平台的事件里会写 OOMKilled。看到 137 不要先查代码内存泄漏,先确认限额和堆参数是否匹配;确认之后再用堆转储查泄漏。

时区要显式设置。容器默认常用 UTC,应用日志的时间和北京时间差八小时,定时任务也会按 UTC 触发。设置 TZ=Asia/Shanghai,并在 cron 表达式里显式写 zone,两处都做,避免一处漏掉。日志时间对不上,排查时序问题会非常痛苦。

文件编码同样要显式。读取上传的 CSV、导出文本、调用外部接口,都可能因为默认编码不同出现乱码。JVM 的 file.encoding 在 JDK 18 之后默认是 UTF-8,但依赖库不一定按这个来。读写文件时显式指定 StandardCharsets.UTF_8,别用平台默认值。

镜像本身也有成本。基础镜像带完整 JDK 会让镜像变大,带 JRE 又可能缺少诊断工具。常见折中是运行用精简 JRE,排查时另起一个带工具的临时容器连进去。不要把调试端口长期开在生产容器上。

上线后出问题先看什么

下面这张表按现象查。前四行是「服务看起来活着但实际不可用」,中间三行是资源和环境问题,最后两行是发布流程问题。每一条都给出第一个该看的位置,不要一上来就翻业务代码。

现象真实原因第一步查什么
健康检查 200,业务请求大量 500探针只查进程存活,没查数据库readiness 分组是否包含 db
容器反复重启,退出码 137内存超限被 OOMKilled编排平台事件里的 reason 和堆参数
日志时间比北京时间早八小时容器时区是 UTC看 TZ 环境和 cron 的 zone
中文内容写入后变成问号读写时用了平台默认编码看代码里有没有显式 UTF-8
改了环境变量但启动值没变命令行参数覆盖了环境变量看启动脚本和 /actuator/env
发布瞬间出现 502旧实例先停,新实例还没就绪看 readiness 和摘流顺序
高并发下连接被拒Tomcat 线程或 accept-count 打满看线程数、连接数和队列指标
日志文件几天就撑满磁盘没有滚动策略或上限看 logback 的 maxFileSize 和 totalSizeCap
拿到的客户端 IP 全是代理地址X-Forwarded-For 没传或没启用看 Nginx 配置和 forward-headers-strategy
多实例发布后部分实例起不来Flyway 迁移锁竞争看启动日志的 lock 等待和发布顺序

第一行最值得记住。健康检查不是「服务在不在」,而是「能不能安全地接流量」。只返回 UP 的探针会掩盖依赖故障,让故障从一个实例扩散到整个集群。把 readiness 做深,是上线前必须完成的一项,不是可选项。

边界与代价

单实例部署最简单,但任何重启都是几十秒的中断,也无法承受单机故障。多实例解决了可用性,代价是状态必须外置:会话要放 Redis,文件要放对象存储,定时任务要加锁或拆成独立进程。这些在前几篇都埋过伏笔,上线时一起兑现。

把健康检查做深也有代价。每次探针都查数据库,频繁探测会增加连接压力;数据库抖动时 readiness 失败,流量被摘走,可能造成容量不足。需要平衡探测频率和检查深度,常见做法是探针只做一次轻量查询,把更深的检查放到监控系统里,不在探针里做。

日志采集同样有成本。全量 JSON 日志加集中存储,费用随流量上涨;采样又会漏掉关键请求。折中是结构化日志加按级别分流,错误全量、调试采样。不要为了省存储把错误日志也采样,那等于主动放弃排查依据。

这些配置做完,服务才算「能上线」,但不等于「高可用」。高可用还要求容量评估、故障演练、回滚预案、数据库备份。它们不在这一篇的范围里,但要知道边界在哪:本文解决的是单服务部署的正确性,多服务协同和容灾是另一个层级的问题。

当天能自己验证的练习

  1. 用同一个 jar,分别以默认配置和 --server.port=9090 启动,确认命令行参数覆盖 yml,并用 /actuator/env 找到实际值。
  2. 把 logging.file.name 指向一个目录,写足够多日志,确认滚动文件按大小切分,并检查总占用是否受 totalSizeCap 限制。
  3. 关闭数据库或改错连接地址,分别请求 /actuator/health 和 readiness 路径,对比两者返回,理解浅探针和深探针的区别。
  4. 提交一个耗时 10 秒的请求,然后停服务,观察优雅停机是否等它完成;再把超时改成 2 秒,对比行为。
  5. 用 PowerShell 设置 TZ 和 APP_SECRET 启动 jar,打印当前时间和密钥是否生效,理解环境变量如何进入应用。

小结

三句话收束:配置从外部注入,命令行高于环境变量高于 yml,密钥不进仓库;健康检查要分 liveness 和 readiness,readiness 必须检查真正的依赖;日志滚动、优雅停机、Tomcat 线程和容器内存上限,是上线前必须逐项确认的清单。

这六篇从空目录走到上线,覆盖了起步、请求链路、数据、鉴权、后台任务和部署。接下来可以回到语言方向补基础,或者横向看数据库与工程化主题。语法决定你能不能写出代码,这些边界决定代码能不能在真实流量下活下去。