nginx-ui 开发环境中的 Pebble 本地 ACME 测试证书体系certs/localhost 目录全解【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui导读本文围绕 nginx-ui 仓库.devcontainer/pebble-test/certs/localhost目录的说明文档完整讲解该目录下cert.pem与key.pem的用途、它们与 Pebble本地 ACME 测试服务器及 nginx-ui 证书签发流程的关系并给出如何让测试代码信任 Pebble 根 CA、如何用minica重新生成整套测试证书的可执行方案。读完本文你将理解 nginx-ui 开发容器中零成本签发测试证书的完整链路并能在自己的测试环境中复现这一套证书体系。目录定位一个目录、一对证书、一项职责certs/localhost目录极其精简仅包含三个文件README.md说明文档即本文的原始依据cert.pemPebble HTTPS 服务器使用的终端实体证书叶子证书key.pem与该证书配对的私钥。在 docker-compose.yml 中Pebble 容器通过 volume 挂载将整个.devcontainer/pebble-test目录暴露为容器内的/test随后 pebble-config.json 通过certificate与privateKey两个配置项指向certificate: /test/certs/localhost/cert.pem, privateKey: /test/certs/localhost/key.pem,也就是说这一对文件是Pebble 自己对外提供 HTTPS ACME API 时使用的 TLS 证书对应端口 14000而不是 Pebble 签发给测试方应用的证书——后者由certs/根目录的pebble.minica.pemCA 签发二者职责不同阅读时注意区分。证书的 SAN 设计为什么是 127.0.0.1 / localhost / pebble根据 certs/localhost/README.md 的说明这对证书包含IP SAN127.0.0.1DNS SANlocalhost、pebble。这个 SAN 组合与 nginx-ui 的开发容器网络拓扑严格对应localhost与127.0.0.1当开发者在本机浏览器或本机进程访问https://localhost:14000/dir时Pebble 返回的证书 SAN 与主机名匹配TLS 握手不会出现主机名不匹配错误pebble这是 docker-compose 网络中 Pebble 服务的服务名见 docker-compose.yml 中pebble:服务定义。容器内的其他服务如 nginx-ui 主容器通过https://pebble:14000/dir访问 ACME 目录时pebble这个 DNS SAN 恰好覆盖了该主机名。nginx-ui 前端也内置了对这一测试端点的支持在 app/src/constants/acme.ts 的CA_SERVER_OPTIONS列表中Pebble Local Test一档直接指向https://localhost:14000/dir与 Pebble 的目录地址一一对应便于开发者在 nginx-ui 的证书申请界面中一键选用本地测试 CA。信任 Pebble 根 CA让测试代码通过 TLS 校验certs/localhost的叶子证书由 certs/ 根目录中的 CA 证书pebble.minica.pem签发。因此要让自己的测试代码如调用 Pebble ACME API 的客户端、nginx-ui 的证书签发模块在访问 Pebble 时不做 HTTPS 报错必须显式信任该 CA配置 ACME 客户端使其运行时使用的根 CA 列表包含pebble.minica.pem文件。绝大多数 ACME 客户端如 Go 的golang.org/x/crypto/acme、lego、certbot 等都提供自定义根 CA或自定义 CA 文件的运行时选项把pebble.minica.pem加进去即可不要把它加入系统信任库。安全红线Pebble CA 私钥是公开的certs/README.md 给出了极其明确的警告不要把pebble.minica.pem加入系统信任库不要在生产代码或生产环境中信任它原因CA 私钥pebble.minica.key.pem是公开的任何拿到它的人都能签发出被信任了 Pebble CA 的系统所信任的任意证书。这条红线同样适用于certs/localhost下的key.pem它同样不是机密只服务于本地开发/CI 测试环境任何将这些文件用于生产信任链的做法都属于安全事故。重新生成整套测试证书minica 命令详解当需要重建证书例如 SAN 变更、证书过期、或换一台机器重新初始化开发环境时certs/README.md 给出了标准做法在.devcontainer/pebble-test/certs/目录下运行minicaminica -ca-cert pebble.minica.pem \ -ca-key pebble.minica.key.pem \ -domains localhost,pebble \ -ip-addresses 127.0.0.1参数含义逐一说明参数含义-ca-cert pebble.minica.pem指定用于签发子证书的 CA 证书文件-ca-key pebble.minica.key.pem指定 CA 私钥minica用它对新证书签名-domains localhost,pebble生成两个 DNS SANlocalhost与pebble-ip-addresses 127.0.0.1生成一个 IP SAN127.0.0.1命令完成后minica会在当前目录下生成localhost/子目录其中即包含新的cert.pem与key.pem覆盖式重建certs/localhost目录中的文件对应minica的默认输出行为按-domains的第一个域名建立输出目录。需要先安装 MiniCA 工具go install github.com/jsha/minicalatest一类方式再于该目录执行命令。完整上下文证书如何嵌入 nginx-ui 的本地 ACME 测试环境将上面的证书体系放回开发容器的整体拓扑中可以更清楚地看到它的位置docker-compose.yml 启动pebble服务ghcr.io/letsencrypt/pebble:latest启动参数-config /test/config/pebble-config.json -strict -dnsserver challtestsrv:8053并暴露14000HTTPS ACME API与15000HTTPS 管理 API两个端口Pebble 根据 pebble-config.json 加载certs/localhost/cert.pem与key.pem作为自身 TLS 证书配置中还包含 HTTP-01/TLS-ALPN-01 校验端口httpPort: 5002、tlsPort: 5001、retryAfter节流参数以及证书 profile 有效期等配套的 pebble-config-external-account-bindings.json 则演示了开启externalAccountBindingRequired: true、配置 EAB HMAC 密钥的形态用于测试需要外部账号绑定EAB的 CA 流程nginx-ui 主容器通过环境变量NGINX_UI_CERT_CA_DIRhttps://pebble:14000/dir见 docker-compose.yml将 ACME 目录指向容器网络内的 Pebble从而实现开发环境下真实走一遍申请证书 → 校验 → 签发 → 落盘的完整链路而无需触碰真实 CA。从源码结构可以推断nginx-ui 的证书签发模块api/certificate/issue.go、internal/cert/在开发模式下即面向此类本地 ACME 目录工作certs/localhost提供的正是这条链路最底层的Pebble 自身可信身份支撑。这也解释了为何该 README 虽短却与容器编排、Pebble 配置、前端 CA 选项列表三处代码遥相呼应。小结certs/localhost目录虽小却是 nginx-ui 本地 ACME 测试环境的信任基石cert.pem/key.pem为 Pebble 的 HTTPS ACME API 提供身份127.0.0.1、localhost、pebble三组 SAN 分别覆盖本机访问与容器网络内访问两种场景配合根目录的pebble.minica.pem做客户端信任即可在完全离线的环境中完成证书签发全流程测试。需要重建时用minica在.devcontainer/pebble-test/certs/下按上文命令重新生成即可——务必牢记这一切仅限本地与 CI 测试Pebble 的 CA 与私钥永远不能进入生产信任链。【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
