JavaWeb 项目从本地跑通到真正上线中间隔着的往往不是代码本身而是一整套环境一致性、进程管理、端口映射和资源隔离的琐碎问题。我见过太多团队在本地localhost:8080一切正常一上服务器就卡在 JDK 版本对不上、Tomcat 启动脚本权限不足、防火墙没放行、日志找不到位置这些地方。用 Docker 把 JavaWeb 项目部署到云服务器本质上就是把这些“环境变量”全部固化进镜像让“本地能跑”和“线上能跑”变成同一件事。这篇内容面向的是已经能写出可运行 JavaWeb 项目、但对容器化部署还停留在“听说过 docker run”阶段的开发者也适合那些被传统部署方式反复折磨、想换一套更可控流程的运维同学。我会从整体设计思路讲到镜像构建、容器编排、反向代理、日志与排障把每一步为什么这么做、参数怎么算、坑在哪里都摊开说清楚你照着抄作业就能落地。1. 整体部署方案设计与选型考量1.1 为什么 JavaWeb 项目值得用 Docker 来部署传统 JavaWeb 部署的典型路径是服务器装 JDK、装 Tomcat、把 war 包丢进 webapps、改 server.xml、配环境变量、写启动脚本、再配个开机自启。这套流程本身没错但它有一个致命弱点——环境状态是“手工累积”出来的。今天你为了排查一个问题升级了 JDK明天另一个项目又依赖旧版本服务器上的状态就越来越不可复现。Docker 的价值不在于“新潮”而在于它把 JDK 版本、Tomcat 版本、时区、字符集、JVM 参数、应用包全部声明在一份 Dockerfile 里镜像构建出来的那一刻运行环境就被冻结了。从资源角度看JavaWeb 项目通常不是 CPU 密集型而是内存敏感型。一个 Spring Boot 打成的可执行 jar空跑就要占 200MB 到 400MB 堆外加堆内内存再加上 Tomcat 线程栈、元空间一台 2GB 内存的入门云服务器如果不做限制很容易被 JVM 默认的堆大小策略撑爆。Docker 的-m内存限制配合 JVM 的-XX:MaxRAMPercentage能让容器内存和 JVM 堆之间形成可控关系这是传统部署很难精细做到的。另外容器天然适合“一个容器一个进程”的模型应用挂了容器就退出配合重启策略能实现比手写守护脚本更可靠的进程管理。还有一点常被忽略部署回滚。传统方式回滚靠备份 war 包和手动替换Docker 方式下每个镜像都有 tag回滚就是把容器重新指向旧 tag几十秒完成而且回滚后的环境和当初上线时完全一致。这个能力在出故障的深夜价值极高。1.2 镜像构建方式的选择Dockerfile 手写还是插件生成JavaWeb 项目打镜像有两条主流路线。第一条是手写 Dockerfile基于openjdk或eclipse-temurin基础镜像把 jar 或 war 拷进去写 ENTRYPOINT。第二条是用 Maven 或 Gradle 插件如 jib、spring-boot-maven-plugin 的 build-image自动生成镜像。我的建议是生产环境优先手写 Dockerfile。原因很实际——插件生成的镜像层次结构不透明基础镜像版本、JVM 参数、时区设置往往被封装在插件配置里出问题时排查成本高而手写 Dockerfile 每一行都看得见改起来直接。不过手写也有代价就是要自己处理基础镜像选择。这里有个关键决策用完整 JDK 镜像还是 JRE 镜像。编译阶段需要 JDK运行阶段只需要 JRE。如果项目是 Spring Boot 可执行 jar运行阶段用eclipse-temurin:17-jre这类镜像即可体积能比 JDK 镜像小 100MB 以上。如果是传统 war 包部署到外部 Tomcat那就直接用tomcat:9-jre17这类官方镜像把 war 放进webapps目录。多阶段构建multi-stage build是更优雅的方案第一阶段用 Maven 镜像编译打包第二阶段只拷产物到 JRE 镜像最终镜像里不含源码和构建工具既小又安全。1.3 云服务器上的容器编排单机 Docker 还是 Compose很多教程一上来就讲 Kubernetes但对绝大多数中小型 JavaWeb 项目来说一台云服务器加 Docker Compose 已经完全够用。Compose 的核心价值是把“应用容器 数据库容器 反向代理容器”的关系用一份 YAML 声明出来docker compose up -d一条命令拉起整套服务网络、卷、依赖顺序都在文件里。相比一堆docker run命令Compose 的可维护性高一个量级。选型上我的判断标准很简单单机部署、服务数量在个位数、没有跨节点调度需求就用 Compose。K8s 带来的运维复杂度etcd、网络插件、Ingress 控制器在小规模场景下是负收益。Compose 里要重点设计的是网络模式——默认的 bridge 网络下容器之间可以用服务名互相访问这比记 IP 地址可靠得多数据卷则用来持久化数据库数据和上传文件目录避免容器重建丢数据。2. 核心细节解析与实操要点2.1 基础镜像与 JDK 版本的对齐逻辑镜像选型的第一原则是和项目编译时的 JDK 大版本严格一致。项目用 JDK 17 编译运行镜像就必须是 17用 11 跑 17 编译的字节码会直接抛UnsupportedClassVersionError。我习惯在项目pom.xml里用maven.compiler.source和target锁定版本然后在 Dockerfile 里用同一个大版本的基础镜像形成“编译期和运行期版本声明在两处但值一致”的约束。基础镜像的具体选择上eclipse-temurin是目前社区维护活跃、更新及时的选择openjdk官方镜像在较新版本上已经不再推荐。如果公司有内部镜像仓库建议把基础镜像同步到内网避免构建时因为外网拉取失败卡住。另外要注意镜像的 OS 变体-alpine后缀的镜像体积小但用的是 musl libc某些依赖 glibc 的本地库比如某些加密库、图像处理库会出问题JavaWeb 项目如果用了 JNI 调用的组件老老实实用默认的 Debian 系镜像更稳。2.2 时区、字符集与 JVM 参数的容器化处理这三个东西是 JavaWeb 项目上线后“看起来正常但数据不对”的高发区。时区不对日志时间戳和数据库写入时间差 8 小时字符集不对中文参数传到后端变乱码JVM 参数不设容器内存被堆撑爆触发 OOM Kill。处理方式要写进 Dockerfile 和启动命令里。时区通过环境变量TZAsia/Shanghai设置同时在 Dockerfile 里装tzdata并做ln -sf软链双保险。字符集方面现代 JDK 默认file.encoding已经是 UTF-8但为了保险可以在 JVM 参数里显式加-Dfile.encodingUTF-8。JVM 内存参数是重点容器里 JVM 默认会读取 cgroup 内存限制JDK 8u191 之后支持但更稳妥的做法是显式指定-XX:MaxRAMPercentage75.0意思是堆最大占容器内存的 75%剩下 25% 留给元空间、线程栈、直接内存和系统开销。这个比例不是拍脑袋是大量实践后的经验值——低于 70% 浪费内存高于 80% 容易在流量高峰时被 OOM Kill。2.3 端口映射与反向代理的层次设计JavaWeb 项目容器内监听 8080对外暴露有两种做法直接把宿主机 8080 映射到容器 8080或者前面加一层 Nginx 做反向代理。生产环境强烈建议加 Nginx。原因有三第一Nginx 处理静态资源、SSL 终止、gzip 压缩比 Tomcat 高效第二应用容器不需要直接暴露公网端口只暴露给 Nginx 所在的 Docker 网络安全性更好第三后续要做多实例负载均衡时Nginx 的 upstream 配置改起来比动容器端口映射方便。端口映射的写法上-p 8080:8080是宿主机端口在前、容器端口在后这个顺序新手经常搞反。如果走 Nginx 反代应用容器甚至可以不写ports只在 Compose 网络里被 Nginx 通过服务名访问这样应用端口完全不对外攻击面最小。2.4 数据持久化与配置外置的边界容器是无状态的但 JavaWeb 项目往往有状态上传的文件、生成的报表、本地缓存、日志。这些必须挂载到宿主机卷或命名卷上否则容器一重建全丢。我的划分原则是代码和依赖进镜像数据和配置出容器。配置文件数据库连接、第三方密钥通过环境变量或挂载外部配置文件注入不打进镜像这样同一份镜像可以在测试和生产环境复用只换环境变量。日志的处理要特别注意。容器内应用把日志写到/app/logs通过卷挂载到宿主机既方便排查又不会因为容器删除丢失。更规范的做法是让应用日志输出到 stdout由 Docker 的日志驱动统一收集但这需要改日志配置老项目迁移时成本较高挂载卷是更平滑的过渡方案。3. 完整实操流程与关键环节实现3.1 项目打包与 Dockerfile 编写假设项目是一个 Spring Boot 打成的可执行 jar名为demo-app.jar监听 8080。先在项目根目录确认mvn clean package能产出 jar然后写 Dockerfile。我用的多阶段构建版本如下# 第一阶段构建 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn clean package -DskipTests -B # 第二阶段运行 FROM eclipse-temurin:17-jre ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone WORKDIR /app COPY --frombuilder /build/target/demo-app.jar app.jar RUN mkdir -p /app/logs EXPOSE 8080 ENTRYPOINT [java, \ -XX:MaxRAMPercentage75.0, \ -Dfile.encodingUTF-8, \ -Duser.timezoneAsia/Shanghai, \ -jar, /app/app.jar]这里有几个设计点值得说。mvn dependency:go-offline单独一层是为了利用 Docker 层缓存——只要pom.xml没变依赖下载这层就命中缓存后续改代码重新构建时省掉几分钟的依赖下载时间。COPY src放在依赖之后也是同样的缓存逻辑。运行阶段用 JRE 镜像而不是 JDK最终镜像体积能控制在 250MB 左右。ENTRYPOINT用数组形式exec form保证 java 进程是容器内的 1 号进程能正确接收docker stop发来的 SIGTERM 信号实现优雅停机。如果项目是传统 war 包部署到 TomcatDockerfile 会简单很多FROM tomcat:9-jre17 ENV TZAsia/Shanghai RUN rm -rf /usr/local/tomcat/webapps/* COPY target/demo.war /usr/local/tomcat/webapps/ROOT.war EXPOSE 8080把 war 命名为ROOT.war是为了让应用直接挂在根路径省去访问时带项目名的麻烦。rm -rf webapps/*是清掉 Tomcat 自带的示例应用减少攻击面和启动时间。3.2 镜像构建与本地验证在项目根目录执行构建docker build -t demo-app:1.0.0 .构建完成后先在本地跑一遍验证镜像本身没问题docker run -d --name demo-test -p 8080:8080 \ -e SPRING_PROFILES_ACTIVEdev \ demo-app:1.0.0然后docker logs -f demo-test看启动日志确认 Spring Boot 的 “Started Application” 出现再curl localhost:8080/actuator/health如果引入了 actuator确认健康检查通过。这一步的意义在于把“镜像问题”和“服务器环境问题”隔离开——本地镜像跑不通就别急着往服务器推。3.3 云服务器环境准备与镜像传输服务器上要装的是 Docker Engine 和 Compose 插件。以主流 Linux 发行版为例用官方脚本安装最省事但生产环境我更倾向用包管理器安装固定版本避免自动升级带来意外。装完后执行docker version和docker compose version确认两者都可用并把当前用户加入 docker 组避免每条命令都加 sudo。镜像传到服务器有两种方式。第一种是在服务器上直接git clone项目再docker build适合服务器能访问代码仓库的场景缺点是构建消耗服务器 CPU 和内存小内存机器构建时可能卡顿。第二种是本地构建好后docker save成 tar 包scp传上去再docker load适合服务器构建能力弱或网络受限的场景# 本地导出 docker save demo-app:1.0.0 -o demo-app-1.0.0.tar # 传输后服务器导入 docker load -i demo-app-1.0.0.tar我一般用第二种因为构建在本地开发机上更快服务器只负责运行职责清晰。3.4 Compose 编排文件编写与启动服务器上建一个部署目录比如/opt/demo-app里面放docker-compose.yml和.env文件。Compose 文件示例services: app: image: demo-app:1.0.0 container_name: demo-app restart: unless-stopped environment: - SPRING_PROFILES_ACTIVEprod - SPRING_DATASOURCE_URLjdbc:mysql://db:3306/demo?useUnicodetruecharacterEncodingutf8 - SPRING_DATASOURCE_USERNAMEdemo - SPRING_DATASOURCE_PASSWORD${DB_PASSWORD} volumes: - ./logs:/app/logs - ./uploads:/app/uploads networks: - demo-net depends_on: db: condition: service_healthy deploy: resources: limits: memory: 1g db: image: mysql:8.0 container_name: demo-db restart: unless-stopped environment: - MYSQL_ROOT_PASSWORD${DB_ROOT_PASSWORD} - MYSQL_DATABASEdemo - MYSQL_USERdemo - MYSQL_PASSWORD${DB_PASSWORD} - TZAsia/Shanghai volumes: - ./mysql-data:/var/lib/mysql networks: - demo-net healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 10s timeout: 5s retries: 5 nginx: image: nginx:1.25 container_name: demo-nginx restart: unless-stopped ports: - 80:80 - 443:443 volumes: - ./nginx/conf.d:/etc/nginx/conf.d:ro - ./nginx/certs:/etc/nginx/certs:ro networks: - demo-net depends_on: - app networks: demo-net: driver: bridge这份文件里有几个关键设计。restart: unless-stopped保证服务器重启或容器异常退出后自动拉起比手写 systemd 服务省事。depends_on配合condition: service_healthy让应用等数据库健康检查通过再启动避免应用启动时连不上库反复重试。deploy.resources.limits.memory限制应用容器最多 1GB配合前面 JVM 的MaxRAMPercentage75堆最大约 768MB留足余量。数据库数据挂载到./mysql-data容器重建数据不丢。密码通过.env文件注入.env不提交到代码仓库。Nginx 配置放在nginx/conf.d/default.confserver { listen 80; server_name _; location / { proxy_pass http://app: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; } }proxy_pass http://app:8080里的app就是 Compose 里的服务名Docker 内置 DNS 会解析到应用容器 IP这就是前面说的“容器间用服务名访问”的好处。X-Forwarded-For等头是让后端能拿到真实客户端 IP否则应用日志里全是 Nginx 容器的内网 IP。启动整套服务cd /opt/demo-app docker compose up -d docker compose ps docker compose logs -f appdocker compose ps看各容器状态是否都是 Uplogs -f app盯应用启动日志。全部正常后浏览器访问服务器公网 IP 的 80 端口应该能看到应用首页。3.5 防火墙与安全组放行这一步是新手最容易漏的。云服务器通常有两层网络控制云厂商控制台的安全组和服务器本机的防火墙firewalld 或 ufw。安全组里要放行 80 和 443 端口的入站规则本机防火墙也要对应放行。应用容器的 8080 端口因为只在内网被 Nginx 访问不需要对公网放行这正是前面加 Nginx 的安全收益。数据库的 3306 更是绝对不能对公网开放Compose 网络里它只对demo-net内的容器可见。4. 常见问题排查与避坑经验实录4.1 容器启动即退出从日志和退出码定位容器docker compose ps显示Exited (1)是最常见的情况。排查顺序是先docker compose logs app看应用日志如果日志里什么都没有说明 JVM 根本没起来问题在镜像或启动命令如果有日志但报错按报错内容定位。几个高频原因UnsupportedClassVersionError是 JDK 版本不匹配Port already in use是宿主机端口被占Connection refused连数据库失败是网络或数据库未就绪No such file是 jar 路径写错。退出码也有信息量。退出码 137 表示被 SIGKILL 杀掉通常是内存超限被 OOM Killer 干掉要检查docker inspect里的OOMKilled字段和内存限制是否过小。退出码 143 是收到 SIGTERM 正常退出可能是docker stop或重启策略触发。我习惯在排查时先跑docker inspect 容器名 --format {{.State.ExitCode}} {{.State.OOMKilled}}一眼看出是不是内存问题。4.2 应用能启动但访问 502反向代理链路排查Nginx 返回 502 Bad Gateway说明 Nginx 活着但连不上后端。排查链路是先在 Nginx 容器里curl http://app:8080测试能否通不通则问题在应用容器或网络通了但外部访问 502则问题在 Nginx 配置或端口映射。常见原因包括proxy_pass里服务名写错、应用容器没加入同一个网络、应用监听的是127.0.0.1而不是0.0.0.0。最后这个特别隐蔽——Spring Boot 默认监听所有网卡但如果配置文件里写了server.address127.0.0.1容器外部就访问不到必须改成0.0.0.0或不配。4.3 中文乱码与时区错乱的组合排查中文乱码要分三层看请求参数乱码、响应内容乱码、数据库存储乱码。请求参数乱码检查 Nginx 是否透传了正确的 Content-Type以及应用是否配置了server.servlet.encoding.charsetUTF-8数据库乱码检查连接串里的characterEncodingutf8和数据库本身的字符集。时区问题则要同时检查容器TZ环境变量、JVM 的user.timezone参数、数据库的time_zone设置三者必须一致否则会出现“日志时间对但数据库时间差 8 小时”这种诡异现象。4.4 常见问题速查表现象可能原因排查命令解决方向容器 Exited(1)JDK 版本不匹配 / 启动命令错误docker compose logs app对齐基础镜像与编译版本容器 Exited(137)内存超限被 OOM Killdocker inspect --format {{.State.OOMKilled}}调大内存限制或降 MaxRAMPercentage外部访问 502Nginx 连不上后端docker exec nginx curl http://app:8080检查网络、服务名、监听地址中文乱码字符集配置不一致检查连接串与 encoding 配置统一 UTF-8时间差 8 小时时区未统一docker exec app date统一 TZ 与 JVM 时区数据丢失未挂载数据卷docker inspect看 Mounts补 volumes 配置构建慢依赖层缓存失效观察构建输出层命中调整 COPY 顺序4.5 几条踩坑换来的实操心得第一条不要在 Dockerfile 里用ADD解压远程 tar 包ADD的隐式行为多用COPY加显式RUN tar更可控。第二条镜像 tag 永远不要用latest生产环境用语义化版本号回滚时才知道该指向哪个。第三条Compose 的.env文件权限设成 600里面是数据库密码别让同服务器其他用户读到。第四条定期docker system prune清理悬空镜像不然服务器磁盘几个月就被旧镜像占满我见过一台机器攒了 40GB 无用镜像导致磁盘告警。第五条应用日志一定要配滚动策略挂载到宿主机的日志文件如果无限增长迟早把磁盘写满Spring Boot 的logging.logback.rollingpolicy.max-file-size和max-history要设上。还有一条关于优雅停机的docker stop默认给容器 10 秒宽限期如果应用关闭时需要处理完在途请求这个时间可能不够可以在 Compose 里配stop_grace_period: 30s同时确保 JVM 的 shutdown hook 能正常执行。这个细节平时看不出价值但在发布时如果有长事务或大批量任务在跑能避免请求被硬切断。整套流程跑顺之后日常发布就变成三步本地docker build打新 tag、docker save传输、服务器docker compose up -d滚动替换。回滚就是把 Compose 里的镜像 tag 改回上一个版本再up -d一分钟内完成。我个人在实际操作中的体会是容器化部署前期搭建确实比传统方式多花半天时间但这份投入会在第一次线上故障回滚时全部赚回来——那种“改个 tag 就能回到已知良好状态”的踏实感是手工部署给不了的。