#配置 TLS

本指南介绍 Alauda Hyperflux 对其出站连接的 TLS 相关配置：LLM 服务、reranker、MCP server 和 PostgreSQL。

最常见的需求——信任使用内部或自签名证书的 LLM 或 MCP endpoint——可以通过 Extra CA ConfigMaps 来解决，该功能可直接在安装表单中使用。对于测试环境，LLM 调用的证书验证也可以完全跳过（见最后一节）。

#信任内部 / 自签名 CA（Extra CA ConfigMaps）

如果你的 LLM、reranker 或 MCP endpoint 提供的是由内部 CA 签名的证书，请求会因 CERTIFICATE_VERIFY_FAILED 而失败。将 CA 证书添加到信任证书包中：

1. 创建一个包含 CA 证书（PEM）的 ConfigMap，放在安装 Alauda Hyperflux 的命名空间中（cpaas-system）。CA 证书是公开信息，因此应使用 ConfigMap，而不是 Secret。一个 ConfigMap 可以包含多个 *.pem 键：

   kubectl create configmap my-org-internal-ca -n cpaas-system \
     --from-file=ca.pem=/path/to/internal-ca.pem

2. 在 管理员 / Marketplace / 集群插件 中，安装或更新 Alauda Hyperflux 插件，并在 Extra CA ConfigMaps 下添加该 ConfigMap 名称。服务会自动重启。

每个列出的 ConfigMap 都会以只读方式挂载到 /opt/extra-ca/<configmap-name>/。启动时，这些证书会与默认 CA 证书包合并，并将合并后的证书包应用于整个进程，因此它会覆盖 LLM、reranker 和 MCP 连接。

注意： PostgreSQL 是例外——它不使用此证书包。连接外部 PostgreSQL 的 TLS 需要通过插件配置中的 pgSSLMode / pgSSLRootCert 单独配置。

更新已注册 ConfigMap 的 内容（例如轮换 CA）需要手动重启：

kubectl -n cpaas-system rollout restart deploy/smart-doc

#验证

# The mounted CA and the merged bundle
kubectl -n cpaas-system exec deploy/smart-doc -c serve -- ls /opt/extra-ca/my-org-internal-ca/
kubectl -n cpaas-system exec deploy/smart-doc -c serve -- grep -c 'BEGIN CERTIFICATE' /tmp/smart-doc-ca.pem

# The startup log line
kubectl -n cpaas-system logs -l app=smart-doc -c serve | grep extra_ca

预期的日志行：

extra_ca: merged 1/1 CA file(s) into /tmp/smart-doc-ca.pem

然后在聊天图表中提问——此前因 CERTIFICATE_VERIFY_FAILED 而失败的 endpoint 请求现在应该可以成功了。

#跳过 TLS 证书验证（不推荐）

对于无法方便导入 CA 的测试或开发环境，LLM 调用 的 TLS 证书验证可以通过 llmSkipSslVerify 完全关闭。

警告： 这会使 LLM 连接暴露于中间人攻击之下，并且会覆盖 TLS profile 以及任何额外的 CA 信任——这也是它被刻意不提供在安装表单中的原因。对内部证书而言，生产环境安全的做法是使用上面的 Extra CA ConfigMaps。该设置只影响 LLM 调用；reranker、MCP 和 PostgreSQL 连接不受影响。

通过直接 patch 插件配置（ModuleInfo）来应用它：

# Find the ModuleInfo of the Hyperflux plugin (cluster-scoped, name like global-<hash>)
MI=$(kubectl get moduleinfo -o jsonpath='{.items[?(@.spec.module=="alauda-hyperflux")].metadata.name}')

kubectl patch moduleinfo "$MI" --type=merge -p \
  '{"spec":{"config":{"smartdoc":{"llmSkipSslVerify":true}}}}'

平台会协调该变更并自动滚动这些 pod。启用后，每次启动都会记录一条警告：

LLM_SKIP_SSL_VERIFY=true — LLM TLS certificate verification is DISABLED (verify=False)

要恢复，只需将该值 patch 回 false。

对于外部 MCP server，还有一个等效的按 server 配置的 tls_verify: false 字段——请参见 配置外部 MCP server，注意事项相同。