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

Docker Nginx SSL 配置实战:证书挂载、443 端口与续期 reload 全链路

docker nginx ssl 配置 — Docker Nginx SSL 配置实战:证书挂载、443 端口与续期 reload 全链路
核心结论

docker nginx ssl 配置的核心是三件事:把 fullchain.pem 与 privkey.pem 挂载进容器内的 /etc/nginx/certs、在 server 块写 listen 443 ssl、在 compose 里映射 443:443,三者缺一即报错。 nginx 1.27-alpine 应写 listen 443 ssl; 加 http2 on;,旧的 listen 443 ssl http2; 自 1.25.1 起已标记废弃。 证书续期后必须执行 docker compose exec nginx nginx -s reload,nginx 不会自动读取磁盘上的新证书,重启容器才会强制重载。 验证用 openssl s_client -connect example.com:443 -servername example.com 查看 enddate,用 docker compose exec nginx nginx -T | grep ssl_certificate 确认实际加载的证书路径。 Let's Encrypt 证书有效期 90 天,certbot 在到期前 30 天才真正续期,建议 cron 每天 03:00 跑一次 renew 并挂 --deploy-hook 触发 reload。

为什么 docker nginx ssl 配置经常失败?先看证书路径、端口映射、配置加载三处断点

多数“证书坏了”的判断都是误诊。按发生率排序,docker nginx ssl 配置的故障集中在三处彼此独立的断点:文件有没有进容器、端口有没有通到容器、配置有没有被 include。下面按报错逐一定位。

断点一:宿主机有证书,容器里却没有这个路径?

certbot 默认把证书写入宿主机 /etc/letsencrypt/live/example.com/,容器是独立挂载命名空间,不写 volumes 就完全看不到。此时 nginx 启动报:

[emerg] cannot load certificate "/etc/nginx/certs/fullchain.pem":
BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory)

它表示 fopen() 找不到文件,不是 PEM 损坏。更隐蔽的是符号链接:据 Let’s Encrypt 文档,live/example.com/fullchain.pem 和 privkey.pem 都指向 ../../archive/example.com/。只挂载 live/example.com 单目录,链接在容器内会指向不存在的 archive。正确做法是整目录挂载:

services:
  nginx:
    image: nginx:1.27-alpine
    ports:
      - "80:80"
      - "443:443"          # 宿主机 443 映射到容器 443
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - /etc/letsencrypt:/etc/letsencrypt:ro   # 保留 live -> archive 相对链接

若不想暴露整个 Let’s Encrypt 目录,可用 cp -L 解引用成实体文件:

sudo install -d -m 700 ./certs
sudo cp -L /etc/letsencrypt/live/example.com/fullchain.pem ./certs/
sudo cp -L /etc/letsencrypt/live/example.com/privkey.pem   ./certs/
sudo chmod 600 ./certs/privkey.pem
# 然后挂载 ./certs:/etc/nginx/certs:ro

断点二:只写了 listen 443 ssl,或只写了 ports 443,为什么还是不通?

这是两个独立开关:容器内 listen 443 ssl; 决定 nginx 是否说 TLS;Compose 的 ports: "443:443" 决定宿主机流量是否进来。据 Docker 文档,ports 才创建宿主机端口发布。对照现象:

现象 容器内 listen 443 ssl compose ports 443 根因
curl: (7) connection refused 有 无 宿主机 443 没有监听
浏览器 ERR_SSL_PROTOCOL_ERROR 无,只有 80 明文 有 TLS ClientHello 被当 HTTP 处理
握手成功 有 有 链路完整
docker compose port nginx 443        # 期望输出 0.0.0.0:443
ss -ltnp | grep ':443'               # 宿主机确认监听
curl -vk https://localhost/ -o /dev/null
docker compose exec nginx nginx -t   # 先验配置,再看端口

断点三:server 块写进 nginx.conf 就报 not allowed here?

官方镜像的 /etc/nginx/nginx.conf 在 http {} 内含 include /etc/nginx/conf.d/*.conf;。把 server 追加到文件末尾,往往落在 http 块之外,报:

[emerg] "server" directive is not allowed here in /etc/nginx/nginx.conf:38

把站点配置放进 conf.d/default.conf 即可。版本差异也要注意:nginx 1.25.1 起,listen 443 ssl http2; 中的 http2 参数被废弃,1.27-alpine 会给出 the "listen ... http2" directive is deprecated, use the "http2" directive instead 警告。应写成:

server {
    listen 443 ssl;      # nginx >= 1.25.1
    http2 on;            # 替代 listen ... http2
    server_name example.com;
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
}

权限链路:为什么 root 能读、容器用户读不了?

官方镜像 master 以 root 启动、worker 降为 nginx 用户,privkey.pem 为 600 且属主 root 时通常正常。但若 Compose 写了 user: "1000:1000",master 本身变成 1000,读取 root:600 私钥会失败:

SSL_CTX_use_PrivateKey_file() failed (SSL: error:...:system library:fopen:Permission denied)

修复时改私钥属主或补组权限,并确保续期后仍生效:

sudo chown 1000:1000 /etc/letsencrypt/archive/example.com/privkey*.pem
sudo chmod 600 /etc/letsencrypt/archive/example.com/privkey*.pem
# 或保留 root 属主,改为 root:1000 + 640,让容器用户经组读取
docker compose restart nginx

docker nginx ssl 配置的完整步骤:6 步从证书落地到 443 生效

把 docker nginx ssl 配置拆开看,真正容易翻车的环节往往不在 server 块写错,而在于两处:证书链没有放全、续期后没人 reload。下面 6 步按“证书落地 → 权限 → 配置 → 编排 → 校验 → 续期钩子”的顺序走,每一步都给出可直接复制的命令。

第 1 步:拿证书,先决定用 HTTP-01 还是 DNS-01

据 Let’s Encrypt 文档(RFC 8555 定义的 ACME 协议),certbot 3.x 提供两种主流验证方式,选错会直接影响后续能否签泛域名:

维度 HTTP-01(webroot) DNS-01(manual / 插件)
是否需要 80 端口对外可达 是 否
能否签发通配符证书 否 是(*.example.com)
典型命令 certbot certonly --webroot -w /var/www/certbot -d example.com -d www.example.com certbot certonly --manual --preferred-challenges dns -d example.com -d '*.example.com'
适用场景 nginx 已占用 80,续期可全自动 泛域名、内网机器、80 端口被封

商业证书则先在本机生成 CSR(OpenSSL 3.0.x 默认输出 PKCS#8 私钥,nginx 1.11.0 以后可直接读取,无需转换):

# 生成 2048 位 RSA 私钥 + CSR,SAN 必须写全,否则 www 子域会报证书不匹配
openssl req -new -newkey rsa:2048 -nodes 
  -keyout privkey.pem -out example.com.csr 
  -subj '/CN=example.com' 
  -addext 'subjectAltName=DNS:example.com,DNS:www.example.com'

# 验证 CSR 中的 SAN 是否生效
openssl req -in example.com.csr -noout -text | grep -A1 'Subject Alternative Name'

CA 返回的通常是 fullchain.pem(服务器证书 + 中间证书)与 privkey.pem,直接落盘即可。

第 2 步:落盘与权限,只放服务器证书是常见坑

mkdir -p nginx/certs
# -L 必须加:/etc/letsencrypt/live/ 下的文件是符号链接,不加 -L 会拷到一个断链
cp -L /etc/letsencrypt/live/example.com/fullchain.pem nginx/certs/
cp -L /etc/letsencrypt/live/example.com/privkey.pem   nginx/certs/

chmod 644 nginx/certs/fullchain.pem   # 公钥证书,容器内 nginx worker 需可读
chmod 600 nginx/certs/privkey.pem     # 私钥仅 root 可读,nginx master 以 root 启动

若只放服务器证书、漏掉中间证书,Android 7 及部分 Java 客户端会直接抛出 unable to get local issuer certificate——因为终端设备不预置你所用 CA 的中间证书。用 openssl s_client -connect example.com:443 -showcerts 可确认链是否完整。

第 3 步:写 80 跳转 + 443 TLS server 块

# nginx/conf.d/example.com.conf
server {
    listen 80;
    server_name example.com www.example.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }  # 供 webroot 续期
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl;
    http2 on;                                   # nginx 1.25.1+ 语法;旧版用 listen 443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;   # 容器内路径
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;        # nginx 1.23.4 起默认值即为此
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;

    location / { proxy_pass http://app:3000; }
}

参数取值可对照 Mozilla SSL Configuration Generator 的 intermediate 档位,ssl_protocols 默认值在 nginx 1.23.4 之前是 TLSv1 TLSv1.1 TLSv1.2,务必显式覆盖。

第 4 步:写 compose,注意只读挂载

services:
  nginx:
    image: nginx:1.27-alpine
    ports: ["80:80", "443:443"]
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro    # 配置只读,避免容器写回宿主机
      - ./nginx/certs:/etc/nginx/certs:ro
      - ./nginx/www:/var/www/certbot:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 5s
      retries: 3

第 5 步:先 nginx -t 再 up -d

docker compose run --rm nginx nginx -t
# 期望输出:nginx: configuration file /etc/nginx/nginx.conf test is successful

跳过这步直接 up -d,容器会在几秒内反复重启,日志里能定位到具体行号,例如:

nginx: [emerg] cannot load certificate "/etc/nginx/certs/fullchain.pem":
BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory)

第 6 步:接续期钩子,让证书更新后自动热加载

# crontab -e,每天 03:00 检查;certbot 仅在剩余不足 30 天时才会真正续期
0 3 * * * certbot renew --quiet --deploy-hook 'docker compose -f /opt/web/docker-compose.yml exec -T nginx nginx -s reload'

--deploy-hook 只在成功续期时触发,exec -T 关闭 TTY 分配,否则 cron 环境下会报 the input device is not a TTY。注意:renew 更新的是 /etc/letsencrypt/live/ 下的文件,而容器挂载的是 ./nginx/certs/ 的副本,因此钩子里需先 cp -L 同步再 reload;更稳妥的做法是把 /etc/letsencrypt 整个目录只读挂进容器,直接引用 live/example.com/fullchain.pem,省掉复制这一环。

docker nginx ssl 配置示例:docker-compose.yml 与 nginx.conf 的关键参数(nginx 1.27 / OpenSSL 3.0)

下面给出可以直接落地的完整配置骨架。所有片段基于 nginx:1.27-alpine(镜像内置 OpenSSL 3.0.x),路径约定为:证书放宿主机 ./nginx/certs,映射进容器 /etc/nginx/certs。

docker-compose.yml:只读挂载是硬性要求

services:
  nginx:
    image: nginx:1.27-alpine
    container_name: web-nginx
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro   # 站点配置,只读
      - ./nginx/certs:/etc/nginx/certs:ro     # 证书目录,只读:容器内进程无法改写/删除私钥
      - ./www:/usr/share/nginx/html:ro
    restart: unless-stopped

:ro 不只是”保险”:Let’s Encrypt 的 certbot 在宿主机上以 root 身份轮换证书文件,若容器内挂载可写,一旦 nginx 进程被利用(例如恶意配置注入),攻击面直接覆盖到私钥文件。只读挂载让容器内任何写入都返回 Read-only file system。

443 server 块:显式写默认值,换机器行为才一致

server {
    listen 443 ssl;
    http2 on;                                  # 1.25.1 起用 http2 指令替代 listen ... http2
    server_name example.com www.example.com;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;  # 叶子证书 + 中间证书
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    ssl_protocols       TLSv1.2 TLSv1.3;       # 默认值自 1.23.4 起即为这两项
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    ssl_prefer_server_ciphers off;             # 默认 off,交给客户端选,利于 ChaCha20 在移动端生效
    ssl_session_cache   shared:SSL:10m;        # 默认 none;10m 约存 4 万个会话
    ssl_session_timeout 1d;                    # 默认 5m
    ssl_session_tickets off;                   # 默认 on;关掉便于轮换密钥时前向安全

    # OCSP 装订:必须提供签发者证书链
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_trusted_certificate /etc/nginx/certs/chain.pem;

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

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

关于 OCSP:若 chain.pem 缺失,nginx -t 不会失败,只在错误日志里留下 warning: "ssl_stapling" ignored, issuer certificate not found,装订静默失效、启动看似正常——这是最常见的一类”配置了但没生效”。据 Mozilla Server Side TLS 指南,现代客户端对 OCSP 的容错已很强,但 HSTS 与 TLS 1.3 仍是收益最高的两项。参数默认值对照如下:

指令 默认值 显式设置的理由
ssl_protocols TLSv1.2 TLSv1.3(1.23.4 起) 旧版本镜像默认含 TLSv1/1.1,锁定行为
ssl_session_cache none 不设则每次握手全量协商,TLS 1.2 明显变慢
ssl_session_timeout 5m 1d 更适合长连接复用场景
ssl_prefer_server_ciphers off 保持默认,让客户端优先选 ChaCha20
ssl_session_tickets on 关闭以避免 ticket key 泄漏导致历史流量可解

80 server 块:保留 acme-challenge,否则续期 404

server {
    listen 80;
    server_name example.com www.example.com;

    location /.well-known/acme-challenge/ {
        root /var/www/certbot;                 # 与 certbot webroot 指向同一目录
    }
    location / {
        return 301 https://$host$request_uri;  # 其余全部跳 HTTPS
    }
}

如果 location / 的 301 覆盖了 /.well-known/,certbot 的 HTTP-01 校验会拿到 301 或 404 而失败。务必让 acme-challenge 的 location 排在前面(nginx 前缀匹配取最长者,此处天然优先)。据 Let’s Encrypt 文档,HTTP-01 校验要求 80 端口对外可达且路径返回 200。

本地先自签验证链路

openssl req -x509 -newkey rsa:2048 -nodes 
  -keyout privkey.pem -out fullchain.pem -days 365 
  -subj '/CN=localhost' 
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1'
docker compose up -d && docker compose exec nginx nginx -t
curl -vk https://localhost/ -o /dev/null   # 看 * SSL certificate verify result 是否只有自签告警

上线前把自签文件替换为 CA 签发的 fullchain.pem / privkey.pem / chain.pem。另有一个容易忽略的优化点:nginx 自 1.11.0 起支持在同一 server 内写两条 ssl_certificate,分别挂 RSA 与 ECDSA 证书,由客户端按 signature_algorithms 自动选择,ECDSA 证书体积更小、握手更快。

证书续期后 docker nginx ssl 配置如何平滑生效?reload 而不是 restart

为什么磁盘上的证书已经换了,浏览器抓到的还是旧证书?

因为 nginx 只在 master 进程启动或收到 reload 信号时,才会把 ssl_certificate 指向的文件读进内存。certbot 续期只改动了宿主机文件系统,容器里的 nginx 工作进程仍然握有旧的 SSL_CTX。据 nginx 官方文档 Controlling nginx 一节,nginx -s reload 的实际行为是:master 重新解析配置、拉起新的 worker、向旧 worker 发送 QUIT,旧 worker 处理完存量请求后优雅退出,整个切换通常 100–300ms,已有 keepalive 连接不会被打断。所以日常让 docker nginx ssl 配置生效的正确动作是 reload,不是 restart。

# 宿主机执行:先校验再热加载(-T 关闭伪终端,脚本/cron 环境必需)
docker compose -f /opt/web/docker-compose.yml exec -T nginx nginx -t
docker compose -f /opt/web/docker-compose.yml exec -T nginx nginx -s reload
# 等价做法:直接给 master 进程发 HUP
docker compose -f /opt/web/docker-compose.yml kill -s HUP nginx

旧 worker 的最长存活时间由 worker_shutdown_timeout 控制,默认 240s,取值为时间值,上下文为 main;长连接场景下可以调小到 30s 让旧证书更快彻底退场。

操作 命令 80/443 可用性 容器内临时状态 何时用
reload exec -T nginx nginx -s reload 不中断 保留 证书续期、改 nginx.conf、加 server 块(日常首选)
restart docker compose restart nginx 中断约 1–3 秒 重置 /var/cache/nginx、/var/run 不建议用于续期
重建 docker compose up -d nginx 中断,取决于健康检查 重置 改了 compose 的 ports、volumes、environment

符号链接陷阱:为什么 reload 报 “No such file or directory”?

certbot 的目录结构是 archive/example.com/fullchain1.pem 存真实文件、live/example.com/fullchain.pem 是指向 archive 的相对符号链接。若只把 live/example.com 单目录挂进容器,链接目标不在容器内,reload 时 nginx 会直接拒绝:

# nginx: [emerg] cannot load certificate "/etc/nginx/certs/fullchain.pem":
# BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory)
# 正确写法:整目录挂载,保留相对链接的可解析性
volumes:
  - /etc/letsencrypt:/etc/letsencrypt:ro   # 容器内 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

续期后如何自动 reload?用 certbot 的 deploy-hook,它在每次成功续期后执行(certbot renew 默认只在剩余有效期不足 30 天时真正续期,Let’s Encrypt 证书有效期 90 天):

# 写成 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh 并 chmod +x 即可全局生效
certbot renew --deploy-hook 'docker compose -f /opt/web/docker-compose.yml exec -T nginx nginx -s reload'
# 漏写 -T 时,cron 里会报:the input device is not a TTY

怎么确认新证书真的上线了?对比两端 notAfter 是否一致即可:

openssl s_client -connect example.com:443 -servername example.com /dev/null | openssl x509 -noout -dates
docker compose -f /opt/web/docker-compose.yml exec -T nginx openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates

若容器内已是新日期而线上仍是旧日期,说明 reload 未成功,回到 nginx -t 看具体报错行——这也是排查 docker nginx ssl 配置问题时最省时间的一步。

docker nginx ssl 配置的四种落地方案对比:挂载证书、宿主反代、certbot 容器、自动 ACME

先给结论:四种方案没有绝对优劣,取决于你是否需要直接编辑 nginx.conf、容器数量、以及是否愿意在宿主机上装 certbot。下表按”证书落在哪、续期怎么 reload、要不要重建容器”三个维度对齐,其中”是否重建容器”全部为否——因为 nginx -s reload(即向 master 进程发 SIGHUP)会平滑加载新证书,不需要 docker compose up -d 重建。

方案 证书位置 续期与 reload 是否重建容器 适用场景
A 证书挂载进 nginx 容器 宿主机 /etc/letsencrypt 或 ./certs certbot renew + deploy-hook 执行 nginx -s reload 否 单机、容器数 ≤10、需要完全掌控 nginx.conf
B 宿主机 nginx/Caddy 终止 TLS,反代容器 8080 宿主机 宿主机服务自行 reload 否 已有宿主 nginx、容器只跑应用
C certbot 独立容器 + 共享 volume 命名卷 letsencrypt 容器内 renew + docker exec reload 否 不想在宿主机装 certbot
D Traefik / nginx-proxy + ACME 由 label 声明 全自动 否 多域名、服务频繁增减

方案 A 为什么适合做第一个 docker nginx ssl 配置方案?因为 nginx.conf 完全可控、证书路径透明,排错时 docker compose exec nginx ls -l /etc/letsencrypt/live/ 一眼看到 fullchain.pem 与 privkey.pem 是否挂进去了。代价是续期与 reload 要自己写钩子,多台机器各维护一份。最小可用组合如下(nginx 1.27 为 2024 年 mainline,stable 为 1.26):

# docker-compose.yml 片段
services:
  nginx:
    image: nginx:1.27-alpine
    ports: ["80:80", "443:443"]
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - /etc/letsencrypt:/etc/letsencrypt:ro      # 只读,私钥不进镜像层
      - ./certbot-webroot:/var/www/certbot:ro     # HTTP-01 challenge 目录

# 首次签发(webroot 方式,无需停 nginx)
certbot certonly --webroot -w ./certbot-webroot -d example.com 
  --deploy-hook 'docker compose -f /opt/site/docker-compose.yml exec -T nginx nginx -s reload'

据 Let’s Encrypt 文档,证书有效期 90 天,官方建议在剩余 30 天时续期;certbot 的 renew_before_expiry 默认正是 30 天,systemd 环境下由 certbot.timer 每天触发两次并带随机延迟,因此你不需要额外写 cron,只要保证 deploy-hook 里的 nginx -t 先跑通:

#!/bin/sh
# /etc/letsencrypt/renewal-hooks/deploy/10-nginx-reload.sh,chmod +x
set -e
docker compose -f /opt/site/docker-compose.yml exec -T nginx nginx -t
docker compose -f /opt/site/docker-compose.yml exec -T nginx nginx -s reload

方案 B 少一层证书挂载,但多一跳网络,最容易踩的坑是日志里全是 172.17.0.x。必须同时配 proxy_set_header X-Forwarded-For 与 real_ip 模块,缺一不可:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host              $host;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    real_ip_header X-Forwarded-For;
    set_real_ip_from 172.16.0.0/12;   # 只信任 Docker 网段,否则可被伪造
}

方案 C 的坑在 volume 权限:certbot 容器以 root 写 /etc/letsencrypt,而 nginx 容器若用非 root 用户运行,reload 时会直接报错:nginx: [emerg] cannot load certificate key "/etc/letsencrypt/live/example.com/privkey.pem": Permission denied。解决办法是统一 UID(compose 里两边都写 user: "1000:1000"),或把私钥复制到另一目录并 chmod 640 交给 nginx 组。注意 live/ 下是符号链接,指向 ../../archive/,跨卷复制时用 cp -L 跟随链接。

方案 D 自动化程度高,调试成本也高:证书申请失败时日志埋在 traefik 容器的 acme 段里,得用 docker compose logs traefik | grep -i acme 才能看到 challenge 失败原因,典型输出是 acme: error: 429 :: urn:ietf:params:acme:error:rateLimited(Let’s Encrypt 对同一注册域名每周 50 张的重复证书限额)。Traefik 用 label 声明域名(v3 写法与 v2 一致),nginx-proxy 侧则是 nginx-proxy + acme-companion 两个容器,不建议作为第一个 docker nginx ssl 配置方案上手——先用手工挂载把 TLS 握手、证书链、HSTS 跑通,再换成自动 ACME,排错时你能立刻区分”是证书没签下来”还是”nginx 没 reload”。

docker nginx ssl 配置常见报错与排查:从 emerg 日志到端口占用

容器一起来就退出,日志只有一行 emerg,从哪儿下手?

nginx 在 master 进程解析配置阶段就加载证书,加载失败即以退出码 1 终止,worker 从未启动,因此不会留下 access.log。第一步不是改配置,而是确认容器内究竟看见了什么——挂载失败和证书损坏的报错长得完全不同。

# 1) 容器已退出时,用同一挂载路径起一次性容器,看目录里到底是文件还是空目录
docker run --rm -v /opt/nginx/certs:/etc/nginx/certs:ro alpine:3.20 ls -l /etc/nginx/certs

# 2) 查看退出码:1 表示配置或证书加载失败,137 多为 OOM/被杀
docker inspect -f '{{.State.ExitCode}}' nginx

# 3) 打印合并后的完整配置,确认 include 的 server 块里到底有没有 ssl_certificate
docker exec nginx nginx -T | grep -n 'ssl_certificate|listen'

报错 [emerg] cannot load certificate … BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory) 是怎么回事?

据 Docker 官方文档,-v / 短语法 bind mount 在宿主机源路径不存在时会自动创建一个同名空目录,于是同一个配置在宿主机上文件缺失时报 No such file or directory,而挂载源写错成目录时 nginx 读到目录,报 Is a directory。两条报错根因相同,都是”宿主机那侧没准备好”。用长语法并显式关闭自动创建,可让 Docker 在启动时直接报错而不是静默建目录(Compose v2.14+ 支持 create_host_path,默认 true):

services:
  nginx:
    image: nginx:1.27-alpine
    volumes:
      # 长语法 + create_host_path: false,源文件缺失时直接启动失败,不建空目录
      - type: bind
        source: /opt/nginx/certs/fullchain.pem
        target: /etc/nginx/certs/fullchain.pem
        read_only: true
        bind:
          create_host_path: false
      - type: bind
        source: /opt/nginx/certs/privkey.pem
        target: /etc/nginx/certs/privkey.pem
        read_only: true
        bind:
          create_host_path: false

顺带用 openssl x509 -in fullchain.pem -noout -subject -enddate 确认文件本身是合法 PEM 而非 HTML 错误页。

报错 PEM_read_bio_PrivateKey() failed 怎么修?

三种成因:私钥带 passphrase、文件其实是 PKCS#12 二进制、或换行被编辑器改成 CRLF。nginx 不支持交互式输入密码,加密私钥必然失败。

# 首行是 BEGIN ENCRYPTED PRIVATE KEY 即带密码;应为 BEGIN PRIVATE KEY 或 BEGIN RSA PRIVATE KEY
head -1 /opt/nginx/certs/privkey.pem

# 完整性校验:输出 "RSA key ok" 才算正常(EC 私钥改用 openssl ec -in ... -check -noout)
openssl rsa -in /opt/nginx/certs/privkey.pem -check -noout

# 去 passphrase(OpenSSL 3.x,会提示输入原密码)
openssl pkey -in privkey.pem -out privkey.dec.pem

# PKCS#12 转 PEM 私钥(-nodes 表示不再加密)
openssl pkcs12 -in cert.pfx -nocerts -nodes -out privkey.pem

# 修 CRLF 换行
sed -i 's/r$//' privkey.pem

报错 SSL_CTX_use_PrivateKey(…) failed (SSL: error:0A080006:SSL routines::EVP lib) 呢?

这是证书与私钥不配对。要点里的 modulus 比对只适用于 RSA;OpenSSL 1.1.1 起更通用的是比对公钥指纹,ECDSA 证书同样适用:

# 通用做法:两侧公钥的 md5 必须完全一致
openssl x509 -noout -pubkey -in fullchain.pem | openssl md5
openssl pkey -pubkey -noout -in privkey.pem  | openssl md5

# 仅 RSA 可用的传统做法
openssl x509 -noout -modulus -in fullchain.pem | openssl md5
openssl rsa  -noout -modulus -in privkey.pem  | openssl md5

报错 no ‘ssl_certificate’ is defined for the ‘listen … ssl’ directive 为什么改完还是报?

据 nginx 官方 ngx_http_ssl_module 文档,ssl_certificate 与 ssl_certificate_key 可写在 http、server 层并被继承,但某个 listen 443 ssl 的 server 必须能向上继承到这对指令。常见错误是把它们写进了另一个 server 块,或写在 http 块外。用 nginx -t 校验,成功输出为 configuration file /etc/nginx/nginx.conf test is successful。

Bind for 0.0.0.0:443 failed: port is already allocated 怎么办?

宿主机上已有 nginx、apache2 或另一个容器占用 443。用 iproute2 的 ss 定位持有者,再二选一:

ss -lntp | grep ':443'            # 输出 PID/Program name,可能是 nginx 也可能是 docker-proxy
docker ps --filter publish=443    # 确认是不是另一个容器占了端口

# 方案 B:改映射为 8443:443,由外层负载均衡或防火墙把 443 转发进来
# ports: ["8443:443"]

浏览器报 ERR_SSL_PROTOCOL_ERROR,但容器日志干干净净?

典型是 ports 写成了 "443:80":客户端发起 TLS 握手,容器回的是明文 HTTP。用 compose 反查映射,再用 curl 看握手停在哪一步:

docker compose port nginx 443   # 期望输出 0.0.0.0:443,若显示 80 就是映射写错
curl -vI https://example.com 2>&1 | grep -E 'Connected|TLS|SSL|HTTP'
# 出现 error:0A00010B:SSL routines::wrong version number,即服务端回的是明文
日志关键字 根因 一条验证命令
BIO_new_file() failed / Is a directory 宿主机源文件不存在,Docker 自动建成目录 ls -l /opt/nginx/certs
PEM_read_bio_PrivateKey() failed 私钥加密、PKCS#12 或 CRLF 换行 openssl rsa -in privkey.pem -check -noout
EVP lib / key values mismatch 证书与私钥不配对 openssl pkey -pubkey -noout -in privkey.pem | openssl md5
no ‘ssl_certificate’ is defined 指令不在该 server 的作用域链上 nginx -T | grep -n ssl_certificate
Bind for 0.0.0.0:443 failed 宿主机 443 已被其他进程/容器占用 ss -lntp | grep ':443'

怎么验证 docker nginx ssl 配置已生效?5 条命令给出确定答案

证书挂载对了、443 端口映射了,都不等于配置真的生效——容器里可能还跑着镜像自带的 default.conf,或者 add_header 被上层 server 块覆盖。下面 5 条命令按“配置层 → 证书层 → 协议层 → 响应头层 → OCSP 层”逐层收口,每条都给出通过标准和失败信号。示例统一用 nginx:1.27-alpine(nginx -T 参数自 1.9.10 起可用)与 OpenSSL 3.x。

1. 配置层:容器真正加载的是哪份文件、哪个路径?

# -T 输出合并后的完整配置(含 include),比看宿主机 conf 可靠
docker compose exec nginx nginx -T 2>/dev/null 
  | grep -n -E 'ssl_certificate|listen 443|http2'
# 期望:证书路径是容器内路径,如 /etc/letsencrypt/live/example.com/fullchain.pem
# 期望:listen 443 ssl; 与 http2 on;(1.25.1+)或 listen 443 ssl http2;(旧写法)

如果 grep 不到 ssl_certificate,说明挂载的 conf 没被 include /etc/nginx/conf.d/*.conf 覆盖到,或者文件名不是 .conf 后缀——这是 docker nginx ssl 配置最常见的“配了但没生效”。

2. 证书层:线上返回的到底是不是刚续期的那张?

openssl s_client -connect example.com:443 -servername example.com -showcerts /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# 期望 notAfter 与你续期计划一致;issuer 是中间 CA(如 Let's Encrypt 的 R11/E6),不是根 CA

据 Let’s Encrypt 文档,fullchain.pem 必须包含中间证书;issuer 显示成根 CA 或握手报 unable to get local issuer certificate,都说明只挂了 cert.pem。

3. 协议层:TLS 1.0/1.1 是否真的关掉了?

openssl s_client -connect example.com:443 -tls1_1 /dev/null | grep -i protocols
# 期望:no protocols available(说明 TLSv1.0/1.1 已关闭)
curl -sI --tlsv1.3 --http2 https://example.com | head -1
# 期望:HTTP/2 200;若报 "option --http2: is unknown" 说明 curl 未编入 nghttp2

4. 响应头层:HSTS 到底进没进 location?

curl -sI https://example.com | grep -i -E 'strict-transport-security|^server'
# 期望:strict-transport-security: max-age=31536000; includeSubDomains
# 缺失 = add_header 未进该 location,或被上层 add_header 覆盖(nginx 的 add_header 不继承叠加)

5. OCSP 层:装订(stapling)是否成功?

openssl s_client -connect example.com:443 -servername example.com -status /dev/null 
  | grep -A2 'OCSP Response Status'
# 期望:successful;返回 no response sent 多为 ssl_trusted_certificate 缺失
# 参考配置:ssl_stapling on; ssl_stapling_verify on;(默认均为 off)
验证层 关键命令 通过标准 典型失败信号
配置 nginx -T 输出含容器内证书路径 grep 无结果
证书 openssl x509 -dates issuer 为中间 CA 链不完整告警
协议 -tls1_1 no protocols available 握手成功
头部 curl -sI HSTS max-age=31536000 无该头
OCSP -status successful no response sent

外部评分要不要看?A 和 A+ 差在哪?要,但只作为兜底。执行 docker run --rm -t ghcr.io/drwetter/testssl.sh:latest --fast https://example.com,或直接用 Qualys SSL Labs 扫描,重点看证书链完整、TLS 1.3 可用、无已知漏洞。据 SSL Labs 评分规则,A 已代表 docker nginx ssl 配置达标;A+ 额外要求 HSTS 且 max-age ≥ 15552000(180 天)并进入浏览器预加载列表,仅为了分数去调 max-age 收益有限。

最常见是端口映射写反,例如 ports 写成 '443:80',客户端发起 TLS 握手而容器回的是明文 HTTP。其次是 server 块只有 listen 80 没有 listen 443 ssl,或证书路径写错导致 nginx 根本没起来。先用 docker compose port nginx 443 和 docker compose logs nginx 两条命令定位,再看 curl -vI 的输出卡在哪个阶段。

nginx 在启动和 reload 时才读取 ssl_certificate 文件,certbot 续期只改了磁盘,内存里仍是旧证书。执行 docker compose exec nginx nginx -s reload 即可热加载,用 openssl s_client -connect 域名:443 -servername 域名 对比 notAfter 是否变化。若 reload 后仍旧,检查是否挂载了 live 单目录导致符号链接断裂。

挂载两个具体文件更小更安全,但 certbot 续期时是新建 archive 文件并更新 live 符号链接,绑定的旧 inode 不会自动跟着变,reload 后可能仍读旧证书,需要重启容器。挂载整个 /etc/letsencrypt 目录能让符号链接在容器内正常解析,配合 nginx -s reload 即可平滑生效,是 docker nginx ssl 配置里更省心的做法。

单机单域名场景,Caddy 用一行域名配置就能自动申请和续期,省事程度更高。需要精细控制 cipher、OCSP 装订、HSTS、多站点混部时,nginx 的可控性更好,代价是续期钩子要自己维护。多容器频繁增减的环境用 Traefik 的 label 声明更合适,但排错要看 ACME 日志,学习成本不低。

先确认宿主机上该文件真实存在:ls -l ./nginx/certs/fullchain.pem。再确认容器内路径:docker compose exec nginx ls -l /etc/nginx/certs。如果宿主机上原本没有这个文件,Docker 会把挂载源当成目录创建,日志里会出现 Is a directory,删掉该空目录、放好证书文件再 up -d 即可。

用 ss -lntp | grep :443 找到占用进程,停掉宿主 nginx 或改它的监听端口。也可以让容器只映射 8443:443,由宿主机上已有的 nginx 用 proxy_pass https://127.0.0.1:8443 转发,此时 TLS 在容器内终止,宿主只做四层或七层转发。

自 1.25.1 起 http2 从 listen 参数改为独立指令,正确写法是 listen 443 ssl; 加一行 http2 on;。旧的 listen 443 ssl http2; 在 1.27 上会输出 the 'listen … http2' directive is deprecated,功能仍可用,但升级到移除该参数的版本后会直接报错,建议现在统一改掉。


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

内容审核

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