docker-nginx-certbot 是一个基于官方 Nginx Docker 镜像（Debian 与 Alpine 均有）构建的容器，它使用 Let's Encrypt 免费证书机构及其客户端 certbot，自动创建并续期网站 SSL 证书，同时自动生成 Diffie-Hellman 参数用于初始握手加密套件。
一、项目官方信息
| 项目 | 信息 |
|---|---|
| GitHub 仓库 | https://github.com/JonasAlfredsson/docker-nginx-certbot |
| Docker Hub 镜像 | https://hub.docker.com/r/jonasal/nginx-certbot |
| 开源协议 | MIT |
| 主要语言 | Shell（约 90.1%） |
| Star 数 | 约 1.2k |
| 证书来源 | Let's Encrypt（certbot 客户端） |
该容器的亮点：一次请求可处理多个服务器名（如同时包含 example.com 与 www.example.com）；配合 DNS 认证可签发泛域名证书；可同时签发 RSA 与 ECDSA 证书；自动创建 DH 参数；沿用 Nginx 官方镜像的 /docker-entrypoint.d/ 目录；停止/被杀/失败时返回正确退出码；发送 SIGHUP 即可热重载配置而无需重启容器；支持借助本地 CA 离线使用；Debian 与 Alpine 镜像支持多架构。
二、官方图片
下图是该项目仓库在 GitHub 上的官方预览图：
三、环境要求
- 已安装 Docker（https://docs.docker.com/engine/install/ ）。
- 拥有一个已正确解析到服务器 IP 的域名；若在 NAT 后面，需正确转发 80 与 443 端口（可使用 DuckDNS 等动态 DNS）。
- 首次启动较慢，因为容器会自动生成 Diffie-Hellman 参数（默认 2048 位），请耐心等待。
- 建议先阅读项目 docs 中前两节，了解基础 server 配置写法与如何使用 Let's Encrypt 预发环境（staging）避免触发速率限制。
四、完整部署步骤
1. 准备自定义 Nginx 配置目录
在宿主机新建 user_conf.d/ 目录，把你自己的 server 配置文件放进去（参考仓库 examples 目录里的 example_server.conf）。该目录会以只读方式挂载进容器的 /etc/nginx/user_conf.d。
同时准备一个持久化目录 nginx_secrets，用于保存已签发的证书与 DH 参数（挂载到容器的 /etc/letsencrypt）。
2. 用 docker run 启动
docker run -it -p 80:80 -p 443:443 \
--env CERTBOT_EMAIL=your@email.org \
-v $(pwd)/nginx_secrets:/etc/letsencrypt \
-v $(pwd)/user_conf.d:/etc/nginx/user_conf.d:ro \
--name nginx-certbot jonasal/nginx-certbot:latest
-p 80:80 -p 443:443：暴露 HTTP/HTTPS 端口；CERTBOT_EMAIL：必填，Let's Encrypt 用于在安全问题发生时联系你；- 两个
-v：分别持久化证书目录、只读挂载你的 Nginx 配置目录； - 镜像建议使用具体 tag（
jonasal/nginx-certbot:latest不保证 100% 稳定），可用Ctrl+P再按Ctrl+Q脱离容器。
3. 用 docker-compose 启动
仓库 examples/ 目录提供了 docker-compose.yml 与 nginx-certbot.env 示例。把自定义 server 配置放进 user_conf.d/ 后执行：
docker-compose up
nginx-certbot.env 里的默认参数可被 yaml 中 environment: 覆盖；environment: 与 env_file: 可单独或组合使用，唯一要求是必须在某处定义 CERTBOT_EMAIL。
4. 修改配置后热重载
容器就绪后，改动配置文件无需重启容器，向容器发送 SIGHUP 即可让脚本和 Nginx 全部重载：
docker kill --signal=HUP <container_name>
5. 自定义 Dockerfile 自建镜像
如果你想把配置直接打进镜像，可跳过 user_conf.d/，把文件复制到 Nginx 的 conf.d/：
FROM jonasal/nginx-certbot:latest
COPY conf.d/* /etc/nginx/conf.d/
注意自建前请先理解镜像内已有配置如何与 certbot 协同工作。
五、使用方法
环境变量
必填：
| 变量 | 说明 |
|---|---|
CERTBOT_EMAIL |
你的邮箱，Let's Encrypt 安全通知用 |
可选：
| 变量 | 默认值 | 说明 |
|---|---|---|
DHPARAM_SIZE |
2048 |
Diffie-Hellman 参数位数 |
ELLIPTIC_CURVE |
secp256r1 |
ECDSA 密钥曲线 |
RENEWAL_INTERVAL |
8d |
certbot 续期检查间隔 |
RSA_KEY_SIZE |
2048 |
RSA 密钥位数 |
STAGING |
0 |
设为 1 使用 Let's Encrypt 预发环境 |
USE_ECDSA |
1 |
设为 0 改用 RSA 证书 |
高级：
| 变量 | 默认值 | 说明 |
|---|---|---|
CERTBOT_AUTHENTICATOR |
webroot |
响应挑战用的认证插件 |
CERTBOT_DNS_PROPAGATION_SECONDS |
certbot 默认 | DNS 挑战等待传播秒数 |
CERTBOT_DNS_CREDENTIALS_DIR |
/etc/letsencrypt |
DNS 认证凭据目录 |
DEBUG |
0 |
设为 1 开启调试并使用 nginx-debug |
USE_LOCAL_CA |
0 |
设为 1 启用本地 CA（离线使用） |
卷说明
/etc/letsencrypt：存放已获取的证书与 Diffie-Hellman 参数，务必持久化挂载。
测试
在仓库根目录用 BATS 运行测试：
docker run -it --rm -v "$(pwd):/workdir" ffurrer/bats:latest ./tests
六、常见问题 FAQ
1. 为什么容器第一次启动要等很久？ 首次启动时容器会自动生成 Diffie-Hellman 参数（默认 2048 位），这一步比较耗时，属正常现象。之后重启会快很多。
2. 调试阶段如何避免触发 Let's Encrypt 速率限制？
把环境变量 STAGING=1 打开，使用 Let's Encrypt 的预发环境签发测试证书，确认流程无误后再切回正式环境。
3. 如何签发泛域名证书？
泛域名证书需要用 DNS 认证（CERTBOT_AUTHENTICATOR 配置为对应的 DNS 插件），并准备好 DNS 凭据目录，详见仓库 docs 中 certbot_authenticators 文档。
4. 想同时用 RSA 和 ECDSA 证书怎么办？
镜像支持多证书配置，可同时请求 RSA 与 ECDSA 两张证书，参考 docs 中 advanced_usage 的 multi-certificate 章节；USE_ECDSA=0 则只签发 RSA。
5. 改了 Nginx 配置要重启容器吗？
不用。向容器发送 SIGHUP 即可热重载：docker kill --signal=HUP nginx-certbot。
6. 为什么不推荐直接用 :latest？
README 明确建议 docker pull 时使用具体 tag，因为 :latest 可能并非 100% 稳定。所有可用 tag 见 docs/dockerhub_tags.md 或 Docker Hub 页面。
七、跳转链接
- GitHub 仓库：https://github.com/JonasAlfredsson/docker-nginx-certbot
- Docker Hub 镜像：https://hub.docker.com/r/jonasal/nginx-certbot
- 官方文档（Good to Know / Advanced Usage / Certbot Authenticators）：https://github.com/JonasAlfredsson/docker-nginx-certbot/tree/master/docs