自建镜像 on Liangweidong's blog

JDK 自建镜像实战：从 JDK 8 到 JDK 21 的三大流派

Sun, 15 Dec 2024 00:00:00 +0800

在企业里跑 Java 容器，最常见的一条路是 docker pull openjdk:8 然后把 jar 塞进去。但稍微严肃一点的场景——生产环境要可控、要带字体、要带时区、要 wait 启动——都会走向自建 JDK 基础镜像这条路。这篇把 5 年间从 JDK 8u333 一直到 JDK 21 的演进整理一遍，把踩过的坑一次说清楚。

阅读对象：需要维护 Java 应用基础镜像的运维 / 后端工程师 覆盖范围：JDK 8u333 / 8u351 / 8u371 / 8u381 / 8u401（Alpine）/ JDK 21 + Debian / Ubuntu / Alpine 三大基础镜像流派 + wait-for-it 启动 + 中文乱码 + 字体 + 时区 + TLS 1.0/1.1 兼容

一、为什么需要自建 JDK 基础镜像

官方 openjdk 镜像有两个"够用但不舒服"的地方：

时区不是上海：容器里 date 永远差 8 小时，日志时间戳对不上排查窗口特别痛苦
没有字体：用到图形验证码、PDF 导出、POI 操作 Excel 的应用，直接 OOM 崩溃
没有 wait.sh：微服务启动顺序错乱，A 服务没等 B 服务的注册中心起来就启动
没有 tzdata / curl / iputils-ping 等常用工具：调试时 ping / nslookup 找不到，只能 exec 进去手动装

自建基础镜像的本质是：把这些"跑生产迟早要的东西"预先 bake 进去，业务镜像只关心应用本身。

When to use：

一个团队有 ≥ 3 个 Java 微服务需要部署 → 必须自建 JDK 基础镜像

公司内部有"安全合规"要求，必须用某特定 JDK 版本 / 特定 OS → 自建

单个临时 demo → 没必要，openjdk:8-jre-slim 凑合用

二、Debian 流派：JDK 8u371 / 8u381

Debian 11 是 JDK 8 / 11 时代最稳的基础镜像——包管理 apt 完善、镜像体积可控、对 glibc 应用兼容好。

2.1 基础 Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


FROM debian:11.8
LABEL maintainer="ops@example.com"
WORKDIR /
RUN mkdir /usr/local/jdk && chmod 777 /usr/local/jdk
ADD jdk-8u381-linux-x64.tar.gz /usr/local/jdk
ENV JAVA_HOME /usr/local/jdk/jdk1.8.0_381
ENV CLASSPATH=$JAVA_HOME/bin:$JAVA_HOME/lib:$JAVA_HOME/jre/lib
ENV PATH=.:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH
ENV LANG C.UTF-8
ENV TZ=Asia/Shanghai DEBIAN_FRONTEND=noninteractive
RUN ln -fs /usr/share/zoneinfo/${TZ} /etc/localtime \
 && echo ${TZ} > /etc/timezone \
 && dpkg-reconfigure --frontend noninteractive tzdata \
 && rm -rf /var/lib/apt/lists/*

关键点：

LABEL maintainer 用部门邮箱而非个人邮箱，避免人员流动留下旧地址
ENV LANG C.UTF-8 解决Java 应用中文乱码最常见原因
dpkg-reconfigure tzdata 让 java.util.Date 也走上海时区（不是只改了 /etc/localtime）
末尾 rm -rf /var/lib/apt/lists/* 必须保留，否则镜像会大 100MB+

2.2 镜像版本演进

实战中一个 JDK 8u381 基础镜像可能要经过 5~6 次迭代：

Tag	增加的能力	触发场景
`8u381`	基础 JDK + 时区	第一次发版
`8u381-2`	+ 中文字体（fontconfig）	应用导出 PDF 报错
`8u381-3`	+ `dmidecode`	arthas / sigar 读硬件信息
`8u381-4`	+ TLS 1.0 / 1.1 启用	接入老客户的 HTTPS 服务
`8u381-5`	合并 -3 和 -4 全部能力	版本归一
`8u381-6`	+ skywalking agent + arthas-boot.jar	接入分布式追踪
`8u381-7`	+ 第三方 SDK（硬盘录像机 .so）	视频监控项目
`8u381-8`	+ mysqldump / mysql 客户端	容器内做 DB 备份

经验法则：每加一个能力就 +1 版本号，永远不要覆盖旧 tag——历史容器用的就是旧镜像，回头调试时还能拉下来。

2.3 时区必须做两件事

只改 /etc/localtime 不够。完整做法：

1
2
3
4
5
6


# 1. 软链时区文件
ln -fs /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
# 2. 写 timezone 文件（apt 工具会读这个）
echo "Asia/Shanghai" > /etc/timezone
# 3. 让 glibc 知道
dpkg-reconfigure --frontend noninteractive tzdata

第 3 步会更新 /etc/localtime 并设置内部状态。不执行第 3 步时 date 命令对，new Date() 错——Java 用的是 glibc 内部状态。

2.4 wait-for-it：解决启动顺序

微服务 xjAuth 依赖 nacos 先启动，直接 depends_on 没用——Docker 只控制启动顺序，不等待端口。

引入 wait.sh（基于 wait-for-it.sh）：

1
2
3
4


docker run -d --name xjAuth \
 --network_mode: "host" \
 <your-public-ip>:13001/base/lwd/jdk:8u381 \
 /wait.sh localhost:8848 -t 0 -- java -jar /jar/xjrsoft-auth.jar

wait.sh 会先阻塞直到 localhost:8848 可达，再 exec 真正启动命令。-t 0 表示无限等待（生产推荐，避免临时网络抖动让容器直接退出）。

实战日志：

1
2


wait.sh: waiting for localhost:8848 without a timeout
wait.sh: localhost:8848 is available after 23 seconds

三、Ubuntu 流派：JDK 8u333 / 8u351

Ubuntu 适合老系统延续——ubuntu:22.10 / 22.04 都有官方仓库支持。

1
2
3
4
5
6
7
8


FROM ubuntu:22.10
MAINTAINER ops@example.com
WORKDIR ./usr/local
RUN mkdir jdk && chmod 777 /usr/local/jdk
ADD jdk-8u351-linux-x64.tar.gz /usr/local/jdk
ENV JAVA_HOME /usr/local/jdk/jdk1.8.0_351
ENV CLASSPATH=$JAVA_HOME/bin:$JAVA_HOME/lib:$JAVA_HOME/jre/lib
ENV PATH=.:$JAVA_HOME/bin:$JAVA_HOME/jre/bin:$PATH

注意：Ubuntu 基础镜像默认没有 ca-certificates——HTTPS 请求会报 x509: certificate signed by unknown authority。要么 apt install -y ca-certificates，要么用 wget --no-check-certificate（不推荐）。

四、Alpine 流派：JDK 8u401（极致小）

Alpine 用 musl libc 而非 glibc，镜像只有 5MB 级别——但 JDK 跑在 Alpine 上要绕开 glibc 依赖。

4.1 坑：Alpine 自带 musl，Java 跑不动

解决方案：装 sgerrand/alpine-pkg-glibc 包。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


FROM alpine:v3.19.1
LABEL author="ops"
WORKDIR /opt
# 1. 换 Alpine 源到清华
RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories
RUN apk update && apk upgrade
# 2. 装 ca-certificates
RUN apk --no-cache --upgrade add ca-certificates
# 3. 装 glibc（关键！）
ADD sgerrand.rsa.pub /etc/apk/keys/sgerrand.rsa.pub
COPY glibc-2.35-r1.apk glibc-bin-2.35-r1.apk glibc-dev-2.35-r1.apk glibc-i18n-2.35-r1.apk /opt/
RUN apk add --no-cache --force-overwrite glibc-2.35-r1.apk \
 glibc-bin-2.35-r1.apk glibc-dev-2.35-r1.apk glibc-i18n-2.35-r1.apk \
 && rm -f glibc-*.apk
# 4. 装时区数据
RUN apk add --no-cache tzdata && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
# 5. 装中文字体（alpine 3.15+ 必需，否则图形验证码 OOM）
RUN apk add --no-cache fontconfig
# 6. 解压 JDK
ADD jdk-8u401-linux-x64.tar.gz /opt
# 7. 环境变量
ENV JAVA_HOME=/opt/jdk1.8.0_401
ENV JRE_HOME=/opt/jdk1.8.0_401/jre
ENV CLASS_PATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar:$JRE_HOME/lib
ENV PATH=$PATH:$JAVA_HOME/bin:$JRE_HOME/bin
# 8. 软链 ld-linux 解决库文件报错
RUN ln -sf /usr/glibc-compat/lib/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2
CMD ["java", "-version"]

4.2 镜像大小对比

基础镜像	JDK 8u401 后大小
`debian:11.8` + JDK 8u381	~ 800 MB
`ubuntu:22.10` + JDK 8u351	~ 750 MB
`alpine:v3.19.1` + JDK 8u401 + glibc	~ 350 MB

Alpine 省了一半体积，冷启动时间和拉取速度都更友好——但 apk add 包要慎重（musl 与 glibc 二进制不兼容）。

五、JDK 21：新时代的开端

JDK 21 是 LTS（2023-09 发布，支持到 2031 年），如果新项目可以直接上 21。

5.1 Liberica JDK 21 Dockerfile

Liberica 是 BellSoft 出品的 OpenJDK 发行版，支持 alpine 和 glibc 两种打包，省心：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


FROM debian:12.12
LABEL maintainer="ops@example.com"
LABEL description="Debian 12.12 + BellSoft Liberica JDK 21"

RUN mkdir /usr/local/jdk && chmod 755 /usr/local/jdk
ADD bellsoft-jdk21.0.5+11-linux-amd64-full.tar.gz /usr/local/jdk
ENV JAVA_HOME /usr/local/jdk/jdk-21.0.5-full
ENV PATH=$JAVA_HOME/bin:$PATH:.
ENV LANG C.UTF-8
ENV TZ=Asia/Shanghai DEBIAN_FRONTEND=noninteractive

RUN sed -i 's|URIs: http://deb.debian.org/debian|URIs: http://mirrors.ustc.edu.cn/debian|g' /etc/apt/sources.list.d/debian.sources \
 && apt clean \
 && apt update \
 && apt install -y --no-install-recommends fontconfig \
 && ln -snf /usr/share/zoneinfo/${TZ} /etc/localtime \
 && echo ${TZ} > /etc/timezone \
 && fc-cache -fv \
 && rm -rf /var/lib/apt/lists/* \
 && java -version && javac -version

WORKDIR /app

5.2 JDK 21 的 Virtual Thread

JDK 21 的最大亮点是 Virtual Thread（虚拟线程，JEP 444）——轻量级线程，百万级并发不再是梦想：

1
2
3
4
5
6
7


// 旧写法：平台线程
Thread.startVirtualThread(() -> {
 handleRequest(request);
});

// Spring Boot 3.2+ 自动集成
spring.threads.virtual.enabled=true

实战效果：同等 QPS 下，线程数从 200 降到 50，P99 延迟下降 30%。这是 JDK 21 值得升级的核心动力。

六、典型坑位

6.1 中文乱码三连击

症状：Java 应用读 CSV 出现 ???、写 MySQL 中文 ?、导出 PDF □。

排查顺序：

1
2
3
4
5
6
7
8


# 1. 看 locale
docker exec -it app locale
# 期望：C C.UTF-8 POSIX en_US.utf8
# 2. 看 JDK 编码
docker exec -it app java -XshowSettings:properties -version 2>&1 | grep encoding
# 期望：file.encoding = UTF-8
# 3. 看 MySQL 客户端字符集
docker exec -it app locale -a | grep -i utf

根治方案：

Dockerfile 加 ENV LANG C.UTF-8
JVM 参数加 -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8
MySQL 连接串加 useUnicode=true&characterEncoding=UTF-8

6.2 TLS 1.0 / 1.1 兼容

症状：对接老客户的 HTTPS 接口报 SSLHandshakeException。

原因：JDK 8u381 默认 jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, ...，TLS 1.0/1.1 被禁用。

修复：

1
2
3
4
5
6


vim $JAVA_HOME/jre/lib/security/java.security
# 找到 jdk.tls.disabledAlgorithms
# 删掉 TLSv1, TLSv1.1
jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, \
 DH keySize < 1024, EC keySize < 224, anon, NULL, \
 include jdk.disabled.namedCurves

注意：TLS 1.0/1.1 已不安全，只在必须对接老客户时开。新项目应该让客户升级到 TLS 1.2+。

6.3 容器内 `ping` / `ip` 找不到

Debian 镜像默认最小化，连 ping 都没有：

1

RUN apt install -y iputils-ping iproute2 dnsutils curl wget

七、Jenkins Agent 镜像

CI/CD 场景需要 JNLP 客户端连 Jenkins Master：

1
2
3
4
5


FROM dockerhub.example.com/base/jenkins/inbound-agent:latest-jdk21
USER root
COPY jenkins /usr/local/bin/jenkins
RUN chmod +x /usr/local/bin/jenkins
USER jenkins

配套 Jenkinsfile：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


pipeline {
 agent {
 kubernetes {
 cloud 'k8s'
 inheritFrom 'jnlp-slave'
 namespace 'kube-ops'
 }
 }
 environment {
 time_now = createVersion()
 }
 tools {
 jdk 'jdk1.8'
 maven 'maven3.9.6'
 }
 stages {
 stage("get releaseHost") {
 steps {
 script {
 sh 'jenkins -h'
 }
 }
 }
 }
}
def createVersion() {
 return new Date().format("yyyy-MM-dd'T'HH-mm-ss", TimeZone.getTimeZone("Asia/Shanghai")) + "_${env.BUILD_ID}"
}

八、镜像分发：自建 vs Docker Hub

方案	适用场景	优缺点
自建 Harbor	企业内网 / 等保合规	速度快、可扫描 CVE、可审计；但要维护 Harbor
Docker Hub 私有仓库	小团队 / 个人	零运维；但国内拉取慢、可能泄露
阿里云容器镜像 ACR	国内企业	国内快、便宜；但要绑定阿里云账号

生产推荐：Harbor + 跨地域复制。构建在 北方节点，自动同步到 华东 / 华南 / 华北 三个 Harbor。

九、构建与分发完整命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 1. 构建
docker build -f Dockerfile -t dockerhub.example.com/base/lwd/jdk:8u381-2 .

# 2. 验证
docker run --rm dockerhub.example.com/base/lwd/jdk:8u381-2 java -version
docker run --rm dockerhub.example.com/base/lwd/jdk:8u381-2 date

# 3. 推 Harbor
docker login -u admin -p {{REDACTED}} dockerhub.example.com
docker push dockerhub.example.com/base/lwd/jdk:8u381-2

# 4. 离线分发（内网或保密环境）
docker save dockerhub.example.com/base/lwd/jdk:8u381-2 > jdk8u381-2.tar
docker load < jdk8u381-2.tar

十、最佳实践清单

版本号带具体 patch 号：8u381 而非 8，便于回溯
基础镜像锁版本：debian:11.8 而非 debian:latest，避免某天突然构建失败
时区三步走：软链 + timezone 文件 + dpkg-reconfigure
wait 脚本必装：微服务架构 90% 的"启动失败"都是顺序问题
字体必装：Alpine 3.15+、Debian 12+ 都需要 apt install fontconfig
TLS 兼容性单独 tag：避免一个基础镜像同时承担新客户和老客户的兼容要求
MySQL 客户端单独 tag：不是所有 Java 应用都需要它，按需装

2024+ 视角补充

本文写于 2024-12，2025-2026 期间 JDK 自建镜像关键演进：

JDK 21 / 25 主流化：JDK 25（2025-09 发布）已成为新 LTS（支持到 2033+）——2025+ 新项目强烈推荐 JDK 25
JDK 8u421+ / 8u431+ 维护更新：Oracle 仍给付费用户提供 JDK 8 季度更新；开源社区转向 Eclipse Temurin 8u432+（2025+ 仍维护）
Eclipse Temurin 17 / 21 / 25：2024-2026 容器首选——多平台 + LTS 支持 + 商业保障
BellSoft Liberica JDK 21+：Alpine / glibc / CRaC 三种打包——云原生首选
GraalVM JDK 21+：AOT 编译 + Native Image + Truffle 多语言——Serverless 首选
Azul Zulu Prime 17 / 21：C4 Pauseless GC（亚毫秒 GC）——金融 / 电信级延迟敏感
Amazon Corretto 21+：AWS 维护，生产级 LTS——AWS 用户首选
**多架构构建（ARM64 + AMD64）**已成 2024+ 标准
CRaC（Coordinated Restore at Checkpoint）：JDK 17 / 21 实验特性，JVM 启动 < 10ms
JLink 定制 JRE：Spring Boot 3.x + JLink 50MB 级别镜像

实战建议（2025-2026 视角）：

新项目 → JDK 21 LTS / 25 LTS + Eclipse Temurin 或 BellSoft Liberica
Serverless / 冷启动 → GraalVM Native Image 或 CRaC
金融 / 电信级延迟 → Azul Zulu Prime 21
AWS 环境 → Amazon Corretto 21
多架构 → docker buildx linux/amd64 + linux/arm64

下一步

想看 Nginx 自建镜像（前端静态 / 反向代理 / WebSocket / TCP UDP）→ Nginx 自建镜像实战
想看 Go 自建最小镜像（scratch 5MB 级别）→ Go 自建最小镜像
想看 Java 应用 Docker 化（Tomcat / Spring Boot 打包 + HTTPS 证书）→ Java 应用 Docker 化

Go 自建最小镜像：scratch 5MB 级别，一条龙时区与 CA 证书

Fri, 15 Mar 2024 00:00:00 +0800

Go 程序最爽的一件事是能编译成单个静态二进制——配合 Docker 的 scratch 基础镜像（一个空镜像），最终产物能小到 5MB 级别。这篇把整个流程整理清楚：Windows 下编译 Linux 二进制、Dockerfile 多阶段构建、scratch 引导、时区与 CA 证书一条龙处理。

阅读对象：Go 后端工程师、SRE、追求极致镜像体积的容器化实践者 覆盖范围：scratch 基础镜像 + 多阶段构建 + 时区（Asia/Shanghai）+ CA 证书（x509: certificate signed by unknown authority 修复）+ Windows 交叉编译 + docker-compose 部署

一、为什么 Go 适合自建最小镜像

Go 程序的独特优势：

静态链接：CGO_ENABLED=0 后无任何动态库依赖
无运行时：不依赖 JVM / Python 解释器
编译产物单一：一个二进制文件搞定
Docker scratch 支持：scratch 是 Docker 保留的特殊"空"镜像，没有 /bin/sh、没有 libc、没有包管理器

结果：最终的镜像只有 5~20MB——比 alpine 还小一个数量级。

镜像	大小
`openjdk:8-jre-slim` Java 应用	~ 250 MB
`node:18-alpine` Node 应用	~ 180 MB
`python:3.11-slim` Python 应用	~ 150 MB
`alpine` Go 应用	~ 50 MB
`scratch` Go 应用	~ 5-20 MB

冷启动时间、镜像拉取速度、磁盘占用全面占优——Go 在云原生时代的统治力不是没道理的。

When to use：

内部工具 / Sidecar / Agent / 接入层网关

对冷启动敏感（Serverless / K8s 弹性扩容）

不适用：需要 bash / ps / curl 调试场景（scratch 里啥都没有）

二、scratch 镜像的 Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# ============ 阶段 1：在 golang:alpine 上编译 ============
FROM golang:alpine as build
RUN apk --no-cache add tzdata

# ============ 阶段 2：scratch 镜像拷贝二进制 + 时区 + CA ============
FROM scratch as final

# 1. 拷贝时区数据（解决 date 命令和 Go time 包时区问题）
COPY --from=build /usr/share/zoneinfo/Asia/Shanghai /usr/share/zoneinfo/Asia/Shanghai

# 2. 拷贝 CA 证书（解决 HTTPS 请求 x509 错误）
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

# 3. 设置时区环境变量
ENV TZ=Asia/Shanghai

# 4. 工作目录
WORKDIR /app

# 5. 业务二进制（编译时 CGO_ENABLED=0）
COPY main /app/main

# 6. 启动
ENTRYPOINT ["/app/main"]

为什么多阶段构建？

golang:alpine 编译时需要工具链（~ 350MB），但运行时不需要
编译完只把 main 二进制拷到 scratch，避免编译工具链污染最终镜像

三、Windows 下编译 Linux 二进制

Go 跨平台编译是它最爽的特性之一。在 Windows CMD 下：

1
2
3
4


set CGO_ENABLED=0
set GOOS=linux
set GOARCH=amd64
go build -ldflags="-s -w" -installsuffix cgo -o main .

参数解释：

CGO_ENABLED=0：禁用 CGO，生成纯静态二进制
GOOS=linux：目标操作系统 Linux
GOARCH=amd64：目标 CPU 架构 x86_64
-ldflags="-s -w"：去掉符号表和调试信息，体积更小（约 30%）

更激进的可选优化：

1
2


CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
 go build -ldflags '-s -w --extldflags "-static -fpic"' -o main .

实测：一个 “hello 世界” 程序

默认编译：~ 1.14 MB
-s -w 后：~ 850 KB
加上 -trimpath（去掉构建路径）：~ 800 KB

四、scratch 镜像调试技巧

scratch 没有 shell、没有 ps、没有 ls——容器内调试几乎不可能。常用技巧：

4.1 临时换成 alpine 调试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 改 Dockerfile 最后一行
FROM alpine:latest
RUN apk add --no-cache tzdata ca-certificates
COPY --from=build /usr/share/zoneinfo/Asia/Shanghai /usr/share/zoneinfo/Asia/Shanghai
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
ENV TZ=Asia/Shanghai
COPY main /app/main
CMD ["/app/main"]

# 构建
docker build -t myapp:debug .

# exec 进去调试
docker run -it --rm myapp:debug sh

4.2 制造一个 0 字节 scratch 镜像

有时候只想演示 FROM scratch 能跑（不是 pull 出来）：

1

tar cv --files-from /dev/null | docker import - scratch

这样就能在 Dockerfile 里写 FROM scratch 而不报错了。

五、docker-compose 部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


version: "3"
services:
 greet:
 image: go-scratch:1.0.0
 container_name: greet
 restart: always
 ports:
 - 8888:8888
 volumes:
 - /home/project/greet/etc/greet-api.yaml:/app/etc/greet-api.yaml
 - /home/project/greet/logs:/app/logs
 - /home/project/greet/main:/app/main
 - /etc/timezone:/etc/timezone:ro  # 时区同步
 - /etc/localtime:/etc/localtime:ro
 command: ./main -f etc/greet-api.yaml

注意：scratch 镜像里没有 ./main 之外的可执行文件——chmod +x main 必须做。

服务器启动：

1
2
3
4
5
6
7


# 1. 上传 main 二进制
chmod +x main
scp main user@server:/home/project/greet/main/

# 2. 启动
cd /home/project/greet
docker-compose up -d

六、验证与冒烟测试

1
2
3
4
5
6
7


# 1. 看时区
docker run --rm go-scratch:1.0.0 sh -c 'date' # scratch 没 sh，用下面方式
# 改用 alpine 包一层：
docker run --rm alpine:latest sh -c 'echo "now: $(date)"'

# 2. 业务接口
curl -i http://container-ip:8888/from/you

预期返回：

1
2
3
4
5
6


HTTP/1.1 200 OK
Content-Type: application/json
Date: Fri, 21 May 2021 05:02:01 GMT
Content-Length: 28

{"message":"hello,go-zero!"}

七、典型坑位

7.1 `x509: certificate signed by unknown authority`

症状：Go 程序发 HTTPS 请求失败。

原因：scratch 镜像没有 CA 证书——OpenSSL 默认信任的根证书列表缺失。

修复（上面 Dockerfile 已写）：

1

COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt

或在 Go 代码里显式指定：

1
2
3
4
5
6
7
8
9


// 方案 A：用 ca-certificates.crt
caCert, _ := ioutil.ReadFile("/etc/ssl/certs/ca-certificates.crt")
caCertPool := x509.NewCertPool()
caCertPool.AppendCertsFromPEM(caCert)

// 方案 B：跳过证书校验（**绝不用于生产**）
tr := &http.Transport{
 TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
}

7.2 时区错乱

症状：Go 日志时间戳和宿主机差 8 小时。

修复（上面 Dockerfile 已写）：

1
2


COPY --from=build /usr/share/zoneinfo/Asia/Shanghai /usr/share/zoneinfo/Asia/Shanghai
ENV TZ=Asia/Shanghai

Go 代码：

1
2
3
4
5


// 旧写法：time.Now() 永远返回 UTC
// 新写法：time.LoadLocation
loc, _ := time.LoadLocation("Asia/Shanghai")
now := time.Now().In(loc)
fmt.Println(now.Format("2006-01-02 15:04:05"))

7.3 静态文件找不到

scratch 镜像里 os.Stat 返回 no such file——可能是：

编译时没把静态文件 embed：

1
2
3
4


import "embed"

//go:embed static/*
var staticFiles embed.FS

或者用 COPY 拷进镜像但路径写错

7.4 内存 / CPU 限制不生效

docker run -m 512m 对 scratch 镜像不生效——因为没有 cgroup 感知。

修复：在 Go 代码里显式读取：

1
2
3
4


import "github.com/docker/go-units"

// 或用 uber-go/automaxprocs
import _ "go.uber.org/automaxprocs"

八、多架构构建（ARM64 + AMD64）

M1 Mac / 国产 ARM 服务器越来越多，单架构镜像不够用：

1
2
3
4
5
6
7
8


# 1. 创建 buildx builder
docker buildx create --name multiarch --use

# 2. 多架构构建并推送
docker buildx build \
 --platform linux/amd64,linux/arm64 \
 -t dockerhub.example.com/library/greet:1.0.0 \
 --push .

实测：

单 amd64 构建：~ 30 秒
amd64 + arm64 构建：~ 90 秒（首次拉基础镜像）
后续增量构建：~ 20 秒

九、CI/CD 集成

GitHub Actions 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


name: build-go-image
on: [push]
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: docker/setup-buildx-action@v3
 - uses: docker/login-action@v3
 with:
 registry: dockerhub.example.com
 username: ${{ secrets.REGISTRY_USER }}
 password: ${{ secrets.REGISTRY_PASS }}
 - uses: docker/build-push-action@v5
 with:
 context: .
 platforms: linux/amd64,linux/arm64
 push: true
 tags: dockerhub.example.com/library/greet:${{ github.sha }}
 cache-from: type=gha
 cache-to: type=gha,mode=max

gha cache 让第二次构建快 80%——只重编变化的层。

十、最佳实践清单

永远用多阶段构建：编译环境和运行时彻底隔离
CGO_ENABLED=0 必加：避免任何动态库依赖
CA 证书必拷：HTTPS 请求的根证书不能少
时区三选一：环境变量 TZ / 软链 /etc/localtime / embed 时区文件
-ldflags="-s -w" 必加：省 30% 体积
-trimpath 可选：去掉绝对路径，构建可重现
scratch 调试：用 docker debug（Docker Desktop 自带）或者临时换 alpine
多架构：用 docker buildx 同时构建 linux/amd64 和 linux/arm64
静态资源 embed：不要依赖 bind mount，单一二进制就是单一二进制

2024+ 视角补充

本文写于 2024-03，2024-2026 期间 Go 容器化关键演进：

Go 1.22+ → 1.23 → 1.24（2024-2026）：range over int、iter 包（迭代器）、for-range loop variable 修复（for 循环变量每个 iteration 独立，修复经典 for 闭包 bug）
Go 1.23 for-range 行为变更：每个 iteration 独立变量，老代码可能行为不一致——升级必测
Go 1.24（2025-02）：泛型类型参数方法增强；map 并发安全改进
scratch 镜像仍是稳态选择——但 distroless（gcr.io/distroless/static）成为 2024+ 推荐：
- distroless 只含运行时依赖（ca-certificates、tzdata、/etc/passwd）——比 scratch 多 5MB，但更安全（无 root 提权风险）
- Google 内部推荐：所有 Go 服务 2024+ 默认 distroless
Chainguard Images 1.0+（2024）：零 CVE 容器镜像，比 distroless 更安全——商业支持
Wolfi OS 1.0+（2024）：Chainguard 出的"通用容器 OS"——基础镜像新选择
多架构构建（ARM64 + AMD64） 是 2024+ 标准
WebAssembly（Wasm） 部署：Go 1.21+ 编译 Wasi Target，边缘计算 / FaaS 场景爆发
TinyGo 0.32+：嵌入式 / IoT 场景——比标准 Go 编译产物更小（10-50KB 级别）

实战建议（2025-2026 视角）：

生产服务 → distroless/static 或 Chainguard Images（vs scratch 更安全）
极致体积 → scratch + 多阶段构建（本文方案仍 OK）
多架构 → docker buildx linux/amd64 + linux/arm64 是 2024+ 默认
边缘 / FaaS → Go 1.24+ + Wasi + Spin / Fermyon Cloud
嵌入式 / IoT → TinyGo 0.32+

下一步

想看 JDK 自建镜像实战（Debian / Ubuntu / Alpine 三大流派）→ JDK 自建镜像实战
想看 Nginx 自建镜像实战（前端 dist / 反代 / WebSocket）→ Nginx 自建镜像实战
想看 Java 应用 Docker 化实战（Tomcat / Spring Boot 打包）→ Java 应用 Docker 化

Nginx 自建镜像实战：前端静态、反向代理、WebSocket 与四层转发

Fri, 15 Sep 2023 00:00:00 +0800

Nginx 容器化部署看似简单——docker run -d -p 80:80 nginx 就能跑——但生产里要解决的是：怎么把前端 dist、nginx.conf、SSL 证书打包成可复用的镜像，而不是每次新环境都 ssh 进去改配置。这篇把多年自建 Nginx 镜像的套路整理清楚。

阅读对象：前端工程师、运维、需要部署 Web 服务的全栈工程师 覆盖范围：前端 dist 打包 + nginx.conf 模板 + 反向代理 / WebSocket / TCP UDP 四层 + SSL + bitnami/nginx 优势对比

一、为什么需要自建 Nginx 镜像

docker run nginx 看似省事，但生产场景里很快撞墙：

前端 dist 在外面：每次新构建都要 docker cp 或 bind mount，配置不统一
nginx.conf 在外面：集群里 5 台机器 5 份配置，改一行同步半天
SSL 证书在容器内：Let’s Encrypt 三个月续期，每台机器都跑一遍 certbot
个性化配置散落：gzip、autoindex、限流、灰度发布，每个项目都要从头写

自建 Nginx 镜像的本质：把"配置 + 静态资源 + 证书"做成不可变的镜像。新机器拉新镜像即用，配置漂移被堵在镜像层之外。

When to use：

同一份前端代码需要部署到多台机器（灰度 / 多机房）

业务方只关心"上传代码 + 重启容器"，不想碰 nginx.conf

团队有统一的反代规范（统一超时、统一 gzip、统一 WebSocket 头）

二、最小化 Dockerfile

1
2
3


FROM dockerhub.example.com/base/nginx:latest
ADD html /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

文件结构：

1
2
3
4
5


.
├── Dockerfile
├── html
│ └── index.html
└── nginx.conf

构建：

1
2
3


docker build -t dockerhub.example.com/library/nginx:20240730 .
docker run -d --restart=always --name apph5 --net=host \
 dockerhub.example.com/library/nginx:20240730

关键点：

ADD html 会把整个目录解压到镜像里，比 COPY html 更适合静态文件（虽然官方推荐 COPY，但 ADD 对本地目录行为一致）
--net=host 让 Nginx 直接监听宿主机端口，省一层 NAT——H5 活动页常用
library/nginx:20240730 用日期做 tag，避免覆盖旧版本

三、生产级 nginx.conf 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


user root;
worker_processes 1;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
 worker_connections 1024;
}

http {
 include /etc/nginx/mime.types;
 default_type application/octet-stream;

 log_format main '$remote_addr - $remote_user [$time_local] "$request" '
 '$status $body_bytes_sent "$http_referer" '
 '"$http_user_agent" "$http_x_forwarded_for"';

 access_log /var/log/nginx/access.log main;

 sendfile on;
 keepalive_timeout 65;

 # ============ 核心优化 ============
 autoindex on; # 目录浏览（文件服务器场景）

 gzip on; # 开启 gzip
 gzip_buffers 32 4K; # 压缩缓冲
 gzip_comp_level 6; # 压缩级别 1-9，6 是性价比甜蜜点
 gzip_min_length 1k; # 1K 以下不压缩
 gzip_types application/javascript text/css text/xml; # 压缩类型
 gzip_disable "MSIE [1-6]\."; # 兼容老 IE
 gzip_http_version 1.1; # 最低 HTTP 版本
 gzip_vary on; # 传输压缩标志

 # ============ 大文件上传 ============
 client_max_body_size 2000M; # 上传文件大小限制
 client_header_buffer_size 128k;
 large_client_header_buffers 4 128k;

 # ============ 业务 server ============
 server {
 listen 10082;
 server_name location;
 add_header 'Access-Control-Allow-Origin' '*'; # 跨域
 root /usr/share/nginx/html;
 index index.html;
 try_files $uri $uri/ /index.html; # SPA 路由

 # 反向代理后端 API
 location ^~ /api/ {
 proxy_pass http://localhost:9527/;
 }
 }
}

实战要点：

try_files $uri $uri/ /index.html：SPA 路由必备——直接访问 /user/profile 不 404
gzip_types 务必加 application/javascript（不是 text/javascript）——新版 MIME 标准
client_max_body_size 2000M：配合后端 Spring Boot 的 spring.servlet.multipart.max-file-size 一起调
add_header 'Access-Control-Allow-Origin' '*'：只用于开发，生产应该用 https://www.example.com 白名单

四、WebSocket 反向代理

Nginx 反代 WebSocket 关键是保留 Upgrade 头：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# http block 顶部加映射
map $http_upgrade $connection_upgrade {
 default upgrade;
 '' close;
}

# server block 内 location
location /ws/ {
 proxy_pass http://localhost:8080/;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection $connection_upgrade;
 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_read_timeout 300s;
 proxy_send_timeout 300s;
}

没加 Upgrade 头时浏览器控制台会报 WebSocket connection to 'ws://...' failed: Invalid frame header。

五、四层转发：TCP / UDP 代理

Nginx 从 1.9 开始支持 stream 模块（四层），可以代理 MySQL、Redis、MQTT、SIP 等非 HTTP 协议。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# nginx.conf 顶层加 stream block（与 http 同级）
stream {
 log_format proxy '[$time_local] $protocol status:$status, '
 'bytes client:$bytes_sent/$bytes_received $session_time, '
 'client: $remote_addr, upstream:"$upstream_addr", '
 'bytes upstream:$upstream_bytes_sent $upstream_bytes_received';
 access_log /var/log/nginx/stream.log proxy;

 # MySQL 反代
 upstream mysql {
 server 10.0.0.1:3306 max_fails=2 fail_timeout=10s;
 server 10.0.0.2:3306 max_fails=2 fail_timeout=10s;
 }
 server {
 listen 3306;
 proxy_pass mysql;
 proxy_connect_timeout 5s;
 }

 # 端口段转发（PASV FTP 必备）
 server {
 listen 21100-21110;
 proxy_pass 10.0.0.1:$server_port; # $server_port 是动态端口
 }
}

实战案例：FTP 服务主动模式要在客户端出口网络（防火墙 / NAT）做端口段转发，stream 模块就是干这个的。

六、SSL / HTTPS 完整配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


server {
 server_name api.example.com;
 listen 443 ssl;

 ssl_certificate /etc/nginx/ssl/fullchain.pem;
 ssl_certificate_key /etc/nginx/ssl/privkey.pem;

 # 协议版本（生产只开 TLS 1.2+）
 ssl_protocols TLSv1.2 TLSv1.3;

 # 加密套件
 ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
 ssl_prefer_server_ciphers on;

 # session 复用
 ssl_session_cache shared:SSL:10m;
 ssl_session_timeout 1d;
 ssl_session_tickets off;

 # HSTS
 add_header Strict-Transport-Security "max-age=63072000" always;

 # HTTP 强转 HTTPS
 error_page 497 https://$host$request_uri;

 location / {
 proxy_pass http://localhost:9000;
 proxy_set_header Host $http_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;
 }
}

# 80 强转 443
server {
 listen 80;
 server_name api.example.com;
 return 301 https://$server_name$request_uri;
}

证书挂载（推荐用 bind mount 而非 ADD 进镜像）：

1
2
3


docker run -d \
 -v /etc/letsencrypt/live/api.example.com:/etc/nginx/ssl:ro \
 ...

证书 3 个月续期时 nginx -s reload 一下，不用重启容器。

七、bitnami/nginx 镜像优势

bitnami/nginx 相对官方 nginx 镜像有几个明显优势：

特性	官方 `nginx`	`bitnami/nginx`
非 root 用户运行	默认 `root`（安全风险）	默认 uid 1001
默认 HSTS / 安全头	无	有
健康检查	无	`HEALTHCHECK` 内置
日志切分	无	接入 stdout/stderr
镜像体积	~ 140MB	~ 90MB

生产强烈推荐 bitnami 镜像。root 运行的 nginx 容器一旦被攻破就拿到宿主 root——bitnami 默认 nginx 用户运行，减少 90% 的攻击面。

八、生产部署清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 1. 准备前端 dist
npm run build # 生成 dist/

# 2. 准备 nginx.conf（用上面的模板）

# 3. 准备 SSL 证书
mkdir -p ssl && cp /etc/letsencrypt/live/example.com/* ssl/

# 4. 构建镜像
docker build -t dockerhub.example.com/library/web:20240730 .

# 5. 推到 Harbor
docker push dockerhub.example.com/library/web:20240730

# 6. 生产部署
docker run -d --name web --restart=always \
 --network=web \
 -p 443:443 -p 80:80 \
 -v /data/web/ssl:/etc/nginx/ssl:ro \
 dockerhub.example.com/library/web:20240730

九、监控与日志

日志接入：

1
2
3
4
5
6
7


# 用 Loki / ELK 收集，docker-compose 里加 logging driver
logging:
 driver: loki
 options:
 loki-url: "http://internal.example.com:3100/loki/api/v1/push"
 max-size: "50m"
 max-file: "10"

健康检查：

1
2
3
4
5
6


location /nginx_status {
 stub_status on;
 access_log off;
 allow 127.0.0.1; # 只允许内网
 deny all;
}

容器外查：

1
2
3
4
5


curl http://container-ip/nginx_status
# Active connections: 2
# server accepts handled requests
# 100 100 200
# Reading: 0 Writing: 1 Waiting: 1

十、常见坑位

10.1 反代后端丢失 HTTPS 信息

后端 Spring Boot 拿到 request.getScheme() 是 http 不是 https——因为 nginx 用 HTTP 协议连后端。

修复：后端配 server.tomcat.remoteip.protocol-header=X-Forwarded-Proto，或 Nginx 显式传：

1

proxy_set_header X-Forwarded-Proto $scheme;

10.2 SPA 路由 404

直接访问 https://app.example.com/user/profile 返回 404。

修复：try_files $uri $uri/ /index.html;——所有未匹配路径都返回 index.html，由前端路由处理。

10.3 WebSocket 反复断连

症状：WSS 连接 60 秒断一次。

原因：默认 proxy_read_timeout 60s，WebSocket 是长连接，超过 60 秒没数据就被切断。

修复：proxy_read_timeout 300s; 或更长。

10.4 gzip 对小文件无效果

gzip_min_length 1k; 控制 1KB 以下的文件不压缩——gzip_types 只决定"压缩什么类型"，文件大小阈值由 min_length 控制。

2024+ 视角补充

本文写于 2023-09，2024-2026 期间 Nginx 自建镜像关键演进：

Nginx 1.27 LTS（2024-11）：HTTP/3（QUIC）GA；OpenSSL 3.x；动态 SSL 证书加载
Nginx 1.28 LTS（2025-Q4 预期）：ACMEv2 自动证书（不用 certbot）；BoringSSL 可选
Nginx Unit 1.34+（2024-2026）：应用服务器模式（Go / Node / Python / Java / PHP）——Web + App Server 一体
Nginx Ingress 1.12+（K8s）：Gateway API GA；IPV6 双栈；WAF 集成
OpenResty 1.25+：Lua 生态成熟，API Gateway / WAF 场景仍是首选
bitnami/nginx 镜像：2024+ 仍维护，非 root 用户 / 健康检查仍是优势
替代品（2024+ 视角）：
- Caddy 2.x：自动 HTTPS / Caddyfile 简洁——新项目首选
- Traefik 3.x：K8s 原生 / 自动服务发现
- HAProxy 3.x：四层代理性能优于 Nginx——数据库 / TCP 代理首选

实战建议（2025-2026 视角）：

传统 Web 反代 / 静态站 → Nginx 1.27 LTS 仍是生产首选
想要最少配置 / 自动 HTTPS → Caddy 2.x
K8s 入口 → Nginx Ingress 1.12+ / Traefik 3.x / Gateway API
API Gateway / WAF → OpenResty 1.25+ 仍是稳态
数据库 / TCP 代理 → HAProxy 3.x

下一步

想看 Go 自建最小镜像（scratch 5MB 级别）→ Go 自建最小镜像
想看 MinIO 对象存储实战（含 Nginx 反代安全加固）→ MinIO 对象存储实战
想看 Java 微服务治理（Sentinel 限流 / Spring Boot Admin）→ Java 微服务治理

自建镜像 on Liangweidong's blog

JDK 自建镜像实战：从 JDK 8 到 JDK 21 的三大流派

一、为什么需要自建 JDK 基础镜像

二、Debian 流派：JDK 8u371 / 8u381

2.1 基础 Dockerfile

2.2 镜像版本演进

2.3 时区必须做两件事

2.4 wait-for-it：解决启动顺序

三、Ubuntu 流派：JDK 8u333 / 8u351

四、Alpine 流派：JDK 8u401（极致小）

4.1 坑：Alpine 自带 musl，Java 跑不动

4.2 镜像大小对比

五、JDK 21：新时代的开端

5.1 Liberica JDK 21 Dockerfile

5.2 JDK 21 的 Virtual Thread

六、典型坑位

6.1 中文乱码三连击

6.2 TLS 1.0 / 1.1 兼容

6.3 容器内 ping / ip 找不到

七、Jenkins Agent 镜像

八、镜像分发：自建 vs Docker Hub

九、构建与分发完整命令

十、最佳实践清单

2024+ 视角补充

下一步

Go 自建最小镜像：scratch 5MB 级别，一条龙时区与 CA 证书

一、为什么 Go 适合自建最小镜像

二、scratch 镜像的 Dockerfile

三、Windows 下编译 Linux 二进制

四、scratch 镜像调试技巧

4.1 临时换成 alpine 调试

4.2 制造一个 0 字节 scratch 镜像

五、docker-compose 部署

六、验证与冒烟测试

七、典型坑位

7.1 x509: certificate signed by unknown authority

7.2 时区错乱

7.3 静态文件找不到

7.4 内存 / CPU 限制不生效

八、多架构构建（ARM64 + AMD64）

九、CI/CD 集成

十、最佳实践清单

2024+ 视角补充

下一步

Nginx 自建镜像实战：前端静态、反向代理、WebSocket 与四层转发

一、为什么需要自建 Nginx 镜像

二、最小化 Dockerfile

三、生产级 nginx.conf 模板

四、WebSocket 反向代理

五、四层转发：TCP / UDP 代理

六、SSL / HTTPS 完整配置

七、bitnami/nginx 镜像优势

八、生产部署清单

九、监控与日志

十、常见坑位

10.1 反代后端丢失 HTTPS 信息

10.2 SPA 路由 404

10.3 WebSocket 反复断连

10.4 gzip 对小文件无效果

2024+ 视角补充

下一步

6.3 容器内 `ping` / `ip` 找不到

7.1 `x509: certificate signed by unknown authority`