devopsansiblede/acme_certs_extract

ACME Certificate Extract 镜像文档

镜像概述

ACME Certificate Extract 是一款用于从 ACME 协议获取的证书文件（如 Træfik 生成的 acme.json）中提取证书的工具，以便证书复用。该工具兼容 Træfik v1、v2 版本，同时支持 ACME v1、v2 协议。

核心功能与特性

• 多版本兼容：支持 Træfik v1/v2 及 ACME v1/v2 协议生成的证书文件。
• 证书提取：从 ACME 文件中解析并提取私钥、证书、证书链及完整证书链。
• 灵活存储：支持按域名分目录存储、扁平化存储（所有证书在同一目录）及历史版本归档。
• 域名限制：可指定仅处理特定完全限定域名（FQDN）列表。
• 自定义脚本：证书更新后可自动执行自定义脚本（如重启服务）。
• 调试支持：提供调试模式，输出详细日志信息。
• 文件名安全：自动替换域名中的星号（*）为指定字符串，避免文件名非法字符。

使用场景与适用范围

• Træfik 证书复用：Træfik 用户需将 ACME 证书用于其他服务（如 Nginx、邮件服务器等）。
• 证书备份与归档：需定期备份证书或保留历史版本以便回滚。
• 自动化运维：证书更新后自动触发后续操作（如重启容器、同步证书至其他节点）。
• 多域名管理：需按域名组织证书文件或仅处理特定域名证书。

使用方法

基本部署（Docker Run）

通过 docker run 命令直接运行，需挂载存放 ACME 文件的目录和证书输出目录：

bash
docker run docker.xuanyuan.run/devopsansiblede/acme-cert-extract \
  -v $(pwd)/acme:/acme \  # 挂载ACME文件所在目录（默认查找acme.json）
  -v $(pwd)/certs:/certs   # 挂载证书输出目录

Docker Compose 部署

项目提供 docker-compose.yml 文件，可用于本地开发或测试最新变更：

yaml
# 示例 docker-compose.yml（具体以项目实际文件为准）
version: '3'
services:
  acme-cert-extract:
    image: docker.xuanyuan.run/devopsansiblede/acme-cert-extract
    volumes:
      - ./acme:/acme       # 本地ACME目录挂载至容器内/acme
      - ./certs:/certs     # 本地证书输出目录挂载至容器内/certs
    environment:
      - DEBUG=True         # 可选：开启调试模式
      - LIMIT_FQDN=example.com  # 可选：限制仅处理example.com

启动命令：

bash
docker-compose up -d

注意：项目中的 acme_example.json 为测试用例，包含无意义数据，不可用于实际证书提取场景。

配置说明

环境变量

通过环境变量调整工具行为，所有布尔值需使用 Python 风格（True/False）。

ANSI 颜色设置

环境变量中的颜色码为 ANSI 转义序列的数值部分（脚本自动添加前缀 \u001b[ 和后缀 m）。格式由多个部分组成，用分号分隔：

• 样式：0（默认）、1（加粗）、4（下划线）等。
• 前景色：以 3 开头，如 31（红色）、32（绿色）、33（黄色）。
• 背景色：以 4 开头，如 43（黄色背景）。

示例：1;31 表示“加粗红色前景色”，对应错误消息；0;32 表示“默认绿色前景色”，对应成功消息。

证书目录结构

工具在 CERTSDIR（默认 /certs）下生成以下目录结构：

certs 目录（按域名分目录存储）

按域名创建子目录，存放当前证书文件。包含主域名及所有主题备用名称（SANs）对应的目录。每个域名目录下文件：

• privkey.pem：私钥
• cert.pem：证书
• chain.pem：证书链
• fullchain.pem：完整证书链（证书+证书链）

flat 目录（扁平化存储）

所有证书文件直接存放在此目录，文件名格式为 <域名>.<类型>：

• <域名>.key：私钥（对应 privkey.pem）
• <域名>.crt：证书（对应 cert.pem）
• <域名>.chain.pem：证书链（对应 chain.pem）
• <域名>_full.crt：完整证书链（对应 fullchain.pem）

说明：仅当 STORE_FLAT_CRTS=True 时生成此目录。

archive 目录（证书归档）

按域名和时间戳存储历史证书版本，目录结构为 archive/<域名>/<时间戳>/，包含该时间点的证书文件。时间戳格式为 %Y%m%d%H%M%S（如 20240520153045）。

说明：仅当 CRT_ARCHIVE=True 时生成此目录。

许可证与贡献

• 许可证：本项目基于 https://creativecommons.org/licenses/by-sa/4.0/ 许可证发布。
• 贡献指南：详见项目 CONTRIBUTING.md 文件。