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-manager 前端帮助文档frontend/src/locale/src/HelpDoc/fr/Certificates.md中的证书章节展开系统讲解该 Docker 版 Nginx 反向代理管理工具中三类证书的申请与使用方式HTTP 验证的 Lets Encrypt 证书、DNS 验证的 Lets Encrypt 证书以及自定义证书导入。读完本文你将掌握三类证书各自的适用场景与前置条件是否需要 Proxy Host、是否支持通配符域名理解证书签发、自动续期、吊销与下载的底层实现并能结合 Web 界面与 REST API 完成证书的完整生命周期管理。一、证书体系总览在 nginx-proxy-manager 中证书Certificate是独立于 Proxy Host、Redirection Host、Stream 等对象的一等公民可以被多个主机引用。从数据库模型与前端列表页frontend/src/pages/Certificates/Table.tsx可以看到每张证书包含以下关键属性属性说明provider证书来源letsencryptLets Encrypt 自动签发或other自定义证书domain_names证书覆盖的域名列表最多 100 个不能包含空格及特殊符号nice_name证书的显示名称Lets Encrypt 证书自动取域名拼接自定义证书可手动命名expires_on过期时间签发或续期后由后端自动写入meta扩展元数据dns_challenge、dns_provider、dns_provider_credentials、key_type、propagation_seconds等上述字段的完整定义见 backend/schema/components/certificate-object.json其中key_type支持rsa与ecdsa两种私钥类型默认rsa。在 Web 界面中点击证书页的添加证书按钮会展开三种创建方式见 frontend/src/pages/Certificates/Table.tsxLets EncryptHTTP 验证通过 80 端口 HTTP 挑战验证域名所有权Lets EncryptDNS 验证通过 DNS Provider 插件写入临时 DNS 记录验证域名所有权自定义证书上传由自己 CA 签发的证书文件。下面逐一展开。二、HTTP 验证证书Lets Encrypt via HTTP2.1 工作原理HTTP 验证证书的含义是Lets Encrypt 的服务器会通过HTTP而不是 HTTPS访问你的域名若访问成功则颁发证书。换言之验证是否成功的唯一标准是http://你的域名能否被 Lets Encrypt 服务器解析并返回预期的挑战内容。结合后端实现backend/internal/certificate.js一次 HTTP 验证证书的创建流程如下查出所有使用了该证书域名的 Proxy Host / Redirection Host / Dead Host并临时禁用其 Nginx 配置disableInUseHosts生成临时的 Lets Encrypt 请求配置并 reload Nginx——该配置由模板 backend/templates/letsencrypt-request.conf 渲染监听 80 端口server_name为证书中的全部域名并 includeconf.d/include/letsencrypt-acme-challenge.conf其余请求一律返回 404调用 certbot 发起证书请求certonly模式--authenticator webroot--preferred-challenges http见 backend/internal/certificate.js请求成功后删除临时配置、reload Nginx并恢复之前被禁用的主机从磁盘上的fullchain.pem解析出到期时间写回数据库并记录审计日志。2.2 前置条件根据帮助文档与源码HTTP 验证方式有以下硬性要求必须为你的域名创建 Proxy Host且该 Proxy Host 必须能通过 HTTP 访问、并指向当前 Nginx 安装即 A 记录/解析指向部署 nginx-proxy-manager 的这台机器证书签发成功后可以把 Proxy Host 的 SSL 证书切换为这张新证书以启用 HTTPS续期时依然依赖 HTTP 访问Proxy Host 必须始终保留 HTTP 入口否则到期后无法自动续期不支持通配符域名wildcard domains如*.example.com。2.3 签发前的连通性测试前端在提交前提供了测试按钮frontend/src/modals/HTTPCertificateModal.tsx后端对应接口为POST /api/nginx/certificates/test-httpbackend/routes/nginx/certificates.js。其实现逻辑backend/internal/certificate.js是先在本地写一个挑战测试文件/data/letsencrypt-acme-challenge/.well-known/acme-challenge/test-challenge然后借助第三方测试服务对每个域名发起 HTTP 探测返回结果包括返回状态含义ok服务器可达且返回了正确内容可以签发404服务器可达但返回 404可能被其他站点占用no-host域名未解析到本机wrong-data返回了错误内容failed/other:...网络或响应异常建议在正式提交前先执行测试避免签发失败。三、DNS 验证证书Lets Encrypt via DNS3.1 工作原理DNS 验证证书要求你使用DNS Provider 插件。流程是插件在你的域名下创建一条临时 TXT 记录Lets Encrypt 查询该记录以确认你对域名的控制权查询成功后即颁发证书。后端实现backend/internal/certificate.js的关键点按dns_provider动态安装对应的 certbot 插件installPlugin插件清单见 backend/certbot/dns-plugins.json把dns_provider_credentials凭据内容写入/etc/letsencrypt/credentials/credentials-{id}权限为0600并通过--plugin-credentials参数传给 certbotRoute 53 是特例改以AWS_CONFIG_FILE环境变量方式传递见 backend/internal/certificate.js以--preferred-challenges dns发起certonly请求可选参数propagation_seconds用于控制 DNS 记录传播等待时间前端输入范围 07200 秒见 frontend/src/components/Form/DNSProviderFields.tsxDNS 挑战无需生成临时的 nginx 配置流程中直接 reload Nginx 后请求证书失败时恢复被禁用的主机并抛错。3.2 与 HTTP 验证的关键差异对比项HTTP 验证DNS 验证前置 Proxy Host必须不需要Proxy Host 需保留 HTTP 访问必须否则无法续期不需要通配符域名不支持支持验证通道80 端口 HTTPDNS TXT 记录临时 nginx 配置需要不需要也就是说如果你的域名还没创建任何 Proxy Host比如想先给*.example.com申请一张通配符证书备用或域名暂时不能通过 HTTP 访问到本机DNS 验证是唯一选择。3.3 DNS Provider 凭据前端会从GET /api/nginx/certificates/dns-providers拉取可用插件列表backend/routes/nginx/certificates.js返回每个插件的id、name与凭据模板。选择某个 Provider 后前端会预填对应的凭据示例如dns_cloudflare_api_token...你在编辑器中替换为真实密钥即可frontend/src/components/Form/DNSProviderFields.tsx。仓库内置的 Provider 覆盖主流厂商例如Cloudflare、Aliyun阿里云、DNSPod、Tencent Cloud腾讯云、GoDaddy、Route 53Amazon、Google、OVH、Vultr、DuckDNS、CloudXNS、Hetzner 等完整清单见 backend/certbot/dns-plugins.json。注意DNS 凭据属于敏感信息。后端在 API 返回中会通过omissions过滤掉meta.dns_provider_credentials字段backend/internal/certificate.js查询与列表接口均不会回传明文密钥。四、自定义证书Custom Certificate4.1 适用场景自定义证书用于导入由你自己的证书颁发机构CA签发的 SSL 证书例如企业内网自建 CA、商业证书等。4.2 需要准备的文件上传时涉及三类文件allowedSslFiles见 backend/internal/certificate.jscertificate证书文件主证书PEM 格式certificate_key私钥文件PEM 格式intermediate_certificate中间证书可选若 CA 提供了链证书。4.3 后端校验与落盘后端在保存前会调用validatebackend/internal/certificate.js做两件事对私钥执行openssl pkey -check -noout校验密钥有效性backend/internal/certificate.js对证书与中间证书执行openssl x509 -subject/-issuer/-dates解析提取 CN、签发者与有效期并拒绝已过期的证书backend/internal/certificate.js。校验通过后证书会被写入/data/custom_ssl/npm-{id}/目录主证书与中间证书拼接为fullchain.pem私钥写入privkey.pembackend/internal/certificate.js之后即可被 Proxy Host 等对象引用。与 Lets Encrypt 证书不同自定义证书不能通过系统自动续期到期前需手动更换上传新的证书可通过POST /api/nginx/certificates/{id}/upload接口更新文件见 backend/routes/nginx/certificates.js。五、证书的自动续期与手动管理5.1 自动续期机制Lets Encrypt 证书默认有效期为 90 天nginx-proxy-manager 内置了续期定时器backend/internal/certificate.js启动时立即执行一次检查之后每小时检查一次intervalTimeout: 1000 * 60 * 60检查条件是provider letsencrypt且expires_on距今不足30 天renewBeforeExpirationBy: [30, days]所有续期任务串行执行sequence链式 Promise避免并发触发 certbot 的 Another instance of Certbot is already running 错误续期完成后会从fullchain.pem重新解析到期时间并更新数据库同时写入renewed审计日志。5.2 手动续期、下载与吊销除了自动续期也可以在证书列表的右键菜单中手动操作frontend/src/pages/Certificates/Table.tsx操作接口说明手动续期POST /api/nginx/certificates/{id}/renew仅 Lets Encrypt 证书可用强制续期--force-renewal下载GET /api/nginx/certificates/{id}/download仅 Lets Encrypt 证书可用将 live 目录下的.pem文件打包为 ZIP删除/吊销DELETE /api/nginx/certificates/{id}软删除记录若为 Lets Encrypt 证书同时执行certbot revoke并删除凭据文件backend/internal/certificate.js5.3 证书生命周期中的域名冲突处理签发与续期时若证书域名正被其他主机使用后端会临时摘除这些主机的 Nginx 配置disableInUseHosts/enableInUseHosts见 backend/internal/certificate.js避免 HTTP 验证时被其他站点占用 80 端口返回错误内容。流程结束后立即恢复并 reload对业务的影响窗口很小。六、总结与选型建议需求推荐方式已有指向本机的 Proxy Host且保持 HTTP 可达HTTP 验证证书最省事需要通配符域名*.example.comDNS 验证证书不支持通配符的 HTTP 验证不可用域名未解析到本机、暂无 Proxy Host、或 80 端口被占用DNS 验证证书内网/商用证书、自有 CA 签发自定义证书导入三种方式的共性是证书在 nginx-proxy-manager 中是独立对象可被 Proxy Host、Redirection Host、Dead Host 与 Stream 共享引用Lets Encrypt 证书由系统自动续期到期前 30 天、每小时检查自定义证书需手动更新。相关源码可进一步阅读 backend/internal/certificate.js、backend/routes/nginx/certificates.js 与 backend/certbot/dns-plugins.json前端交互则见 frontend/src/modals/HTTPCertificateModal.tsx、frontend/src/modals/DNSCertificateModal.tsx 与 frontend/src/modals/CustomCertificateModal.tsx。【免费下载链接】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），仅供参考