跳到主要内容
基础知识

API 服务 SSL 证书怎么配?从签发、部署到 mTLS 双向认证与自动轮换的实战指南

api服务ssl证书 — API 服务 SSL 证书怎么配?从签发、部署到 mTLS 双向认证与自动轮换的实战指南
核心结论

API 服务 SSL 证书就是绑定 API 域名的 TLS 证书:公网开放接口用 Let's Encrypt DV(0 元、90 天有效期、certbot 自动续期)即可满足 curl、Go、Java 与主流 SDK 的校验;集群内东西向调用应改用私有 CA(step-ca / Vault PKI)签发的 24 小时级短证书并开启 mTLS。 证书必须写 SAN:Go 1.15+、Java 8u181+、Chrome 58+ 不再回落到 CN,签发时用 -addext subjectAltName=DNS:api.example.com 明确写入,单张 Let's Encrypt 证书最多 100 个 SAN。 Nginx 1.24 的 ssl_certificate 只指向叶子证书会触发 curl (60) 与 Java PKIX path building failed,必须拼接 fullchain.pem(叶子+中间 CA),并用 openssl verify -CAfile root.crt -untrusted intermediate.crt api.crt 验证返回 OK。 CA/Browser Forum SC-081 把单张证书最长有效期压缩到 2026-03-15 的 200 天、2027-03-15 的 100 天、2029-03-15 的 47 天,API 服务 SSL 证书必须走 ACME 自动化 + deploy-hook 重载,人工续期不可持续。 一条命令验收到期时间:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | openssl x509 -noout -dates -ext subjectAltName,再配合 blackbox_exporter 0.25 的 probe_ssl_earliest_cert_expiry 设置 21 天告警。

API 服务 SSL 证书为什么总在联调时出问题?6 个高频根因

联调时最常听到的一句话是”证书装了,本地 curl 也通,为什么服务一调就崩?”——因为你验证的是自己的机器,而报错发生在对方的运行时。API 服务 SSL 证书的故障几乎都能归到下面 6 个根因,先看对照表,再逐条看命令。

根因 典型报错(原样复制) 一条验证命令
CN/SAN 错配 x509: certificate relies on legacy Common Name field openssl x509 -noout -ext subjectAltName -in cert.pem
证书链不完整 curl: (60) SSL certificate problem: unable to get local issuer certificate openssl s_client -connect host:443 -showcerts
续期后未重载 无报错,只是 notAfter 没变 echo | openssl s_client -connect host:443 2>/dev/null | openssl x509 -noout -dates
客户端信任库滞后 PKIX path building failed / 同上的 (60) keytool -list -keystore $JAVA_HOME/lib/security/cacerts
协议与套件不匹配 sslv3 alert handshake failure / unsupported protocol openssl s_client -tls1_1 -connect host:443
有效期持续缩短 无报错,是运维频率问题 见下方 SC-081 时间表

1. 域名与 SAN 错配。API 往往同时暴露公网域名 api.example.com 和集群内别名 api.svc.cluster.local,而证书若只写 CN=api.example.com、SAN 为空,Go 1.15+ 会直接返回 x509: certificate relies on legacy Common Name field;Java 8u181+ 与 Chrome 58+ 同样不再回落到 CN(据 RFC 6125 §6.4.4,CN 仅在无 SAN 时才被兼容处理)。签发时用 -addext "subjectAltName=DNS:api.example.com,DNS:api.svc.cluster.local" 一次写全。

2. 证书链不完整。Nginx 的 ssl_certificate 只指向叶子证书时,客户端拿不到中间 CA,就报 unable to get local issuer certificate。按 RFC 8446 §4.4.2 的握手流程,服务端应下发”叶子 + 中间”,根证书不要下发(客户端本就持有,多下反而增大握手包):

# /etc/nginx/conf.d/api.conf —— Nginx 1.19+ / OpenSSL 1.1.1+
ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;  # 关键:fullchain = 叶子 + 中间 CA
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols       TLSv1.2 TLSv1.3;   # Mozilla SSL Configuration Generator 5.7 的 intermediate 档默认值

3. 续期后进程未重载。据 Let’s Encrypt 文档,证书有效期 90 天,certbot 默认在剩余 30 天时续期;但文件更新后若没有 deploy hook 执行 reload,worker 进程内存里仍是旧证书,openssl s_client 看到的 notAfter 纹丝不动。补一行即可:

# /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh(chmod +x 后 certbot renew 会自动执行)
#!/bin/sh
systemctl reload nginx   # reload 而非 restart:平滑加载新证书,不断连接

4. 客户端信任库滞后。私有 CA 或企业内网 CA 签发的 API 服务 SSL 证书,必须显式导入 JVM 的 cacerts、容器的 /etc/ssl/certs 或 Go 的 RootCAs,否则照样报 unable to get local issuer certificate——这与证书本身对错无关。注意 JDK 自带的 cacerts 默认口令是 changeit,容器镜像重建后导入会丢失,应写进 Dockerfile。

5. 协议与套件不匹配。按 Mozilla 配置生成器只开 TLSv1.2/1.3 是正确做法,但部分老 SDK(Android 4.4、Java 6、Python 2.7 默认 ssl 模块)只支持 TLSv1.0,握手直接失败。不要为此回退全局协议,用独立 server 块或 SNI 分流给遗留客户端。

6. 有效期持续缩短。CA/Browser Forum 通过的 SC-081 规定:2026-03-15 起最长 200 天、2027-03-15 起 100 天、2029-03-15 起 47 天。接口数量一多,API 服务 SSL 证书若仍靠人工申请,一年要重复 4–8 次,出错概率随服务数线性上升——这就是自动化轮换(ACME + deploy hook + 监控 notAfter)从”最佳实践”变成”硬性前提”的原因。

给 API 服务申请和部署 SSL 证书的 6 个步骤

问:给 API 服务配 SSL 证书,最短路径是什么? 答:按下面 6 步走,每一步都给出可直接复制的命令。整体思路是”私钥在本地生成、证书由 CA 签、链要自检、参数要固定、到期要能被监控到”,这也是后文讲 mTLS 双向认证与自动轮换的基础。

步骤 1|用 OpenSSL 3.x 一次生成私钥与 CSR

据 OpenSSL 3.0 文档,-addext 允许在命令行直接写入 X.509 扩展,省掉手写 openssl.cnf 的麻烦。ECC P-256 是当前 API 场景的首选:握手更快、密钥更短,且 Let’s Encrypt 与主流公有 CA 均已默认签发 ECDSA 证书。

# OpenSSL 3.0+:SAN 在 CSR 阶段一次写全,事后无法追加,只能重签
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 
  -nodes -keyout api.key -out api.csr 
  -subj "/CN=api.example.com" 
  -addext "subjectAltName=DNS:api.example.com,DNS:api-v2.example.com"

# 自检:必须看到两条 DNS 记录,少一条就重来
openssl req -in api.csr -noout -text | grep -A1 "Subject Alternative Name"

仍需兼容 Java 6 或 Android 4.4 的老客户端时,改用 -newkey rsa:2048 -sha256(Java 6 不支持 SNI,也不认 ECDSA)。-nodes 表示私钥不加密存储,这是自动化签发的必要前提,安全性靠后面的 chmod 600 兜底。现代浏览器与 SDK 早已忽略 CN 字段,SAN 才是唯一被校验的域名列表——这是 RFC 6125 明确规定的。

步骤 2|选签发通道:公网走 ACME,东西向走私有 CA

签发通道 适用场景 证书有效期 前置条件
ACME HTTP-01(certbot) 公网单域名 API 90 天 80 端口公网可达
ACME DNS-01 泛域名 *.api.example.com、内网 API 90 天 DNS 服务商 API 凭据
私有 CA(step-ca 0.25+) 集群内东西向、服务间调用 建议 ≤24 小时 需向各服务分发 root_ca.crt
# 公网单域名:HTTP-01 验证,Let's Encrypt 文档要求 80 端口对外可达
certbot certonly --webroot -w /var/www/acme -d api.example.com

# 私有 CA:把有效期压到 24h 以内,配合短周期轮换降低私钥泄露窗口
step ca certificate api-client client.crt client.key --not-after 24h

需要说明的是,据 CA/Browser Forum 基线要求,公有证书最长有效期正逐步缩短(90 天 → 200 天 → 最终 47 天),因此”能自动续期”不是加分项而是必选项。私有 CA 走的是另一条逻辑:有效期越短越安全,但必须配套自动轮换。

步骤 3|拼链并校验,顺序错了客户端会报 unknown ca

# 叶子证书在前、中间证书在后;根证书不要拼进 fullchain
cat api.crt intermediate.crt > api.fullchain.pem

# 校验:必须输出 "api.crt: OK",否则链不完整或中间证书不匹配
openssl verify -CAfile root.crt -untrusted intermediate.crt api.crt

# 确认到期时间与 SAN 列表
openssl x509 -in api.fullchain.pem -noout -dates -ext subjectAltName

步骤 4|部署到入口并收紧文件权限

sudo install -o root -g root -m 600 api.key          /etc/nginx/ssl/api.key
sudo install -o root -g root -m 644 api.fullchain.pem /etc/nginx/ssl/api.fullchain.pem

# Kubernetes:更新用 apply 而非 create,避免 AlreadyExists
kubectl create secret tls api-tls --cert=api.fullchain.pem --key=api.key 
  -n prod --dry-run=client -o yaml | kubectl apply -f -

Ingress 中引用 secretName: api-tls。kubelet 同步 Secret 到 Pod 约需 1 分钟,Nginx Ingress Controller 检测到证书变化后热加载,无需 rollout restart;但若你把证书直接挂载进容器文件系统,则必须重启 Pod 才会生效——这是 api 服务 ssl 证书更新后仍显示旧证书的最常见原因。

步骤 5|固定 TLS 参数,别用默认值

# 参数取自 Mozilla SSL Configuration Generator 5.7 "intermediate" 档
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;   # 10MB 约缓存 40000 个会话
ssl_session_timeout 1d;
ssl_session_tickets off;            # 关闭 ticket,避免密钥轮换后旧会话无法撤销
add_header Strict-Transport-Security "max-age=31536000" always;  # 不加 includeSubDomains

步骤 6|接上续期与到期监控

# certbot 的 systemd timer 默认每天触发两次并带随机延迟,先确认它活着
systemctl list-timers certbot-renew.timer

# 续期后自动 reload,写进 renewal hook 而非 cron 里手写
certbot renew --deploy-hook "systemctl reload nginx"
# blackbox_exporter 0.25 抓取 probe_ssl_earliest_cert_expiry,Prometheus 告警
- alert: APICertExpiringSoon
  expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
  for: 1h
  annotations:
    summary: "{{ $labels.instance }} 证书剩余不足 21 天"

把阈值定在 21 天而非 7 天,是为了给 ACME 失败重试留出缓冲:Let’s Encrypt 建议在到期前 30 天开始续期,certbot 默认在剩余 30 天时动作,21 天告警意味着你已经错过了至少一周的自动续期窗口,值得人工介入排查 80 端口或 DNS 凭据。

API 服务 SSL 证书的配置示例:Nginx 1.24、Envoy 1.29 与客户端信任

Nginx 1.24 的最小可用配置怎么写?最容易踩的坑是 HTTP/2 指令:http2 on; 是 1.25.1 才引入的独立指令,在 1.24 上写它会直接启动失败并报 nginx: [emerg] unknown directive "http2",正确做法是把 http2 挂在 listen 后面。TLS 参数按 Mozilla SSL Configuration Generator 的 intermediate 档位收敛到 TLSv1.2/1.3 + AEAD 套件即可(据 Mozilla,ssl_prefer_server_ciphers off 在 TLS 1.3 下已是推荐值):

# /etc/nginx/conf.d/api.conf —— 适用 Nginx 1.24.x
server {
    listen 443 ssl http2;                 # 1.24 只能这样写;1.25.1+ 可改为 listen 443 ssl; + http2 on;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/ssl/api.fullchain.pem;  # 必须是「叶子证书 + 中间证书」全链
    ssl_certificate_key /etc/nginx/ssl/api.key;            # 权限 600,属主 root

    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    ssl_prefer_server_ciphers off;

    ssl_session_cache   shared:SSL:10m;   # 约 4 万个会话,默认 none
    ssl_session_timeout 1d;
    ssl_session_tickets off;              # 关掉 ticket,便于轮换密钥时真正失效旧会话

    add_header Strict-Transport-Security "max-age=31536000" always;

    location /v1/ {
        proxy_pass http://api_upstream;
        proxy_set_header Host $host;
    }
}

怎么确认证书和私钥是配对的?配错文件时 Nginx 会报 SSL_CTX_use_PrivateKey_file() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)。RSA 与 ECC 的校验方式不同,两行输出必须逐字节一致:

# RSA 证书:比对 modulus 指纹
openssl x509 -noout -modulus -in api.crt | openssl md5
openssl rsa  -noout -modulus -in api.key | openssl md5

# ECDSA 证书:没有 modulus,改比对公钥 SHA-256
openssl pkey -pubout -in api.key | openssl sha256
openssl x509 -pubkey -noout -in api.crt | openssl sha256

Envoy 1.29 开启 mTLS 要改哪几个字段?核心是 require_client_certificate: true(默认 false,不设就等于不校验客户端证书),以及 validation_context.trusted_ca 指向签发客户端证书的私有 CA:

# envoy.yaml —— Envoy 1.29,下游(入站)mTLS
filter_chains:
- transport_socket:
    name: envoy.transport_sockets.tls
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
      require_client_certificate: true          # 客户端不出证书 → 握手阶段即失败
      common_tls_context:
        tls_params:
          tls_minimum_protocol_version: TLSv1_2
        tls_certificates:
        - certificate_chain: { filename: /etc/envoy/api.fullchain.pem }
          private_key:       { filename: /etc/envoy/api.key }
        validation_context:
          trusted_ca: { filename: /etc/envoy/client-ca.pem }  # 校验客户端证书链

客户端如何信任私有 CA 并出示证书?Go 1.22 里 ServerName 不能省:用 IP 直连而证书只有 DNS SAN 时,会报 x509: cannot validate certificate for 10.0.0.12 because it doesn't contain any IP SANs(RFC 5280 规定 SAN 扩展优先于 CN)。

caPEM, _ := os.ReadFile("/etc/ssl/certs/api-ca.pem")
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caPEM)
clientCert, _ := tls.LoadX509KeyPair("client.crt", "client.key")

tr := &http.Transport{TLSClientConfig: &tls.Config{
    MinVersion:   tls.VersionTLS12,
    ServerName:   "api.example.com",           // 必填,否则 IP 直连校验失败
    RootCAs:      pool,                        // 私有 CA;公有 CA 留 nil 走系统根
    Certificates: []tls.Certificate{clientCert},
}}
c := &http.Client{Transport: tr, Timeout: 5 * time.Second}
curl --cacert api-ca.pem --cert client.crt --key client.key https://api.example.com/v1/health

# Python requests 2.32(底层 OpenSSL 3.x,默认安全级别 SECLEVEL=2,已拒绝 1024 位 RSA 证书)
r = requests.get("https://api.example.com/v1/health",
                 verify="/etc/ssl/certs/api-ca.pem",
                 cert=("client.crt", "client.key"), timeout=5)
客户端 信任私有 CA 出示客户端证书 典型报错
curl 8.x --cacert --cert + --key SSL certificate problem: unable to get local issuer certificate
requests 2.32 verify= cert=(crt,key) SSLError: certificate verify failed
Go 1.22 RootCAs Certificates x509: certificate signed by unknown authority

证书从哪来、多久续一次?Let’s Encrypt 证书有效期为 90 天(据 Let’s Encrypt 官方文档,续期建议在剩余 30 天内完成),两种主流 ACME 客户端命令如下,--deploy-hook / --reloadcmd 是让新证书真正生效的关键一步:

# certbot(≥2.0 支持 --key-type ecdsa)
certbot certonly --webroot -w /var/www/acme -d api.example.com 
  --key-type ecdsa --elliptic-curve secp256r1 
  --deploy-hook "systemctl reload nginx"

# acme.sh 3.0(默认 CA 为 ZeroSSL,可用 --server letsencrypt 切换)
acme.sh --issue -d api.example.com --webroot /var/www/acme --keylength ec-256 
  --reloadcmd "systemctl reload nginx"

注意 certbot 生成的 fullchain.pem 才可直接填 ssl_certificate;误填 cert.pem 会导致部分客户端报 unable to get local issuer certificate,这也是 api 服务 ssl 证书部署中最常见的「浏览器正常、SDK 报错」原因。

API 服务 SSL 证书怎么选?DV、OV、泛域名与私有 CA 对比表

选型时先把问题拆成三问:谁来验证你的身份、这张证书要覆盖多少个域名、私钥最终放在哪台机器上。答案不同,成本和运维方式差一个数量级。下表是 2025 年可直接落地的对比,价格取国内主流 CA 与云厂商的公开报价区间。

方案 2025 年国内参考价 单张最长有效期 典型场景 关键参数
Let’s Encrypt DV 0 元 90 天 公网 API 网关、SaaS 开放接口 ACME v2,50 张/注册域名/周
商业 DV 单域名 100–400 元/年 397 天(2026-03 后 200 天) 需要发票、SLA 与 OCSP 支持 ECC/RSA 双算法
OV 单域名 800–2500 元/年 397 天 对外合作的支付、数据类接口 需营业执照核验,1–3 工作日
OV 泛域名 3000–8000 元/年 397 天 多租户 *.api.example.com 通配只覆盖一级子域
私有 CA(step-ca / Vault PKI) 软件 0 元,人力成本为主 24 小时–7 天 集群内东西向 API、mTLS SPIFFE ID、自动轮换
自签证书 0 元 任意 本地联调、单元测试 浏览器与 SDK 默认不信任

泛域名到底能覆盖几层?这是上线当天最常见的翻车点。*.api.example.com 只匹配一级子域,payments.api.example.com 能过,v1.payments.api.example.com 不行。此时客户端会报 curl: (60) SSL: no alternative certificate subject name matches target host name 'v1.payments.api.example.com',依据是 RFC 6125 的通配符单层匹配规则。两条出路:把多级子域逐个写进 SAN,或按层级各签一张。注意 Let’s Encrypt 单张证书 SAN 上限为 100 个名字(据 Let’s Encrypt 官方 Rate Limits 文档),且泛域名只能走 DNS-01 验证:

# Certbot 2.0+:泛域名 + 多级子域混合 SAN,DNS-01 自动验证
certbot certonly --dns-cloudflare 
  --dns-cloudflare-credentials ~/.secrets/cf.ini   # API Token,仅需 Zone.DNS 编辑权限
  -d api.example.com 
  -d '*.api.example.com'                           # 只覆盖一级子域
  -d v1.payments.api.example.com                   # 二级子域必须显式列出
  --key-type ecdsa --elliptic-curve secp256r1      # 默认 rsa2048,显式切 ECDSA P-256
  --cert-name api-example --dry-run                 # 先 --dry-run,避免触发 5 张/周重复证书限额

算法选 ECDSA 还是 RSA?TLS 1.3 下 ECDSA P-256 的签名长度约 70 字节,RSA 2048 约 256 字节,握手包更小、CPU 验签更快,Mozilla 的 Server Side TLS 指南也把 ECDSA 列为现代配置首选。但 Java 6、Windows XP 的 SChannel 等老 TLS 栈没有 ECDSA 套件。折中做法是 Nginx 1.11.0 起支持的双证书写法,同一 server 块写两条 ssl_certificate,由服务端按客户端能力自动协商:

# nginx >= 1.11.0
server {
    listen 443 ssl;
    http2 on;                       # nginx 1.25.1+ 语法;旧版写 listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/ssl/api.ecdsa.fullchain.pem;  # 优先协商 ECDSA
    ssl_certificate_key /etc/nginx/ssl/api.ecdsa.key;
    ssl_certificate     /etc/nginx/ssl/api.rsa.fullchain.pem;    # 老客户端兜底
    ssl_certificate_key /etc/nginx/ssl/api.rsa.key;

    ssl_protocols       TLSv1.2 TLSv1.3;   # 1.23.4+ 的默认值,无需再放宽到 TLSv1.1
    ssl_prefer_server_ciphers off;         # 默认 off,交给客户端选,利于 TLS 1.3 与移动端
}

OV 值不值得多花两千块?OV 只比 DV 多一道营业执照核验(1–3 个工作日,泛域名 3–5 个工作日),浏览器地址栏并不区分显示。EV 早在 Chrome 77 就取消了绿色标识,为 EV 付溢价没有实际收益。真正决定 API 服务 SSL 证书可靠性的不是等级,而是自动化签发与到期监控——CA/Browser Forum 的 SC-081 已明确把最长有效期压到 2026-03-15 起 200 天、2027-03-15 起 100 天,靠人工续期迟早出事。预算应优先投在 ACME 客户端与告警上。

内网 API 能用公网 CA 吗?不能。.internal、.local、.svc 这类域名无法通过公共域名验证,而把公网 CA 私钥分发到几十个 Pod 里,等于把信任边界摊平。正确姿势是私有 CA 签发短命证书:step-ca 默认 leaf 有效期 24 小时,Vault PKI 角色默认 max_ttl 为 768 小时,都支持把 SPIFFE ID 写进 SAN,供 mTLS 侧做服务身份校验。公网入口单独用 DV 证书终止 TLS,两者互不干扰。

# step-ca:为集群内 API 签发 24 小时证书,SAN 里带 SPIFFE ID 供 mTLS 鉴权
step ca certificate "payments.api.svc" api.pem api.key 
  --ca-url https://ca.internal:9000 
  --root /etc/step/certs/root_ca.crt 
  --san "payments.api.svc" 
  --san "spiffe://example.com/ns/prod/sa/payments" 
  --not-after 24h    # step-ca 默认 24h;上限受 provisioner 的 maxTLSCertDuration 约束

API 服务 SSL 证书的 6 类真实报错与排查路径

API 服务出现 TLS 故障时有一个共性:浏览器能打开,并不代表你的客户端能连上。curl、Java、Go 各自维护信任库和主机名校验逻辑,所以排查时必须站在客户端视角复验,不能只在 Chrome 里点开锁图标。下面 6 类报错覆盖了绝大多数线上事故。

1. curl: (60) SSL certificate problem: unable to get local issuer certificate —— 链不全? 九成是服务端只下发了叶证书,没带中间证书。先数一下服务端实际下发的证书条数:

# 返回 1 说明只有叶证书(缺中间证书);返回 2~3 说明链正常
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -c "BEGIN CERTIFICATE"

# 修复:把中间证书拼进 fullchain.pem,顺序必须是"叶证书在前、中间证书在后"
cat api.crt intermediate.crt > fullchain.pem
nginx -t && nginx -s reload

据 Let’s Encrypt 文档,cert.pem 只含叶证书、chain.pem 只含中间证书,而 nginx 的 ssl_certificate 必须指向 fullchain.pem——这正是自签或手工拷贝证书时最容易漏的一步。

2. Java 侧 PKIX path building failed —— 信任库缺 CA? 报错全文为 javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target,含义是 JDK 的 cacerts 里没有签发链上的 CA。两种修法:

# 方案 A:导入全局信任库(cacerts 默认口令 changeit)
keytool -importcert -trustcacerts -alias api-ca -file ca.crt 
  -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit

# 方案 B:不动全局库,启动时指定独立信任库(推荐,便于灰度与回滚)
java -Djavax.net.ssl.trustStore=/opt/truststore.jks 
     -Djavax.net.ssl.trustStorePassword=changeit -jar app.jar

注意:JDK 9 起 keytool 默认生成 PKCS12,若目标库是 JKS 需显式加 -storetype JKS。

3. Go 侧两类 x509 报错,根因完全不同。 x509: certificate signed by unknown authority 是 Transport.TLSClientConfig.RootCAs 为 nil、回落到系统根库,私有 CA 未加载;x509: certificate is valid for api.internal, not api.example.com 是证书 SAN 不含实际访问域名(按 RFC 5280 与 RFC 6125,CN 早已不参与校验)。两者都不会因为”浏览器能打开”而消失。

# 核对 SAN 是否覆盖实际访问域名
openssl x509 -in api.crt -noout -text | grep -A1 "Subject Alternative Name"

4. nginx 启动失败 key values mismatch —— 私钥和证书不配对? 报错为 nginx: [emerg] SSL_CTX_use_PrivateKey(/etc/nginx/ssl/api.key) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch),常见于从旧服务器复制了证书却用了新生成的 key。比对方法:

# RSA 证书比对 modulus,两行 md5 必须一致
openssl x509 -noout -modulus -in api.crt | openssl md5
openssl rsa  -noout -modulus -in api.key | openssl md5
# ECDSA 证书改用公钥哈希比对
openssl x509 -in api.crt -noout -pubkey | openssl sha256
openssl pkey -in api.key -pubout     | openssl sha256

5. curl: (35) error:0A00010B:SSL routines::wrong version number —— 用 https 打了 http 端口? 要么客户端用 https:// 访问了 80 端口,要么反向代理已终止 TLS 却又用 https:// 回源到只监听明文 HTTP 的后端。

curl -v http://api.example.com:80 -o /dev/null    # 先确认端口实际协议

# nginx 回源协议前缀必须与后端监听方式一致
proxy_pass http://127.0.0.1:8080;   # 后端是明文 HTTP,不要写成 https://

6. mTLS 场景 400 Bad Request / No required SSL certificate was sent —— 客户端没带证书,还是 CA 配错? 先用 curl 手动复现,再核对 nginx 配置:

curl -v --cert client.crt --key client.key --cacert ca.crt https://api.example.com/ping
ssl_verify_client on;                              # 强制校验客户端证书
ssl_client_certificate /etc/nginx/ssl/ca.crt;      # 必须是签发客户端证书的那条 CA 链
ssl_verify_depth 2;                                # 默认 1;二级子 CA 签发时必须调到 2

把六类报错压缩成一张速查表,方便对号入座:

报错特征 根因 一条命令定位
curl: (60) unable to get local issuer certificate 服务端未下发中间证书 openssl s_client -showcerts 数 BEGIN 条数
Java PKIX path building failed cacerts 缺私有 CA keytool -list -keystore $JAVA_HOME/lib/security/cacerts
Go x509: unknown authority RootCAs 未加载私有 CA 检查 TLSClientConfig.RootCAs
Go x509: valid for X, not Y SAN 不含实际域名 openssl x509 -text | grep -A1 "Alternative Name"
nginx key values mismatch 证书与私钥不配对 比对 modulus / 公钥 sha256
curl: (35) wrong version number 协议与端口错配 curl -v http://host:80
mTLS: No required SSL certificate was sent 客户端未带证书或 CA 不一致 curl --cert --key --cacert

一个通用判断原则:任何”服务端看起来正常”的证书问题,都先用 openssl s_client -servername 拿到服务端真实下发的链,再用目标语言的最小客户端复验一次。OpenSSL 3.x 的 s_client 默认不再自动校验证书链,需显式加 -verify_return_error 才能复现 curl 的失败行为——这也是很多人”本地测没问题、上线就报错”的原因。

怎么验证 API 服务 SSL 证书已经生效?6 种可复现的检查方法

换完证书不等于已经生效。证书文件写进磁盘、Secret 更新完、CI 显示 green,都只能说明“材料到位”,不能说明“线上真的在用它”。下面 6 种方法分别从服务端、客户端、扫描器、监控四个视角交叉验证,全部可以复制执行。

1. 服务端实际下发的是哪张证书?

最直接的办法是绕过浏览器和任何中间层,直接问 443 端口要证书。注意 -servername 必须带,否则 SNI 缺失时 Nginx/Envoy 可能返回默认虚拟主机的证书,你会得出错误结论;</dev/null 是为了让 s_client 握手后立刻退出而不是等待标准输入(OpenSSL 1.1.1+ 行为)。

# 取叶子证书(-showcerts 会打印整条链,x509 默认只解析第一张)
openssl s_client -connect api.example.com:443 
  -servername api.example.com -showcerts /dev/null 
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName

# 典型输出
# subject=CN = api.example.com
# issuer=C = US, O = Let's Encrypt, CN = R11
# notBefore=Jun  1 00:00:00 2025 GMT
# notAfter=Aug 30 23:59:59 2025 GMT
# X509v3 Subject Alternative Name:
#     DNS:api.example.com, DNS:*.api.example.com

判断标准只有一条:notBefore/notAfter 是否与新证书一致。如果仍是旧日期,按这个顺序排查——K8s Secret 已更新但 Ingress Controller 没 watch 到、nginx -s reload 没执行(reload 才会重读证书,restart 才会重建进程)、或者负载均衡后面还有节点没滚动更新。逐节点确认可以用循环:

# 逐个后端 IP 验证,确认没有漏更新的节点
for ip in 10.0.1.11 10.0.1.12 10.0.1.13; do
  printf '%s -> ' "$ip"
  openssl s_client -connect "$ip:443" -servername api.example.com /dev/null 
    | openssl x509 -noout -enddate
done

# 顺带核对集群里存的证书本身
kubectl get secret api-tls -o jsonpath='{.data.tls.crt}' | base64 -d | openssl x509 -noout -enddate

2. 客户端实际协商到了哪个 TLS 版本和套件?

# 强制只允许 TLS 1.3,能连上才说明服务端真的支持 1.3(--tls-max 需要 curl 7.54+)
curl -vI --tlsv1.3 --tls-max 1.3 https://api.example.com/v1/health

正常输出里应同时出现 SSL certificate verify ok. 和 SSL connection using TLSv1.3 / TLS_AES_128_GCM_SHA256。返回 405/404 不影响结论,握手早已完成,只看 TLS 那几行。如果被降级到 TLSv1.2,先怀疑链路中间的设备做了 TLS 卸载(CDN、WAF、云 LB 的“灵活 SSL”模式),证书装在边缘而你查的是源站。据 RFC 8446(TLS 1.3),1.3 握手默认只提供前向保密套件,一旦降级就意味着你丢掉了这一层保障。

3. 有没有残留的 TLS 1.0/1.1、RC4、3DES?

# testssl.sh 3.2,只报 HIGH 及以上,只看协议部分
./testssl.sh --severity HIGH --protocols https://api.example.com

# 备选:nmap 无需额外安装依赖
nmap -p443 --script ssl-enum-ciphers api.example.com

期望看到 TLS 1.0 not offered、TLS 1.1 not offered,套件列表里没有 RC4、3DES、CBC 系列。RFC 8996 已将 TLS 1.0/1.1 标记为弃用,Mozilla SSL Configuration Generator 的 intermediate 配置默认也只启用 TLS 1.2+。

4. 怎么把“证书快过期”变成一条告警?

blackbox_exporter 0.25 的 https 探针会输出 probe_ssl_earliest_cert_expiry(Unix 时间戳),这是整条链中最早到期的证书,比只看叶子证书更稳妥——中间证书过期同样会让客户端报 unable to get local issuer certificate。

# blackbox.yml
modules:
  https_api:
    prober: http
    timeout: 5s
    http:
      valid_status_codes: [200]
      preferred_ip_protocol: ip4
      tls_config:
        ca_file: /etc/ssl/certs/api-ca.pem   # 私有 CA 场景必填;公有证书可省略
# Prometheus 告警规则:剩余不足 21 天触发
- alert: API证书即将过期
  expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
  for: 1h
  labels:
    severity: warning
  annotations:
    summary: "{{ $labels.instance }} 证书剩余 {{ $value | printf "%.1f" }} 天"

21 天这个阈值同时覆盖 90 天(Let’s Encrypt 默认)和 47 天(2025 年起逐步缩短的节奏)两种有效期,留够人工介入窗口。据 Let’s Encrypt 文档,其证书有效期与续期窗口会继续调整,所以不要把阈值写死成“剩余 30 天”。

5. 客户端代码里怎么看握手细节?

# Java:打印握手过程、证书链与 SNI(JDK 8+ 通用)
java -Djavax.net.debug=ssl:handshake -jar app.jar

# Go:1.15+ 用 VerifyConnection 回调,握手完成后打印叶子证书到期时间
# tr := &http.Transport{TLSClientConfig: &tls.Config{
#     VerifyConnection: func(cs tls.ConnectionState) error {
#         log.Printf("peer=%s notAfter=%s ver=%x",
#             cs.PeerCertificates[0].Subject.CommonName,
#             cs.PeerCertificates[0].NotAfter, cs.Version)
#         return nil   // 返回非 nil 即中断连接
#     },
# }}

# Node.js 20.x:加载私有 CA(启动时读取一次,运行中改环境变量无效)
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/api-ca.pem node server.js

这三种方式的价值在于区分“服务端问题”和“客户端信任库问题”。典型报错 curl: (60) SSL certificate problem: unable to get local issuer certificate 说明服务端没下发完整中间证书链,用方法 1 加上 -showcerts 就能看到链里只有一张。

6. 外部评级工具够不够用?

SSL Labs 能确认链完整性和协议配置,但它只能扫公网可达的域名,内网 API 根本扫不到。正确做法是在集群内跑一份 testssl.sh 或上面的 openssl 脚本,并把它接进 CI,每次证书变更自动执行一遍,失败即阻断发布。

方法 检查位置 能发现 盲区
openssl s_client 服务端实际下发 证书日期、SAN、链是否完整、SNI 路由是否正确 不验证客户端信任库
curl -v 客户端协商 TLS 版本、套件、验证是否通过 只覆盖单条链路
testssl.sh / nmap 协议与套件 弱协议、弱套件、前向保密缺失 内网需自建执行环境
blackbox_exporter 持续监控 整链最早到期时间、趋势告警 不覆盖配置错误
客户端调试日志 应用进程内 信任库缺失、SNI 未发送、链解析失败 需改代码或启动参数
SSL Labs 公网评级 链完整性、协议配置评分 内网不可达

实践上把这 6 项拆成两层:方法 1、2、3 在证书变更后手动或由 CI 跑一次,做发布门禁;方法 4 常驻 Prometheus,负责发现“过期”这类时间维度的问题。两者缺一不可——监控能告诉你 20 天后会出事,但只有主动探测能告诉你今天的证书压根没换上去。

先分清两件事:服务端证书证明”你是 api.example.com”,客户端证书证明”调用方是谁”。后者受 RFC 5280 §4.2.1.12 约束——证书一旦带 extendedKeyUsage 扩展,就只能用于其中列出的用途。所以签发客户端证书时 EKU 必须是 clientAuth;错写成 serverAuth,Nginx 会直接拒掉,日志里是 client SSL certificate verify error: (26:unsupported certificate purpose)(OpenSSL 的 X509_V_ERR_INVALID_PURPOSE)。

用 step-ca 0.25 签发最省事,短有效期一条命令搞定:

# step-ca 0.25.x;--not-after 24h 让证书第二天自动过期,配合轮换脚本
# 首次使用需先 step ca bootstrap --ca-url https://ca.internal --fingerprint <fp>
step ca certificate api-client client.crt client.key 
  --ca-url https://ca.internal 
  --root root_ca.crt 
  --not-after 24h 
  --san api-client.internal

没有 step-ca 就用 openssl 手工签,关键在 -extfile:

# 1) 生成私钥与 CSR(CN 只是标识,真正的身份建议放 SAN)
openssl req -new -newkey rsa:2048 -nodes -keyout client.key -out client.csr 
  -subj "/CN=api-client.internal"

# 2) 用内部 CA 签 1 天;EKU 必须为 clientAuth,进程替换需 bash/zsh
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 1 
  -extfile <(printf "extendedKeyUsage=clientAuthnkeyUsage=digitalSignaturensubjectAltName=DNS:api-client.internal")

# 3) 自查 EKU,输出应为 TLS Web Client Authentication
openssl x509 -in client.crt -noout -text | grep -A1 "Extended Key Usage"

部署侧两套主流网关的配置语义对照如下,注意默认值——很多”配了不生效”都是默认值在作祟:

能力 Nginx 1.25+ Envoy 1.29
强制双向校验 ssl_verify_client on(默认 off) require_client_certificate: true(默认 false)
信任锚 ssl_client_certificate(客户端 CA,非服务端证书) validation_context.trusted_ca
链深限制 ssl_verify_depth,默认 1 max_verify_depth
按路径放宽 ssl_verify_client optional + if ($ssl_client_verify != SUCCESS) optional + RBAC/XFCC 判断
吊销列表 ssl_crl crl.filename
# /etc/nginx/conf.d/api.conf
server {
    listen 443 ssl;
    ssl_certificate     /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    ssl_client_certificate /etc/nginx/ssl/client-ca.pem;  # 客户端 CA 链
    ssl_verify_client optional;   # 默认 off;on 则全站强制
    ssl_verify_depth 2;           # 默认 1,中间 CA 多一层会报 unable to get issuer certificate
    ssl_crl /etc/nginx/ssl/client-ca.crl;
    ssl_session_timeout 10m;      # 默认 5m;若曾调到 1d 务必降回,缩短会话复用窗口

    location /v1/orders {
        if ($ssl_client_verify != SUCCESS) { return 403; }  # optional 模式下的兜底
        proxy_pass http://orders_upstream;
    }
}
# Envoy:强制全体下游出示客户端证书
transport_socket:
  name: envoy.transport_sockets.tls
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext
    require_client_certificate: true      # 默认 false
    common_tls_context:
      tls_certificates:
        - certificate_chain: { filename: /etc/envoy/server.crt }
          private_key:       { filename: /etc/envoy/server.key }
      validation_context:
        trusted_ca: { filename: /etc/envoy/client-ca.pem }
        max_verify_depth: 2

只对部分路由强制时,把 require_client_certificate 设为 false,改用 HTTP filter 读身份。Envoy 会把证书摘要写进 XFCC 头(受 forward_client_cert_details 控制),也可以用 RBAC 的 authenticated 直接匹配 SAN 里的 SPIFFE ID,比解析 XFCC 更稳。

验证必须两种结果都出现才算配好,只测成功路径等于没测:

# 预期 200
curl -sv --cert client.crt --key client.key --cacert ca.crt 
  https://api.example.com/v1/orders

# 去掉 --cert,Nginx 预期 400 "No required SSL certificate was sent"
# Envoy 预期 400/403;若仍返回 200,说明校验根本没生效
curl -sv --cacert ca.crt https://api.example.com/v1/orders

最后是时效与吊销。客户端证书的有效期建议压到 24 小时以内,把”吊销”问题转成”过期”问题;ssl_session_timeout 若停留在 1d,TLS 会话复用会让客户端跳过完整握手,吊销检查形同虚设,降到 10m 能显著收窄这个窗口。CRL 用 ssl_crl 指定后需随 CA 定期重生成并 nginx -s reload。至于 OCSP stapling——据 Let’s Encrypt 官方公告,其 OCSP responder 已于 2025 年 5 月停止服务,新签发证书不再内嵌 OCSP URL,吊销状态统一转向 CRL;因此配置 ssl_stapling on 前,先确认你的 api 服务 SSL 证书签发方是否仍提供 OCSP 响应,否则只会拿到 ssl_stapling ignored, issuer certificate not found 一类的无效配置。这也反过来解释了为什么内部 API 服务的 mTLS 方案里,短有效期 + CRL 比 OCSP 更现实。

API 服务 SSL 证书的自动续期、轮换与成本清单

自动续期最容易出问题的地方不是”能不能续”,而是”续了但没生效”。先把两件事分开监控:证书文件是否更新、服务进程是否加载了新证书。据 Let’s Encrypt 文档,同一注册域名每周签发上限 50 张、重复证书每周 5 张,压测时务必切到 staging 端点,否则几轮 CI 就能把配额打满。

certbot 侧:先确认 timer 真的在跑

# 1. 确认自动续期定时器已启用(由 certbot 包安装时自动创建)
systemctl list-timers | grep certbot
# 期望输出包含:certbot-renew.timer  ...  n/a  n/a  certbot-renew.service

# 2. 检查续期配置与钩子,renew 会读取 /etc/letsencrypt/renewal/*.conf
sudo certbot renew --dry-run --quiet 
  --deploy-hook "systemctl reload nginx"   # 仅在真正续期成功时执行,不续期不触发

# 3. 生产环境实际执行(staging 测试时加 --server 参数)
sudo certbot renew --quiet --deploy-hook "systemctl reload nginx" 
  --server https://acme-staging-v02.api.letsencrypt.org/directory

# 4. 排查失败原因,所有 ACME 交互与钩子输出都写在这里
sudo tail -n 100 /var/log/letsencrypt/letsencrypt.log

--deploy-hook 与已废弃的 --renew-hook 行为不同:前者只在证书确实更新后执行,后者每次 renew 都执行。reload 失败必须单独告警,否则会出现”文件是新的、进程还在用旧的”这种静默故障。

Kubernetes 侧:cert-manager 1.15 的声明式续期

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: api-gateway-tls
  namespace: prod
spec:
  secretName: api-gateway-tls
  duration: 2160h      # 90 天,默认值即为 2160h
  renewBefore: 720h    # 提前 30 天续期,约占有效期 1/3
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - api.example.com

配合 Ingress 注解 cert-manager.io/cluster-issuer: letsencrypt-prod 即可全自动。Secret 更新后,ingress-nginx 等控制器会监听并热加载;自建 Nginx 不会,需挂 nginx-reloader 或 sidecar 轮询 Secret 哈希。

轮换如何做到不停机

Nginx 里最稳的做法是新旧证书并行:先在同一 server 块追加新证书路径并 reload,确认 openssl s_client -connect api.example.com:443 -servername api.example.com | openssl x509 -noout -dates 显示新有效期,再摘掉旧证书二次 reload。K8s 下用灰度:

kubectl rollout restart deployment/api-gateway -n prod
kubectl rollout status deployment/api-gateway -n prod --timeout=300s
# 观察 5 分钟内 5xx 比例与 TLS 握手失败数不上升,再全量

按 47 天有效期重新设计节奏

据 CA/Browser Forum 基线要求,2029-03-15 之后单张证书最长 47 天,续期窗口仅约 15 天,人工介入不再可行。建议把 renewBefore 设为 15 天以上,并同时告警”剩余 < 21 天”与”reload 失败”两个独立指标。

方案 证书费用 签发周期 适用场景
Let’s Encrypt DV 0 元 约 30 分钟上线 绝大多数 API 服务,支持自动轮换
商业 DV 100–400 元/年 当天 需要商业支持或更长兼容链
商业 OV 800–2500 元/年 1–3 个工作日 对公合作方要求组织校验
私有 CA(如 step-ca) 0 元,半天搭建 即时 内网 mTLS、服务间双向认证

监控告警配置约 1 小时,是整份清单里性价比最高的一项:21 天到期阈值 + reload 失败告警,能挡住绝大多数 API 服务 SSL 证书过期事故。

对绝大多数公网 API 够用:Let's Encrypt 是受信任的公共 CA,DV 证书 90 天有效期、支持 ECC 与多 SAN,curl、Go、Java、Python requests 都认。只有当合作方合同要求 OV 组织信息、需要发票与 SLA,或需要 OCSP 响应时,才升级到 800–2500 元/年的 OV 证书。

证书本身同属 X.509 公钥证书,差别在用法:API 场景通常没有浏览器,校验方是 SDK 与网关,所以更依赖 SAN 写全、链完整、客户端信任库正确;另外 API 常需要 mTLS 双向认证与 24 小时级短有效期轮换,而普通网站几乎不用客户端证书。

临时联调可以,长期运维不建议。自签证书没有吊销机制、无法批量轮换、每个客户端都要手工导入;私有 CA(step-ca 0.25 或 Vault PKI)可以统一签发 24 小时证书、自动轮换、支持 CRL 与 mTLS,搭建成本约半天,之后证书费用为 0。

先确认服务端下发的链有几张:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts /dev/null | grep -c BEGIN,返回 1 就是缺中间证书。把中间 CA 拼到叶子证书后面生成 fullchain.pem,Nginx 的 ssl_certificate 指向它并 reload,再复测即可。

Let's Encrypt 的 certbot 默认在剩余 30 天时续期,这是 90 天有效期的安全窗口;2027-03-15 之后最长 100 天、2029-03-15 之后 47 天,续期阈值要相应下调到 15 天以内并保证全自动。监控侧统一用 21 天告警最省心。

不能。*.example.com 只匹配一级子域,api.v2.example.com 是两级,不在通配范围内。要么单独为 v2.example.com 签 *.v2.example.com,要么在 SAN 列表里显式写 api.v2.example.com,Let's Encrypt 单张证书最多 100 个 SAN。

技术上可行,RFC 8738 定义了 IP 地址证书,SAN 里写 IP:10.0.0.12。但 Let's Encrypt 不为 IP 签发,公网 IP 只能走商业 CA,内网 IP 更适合用私有 CA。更常见的做法是给每个服务一个内部域名,避免 IP 变更导致证书重签。


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

内容审核

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