jrcs/letsencrypt-nginx-proxy-companion 镜像文档

1. 镜像概述

jrcs/letsencrypt-nginx-proxy-companion 是一个旧版（legacy）Docker镜像仓库，该项目已迁移至新仓库 nginxproxy/acme-companion。旧仓库镜像已停止更新维护，功能及安全性无法得到保障。建议所有用户立即切换至新仓库镜像以获取最新特性、文档及技术支持。

新镜像（nginxproxy/acme-companion）主要用途：作为 nginx-proxy 容器的配套工具，实现 Let's Encrypt SSL/TLS 证书的自动申请、续期与配置，简化 Docker 环境下多容器应用的 HTTPS 部署流程。

2. 核心功能与特性（基于新镜像 nginxproxy/acme-companion）

2.1 核心功能

• 自动证书管理：与 Let's Encrypt CA 交互，自动完成 SSL 证书的申请、验证及续期（默认90天续期一次）。
• 无缝集成 nginx-proxy：监听 nginx-proxy 容器的虚拟主机配置，动态生成 SSL 配置并更新 nginx。
• 多证书支持：支持单域名、多域名（SAN）及通配符域名证书。
• 证书存储与备份：证书默认存储于持久化卷中，支持自定义存储路径，确保数据不丢失。

2.2 关键特性

• 零手动干预：全程自动化，无需手动执行证书申请/续期命令。
• 兼容性广泛：支持 HTTP-01 和 DNS-01 验证方式，适配多数网络环境。
• 轻量级设计：基于 Alpine Linux，镜像体积小，资源占用低。
• 持续维护：活跃的社区支持，定期更新以适配 Let's Encrypt 协议变更及安全补丁。

3. 使用场景与适用范围

3.1 适用场景

• Docker 多容器应用：需为多个 Web 服务（如前端、API、管理后台）配置 HTTPS 的场景。
• 动态部署环境：频繁新增/移除虚拟主机，需自动同步 SSL 配置的场景。
• 简化运维流程：希望避免手动管理证书申请、续期及 nginx 配置的场景。

3.2 环境要求

• Docker 1.13.0+ 或 Docker Compose 1.10.0+
• 目标域名需指向运行容器的主机（HTTP-01 验证），或具备 DNS 记录管理权限（DNS-01 验证）。
• 需配合 nginxproxy/nginx-proxy 容器使用（核心反向代理组件）。

4. 使用方法与配置说明

4.1 切换至新镜像

旧镜像 jrcs/letsencrypt-nginx-proxy-companion 用户需执行以下步骤迁移至新镜像：

1. 停止并删除基于旧镜像的容器；
2. 拉取新镜像：docker pull nginxproxy/acme-companion；
3. 按新镜像的配置参数重新部署（见下文部署示例）。

4.2 部署示例

4.2.1 Docker Run 命令

需配合 nginx-proxy 容器一起运行：

bash
# 1. 启动 nginx-proxy（反向代理核心）
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -p 443:443 \
  -v /var/run/docker.sock:/tmp/docker.sock:ro \
  -v certs:/etc/nginx/certs \
  -v vhost:/etc/nginx/vhost.d \
  -v html:/usr/share/nginx/html \
  nginxproxy/nginx-proxy

# 2. 启动 acme-companion（证书管理）
docker run -d \
  --name acme-companion \
  --volumes-from nginx-proxy \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v acme:/etc/acme.sh \
  -e "DEFAULT_EMAIL=***" \  # 全局默认***（用于证书通知）
  nginxproxy/acme-companion

# 3. 启动业务容器（示例：nginx 测试服务）
docker run -d \
  --name web-app \
  -e "VIRTUAL_HOST=example.com,[***]" \  # 虚拟主机域名
  -e "LETSENCRYPT_HOST=example.com,[***]" \  # 需要申请证书的域名
  -e "LETSENCRYPT_EMAIL=***" \  # 证书相关通知***（优先级高于全局默认）
  nginx

4.2.2 Docker Compose 配置

创建 docker-compose.yml 文件：

yaml
version: '3'

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - certs:/etc/nginx/certs
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
    restart: always

  acme-companion:
    image: nginxproxy/acme-companion
    volumes_from:
      - nginx-proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - acme:/etc/acme.sh
    environment:
      - DEFAULT_EMAIL=***  # 全局默认证书联系人***
    restart: always

  web-app:  # 示例业务容器
    image: nginx
    environment:
      - VIRTUAL_HOST=example.com,[***]  # 绑定域名
      - LETSENCRYPT_HOST=example.com,[***]  # 申请SSL证书的域名
      - LETSENCRYPT_EMAIL=***  # 可选，覆盖全局***
    restart: always

volumes:
  certs:
  vhost:
  html:
  acme:

启动服务：docker-compose up -d

4.3 核心配置参数（环境变量）

4.3.1 acme-companion 容器环境变量

4.3.2 业务容器环境变量（需申请证书时添加）

5. 注意事项

1. 旧镜像停止维护：jrcs/letsencrypt-nginx-proxy-companion 已不再更新，可能存在安全漏洞及功能缺陷，必须迁移至 nginxproxy/acme-companion。
2. 数据持久化：证书及配置文件需通过 Docker 卷（Volume）持久化存储，避免容器重建导致数据丢失。
3. 域名解析：使用 HTTP-01 验证时，目标域名需解析至主机 IP，且 80/443 端口需对外开放；DNS-01 验证需配置对应 DNS 提供商的 API 密钥（具体参考新镜像文档）。
4. 文档参考：完整配置及高级用法（如 DNS 验证、证书自动更新等）请查阅新镜像***文档：nginxproxy/acme-companion。