跳到主要内容
基础知识

测试环境 SSL 证书怎么配?私有 CA、mkcert 与 Let’s Encrypt 暂存环境实操指南

测试环境ssl证书 — 测试环境 SSL 证书怎么配?私有 CA、mkcert 与 Let's Encrypt 暂存环境实操指南
核心结论

测试环境 SSL 证书推荐用自建私有 CA 签发:根 CA 有效期可设 3650 天,服务器证书控制在 398 天以内,把根 CA 导入各端信任库后,Chrome、curl、Java、Node 均可消除证书告警。 最快的一条命令方案:mkcert v1.4.4 执行 mkcert -install && mkcert api.test.local 127.0.0.1,会自动生成根 CA 并写入本机信任库。 Let's Encrypt 暂存环境目录地址是 https://acme-staging-v02.api.letsencrypt.org/directory,它签发的证书本身不被信任,只适合演练 ACME 签发与续期流程。 最高频的两个报错 curl: (60) SSL certificate problem: self signed certificate 和 Java 的 PKIX path building failed,根因都是客户端 trust store 里没有这张根 CA。 验证是否生效用 openssl s_client -connect host:443 -servername host -CAfile test-ca.crt -verify_return_error,输出 Verify return code: 0 (ok) 才说明链路完整。

测试环境 SSL 证书为什么老是被浏览器和 SDK 拦截?6 个根因拆解

“本地 curl 通、Chrome 报红叉、Jenkins 上 500”——同一个测试环境 SSL 证书在三处表现不同,通常不是运气问题,而是下面 6 个根因之一。按报错信息对应排查最快。

根因 1:签发者不在客户端的 trust store 里。浏览器和 curl 只信任系统或内置的根证书,你的自签证书或私有 CA 默认不在其中。Chrome 119+ 报 NET::ERR_CERT_AUTHORITY_INVALID,curl 7.81 报 curl: (60) SSL certificate problem: self signed certificate。先确认服务端实际发出的链和签名者:

# 1) 看服务端实际发出的证书链,verify error:num=18 即“自签证书”
openssl s_client -connect api.test.local:443 -servername api.test.local -showcerts /dev/null 
  | grep -E "verify|s:|i:"
# 2) 用私有根 CA 显式校验(curl 7.81+ 的 --cacert 指定受信根)
curl -v --cacert ./rootCA.pem https://api.test.local/health
# 报 curl: (60) SSL certificate problem: self signed certificate → 根 CA 未进入信任链

根因 2:SAN 缺失。据 RFC 6125 及 Chrome 58+ 的实际行为,证书校验不再回退到 CN 字段;测试环境 SSL 证书必须带 subjectAltName=DNS:api.test.local,IP:127.0.0.1,否则报 ERR_CERT_COMMON_NAME_INVALID。注意 -addext 需 OpenSSL 1.1.1+,更老的 1.0.2 只能写 openssl.cnf。

根因 3:有效期超限。Apple 自 2020-09-01 起要求 TLS 服务器证书有效期 ≤398 天(iOS 13+ / macOS 10.15+),用 openssl -days 3650 生成的叶子证书会被直接拒绝;但根 CA 设 3650 天是允许的——这条规则只约束叶子证书。下面一条命令同时满足 SAN 与 398 天:

# -days 397 留出 1 天余量;根 CA 可另用 3650 天
openssl req -x509 -newkey rsa:2048 -nodes -days 397 
  -keyout test.key -out test.crt 
  -subj "/CN=api.test.local" 
  -addext "subjectAltName=DNS:api.test.local,DNS:*.test.local,IP:127.0.0.1"
# 自检:SAN 覆盖实际访问的每个主机名/IP,日期落在 398 天内
openssl x509 -in test.crt -noout -text | grep -A1 "Subject Alternative Name"
openssl x509 -in test.crt -noout -dates

根因 4:域名过不了 ACME 验证。Let’s Encrypt 生产环境的 HTTP-01 要求 80 端口公网可达,.local、.test、.internal 这类内网域名根本签不下来;即便切到 Let’s Encrypt 暂存环境(staging,速率限制更宽松),签发链也不受客户端信任。这类域名只能改用 DNS-01(支持泛域名)或私有 CA 方案。

根因 5:证书链不完整。Nginx 只配了叶子证书、没拼中间证书时,桌面浏览器常能靠 AIA 补齐,但 Android 7 以下与 Java 8 的默认信任库会报 PKIX path building failed。测试环境 SSL 证书同样要把 fullchain 拼好:

# 顺序必须是 叶子证书 → 中间 CA;根 CA 不要拼进 fullchain
cat api.test.local.crt intermediate-ca.crt > api.test.local.fullchain.pem

# /etc/nginx/conf.d/api.test.local.conf
server {
    listen 443 ssl;
    server_name api.test.local;
    ssl_certificate     /etc/nginx/ssl/api.test.local.fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/api.test.local.key;
}
# 验证:s_client 输出应出现 s:(叶子)与 i:(中间 CA)两层
openssl s_client -connect api.test.local:443 -showcerts /dev/null | grep -E "s:|i:"

根因 6:团队各自签发。每个开发者本地跑一遍 mkcert,生成的根 CA 互不相同,于是“本地能调、Jenkins 上 500”。根 CA 必须团队共享:把一份 rootCA.pem 放进仓库或 Secret,并在 CI 里注入信任,而不是每人本地生成。

# 输出本地根 CA 目录;不同机器路径不同 = 根因 6 的直接证据
mkcert -CAROOT
根因 典型报错 30 秒自查命令
自签/私有 CA 未入信任库 NET::ERR_CERT_AUTHORITY_INVALID openssl s_client -connect host:443 -showcerts
缺 SAN ERR_CERT_COMMON_NAME_INVALID openssl x509 -in c.pem -noout -text | grep -A1 “Subject Alternative Name”
有效期 >398 天 iOS/macOS 直接拒绝握手 openssl x509 -in c.pem -noout -dates
内网域名无法 HTTP-01 ACME 校验 NXDOMAIN / timeout dig +short api.test.local
链不完整 PKIX path building failed openssl s_client -showcerts(看是否只有一层 s:)
各自签发 本地通、CI 报 500 mkcert -CAROOT(对比各机器路径)

手把手:测试环境 SSL 证书从零签发到全端部署的 6 个步骤

这一步把”能跑起来”变成”可复制、可轮换”。下面 6 个步骤按依赖顺序排列,每一步都给完整命令,照抄即可。

步骤 1:先盘点域名和 IP,再动手签证书

测试环境 SSL 证书最常见的翻车点不是签发失败,而是漏了某个访问方式——浏览器用域名能开,Postman 用 IP 直连就报 x509: certificate is valid for api.test.local, not 10.0.3.21。所以先写 san.cnf,把所有入口一次性列进 subjectAltName:

# san.cnf —— 适用 OpenSSL 1.1.1+ / 3.x
[req]
distinguished_name = dn
req_extensions     = v3_req
prompt             = no

[dn]
CN = api.test.local

[v3_req]
basicConstraints = CA:FALSE
keyUsage         = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName   = @alt_names

[alt_names]
DNS.1 = api.test.local
DNS.2 = *.test.local        # 通配只覆盖一级:a.test.local 可以,a.b.test.local 不行
IP.1  = 127.0.0.1
IP.2  = 10.0.3.21

同时确认客户端类型,因为信任库位置完全不同,这决定了步骤 5 要做几份:

客户端 信任库位置 关键注意点
Chrome / Edge 跟随操作系统(Windows 证书存储、macOS 钥匙串) 导入后需重启浏览器
Firefox 自带 NSS 库,不读系统库 需在 about:certificate 单独导入
Java 8 $JAVA_HOME/jre/lib/security/cacerts keytool 无 -cacerts 参数,须显式写路径
Java 17 $JAVA_HOME/lib/security/cacerts 可直接用 -cacerts
Go 1.21 Linux 读 /etc/ssl/certs/ca-certificates.crt 可用 SSL_CERT_FILE 环境变量临时覆盖
Node 20 内置 Mozilla 根证书,不读系统库 必须设 NODE_EXTRA_CA_CERTS
Android 7+ 用户安装的 CA 默认不被 App 信任 需 network_security_config.xml 或 debug 包放行

步骤 2:建根 CA(只做一次,做完全部锁起来)

# -addext 需要 OpenSSL 1.1.1+;-days 3650 是根 CA 有效期,可长于叶证书
openssl req -x509 -newkey rsa:2048 -sha256 -days 3650 -nodes 
  -keyout test-ca.key -out test-ca.crt 
  -subj "/CN=Test Env Root CA/O=DevOps" 
  -addext "basicConstraints=critical,CA:TRUE" 
  -addext "keyUsage=critical,keyCertSign,cRLSign"

chmod 400 test-ca.key          # 私钥只读,属主为签发人
chmod 444 test-ca.crt

根 CA 私钥一旦泄露,任何拿到它的人都能伪造你测试环境的所有服务,所以它只该出现在跳板机或 Vault 里,绝不进 Git——.gitignore 里写 *.key 不如把签发脚本和 CA 目录物理分开。据 OpenSSL 官方 x509 手册,-CAcreateserial 会生成 .srl 序列号文件,这个文件要和 CA 一起保管,否则可能签发重复序列号。

步骤 3:签服务器证书,天数务必 ≤398

# 1) 生成私钥与 CSR
openssl req -new -newkey rsa:2048 -nodes 
  -keyout api.test.local.key -out api.test.local.csr 
  -subj "/CN=api.test.local"

# 2) 用根 CA 签发,扩展从 san.cnf 的 [v3_req] 读取
openssl x509 -req -in api.test.local.csr 
  -CA test-ca.crt -CAkey test-ca.key -CAcreateserial 
  -days 365 -sha256 
  -extfile san.cnf -extensions v3_req 
  -out api.test.local.crt

# 3) 立刻自检,确认 SAN 没丢
openssl x509 -in api.test.local.crt -noout -text | grep -A1 "Subject Alternative Name"

为什么强调 ≤398 天?CA/Browser Forum 的 SC-42 与 Apple 支持文档 HT211025 规定:2020-09-01 之后签发的 TLS 服务器证书有效期不得超过 398 天,Apple 平台对所有系统信任的证书(含私有 CA 签发)强制执行。私有 CA 在 Linux 上虽可绕过,但为了让同一张证书能装进 iOS/macOS 测试机,统一按 365 天签最省事。

步骤 4:拼 fullchain 并部署到 Nginx / Tomcat 9

# 服务器证书在前、根 CA 在后,顺序反了部分客户端会握手失败
cat api.test.local.crt test-ca.crt > fullchain.crt
chmod 600 api.test.local.key
chown nginx:nginx api.test.local.key
# /etc/nginx/conf.d/api.test.local.conf
server {
    listen 443 ssl;
    server_name api.test.local;
    ssl_certificate     /etc/nginx/ssl/fullchain.crt;
    ssl_certificate_key /etc/nginx/ssl/api.test.local.key;
    ssl_protocols       TLSv1.2 TLSv1.3;   # 对齐 Mozilla 服务器端 TLS 配置的 intermediate 档
}
# Tomcat 9:先转 PKCS12,再在 server.xml 的 SSLHostConfig 里引用
openssl pkcs12 -export -in fullchain.crt -inkey api.test.local.key 
  -name tomcat -out api.test.local.p12 -passout pass:changeit
# server.xml: <SSLHostConfig certificateKeystoreFile="/opt/tomcat/conf/api.test.local.p12"
#              certificateKeystorePassword="changeit" certificateKeystoreType="PKCS12" />

步骤 5:把根 CA 导入各端信任库

# Debian/Ubuntu:文件名必须以 .crt 结尾
sudo cp test-ca.crt /usr/local/share/ca-certificates/test-ca.crt
sudo update-ca-certificates
# RHEL/CentOS:换目录和命令
# sudo cp test-ca.crt /etc/pki/ca-trust/source/anchors/ && sudo update-ca-trust

# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain test-ca.crt

# Windows(管理员 CMD)
certutil -addstore -f Root test-ca.crt

# Java 9+/17:默认口令 changeit
sudo keytool -importcert -cacerts -alias test-ca -file test-ca.crt -storepass changeit -noprompt
# Java 8:sudo keytool -importcert -keystore $JAVA_HOME/jre/lib/security/cacerts -alias test-ca -file test-ca.crt

# Node 20:不改信任库,用环境变量注入
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/test-ca.crt

步骤 6:用 Let’s Encrypt 暂存环境演练,并把过期预警放进 CI

# certbot 2.x:--dry-run 会自动指向 staging,不会消耗正式速率限制
# 若单用 --staging 则会真实签发一张"不被信任"的暂存证书
certbot certonly --staging --dry-run -d api.test.local 
  --manual --preferred-challenges dns 
  --manual-auth-hook ./dns-hook.sh --manual-cleanup-hook ./dns-cleanup.sh

据 Let’s Encrypt 文档,暂存环境的签发速率限制远高于生产环境,但签出的证书由 Fake LE Root 签发,浏览器不信任——这正是它的用途:验证 ACME 账号注册、DNS-01 钩子和续期调度是否跑通,跑通后再切生产。

# 证书剩余有效期不足 14 天(1209600 秒)时返回非 0,可直接用于 CI 失败判定
openssl x509 -checkend 1209600 -noout -in /etc/nginx/ssl/fullchain.crt 
  || echo "ALERT: fullchain.crt 将在 14 天内过期"

把根 CA 证书、san.cnf 和上面整套签发脚本纳入版本管理(私钥除外),设 90 天轮换节奏,并在 CI 里每周跑一次 checkend:私有 CA 没有 ACME 自动续期,过期只能靠巡检兜住。

测试环境 SSL 证书的配置与命令示例(OpenSSL 3.0 + Nginx 1.24 + certbot 2.7)

先把结论摆出来:测试环境要跑通 TLS,真正容易踩坑的不是”生成证书”,而是 SAN 扩展写全、服务端协议版本对齐、客户端信任链注入这三件事。以下命令基于 OpenSSL 3.0、Nginx 1.24、certbot 2.7 实测,版本差异会在对应位置标注。

第一步:用 san.cnf 生成带完整扩展的 CSR

据 OpenSSL 3.0 文档,自 1.1.1 起 openssl req 不再默认读取 [v3_req],必须显式 -extensions,否则签出来的证书没有 SAN,Chrome 会直接报 NET::ERR_CERT_COMMON_NAME_INVALID。

# san.cnf —— 关键:extendedKeyUsage 缺失会导致部分 Java 客户端拒绝握手
[req]
distinguished_name = dn
req_extensions     = v3_req
prompt             = no

[dn]
CN = api.test.local

[v3_req]
basicConstraints     = CA:FALSE
keyUsage             = critical,digitalSignature,keyEncipherment
extendedKeyUsage     = serverAuth          # 漏掉此行,Java 8/11 默认校验 EKU 会抛 SSLHandshakeException
subjectAltName       = @alt_names

[alt_names]
DNS.1 = api.test.local
DNS.2 = *.test.local
IP.1  = 127.0.0.1
# 生成私钥与 CSR(OpenSSL 3.0)
openssl req -new -newkey rsa:2048 -nodes 
  -keyout api.test.local.key -out api.test.local.csr -config san.cnf

# 用私有 CA 签发,有效期 825 天(避开 iOS 对 >825 天的限制)
openssl x509 -req -in api.test.local.csr -CA test-ca.crt -CAkey test-ca.key 
  -CAcreateserial -days 825 -sha256 
  -extfile san.cnf -extensions v3_req -out api.test.local.crt

# 拼接 fullchain(Nginx 需要证书+中间/根链)
cat api.test.local.crt test-ca.crt > fullchain.crt

第二步:Nginx 1.24 的 server 段

server {
    listen 443 ssl;
    http2 on;                                  # 1.25.1 起替代 listen ... http2
    server_name api.test.local;

    ssl_certificate     /etc/nginx/certs/fullchain.crt;
    ssl_certificate_key /etc/nginx/certs/api.test.local.key;

    ssl_protocols       TLSv1.2 TLSv1.3;       # 测试环境也关掉 1.0/1.1,避免与线上行为不一致
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;             # 让客户端决定顺序,贴合现代 CDN 实践
    ssl_session_cache   shared:SSL:10m;        # 约 4 万会话,减少握手开销
    ssl_session_timeout 10m;
}

改完执行 nginx -t && nginx -s reload。ssl_ciphers 默认值 HIGH:!aNULL:!MD5 仍包含非前向保密套件,测试环境建议照上面收窄,与线上保持一致。

第三步:Let’s Encrypt 暂存环境演练

据 Let’s Encrypt 文档,暂存环境(staging)签发的是不受信任的假证书,但校验流程与生产完全一致,且有独立的速率限制——每账号每小时 30 次失败校验,正好用来压测续期脚本而不消耗生产配额(生产是每注册域名每周 50 张)。

# --dry-run 内部即走 staging,不会签发真实证书
certbot certonly --staging 
  --server https://acme-staging-v02.api.letsencrypt.org/directory 
  -d staging.example.com --dry-run

# 演练续期脚本(推荐放进 CI 定时任务)
certbot renew --dry-run --cert-name staging.example.com

生产配额一旦超限,报错是 too many certificates (5) already issued for this exact set of domains ... retry after 2024-05-01T08:00:00Z,在测试环境把脚本跑通再上生产能省掉数天的等待。

第四步:把私有 CA 注入各语言客户端

运行时 环境变量 / 命令 生效范围
Java 17 keytool -importcert -cacerts -storepass changeit -alias test-ca -file test-ca.crt -noprompt 全局 cacerts,影响所有 JVM
Java(临时) -Djavax.net.ssl.trustStore=/path/test-ca.jks -Djavax.net.ssl.trustStorePassword=changeit 单进程,调试首选
Node 20 export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/test-ca.crt 追加而非替换内置根
Go 1.21 export SSL_CERT_FILE=/etc/ssl/certs/test-ca.crt 完全替换根证书池
Python requests export REQUESTS_CA_BUNDLE=/etc/ssl/certs/test-ca.crt 仅 requests,urllib 不认

容器里更稳的做法是把 CA 挂进 /etc/ssl/certs/ca-certificates.crt(Debian/Ubuntu 镜像)后执行 update-ca-certificates,这样所有走系统证书池的库都自动生效。注意 Go 的 SSL_CERT_FILE 是替换语义,设错会让访问公网 HTTPS 全部失败,测试容器里建议只挂载合并后的 bundle。

第五步:两条命令确认到底通没通

# 应用层验证:应返回 HTTP/2 200
curl -vI https://api.test.local --cacert test-ca.crt

# 握手层验证:应输出 Verify return code: 0 (ok)
openssl s_client -connect api.test.local:443 
  -servername api.test.local -CAfile test-ca.crt -verify_return_error

若 s_client 返回 verify error:num=20:unable to get local issuer certificate,说明 fullchain.crt 少了根/中间证书;若 curl 报 SSL certificate problem: unable to get local issuer certificate 但 s_client 通过,通常是客户端没读到 --cacert 或环境变量未导出到当前 shell。把这两条命令写进 CI 的 smoke test,测试环境的 TLS 配置就能和线上保持同一套语义。

测试环境 SSL 证书五种方案怎么选?mkcert、自建 CA、Let's Encrypt 暂存环境对比

问:测试环境 SSL 证书到底有哪几种配法,我该选哪个?先看下面的选型表,再看每种方案的落地命令。核心判断标准只有两条:客户端能不能自动信任,以及证书生命周期能不能自动化。据 CA/Browser Forum Baseline Requirements,公共信任的 TLS 服务器证书有效期上限目前为 398 天,且 SC-081 已规划逐步缩短到 200/100/47 天,这一趋势直接决定了测试环境不该依赖手工续期。

方案 适用场景 证书有效期 客户端信任成本 关键限制
mkcert v1.4.4 本地开发机、单机调试 根 CA 10 年,叶子证书 2 年 3 个月 极低,mkcert -install 一条命令 每台机器一套根 CA,多人协作需同步 rootCA.pem 才能互信,不适合作为 CI 唯一证书来源
自建 OpenSSL 3.0 私有 CA 内网多服务、测试集群、CI 流水线 自定义,服务器证书建议 ≤398 天 中,需把根 CA 分发到各客户端信任库 可控性最好,可统一 SAN 规范与轮换节奏,是测试环境 SSL 证书的主流选择
Let’s Encrypt 暂存环境(acme-staging-v02) 演练 ACME 签发、续期、DNS-01 钩子 90 天,且证书不受任何客户端信任 零成本但无法消除告警 只用于验证流程,不能当作真正的测试环境 SSL 证书使用
公共免费 CA(ZeroSSL、Buypass)签发的 90 天证书 测试域名本身在公网可解析 90 天 低,系统信任库自带 需要公网 DNS 与 80/443 可达,内网 .local 域名无法使用,且会进入 CT 日志
Cloudflare Origin CA 测试环境挂在 Cloudflare 后面回源 可选 7 天到 15 年(默认 5475 天) 中,只有 Cloudflare 回源链路信任 浏览器直连会报不受信任,只适合纯回源场景;参数上优先选 90 天配合自动轮换

问:本地开发最省事的做法是什么?用 mkcert,它在首次运行时生成一套本地根 CA 并写入系统信任库(macOS Keychain、Windows 证书存储、Linux ca-certificates),NSS 库需额外执行一次 mkcert -install 才能覆盖 Firefox。

# mkcert v1.4.4(brew install mkcert / apt install mkcert)
mkcert -install                 # 生成根 CA 并注入系统信任库
mkcert -CAROOT                  # 查看根 CA 存放目录,Linux 默认 ~/.local/share/mkcert
mkcert "*.test.local" localhost 127.0.0.1 ::1
# 生成 _wildcard.test.local+3.pem / -key.pem,叶子证书有效期约 2 年 3 个月
# 协作时把 $(mkcert -CAROOT)/rootCA.pem 提交到私有仓库,团队成员执行 mkcert -install 后互信

问:多服务、CI 里怎么统一签发?自建私有 CA。按 RFC 5280,CA 证书必须带 basicConstraints=critical,CA:TRUE,而现代浏览器完全忽略 CN、只认 SAN,所以 subjectAltName 是必填项而非可选项。

# OpenSSL 3.0+,根 CA 有效期 10 年
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes 
  -keyout rootCA.key -out rootCA.pem -subj "/CN=Test Root CA/O=Dev" 
  -addext "basicConstraints=critical,CA:TRUE,pathlen:0" 
  -addext "keyUsage=critical,keyCertSign,cRLSign"

# server.ext:SAN 必填,私有 CA 不受 398 天强制约束,但建议对齐公共 CA 便于日后迁移
cat > server.ext <<'EOF'
basicConstraints=CA:FALSE
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth
subjectAltName=DNS:api.test.local,DNS:*.test.local,IP:10.0.0.10
EOF

openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr -subj "/CN=api.test.local"
openssl x509 -req -in server.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial 
  -days 397 -out server.crt -extfile server.ext -sha256

问:那 Let’s Encrypt 暂存环境是用来干什么的?只用来验证 ACME 流程。据 Let’s Encrypt 文档,暂存环境由 (STAGING) Pretend Pear X1 等伪根签发,证书永远不受信任,但速率限制远比生产宽松,适合跑通 DNS-01 钩子和续期定时任务;验证通过后去掉 --staging 即可切生产。

# certbot 2.x,--staging 等价于指定 acme-staging-v02 目录
certbot certonly --staging --manual --preferred-challenges dns 
  -d test.example.com --dry-run   # 先用 --dry-run 验证钩子,不产生真实订单

Cloudflare Origin CA 则通过 API 签发,requested_validity 可取 7/90/365/730/1095/5475 天,仅在 Cloudflare 回源链路中被信任,浏览器直连必然告警——它解决的是”源站到边缘”的加密,不是”用户到源站”的信任。综合来看,内网多服务选自建私有 CA 并把它作为 CI 的证书工厂,公网可解析的测试域名用 Let’s Encrypt 生产环境配合自动续期,ACME 流程改动前先在暂存环境跑一遍,本地单机调试交给 mkcert。

测试环境 SSL 证书常见报错与排查(含真实错误信息)

同一个 test-ca.crt,为什么 curl 通了、Java 服务还是抛 PKIX?因为每个运行时都有自己的信任库:测试环境 SSL 证书的根 CA 必须逐个装进去,装错一个就会报错。先按下面的对照表定位,再照抄对应命令。

真实报错信息 典型客户端 根因 修复入口
curl: (60) SSL certificate problem: self signed certificate curl / wget 客户端没有这张根 CA --cacert / CURL_CA_BUNDLE
NET::ERR_CERT_AUTHORITY_INVALID Chrome / Edge / Firefox 根 CA 未导入信任库 系统证书库;Firefox 走独立 NSS
ERR_CERT_COMMON_NAME_INVALID 浏览器 SAN 不含当前主机名或 IP 按 RFC 5280 重签 SAN
PKIX path building failed: unable to find valid certification path to requested target Java cacerts 缺根 CA keytool -importcert
x509: certificate signed by unknown authority Go 镜像里没有测试根 CA SSL_CERT_FILE
UNABLE_TO_VERIFY_LEAF_SIGNATURE / SELF_SIGNED_CERT_IN_CHAIN Node.js 同上 NODE_EXTRA_CA_CERTS
SSL_ERROR_BAD_CERT_DOMAIN / hostname mismatch 浏览器 / openssl 访问的域名与 SAN 不符 重签证书或改用 SAN 内的名字
verify error:num=20:unable to get local issuer certificate openssl s_client 服务端只下发了叶子证书 改用 fullchain.crt

curl 报 self signed certificate,是不是证书签错了?多数不是。先显式指定根 CA 验证一次,能通就证明证书链没问题,只是信任库没装:

# 只信任测试根 CA 做校验,排除证书本身的问题
curl -vI https://api.test.local --cacert test-ca.crt
# 确认无误后,用环境变量让当前 shell 内所有 curl 生效
export CURL_CA_BUNDLE=$PWD/test-ca.crt

浏览器 ERR_CERT_AUTHORITY_INVALID 呢?把 test-ca.crt 导入操作系统信任库(Linux 放 /usr/local/share/ca-certificates/ 后执行 update-ca-certificates,macOS 用「钥匙串访问」并设为「始终信任」)。注意 Firefox 使用独立的 NSS 库,不读系统库:可在 about:config 打开 security.enterprise_roots.enabled=true 复用系统根证书,或用 certutil -d sql:$HOME/.mozilla/firefox/<profile> -A -t "C,," -n test-ca -i test-ca.crt 单独导入。

ERR_CERT_COMMON_NAME_INVALID 一般是 SAN 写漏了。用 IP 访问却只签了 DNS、或签了 *.test.local 却访问 a.b.test.local(按 RFC 6125,通配符只匹配最左一级标签)都会触发。核对命令:

openssl x509 -in server.crt -noout -text | grep -A1 "Subject Alternative Name"

Java 的 PKIX path building failed 是 cacerts 里没有这张 CA。JDK 9+ 可直接用 -cacerts 参数(默认口令 changeit);JDK 8 需显式写 -keystore $JAVA_HOME/jre/lib/security/cacerts:

# 导入测试根 CA
keytool -importcert -cacerts -storepass changeit -alias test-ca -file test-ca.crt
# 确认写入成功,应看到 test-ca, ... trustedCertEntry
keytool -list -cacerts -storepass changeit | grep test-ca

Go 与 Node 的 unknown authority / SELF_SIGNED_CERT_IN_CHAIN 几乎都发生在容器里,因为精简基础镜像不带测试根 CA:

# Go:覆盖默认 CA 包路径(默认读 /etc/ssl/certs/ca-certificates.crt)
export SSL_CERT_FILE=/etc/ssl/certs/test-ca.crt
# Node:额外追加,而不是替换内置根证书列表
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/test-ca.crt
# 更彻底的做法,写进 Dockerfile
COPY test-ca.crt /usr/local/share/ca-certificates/test-ca.crt
RUN update-ca-certificates

openssl s_client 报 num=20 说明服务端证书链不全,Nginx 的 ssl_certificate 只配了叶子证书。按 Let’s Encrypt 与 Mozilla 配置生成器的通行做法,把中间/根证书追加到叶子证书之后,合并成 fullchain 再验证:

cat server.crt test-ca.crt > fullchain.crt
# nginx: ssl_certificate /etc/nginx/certs/fullchain.crt;
openssl s_client -connect api.test.local:443 -CAfile test-ca.crt </dev/null 2>&1 
  | grep -E "verify error|Verify return code"
# 期望输出:Verify return code: 0 (ok)

排查顺序建议固定为:先 openssl s_client 看服务端链是否完整,再逐个客户端验证信任库,最后才怀疑证书本身。这样能把「证书签错」和「CA 没装」两类问题一次分开。

怎么确认测试环境 SSL 证书配置生效?6 种可复现的验证方法

配好证书不等于配对了。怎么判断测试环境 SSL 证书真的生效?建议分三层看:信任链能否闭合、协议与套件是否合规、应用层是否真能跑通。下面 6 条命令可直接复制,按顺序跑一遍就能定位绝大多数问题(示例均以 api.test.local 与私有根 test-ca.crt 为例)。

  1. 握手能不能过?用 openssl s_client 只做一次完整握手,不发 HTTP 请求(OpenSSL 1.1.1+ 才支持 -tls1_3):
    # -verify_return_error:验证失败时返回非 0 退出码,便于脚本判断
    # -servername:显式发 SNI,避免虚拟主机返回默认证书
    openssl s_client -connect api.test.local:443 
      -servername api.test.local 
      -CAfile test-ca.crt 
      -verify_return_error -tls1_3 </dev/null
    # 重点看三行:Verify return code: 0 (ok) / Protocol  : TLSv1.3
    # 以及 Certificate chain 下的编号数量(0=叶子, 1=根,共 2 张)

    若链长度只有 1,说明服务端只下发了叶子证书,客户端拼不出完整路径;加 -showcerts 打印实际发送的证书即可确认。

  2. 证书内容对不对?
    # -ext 需 OpenSSL 1.1.1+;确认 issuer 为 CN=Test Env Root CA
    openssl x509 -in fullchain.crt -noout -subject -issuer -dates -ext subjectAltName

    逐项核对:issuer 必须是私有根;notAfter 距今小于 398 天(CA/Browser Forum 自 2020-09-01 起对公有证书的上限,私有 CA 虽不受限,但建议测试环境按 Let’s Encrypt 的 90 天节奏模拟,避免上线才暴露续期逻辑问题);SAN 需覆盖所有测试域名与 IP,仅写 CN 在 Chrome 中已不再生效。

  3. 还在用 TLS 1.0/1.1 吗?
    nmap -p 443 --script ssl-enum-ciphers api.test.local   # nmap 7.x
    ./testssl.sh --severity MEDIUM --fast https://api.test.local  # testssl.sh 3.0.8

    nmap 输出中不应再出现 TLSv1.0/TLSv1.1 段;testssl.sh 只显示 MEDIUM 及以上告警,理想结果是零条。

  4. 应用层通不通?
    curl -vI https://api.test.local --cacert test-ca.crt   # 期望 HTTP/2 200
    # 漏掉 --cacert 时典型报错:
    # curl: (60) SSL certificate problem: unable to get local issuer certificate

    浏览器打开开发者工具 → Security:Connection 应为 Secure、Certificate 为 valid、颁发者显示 Test Env Root CA。注意私有根需导入系统钥匙串,否则 Chrome 仍会拦截。

  5. Java 信任了吗?JVM 不读系统信任库,必须单独确认。
    # JDK 9+ 用冒号语法;JDK 8 写成 -Djavax.net.debug=ssl,handshake
    java -Djavax.net.debug=ssl:handshake -jar app.jar
    # 日志出现 "Found trusted certificate" 即表示测试环境 SSL 证书已被 JVM 接受

    默认信任库是 $JAVA_HOME/lib/security/cacerts(口令 changeit),用 keytool -importcert -alias test-root -file test-ca.crt -keystore truststore.jks 导入自建库后通过 -Djavax.net.ssl.trustStore 指定,可避免污染全局。

  6. 怎么让 CI 自动拦住问题?
    # 1) 业务可用性:非 2xx 或证书不合法即退出非 0,阻断发布
    curl --fail --silent --cacert /etc/ssl/certs/test-ca.crt 
      https://api.test.local/healthz
    # 2) 有效期:剩余不足 1209600 秒(14 天)时退出码为 1,触发告警
    openssl x509 -checkend 1209600 -noout -in fullchain.crt
验证手段 覆盖的问题 失败时的典型输出
openssl s_client 信任链、协议版本 Verify return code: 20 (unable to get local issuer certificate)
openssl x509 有效期、SAN、签发者 SAN 缺项 / Verify return code: 10 (certificate has expired)
nmap / testssl.sh 弱协议与弱套件 列出 TLSv1.0 段或 MEDIUM 告警
curl / 浏览器 端到端可用性 curl: (60) 或浏览器 NET::ERR_CERT_AUTHORITY_INVALID
JVM debug Java 信任库 PKIX path building failed ... unable to find valid certification path
CI 检查 回归与过期预防 curl 退出码非 0 / -checkend 返回 1

实践建议:前 3 条在证书签发后立即跑,第 4、5 条随部署跑,第 6 条常驻流水线。据 OpenSSL 官方文档,-checkend 的退出码语义是”证书将在指定秒数内过期则返回 1″,因此可直接用 if ! openssl x509 -checkend ...; then ...; fi 做分支判断,无需解析输出文本。

测试环境 SSL 证书的轮换、隔离与上线前检查清单

证书签发成功就等于配置完成了吗?远远不是。测试环境的 SSL 证书真正容易出问题的地方,是在”配好之后”——续期脚本常年不运行,一旦失效,测试环境就会先出问题;测试根 CA 混进生产镜像,信任范围随之扩大;上线时配置里还残留着测试证书路径,结果变成”测试通、线上挂”。这一节把轮换、隔离和上线前检查整理成可直接执行的步骤。

怎么让证书过期前自动告警?用 openssl x509 -checkend。它接受一个秒数参数(无默认值,必须显式给出),证书若在该时间窗内到期则返回非 0 退出码,非常适合交给 cron 判断。1209600 秒即 14 天:

# /etc/cron.d/cert-expiry-check
# 适用:OpenSSL 1.1.1+ / 3.x(Debian 11+、Ubuntu 20.04+、RHEL 8+ 自带)
# cron 需已安装并运行;mail 命令来自 mailx/bsd-mailx
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
# 每周一 09:00 检查:checkend 返回 0 表示 14 天内不会过期,非 0 触发告警
0 9 * * 1 root /usr/bin/openssl x509 -checkend 1209600 -noout 
  -in /etc/nginx/ssl/fullchain.crt || 
  echo "TLS cert on $(hostname) expires within 14 days" | 
  mail -s "[TEST-ENV] 证书即将过期" ops@example.com

注意这条命令的局限:文件不存在时 openssl 同样返回非 0,因此告警文案里要写清”即将过期或文件缺失”,否则容易误判。测试环境 SSL 证书也建议按 90 天节奏轮换——Let’s Encrypt 的默认证书有效期就是 90 天,只有让测试环境持续运行同一套 ACME 续期流程,才能提前发现 webroot 权限、80 端口被占、DNS-01 钩子失效等问题;如果测试证书一签就是三年,续期脚本等于从未被执行验证过。

测试根 CA 和生产根 CA 能不能共用一套?绝对不能。共用意味着测试私钥一旦泄露,生产信任链随之失守。区分方式很简单:Subject CN 直接写死在签发命令里,并用权限和存放位置把私钥隔离到离线介质:

# 生成测试专用根 CA(-addext 需要 OpenSSL 1.1.1+)
install -d -m 700 /opt/test-ca && cd /opt/test-ca
openssl req -x509 -newkey rsa:4096 -sha256 -days 1825 -nodes 
  -keyout test-ca.key -out test-ca.crt 
  -subj "/O=Example Corp/OU=QA/CN=Test Env Root CA" 
  -addext "basicConstraints=critical,CA:TRUE" 
  -addext "keyUsage=critical,keyCertSign,cRLSign"
chmod 400 test-ca.key && chown root:root test-ca.key   # 私钥 400,仅 root 可读
# 私钥放离线介质/密钥库,绝不 git add,也绝不 COPY 进任何基础镜像
维度 测试根 CA 生产根 CA
Subject CN CN=Test Env Root CA CN=Prod Root CA(或公有 CA 托管)
有效期 1–3 年,到期即重建 5–10 年,走变更流程
私钥权限与位置 400,root 所有,离线保存 400 + HSM/KMS,双人审批
分发方式 测试 Dockerfile 阶段或 entrypoint 注入 不进镜像,由公有信任库提供
是否进 CT 日志 否(RFC 6962 只约束公有 CA) 是

为什么不能把测试根 CA 写进公共基础镜像?因为 COPY test-ca.crt /usr/local/share/ca-certificates/ 这一行会随着镜像标签一起流向生产——所有基于该镜像的容器都会默认信任测试证书,攻击者只要拿到那张测试 CA 私钥(而它通常就放在某个人的笔记本上),就能对生产服务发起中间人攻击。正确做法是把注入限定在测试专用的构建阶段:

# 仅在 test 阶段注入,生产阶段 FROM base 时完全看不到该证书
FROM debian:12-slim AS base
# ... 应用依赖
FROM base AS test
COPY test-ca.crt /usr/local/share/ca-certificates/test-env-root-ca.crt
RUN update-ca-certificates          # 输出 1 added, 0 removed
FROM base AS prod                   # 生产阶段不含任何测试 CA

测试域名会不会泄露业务信息?会。据 Let’s Encrypt 文档与 RFC 6962,所有公有 CA 签发的证书都会提交到 Certificate Transparency 日志,且日志是公开可查、不可删除的。因此测试域名不要复用真实业务域名(如 test.你的品牌.com),否则子域名结构、内部服务命名会永久暴露在 crt.sh 之类的检索服务里。

域名方案 示例 是否写入 CT 适用场景
.local api.test.local 否 本地 mkcert / 私有 CA,最常用
.internal db.internal 否 内网服务互调
专用测试域 example-test.com 是 需要验证真实证书链、OCSP、HSTS
真实业务子域 test.品牌.com 是,且不可撤回 不建议使用

上线前该检查什么?至少跑完下面四条,任何一条输出异常都不要发布:

# 1) 生产配置中是否残留测试 CA 路径(应输出 OK)
grep -rn "test-ca|mkcert|rootCA.pem" /etc/nginx/ /etc/apache2/ 
  || echo "OK: 未引用测试 CA"

# 2) SAN 中是否含 .local 或内网 IP(应无输出)
openssl x509 -in /etc/nginx/ssl/fullchain.crt -noout -ext subjectAltName 
  | grep -E ".local|10.|192.168.|172.(1[6-9]|2[0-9]|3[01])."

# 3) 签发者是否为公网 CA(issuer 不应出现 Test Env Root CA)
openssl x509 -in /etc/nginx/ssl/fullchain.crt -noout -issuer

# 4) TLS 版本与测试环境保持一致,避免“测试通、线上挂”
openssl s_client -connect example.com:443 -tls1_2 /dev/null | grep Protocol

另外要确认 nginx 的 ssl_certificate 指向的是 fullchain.crt 而不是 cert.pem——只配叶子证书时,浏览器往往能靠 AIA 补链而正常,但 Android 和 Java 客户端会直接报 unable to find valid certification path,这正是”测试用 curl 通过、线上 App 打不开”的典型成因。TLS 版本与密码套件建议对照 Mozilla SSL Configuration Generator 的 Intermediate 档位逐项比对,确保测试与生产一致。

怎么让新人 15 分钟复现一套?在运维手册里固化三样东西:签发命令(含 -subj 完整字符串)、根 CA 指纹、轮换负责人。指纹用下面这条命令生成,写进文档后即可用于校验分发出去的 CA 是否被替换:

openssl x509 -in test-ca.crt -noout -fingerprint -sha256
# SHA256 Fingerprint=3A:F1:...:9C   ← 记录到手册,与各测试机 /usr/local/share/ca-certificates 中的副本比对

配套记录:分发方式(entrypoint 挂载还是镜像阶段注入)、轮换周期与触发条件、告警接收人。建议在手册中附一条自检命令 openssl verify -CAfile test-ca.crt server.crt,新人执行后看到 server.crt: OK 即说明链路完整——比口头交接可靠得多。

可以,但必须把签发它的根 CA 导入客户端信任库,否则 Chrome 会报 NET::ERR_CERT_AUTHORITY_INVALID。推荐用自建私有 CA 或 mkcert 签发,而不是直接用 openssl req -x509 生成一张“自签叶子证书”,因为后者无法被集中管理和轮换。导入根 CA 后,浏览器地址栏会显示正常的锁标识。

Let's Encrypt 签发的是公网可信证书,有效期 90 天,但要求域名公网可解析且 80/443 可达,内网 .local 域名用不了。测试环境 SSL 证书如果面向内网域名或 IP,选自建私有 CA 更合适;如果测试域名本身在公网,用 Let's Encrypt 可以顺带验证生产环境的 ACME 流程。两者也可以并存:内网服务用私有 CA,公网测试域名用 Let's Encrypt。

这个报错表示签发者不在信任库里。先执行 openssl s_client -connect host:443 -showcerts 导出链上的根证书,确认它是否已安装:Linux 用 update-ca-certificates,macOS 用 security add-trusted-cert,Windows 用 certutil -addstore -f Root。Firefox 使用独立的 NSS 信任库,需要在 about:config 里把 security.enterprise_roots.enabled 设为 true,或手动在设置中导入。

因为信任库是每个运行环境独立的。本地机器导入过测试根 CA,而 Jenkins 节点和容器镜像里没有。解决方式是在流水线里挂载根 CA 并设置环境变量:Go 用 SSL_CERT_FILE,Node 用 NODE_EXTRA_CA_CERTS,Python 用 REQUESTS_CA_BUNDLE,或在 Dockerfile 中 COPY test-ca.crt 到 /usr/local/share/ca-certificates/ 后执行 update-ca-certificates。

根 CA 可以设 3650 天,服务器证书建议 90 到 365 天,且不要超过 398 天,否则 iOS 13+ 和 macOS 10.15+ 会拒绝。实践中把测试环境 SSL 证书设成和线上一致的 90 天,能顺带把续期脚本、监控告警一起验证,避免上线后才发现自动化流程有问题。

mkcert v1.4.4 胜在快,mkcert -install && mkcert api.test.local 两条命令就能搞定本地开发,但每台机器默认生成独立根 CA。多人协作或需要 CI 统一签发时,用 OpenSSL 3.0 自建一套私有 CA、把根证书纳入配置管理更稳妥,mkcert 也可以用 -CAROOT 指向共享的 rootCA.pem 来复用同一套根。

只有公共 CA 签发的证书才会写入 Certificate Transparency 日志,自建私有 CA 签发的测试环境 SSL 证书不会。所以内网测试域名建议一律走私有 CA,既能避免子域名信息外泄,也省去 DNS-01 验证的配置成本。


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

内容审核

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