Nginx Proxy Manager 证书管理实战：HTTP、DNS 与自定义证书的签发、续期与源码解析

Nginx Proxy Manager 证书管理实战HTTP、DNS 与自定义证书的签发、续期与源码解析【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager本文是 Nginx Proxy ManagerNPM证书模块的完整实战指南围绕HTTP 证书HTTP-01 挑战、DNS 证书DNS-01 挑战与自定义证书上传三种证书获取方式展开覆盖前置条件、界面操作、Lets Encrypt 签发原理、自动续期机制与常见排障。读完本文你将能根据自身域名与网络条件正确选择证书方案并理解 NPM 在签发与续期过程中对 Nginx 配置、DNS 记录和文件系统的底层操作。本文内容以仓库内帮助文档 frontend/src/locale/src/HelpDoc/en/Certificates.md及对应乌克兰语版本为主体结合后端源码与前端表单实现进行纵深讲解。一、NPM 中证书体系概览在 Nginx Proxy Manager 中证书是域名 私钥 证书链的集合被 Proxy Hosts、Redirection Hosts、Dead Hosts 与 Streams 引用。证书创建入口位于前端 Certificates 页面对应 API 为POST /api/nginx/certificates实现位于 backend/internal/certificate.js 的create方法。从数据模型看backend/models/certificate.js每条证书记录都带有provider字段用于区分证书来源provider 值来源自动续期通配符域名letsencryptHTTP 挑战Lets Encrypt 通过 HTTP 验证支持不支持letsencryptDNS 挑战meta.dns_challenge trueLets Encrypt 通过 DNS 验证支持支持other用户上传的自有 CA 证书不支持取决于证书本身其中前两类均由 NPM 调用certbot命令签发后端封装了完整的请求、续期与吊销流程见 backend/internal/certificate.js第三类则完全由用户提供证书材料NPM 负责校验并落盘。二、HTTP 证书通过 80 端口完成域名验证2.1 原理与前置条件HTTP 证书使用 Lets Encrypt 的HTTP-01 挑战webroot 模式。Lets Encrypt 服务器会尝试通过HTTP而非 HTTPS访问你域名下的挑战路径/.well-known/acme-challenge/xxx只有返回内容正确才会签发证书。在 NPM 中这一方法有两个硬性前置条件必须已为该域名创建了 Proxy Host且该 Proxy Host 通过 HTTP 可访问该 Proxy Host 的流量必须指向当前这台 Nginx 实例因为挑战文件由本机 Nginx 对外提供。签发成功后你可以修改该 Proxy Host 使用这张证书开启 HTTPS但为了让证书后续能够自动续期该 Proxy Host 必须继续保持 HTTP 可访问——这是本帮助文档明确强调的约束见 frontend/src/locale/src/HelpDoc/en/Certificates.md。该方法不支持通配符域名如*.example.com。2.2 操作步骤进入Certificates页面点击Add SSL Certificate → Lets Encrypt选择HTTP Certificate方式在 Domain Names 中输入域名可填多个并选择密钥类型Key TypeRSA 或 ECDSA默认 ECDSA见 frontend/src/modals/HTTPCertificateModal.tsx点击SaveNPM 将调用后端完成签发。2.3 签发背后的完整流程源码级后端create方法对 HTTP 挑战执行了严格的六步流程backend/internal/certificate.js通过internalHost.getHostsWithDomains找出所有使用了这些域名的 Proxy Host / Redirection Host / Dead Host通过disableInUseHosts临时移除这些主机的 Nginx 配置调用internalNginx.generateLetsEncryptRequestConfig生成一份临时的 Lets Encrypt 请求配置模板见 backend/templates/letsencrypt-request.conf重新加载 Nginx 后调用requestLetsEncryptSsl请求证书删除临时配置并再次 reload通过enableInUseHosts恢复之前被禁用的主机配置。之所以要先禁用再恢复是因为签发期间域名需要由挑战专用配置响应/.well-known/acme-challenge/路径。该路径由 docker/rootfs/etc/nginx/conf.d/include/letsencrypt-acme-challenge.conf 定义将请求映射到/data/letsencrypt-acme-challenge目录并显式关闭auth_basic与 IP ACL以放行 Lets Encrypt 的验证请求。真正的签发由 certbot 完成requestLetsEncryptSslbackend/internal/certificate.js拼装的核心参数为certbot certonly \ -n \ --config /etc/letsencrypt.ini \ --work-dir /tmp/letsencrypt-lib \ --logs-dir /data/logs \ --cert-name npm-certificateId \ --agree-tos \ --authenticator webroot \ -m 用户邮箱 \ --preferred-challenges http \ --domains 域名1,域名2,... \ [--key-type rsa|ecdsa]签发完成后NPM 会从/etc/letsencrypt/live/npm-id/fullchain.pem读取证书到期时间并回写数据库。2.4 签发前的 HTTP 可达性测试前端表单提供了 Test 按钮frontend/src/modals/HTTPCertificateModal.tsx调用POST /api/nginx/certificates/test-http。后端testHttpsChallengebackend/internal/certificate.js会先在/data/letsencrypt-acme-challenge/.well-known/acme-challenge/写入一个test-challenge测试文件然后逐个域名请求http://域名/.well-known/acme-challenge/test-challenge最后清理测试文件。返回结果对应前端展示的状态ok服务器返回 200 且内容正确可以签发no-host域名无法解析404主机存在但未返回挑战文件wrong-data返回了错误内容failed/other:code其他错误。建议在正式签发前先运行该测试避免因 DNS 未生效或 Proxy Host 未指向本机而导致签发失败。三、DNS 证书通过 DNS 记录完成域名验证3.1 原理与优势DNS 证书使用DNS-01 挑战NPM 借助DNS Provider 插件在你的域名 DNS 中自动创建一条临时的 TXT 记录Lets Encrypt 查询该记录确认你对域名的控制权后签发证书。与 HTTP 方式相比DNS 方式有两点关键差异不需要预先创建 Proxy Host也不要求任何主机通过 HTTP 可访问支持通配符域名如*.example.com这是签发泛域名证书的唯一内置途径。3.2 DNS Provider 插件体系NPM 内置了庞大的 DNS 插件清单定义于 backend/certbot/dns-plugins.json包含 Cloudflare、DigitalOcean、Cloudflare、Google、Route 53、OVH、Vultr、Hetzner、阿里云Aliyun、腾讯云Tencent Cloud、DNSPod、DuckDNS、Namecheap、GoDaddy、CloudXNS 等上百家提供商。每条记录包含插件名称、certbot 包名、版本约束与凭据模板。例如 Cloudflare 的凭据模板为# Cloudflare API token dns_cloudflare_api_token0123456789abcdef0123456789abcdef01234567阿里云的模板为dns_aliyun_access_key 12345678 dns_aliyun_access_key_secret 1234567890abcdef1234567890abcdef前端通过GET /api/nginx/certificates/dns-providersbackend/routes/nginx/certificates.js拉取提供商列表选择后自动带入对应的凭据模板供用户填写frontend/src/components/Form/DNSProviderFields.tsx。3.3 操作步骤进入Certificates → Add SSL Certificate → Lets Encrypt选择DNS Certificate填写域名勾选通配符时输入*.example.com选择 DNS Provider在凭据编辑器中填写该提供商的 API 凭据界面会提示凭据以明文保存在数据库中需谨慎对待见 frontend/src/components/Form/DNSProviderFields.tsx可选设置Propagation SecondsDNS 记录传播等待时间07200 秒用于等待 TXT 记录在全球生效后再让 Lets Encrypt 校验点击 Save。3.4 签发背后的完整流程源码级DNS 挑战走requestLetsEncryptSslWithDnsChallengebackend/internal/certificate.js关键步骤调用installPlugin按需安装对应的 certbot DNS 插件将用户填写的凭据以0600 权限写入/etc/letsencrypt/credentials/credentials-id避免敏感信息被其他用户读取执行 certbotcertbot certonly \ -n \ --config /etc/letsencrypt.ini \ --cert-name npm-certificateId \ --agree-tos \ -m 用户邮箱 \ --preferred-challenges dns \ --domains 域名1,域名2,... \ --authenticator dns插件全名 \ --dns插件全名-credentials /etc/letsencrypt/credentials/credentials-id \ [--dns插件全名-propagation-seconds 秒数]对于 Route 53 这类特殊插件不传--credentials参数而是通过环境变量AWS_CONFIG_FILE指向凭据文件backend/internal/certificate.jsDuckDNS 则会追加--dns-duckdns-no-txt-restore参数。值得注意的是由于 DNS 挑战不需要临时 Nginx 配置create流程中会跳过生成/删除 LE 请求配置两步仅做 reload 与主机启用/禁用处理backend/internal/certificate.js。这也从实现层面印证了文档所述申请 DNS 证书前无需创建 Proxy Host。四、自定义证书上传自有 CA 签发的证书4.1 适用场景如果你已经拥有由自己的 CA证书颁发机构签发的 SSL 证书例如企业内网 CA、商业证书或已在其他平台申请的证书可以使用Custom Certificate方式直接上传无需经过 Lets Encrypt。后端将此类证书的provider记为other。4.2 需要准备的三份文件在 frontend/src/modals/CustomCertificateModal.tsx 中可以看到上传表单包含三个文件输入框与一个名称输入框字段说明是否必填Name证书显示名称1255 字符必填Certificate Key私钥文件PEM必填Certificate证书文件PEM含公钥与主体信息必填Intermediate Certificate中间证书链文件PEM选填4.3 校验—创建—上传三段式流程前端的提交逻辑frontend/src/modals/CustomCertificateModal.tsx清晰展示了三段式流程校验POST /api/nginx/certificates/validate对私钥与证书做合法性检查创建POST /api/nginx/certificates创建provider: other的证书空记录上传POST /api/nginx/certificates/id/upload将文件写入后端存储。后端校验逻辑在internalCertificate.validatebackend/internal/certificate.js私钥通过openssl pkey -in file -check -noout验证若包含密码保护或格式非法会直接报错checkPrivateKeybackend/internal/certificate.js证书与中间证书通过openssl x509解析出 CNsubject、颁发者issuer与有效期notBefore/notAfter并检测是否已过期getCertificateInfoFromFilebackend/internal/certificate.js。上传成功后后端会将证书链与私钥写入/data/custom_ssl/npm-id/fullchain.pem与privkey.pemwriteCustomCertbackend/internal/certificate.js并把证书的 CN 与到期时间回写数据库。若提供了中间证书会自动追加到fullchain.pem中。自定义证书不会自动续期到期后需要你手动重新上传替换。五、Lets Encrypt 证书的自动续期机制5.1 续期定时器NPM 后端启动时会初始化一个每小时执行一次的续期定时器initTimerbackend/internal/certificate.js并立即触发一次检查。检查逻辑processExpiringHostsbackend/internal/certificate.js会查询所有provider letsencrypt且距离到期不足 30 天的证书逐个执行续期。5.2 串行续期避免冲突源码注释明确说明续期必须串行执行否则会触发 certbot 的 Another instance of Certbot is already running 错误backend/internal/certificate.js。因此所有待续期证书通过 Promise 链依次处理单个失败仅记录日志不会中断其余证书的续期。5.3 手动续期与吊销手动续期Certificates 页面提供 Renew 按钮调用POST /api/nginx/certificates/id/renewbackend/routes/nginx/certificates.js。后端按证书是否启用 DNS 挑战自动选择续期方式并在成功后更新expires_on与审计日志。注意只有letsencrypt类型的证书允许续期backend/internal/certificate.js。删除吊销删除 Lets Encrypt 证书时后端会执行certbot revoke --delete-after-revoke主动吊销backend/internal/certificate.js。下载备份Lets Encrypt 证书可从页面打包下载GET /api/nginx/certificates/id/download后端会将/etc/letsencrypt/live/npm-id/下的.pem文件压缩为 zipbackend/internal/certificate.js。六、权限、邮箱与其他配置要点6.1 操作权限证书的新增、修改、删除与列表查看均有独立权限点certificates:create、certificates:update、certificates:delete、certificates:get、certificates:list前端也通过CERTIFICATES/MANAGE权限控制按钮显隐frontend/src/pages/Certificates/Table.tsx。非管理员用户需要被授予证书管理权限见权限校验定义 backend/lib/access/certificates-create.json。6.2 用户邮箱是硬性要求签发 Lets Encrypt 证书时certbot 需要注册邮箱。后端create流程会校验当前用户是否设置了有效邮箱否则抛出 A valid email address must be set on your user account to use Lets Encrypt 错误backend/internal/certificate.js。因此首次使用 Lets Encrypt 前请先在用户资料中填写邮箱。6.3 环境级配置backend/internal/certificate.js 中的getAdditionalCertbotArgs展示了两个可配置项自定义 ACME 服务器通过LE_SERVER环境变量传入--server urlLets Encrypt 预演环境配置LE_STAGING后追加--staging用于在正式签发前测试流程预演证书不受速率限制。七、常见问题与排障清单现象可能原因与排查方向HTTP 证书签发失败测试返回no-host域名 DNS 未解析到本机或 Proxy Host 未指向本 Nginx 实例HTTP 证书签发失败返回404Proxy Host 存在但未走挑战配置路径检查 Nginx 是否已 reload提示需要邮箱当前用户账户未设置邮箱见 6.2 节DNS 证书签发超时TXT 记录传播慢调大 Propagation Seconds07200 秒通配符域名无法通过 HTTP 方式签发通配符只支持 DNS 方式请改用 DNS Certificate自定义证书上传报私钥无效私钥含密码保护或格式非法需使用无密码的 PEM 私钥证书到期未自动续期确认 Proxy Host 仍保持 HTTP 可访问HTTP 方式续期定时器每小时运行一次可先手动点击 Renew结语Nginx Proxy Manager 将 Lets Encrypt 的 HTTP-01 与 DNS-01 两种挑战方式、上百家 DNS 提供商的插件体系以及自有证书上传统一封装在 Certificates 页面之下后端通过 backend/internal/certificate.js 与 certbot 协作完成签发、续期、吊销与文件落盘前端通过 frontend/src/modals/HTTPCertificateModal.tsx、frontend/src/modals/DNSCertificateModal.tsx、frontend/src/modals/CustomCertificateModal.tsx 提供操作界面。选择证书方式的核心原则是能通过 HTTP 访问本机且不需要通配符 → 用 HTTP 方式需要通配符或主机不在公网 80 端口可达 → 用 DNS 方式已有自有 CA 证书 → 直接上传自定义证书。结合本文提供的源码级流程与排障清单你可以更准确地完成证书配置并快速定位问题。【免费下载链接】nginx-proxy-managerDocker container for managing Nginx proxy hosts with a simple, powerful interface项目地址: https://gitcode.com/GitHub_Trending/ng/nginx-proxy-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考