域名解析到服务器#

在你的域名 DNS 管理里，给要用的域名加 A 记录指向服务器公网 IP，比如：

解析生效需要几分钟到几十分钟。验证是否生效，在本地执行：

1
ping blog.example.com

返回的 IP 是你服务器的 IP 就说明解析到位了。这一步没到位之前不要去申请证书，Let’s Encrypt 会因为验证不到域名归属直接拒绝，失败次数多了还会触发限额（后面排障部分会细说）。

放行 80 和 443 端口#

两个地方都要放行，缺一个都不行：

• 云厂商安全组（如果你的服务器在云上）：入方向放行 TCP 80、443。
• 本机防火墙（如果开了 ufw / firewalld）：

1
# ufw
2
ufw allow 80/tcp
3
ufw allow 443/tcp
4

5
# firewalld
6
firewall-cmd --permanent --add-service=http
7
firewall-cmd --permanent --add-service=https
8
firewall-cmd --reload

80 端口不只是给 HTTP 访问用的，Let’s Encrypt 的 HTTP-01 验证也要走 80 端口，80 不通 = 证书申请必失败，这是新手最常见的翻车点。

被反代的服务先「藏好」#

反代上线之后，后端服务就不应该再直接暴露公网了。两种做法：

• 服务跑在宿主机或端口映射时只绑回环地址：Compose 里把端口映射写成 127.0.0.1:8080:80，这样只有本机能连，外网连不上，流量只能从反代进来。
• 服务和反代在同一个 Docker 网络里：端口干脆不映射（不写 ports），只通过容器名在内网互通。

先有个概念就行，路线 A 用第一种衔接方式（同网络容器名互通也会讲到），路线 B 会专门讲它惯用的网关地址写法。

目录结构#

先建好目录，后面所有路径都以此为准：

1
mkdir -p /opt/nginx-proxy/{conf.d,certbot/www,certbot/conf}
2
cd /opt/nginx-proxy

docker-compose.yml#

1
services:
2
  nginx:
3
    image: nginx:alpine
4
    container_name: nginx-proxy
5
    restart: unless-stopped
6
    ports:
7
      - "80:80"
8
      - "443:443"
9
    volumes:
10
      - ./conf.d:/etc/nginx/conf.d:ro
11
      - ./certbot/www:/var/www/certbot:ro
12
      - ./certbot/conf:/etc/letsencrypt:ro
13

14
  certbot:
15
    image: certbot/certbot:latest
16
    container_name: certbot
17
    volumes:
18
      - ./certbot/www:/var/www/certbot
19
      - ./certbot/conf:/etc/letsencrypt

两个细节注意：

• Nginx 侧的三个挂载都加了 :ro（只读），Nginx 只需要读配置和证书，不给写权限更安全；Certbot 侧不能加 :ro，它要往里面写证书和验证文件。
• certbot 服务没有 command，它是一次性工具容器，需要用的时候用 docker compose run --rm certbot ... 临时拉起来执行命令，执行完自动删除，这正是下面申请证书的用法。

第一步：先写 HTTP 版站点配置#

关键顺序问题：证书还没申请下来之前，Nginx 不能加载引用证书文件的 HTTPS 配置，否则启动直接报错。所以流程是先用纯 HTTP 配置把 Nginx 跑起来 → 用 Certbot 申请证书 → 再换成 HTTPS 配置并重载。

在 conf.d/ 里新建 blog.conf，先写 HTTP 版本（以把本机 8080 端口的博客服务反代到 blog.example.com 为例）：

1
server {
2
    listen 80;
3
    server_name blog.example.com;
4

5
    # ACME 验证路径：Let's Encrypt 会来这里取验证文件，必须放在 location / 之前并单独声明
6
    location /.well-known/acme-challenge/ {
7
        root /var/www/certbot;
8
    }
9

10
    location / {
11
        proxy_pass http://172.17.0.1:8080;
12
        proxy_set_header Host $host;
13
        proxy_set_header X-Real-IP $remote_addr;
14
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
15
        proxy_set_header X-Forwarded-Proto $scheme;
16
    }
17
}

这份配置逐行讲清楚，这是全篇最核心的部分：

• listen 80;：监听 HTTP 端口。
• server_name blog.example.com;：这个站点块只处理域名为 blog.example.com 的请求，这就是「按域名分流」的实现方式——多个服务就写多个 server 块，各自认领一个域名。
• location /.well-known/acme-challenge/：Let’s Encrypt 的 HTTP-01 验证路径。验证时它会访问 http://blog.example.com/.well-known/acme-challenge/某个随机文件名，Certbot 会把验证文件写到共享目录里，Nginx 从这里读到并返回，验证就通过了。这个 location 缺失或被其他规则拦截，是证书申请失败的第二大原因。
• proxy_pass http://172.17.0.1:8080;：把请求转发到后端服务。这里的 172.17.0.1 是 Docker 默认网桥在宿主机一侧的网关地址，也就是说后端服务是「监听在宿主机 8080 端口」的情况（比如另一个 Compose 项目映射了 127.0.0.1:8080）。如果后端服务和 Nginx 在同一个 Compose、同一个网络里，这里可以直接写容器名加容器端口，如 proxy_pass http://blog:80;，靠 Docker 内置 DNS 解析。
• proxy_set_header 四件套，每一项都不能省：
  • Host $host：把用户实际访问的域名原样告诉后端。不传的话后端收到的 Host 是 172.17.0.1:8080，很多应用会据此生成跳转链接、校验来源，轻则链接全错，重则直接拒绝请求。
  • X-Real-IP $remote_addr：把访客的真实 IP 传给后端。经过反代之后，后端看到的连接来源全是 Nginx 的地址，没有这一行，后端日志里所有访客 IP 都会变成同一个网关地址，限流、封禁、审计全没法做。
  • X-Forwarded-For $proxy_add_x_forwarded_for：和上一行的分工不同，这个头记录的是完整的代理链（访客 IP 经过每一层代理依次追加），后端框架普遍优先读这个头来还原真实 IP。$proxy_add_x_forwarded_for 的含义是「在已有的 X-Forwarded-For 后面追加上一层的地址」，而不是覆盖，多层代理时不会丢链。
  • X-Forwarded-Proto $scheme：告诉后端「用户到 Nginx 这一段用的是 http 还是 https」。等启用 HTTPS 后这一行尤其关键：后端如果不知道前面是 HTTPS，会生成 http 的跳转地址，用户就会被甩回明文或陷入重定向死循环（登录后反复跳回登录页是典型症状）。

写好后启动 Nginx：

1
docker compose up -d nginx
2
docker compose logs nginx   # 确认没有配置报错

第二步：用 Certbot 申请证书#

1
docker compose run --rm certbot certonly --webroot \
2
  -w /var/www/certbot \
3
  -d blog.example.com \
4
  --email your@email.com \
5
  --agree-tos \
6
  --no-eff-email

参数说明：

• certonly：只申请证书，不自动改任何配置（配置我们自己写，可控）。
• --webroot -w /var/www/certbot：用 webroot 验证方式，把验证文件写到共享目录，正好对应上一步 Nginx 配置里的 ACME 路径。
• -d blog.example.com：要申请证书的域名，多个域名可以继续加 -d。
• --email：证书快到期时 Let’s Encrypt 会发提醒邮件到这个邮箱。

成功后证书会出现在 certbot/conf/live/blog.example.com/ 下，关键的两个文件是 fullchain.pem（证书链）和 privkey.pem（私钥）。

WARNING

第一次申请前务必确认两件事：域名已经解析到这台服务器、80 端口从外网能通。验证失败会计入 Let’s Encrypt 的限额：同一域名组合 一周内失败验证和重复签发都有次数上限（重复证书每周 5 张、失败验证每小时 5 次），触发限额只能等窗口过期，急也没用。所以别拿生产域名反复试错，先把前置准备做扎实。

第三步：换上 HTTPS 配置并加 HTTP 跳转#

把 conf.d/blog.conf 替换成完整版本：

1
server {
2
    listen 80;
3
    server_name blog.example.com;
4

5
    location /.well-known/acme-challenge/ {
6
        root /var/www/certbot;
7
    }
8

9
    # 其余 HTTP 请求一律 301 跳转到 HTTPS
10
    location / {
11
        return 301 https://$host$request_uri;
12
    }
13
}
14

15
server {
16
    listen 443 ssl;
17
    server_name blog.example.com;
18

19
    ssl_certificate /etc/letsencrypt/live/blog.example.com/fullchain.pem;
20
    ssl_certificate_key /etc/letsencrypt/live/blog.example.com/privkey.pem;
21
    ssl_protocols TLSv1.2 TLSv1.3;
22
    ssl_session_cache shared:SSL:10m;
23
    ssl_session_timeout 10m;
24

25
    location / {
26
        proxy_pass http://172.17.0.1:8080;
27
        proxy_set_header Host $host;
28
        proxy_set_header X-Real-IP $remote_addr;
29
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
30
        proxy_set_header X-Forwarded-Proto $scheme;
31
    }
32
}

新增的部分：

• 第一个 server 块只干两件事：保留 ACME 验证路径（续期还要用它，删了续期就失败），其余请求 return 301 https://$host$request_uri; 永久跳转到 HTTPS，$request_uri 保证跳转后路径和参数原样保留。
• 第二个 server 块监听 443 ssl，用 ssl_certificate / ssl_certificate_key 指向刚申请下来的证书，ssl_protocols 只允许 TLS 1.2 和 1.3，老旧协议全部关掉。
• 反代的四件套和 HTTP 版一字不差，注意此时 $scheme 的值变成了 https，后端靠它就知道外层是加密连接。

改好后先验配置再重载，不要直接重启：

1
docker compose exec nginx nginx -t      # 语法检查，必须看到 successful
2
docker compose exec nginx nginx -s reload

浏览器访问 https://blog.example.com，地址栏有锁、证书信息里签发者是 Let’s Encrypt，就算上线了。再访问 http://blog.example.com 应该会被自动跳到 HTTPS。

第四步：证书自动续期#

Let’s Encrypt 证书有效期只有 90 天，自动续期是这条路线的必修课。原理是定期跑 certbot renew（它只会续期离到期不足 30 天的证书，没到期跑了也无副作用），续期成功后重载 Nginx 让新证书生效。用宿主机的 cron 实现最稳妥：

1
crontab -e

加入一行（每周一凌晨 3 点执行，路径换成你的实际目录）：

1
0 3 * * 1 cd /opt/nginx-proxy && docker compose run --rm certbot renew --quiet && docker compose exec nginx nginx -s reload >> /var/log/certbot-renew.log 2>&1

用 systemd 的机器也可以写 timer，效果一样，二选一即可。续期机制上线后建议手动演练一次，确认整条链是通的：

1
cd /opt/nginx-proxy
2
docker compose run --rm certbot renew --dry-run

--dry-run 是向 Let’s Encrypt 的测试环境走一遍完整续期流程，不消耗正式限额，输出里看到 Congratulations, all simulated renewals succeeded 就说明解析、80 端口、验证路径都没问题。

WARNING

续期失败最常见的两个原因：一是有人「优化」配置时把 /.well-known/acme-challenge/ 那个 location 删了或被跳转规则吞了；二是 80 端口被关了。所以 HTTP server 块里的 ACME 路径和 301 跳转要并存——验证路径优先匹配自己的 location，其余才走跳转，上面配置的写法已经处理好了，不要把 return 301 写到 server 块顶层去，那样验证路径也会被跳走。

docker-compose.yml#

1
services:
2
  npm:
3
    image: jc21/nginx-proxy-manager:latest
4
    container_name: nginx-proxy-manager
5
    restart: unless-stopped
6
    ports:
7
      - "80:80"     # HTTP 入口
8
      - "443:443"   # HTTPS 入口
9
      - "81:81"     # 管理后台
10
    volumes:
11
      - ./data:/data
12
      - ./letsencrypt:/etc/letsencrypt

1
docker compose up -d

data 卷存 NPM 的全部配置和数据库，letsencrypt 卷存它申请的证书，两个都要持久化，重建容器不会丢配置。

首次登录：先改密码#

浏览器打开 http://服务器IP:81，用官方默认账号登录：

WARNING

admin@example.com / changeme 是 NPM 官方公开的默认账号密码，任何人都知道。登录后系统会强制要求你先完善资料并修改密码，不要跳过、不要拖延：81 端口等于把全站流量的总闸开在了公网，默认密码不改就是裸奔。改完密码后，进一步建议把 81 端口也收一下：只绑 127.0.0.1:81:81 再通过内网或隧道访问，或者在防火墙里只放行你自己的 IP。

添加一个反代站点（Proxy Host）#

登录后点顶部的 Hosts → Proxy Hosts → Add Proxy Host，在 Details 页填：

保存后先用 http://blog.example.com 访问验证反代本身通不通，通了再去开证书，不要两个变量一起改，出问题不好定位。

一键申请证书并强制 HTTPS#

编辑刚建的 Proxy Host，切到 SSL 页：

1. SSL Certificate 下拉选 Request a new SSL Certificate；
2. 打开 Force SSL（等于路线 A 里手写的 301 跳转）；
3. 打开 HTTP/2 Support；
4. 填你的邮箱，勾选同意 Let’s Encrypt 条款，保存。

NPM 会自动走完验证、签发、配置、重载的全过程，十几秒后 https://blog.example.com 就能访问了。证书续期也由 NPM 内部自动处理，不用再单独配 cron——这是图形化路线最省心的地方。

上游地址为什么填 172.17.0.1#

这是 NPM（以及一切独立部署的反代）最值得讲清楚的一个细节。添加 Proxy Host 时，后端地址有两种填法：

• 填容器名：要求 NPM 和后端服务处在同一个 Docker 网络里，NPM 才能靠内置 DNS 解析到容器名。后果是每接一个新服务，就要把 NPM 拉进那个服务的网络，服务多了 NPM 身上挂着一堆网络，配置互相耦合，删服务、改网络时还容易误伤总闸。
• 填 172.17.0.1:<端口>（本篇推荐）：172.17.0.1 是 Docker 默认网桥 docker0 在宿主机一侧的网关地址，从任何容器里访问它，就等于访问宿主机本身。所以后端服务只要把端口映射到宿主机（配合前面说的绑 127.0.0.1 更安全），NPM 用「网关地址 + 宿主机端口」就能找到它，完全不用把 NPM 拉进各业务网络。反代和业务彻底解耦：业务随便增删改，反代这边只改一行转发地址。

代价只有一个：后端服务必须在宿主机上有端口映射（哪怕只绑 127.0.0.1 也行，网关地址同样能连通回环绑定的端口）。对绝大多数个人部署来说，这个代价可以忽略，换来的是干净的网络结构。

502 Bad Gateway#

502 的含义非常明确：反代本身活着，但它连不上或读不懂后端。按这个顺序查，基本五分钟内定位：

1. 后端服务活没活。 docker ps 看容器在不在跑；直接在服务器上 curl -v http://127.0.0.1:8080（换成你的后端地址端口），本机都访问不通就先修后端，反代不用看了。
2. 转发地址和端口对不对。 对照 Proxy Host / 配置文件里的地址端口和后端实际监听的是否一致，尤其注意「容器内端口」和「映射到宿主机的端口」是两回事：走 172.17.0.1 时填的是宿主机映射端口。
3. 看反代的错误日志。 路线 A：docker compose logs nginx 或容器内 /var/log/nginx/error.log；路线 B：docker logs nginx-proxy-manager。日志会直说原因，常见三类：
   • connect() failed (111: Connection refused)：后端没监听这个端口，回到第 1、2 步。
   • no live upstreams：同上，本质还是连不上。
   • upstream sent too big header：后端返回头过大，给 location 加 proxy_buffer_size 128k; 和 proxy_buffers 4 256k; 再重载。

还有一个隐蔽情况：后端绑了 127.0.0.1、本机 curl 也通，但走网关地址就是不通——检查后端端口映射绑的是不是 127.0.0.1，绝大多数发行版上回环绑定对 172.17.0.1 过来的连接同样有效；个别环境不行的话，改绑 0.0.0.0 并用防火墙封掉外网访问该端口即可。

证书申请失败#

按可能性从高到低排查：

1. 域名没解析过来。 ping 域名 看 IP 对不对；刚改的解析没生效就等等，别反复重试耗限额。
2. 80 端口不通。 云安全组和本机防火墙两处都查；可以在别的网络用手机流量打开 http://域名 验证（能打开反代的默认页或后端都行，关键是通）。
3. ACME 路径被拦截。 路线 A 检查 /.well-known/acme-challenge/ 的 location 还在不在、有没有被 301 跳转吞掉；路线 B 一般不会，但如果 Advanced 里写过自定义配置要重点怀疑。
4. 触发 Let’s Encrypt 限额。 错误信息里出现 rate limit 就是它，只能等（重复证书限额按周滚动，失败验证按小时）。等待期间想先上线，可以临时用自签证书顶着，或者换一个子域名继续。

证书过期与有效期检查#

怀疑证书过期或想确认续期是否生效，用这两条命令在任何机器上都能查：

1
# 看证书的生效与到期时间
2
echo | openssl s_client -connect blog.example.com:443 -servername blog.example.com 2>/dev/null | openssl x509 -noout -dates
3

4
# 或者从 curl 的握手信息里看
5
curl -vI https://blog.example.com 2>&1 | grep -E "expire|SSL certificate verify"

notAfter 是到期时间。两条路线分别这样查：