VCF 私有 AI 服务（PAIS）自签名 TLS 证书配置避坑指南

在实验室或概念验证环境中，自签名 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 容器启动失败，提示 "证书验证失败：主机名不匹配"

1. 现象描述

部署 PAIS 配置后，API 容器日志显示报错： $SSL: CERTIFICATE_VERIFY_FAILED$ certificate verify failed: Hostname mismatch，但实际证书中的主机名与目标域名(如 auth.vcf.lab)完全一致，排查陷入僵局。

2. 根源分析

这一报错并非真正的主机名不匹配，而是 Python 依赖的 "certifi" 库对自签名证书有特殊要求 ------ 必须包含Subject Alternative Name(SAN，主题备用名称) 扩展字段。传统自签名证书仅配置 Common Name(CN)字段，虽能满足 Golang 等工具的验证逻辑，但 Python 库严格遵循 RFC 6125 标准，优先通过 SAN 字段验证域名合法性，缺失该字段则直接判定证书无效。

3. 解决方案：生成含 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 推送模型失败，提示 "证书不符合标准"

1. 现象描述

使用 VCF CLI 工具推送 AI 模型至 Harbor 仓库时，报错：tls: failed to verify certificate: x509: "registry.vcf.lab" certificate is not standards compliant，但该 Harbor 已配置为 Docker 的 "不安全仓库"，且 Docker 登录、推送容器镜像均正常。

2. 根源分析

Docker 的 "不安全仓库" 配置仅适用于 Docker 自身的镜像推拉流程，而 VCF CLI 的 PAIS 插件采用独立的证书验证逻辑，未继承 Docker 的信任配置。报错中 "不符合标准" 实际是指证书未被系统信任链识别，需手动将自签名证书添加到操作系统的根信任库。

3. 解决方案：跨系统添加证书至信任库

(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命令检查证书结构，或查看工具日志确认具体验证失败环节。