Homelab 证书管理实战:从私有 CA 到自动签发
基于 step-ca、cert-manager 与 Vault PKI 的内网证书实践
前言:为什么要自建证书管理系统
Homelab 里的服务一多,证书就会散落在 Nginx 配置、Kubernetes Secret、容器挂载目录和几台虚拟机上。公网证书有 Let’s Encrypt 和 Cloudflare 兜底,内网服务却没那么省心:用自签证书,浏览器和命令行工具到处报警告;把公网 CA 签发的证书用在 *.homelab.internal 上,又签不出来。
这篇文章记录我在 Homelab 里搭起来的一套证书管理链路:
- step-ca 作为内网私有 CA,提供 ACME 接口和
stepCLI; - cert-manager 在 Kubernetes 里申请、续期证书,并把结果写进 Secret;
- Prometheus 采集证书过期时间、续期时间和就绪状态;
- Vault PKI 作为需要审计和统一策略时的备选方案,这次也实际跑通了;
- Cloudflare 继续负责公网域名,文中作为对比方案说明。
文中的实测部分运行在一台 Debian 12 + k3s 的虚拟机上,版本是 step-ca 0.30.2、step CLI 0.31.0、cert-manager 1.21.3、Vault 2.2.2。Vault PKI 已经在同一台 VM 上接入 cert-manager 并签发证书,Prometheus/Alertmanager 告警链路和 step-ca、Vault 的吊销流程也做了实测;Cloudflare API 只做方案说明,SPIFFE/SPIRE 和 cert-manager CSI Driver 属于后续方向,本文不展开。
架构设计:证书管理全景图
先看整体结构。CA 层负责签发,cert-manager 负责把签发流程接到 Kubernetes,消费层是 Ingress、Pod 和虚拟机,监控层采集证书状态。
graph TB
subgraph CA["CA 层"]
StepCA["step-ca<br/>私有 CA"]
Vault["Vault PKI<br/>可选"]
CF["Cloudflare<br/>公网证书"]
end
subgraph Issue["签发层"]
CM["cert-manager"]
ACME["ACME / HTTP-01"]
end
subgraph Use["消费层"]
Traefik["Traefik"]
Ing["Ingress"]
Pod["Pod"]
VM["虚拟机 / 裸机服务"]
end
subgraph Monitor["监控层"]
Prom["Prometheus"]
Grafana["Grafana"]
AM["Alertmanager"]
end
StepCA -->|ACME| CM
Vault -->|Vault Issuer| CM
CF -->|Origin CA| Traefik
Traefik --> Ing
CM -->|Secret| Ing
CM -->|Secret / CSI| Pod
StepCA -->|step CLI| VM
CM -->|metrics| Prom
Prom --> Grafana
Prom --> AM
style StepCA fill:#4f46e5,color:#fff
style CM fill:#326ce5,color:#fff
style Vault fill:#000,color:#fff
三种方案怎么选
| 方案 | 适合的场景 | 优点 | 限制 |
|---|---|---|---|
| step-ca | 内网服务、开发环境、Kubernetes | 单二进制部署,支持 ACME,短期证书 | 需要把 Root CA 分发到客户端 |
| Vault PKI | 需要审计、动态凭证、统一策略 | 权限模型和审计链路完整 | 部署和运维成本高 |
| Cloudflare | 公网暴露的服务 | 边缘证书自动管理,Origin CA 有效期长 | 只覆盖 Cloudflare 代理的流量 |
我的选择是 step-ca 做内网 CA,cert-manager 做 Kubernetes 侧的自动化。Vault 负责更敏感的服务,Cloudflare 继续管公网域名。三套方案不冲突,按域名和消费端拆分即可。
网络拓扑
graph LR
U["用户"] --> CF["Cloudflare"]
CF -->|Full Strict| Traefik["Traefik<br/>Origin Certificate"]
Traefik --> K8s["k3s / Kubernetes<br/>step-ca certificates"]
K8s --> DB[("PostgreSQL<br/>可选 Vault 证书")]
CA["step-ca<br/>ca.homelab.internal:8443"] --> K8s
style CF fill:#f38020,color:#fff
style Traefik fill:#24a1c1,color:#fff
style K8s fill:#326ce5,color:#fff
style CA fill:#4f46e5,color:#fff
实验环境里没有独立的内网 DNS,ca.homelab.internal 和测试域名通过 CoreDNS 的 homelab.internal server block 解析到实验室 VM。生产环境应该把这些记录放进自己的 DNS,而不是长期靠改 CoreDNS。
方案一:step-ca 私有 CA
step-ca 是 Smallstep 开源的 CA 服务端,单个二进制就能跑,支持 ACME、JWK、OIDC 等 provisioner,适合 Homelab 这种规模。
为什么选 step-ca
我主要看中这几点:
- 部署轻,不需要数据库集群,BadgerDB 落地即可;
- cert-manager 可以直接走 ACME,不需要定制 Issuer;
- 默认证书有效期短,泄露后的影响窗口小;
stepCLI 能覆盖初始化、签发、检查和客户端信任配置。
准备工作
创建目录和专用用户。下面的命令在 Debian 12 上执行,CA 监听 8443。
sudo useradd -r -s /bin/false step
sudo mkdir -p /opt/step-ca/{config,secrets,db,certs}
sudo chown -R step:step /opt/step-ca
# 生成 CA 私钥的加密口令,step-ca 启动时会读这个文件
sudo -u step sh -c 'openssl rand -base64 24 > /opt/step-ca/secrets/password.txt'
sudo chmod 600 /opt/step-ca/secrets/password.txt
export STEPPATH=/opt/step-ca
export CA_NAME="Homelab Root CA"
export CA_ADDRESS=":8443"
export CA_PROVISIONER="[email protected]"
CA_PROVISIONER 是第一个 JWK provisioner 的名字。后面用 step ca token 或 step ca certificate 手动签发时会用到它。
安装 step 和 step-ca
本文使用的版本是 step CLI 0.31.0、step-ca 0.30.2。下载地址和压缩包内的目录结构如下:
cd /tmp
curl -sLO https://github.com/smallstep/cli/releases/download/v0.31.0/step_linux_amd64.tar.gz
tar xzf step_linux_amd64.tar.gz
sudo install -m 755 step_linux_amd64/bin/step /usr/local/bin/step
curl -sLO https://github.com/smallstep/certificates/releases/download/v0.30.2/step-ca_linux_amd64.tar.gz
tar xzf step-ca_linux_amd64.tar.gz
sudo install -m 755 step-ca_linux_amd64/step-ca /usr/local/bin/step-ca
step version
step-ca version
step-ca 的压缩包里是 step-ca_linux_amd64/step-ca,不是直接在根目录。有些教程里的 mv step-ca /usr/local/bin/ 会找不到文件。
初始化 CA
初始化时直接把 ACME provisioner 一起创建出来。step-ca 0.30 的 step ca init 支持 --acme,比先启动 CA、再调用 admin API 添加 provisioner 省事。
cd /opt/step-ca
sudo -u step env STEPPATH=/opt/step-ca step ca init \
--name="$CA_NAME" \
--dns=ca.homelab.internal \
--dns=ca.plz.ac \
--dns=10.31.0.141 \
--address="$CA_ADDRESS" \
--provisioner="$CA_PROVISIONER" \
--acme \
--deployment-type=standalone \
--password-file=/opt/step-ca/secrets/password.txt
--dns 可以重复多次;不要写成逗号分隔的一整串,step-ca 不会帮你拆开。--deployment-type=standalone 表示不连接 Smallstep 的云服务,密钥完全本地管理。10.31.0.141 是实验环境 CA 的地址,实际部署时换成你的 CA IP,或者只在客户端通过域名访问时省略这个 SAN。
初始化完成后,目录结构是:
/opt/step-ca/
├── certs/
│ ├── root_ca.crt
│ └── intermediate_ca.crt
├── config/
│ ├── ca.json
│ └── defaults.json
├── db/
├── secrets/
│ ├── password.txt
│ ├── root_ca_key
│ └── intermediate_ca_key
└── ...
Root CA 证书在 certs/,私钥在 secrets/。有些示例把 root_ca.crt 写在 secrets/ 下,和 0.30 的实际布局不一致。
调整证书有效期
ca.json 里的 authority.claims 控制默认有效期。下面只列出需要修改的字段,不要整段覆盖原文件。为了让后面的续期测试能在几分钟内观察到,我把默认值改成了 10 分钟:
{
"authority": {
"claims": {
"minTLSCertDuration": "5m",
"maxTLSCertDuration": "2160h",
"defaultTLSCertDuration": "10m",
"disableRenewal": false,
"allowRenewalAfterExpiry": true
},
"provisioners": [
{
"type": "ACME",
"name": "acme",
"claims": {
"minTLSCertDuration": "5m",
"maxTLSCertDuration": "2160h",
"defaultTLSCertDuration": "10m"
}
}
]
}
}
生产环境可以把 defaultTLSCertDuration 设为 24h 或 720h。ACME 客户端不能在订单里指定有效期,最终有效期由 CA 的 provisioner 配置决定;cert-manager 的 duration 字段在 ACME Issuer 下不会改变这个值。provisioners 数组里要保留初始化时生成的 JWK provisioner,只给 ACME 这一项加 claims。
修改后重启 CA,用 step ca provisioner list 可以看到 ACME provisioner 和 claims:
sudo systemctl restart step-ca
sudo step ca provisioner list \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt
systemd 服务
把 CA 作为 systemd 服务运行,直接用专用用户 step,并限制它能写的目录:
# /etc/systemd/system/step-ca.service
[Unit]
Description=step-ca Certificate Authority
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=step
Group=step
Environment=STEPPATH=/opt/step-ca
ExecStart=/usr/local/bin/step-ca /opt/step-ca/config/ca.json --password-file=/opt/step-ca/secrets/password.txt
Restart=on-failure
RestartSec=10
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/step-ca/db
[Install]
WantedBy=multi-user.target
ProtectSystem=strict 会把大部分文件系统挂成只读,所以 ReadWritePaths 至少要包含 db。如果后面启用了其他会写文件的特性,要把对应目录加进去,否则 CA 会在启动或签发时因为权限失败。
启动并检查:
sudo systemctl daemon-reload
sudo systemctl enable --now step-ca
sudo systemctl status step-ca --lines=0 --no-pager
sudo step ca health \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt
step ca health 返回 ok 就说明 CA 的 HTTPS 和 ACME 端点已经起来了。下图是实际运行状态和 provisioner 列表:

ACME 端点
step-ca 的 ACME directory 路径是 /acme/{provisioner}/directory。本文的 provisioner 名字是 acme,所以地址是:
https://ca.homelab.internal:8443/acme/acme/directory
可以直接验证:
sudo curl -s --cacert /opt/step-ca/certs/root_ca.crt \
https://ca.homelab.internal:8443/acme/acme/directory | jq
输出包含 newNonce、newAccount、newOrder、revokeCert、keyChange。cert-manager 的 ACME Issuer 会先访问 newNonce 和 newAccount,然后创建订单。
客户端信任 Root CA
私有 CA 绕不开的一步:把 Root CA 装进客户端信任库。Linux 下:
# 用指纹校验后再写入,避免从网络直接信任一个未知证书
step ca root root_ca.crt \
--ca-url=https://ca.homelab.internal:8443 \
--fingerprint <root-ca-fingerprint>
sudo cp root_ca.crt /usr/local/share/ca-certificates/homelab-ca.crt
sudo update-ca-certificates
# 验证
curl https://ca.homelab.internal:8443/health
macOS:
sudo security add-trusted-cert -d -r trustRoot \
-k /Library/Keychains/System.keychain root_ca.crt
Windows(管理员 PowerShell):
Import-Certificate -FilePath "C:\temp\root_ca.crt" `
-CertStoreLocation Cert:\LocalMachine\Root
容器镜像里没有系统信任库时,可以把 Root CA 复制进镜像:
FROM alpine:3.22
COPY root_ca.crt /usr/local/share/ca-certificates/homelab-ca.crt
RUN update-ca-certificates
或者在 Kubernetes 里用 ConfigMap 挂载,再用 SSL_CERT_FILE 指向它。不要在每个应用里重复写一套信任逻辑,能统一就统一。
容器化部署(可选)
如果不想在宿主机装二进制,官方镜像也可以直接跑。下面这份 compose 文件和 systemd 版本等价,适合把 CA 放到独立的 Docker 主机上:
services:
step-ca:
image: smallstep/step-ca:0.30.2
container_name: step-ca
restart: unless-stopped
ports:
- "8443:8443"
volumes:
- ./step:/home/step
environment:
- DOCKER_STEPCA_INIT_NAME=Homelab Root CA
- DOCKER_STEPCA_INIT_DNS_NAMES=ca.homelab.internal,ca.plz.ac
- DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true
- DOCKER_STEPCA_INIT_ACME=true
healthcheck:
test: ["CMD", "step", "ca", "health"]
interval: 30s
timeout: 10s
retries: 3
这部分没有在本次实验里单独跑;镜像的初始化参数在不同版本间有变化,使用前先看对应版本的 README。
方案二:cert-manager 自动化签发
cert-manager 负责三件事:根据 Certificate 或 Ingress 注解创建 CertificateRequest,向 ACME 服务申请证书,把结果写进 Secret 并在到期前续期。
安装 cert-manager
本文使用 cert-manager v1.21.3。新版 Helm chart 用 crds.enabled 安装 CRD,旧的 installCRDs 已经不再推荐。
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.21.3 \
--set crds.enabled=true \
--set prometheus.enabled=true
kubectl get pods -n cert-manager
kubectl wait --for=condition=Ready pods --all -n cert-manager --timeout=120s
prometheus.enabled=true 会给 cert-manager 的 Pod 加上 prometheus.io/scrape、prometheus.io/port 注解,同时暴露 9402 端口的 metrics。
配置 step-ca Issuer
先把 Root CA 转成 base64,写进 ClusterIssuer 的 caBundle。这一步不能省,否则 cert-manager 访问 https://ca.homelab.internal:8443 时会报 x509: certificate signed by unknown authority。
CA_B64=$(sudo base64 -w0 /opt/step-ca/certs/root_ca.crt)
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: step-ca-issuer
spec:
acme:
server: https://ca.homelab.internal:8443/acme/acme/directory
email: [email protected]
privateKeySecretRef:
name: step-ca-account-key
caBundle: ${CA_B64}
solvers:
- http01:
ingress:
ingressClassName: traefik
EOF
这里用 ingressClassName: traefik 指定 HTTP-01 solver 创建的 Ingress 由 Traefik 接管。早期示例里常见的是 class: traefik;新版本用 ingressClassName 更明确。
检查 Issuer 状态:
kubectl get clusterissuer step-ca-issuer
kubectl describe clusterissuer step-ca-issuer
READY=True 且消息是 The ACME account was registered with the ACME server,说明 cert-manager 已经用 caBundle 验证了 step-ca 的 TLS,并完成 ACME 账户注册。
申请证书
先创建一个测试命名空间和 Certificate:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: test-cert
namespace: cert-test
spec:
secretName: test-tls
commonName: test.apps.homelab.internal
dnsNames:
- test.apps.homelab.internal
renewBefore: 5m
issuerRef:
name: step-ca-issuer
kind: ClusterIssuer
把上面的 YAML 保存为 test-cert.yaml,然后应用:
kubectl create namespace cert-test
kubectl apply -f test-cert.yaml
kubectl wait --for=condition=Ready certificate/test-cert -n cert-test --timeout=120s
kubectl get certificate -n cert-test
在本次实验里,从创建 Certificate 到 Ready=True 大约用了 20 秒。cert-manager 会创建一个 Order 和 HTTP-01 Challenge,step-ca 通过 Traefik 访问 http://test.apps.homelab.internal/.well-known/acme-challenge/...,验证通过后签发证书。

关于 wildcard 和 duration
一个常见的错误示例是直接申请 *.apps.homelab.internal,同时又用 HTTP-01 solver。这个组合跑不通:ACME 的 HTTP-01 只能验证具体主机名,wildcard 必须用 DNS-01。要签 wildcard,需要给 cert-manager 配一个 DNS-01 solver,例如 RFC2136、Cloudflare DNS 或 webhook。
另一个容易踩的点是 duration。ACME 协议里没有“请求有效期”这个字段,证书有效期由 CA 的 provisioner 决定。cert-manager 的 duration 在 ACME Issuer 下不会改变 step-ca 的签发结果。如果把 renewBefore 设得比实际有效期还长,cert-manager 会不停地续期。我的做法是:先看 step-ca 的 defaultTLSCertDuration,再把 renewBefore 设成它的一半左右。
通过 Ingress 注解自动申请
更常见的用法是让 cert-manager 监听 Ingress 的 tls 配置,自动创建 Certificate:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: myapp
namespace: cert-test
annotations:
cert-manager.io/cluster-issuer: step-ca-issuer
spec:
ingressClassName: traefik
tls:
- hosts:
- myapp.apps.homelab.internal
secretName: tls-myapp
rules:
- host: myapp.apps.homelab.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: myapp
port:
number: 80
Ingress 创建后,cert-manager 会生成名为 tls-myapp 的 Certificate 和对应的 Secret。Traefik 从 Secret 读取证书,HTTPS 请求就能正常完成握手。Ingress 自动生成的证书通常只有 SAN,没有 Common Name,这是 cert-manager 的正常行为。
检查证书内容
kubectl get certificate -n cert-test test-cert -o wide
kubectl describe certificate -n cert-test test-cert
kubectl get secret -n cert-test test-tls -o jsonpath='{.data.tls\.crt}' \
| base64 -d \
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
实际输出包含:
subject=CN = test.apps.homelab.internal
issuer=O = Homelab Root CA, CN = Homelab Root CA Intermediate CA
X509v3 Subject Alternative Name:
DNS:test.apps.homelab.internal

证书链是“叶子证书 → step-ca Intermediate CA → Homelab Root CA”。客户端只要信任 Root CA,就能验证整条链。
方案三:Vault PKI
Vault 的 PKI Secrets Engine 更适合需要审计、动态凭证和统一策略的环境。这一次我在同一台实验 VM 上把 Vault PKI 链路完整跑通了:Vault 2.2.2 使用 file backend,Vault 自己的 HTTPS 证书由 step-ca 签发,cert-manager 通过 Kubernetes auth 使用 Vault Issuer 签发证书。
部署 Vault
Vault 的 HTTPS 证书先用 step-ca 签发,域名是 vault.homelab.internal:
sudo useradd -r -s /bin/false vault
sudo mkdir -p /opt/vault/{data,tls}
PROV=$(sudo step ca provisioner list \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
| jq -r '.[] | select(.type=="JWK") | .name')
sudo STEPPATH=/opt/step-ca step ca certificate vault.homelab.internal \
/opt/vault/tls/vault.crt /opt/vault/tls/vault.key \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
--provisioner="$PROV" \
--provisioner-password-file=/opt/step-ca/secrets/password.txt \
--password-file=/opt/step-ca/secrets/password.txt \
--not-after=720h
# 证书和私钥交给 vault 用户,Root CA 复制到 Vault 可读的位置
sudo chown -R vault:vault /opt/vault
sudo chmod 600 /opt/vault/tls/vault.key
sudo cp /opt/step-ca/certs/root_ca.crt /opt/vault/tls/root_ca.crt
sudo chmod 644 /opt/vault/tls/root_ca.crt
实验环境为了省事用了 disable_mlock = true;生产环境应启用 mlock 并关闭 swap,避免私钥被换出到磁盘。Vault 配置使用 file storage,并监听 8200:
# /etc/vault.d/vault.hcl
ui = true
disable_mlock = true
api_addr = "https://vault.homelab.internal:8200"
cluster_addr = "https://vault.homelab.internal:8201"
storage "file" {
path = "/opt/vault/data"
}
listener "tcp" {
address = "0.0.0.0:8200"
tls_cert_file = "/opt/vault/tls/vault.crt"
tls_key_file = "/opt/vault/tls/vault.key"
}
systemd 服务把 Vault 跑在专用用户下:
[Unit]
Description=HashiCorp Vault
After=network-online.target
Wants=network-online.target
[Service]
User=vault
Group=vault
ExecStart=/usr/local/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGINT
Restart=on-failure
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
初始化时为了实验方便使用 1 个 share、阈值 1;生产环境不要这么配:
export VAULT_ADDR=https://vault.homelab.internal:8200
export VAULT_CACERT=/opt/vault/tls/root_ca.crt
vault operator init -key-shares=1 -key-threshold=1 -format=json \
| sudo tee /opt/vault/init.json >/dev/null
UNSEAL=$(sudo jq -r '.unseal_keys_b64[0]' /opt/vault/init.json)
ROOT=$(sudo jq -r '.root_token' /opt/vault/init.json)
vault operator unseal "$UNSEAL"
vault login "$ROOT"
vault status
vault status 显示 Initialized true、Sealed false,服务就算起来了:

启用 PKI 和 Intermediate CA
vault secrets enable pki
vault secrets tune -max-lease-ttl=87600h pki
vault write -field=certificate pki/root/generate/internal \
common_name="Homelab Vault Root CA" \
issuer_name="homelab-root" \
ttl=87600h > vault_root_ca.crt
vault write pki/config/urls \
issuing_certificates="https://vault.homelab.internal:8200/v1/pki/ca" \
crl_distribution_points="https://vault.homelab.internal:8200/v1/pki/crl"
vault secrets enable -path=pki_int pki
vault secrets tune -max-lease-ttl=43800h pki_int
vault write -format=json pki_int/intermediate/generate/internal \
common_name="Homelab Vault Intermediate CA" \
issuer_name="homelab-intermediate" \
| jq -r '.data.csr' > pki_intermediate.csr
vault write -format=json pki/root/sign-intermediate \
issuer_ref="homelab-root" \
csr=@pki_intermediate.csr \
format=pem_bundle \
ttl="43800h" \
| jq -r '.data.certificate' > intermediate.cert.pem
vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem
创建角色和策略
vault write pki_int/roles/homelab-internal \
allowed_domains="homelab.internal,svc.cluster.local" \
allow_subdomains=true \
allow_bare_domains=true \
max_ttl="720h" \
generate_lease=true \
no_store=false
vault policy write cert-manager-policy - <<'EOF'
path "pki_int/sign/homelab-internal" {
capabilities = ["create", "update"]
}
path "pki_int/issue/homelab-internal" {
capabilities = ["create"]
}
EOF
no_store=false 让 Vault 保存签发记录,后面可以用 vault list pki_int/certs 查序列号。
Kubernetes 认证
Vault 跑在集群外,auth/kubernetes/config 需要 token reviewer 的 JWT 和 Kubernetes CA。先创建一个只用于 token review 的 ServiceAccount:
apiVersion: v1
kind: Namespace
metadata:
name: vault
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: vault-auth
namespace: vault
---
apiVersion: v1
kind: Secret
metadata:
name: vault-auth-token
namespace: vault
annotations:
kubernetes.io/service-account.name: vault-auth
type: kubernetes.io/service-account-token
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: vault-auth-delegator
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: system:auth-delegator
subjects:
- kind: ServiceAccount
name: vault-auth
namespace: vault
TOKEN=$(kubectl -n vault get secret vault-auth-token -o jsonpath='{.data.token}' | base64 -d)
CA=$(kubectl -n vault get secret vault-auth-token -o jsonpath='{.data.ca\.crt}' | base64 -d)
vault auth enable kubernetes
vault write auth/kubernetes/config \
kubernetes_host="https://10.31.0.141:6443" \
token_reviewer_jwt="$TOKEN" \
kubernetes_ca_cert="$CA"
vault write auth/kubernetes/role/cert-manager \
bound_service_account_names=cert-manager \
bound_service_account_namespaces=cert-manager \
policies=cert-manager-policy \
ttl=1h
kubernetes_host 用 k3s API 的地址,不要写 https://kubernetes.default.svc,因为 Vault 不在 Pod 里。
cert-manager Vault Issuer
cert-manager 原生支持 Vault Issuer,不需要额外插件。认证方式用 serviceAccountRef,让 cert-manager 用自己 Pod 里的 ServiceAccount token 去换 Vault token:
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: vault-issuer
spec:
vault:
server: https://vault.homelab.internal:8200
path: pki_int/sign/homelab-internal
caBundle: <base64-step-ca-root>
auth:
kubernetes:
role: cert-manager
mountPath: /v1/auth/kubernetes
serviceAccountRef:
name: cert-manager
这里的 caBundle 是 Vault HTTPS 证书的信任根,也就是 step-ca 的 Root CA,不是 Vault PKI 的 Root CA。两个 CA 在这一套里是分开的:step-ca 保护 Vault 的 API,Vault PKI 负责签发业务证书。
cert-manager 的 ServiceAccount 还需要 create serviceaccounts/token 权限,否则 Issuer 会报:
serviceaccounts "cert-manager" is forbidden:
User "system:serviceaccount:cert-manager:cert-manager"
cannot create resource "serviceaccounts/token"
补一个 Role 和 RoleBinding:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: cert-manager-token-creator
namespace: cert-manager
rules:
- apiGroups: [""]
resources: ["serviceaccounts/token"]
verbs: ["create"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: cert-manager-token-creator
namespace: cert-manager
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: cert-manager-token-creator
subjects:
- kind: ServiceAccount
name: cert-manager
namespace: cert-manager
之后 Issuer 变成 Ready=True,消息是 Vault verified:

用 Vault PKI 签发证书
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: vault-test
namespace: cert-test
spec:
secretName: vault-test-tls
commonName: vault-test.apps.homelab.internal
dnsNames:
- vault-test.apps.homelab.internal
duration: 24h
issuerRef:
name: vault-issuer
kind: ClusterIssuer
把上面的 YAML 保存为 vault-test.yaml,然后应用:
kubectl apply -f vault-test.yaml
kubectl wait --for=condition=Ready certificate/vault-test -n cert-test --timeout=120s
kubectl get certificate -n cert-test vault-test -o wide
实际结果是证书由 Homelab Vault Intermediate CA 签发,有效期 24 小时,SAN 正确:
subject=CN = vault-test.apps.homelab.internal
issuer=CN = Homelab Vault Intermediate CA
notBefore=Nov 13 17:25:51 2026 GMT
notAfter=Nov 14 17:26:21 2026 GMT
X509v3 Subject Alternative Name:
DNS:vault-test.apps.homelab.internal

证书链是“叶子证书 → Homelab Vault Intermediate CA → Homelab Vault Root CA”。Vault 的 pki_int/certs 里也能查到这次签发的序列号,说明 no_store=false 和 generate_lease=true 都生效了:
vault list pki_int/certs
Keys
----
1f:2a:b8:9a:9b:68:ae:70:ff:31:66:ea:75:09:84:2e:24:e3:05:b9
证书监控与告警
证书签发只是开始。真正容易出事的是“证书过期了但没人知道”,所以监控要覆盖三件事:什么时候过期、什么时候续期、续期失败时能不能发现。
cert-manager 指标
cert-manager 在 9402 端口暴露 Prometheus 指标。开启 prometheus.enabled=true 后,可以直接抓取这些指标:
| 指标 | 含义 |
|---|---|
certmanager_certificate_expiration_timestamp_seconds |
证书过期时间戳 |
certmanager_certificate_ready_status |
证书是否就绪,condition="True" 且值为 1 表示正常 |
certmanager_certificate_renewal_timestamp_seconds |
计划续期时间戳 |
certmanager_controller_sync_call_count |
控制器同步调用计数 |
如果集群里装了 Prometheus Operator,用 ServiceMonitor 最省事:
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: cert-manager
namespace: cert-manager
spec:
selector:
matchLabels:
app.kubernetes.io/name: cert-manager
app.kubernetes.io/component: controller
endpoints:
- port: http-metrics
interval: 30s
没有 Prometheus Operator 时,可以在 Prometheus 的 scrape config 里直接抓 cert-manager.cert-manager.svc:9402,或者用 Pod 注解做服务发现。用注解方式时,relabel 要把 __address__ 改成 PodIP:9402,只写 keep 规则是不够的。

告警规则
下面几条规则覆盖“即将过期”“已经过期”“未就绪”和“控制器消失”:
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
name: cert-manager-alerts
namespace: monitoring
spec:
groups:
- name: cert-manager
rules:
- alert: CertificateExpiringSoon
expr: |
(certmanager_certificate_expiration_timestamp_seconds - time()) < 7 * 24 * 3600
and
(certmanager_certificate_expiration_timestamp_seconds - time()) > 0
for: 1h
labels:
severity: warning
annotations:
summary: "Certificate {{ $labels.name }} expires in 7 days"
description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} will expire soon."
- alert: CertificateExpiringCritical
expr: |
(certmanager_certificate_expiration_timestamp_seconds - time()) < 24 * 3600
and
(certmanager_certificate_expiration_timestamp_seconds - time()) > 0
for: 10m
labels:
severity: critical
annotations:
summary: "Certificate {{ $labels.name }} expires in 24 hours"
description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} needs immediate attention."
- alert: CertificateExpired
expr: |
certmanager_certificate_expiration_timestamp_seconds - time() < 0
for: 5m
labels:
severity: critical
annotations:
summary: "Certificate {{ $labels.name }} has expired"
description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} is past its expiry time."
- alert: CertificateNotReady
expr: |
certmanager_certificate_ready_status{condition="True"} == 0
for: 15m
labels:
severity: warning
annotations:
summary: "Certificate {{ $labels.name }} is not ready"
description: "Certificate {{ $labels.name }} in {{ $labels.namespace }} has been not ready for 15 minutes."
- alert: CertManagerAbsent
expr: |
absent(up{job="cert-manager"} == 1)
for: 10m
labels:
severity: critical
annotations:
summary: "cert-manager is down"
description: "cert-manager has been unavailable for more than 10 minutes."
CertManagerAbsent 里的 job 标签取决于你的抓取配置,用 ServiceMonitor 时通常不是字面上的 cert-manager。部署前先查一下 up{job=~".*cert-manager.*"} 的实际标签。
告警链路实测
只看规则文本不够,我在实验环境里用最小化的 Prometheus 3.16.0 和 Alertmanager 0.35.0 跑了一遍,确认指标能从 cert-manager 抓取,规则能进入 firing,Alertmanager 能收到告警。实验里没有装完整的 kube-prometheus-stack,只用两个最小 Deployment 加 ConfigMap 验证链路;生产环境直接用 Prometheus Operator 的 ServiceMonitor 和 PrometheusRule 即可。
Prometheus 的抓取配置直接指向 cert-manager 的 Service:
scrape_configs:
- job_name: cert-manager
static_configs:
- targets: ["cert-manager.cert-manager.svc:9402"]
规则文件里先用一条 CertificateNotReady,for 缩短到 30 秒方便观察:
groups:
- name: cert-manager
rules:
- alert: CertificateNotReady
expr: certmanager_certificate_ready_status{condition="True"} == 0
for: 30s
labels:
severity: warning
annotations:
summary: "Certificate {{ $labels.name }} is not ready"
然后创建一个引用不存在 Issuer 的 Certificate,让它保持 Ready=False:
kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: alert-test
namespace: cert-test
spec:
secretName: alert-test-tls
commonName: alert-test.apps.homelab.internal
dnsNames:
- alert-test.apps.homelab.internal
issuerRef:
name: does-not-exist
kind: ClusterIssuer
EOF
大约一轮抓取加 30 秒之后,Prometheus 和 Alertmanager 都能看到这条告警:
kubectl get certificate -n cert-test alert-test
curl -s localhost:9090/api/v1/alerts | jq -r '.data.alerts[] | [.labels.alertname, .state, .labels.name] | @tsv'
curl -s localhost:9093/api/v2/alerts | jq -r '.[] | [.labels.alertname, .status.state, .labels.name] | @tsv'
实际输出是 CertificateNotReady firing alert-test 和 CertificateNotReady active alert-test:

实验里的 Alertmanager 只配置了空 receiver,所以这里用 API 验证链路。生产环境把 receiver 换成 Slack、邮件或 webhook,并保留 for: 15m 之类的持续时间,避免瞬时抖动触发告警。
外部证书:blackbox-exporter
不在 Kubernetes 里的服务,可以用 blackbox-exporter 的 TLS probe 检查:
modules:
tls_connect:
prober: tcp
timeout: 5s
tcp:
tls: true
tls_config:
insecure_skip_verify: false
Prometheus 抓取配置:
scrape_configs:
- job_name: blackbox-tls
metrics_path: /probe
params:
module: [tls_connect]
static_configs:
- targets:
- ca.homelab.internal:8443
- vault.homelab.internal:8200
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: instance
- target_label: __address__
replacement: blackbox-exporter:9115
对应的告警:
- alert: TLSCertExpiringSoon
expr: |
probe_ssl_earliest_cert_expiry - time() < 7 * 24 * 3600
for: 1h
labels:
severity: warning
annotations:
summary: "TLS certificate for {{ $labels.instance }} expires soon"
Cloudflare 证书
如果域名托管在 Cloudflare,证书分两层:
- Edge Certificate:Cloudflare 到访客,Universal SSL 自动管理,通常不需要手工续期;
- Origin Certificate:Cloudflare 到源站,最长 15 年,适合放在 Traefik 或 Nginx 上。
用 API 查看边缘证书包和 Origin CA 证书:
export CF_API_TOKEN="..."
export CF_ZONE_ID="..."
curl -s "https://api.cloudflare.com/client/v4/zones/${CF_ZONE_ID}/ssl/certificate_packs" \
-H "Authorization: Bearer ${CF_API_TOKEN}" \
| jq '.result[] | {id, type, status, hosts, expires_on: .certificates[0].expires_on}'
curl -s "https://api.cloudflare.com/client/v4/certificates?zone_id=${CF_ZONE_ID}" \
-H "Authorization: Bearer ${CF_API_TOKEN}" \
| jq '.result[] | {id, hostnames, expires_on, request_type}'
这部分没有在实验环境里调用真实 API。Cloudflare 的 API token 权限和返回字段会随产品调整,脚本上线前先用一个只读 token 验证。
实践验证:端到端测试
实验环境
| 项目 | 配置 |
|---|---|
| 操作系统 | Debian 12 (bookworm) |
| 虚拟化 | Proxmox VE 虚拟机,4 vCPU / 5.8 GiB |
| Kubernetes | k3s v1.32.3+k3s1,单节点 |
| Ingress | Traefik 3.3.2(k3s 自带) |
| 私有 CA | step-ca 0.30.2 / step CLI 0.31.0 |
| cert-manager | v1.21.3 |
| Vault | 2.2.2,file backend |
| 监控 | Prometheus 3.16.0 / Alertmanager 0.35.0 |
| 证书默认有效期 | 10 分钟(仅为测试续期;Vault 测试用 24 小时) |
测试域名是 test.apps.homelab.internal、renew.apps.homelab.internal 和 myapp.apps.homelab.internal。step-ca 运行在同一个 VM 上,监听 8443;Traefik 监听 80/443。
测试一:内网服务证书签发
创建 Certificate 并等待就绪:
kubectl create namespace cert-test
kubectl apply -f - <<'EOF'
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: test-cert
namespace: cert-test
spec:
secretName: test-tls
commonName: test.apps.homelab.internal
dnsNames:
- test.apps.homelab.internal
renewBefore: 5m
issuerRef:
name: step-ca-issuer
kind: ClusterIssuer
EOF
kubectl wait --for=condition=Ready certificate/test-cert -n cert-test --timeout=120s
kubectl get certificate -n cert-test
实际结果是 READY=True,状态为 Certificate is up to date and has not expired,从创建到就绪大约 20 秒。
检查证书细节:
kubectl get secret -n cert-test test-tls -o jsonpath='{.data.tls\.crt}' \
| base64 -d \
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
输出确认了主题、签发者和 SAN:
subject=CN = test.apps.homelab.internal
issuer=O = Homelab Root CA, CN = Homelab Root CA Intermediate CA
X509v3 Subject Alternative Name:
DNS:test.apps.homelab.internal
这一步同时验证了 CA 信任链:客户端信任 Root CA,叶子证书由 Intermediate CA 签发,中间证书由 Root CA 签发。
测试二:自动续期
为了在几分钟内看到续期,我把 step-ca 的 ACME 默认有效期设为 10 分钟,并给 Certificate 设置 renewBefore: 5m:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: renew-test
namespace: cert-test
spec:
secretName: renew-test-tls
commonName: renew.apps.homelab.internal
dnsNames:
- renew.apps.homelab.internal
renewBefore: 5m
issuerRef:
name: step-ca-issuer
kind: ClusterIssuer
把上面的 YAML 保存为 renew-cert.yaml,然后应用:
kubectl apply -f renew-cert.yaml
kubectl wait --for=condition=Ready certificate/renew-test -n cert-test --timeout=120s
kubectl get certificate -n cert-test renew-test -o wide
第一次签发后,证书有效期是 16:48:22 到 16:59:22,renewalTime 是 16:54:22,正好提前 5 分钟。到了续期时间,cert-manager 创建了 renew-test-2,随后又因为同样的 10 分钟有效期产生了 renew-test-3。截图中 revision=3,序列号和 notBefore/notAfter 都已经更新:

这说明续期链路是通的,不是只在第一次签发时成功。生产环境不会用 10 分钟有效期,改成 24 小时、renewBefore: 8h 更合适。
测试三:Ingress 注解自动签发
部署一个 nginx 和一个带 cert-manager 注解的 Ingress:
kubectl apply -f - <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
namespace: cert-test
spec:
replicas: 1
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: nginx
image: nginx:1.27-alpine
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: myapp
namespace: cert-test
spec:
selector:
app: myapp
ports:
- port: 80
targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: myapp
namespace: cert-test
annotations:
cert-manager.io/cluster-issuer: step-ca-issuer
spec:
ingressClassName: traefik
tls:
- hosts:
- myapp.apps.homelab.internal
secretName: tls-myapp
rules:
- host: myapp.apps.homelab.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: myapp
port:
number: 80
EOF
kubectl wait --for=condition=Ready certificate/tls-myapp -n cert-test --timeout=120s
kubectl get ingress,certificate -n cert-test
tls-myapp 变成 Ready=True 后,用 curl 验证 HTTPS:
sudo curl -sSI \
--cacert /opt/step-ca/certs/root_ca.crt \
--resolve myapp.apps.homelab.internal:443:10.31.0.141 \
https://myapp.apps.homelab.internal/
实际返回 HTTP/2 200,说明 Traefik 已经加载了 cert-manager 生成的 Secret,TLS 握手和证书校验都通过:

测试四:监控指标
把 cert-manager 的 metrics 端口转到本地,查三个关键指标:
kubectl -n cert-manager port-forward svc/cert-manager 9402:9402 >/dev/null 2>&1 &
sleep 2
curl -s localhost:9402/metrics \
| grep -E '^certmanager_certificate_(expiration_timestamp_seconds|ready_status|renewal_timestamp_seconds)'
实际输出里能看到 test-cert、renew-test 和 tls-myapp 的过期时间、就绪状态和续期时间。ready_status{condition="True"} 为 1,condition="False" 为 0,和资源状态一致,指标截图见上一节。
测试结果汇总
| 项目 | 结果 |
|---|---|
| step-ca 服务 | systemd active (running),step ca health 返回 ok |
| ACME 账户 | ClusterIssuer Ready=True,账户注册成功 |
| 首次签发 | Certificate Ready=True,约 20 秒 |
| 证书链 | Leaf → Intermediate CA → Root CA,SAN 正确 |
| 自动续期 | revision 从 1 升到 3,序列号和有效期更新 |
| Ingress 自动签发 | tls-myapp Ready,HTTPS 返回 HTTP/2 200 |
| Vault PKI | vault-issuer Ready,vault-test 由 Vault Intermediate CA 签发,24 小时有效 |
| 监控指标 | 过期、就绪、续期三类指标均可抓取 |
| 告警链路 | CertificateNotReady 进入 firing,Alertmanager 收到 active 告警 |
| step-ca 吊销 | mTLS 和 JWK token 两种方式均成功,序列号出现在 /1.0/crl |
| Vault 吊销 | revocation_time 已写入,序列号出现在 Vault CRL |
没有验证的部分
下面这些内容在本文里只作为方案说明,没有在这台 k3s VM 上完整部署:
- Cloudflare API 的真实调用(需要域名和 API token);
- SPIFFE/SPIRE 工作负载身份;
- cert-manager CSI Driver 的证书挂载和轮换;
- wildcard 证书的 DNS-01 流程(需要可编程 DNS)。
文中没有说明实测的部分按方案示例看待,不要直接当成已经在生产验证过的配置。
故障排查
1. x509: certificate signed by unknown authority
cert-manager 访问 step-ca 时最常见的错误。原因是 ClusterIssuer 没有配置 caBundle,或者 base64 内容不对。
# 确认 Root CA 路径
sudo ls -l /opt/step-ca/certs/root_ca.crt
# 重新生成 base64,注意不要带换行
CA_B64=$(sudo base64 -w0 /opt/step-ca/certs/root_ca.crt)
echo "$CA_B64" | head -c 80; echo
kubectl describe clusterissuer step-ca-issuer
2. HTTP-01 无法签发 wildcard
ACME 的 HTTP-01 challenge 需要访问具体域名的 /.well-known/acme-challenge/<token>,wildcard 没有对应的主机名,所以只能走 DNS-01。cert-manager 的报错通常会出现在 Order 或 Challenge 的 message 里:
kubectl get order,challenge -n cert-test
kubectl describe challenge -n cert-test <challenge-name>
3. 证书反复续期
如果 renewBefore 大于等于证书的实际有效期,cert-manager 会认为证书一直处于“需要续期”的状态。先看证书的真实有效期:
kubectl get certificate -n cert-test renew-test -o jsonpath='{.status.notAfter}{"\n"}'
再对照 step-ca 的 provisioner 配置:
sudo step ca provisioner list \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt
把 renewBefore 调到实际有效期的一半左右,或者把 CA 的 defaultTLSCertDuration 调大。
4. CoreDNS 自定义 hosts 导致 CrashLoopBackOff
如果直接在 CoreDNS 的 .override 文件里再写一个 hosts 块,CoreDNS 会报:
plugin/hosts: this plugin can only be used once per Server Block
因为 k3s 默认的 Corefile 里已经有一个 hosts /etc/coredns/NodeHosts。正确做法是给 homelab.internal 单独建一个 server block,放在 coredns-custom 的 .server 文件里:
apiVersion: v1
kind: ConfigMap
metadata:
name: coredns-custom
namespace: kube-system
data:
homelab.server: |
homelab.internal:53 {
errors
hosts {
10.31.0.141 ca.homelab.internal test.apps.homelab.internal myapp.apps.homelab.internal
fallthrough
}
forward . /etc/resolv.conf
}
改完后重启 CoreDNS:
kubectl -n kube-system rollout restart deployment coredns
另外,k3s 会周期性地 reconcile coredns ConfigMap 的 NodeHosts,手工往里加记录可能过一会就消失。生产环境应该把记录放到自己的 DNS,而不是长期改 CoreDNS。
5. step ca root 下载失败
step ca root 需要验证 Root CA 的指纹。没有指纹时,它可能拒绝下载或者依赖系统信任库:
step ca root root_ca.crt \
--ca-url=https://ca.homelab.internal:8443 \
--fingerprint <root-ca-fingerprint>
指纹可以在 CA 初始化输出里找到,也可以在 CA 主机上执行:
step certificate fingerprint /opt/step-ca/certs/root_ca.crt
6. systemd 下 CA 无法写数据库
如果看到 permission denied 或 BadgerDB 打不开,检查 ProtectSystem=strict 下的 ReadWritePaths 是否包含 /opt/step-ca/db,以及目录属主是不是 step:step:
sudo systemctl status step-ca --no-pager
sudo journalctl -u step-ca -n 50 --no-pager
sudo ls -ld /opt/step-ca/db
证书吊销与安全事故响应
删除 Certificate 或删除 Secret 不等于吊销。删除只是让 cert-manager 不再管理这个对象,已经签发的证书在有效期内仍然可以使用。真正的安全事故响应要在签发它的 CA 上吊销,并确认客户端会检查吊销状态。
step-ca 的 CRL 和吊销
step-ca 的 CRL 默认关闭。配置要放在 ca.json 的顶层,不要放进 authority:
{
"crl": {
"enabled": true,
"generateOnRevoke": true,
"cacheDuration": "24h"
}
}
step-ca 文档里这个 CRL 功能仍标注为 experimental,上线前要在自己的客户端上验证兼容性。我第一次把 crl 写在 authority 下面,/1.0/crl 一直返回 404,日志里是 Certificate Revocation Lists are not enabled。移到顶层并重启 step-ca 后,CRL 端点才正常:
sudo systemctl restart step-ca
sudo curl -s --cacert /opt/step-ca/certs/root_ca.crt \
https://ca.homelab.internal:8443/1.0/crl \
-o /tmp/ca.crl
吊销时可以从 Secret 取出证书和私钥,用 mTLS 授权:
kubectl get secret -n cert-test revoke-test-tls -o jsonpath='{.data.tls\.crt}' \
| base64 -d > /tmp/revoke-test.crt
kubectl get secret -n cert-test revoke-test-tls -o jsonpath='{.data.tls\.key}' \
| base64 -d > /tmp/revoke-test.key
sudo step ca revoke \
--cert=/tmp/revoke-test.crt \
--key=/tmp/revoke-test.key \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
--reason=KeyCompromise
也可以按序列号加 JWK token 吊销:
PROV=$(sudo step ca provisioner list \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
| jq -r '.[] | select(.type=="JWK") | .name')
# step ca token --revoke 使用十进制序列号;openssl x509 -serial 输出的是十六进制
TOKEN=$(sudo step ca token <serial-number> --revoke \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
--provisioner="$PROV" \
--provisioner-password-file=/opt/step-ca/secrets/password.txt)
sudo step ca revoke <serial-number> \
--token="$TOKEN" \
--ca-url=https://ca.homelab.internal:8443 \
--root=/opt/step-ca/certs/root_ca.crt \
--reason=KeyCompromise
CRL 里能看到被吊销的序列号:
sudo openssl crl -inform DER -in /tmp/ca.crl -noout -text \
| sed -n '/Revoked Certificates/,+6p'

这里有个容易忽略的限制:打开 CRL 服务不会自动把 CRL 分发地址写进新签发的证书。客户端必须显式配置 CRL URL,或者由应用自己检查;否则吊销只能阻止证书续期,不能阻止已签发证书在剩余有效期内继续使用。证书有效期越短,这个窗口越小。
Vault PKI 的吊销
Vault 的吊销更直接,按序列号写入 pki_int/revoke:
export VAULT_ADDR=https://vault.homelab.internal:8200
export VAULT_CACERT=/opt/vault/tls/root_ca.crt
SERIAL=$(vault list -format=json pki_int/certs | jq -r '.[0]')
vault write pki_int/revoke serial_number="$SERIAL"
vault read pki_int/cert/$SERIAL | grep -E 'revocation_time|state'
再拉 Vault 的 CRL 确认序列号已经进入吊销列表:
curl -s --cacert /opt/vault/tls/root_ca.crt \
https://vault.homelab.internal:8200/v1/pki_int/crl/pem \
| openssl crl -in /dev/stdin -noout -text \
| sed -n '/Revoked Certificates/,+3p'

事故响应顺序
证书私钥泄露、主机被入侵或者 CA 私钥泄露,处理顺序不一样,但大方向一致:
- 确认范围:拿到证书序列号、私钥所在的 Secret 或主机、签发者和到期时间。
openssl x509 -serial和 CA 的签发日志都要看。 - 隔离:先停止使用这张证书的服务,删除对应的 Secret 或挂载,必要时在入口层阻断流量。不要一边吊销一边继续让旧私钥提供服务。
- 吊销:在签发 CA 上执行 revoke,记录 reason(私钥泄露用
KeyCompromise)和操作人。step-ca 和 Vault 都要保留吊销记录。 - 轮换:删除旧 Secret,让 cert-manager 重新签发;
rotationPolicy: Always可以保证每次续期都换私钥。如果怀疑签发 CA 本身泄露,就不只是换叶子证书,要轮换 Intermediate CA 甚至 Root CA,并重新分发信任链。 - 验证:确认 CRL 或 OCSP 里能查到旧序列号,确认客户端会拒绝旧证书,检查日志里是否还有旧序列号在活动。
- 复盘:检查 CA 日志、cert-manager Event、Kubernetes audit log,缩短证书有效期和
renewBefore,把同类告警补上。
几个配置上的注意事项:
allowRenewalAfterExpiry生产环境应该设为false,避免已过期证书继续续期;- 删除 Certificate 不会自动吊销,必须显式调用 CA 的 revoke;
- 短期证书能缩小泄露窗口,但不能替代吊销流程;
- Root CA 私钥尽量离线保存,日常签发只用 Intermediate CA;
- 如果客户端完全不检查 CRL,吊销的效果有限,这时短期证书和快速轮换更重要。
最佳实践
证书生命周期
| 阶段 | 建议 |
|---|---|
| 签发 | 内网服务用 24h 到 7d 的短期证书,减少泄露影响 |
| 存储 | Kubernetes Secret 开启 etcd 加密;CA 私钥离线保存 |
| 分发 | cert-manager 写 Secret,Ingress/Pod 自动挂载 |
| 续期 | renewBefore 设为有效期的 1/3 到 1/2 |
| 监控 | 7 天预警,24 小时严重告警 |
| 轮换 | 需要换私钥时用 rotationPolicy: Always |
安全加固
- Root CA 私钥离线保存,日常签发只用 Intermediate CA;
- CA 服务只监听内网,ACME 端点不要直接暴露到公网;
- 每个 Issuer 只允许必要的域名,Vault 的 role 用
allowed_domains限制; - 打开 CA 和 cert-manager 的审计日志,至少保留签发、续期、失败记录;
- 备份 Root CA、Intermediate CA、
ca.json和db,恢复演练比备份本身更重要。
备份与恢复
# 备份前先停服务,避免 BadgerDB 在写入过程中被打包
sudo systemctl stop step-ca
# 备份 step-ca 的证书、密钥、配置和数据库
sudo tar czf step-ca-backup.tar.gz \
-C /opt step-ca/certs step-ca/secrets step-ca/config step-ca/db
sudo systemctl start step-ca
# 备份 cert-manager 的资源
kubectl get certificate,certificaterequest,issuer,clusterissuer -A -o yaml \
> cert-manager-backup.yaml
# 备份 cert-manager 生成的 TLS Secret
kubectl get secrets -A -l cert-manager.io/certificate-name \
-o yaml > tls-secrets-backup.yaml
恢复时先恢复 CA,再恢复 cert-manager 的 CRD 和资源,最后让 cert-manager 重新签发或续期。不要只备份 Secret 而不备份 CA 私钥,否则证书过期后无法续期。
总结
这套链路现在跑在一台 4 vCPU 的 k3s 虚拟机上:step-ca 负责内网 CA,cert-manager 负责申请和续期,Vault PKI 负责需要独立审计和策略的证书,Traefik 从 Secret 加载证书,Prometheus/Alertmanager 负责指标和告警。实测覆盖了首次签发、自动续期、Ingress 注解签发、Vault 签发、告警链路,以及两套 CA 的吊销和 CRL 查询。
还有几件事值得继续做:
- 给 wildcard 域名配 DNS-01,避免 HTTP-01 的限制;
- 把 Vault 的审计和租期策略继续补全;
- 在规模更大时引入 SPIFFE/SPIRE 或 cert-manager CSI Driver,减少对 Secret 的依赖。
证书管理不需要一开始就上最复杂的方案。先把 CA、Issuer、续期和告警跑通,再按服务的重要程度逐步加策略,维护成本会低很多。
参考资料
如果你觉得这篇文章对你有所帮助,欢迎赞赏~
赞赏