Certbot NS1 DNS插件Docker镜像文档

镜像概述和主要用途

本镜像为EFF（电子前哨基金会）官方构建的Certbot Docker镜像，集成了NS1 DNS插件。Certbot是一款免费开源的SSL/TLS证书管理工具，可自动获取和续期Let's Encrypt等证书颁发机构的证书。NS1 DNS插件允许Certbot通过DNS-01挑战验证域名所有权，适用于域名DNS由NS1托管的场景。

主要用途：通过NS1 DNS服务执行DNS-01挑战，为域名自动获取、续期SSL/TLS证书，无需开放HTTP/HTTPS端口（80/443）。

核心功能和特性

核心功能

• DNS-01挑战支持：通过NS1 DNS服务自动添加和删除DNS TXT记录，完成域名所有权验证（符合ACME协议的DNS-01挑战流程）。
• 证书生命周期管理：支持获取新证书、续期现有证书、吊销证书等操作。
• NS1服务集成：通过NS1 API与NS1 DNS服务直接交互，无需手动操作DNS记录。

特性

• 官方维护：基于EFF官方Certbot镜像构建，确保兼容性、安全性和更新及时性。
• 轻量级：优化镜像体积，基于Alpine或Debian Slim基础镜像（具体取决于Certbot官方基础镜像版本）。
• 自动化支持：可通过命令行参数或配置文件实现全自动化证书管理，支持非交互式运行。
• 证书持久化：支持挂载本地目录存储证书和配置，避免容器重启后数据丢失。

使用场景和适用范围

适用场景

• 域名DNS由NS1托管：需为NS1管理的域名获取SSL/TLS证书。
• 无法开放HTTP/HTTPS端口：服务器因网络策略或安全限制无法开放80/443端口（不适用HTTP-01挑战）。
• 多域名或通配符证书：需为通配符域名（如*.example.com）或多个域名批量获取证书（DNS-01挑战支持通配符证书）。
• 自动化运维环境：需在Docker容器中集成证书自动管理流程（如CI/CD流水线、容器化服务部署）。

不适用场景

• 域名DNS非NS1托管（需使用对应DNS服务商的Certbot插件）。
• 可通过HTTP-01挑战验证域名（直接使用基础Certbot镜像更简单）。

详细使用方法和配置说明

前置条件

1. NS1账户及API密钥：需拥有NS1账户，创建具备DNS记录管理权限的API密钥（创建路径：NS1控制台 > 账户 > API密钥）。
2. 域名所有权：需确保目标域名的DNS由NS1托管，且API密钥有权限修改该域名的DNS记录。
3. Docker环境：已安装Docker Engine（20.10+推荐）或Docker Compose（v2+推荐）。

基础使用流程

1. 配置NS1 API密钥（通过环境变量或配置文件传入）。
2. 运行容器，执行Certbot命令获取/续期证书。
3. 挂载本地目录持久化存储证书（默认路径/etc/letsencrypt）。

证书获取示例（Docker Run）

1. 首次获取证书

通过docker run命令直接运行容器，指定NS1 API密钥、目标域名及证书存储路径：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \  # 挂载本地目录持久化证书和配置
  -e NS1_API_KEY="your_ns1_api_key" \    # 注入NS1 API密钥（替换为实际密钥）
  certbot/dns-ns1 \                      # 镜像名称（根据实际镜像标签调整，如:v1.7.0）
  certonly \                             # Certbot子命令：获取证书
  --dns-ns1 \                            # 指定使用NS1 DNS插件
  --non-interactive \                    # 非交互式模式（自动化必备）
  --agree-tos \                          # 同意Let's Encrypt服务条款
  --email "***" \         # 管理员邮箱（用于证书通知）
  --domains "example.com,*.example.com"  # 目标域名（支持多个域名或通配符）

2. 证书续期

Certbot默认支持自动续期（证书到期前30天触发），可通过renew子命令手动触发：

docker run -it --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -e NS1_API_KEY="your_ns1_api_key" \
  certbot/dns-ns1 \
  renew \                                # Certbot续期子命令
  --dns-ns1 \
  --non-interactive \
  --force-renewal                        # 强制续期（测试用，生产环境建议省略）

Docker Compose配置示例

创建docker-compose.yml文件，集成证书持久化和自动续期：

version: '3.8'

services:
  certbot-ns1:
    image: certbot/dns-ns1:v1.7.0  # 指定镜像版本（推荐固定版本而非latest）
    container_name: certbot-ns1
    environment:
      - NS1_API_KEY=your_ns1_api_key  # 替换为实际NS1 API密钥
    volumes:
      - ./letsencrypt:/etc/letsencrypt  # 本地目录挂载，持久化证书和配置
      - ./certbot-logs:/var/log/letsencrypt  # 可选：挂载日志目录
    command: certonly --dns-ns1 --non-interactive --agree-tos --email *** --domains example.com,*.example.com
    restart: "no"  # 证书获取为一次性任务，无需常驻（续期通过cron或Certbot定时器实现）

续期自动化配置

方法1：使用Certbot内置定时器（推荐）

Certbot镜像内置certbot renew命令，可通过系统crontab或Docker Compose定时任务触发：

系统crontab示例（每天凌晨3点执行续期检查）：

0 3 * * * docker run --rm -v /path/to/letsencrypt:/etc/letsencrypt -e NS1_API_KEY=your_key certbot/dns-ns1 renew

方法2：Docker Compose与外部定时工具（如cron容器）

通过ofelia等定时任务容器触发Certbot续期：

# docker-compose.yml 补充内容
services:
  ofelia:
    image: mcuadros/ofelia:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: daemon --config /etc/ofelia/config.ini
    configs:
      - source: ofelia-config
        target: /etc/ofelia/config.ini

configs:
  ofelia-config:
    content: |
      [job-exec "certbot-renew"]
      schedule = 0 3 * * *
      container = certbot-ns1
      command = certbot renew --dns-ns1 --non-interactive

配置参数和环境变量说明

必要环境变量

Certbot核心命令参数

数据持久化路径

注意事项

1. API密钥安全：NS1_API_KEY具有DNS记录修改权限，需严格保密，避免暴露在代码仓库或日志中（建议通过环境变量文件或Docker Secrets管理，而非明文写在命令或配置文件中）。
2. 版本固定：生产环境建议使用固定镜像版本（如v1.7.0），避免因latest标签自动更新导致兼容性问题。
3. 证书备份：/etc/letsencrypt目录包含所有证书和私钥，建议定期备份，防止数据丢失。
4. API权限最小化：NS1 API密钥应仅授予目标域名的DNS记录修改权限，遵循最小权限原则。
5. 日志监控：建议监控Certbot日志（/var/log/letsencrypt），及时发现续期失败等问题（如API密钥过期、DNS解析延迟）。