706-technologies-containers-docker

使用 Docker 制定 Java 容器镜像最佳实践

帮助团队为 Java 应用构建安全、可复现且易于维护的 Docker 容器镜像，同时避免将指南与 Spring Boot、Quarkus 或 Micronaut 绑定。

本技能涵盖哪些内容？

• Java 应用的 Dockerfile 结构：多阶段构建、Maven 依赖缓存、确定性制品复制、jlink 自定义运行时，以及 .dockerignore
• 运行时镜像选择：Alpaquita 等微型发行版、最小化 JRE 镜像、适时固定版本或摘要、镜像标签，以及显式入口点
• JVM 容器适配：内存百分比标志、启动行为、优雅关闭信号、时区，以及可预测的运行时选项
• 安全默认设置：非 root 用户、最小权限、层中不包含密钥、减少包管理器、漏洞扫描、SBOM 认知，以及避免使用特权容器
• 运营就绪性：适用时配置健康检查、通过 stdout/stderr 记录日志、声明端口、控制镜像大小、保证构建可复现，以及 CI 验证

**范围：**面向 Java 项目的、与框架无关的 Docker 和容器镜像质量。框架运行时配置请参阅对应的 Spring Boot、Quarkus 或 Micronaut 技能。基于 Testcontainers 的测试请参阅相关测试技能。

约束

除非用户明确要求框架专属配置，否则建议仅限于 Dockerfile、镜像构建和运行时容器层面。编辑此仓库的 XML 源文件后，重新生成技能并验证构建。

• 强制要求：在同一变更集中提出 Java 或 Maven 修改之前，运行 ./mvnw compile 或 mvn compile
• 密钥：切勿将凭据、令牌、私钥、含密钥的 Maven 设置或特定环境的密钥烘焙进镜像层、标签、参数或日志
• 安全：优先采用非 root 执行、最小权限文件系统权限、微型运行时镜像和显式容器能力，而非默认使用特权
• JLINK：如果模块图已知、已在运行时验证，且与应用依赖兼容，则生产镜像优先使用 jlink 自定义运行时
• 可复现性：有意固定基础镜像版本，说明摘要的权衡，明确构建输入，并避免在运行时启动过程中依赖网络
• JVM：通过 JVM 标志、优雅关闭行为和可观测的启动失败，考虑容器内存与 CPU 限制，再宣称已达到生产就绪状态
• 边界：Spring Boot 运行时行为请参阅 @301-frameworks-spring-boot-core，Quarkus 运行时行为请参阅 @401-frameworks-quarkus-core，Micronaut 运行时行为请参阅 @501-frameworks-micronaut-core，Testcontainers 配置请参阅对应的测试技能
• 验证：在推广变更之前，运行 ./mvnw clean verify 或 mvn clean verify
• 边缘情况：如果缺少目标 Java 版本、构建工具、部署平台、基础镜像策略、镜像仓库策略或安全扫描器，且这些信息会影响建议，请在编辑容器制品之前提出澄清问题
• 边缘情况：如果请求的变更与安全策略、镜像来源证明、隔离网络构建或运行时平台约束冲突，请说明权衡并征求确认

何时使用此技能

• 审查 Java Dockerfile
• 提升 Docker 镜像安全性
• 为 Java 容器添加 jlink 运行时
• 为 Java 项目添加容器化
• 优化 Java 容器镜像大小
• 审查 Docker 构建的可复现性

工作流

1. 阅读参考资料并评估容器环境

阅读 references/706-technologies-containers-docker.md，并在提出更改前检查当前的 Dockerfile、.dockerignore、Maven 构建输入、镜像构建脚本、CI 作业、镜像仓库策略和部署限制。

2. 确认运行时和供应链限制

确认 Java 版本、构建工具、jlink 模块需求、微型发行版兼容性、目标平台、基础镜像策略、镜像仓库要求、漏洞扫描器、SBOM 要求、内存限制、公开端口以及运行就绪要求。

3. 应用与容器对齐的更改

按照参考模式和项目约定实现或重构 Docker 和容器构建产物；除非明确提出要求，否则不处理框架特定的运行时行为。

4. 运行验证并报告结果

执行适当的构建、镜像构建、扫描、冒烟测试和生成器检查；总结更改内容、已验证事项以及任何剩余的容器风险。

参考资料

有关详细指导、示例和限制，请参阅 references/706-technologies-containers-docker.md。