跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

故障排除

最后更新 查看 MarkdownAgent 设置

如果在配置并嵌入客户端 SSL 证书后查询仍返回错误,请检查以下设置。


检查 SSL/TLS 握手

在终端中,使用以下命令检查客户端与 API 端点之间是否可以成功建立 SSL/TLS 连接。

curl --verbose --cert /path/to/certificate.pem --key /path/to/key.pem https://your-api-endpoint.com

如果无法完成 SSL/TLS 握手,请检查证书和私钥是否正确。 如果握手完成但请求仍被阻止,请确认 Cloudflare 正在验证客户端证书。


检查 mTLS 主机

检查是否已为正确的主机启用 mTLS。主机应与您要保护的 API 端点匹配。


检查 mTLS 规则

要检查 mTLS 规则,请考虑以下步骤。更多指导请参阅自定义规则。

  1. 在 Cloudflare 仪表板中,前往 Security rules(安全规则) 页面。

    前往 Security rules(安全规则) ↗
  2. 在特定规则上,选择 Edit(编辑)。

  3. 在该规则上,检查:

    • Expression Preview 是否正确。

    • 如果定义了主机名,是否与您的 API 端点匹配。例如,对于 API 端点 api.trackers.ninja/time,规则应类似于:

      (http.host in {"api.trackers.ninja"} and not cf.tls_client_auth.cert_verified)
  4. 要编辑规则,请使用用户界面或选择 Edit expression(编辑表达式)。


高级调试

您可以使用 Cloudflare Workers 调试客户端证书验证失败。

  1. 创建一个 Worker,用于记录传入请求的 cf 属性,并将每个请求转发到源站:

    src/index.jsjs
    export default {
    	async fetch(request) {
    		console.info({ message: JSON.stringify(request.cf, null, 2) });
    		return fetch(request);
    	},
    };
    src/index.tsts
    export default {
      async fetch(request): Promise<Response> {
        console.info({ message: JSON.stringify(request.cf, null, 2) });
        return fetch(request);
      },
    } satisfies ExportedHandler;
  2. 使用 Worker route 将 Worker 与已启用 mTLS 的主机名关联。

  3. 向已配置的主机名和/或路径发起请求,分别在发送和不发送 mTLS 客户端证书的情况下进行。

  4. 在 Observability 仪表板中,将记录的 tlsClientAuth 值与预期值进行比较。

    前往 Observability(可观测性) ↗
  • 有效证书

    "tlsClientAuth": {
      "certPresented": "1",
      "certVerified": "SUCCESS",
    },
  • 无效证书(例如自签名证书)

    "tlsClientAuth": {
      "certPresented": "1",
      "certVerified": "FAILED:self signed certificate",
    },
  • 无证书

    "tlsClientAuth": {
      "certPresented": "0",
      "certVerified": "NONE",
    },

已达到证书配额

Cloudflare 托管 CA

Cloudflare 托管的客户端证书计入按 zone 的配额。要释放名额,请吊销不再需要的证书。吊销证书会立即释放该名额。

要列出并吊销证书,请参阅 client certificates API。

使用自有 CA (BYOCA)

每个 Enterprise 账户最多可为 BYOCA 上传五个 CA 证书。此配额由 API Shield、Workers mTLS 和 Cloudflare Gateway 共享。

如果超出此限制,API 将返回:

{
  "code": 1489,
  "message": "Hit maximum CA cert allocation."
}

要释放名额,必须先移除该 CA 的所有主机名关联,然后再删除它。要提高配额,请联系您的账户团队。


BYOCA 证书上传错误

上传用于 自带 CA (BYOCA) 的 CA 证书时,证书必须满足以下要求:

  • CA 证书可以来自公开受信任的 CA 或自签名。

  • 在证书 Basic Constraints 中,CA 属性必须设置为 TRUE。

  • 证书必须使用以下列出的签名算法之一:

    允许的签名算法

    x509.SHA1WithRSA

    x509.SHA256WithRSA

    x509.SHA384WithRSA

    x509.SHA512WithRSA

    x509.ECDSAWithSHA1

    x509.ECDSAWithSHA256

    x509.ECDSAWithSHA384

    x509.ECDSAWithSHA512

上传 CA 证书,而不是 leaf 证书

您上传的必须是 CA 证书——也就是说,其扩展中必须包含 Basic Constraints: CA=TRUE。请上传客户端证书链中的 CA 证书,而不是客户端证书本身。

上传失败的常见原因是上传了叶(客户端)证书而不是 CA 证书。如果您的证书链是 Root CA → Intermediate CA → Client certificate,请在单个 PEM 文件中上传完整 CA 链,先放中间 CA,再放根 CA。

如果只上传中间 CA,即使主机名已与该 CA 关联,每次请求的 mTLS 验证也会失败。在 HTTP 请求日志中,ClientMTLSAuthCertFingerprint 与预期的客户端证书匹配,但 ClientMTLSAuthStatus 为 unknown。

要确认证书是 CA 证书,请对链中的每张证书运行以下命令:

openssl x509 -in certificate.pem -noout -text | grep -A1 "Basic Constraints"

输出应包含 CA:TRUE。如果显示 CA:FALSE 或该字段缺失,则该证书不是 CA 证书,无法上传。

不支持的签名算法

CA 证书必须使用以下签名算法之一:

  • SHA1WithRSA, SHA256WithRSA, SHA384WithRSA, SHA512WithRSA
  • ECDSAWithSHA1, ECDSAWithSHA256, ECDSAWithSHA384, ECDSAWithSHA512

如果 CA 证书使用了其他算法,请使用受支持的算法重新签发。

PEM 内容格式不正确

上传请求中的 certificates 字段必须包含有效且正确分隔的 PEM 内容。确保证书以 -----BEGIN CERTIFICATE----- 开头,并以 -----END CERTIFICATE----- 结尾。请勿在此字段中包含私钥或证书签名请求。

这篇文档对您有帮助吗?