gwilym/generic-jvm

通用JVM Docker容器

镜像概述和主要用途

该通用容器设计用于运行需要凭据或其他任务配置的Java应用（以JAR形式）。当前基于Alpine Linux，默认假设使用AWS作为存储机制（未来可扩展为灵活配置）。它通过环境变量和S3对象，基于简单约定控制应用执行，作为为每个Java应用构建单独Docker容器的替代方案（当这些容器本质上相同，仅启动脚本和环境变量不同时）。

注意：此为alpha版本，在1.0.0版本发布前，配置约定可能发生不兼容变更。

核心功能和特性

• 轻量基础：基于Alpine Linux，保持容器体积小巧
• 灵活引导：通过环境变量中嵌入的脚本或S3中的脚本进行自引导
• 安全密钥管理：从S3下载加密密钥并解密到容器中
• JAR管理：从S3下载、验证并执行单个JAR文件
• 用户脚本支持：提供预引导（USERSCRIPT_PRE_BOOTSTRAP）和后引导（USERSCRIPT_POST_BOOTSTRAP）脚本注入点
• 签名验证：支持通过KMS加密的签名验证JAR文件完整性

使用场景和适用范围

• 当多个Java应用的容器结构基本相同，仅启动脚本和环境变量不同时，避免为每个应用构建单独容器
• 需要从AWS S3动态获取配置、密钥或应用JAR的Java应用部署
• 需要通过环境变量注入自定义脚本以控制容器启动流程的场景
• 基于AWS生态的Java应用部署（如ECS、EKS等服务）

使用方法和配置说明

启动流程

容器启动时按以下顺序执行操作：

1. 预引导脚本执行：如果设置了USERSCRIPT_PRE_BOOTSTRAP，其内容将被写入文件并在其他操作前执行（需符合格式要求，见下文）
2. 密钥解密：若定义了SECRETS_BASE_S3_URL，从该地址下载密钥到SECRETS_BASE_DIR并使用GnuPG（gpg）解密：
   • 每个密钥由.gpg文件和.key文件组成，其中.key文件通过AWS KMS加密，.gpg文件通过KMS加密的密钥加密（信封加密机制）
   • 容器需具备解密.key文件的KMS权限
3. S3引导脚本执行：若定义了BOOTSTRAP_S3_URL，从该地址下载引导脚本并执行
4. JAR下载与验证：若定义了JAVA_JAR_S3_URL，从该地址下载JAR文件，并通过JAVA_JAR_S3_URL.sig下载KMS加密的签名进行验证；验证通过后，JAVA_JAR变量将被设置为下载的JAR路径
5. 后引导脚本执行：如果设置了USERSCRIPT_POST_BOOTSTRAP，其内容将在所有操作后、Java应用启动前执行（需符合格式要求，见下文）
6. 启动Java应用：通过exec java -jar $JAVA_JAR执行应用；若JAVA_JAR未设置，启动失败

环境变量说明

环境变量脚本注意事项

• USERSCRIPT_*变量内容必须经过base64编码
• 支持压缩格式：通过USERSCRIPT_FORMAT指定gzip或zip，未指定则按原始文本处理并执行

加密密钥操作步骤

生成加密数据密钥

使用AWS KMS生成由KEY_ID加密的数据密钥（AES-256）：

bash
aws kms generate-data-key-without-plaintext \
    --key-id=${KEY_ID} \
    --key-spec=AES_256 --query CiphertextBlob \
    --output=text \
    | base64 -d \
    > ${SECRET_FILE}.key

加密密钥文件

使用上述生成的密钥解密后加密实际密钥内容：

bash
aws kms decrypt \
    --ciphertext-blob=fileb://${SECRET_FILE}.key \
    --query=Plaintext \
    --output=text \
    | base64 -d \
    | gpg --symmetric --passphrase-fd 0 --cipher-algo AES256 --batch \
        --out ${SECRET_FILE}.gpg ${SECRET_FILE}

上传密钥到S3

仅上传加密后的密钥文件（.gpg和.key）到S3，所有密钥需放在同一前缀下以便容器发现：

bash
aws s3 cp ${SECRET_FILE}.gpg ${SECRETS_PREFIX}/${SECRET_FILE}.gpg
aws s3 cp ${SECRET_FILE}.key ${SECRETS_PREFIX}/${SECRET_FILE}.key

JAR签名操作步骤

生成并加密JAR签名

生成JAR文件的SHA-512哈希，使用KMS加密后上传到S3：

bash
# 生成加密签名
aws kms encrypt --key-id ${KEY_ID} --plaintext "$(sha512sum < ${JAR_FILE})" --output text --query CiphertextBlob | base64 -d > ${JAR_FILE}.sig

# 上传JAR和签名到S3
aws s3 cp ${JAR_FILE} ${JAR_S3_URL}
aws s3 cp ${JAR_FILE}.sig ${JAR_S3_URL}.sig

示例设置

• CI/CD集成：Travis-CI配置为构建应用的可部署master分支，然后执行签名并将JAR上传到S3
• 基础设施管理：Terraform配置管理AWS ECS任务定义，加密密钥存储在Terraform仓库中
• 容器编排：通过Terraform管理的配置，由AWS ECS调度Docker容器运行