ljwx-health/docs/03-deployment/docker/custom-base-images.md

自定义基础镜像使用指南

📋 概述

LJWX Health 项目使用自定义基础镜像来优化构建速度、集成可观测性组件（OpenTelemetry）和标准化开发环境。

核心优势：

• ✅ 避免每次构建都下载 Maven、OpenTelemetry Agent
• ✅ 统一版本管理（JDK 21、Maven 3.9、OpenTelemetry 2.11.0）
• ✅ 集成公司标准配置（阿里云 Maven 镜像、时区设置）
• ✅ 支持多架构（amd64、arm64）

---

🏗️ 可用的自定义基础镜像

1. Java Maven + OpenTelemetry（ljwx-boot）

镜像标签：

harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine
harbor.omniverseai.net/ljwx-base-images/java-maven-otel:latest

包含组件：

• ✅ Eclipse Temurin JDK 21 (Alpine)
• ✅ Maven 3.9
• ✅ OpenTelemetry Java Agent 2.11.0 (/opt/opentelemetry-javaagent.jar)
• ✅ 阿里云 Maven 镜像配置
• ✅ 时区设置（Asia/Shanghai）

构建脚本：

cd docker/base-images
./build-java-maven-otel.sh

Dockerfile 使用示例：

# ====== 构建阶段 ======
FROM harbor.omniverseai.net/ljwx-base-images/java-maven-otel:21-alpine AS builder

WORKDIR /build

# 复制 pom.xml 和源码
COPY pom.xml .
RUN mvn dependency:go-offline -B

COPY src/ ./src/
RUN mvn clean package -DskipTests -B

# ====== 运行阶段 ======
FROM eclipse-temurin:21-jre-alpine

WORKDIR /app

# 复制 JAR 和 OpenTelemetry Agent
COPY --from=builder /build/target/*.jar app.jar
COPY --from=builder /opt/opentelemetry-javaagent.jar /opt/opentelemetry-javaagent.jar

# 启动应用（集成 OpenTelemetry）
ENTRYPOINT ["sh", "-c", "java -javaagent:/opt/opentelemetry-javaagent.jar $JAVA_OPTS -jar app.jar"]

---

2. Node 20 + pnpm（ljwx-admin）

镜像标签：

harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest

包含组件：

• ✅ Node.js 20 (Alpine)
• ✅ pnpm 10.8.0
• ✅ 时区设置（Asia/Shanghai）

构建脚本：

cd docker/base-images
docker build -f Dockerfile.node20-pnpm -t harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest .
docker push harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest

Dockerfile 使用示例：

# 构建阶段
FROM harbor.omniverseai.net/ljwx-base-images/node20-pnpm:latest AS builder

WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

# 运行阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

---

3. Python 3.12 + pip（ljwx-bigscreen）

镜像标签：

harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest

包含组件：

• ✅ Python 3.12 (Alpine)
• ✅ pip 最新版
• ✅ 阿里云 PyPI 镜像配置
• ✅ 时区设置（Asia/Shanghai）

构建脚本：

cd docker/base-images
docker build -f Dockerfile.python3.12-pip -t harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest .
docker push harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest

Dockerfile 使用示例：

FROM harbor.omniverseai.net/ljwx-base-images/python3.12-pip:latest

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "app.py"]

---

🚀 OpenTelemetry 集成详解

为什么需要 OpenTelemetry Java Agent？

OpenTelemetry 是 CNCF 标准的可观测性框架，提供：

• 📊 分布式追踪：跟踪请求在微服务间的完整调用链
• 📈 指标收集：JVM、HTTP、数据库等自动指标
• 📝 日志关联：trace_id、span_id 自动注入日志

ljwx-boot 中的 OpenTelemetry 配置

1. Dockerfile 集成

构建阶段：

FROM harbor.omniverseai.net/ljwx/java-maven-otel:21-alpine AS builder
# OpenTelemetry Agent 已预置在 /opt/opentelemetry-javaagent.jar

运行阶段：

FROM eclipse-temurin:21-jre-alpine
COPY --from=builder /opt/opentelemetry-javaagent.jar /opt/opentelemetry-javaagent.jar
ENTRYPOINT ["sh", "-c", "java -javaagent:/opt/opentelemetry-javaagent.jar $JAVA_OPTS -jar app.jar"]

2. 环境变量配置（K8s）

在 deploy/helm/ljwx-health/values.yaml 中配置：

ljwxBoot:
  env:
    # OpenTelemetry 基础配置
    - name: OTEL_SERVICE_NAME
      value: "ljwx-boot"

    # Tempo OTLP 接收端点（gRPC）
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: "http://tempo.tracing.svc.cluster.local:4317"

    # 采样策略（生产环境 10%）
    - name: OTEL_TRACES_SAMPLER
      value: "parentbased_traceidratio"
    - name: OTEL_TRACES_SAMPLER_ARG
      value: "0.1"

    # 资源属性（用于 Grafana 分组）
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: "service.name=ljwx-boot,deployment.environment=production"

3. 验证 OpenTelemetry 集成

检查 Pod 是否启动了 Agent：

kubectl logs -n ljwx-health deployment/ljwx-boot | grep -i opentelemetry
# 应该看到：OpenTelemetry Javaagent 2.11.0 initialized

检查环境变量：

kubectl exec -n ljwx-health deployment/ljwx-boot -- env | grep OTEL

验证追踪数据：

# 访问 Grafana Explore → Tempo 数据源
# 查询：{service.name="ljwx-boot"}

---

📦 多架构支持

所有自定义基础镜像都支持多架构构建（amd64、arm64）。

本地架构构建（快速）

cd docker/base-images
./build-java-maven-otel.sh  # 自动检测当前架构（amd64 或 arm64）

多架构构建（完整）

cd docker/base-images
# 设置环境变量，同时构建两种架构
PLATFORMS=linux/amd64,linux/arm64 ./build-java-maven-otel.sh

---

🔧 维护指南

更新 OpenTelemetry Agent 版本

1. 下载新版本 Agent：

cd docker/base-images
OTEL_VERSION=2.12.0  # 修改为新版本
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v${OTEL_VERSION}/opentelemetry-javaagent.jar \
     -O opentelemetry-javaagent-${OTEL_VERSION}.jar

2. 更新构建脚本：

# 编辑 build-java-maven-otel.sh
OTEL_VERSION="2.12.0"  # 修改此行

3. 更新 Dockerfile：

# 编辑 Dockerfile.java-maven-otel
ARG OTEL_AGENT_VERSION=2.12.0  # 修改此行

4. 重新构建并推送：

./build-java-maven-otel.sh

更新 JDK 版本

修改 Dockerfile.java-maven-otel 的基础镜像：

FROM eclipse-temurin:23-jdk-alpine  # 升级到 JDK 23

---

⚠️ 重要注意事项

1. Dockerfile 必须使用正确的基础镜像

错误示例（导致 OpenTelemetry 缺失）：

# ❌ 运行阶段使用了不包含 Agent 的镜像
FROM harbor.omniverseai.net/ljwx-base-images/maven3.9-jdk21:latest

正确示例：

# ✅ 方案 1：使用包含 Agent 的基础镜像
FROM harbor.omniverseai.net/ljwx/java-maven-otel:21-alpine AS builder

# ✅ 方案 2：从构建阶段 COPY Agent
FROM eclipse-temurin:21-jre-alpine
COPY --from=builder /opt/opentelemetry-javaagent.jar /opt/opentelemetry-javaagent.jar
ENTRYPOINT ["sh", "-c", "java -javaagent:/opt/opentelemetry-javaagent.jar $JAVA_OPTS -jar app.jar"]

2. 必须在启动命令中添加 -javaagent 参数

错误示例（Agent 不会生效）：

ENTRYPOINT ["java", "$JAVA_OPTS", "-jar", "app.jar"]

正确示例：

ENTRYPOINT ["sh", "-c", "java -javaagent:/opt/opentelemetry-javaagent.jar $JAVA_OPTS -jar app.jar"]

3. 环境变量必须正确配置

确保 K8s deployment 或 Helm values.yaml 中包含：

• OTEL_SERVICE_NAME
• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_TRACES_SAMPLER 和 OTEL_TRACES_SAMPLER_ARG

---

📚 相关文档

• OpenTelemetry Java Agent 官方文档
• Tempo 官方文档
• 可观测性实施指南
• Kubernetes 部署指南

---

🆘 故障排查

问题：Grafana 中看不到追踪数据

检查清单：

1. ✅ Dockerfile 是否使用了正确的基础镜像？
2. ✅ 是否复制了 /opt/opentelemetry-javaagent.jar？
3. ✅ ENTRYPOINT 是否包含 -javaagent 参数？
4. ✅ K8s deployment 是否配置了 OTEL 环境变量？
5. ✅ Tempo 服务是否正常运行？

调试命令：

# 检查 Pod 日志
kubectl logs -n ljwx-health deployment/ljwx-boot | grep -i opentelemetry

# 检查环境变量
kubectl exec -n ljwx-health deployment/ljwx-boot -- env | grep OTEL

# 检查 Tempo 服务
kubectl get svc -n tracing tempo

# 测试 Tempo 连通性
kubectl exec -n ljwx-health deployment/ljwx-boot -- nc -zv tempo.tracing.svc.cluster.local 4317

---

最后更新：2026-01-05 维护者：[email protected]