在实验室或概念验证环境中，自签名 TLS 证书是 VCF 私有 AI 服务(PAIS)部署的常用选择，但常因底层库验证机制差异引发各类报错。本文针对 PAIS 部署中两类高频证书问题 ——API 容器启动失败与 Harbor 模型推送报错，拆解报错根源，提供含 SAN 扩展的证书生成、多系统信任库配置等 step-by-step 解决方案，帮助运维人员快速排障，避免陷入底层库错误信息的误导。
一、背景说明
VMware 私有 AI 服务(PAIS)已整合至 VMware 云基础架构(VCF)生态，成为私有云 AI 部署的重要组件。在非生产环境中，自签名 TLS 证书因无需第三方 CA 审核，广泛用于加密通信验证，但由于不同编程语言(如 Python、Golang)及工具(如 VCF CLI、Docker)的证书验证逻辑存在差异，易出现 “证书无效”“主机名不匹配” 等看似矛盾的报错，实际多与证书配置不规范或信任链未建立相关。
二、常见问题及解决方案
(一)问题 1：PAIS API 容器启动失败，提示 “证书验证失败：主机名不匹配”
- 现象描述
部署 PAIS 配置后，API 容器日志显示报错：[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch，但实际证书中的主机名与目标域名(如 auth.vcf.lab)完全一致，排查陷入僵局。
- 根源分析
这一报错并非真正的主机名不匹配，而是 Python 依赖的 “certifi” 库对自签名证书有特殊要求 —— 必须包含Subject Alternative Name(SAN，主题备用名称) 扩展字段。传统自签名证书仅配置 Common Name(CN)字段，虽能满足 Golang 等工具的验证逻辑，但 Python 库严格遵循 RFC 6125 标准，优先通过 SAN 字段验证域名合法性，缺失该字段则直接判定证书无效。
- 解决方案：生成含 SAN 扩展的自签名证书
步骤 1：准备 OpenSSL 工具
确保环境已安装 OpenSSL(Windows 可从官网下载，Linux/macOS 通常预装)，验证命令：
openssl version # 输出版本号即正常
步骤 2：创建证书配置文件(req.conf)
新建文本文件，写入以下内容(替换 DNS 字段为实际使用的域名 / IP)：
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no # 生成时不交互询问信息
[req_distinguished_name]
C = CN # 国家代码
ST = Beijing # 省份
L = Beijing # 城市
O = Internal Lab # 机构名称
CN = auth.vcf.lab # 主域名(与实际使用一致)
[v3_req]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names # 关联SAN配置
[alt_names]
DNS.1 = auth.vcf.lab # 核心域名
DNS.2 = registry.vcf.lab # 其他需支持的域名(如Harbor地址)
IP.1 = 192.168.1.100 # 可选：服务绑定的IP地址
步骤 3：生成证书与私钥
执行以下命令，一次性生成有效期 10 年的证书(mkcert.crt)和私钥(mkcert.key)：
openssl req -x509 -newkey rsa:2048 -keyout mkcert.key -out mkcert.crt -days 3650 -nodes -config req.conf -extensions v3_req
参数说明：-x509表示生成自签名证书，-nodes表示私钥不加密，-days 3650设置有效期 10 年。
步骤 4：验证 SAN 字段是否生效
生成后执行以下命令检查证书信息：
openssl x509 -in mkcert.crt -text -noout | grep -A 1 "Subject Alternative Name"
若输出包含配置文件中指定的 DNS 和 IP，说明 SAN 字段已成功添加。
步骤 5：替换 PAIS 的证书配置
将生成的mkcert.crt(证书)和mkcert.key(私钥)替换 PAIS 部署目录下的原有证书文件，重启 API 容器即可解决启动失败问题。
(二)问题 2：向 Harbor 推送模型失败，提示 “证书不符合标准”
- 现象描述
使用 VCF CLI 工具推送 AI 模型至 Harbor 仓库时，报错：tls: failed to verify certificate: x509: “registry.vcf.lab” certificate is not standards compliant，但该 Harbor 已配置为 Docker 的 “不安全仓库”，且 Docker 登录、推送容器镜像均正常。
- 根源分析
Docker 的 “不安全仓库” 配置仅适用于 Docker 自身的镜像推拉流程，而 VCF CLI 的 PAIS 插件采用独立的证书验证逻辑，未继承 Docker 的信任配置。报错中 “不符合标准” 实际是指证书未被系统信任链识别，需手动将自签名证书添加到操作系统的根信任库。
- 解决方案：跨系统添加证书至信任库
(1)macOS 系统
双击生成的mkcert.crt证书文件，弹出 “钥匙串访问” 窗口;
选择 “系统” 钥匙串，点击 “添加”;
右键点击刚添加的证书，选择 “显示简介”;
在 “信任” 选项卡中，设置 “使用此证书时” 为 “始终信任”，关闭窗口并输入系统密码确认。
(2)Windows 系统(两种方式)
图形界面方式：
按Win+R输入certmgr.msc，打开证书管理器;
展开 “受信任的根证书颁发机构”→“证书”，右键选择 “所有任务”→“导入”;
浏览选择mkcert.crt，按向导完成导入，确保存储位置为 “受信任的根证书颁发机构”。
命令行方式(管理员权限)：
certutil -addstore "Root" C:\path\to\mkcert.crt
(3)Linux 系统(分发行版)
Debian/Ubuntu 系列：
复制证书到信任目录
sudo cp mkcert.crt /usr/local/share/ca-certificates/
更新证书数据库
sudo update-ca-certificates
CentOS/RHEL 系列：
复制证书到信任目录
sudo cp mkcert.crt /etc/pki/ca-trust/source/anchors/
提取并更新证书
sudo update-ca-trust extract
步骤 4：验证配置
重新执行 VCF CLI 模型推送命令，此时工具会通过系统信任库验证证书合法性，报错即可解决。
三、注意事项
自签名证书仅适用于实验室、测试或内部验证环境，生产环境需使用可信 CA 签发的证书，避免安全风险;
生成证书时，SAN 字段需包含所有可能的访问域名 / IP(如 PAIS 服务地址、Harbor 地址)，避免遗漏导致部分场景验证失败;
证书有效期建议设置为 1-3 年，过期前需提前重新生成并替换，同时更新系统信任库;
若使用 Java 开发的相关组件，需额外将证书导入 JVM 的 cacerts 信任库(命令：keytool -import -trustcacerts -alias pais-cert -file mkcert.crt -keystore $JAVA_HOME/lib/security/cacerts)。
通过规范证书生成配置与建立系统级信任，可有效解决 PAIS 部署中 90% 以上的自签名 TLS 证书问题。若遇到特殊报错，可优先通过openssl x509 -text -noout命令检查证书结构，或查看工具日志确认具体验证失败环节。
注·部分内容为AI辅助生成