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

Nginx Proxy Manager 配置 SSL 全流程:从 Let’s Encrypt 申请到反向代理 HTTPS 生效

nginx proxy manager 配置ssl — Nginx Proxy Manager 配置 SSL 全流程:从 Let's Encrypt 申请到反向代理 HTTPS 生效
核心结论

在 Nginx Proxy Manager 配置 SSL 的最短路径:Proxy Host 填好域名与上游地址后,在 SSL 标签页选 Request a new SSL Certificate → Let's Encrypt,勾选 Force SSL 与 HTTP/2,80/443 放通后约 30 秒即可签发并挂载 90 天有效期的证书。 NPM 2.11.3 将证书存放在容器内 /etc/letsencrypt/live/npm-{id}/fullchain.pem,对应宿主机 ./data/letsencrypt/live/npm-{id}/,删除该目录会导致 nginx: [emerg] cannot load certificate。 HTTP-01 验证必须让公网访问 http://域名/.well-known/acme-challenge/{token},80 端口被宝塔、群晖 DSM 占用时会报 Problem binding to port 80: Could not bind to IPv4 or IPv6。 需要 *.example.com 通配符时改用 DNS-01:SSL 标签页勾 Use DNS Challenge,Cloudflare 填 Zone.DNS Edit 权限的 API Token,证书同样 90 天并由容器内 certbot renew 在到期前 30 天自动续期。 验证命令:openssl s_client -connect example.com:443 -servername example.com /dev/null | openssl x509 -noout -issuer -dates,issuer 应为 Let's Encrypt R10/R11,notAfter 距今不超过 90 天。

为什么 Nginx Proxy Manager 配置 SSL 总是失败?先看清 6 个根本原因

为什么点一下 Save 只弹出 Internal Error,什么都不告诉你? 因为 NPM 2.11.x 把三件事耦合在同一个 Node.js 进程里:调用 certbot 申请证书、渲染并写入 /data/nginx/proxy_host/{id}.conf、执行 nginx -s reload。任何一环抛错,前端统一回一句 Internal Error,真正的堆栈只存在于容器日志里。所以排查顺序永远是:先看日志,再改配置。

# NPM 2.11.x + Docker 部署:实时跟踪日志,只过滤证书与 nginx 相关行
docker logs -f nginx-proxy-manager 2>&1 | grep -Ei 'acme|error|emerg|reload|challenge'

据 Let’s Encrypt 文档,HTTP-01 校验要求 CA 从公网访问 http://你的域名/.well-known/acme-challenge/{token},这一条约束直接决定了下面六个高频失败点。

  1. 宿主机 80 端口已被占用(最高频)。 宝塔面板、Apache、群晖 DSM 都会抢 80,certbot 起监听时直接报 Problem binding to port 80: Could not bind to IPv4 or IPv6。先确认占用者,再决定是停服务还是让 NPM 独占:
# 查谁占了 80/443(需要 root 或 sudo 才能看到进程名)
ss -ltnp | grep -E ':80|:443'
# 宿主机已被占用时,NPM 只能映射其他端口,或停掉冲突服务后 docker restart nginx-proxy-manager
docker restart nginx-proxy-manager
  1. 解析只配了 AAAA,或 A 记录尚未生效。 若 NPM 所在网络 IPv6 优先,AAAA 指向一台没放行 80 的机器,校验会以 Timeout during connect (likely firewall problem) 失败。双向确认:dig +short A example.com 与 dig +short AAAA example.com,两条都必须指向真正运行 NPM 的地址。
  2. Cloudflare 橙云开着。 挑战请求被 CDN 拦截或回源失败,面板报 Invalid response from http://example.com/.well-known/acme-challenge/xxx: 404。验证方法:curl -I http://example.com/.well-known/acme-challenge/test,若返回 404/522 而源站文件确实存在,就是橙云所致——临时切灰云,或直接改用 DNS-01。
  3. 证书文件与数据库记录脱节。 手动删过 data 目录、或重建容器时漏挂 ./letsencrypt 卷,UI 里证书仍在,nginx 却启动即失败:nginx: [emerg] cannot load certificate "/data/custom_ssl/npm-2/fullchain.pem": BIO_new_file() failed。用 docker inspect nginx-proxy-manager --format '{{json .Mounts}}' 核对挂载,缺失则从 UI 删除该证书重新申请。
  4. 上游自身是 HTTPS 自签证书。 即使 SSL 标签页已开 Force SSL,访问仍是 502,因为 NPM→上游这段 TLS 握手失败。在 Advanced 里补两行(对应 nginx 默认 proxy_ssl_verify on):
# 适用 NPM 2.x Advanced 标签页:关闭对上游证书链校验,并发送 SNI
proxy_ssl_verify off;          # 默认 on,自签上游必须关
proxy_ssl_server_name on;      # 默认 off,多域名上游必须开
proxy_ssl_name 上游域名;        # 可选,上游靠 SNI 分流时指定

第六点其实是前五点的元问题:把 UI 的 Internal Error 当成原因而不是症状。真正要区分的是“申请失败”还是“reload 失败”——前者日志里有 ACME 关键字,后者是 [emerg]。据此选校验方式:

维度 HTTP-01 DNS-01
端口要求 必须公网可达 80 无要求,仅需 DNS API
通配符证书 不支持 支持 *.example.com
橙云代理 需临时切灰云 可保持橙云
典型报错 Timeout / Problem binding to port 80 DNS problem: NXDOMAIN looking up TXT

协议层面这些失败都发生在 RFC 8555 定义的 ACME 授权阶段,与 NPM 本身无关;NPM 只负责把 certbot 的结果写进 nginx 配置并 reload,据 nginx 官方文档,proxy_ssl_verify 自 1.7.0 起提供、默认值即为 on,这就是自签上游必然 502 的根因。

Nginx Proxy Manager 配置 SSL 的完整实操步骤(Let's Encrypt HTTP-01 路线)

为什么建议用 Docker 而不是直接装在宿主机上?Nginx Proxy Manager(下称 NPM)把 Nginx、Certbot 和一份 SQLite 配置库打包成一个镜像,如果直接安装在宿主机上,Nginx 会与系统包管理器争用 80/443 端口;而使用容器化部署时,数据全部保存在 /data 与 /etc/letsencrypt 两个卷里,升级时只需要更换镜像 tag。下面以官方镜像 jc21/nginx-proxy-manager:2.11.3 为例(该版本对应 Nginx 1.25 与 Certbot 2.x,ACME 协议遵循 RFC 8555)。

第 1 步:怎么写出可复用的 docker-compose.yml?

# docker-compose.yml —— NPM 2.11.3
services:
  nginx-proxy-manager:
    image: jc21/nginx-proxy-manager:2.11.3   # 固定 tag,避免 :latest 自动升级导致配置漂移
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - "80:80"      # HTTP-01 验证与 301 跳转入口
      - "443:443"    # HTTPS
      - "81:81"      # 管理面板,切勿对公网长期开放
    volumes:
      - ./data:/data                        # SQLite 库、Nginx 配置、日志
      - ./letsencrypt:/etc/letsencrypt      # 证书与 ACME 账户密钥
    healthcheck:
      test: ["CMD", "/usr/bin/check-health"]
      interval: 10s
      timeout: 3s

# 执行:docker compose up -d && docker ps --filter name=nginx-proxy-manager
# 期望输出(截取关键列):
# CONTAINER ID   IMAGE                            STATUS
# 9f3c1a2b7d10   jc21/nginx-proxy-manager:2.11.3  Up 12 seconds (healthy)

如果状态里没有 (healthy),通常是 ./data 目录权限问题;官方文档建议宿主机 UID 与容器内 root 一致,或者直接 chown -R 1000:1000 ./data。

第 2 步:初始化面板时必须改掉什么?浏览器打开 http://服务器公网IP:81,首次登录使用默认凭据 admin@example.com / changeme。登录后立刻进入 Users 修改密码,并把邮箱换成真实地址——据 Let’s Encrypt 官方说明,ACME 账户注册与证书到期提醒(到期前 20 天左右)都绑定这个邮箱,填错等于放弃了续期告警。

第 3 步:Proxy Host 的关键字段怎么填?进入 Hosts → Proxy Hosts → Add Proxy Host:Domain Names 一行一个填 example.com 与 www.example.com;Scheme 选 http(后端是明文 HTTP 时);Forward Hostname 填同网络下的容器名或内网 IP;Forward Port 填 3000;勾选 Block Common Exploits 与 Websockets Support。前者会加载一组针对常见扫描路径的 deny 规则,后者会追加 proxy_set_header Upgrade $http_upgrade,否则 WebSocket 握手会返回 400。

第 4 步:SSL 标签页该勾哪几项?SSL Certificate 下拉选 Request a new SSL Certificate,勾选 I Agree to the Let’s Encrypt Terms of Service,同时勾上 Force SSL 与 HTTP/2 Support。HSTS 建议先不勾:一旦下发 Strict-Transport-Security,浏览器会按 max-age 强制 HTTPS,若某个子域还没上证书就会直接不可访问,等全站稳定后再开启(Mozilla SSL Configuration Generator 默认建议 max-age=63072000)。

第 5 步:怎么确认签发真的成功了?点 Save 后立刻执行 docker logs -f nginx-proxy-manager,正常序列如下,全程约 15–40 秒:

Requesting a certificate for example.com and www.example.com
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/npm-1/fullchain.pem
New certificate obtained!
# 若 80 端口被占用或被 CDN 回源挡住,会看到:
# Error: Fetching http://example.com/.well-known/acme-challenge/xxx: Timeout during connect

第 6 步:如何复核绑定与跳转?回到 Proxy Hosts 列表,SSL 列显示 expires on 2025-xx-xx(Let’s Encrypt 证书固定 90 天有效期),状态列为 Online。用 curl 验证 301:

curl -sI http://example.com | head -3
# HTTP/1.1 301 Moved Permanently
# Location: https://example.com/
curl -sI https://example.com | grep -i strict-transport   # 未开 HSTS 时应无输出

第 7 步:80 端口不可达时怎么办?改走 DNS-01。在同一 SSL 标签页勾选 Use DNS Challenge,Provider 选 Cloudflare,粘贴仅有 Zone.DNS Edit 权限的 API Token(不要用 Global API Key),Domain Names 填 *.example.com 与 example.com。NPM 会调用 ACME 的 dns-01 挑战,写入 _acme-challenge TXT 记录,因此在纯内网或 80 端口被封的环境下也能签发,并且通配符证书只能用这条路。

对比项 HTTP-01 DNS-01
前置条件 80 端口对公网可达 DNS API Token 有 Zone.DNS Edit 权限
是否支持通配符 否 是(*.example.com)
签发耗时 约 15–40 秒 取决于 DNS 传播,通常 30 秒–5 分钟
典型失败信息 Timeout during connect Incorrect TXT record found(旧记录未清)
NPM 中的开关 默认 Use DNS Challenge + Provider

两条路线签下的证书都由 NPM 内置的 Certbot 定时任务在到期前 30 天自动续期,续期日志同样输出到 docker logs;若你改了域名解析或换了 Token,记得在 SSL 标签页重新保存一次以触发重签,否则旧 challenge 配置会一直沿用。

Nginx Proxy Manager 配置 SSL 的关键配置片段与命令示例

面板上点完”Save”,底层到底写了什么?这一节直接给可复制的片段和校验命令,把 nginx proxy manager 配置 ssl 的黑盒拆开看。

docker-compose.yml 最少要写哪几行?

# docker-compose.yml —— NPM 2.11.3 最小可用片段
services:
  app:
    image: jc21/nginx-proxy-manager:2.11.3   # 固定小版本,避免 latest 漂移
    restart: unless-stopped
    ports:
      - "80:80"        # HTTP-01 校验与 301 跳转必需
      - "443:443"
      - "81:81"        # 管理面板
    volumes:
      - ./data:/data                     # 含 database.sqlite 与 nginx/proxy_host/*.conf
      - ./letsencrypt:/etc/letsencrypt   # 证书实体,不挂载重启即丢
    environment:
      DISABLE_IPV6: "true"   # 无 IPv6 出口时必开,否则 AAAA 记录导致校验超时

DISABLE_IPV6 的原理:据 Let’s Encrypt 文档,HTTP-01 校验会优先解析 AAAA 记录;若容器所在网络没有 IPv6 出口,校验请求会一直超时并报 Fetching http://example.com/.well-known/acme-challenge/...: Timeout during connect。

面板保存后,配置落到哪个文件?

# ./data/nginx/proxy_host/1.conf —— NPM 自动生成,不要手改(下次保存会被覆盖)
server {
  listen 443 ssl http2;                                     # 编号 1 对应证书目录 npm-1
  ssl_certificate     /etc/letsencrypt/live/npm-1/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/npm-1/privkey.pem;
  # proxy_pass / location 等由 UI 表单生成
}

加固必须写进 UI 的 Advanced 标签页,它会追加到同一个 server 块内,不会被覆盖。

Advanced 里该填什么?(NPM 2.11.x 内置 nginx 1.25 系列,默认已开 TLSv1.2/1.3,以下与 Mozilla SSL Configuration Generator 的 intermediate 档一致)

ssl_protocols TLSv1.2 TLSv1.3;
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;          # TLS1.3 下由客户端选序,off 反而更快
ssl_session_cache shared:SSL:10m;       # 默认 none,开启后省一次完整握手
ssl_session_timeout 1d;
add_header Strict-Transport-Security "max-age=300; includeSubDomains" always;  # 先 300 秒试跑

HSTS 按 RFC 6797,一旦浏览器缓存了 max-age,在到期前无法回退到 HTTP。稳妥做法:先 300 秒跑 24 小时,确认所有子域都能 HTTPS,再改 max-age=31536000; includeSubDomains。

怎么确认真的生效?

# 1) 看运行时合并后的配置
docker exec -it nginx-proxy-manager nginx -T 2>/dev/null 
  | grep -n -A4 "server_name example.com"
# 应看到 listen 443 ssl http2、正确的 ssl_certificate 路径、以及 add_header 行

# 2) 核对数据库里的勾选是否落库
docker exec -it nginx-proxy-manager sqlite3 /data/database.sqlite 
  "select id,domain_names,ssl_forced,http2_support from proxy_host;"
# 输出示例:1|["example.com"]|1|1  —— ssl_forced=1、http2_support=1 才算真开

若提示 sqlite3: not found,直接在宿主机查:sqlite3 ./data/database.sqlite "select ..."。另外 nginx 1.25.1 起 listen ... http2 已被标记废弃,nginx -T 里出现 the "listen ... http2" directive is deprecated 警告属正常,等 NPM 升级到使用 http2 on; 即可消除。

Nginx Proxy Manager 配置 SSL 的三种证书方案对比与选型表

三种证书方案不是”谁更好”,而是”你的网络拓扑允许谁”。下表把 Nginx Proxy Manager(下称 NPM,以 2.11.x 面板为准)中三条签发路径的硬性差异摊开对比,选型时先看”前置条件”和”典型失败”两列——它们直接决定你在 nginx proxy manager 配置ssl 这一步会卡在哪。

方案 前置条件 有效期与续期 NPM 面板路径 费用 典型失败
Let’s Encrypt HTTP-01 80 端口公网可达、A 记录已生效 90 天,到期前 30 天自动续 SSL Certificates → Add → Let’s Encrypt 0 元 Timeout during connect
Let’s Encrypt DNS-01 通配符 域名商 API Token(如 Cloudflare Zone.DNS Edit) 90 天,同上 同上,勾选 Use a DNS Challenge 0 元 Incorrect TXT record found
上传自定义/商业证书 已有 fullchain.pem 与 privkey.pem 通常 1 年,需手动替换 SSL Certificates → Add → Custom Certificate DV 约 100–400 元/年,OV 约 800–2000 元/年 cannot load certificate

只有一台公网 VPS,值得折腾 DNS-01 吗?不值得。HTTP-01 走的是 RFC 8555 定义的 http-01 挑战,ACME 服务器直接 GET http://你的域名/.well-known/acme-challenge/<token>,NPM 会自动注入临时 location,零配置零成本。它的软肋就是 80 端口:被 CDN 回源规则拦、被运营商封、Docker 端口映射写错,面板里都会落到 Timeout during connect (likely firewall problem) 这一句上。排查顺序是先在外部执行 curl -I http://你的域名/.well-known/acme-challenge/test,看返回 404(正常,说明能通)还是超时。

80 端口被运营商封锁怎么办?走 DNS-01。代价是要在域名商侧建 API Token,建议单独建一个只授权 Zone.DNS Edit 的令牌、记录到期时间,别用 Global API Key。调试阶段务必先验证 TXT 传播,不要拿生产额度试错:

# 用 staging 端点预演 DNS-01,签发的是不被信任的测试证书,不消耗生产配额
# certbot/certbot 镜像当前对应 certbot 3.x,--preferred-challenges dns 即 RFC 8555 的 dns-01
docker run --rm -it 
  -v "$PWD/le:/etc/letsencrypt" 
  certbot/certbot certonly --manual --preferred-challenges dns 
  --staging 
  -d '*.example.com' -d example.com
# 输出会给出 _acme-challenge.example.com 的 TXT 值,手动添加后回车继续
# 若报 Incorrect TXT record found,通常是旧记录未删或多条 TXT 并存

据 Let’s Encrypt 官方 Rate Limits 文档,每个注册域名每周最多签发 50 张证书(new orders),同一组域名集合的重复证书每周限 5 张,验证失败限每账号每主机名每小时 5 次——这就是”调试用 staging”的硬理由。

企业采购的 pfx 能直接传进 NPM 吗?不能。NPM 只接受 PEM,且证书框要贴 fullchain(服务器证书 + 中间 CA),私钥框贴 privkey。先拆分并校验配对:

# OpenSSL 1.1.1 / 3.x 通用;-nodes 表示私钥不加密,便于 NPM 直接读取
openssl pkcs12 -in cert.pfx -nodes -nokeys -out fullchain.pem   # 证书链
openssl pkcs12 -in cert.pfx -nocerts -nodes -out privkey.pem    # 私钥

# 校验两者是否匹配:两条输出的 SHA256 摘要必须完全一致(RSA 证书适用)
openssl x509 -noout -modulus -in fullchain.pem | openssl sha256
openssl rsa  -noout -modulus -in privkey.pem    | openssl sha256

若把私钥误贴进证书框,NPM 保存后会报 nginx: [emerg] cannot load certificate "/data/custom_ssl/npm-3/fullchain.pem": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory)——文件确实生成了,但内容不是证书,OpenSSL 解析失败。

三种方案能混着用吗?能,而且混合策略最实用:主域用 DNS-01 通配符覆盖所有二级子域,个别对外品牌域名额外挂 OV 证书。NPM 里每个 Proxy Host 在 SSL 标签页独立选择证书,互不影响,这也让后续做多域名、多后端的 nginx proxy manager 配置ssl 扩展时不必推倒重来。

Nginx Proxy Manager 配置 SSL 后最常见的 6 个真实报错与排查

Q:Nginx Proxy Manager 报 Problem binding to port 80: Could not bind to IPv4 or IPv6. 怎么处理?

这条报错与 NPM 无关,是宿主机 80 端口已被占用,容器里的 nginx 无法监听。NPM 的 docker-compose.yml 必须做 80:80 映射,且 ACME HTTP-01 校验只能走 80 端口,据 RFC 8555 与 Let’s Encrypt 官方文档,HTTP-01 不支持自定义端口,因此”改成 8080 绕开”这条路走不通。

# 1. 在宿主机找占用者(需要 root 才能看到进程名)
sudo ss -lntp | grep -E ':(80|443)b'
# 典型输出:
# LISTEN 0 511 0.0.0.0:80 0.0.0.0:* users:(("nginx",pid=1187,fd=6))
# LISTEN 0 4096 0.0.0.0:80 0.0.0.0:* users:(("docker-proxy",pid=902,fd=4))

# 2. 停掉宿主机自带 Web 服务(示例为 nginx / httpd 二选一)
sudo systemctl stop nginx && sudo systemctl disable nginx
# sudo systemctl stop httpd && sudo systemctl disable httpd

# 3. 重启 NPM 容器重试签发
docker restart nginx-proxy-manager
docker logs --tail 50 nginx-proxy-manager

若占用者是 docker-proxy,说明另一个容器也映射了 80,用 docker ps --format '{{.Names}}t{{.Ports}}' | grep :80 定位并改端口。适用版本:NPM 2.x(基于 nginx 1.2x + Node 18/20 镜像),默认 80/443/81 三个端口。

Q:报 Timeout during connect (likely firewall problem) 是哪里没放行?

Let’s Encrypt 校验节点从公网访问 http://example.com/.well-known/acme-challenge/<token> 超时,说明 80 端口在某一层被拦。按”云安全组 → 主机防火墙 → 容器映射”三层排查:

# 从任意一台外网机器验证(不要在本机 curl,会误判)
curl -I http://example.com/.well-known/acme-challenge/test
# 期望返回 404 而不是超时;404 说明链路通,超时说明被拦

# 主机层:ufw 与 iptables 都要看
sudo ufw status verbose
sudo iptables -L -n --line-numbers | grep -E 'dpt:(80|443)'
docker port nginx-proxy-manager   # 确认 80/tcp -> 0.0.0.0:80

注意一个高频坑:Docker 发布端口会写入 DOCKER 链,绕过 ufw 的 INPUT 规则,所以”ufw 显示放行”不等于真放行,云厂商安全组必须单独开 80/443 入方向。

Q:校验返回 Invalid response ... 404,但网站本身能打开?

多数是同一域名被两个 Proxy Host 重复绑定。NPM 每个 Proxy Host 生成 /data/nginx/proxy_host/N.conf,先加载的 server_name 匹配者抢占请求,若那条记录没绑定证书、也没有 ACME location,校验文件自然 404。

# 找出所有声明了该域名的 server 块
docker exec nginx-proxy-manager sh -c 
  "grep -l 'server_name example.com' /data/nginx/proxy_host/*.conf"

处理方式:删掉重复条目,或把域名合并进同一个 Proxy Host 的 Domain Names(逗号分隔)。

Q:Error: ENOENT: no such file or directory, open '/etc/letsencrypt/live/npm-3/fullchain.pem'

证书文件已不存在,但 NPM 数据库仍留着记录。先确认卷挂载,再到 SSL Certificates 列表删除该条目重新签发:

# docker-compose.yml 必须包含这两行(相对路径挂载到容器内固定路径)
# volumes:
#   - ./data:/data
#   - ./letsencrypt:/etc/letsencrypt

docker exec -it nginx-proxy-manager ls -l /etc/letsencrypt/live/
docker exec -it nginx-proxy-manager ls -l /data/custom_ssl/

Q:nginx: [emerg] cannot load certificate "/data/custom_ssl/npm-2/fullchain.pem": BIO_new_file() failed

这是 OpenSSL 加载文件失败(见 OpenSSL 文档中 BIO_new_file() 语义),原因无非路径错、权限不足或内容不完整。容器内 nginx 以非 root 用户运行,私钥/证书建议 644:

docker exec -u 0 -it nginx-proxy-manager sh -c 
  "chmod 644 /data/custom_ssl/npm-2/*.pem && 
   grep -c 'BEGIN CERTIFICATE' /data/custom_ssl/npm-2/fullchain.pem && 
   openssl x509 -noout -subject -issuer -dates -in /data/custom_ssl/npm-2/fullchain.pem"
# fullchain 内证书数应为 2 及以上(叶子证书 + 中间证书)

Q:urn:ietf:params:acme:error:rateLimited / too many certificates already issued

限额项 默认值 触发后的建议
同一注册域名证书数 50 张 / 7 天 合并子域名为一张证书(SAN)
重复证书(同域名集合) 5 张 / 周 等待 168 小时,勿反复点 Save
新订单 300 次 / 3 小时 / 账户 调试期改用 DNS-01 或 staging
校验失败 5 次 / 小时 / 主机名 先修 404/超时再重试

据 Let’s Encrypt 官方 Rate Limits 文档,重复证书限额按”完全相同的域名集合”计。调试期可用 staging 目录预演(签发不受信任但流程一致):

docker run --rm certbot/certbot certonly --staging 
  -d example.com --manual --preferred-challenges http 
  --server https://acme-staging-v02.api.letsencrypt.org/directory

Q:证书明明没问题,为什么还是 502 Bad Gateway?

502 属于上游不可达,与证书无关,但常被误判。从 NPM 容器内部验证,而不是从宿主机:

docker exec nginx-proxy-manager curl -I http://app:3000
docker exec nginx-proxy-manager getent hosts app
# 宿主侧确认上游监听地址
sudo ss -lntp | grep 3000
# 若显示 127.0.0.1:3000,容器内永远连不通,需改为 0.0.0.0:3000

上游绑定 127.0.0.1 是 Docker 场景最典型的 502 成因;其余检查 Forward Hostname/Port 是否与容器名、网络别名一致(同一 compose network 内用服务名即可)。这也是 nginx proxy manager 配置 ssl 后被误报为”证书故障”的第一大冤案——先分清 4xx/5xx 是 TLS 层还是应用层,再回头查 docker logs nginx-proxy-manager 中对应的 connect() failed 行。

怎么验证 Nginx Proxy Manager 配置 SSL 已经真正生效?

配置点完 Save 不等于生效。NPM 的 UI 只负责把字段写进 SQLite,真正的证书与 server 块要经过 Let’s Encrypt 签发、nginx 重载两步才落地。按下面六个层面依次验证,任一层失败都能立刻定位到具体环节。

1. 证书链:issuer 是谁、什么时候过期?

# -servername 必带,否则 SNI 缺失会拿到 default_server 的占位证书
openssl s_client -connect example.com:443 -servername example.com /dev/null 
  | openssl x509 -noout -subject -issuer -dates
# 期望输出(2024-06 起 Let's Encrypt 中间证书为 R10/R11;ECDSA 链为 E5/E6)
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R11
# notAfter=Oct  9 12:00:00 2025 GMT   ← 距签发不超过 90 天

据 Let’s Encrypt 官方文档,其证书有效期固定 90 天,中间证书 R10/R11 自 2024 年 6 月起全面替代已退役的 R3。若 issuer 显示 CN = snakeoil 或 localhost,说明该域名的 Proxy Host 没绑定证书,nginx 落到了默认 server 块。若出现 verify error:num=20:unable to get local issuer certificate,是链不完整而非证书本身有问题。

2. HTTP 响应头:协议、服务标识、HSTS

curl -sSI https://example.com | head -20
# 期望:
# HTTP/2 200
# server: openresty            ← NPM 内置 OpenResty(基于 nginx)
# strict-transport-security: max-age=31536000   ← 仅当勾选 HSTS 时出现

NPM 的 HSTS 复选框默认不勾选,max-age 默认写入 31536000 秒(1 年)。没看到这行先别急着报 bug,回面板确认 HSTS Enabled 与 Subdomains 的勾选状态。

3. 跳转:Force SSL 是否真的落库

curl -sSI http://example.com | head -5
# 期望:HTTP/1.1 301 Moved Permanently
#       Location: https://example.com/
# 若返回 200,说明面板勾选未写入数据库,直接在宿主机查(data 目录为 compose 挂载卷):
sqlite3 ./data/database.sqlite "SELECT domain_names, ssl_forced, certificate_id FROM proxy_host;"
# ssl_forced 应为 1;为 0 则在 UI 重新保存一次并观察 nginx 是否 reload

4. 配置落地:443 监听块数量对得上吗

# -T 打印合并后的完整配置;NPM 容器名按实际 compose 服务名替换
docker exec nginx-proxy-manager nginx -T 2>/dev/null | grep -c "listen 443 ssl"
# 该数字应等于已启用 SSL 的 Proxy Host 数量

数字偏小,通常是某条站点保存后 nginx 重载失败(证书文件缺失时 nginx -t 会报 cannot load certificate ... No such file or directory),NPM 会保留旧配置继续跑,UI 却已显示成功。

5. 第三方扫描:别只看评级

./testssl.sh --severity HIGH https://example.com
# 或直接用 Qualys SSL Labs 网页版,目标评级 A 及以上
检查项 期望结果 不达标意味着
协议版本 仅 TLS 1.2 / 1.3 TLS 1.0/1.1 未禁用,评级掉到 B
OCSP stapling offered NPM 默认不开启,需在 Advanced 手写指令
证书链 完整,且不含多余根证书 链中夹带根证书会被部分客户端拒绝
前向保密 支持 ECDHE 仅 RSA 密钥交换,评级受限

6. CT 日志与浏览器侧确认

访问 https://crt.sh/?q=example.com,新证书应在签发后数分钟内出现在 Certificate Transparency 日志中——这是 Let’s Encrypt 的强制要求,查不到说明签发流程异常。最后打开浏览器开发者工具 → Security 面板,应显示 “This connection is secure”、协议 TLS 1.3、证书颁发者为 Let’s Encrypt。至此,从 ACME 签发、nginx 加载到客户端握手整条链路才算端到端验证完毕。

Nginx Proxy Manager 配置 SSL 的续期、备份与长期维护

NPM 的证书会自动续期吗?怎么确认它真的续了?

会。Nginx Proxy Manager(下称 NPM)2.x 镜像内置定时任务,每天在容器内执行一次 certbot renew。按 certbot 官方文档,默认的 renew_before_expiry 为 30 天,即证书剩余有效期进入 30 天窗口才会真正触发签发,其余时间只做检查并静默退出。续期成功后由 deploy hook 自动 reload nginx,不需要 docker restart。验证方式不是看面板,而是检索日志关键字:

# 确认容器内定时任务存在(NPM 2.x 镜像路径,不同 tag 可能是 /etc/cron.d/certbot 或 s6 服务)
docker exec nginx-proxy-manager ls /etc/cron.d

# 关键验证:出现该行说明 certbot 已进入实际续期流程,而非仅检查
docker logs nginx-proxy-manager 2>&1 | grep -i "Renewing an existing certificate"

# 辅助确认:reload 记录与证书到期时间
docker logs nginx-proxy-manager 2>&1 | grep -i "reload"
docker exec nginx-proxy-manager openssl x509 -in /etc/letsencrypt/live/npm-1/fullchain.pem -noout -dates

续期失败通常是什么原因?会被限流吗?

续期链路和首次签发完全一致:HTTP-01 要求 80 端口从公网可达(Let’s Encrypt 会从多个网络视角发起校验,据其官方文档说明),DNS-01 要求域名商 API 凭据仍有效。中途关过 80、改过安全组、或域名走了 CDN 而回源规则变化,都会让续期在无人察觉的情况下连续失败。此时进 SSL Certificates 列表点 Renew Now 手动补签即可。注意失败次数会被计入 Let’s Encrypt 的 Failed Validation 限制——每个账户、每个主机名每小时 5 次,超过后需等待窗口重置,不要在失败后反复狂点。

维度 HTTP-01 DNS-01
续期依赖 80 端口对公网持续可达 域名商 API token 持续有效
通配符证书 不支持 支持 *.example.com
典型中断原因 防火墙/安全组关 80、CDN 回源变更 token 过期、权限被回收、TXT 记录未刷新
NPM 中配置位置 SSL 标签页选 HTTP-01 选 DNS Challenge 并填 Provider 凭据

迁移或重装时,备份哪些目录才不丢证书?

必须同时覆盖两个目录,缺一不可:./data/database.sqlite 保存 Proxy Host 与证书的绑定关系,./letsencrypt 保存私钥与链文件。只备份 data 会导致面板显示证书存在但 nginx 启动报私钥缺失;只备份 letsencrypt 则绑定关系丢失。在 compose 文件所在目录执行:

# 在 docker-compose.yml 同级目录执行,两个目录均为相对挂载路径
tar -czf npm-backup-$(date +%F).tar.gz ./data ./letsencrypt

# 恢复到新机:解包后保持相同挂载路径(/data、/etc/letsencrypt),否则证书绝对路径失效
tar -xzf npm-backup-2025-01-01.tar.gz

换成商业证书怎么替换?

在 SSL 标签页选 Custom Certificate,分别粘贴 fullchain.pem 与 privkey.pem 全文,保存后 nginx 自动 reload,全程无需重启容器。替换前先核对有效期,避免把更早到期的证书换上去:

# notAfter 必须晚于现有证书,否则替换即降级
openssl x509 -in fullchain.pem -noout -dates
# 顺带确认私钥与证书匹配(两条输出应一致)
openssl x509 -in fullchain.pem -noout -pubkey | openssl md5
openssl pkey -in privkey.pem -pubout | openssl md5

升级 NPM 版本要注意什么?

把 compose 里的镜像锁定到具体 tag(如 jc21/nginx-proxy-manager:2.11.3)而不是 latest,因为跨版本升级会执行数据库迁移,而迁移不可逆。升级前先 docker compose stop 并备份 ./data,启动后只有日志出现 Migrations complete 且面板能正常登录,才代表迁移成功;否则立即回滚到旧 tag 恢复备份。日志核对命令:

docker compose pull && docker compose up -d
docker logs nginx-proxy-manager 2>&1 | grep -i "Migrations complete"

面板本身怎么加固?

管理端口 81 默认是明文 HTTP,直接暴露公网等于把管理员登录页交给扫描器。用云安全组限制来源 IP,或叠加 SSH 隧道 ssh -L 8181:127.0.0.1:81 user@host 访问。管理员账号务必开启 2FA(NPM 2.x 内置 TOTP)。最后做一次一致性核对,证书目录数量应与 Proxy Host 中启用 SSL 的数量一致,多出的目录通常是删除主机后残留的孤儿证书:

# 列出所有由 NPM 管理的证书目录(npm-1、npm-2…)
docker exec nginx-proxy-manager ls -l /etc/letsencrypt/live

至少开放 80 与 443:80 用于 HTTP-01 域名验证和 HTTP 到 HTTPS 跳转,443 用于对外提供 TLS 服务。面板端口 81 建议只对可信 IP 开放,用安全组白名单或 SSH 隧道访问,不要直接暴露到公网。

单机少量站点、希望图形化点击完成签发与续期,NPM 更省事,证书申请、nginx 配置生成、自动续期三件事都在一个面板里;需要精细控制 nginx 指令、做复杂 location 规则或大规模自动化时,Certbot + 原生 Nginx 更灵活。两者底层都是 certbot 与 Let's Encrypt,证书本身没有区别。

前端只显示 Internal Error,真实堆栈在容器日志里。执行 docker logs –tail 100 nginx-proxy-manager,重点找 certbot 输出的 Detail: 行和 nginx: [emerg] 行,前者是 ACME 验证失败,后者是配置或证书文件加载失败,按报错关键字对照排查即可。

SSL 标签页必须勾选 Use DNS Challenge 并选择对应 DNS Provider,填好 API Token,Domain Names 同时写 *.example.com 和 example.com(通配符不覆盖裸域)。HTTP-01 不支持通配符,这是硬性限制,写错会直接报错无法签发。

容器内路径是 /etc/letsencrypt/live/npm-{id}/,对应宿主机 ./letsencrypt/live/npm-{id}/,自定义上传证书在 ./data/custom_ssl/。迁移时把 ./data 与 ./letsencrypt 两个目录整体打包复制到新机并保持相同挂载路径,启动容器后证书即可继续使用,无需重新签发。

配置动作不同但结果一样:Let's Encrypt 走 Request a new Certificate 自动签发,90 天自动续期;付费证书走 Custom Certificate 手动粘贴 PEM,通常 1 年一换。浏览器信任链完全一致,差别在于有效期、赔付条款与是否支持 OV 组织信息展示。

先用 openssl s_client -connect 域名:443 -servername 域名 看返回的是不是预期那张证书,常见原因是 CDN 或负载均衡层终止了 TLS、DNS 还指向旧服务器、或 fullchain.pem 缺少中间证书。确认证书链完整后,再检查系统时间是否偏差超过 5 分钟。


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

内容审核

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