跳到主要内容
安装配置教程

Docker SSL 证书安装实战:Nginx 容器挂载、Let’s Encrypt 续期与 6 类报错排查

docker ssl证书安装 — Docker SSL 证书安装实战:Nginx 容器挂载、Let's Encrypt 续期与 6 类报错排查
核心结论

Docker 里的 SSL 证书安装本质是文件挂载:把宿主机的 fullchain.pem 与 privkey.pem 以只读卷挂到容器(如 -v /etc/letsencrypt:/etc/letsencrypt:ro),再在 Nginx 的 listen 443 ssl 中引用路径,Docker 本身不提供证书签发功能。 Nginx 官方镜像 1.25.4 默认配置目录是 /etc/nginx/conf.d,证书推荐放 /etc/letsencrypt/live/你的域名/,私钥权限 600、证书 644;容器内 worker 用户 nginx 的 UID 通常为 101,权限不匹配会报 Permission denied。 Let's Encrypt 证书有效期 90 天,certbot 2.10.0 续期后必须重载 Nginx:certbot renew --deploy-hook 'docker exec nginx nginx -s reload',否则进程仍使用内存中的旧证书。 验证命令:openssl s_client -connect example.com:443 -servername example.com -tls1_3 /dev/null | openssl x509 -noout -issuer -dates,看到 Verify return code: 0 (ok) 且日期正确才算生效。 若你指的是 Docker daemon 远程 API 的 TLS,需要 ca.pem、server-cert.pem、server-key.pem 三件套,dockerd 监听 2376 并加 --tlsverify,与网站 443 证书是两套体系。

为什么在 Docker 里装 SSL 证书容易踩坑?两类场景与四个根因

很多人搜“docker ssl证书安装”时,默认想到的是“把 pem 拷进容器”,但真正踩坑的地方往往不在拷贝动作本身,而在场景没分清、文件放错位置、以及续期后忘了重载。先回答第一个高频问题:证书到底该配在哪一层?

对比维度 场景 A:容器内 Web 服务 场景 B:Docker daemon 远程 API 的 TLS
证书用途 对外提供 443 HTTPS,客户端验证服务端身份 客户端与服务端双向验证(mTLS),保护 dockerd 控制通道
必需文件 fullchain.pem + privkey.pem CA 证书、服务端证书、服务端私钥三件套(ca.pem / server-cert.pem / server-key.pem)
配置位置 Nginx/Apache/Node 的 ssl_certificate、ssl_certificate_key dockerd 启动参数 --tlsverify --tlscacert --tlscert --tlskey
端口 443(容器内 80/443 需 -p 映射) 2376(TLS);2375 是明文,切勿暴露公网
# 场景 B:开启 TLS 后 dockerd 只监听 2376,2375 不再对外(Docker 24.x / 25.x 通用)
dockerd 
  --tlsverify                                   # 强制校验客户端证书
  --tlscacert=/etc/docker/ca.pem                # CA 证书,默认无
  --tlscert=/etc/docker/server-cert.pem         # 服务端证书
  --tlskey=/etc/docker/server-key.pem           # 服务端私钥
  -H=fd:// -H=tcp://0.0.0.0:2376                 # 2376 是 TLS 约定端口

# 客户端连接(缺任一参数会报 "certificate signed by unknown authority")
docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem -H=1.2.3.4:2376 ps

根因一:容器的可写层是临时的。据 Docker 官方文档,容器可写层随容器删除而删除,docker cp 进去的证书在 docker rm 后不可恢复。生产环境应挂载宿主机目录或命名卷:

docker run -d --name nginx -p 443:443 
  -v /etc/letsencrypt:/etc/letsencrypt:ro       # 只读挂载证书目录
  -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro 
  nginx:1.25.4                                    # 官方 Debian 镜像

根因二:私钥权限与 worker 用户不匹配。Let’s Encrypt 的 privkey.pem 默认 600、属主 root;而 nginx 官方 Debian 镜像的 worker 进程以 nginx 用户(UID 101、GID 101)运行,于是出现真实报错:nginx: [emerg] cannot load certificate key "/etc/letsencrypt/live/example.com/privkey.pem": Permission denied。解决方式是把私钥组改为 101 并给 640:

chown root:101 /etc/letsencrypt/live/example.com/privkey.pem
chmod 640 /etc/letsencrypt/live/example.com/privkey.pem
# RHEL/CentOS 9 开启 SELinux 时,挂载需加标签:-v /etc/letsencrypt:/etc/letsencrypt:ro,z
# :z 允许多容器共享,:Z 表示该目录为单容器独占

根因三:只挂叶子证书、漏了中间证书。客户端会报 OpenSSL 的 verify error:num=21:unable to verify the first certificate。据 Let’s Encrypt 文档,fullchain.pem 才是“叶子证书 + 中间证书”的完整链,Nginx 的 ssl_certificate 应指向它,私钥仍用 privkey.pem。

根因四:续期成功但服务没重载。Let’s Encrypt 证书有效期 90 天,certbot 默认在到期前 30 天续期;续期只替换磁盘文件,Nginx 不会自动重读。必须挂 deploy hook:

# /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
#!/bin/sh
docker exec nginx nginx -s reload    # 让容器内 Nginx 重新加载新证书
# 赋权后先用 certbot renew --dry-run 验证钩子是否被触发

最后一个常被忽视的反模式:把私钥 COPY 进镜像。私钥会留在镜像层并进入 registry,任何能拉取镜像的人都能导出。据 Docker 官方文档建议,改用 BuildKit secrets 或只读挂载,别把私钥烘焙进镜像。

Docker SSL 证书安装的完整实操步骤(以 Nginx 1.25.4 + certbot 2.10.0 为例)

从裸机到 HTTPS 可跑,一共几步?六步,全部在宿主机侧完成,容器只提供 Nginx 运行时。下面这套 docker ssl 证书安装 流程以 Ubuntu 22.04 + nginx:1.25.4 + certbot 2.10.0 验证通过,命令可直接复制。

步骤 1:域名和 80 端口真的通吗?HTTP-01 校验由 CA 主动回源请求 http://example.com/.well-known/acme-challenge/<token>,据 Let’s Encrypt 文档,校验固定从公网发起、不命中 CDN 缓存。先确认:

# 两条 A 记录都应返回宿主机公网 IP,为空说明解析未生效
dig +short example.com
dig +short www.example.com

# 必须从外部网络验证,本机 curl 会被本地回环骗过
curl -I http://example.com/.well-known/acme-challenge/test

云安全组与 ufw 需放行 80/443;前置 CDN/WAF 时,/.well-known/acme-challenge/ 路径必须放行回源,否则校验返回 403/404,certbot 报 Invalid response from http://example.com/.well-known/acme-challenge/xxx: 404。

步骤 2:certbot 装哪个版本?Ubuntu 22.04(jammy)源里的 certbot 是 1.21.0-1build1,不是 2.x,这点常被忽略:

安装方式 命令 实际版本 续期机制
apt apt update && apt install -y certbot 1.21.0 自带 certbot.timer
snap(官方推荐) snap install --classic certbot 2.10.0+ 自带 certbot.timer
Docker docker run --rm certbot/certbot:v2.10.0 --version 2.10.0 需自行挂载 + cron

验证输出应为 certbot 2.10.0 或更高。

步骤 3:申请证书。

mkdir -p /var/www/certbot
certbot certonly --webroot -w /var/www/certbot 
  -d example.com -d www.example.com 
  --email ops@example.com --agree-tos --no-eff-email

成功后 /etc/letsencrypt/live/example.com/ 下有四个文件:fullchain.pem(= cert + chain,Nginx 的 ssl_certificate 用它)、privkey.pem、chain.pem、cert.pem。注意 live 目录里全是相对符号链接(指向 ../../archive/),因此必须整目录挂载,只挂 live 子目录会报 cannot load certificate ... No such file or directory。

步骤 4:启动容器并挂载证书。

docker run -d --name nginx --restart unless-stopped 
  -p 80:80 -p 443:443 
  -v /etc/letsencrypt:/etc/letsencrypt:ro 
  -v /var/www/certbot:/var/www/certbot:ro 
  -v /opt/nginx/conf.d:/etc/nginx/conf.d:ro 
  nginx:1.25.4

# 确认三个挂载点都在,且 RW=false
docker inspect nginx --format '{{json .Mounts}}'

步骤 5:写 443 server 块并重载。配置落到 /opt/nginx/conf.d/default.conf:

server {
    listen 443 ssl;
    http2 on;                              # 1.25.1 起推荐,替代 listen 443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;         # nginx 默认含 TLSv1/1.1,必须显式覆盖
    ssl_session_cache shared:SSL:10m;      # 默认 off
    ssl_session_timeout 1d;

    location / { root /usr/share/nginx/html; index index.html; }
}

密码套件建议直接采用 Mozilla SSL Configuration Generator 的 intermediate 配置。先 docker exec nginx nginx -t,看到 syntax is ok 与 test is successful 再 docker exec nginx nginx -s reload;reload 是平滑重载,旧 worker 处理完存量连接才退出,不断连。

步骤 6:自动续期怎么配才不翻车?

certbot renew --dry-run

# 每天 03:17 与 15:17 各跑一次;--deploy-hook 仅在真正签发新证书后执行
17 3,15 * * * certbot renew --quiet --deploy-hook 'docker exec nginx nginx -s reload'

据 Let’s Encrypt 文档,证书有效期 90 天、官方建议每 60 天续期;renew 只在剩余不足 30 天时才真正签发,所以一天跑两次安全且推荐。别把 --deploy-hook 和 --post-hook 混用,后者无论是否续期都会执行。若 certbot 由 snap 安装,certbot.timer 已承担续期,再写 crontab 会重复申请,可能触发每域名每周 50 张的 rate limit。至此这套 docker ssl 证书安装 流程闭环,后续排查集中在校验失败、挂载断链、证书过期三类。

关键配置与命令示例:Nginx、docker-compose 与 Docker daemon TLS

把 Docker 里的 SSL 拆开看,其实是三条互不相干的链路:Nginx 对外提供 443 握手、certbot 续期时对 80 端口的 ACME 校验、以及 dockerd 自身 2376 端口的双向 TLS。任一条配错都会表现为“证书装了但不生效”。下面按这三层给可直接复制的片段。

Nginx 1.25.4 的 443 片段怎么写?注意 http2 on; 是 1.25.1 才引入的独立指令,旧写法 listen 443 ssl http2; 从 1.25.1 起会打印 deprecated 警告(Nginx 官方 changelog)。

# /etc/nginx/conf.d/example.conf  (nginx 1.25.4 验证通过)
server {
    listen 443 ssl;
    http2 on;                                   # 1.25.1+ 写法;1.24 及以下仍用 listen 443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;  # 必须 fullchain,缺中间证书安卓/iOS 会报不受信任
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols       TLSv1.2 TLSv1.3;        # RFC 8446 定义 TLS 1.3;1.2 保留兼容旧客户端
    ssl_session_cache   shared:SSL:10m;         # 10MB 约可缓存 4 万会话
    ssl_session_timeout 1d;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
}

80 端口既要跳转又要放行 ACME 校验,冲突吗?不冲突,用 location 优先级把 /.well-known/acme-challenge/ 单独放行即可。但 webroot 路径必须与 certbot -w 完全一致,否则续期日志里就是 404,这是 Let’s Encrypt 文档明确要求的校验路径约定。

server {
    listen 80;
    server_name example.com www.example.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }   # 与 certbot -w /var/www/certbot 必须同路径
    location / { return 301 https://$host$request_uri; }
}

docker-compose 里怎么把两者串起来?Compose v2.24+ 写法如下,certbot 容器每 12 小时自查一次:

services:
  nginx:
    image: nginx:1.25.4
    ports: ["80:80", "443:443"]
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt:ro        # 只读挂载,防止误删私钥
      - /var/www/certbot:/var/www/certbot:ro
      - ./conf.d:/etc/nginx/conf.d:ro
  certbot:
    image: certbot/certbot:v2.10.0
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt
      - /var/www/certbot:/var/www/certbot
    entrypoint: /bin/sh -c 'trap exit TERM; while :; do certbot renew --webroot -w /var/www/certbot --deploy-hook "docker exec nginx nginx -s reload"; sleep 12h & wait $${!}; done'

坑在这里:certbot/certbot 镜像内没有 docker CLI,--deploy-hook 里的 docker exec 会直接失败并报 docker: not found。更稳的做法是去掉 hook,改为在宿主机 cron 里执行 docker compose exec nginx nginx -s reload,共享卷已经保证了新证书可见。

Docker daemon 自身的 TLS 证书怎么签发?用 OpenSSL 3.0.13 自建 CA,关键是签名时必须 -copy_extensions copy,否则 SAN 不会进入最终证书,客户端会报 x509: certificate relies on legacy Common Name field。

openssl genrsa -aes256 -out ca-key.pem 4096
openssl req -new -x509 -days 3650 -sha256 -key ca-key.pem -out ca.pem -subj '/CN=docker-ca'

# 服务端证书:SAN 必须写全域名 + IP
openssl req -newkey rsa:4096 -nodes -sha256 -keyout server-key.pem -out server.csr 
  -subj '/CN=docker.example.com' -addext 'subjectAltName=DNS:docker.example.com,IP:10.0.0.10'
openssl x509 -req -CA ca.pem -CAkey ca-key.pem -CAcreateserial 
  -in server.csr -out server-cert.pem -days 3650 -sha256 -copy_extensions copy

# 客户端证书同理,用同一 CA 签发 client-cert.pem / client-key.pem
openssl req -newkey rsa:4096 -nodes -sha256 -keyout client-key.pem -out client.csr -subj '/CN=client'
openssl x509 -req -CA ca.pem -CAkey ca-key.pem -CAcreateserial 
  -in client.csr -out client-cert.pem -days 3650 -sha256 -copy_extensions copy

启动与验证:

dockerd --tlsverify --tlscacert=/etc/docker/ca.pem 
  --tlscert=/etc/docker/server-cert.pem --tlskey=/etc/docker/server-key.pem 
  -H=0.0.0.0:2376 -H=unix:///var/run/docker.sock

# 客户端:ca.pem / cert.pem / key.pem 放入 ~/.docker(文件名是 Docker 约定,不能改)
export DOCKER_HOST=tcp://docker.example.com:2376 DOCKER_TLS_VERIFY=1 DOCKER_CERT_PATH=~/.docker
docker info   # 能返回 Server Version 即握手成功
文件 客户端约定名 用途
ca.pem ~/.docker/ca.pem 校验服务端证书链
client-cert.pem ~/.docker/cert.pem 客户端身份(双向 TLS)
client-key.pem ~/.docker/key.pem 客户端私钥,权限应为 0600

参数基线别照抄旧教程。ssl_protocols TLSv1.2 TLSv1.3 已是下限,ssl_ciphers 直接取 Mozilla SSL Configuration Generator 的 intermediate 档;ssl_prefer_server_ciphers 建议保持默认 off——TLS 1.3 的密码套件顺序由客户端决定,设成 on 只对 TLS 1.2 有意义,且会削弱前向兼容。这也是很多 docker ssl证书安装 教程里 HTTPS 能通但 Lighthouse 仍提示降级的原因。

方案选型:证书挂载、镜像内置、Docker secrets 与反向代理怎么选?

选型的唯一判据不是“哪种方案更现代”,而是三个具体问题:私钥最终落在哪一层、谁触发续期、续期后进程如何重新加载。这三问定了,方案基本就定了;剩下的只是权限和 SELinux 的细节。

方案 证书存放位置 续期/更新方式 适用场景 主要代价
宿主机目录只读挂载 宿主机 /etc/letsencrypt 挂到容器 /etc/letsencrypt:ro certbot renew + nginx -s reload 单机、小规模、Compose 需处理 uid 101 读权限与 SELinux :z
构建进镜像 COPY fullchain.pem /etc/nginx/certs 换证书即重建镜像并推 registry 不可变基础设施、离线环境 私钥进入镜像层,泄露面大,不推荐
Docker secrets(Compose/Swarm) /run/secrets/tls_cert、/run/secrets/tls_key Compose 重建容器;Swarm 用 docker secret + service update --force 多服务共享、避免明文环境变量 默认 0444、属主 root,更新链路长
反向代理终止 TLS 宿主机 Nginx / Traefik / Caddy 代理层自动续期 多容器共享 80/443 入口 需正确传 X-Forwarded-Proto,否则重定向循环
certbot 容器共享命名卷 命名卷 letsencrypt:/etc/letsencrypt 容器内循环 renew 全容器化、无宿主机依赖 卷备份、docker exec 权限与 reload 通道要设计

为什么默认推荐“宿主机目录只读挂载”?

因为它把证书生命周期和容器生命周期彻底解耦:换证书只动宿主机文件,容器不重建、不重启、不重拉镜像,回滚就是把旧文件换回来再 reload 一次。据 Let’s Encrypt 文档,证书有效期 90 天,官方客户端会在到期前 30 天开始尝试续期,配合 deploy hook 可长期无人值守运行。

# 1) 签发(webroot 模式,不占用 80 端口,可与 Nginx 共存)
sudo certbot certonly --webroot -w /var/www/certbot 
  -d example.com -d www.example.com

# 2) 修复权限:live/ 与 archive/ 默认 0700 root:root,
#    容器内 nginx worker(uid/gid 101,见 Docker Hub nginx 镜像文档)读不到,
#    典型报错:
#    nginx: [emerg] cannot load certificate "/etc/letsencrypt/live/example.com/fullchain.pem":
#    BIO_new_file() failed (SSL: error:8000000D:system library::Permission denied)
sudo chmod 755 /etc/letsencrypt/live /etc/letsencrypt/archive
sudo chmod 644 /etc/letsencrypt/archive/example.com/fullchain.pem
sudo chmod 640 /etc/letsencrypt/archive/example.com/privkey.pem
sudo chgrp -R 101 /etc/letsencrypt/archive /etc/letsencrypt/live   # 让 uid 101 通过组读私钥

# 3) 只读挂载启动(SELinux  enforcing 的 CentOS/RHEL 必须加 :z)
docker run -d --name nginx-tls 
  -p 80:80 -p 443:443 
  -v /etc/letsencrypt:/etc/letsencrypt:ro 
  -v /var/www/certbot:/var/www/certbot:ro 
  -v /etc/nginx/conf.d:/etc/nginx/conf.d:ro 
  --restart unless-stopped 
  nginx:1.27-alpine

# 4) 续期后自动热加载:/etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
#    chmod +x 后由 certbot.timer / cron 自动调用
#!/bin/sh
docker exec nginx-tls nginx -t && docker exec nginx-tls nginx -s reload

为什么不建议把证书 COPY 进镜像?

因为镜像层是永久的:docker history 能翻到,私有 registry 被拉走就等于私钥泄露。多阶段构建也救不了——中间层仍在构建缓存里。若确实必须内置,用 BuildKit 的 secret 挂载而不是 ARG/COPY,并在 .dockerignore 里排除 *.pem、*.key:

# syntax=docker/dockerfile:1.7
FROM nginx:1.27-alpine
# secret 只在构建期挂载,不进 docker history;但 install 后仍会写入最终层,
# 因此这只是"降低暴露面",不是"安全内置"
RUN --mount=type=secret,id=tls_key,required=true 
    --mount=type=secret,id=tls_cert,required=true 
    install -m 0400 /run/secrets/tls_key  /etc/nginx/certs/tls.key && 
    install -m 0444 /run/secrets/tls_cert /etc/nginx/certs/tls.crt

# 构建:docker build --secret id=tls_key,src=./privkey.pem 
#                    --secret id=tls_cert,src=./fullchain.pem -t app:1.0 .

Docker secrets 在 Compose 和 Swarm 里行为一样吗?

不一样。据 Docker 文档,Compose v2 在非 Swarm 模式下把 secret 以 bind mount 形式挂到 /run/secrets/<名称>,默认权限 0444、属主 root,且 Compose 规范里的 uid/gid/mode 三个字段在非 Swarm 模式下不生效;Swarm 模式下 secret 不可变,更新必须先 docker secret create 新对象,再用 --force 触发服务重新挂载。

# compose.yaml(Compose v2)
services:
  web:
    image: nginx:1.27-alpine
    ports: ["443:443"]
    secrets: [tls_cert, tls_key]
secrets:
  tls_cert:
    file: /etc/letsencrypt/live/example.com/fullchain.pem
  tls_key:
    file: /etc/letsencrypt/live/example.com/privkey.pem
# 宿主机文件更新后必须重建容器才会重新挂载:
# docker compose up -d --force-recreate web

# Swarm:secret 不可变,只能换新对象
docker secret create tls_cert_v2 /etc/letsencrypt/live/example.com/fullchain.pem
docker service update --force 
  --secret-rm tls_cert 
  --secret-add source=tls_cert_v2,target=tls_cert 
  web

反向代理终止 TLS 时,后端为什么会 301 循环?

因为后端 Nginx 仍写着 return 301 https://$host$request_uri;,或 WordPress 之类的应用检测不到 X-Forwarded-Proto 就再次跳 https,浏览器最终报 ERR_TOO_MANY_REDIRECTS。正确做法是后端只监听 80、不再自己跳转,并由代理传入真实协议头。Traefik 2.11 与 Caddy 2.7 均内置 ACME 客户端可自动申请 Let’s Encrypt 证书,是多容器共享 443 入口的省事选择。

# 后端容器:只监听 80,禁止再次 301 到 https
server {
    listen 80;
    location / {
        proxy_pass http://app:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;  # 关键:透传 https
    }
}

规模多大时该换集中式方案?

单机 1–5 个域名,宿主机 certbot + 只读挂载最省事;到 10 个以上域名或多节点,每台机器各自 renew 会造成证书版本漂移,部分节点过期很难第一时间发现,此时应上 Vault PKI 或 Kubernetes 的 cert-manager 统一签发。日常巡检用一条命令即可核对容器内实际生效的证书:

# 对比宿主机与容器内证书到期时间,不一致说明挂载或 reload 没生效
openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -enddate
docker exec nginx-tls sh -c 'openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -enddate 2>/dev/null || echo "容器内无 openssl,改用挂载路径核对"'

常见错误与排查:从真实报错定位证书、权限与证书链问题

容器里证书出问题,报错信息往往只给一行 errno,真正的原因在宿主机挂载、文件权限或证书链。下面按 6 类真实报错逐一拆解,每条都给可复制的定位命令。

1. BIO_new_file() failed ... No such file or directory
Nginx 根本没看到文件,先分清是”挂载没进去”还是”路径写错”。据 Docker 官方文档,docker inspect 的 .Mounts 字段会列出每个挂载的 Source(宿主机)与 Destination(容器内):

# 查看容器实际挂载表,确认 Source 是否指向证书目录
docker inspect nginx --format '{{json .Mounts}}' | jq .

# 再看容器内目标路径下到底有什么
docker exec nginx ls -l /etc/nginx/certs
# 期望输出示例:
# -rw-r--r-- 1 root root 3841 Mar  2 10:11 fullchain.pem
# -rw-r----- 1 root root 1704 Mar  2 10:11 privkey.pem

如果 ls 报 “No such file or directory”,说明 Source 写错(相对路径会按 daemon 工作目录解析)或 Destination 与 nginx.conf 里的 ssl_certificate 不一致。Docker 20.10+ 支持 --mount type=bind,source=/abs/path,target=/etc/nginx/certs,readonly,比 -v 更早暴露源路径不存在的问题(-v 会静默创建一个空目录,这正是”文件消失”的经典陷阱)。

2. key values mismatch(证书与私钥不配对)
RSA 证书用 modulus 比对,两者 MD5 必须一致;ECDSA 证书没有 modulus,改用公钥比对。据 OpenSSL 3.0 文档,x509 -pubkey 可直接导出证书内公钥:

# RSA 证书
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem  | openssl md5

# ECDSA 证书(Let's Encrypt 默认签发 ECDSA 时用这条)
openssl pkey -pubout -in privkey.pem
openssl x509 -pubkey -noout -in fullchain.pem

两段输出不同即证明配错——常见于 certbot 续期后私钥更新、而旧 privkey.pem 仍被另一个挂载覆盖。

3. Permission denied(error:8000000D)
官方 nginx 镜像的 worker 进程以 UID 101(nginx 用户)运行,私钥若为 600 root:root 就读不到:

# 让 nginx 组(101)可读,同时保持其他人不可读
chgrp 101 privkey.pem && chmod 640 privkey.pem

# RHEL 9 / CentOS Stream 9 启用 SELinux 时,bind mount 必须重打标签
docker run -d --name nginx 
  -v /etc/letsencrypt/live/example.com:/etc/nginx/certs:ro,z 
  nginx:1.27

注意 :ro,z 中 z 表示私有标签(Z 为共享),不加会在 ausearch -m avc -ts recent 里看到 denied { read }。另一种做法是主进程 root 启动、worker 由 user nginx; 降权,但这只解决属主问题,不解决 SELinux。

4. verify error:num=21:unable to verify the first certificate(证书链不完整)
ssl_certificate 指向了 cert.pem 而非 fullchain.pem。Let’s Encrypt 文档明确要求服务器发送”叶子证书 + 中间证书”,根证书不要发送。验证方法:

# 统计服务端实际下发的证书数量,正常应 ≥ 2
openssl s_client -connect example.com:443 -servername example.com -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

返回 1 就是漏了中间证书。可在 nginx.conf 用 ssl_trusted_certificate 单独指定链文件用于 OCSP stapling,但 ssl_certificate 本身必须包含完整链。

5. curl: (60) unable to get local issuer certificate
区分”服务端链不全”和”客户端 CA 商店过期”,不要用 curl -k 掩盖:

curl -vI https://example.com          # 看 *  SSL certificate verify 段落
openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt fullchain.pem

若本地 openssl verify 通过而 curl 失败,多半是客户端镜像里的 ca-certificates 包过旧(Debian 用 apt-get install --only-upgrade ca-certificates)。

6. Docker daemon TLS:x509: certificate signed by unknown authority
客户端需设置 DOCKER_CERT_PATH 指向含 ca.pem 的目录,且服务端证书 SAN 必须包含实际连接的主机名或 IP。据 Docker 官方 TLS 文档,daemon 侧要同时给 --tlscacert --tlscert --tlskey:

# 核对 SAN 是否覆盖连接地址
openssl x509 -in server-cert.pem -noout -text | grep -A1 'Subject Alternative Name'
# 输出应含:DNS:docker.example.com, IP Address:10.0.0.5

export DOCKER_HOST=tcp://docker.example.com:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/root/.docker
报错特征 根因层 首选定位命令
BIO_new_file / No such file 挂载路径 docker inspect --format '{{json .Mounts}}'
key values mismatch 证书/私钥配对 openssl x509 -noout -modulus
Permission denied 属主 / SELinux docker exec nginx ls -l
num=21 first certificate 证书链缺失 openssl s_client -showcerts
curl (60) local issuer 客户端 CA 商店 openssl verify -CAfile
signed by unknown authority daemon TLS / SAN openssl x509 -text | grep SAN

排查顺序建议自外向内:先用 openssl s_client 从客户端视角看链,再进容器看文件,最后查宿主机权限与 SELinux 审计日志。这样能避免一上来就改 nginx.conf,把挂载问题误判成配置问题。

把证书挂进容器、改完 Nginx 配置,不等于浏览器实际拿到的就是你写的那份配置——镜像自带的 default.conf、include 顺序、多个 server 块抢 listen 443,都会让请求落到别的文件上。完成一次 docker ssl 证书安装后,按下面 6 个动作由内向外验证,每一步都给出明确的通过判据。

1. 容器里的合并配置到底是不是你写的那份?

nginx -T(Nginx 1.9.0 起提供)会打印语法检查后的完整合并配置,比 nginx -t 只看语法更有用,尤其适合排查 include /etc/nginx/conf.d/*.conf 的加载顺序。

# 打印生效中的证书路径、协议版本、443 监听,并标注来源文件
docker exec nginx nginx -T 2>/dev/null | grep -nE 'ssl_certificate|ssl_protocols|listen 443'
# 期望看到:# configuration file /etc/nginx/conf.d/example.conf:12
#   ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
#   ssl_protocols TLSv1.2 TLSv1.3;

注意默认值差异:ssl_protocols 在 Nginx 1.23.4 之前默认是 TLSv1 TLSv1.1 TLSv1.2,1.23.4 及以后才改为 TLSv1.2 TLSv1.3。如果输出里出现了 TLSv1,说明你用的是旧镜像且没显式覆盖。

2. TLS 握手拿到的证书对不对?

openssl s_client -connect example.com:443 -servername example.com -tls1_3 /dev/null 
  | openssl x509 -noout -subject -issuer -dates

-servername(SNI)必须带,否则可能命中默认站点证书。判据三条:Verify return code: 0 (ok);issuer 为 Let’s Encrypt 中间 CA(2024 年 6 月起新签证书使用 R10/R11、ECDSA 用 E5/E6,旧的 R3 已停用);notAfter 在 90 天内——据 Let’s Encrypt 文档,标准证书有效期固定 90 天。

3. HTTP 层是否强制 HTTPS、是否启用 HTTP/2?

curl -sI --tlsv1.3 --http2 https://example.com | head -n 6
# 期望:HTTP/2 200 且含 strict-transport-security: max-age=31536000
curl -sI http://example.com | grep -Ei '^HTTP|^location'
# 期望:HTTP/1.1 301 Moved Permanently + Location: https://example.com/

4. 证书还剩几天,自动续期还活着吗?

# 直接读文件,不依赖任何服务
docker exec nginx openssl x509 -enddate -noout 
  -in /etc/letsencrypt/live/example.com/fullchain.pem
# 查看 certbot 管理的全部证书与剩余天数(VALID: N days)
docker exec certbot certbot certificates

Certbot 默认 renew_before_expiry = 30 days,即剩余 30 天开始续。请确认续期任务真的在跑:systemctl list-timers | grep certbot 或 crontab -l;若账号在 /etc/cron.deny 中,cron 任务会被静默丢弃。

5. OCSP stapling 是否生效?

# nginx.conf 的 server 块内
ssl_stapling on;
ssl_stapling_verify on;
resolver 223.5.5.5 1.1.1.1 valid=300s;   # 必须配 resolver,否则装订不生效
resolver_timeout 5s;
openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -E 'OCSP Response Status|Verify return code'

返回 OCSP Response Status: successful 即装订成功。但据 Let’s Encrypt 2025 年公告,其已分阶段从证书中移除 OCSP URL 并转向 CRL,2025 年 5 月后签发的证书不再带 OCSP URL,此时该字段为空属正常,不应作为故障处理。

6. 外部视角:别只看浏览器绿锁。

# testssl.sh 3.2 系列,--fast 只跑关键项,约 30 秒
./testssl.sh --fast https://example.com

重点看三项:协议是否只开 TLS 1.2/1.3、证书链是否完整(Chain of trust: OK)、是否支持 HSTS。绿锁只证明”当前这条链能验证”,不代表没开 TLS 1.0、不代表链完整、更不代表没有中间证书缺失。

层次 核心命令 通过判据 典型失败表现
配置合并 nginx -T | grep ssl_ 路径与协议均为你写的值 输出里出现镜像默认 /etc/nginx/certs/
TLS 握手 openssl s_client -servername Verify return code: 0 unable to verify the first certificate
HTTP 行为 curl -I --http2 HTTP/2 200 + HSTS 头 返回 HTTP/1.1 200(未开 http2)
到期时间 certbot certificates VALID ≥ 30 天 天数不再下降,续期任务已停
OCSP s_client -status successful 或证书无 OCSP URL 缺 resolver 导致字段为空
外部扫描 testssl.sh --fast 仅 TLS1.2/1.3、链完整 协议含 TLS1.0、链不完整

这 6 步全部通过,才算完成一次可复现的 docker ssl 证书安装验证。任何一步失败,先回到第 1 步确认容器内的合并配置——据 OpenSSL 官方文档,s_client 报出的 Verify return code 只反映你本机信任库的校验结果,若容器内路径写错,外部工具照样会报 certificate verify failed,容易误判为证书本身有问题。

证书续期与容器重载:别让 90 天证书在第 91 天失效

问:certbot 到底什么时候会自动续期,我什么都不做行不行?据 Let’s Encrypt 文档,证书有效期固定 90 天,官方建议在剩余 30 天时续期。certbot 2.10.0 的 renew 不读取命令行域名参数,而是遍历 /etc/letsencrypt/renewal/*.conf 中每个 lineage 的配置,其中 renew_before_expiry = 30 days 是默认值,只有进入这个窗口才会真正签发新证书;没到期就输出 Cert not yet due for renewal 并跳过。所以“装了证书”和“续期链路通了”是两件事,在 docker ssl证书安装 完成后第一件该做的事就是验证续期。

# 1) 模拟续期:不写盘、不消耗速率限制,成功时最后几行是
#    Congratulations, all simulated renewals succeeded:
#      /etc/letsencrypt/live/example.com/fullchain.pem (success)
sudo certbot renew --dry-run

# 2) 真实续期失败时,详细原因(ACME 返回的 detail 字段)在日志里
sudo tail -n 80 /var/log/letsencrypt/letsencrypt.log
sudo grep -iE "error|detail|challenge|timeout" /var/log/letsencrypt/letsencrypt.log

问:nginx 容器怎么感知到新证书?为什么不能写在 pre-hook 里?因为挂载进容器的是文件,nginx 进程启动后把证书读进内存,文件变了它不会自动重载。certbot 的钩子语义差别很关键:pre-hook 在续期之前执行(此时新证书还没落盘,reload 等于白做),deploy-hook 只在证书真正更新成功后执行,--dry-run 下不会触发。所以重载逻辑必须放在 deploy-hook 里。

# 对所有 lineage 生效的全局 deploy 钩子
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
# certbot 2.10.0:仅续期成功且证书文件已更新时执行
set -e
docker exec nginx nginx -t          # 先校验配置,避免 reload 半途失败
docker exec nginx nginx -s reload   # 等价于 nginx -s reload,不中断连接
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

问:用 systemd timer 还是 cron?容器里跑 certbot 行不行?四种常见组合的差异如下表,选型主要看宿主机有没有 systemd、以及 reload 谁来做。

方案 触发者 reload 方式 主要坑
宿主机 certbot + deploy-hook(推荐) certbot.timer 或 cron docker exec nginx -s reload 需宿主机装 certbot 2.x
certbot/certbot 容器 宿主机 cron 调 docker run 容器内无 docker CLI 钩子里写 docker exec 报 docker: not found
容器内 certbot + 挂载 docker.sock 容器内 cron 可调宿主 docker 挂载 socket 等于给容器 root 级权限
宿主机 cron(无 systemd 的精简镜像) cron 绝对路径调用 cron 的 PATH 只有 /usr/bin:/bin
# systemd 环境:certbot.timer 默认每天两次(00:00 / 12:00,带随机延迟)
systemctl list-timers | grep certbot
# NEXT                        LEFT    LAST                        PASSED  UNIT           ACTIVATES
# Mon 2025-01-06 03:41:12 CST 7h left Sun 2025-01-05 15:41:12 CST 8h ago  certbot.timer  certbot.service

# cron 环境:加随机分钟避开整点洪峰,并显式补 PATH 让 docker 可被找到
PATH=/usr/local/bin:/usr/bin:/bin
17 3,15 * * * /usr/bin/certbot renew --quiet --deploy-hook "/usr/bin/docker exec nginx nginx -s reload" >> /var/log/certbot-cron.log 2>&1

问:怎么提前发现“续期已经悄悄失败三个月”?不要只看 certbot 的输出,直接问证书本身:

# 退出码 0 = 30 天内不会过期;1 = 已进入 30 天窗口,需要立刻人工介入
openssl x509 -checkend 2592000 -noout -in /etc/letsencrypt/live/example.com/fullchain.pem 
  || echo "WARN: 证书将在 30 天内过期" | mail -s "TLS 告警" ops@example.com

# 迁移/重建机器前备份,恢复后无需重新签发
sudo tar czf /root/letsencrypt-$(date +%F).tar.gz -C /etc letsencrypt

备份必须覆盖 accounts/(ACME 账户私钥)与 archive/(历史证书),live/ 只是符号链接。据 Let’s Encrypt 速率限制文档,同一注册域名每周最多签发 50 张证书、验证失败每小时 5 次,反复“删了重装”很容易撞上限;而恢复备份后 certbot 会沿用原账户继续续期,这也是 docker ssl证书安装 之后最省事的迁移方式。若把 certbot 放进容器,请让宿主机 cron 在 docker run 结束后再执行 reload,而不是在钩子里调 docker——镜像里根本没有这个二进制。

安全加固:TLS 1.3、HSTS 与容器最小权限

证书签发成功、浏览器小锁亮起,只说明链路加密生效,不代表配置达到了可上生产的安全基线。证书是”有”,加固是”够不够”。下面按协议、HSTS、会话、容器权限、私钥五层给出可落地的配置。

协议基线怎么定?只开 TLS 1.2 和 TLS 1.3,并显式写出来方便审计——nginx 自 1.23.4 起默认值已改为 TLSv1.2 TLSv1.3(见 nginx CHANGES),但老镜像仍是 TLSv1 TLSv1.1 TLSv1.2,不写就可能在 TLS 1.0 上握手成功。据 RFC 8446,TLS 1.3 把完整握手压缩到 1-RTT 并移除了静态 RSA 密钥交换,因此必须具备前向保密。

# /etc/nginx/conf.d/tls.conf —— 适用 nginx:1.25.4(镜像内 OpenSSL 3.0.x)
server {
    listen 443 ssl;
    http2 on;                        # nginx 1.25.1+ 用 http2 指令替代 listen ... http2
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;   # 关键行:显式禁用 TLS 1.0/1.1
    # 下面这行只对 TLS 1.2 生效,TLS 1.3 套件由 OpenSSL 固定
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;   # 与 Mozilla intermediate 配置一致

    ssl_session_cache shared:SSL:10m;  # 默认 none;1MB≈4000 个会话,10m≈4 万
    ssl_session_timeout 1d;            # 默认 5m
    ssl_session_tickets off;           # 默认 on,合规场景常要求关闭

    add_header Strict-Transport-Security "max-age=300" always;  # 灰度期,always 需 nginx 1.7.5+
}
维度 TLS 1.2(RFC 5246) TLS 1.3(RFC 8446)
完整握手往返 2-RTT 1-RTT,会话恢复可 0-RTT
密钥交换 允许静态 RSA(无前向保密) 仅 (EC)DHE,静态 RSA 已删除
ssl_ciphers 是否生效 生效 不生效,套件固定
Nginx 支持前提 任意版本 需 OpenSSL 1.1.1+,用 nginx -V 确认

HSTS 为什么不能一上来就写一年?因为浏览器会缓存这个策略,max-age 期间内用户无法”点继续访问”http 页面。做法是先 max-age=300 跑一到两周,确认全站资源(含 API、CDN 回源、内部子域)都已 HTTPS 后,再逐级调到 31536000。改完必须校验再 reload:

docker exec nginx nginx -t && docker exec nginx nginx -s reload
# 验证实际协商结果
openssl s_client -connect example.com:443 -servername example.com -tls1_3 /dev/null | grep -E "Protocol|Cipher"

includeSubDomains 和 preload 一旦生效几乎不可回滚:前者会让任意一个尚未上 HTTPS 的子域直接不可访问,后者要提交到浏览器预加载列表,移除需数月。提交前请枚举全部子域。会话方面,ssl_session_tickets off 的代价是 TLS 1.2 恢复率下降,在多副本容器里每个副本各自持有 session cache,需要靠一致性哈希或共享票据密钥缓解。

容器如何最小权限运行?Nginx 需要写 /var/cache/nginx 和 pid 文件,只读根文件系统时必须显式挂 tmpfs,否则启动即报 nginx: [emerg] open() "/var/run/nginx.pid" failed (30: Read-only file system):

docker run -d --name nginx 
  --read-only 
  --tmpfs /var/cache/nginx:rw,noexec,nosuid,size=64m 
  --tmpfs /var/run:rw,noexec,nosuid,size=8m 
  -v /etc/letsencrypt:/etc/letsencrypt:ro 
  -p 80:80 -p 443:443 
  nginx:1.25.4

私钥治理同样属于加固范围:chmod 600、属主 root:root,只把 /etc/letsencrypt 以 :ro 挂给真正需要它的容器;certbot 每次续期会重写 archive/ 下的文件,权限要在 deploy-hook 里重置,否则续期后权限被悄悄放宽。据 Let’s Encrypt 文档,续期由 certbot renew 驱动,把 --deploy-hook 'chmod 600 ... && docker exec nginx nginx -s reload' 接上即可一次解决权限与重载。排查时用 docker cp 取出私钥会在宿主机留下副本,用完立刻删除并检查 ~/.bash_history。

推荐只读挂载,例如 docker run -v /etc/letsencrypt:/etc/letsencrypt:ro,证书更新后只需 reload 容器内 Nginx。COPY 进镜像会把私钥留在镜像层与 registry,任何能拉取镜像的人都可能导出;若必须内置,至少用 BuildKit –secret 并排除 *.pem、*.key。

certbot renew 只替换 /etc/letsencrypt/live 下的文件,Nginx 进程仍使用内存中的旧证书。执行 docker exec nginx nginx -s reload 后再用 openssl s_client -connect example.com:443 -servername example.com 查看 notAfter 是否更新;建议把 reload 写进 –deploy-hook。

这是证书与私钥不配对,常见于手工替换了 fullchain.pem 却没换 privkey.pem,或从不同服务器拷贝了文件。RSA 可比对 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 的 MD5,ECDSA 可比对 x509 -pubkey 与 pkey -pubout 的输出。

不是。网站 443 是容器内 Nginx 读取 fullchain.pem 与 privkey.pem;Docker daemon TLS 是 2376 端口使用 ca.pem、server-cert.pem、server-key.pem,并给 dockerd 加 –tlsverify,客户端设置 DOCKER_TLS_VERIFY=1 与 DOCKER_CERT_PATH。两者证书用途、路径和验证方式都不同。

配置层没有区别,都是把 fullchain 证书与私钥挂进容器并在 Nginx 里引用。差异在有效期(Let's Encrypt 90 天,商业证书常见 397 天/1 年)、组织验证、支持服务与赔付条款;Let's Encrypt 更适合配合 certbot 做自动化续期。

先确认容器内运行用户的 UID,再让宿主机私钥组与它匹配,例如 chgrp 101 privkey.pem && chmod 640 privkey.pem;SELinux 环境挂载加 :z 或 :Z。也可以使用 Docker secrets 把私钥以文件形式挂到 /run/secrets,但要注意默认 0444 权限与属主。

单机场景优先宿主机 certbot 2.10 + webroot,简单且能直接 docker exec nginx nginx -s reload。全容器化可用 certbot/certbot:v2.10.0 + 共享卷,但该镜像内没有 docker CLI,deploy-hook 不能直接执行 docker exec,需要另设 reload 通道或挂载 docker.sock(有安全风险)。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。