# 控制面与数据面之间的双向 TLS

保护控制面（CP）与数据面（DP）之间的通信通道，是保障 API7 网关完整性的基础。配置变更、策略更新和指标上报通过此通道传输。控制台生成的数据面部署通过 DP Manager 的 `7943` 端口使用双向 TLS（mTLS）。此连接会加密流量，要求数据面提供客户端证书，并使用配置的 CA 验证服务器证书。

为保持兼容，DP Manager 也在 `7900` 端口接受 HTTP 连接。这些连接使用实例 Token 认证，但未经加密。生产部署应使用 mTLS 监听，并通过防火墙规则或网络策略将 `7900` 端口限制在可信网络中。切勿将 `7900` 端口暴露到公网。

mTLS 通道使用公钥基础设施（PKI）模型，签发并验证部署专用的证书。

### API7 中 mTLS 的工作原理[​](#api7-中-mtls-的工作原理 "API7 中 mTLS 的工作原理的直接链接")

双向 TLS 扩展了标准 TLS 协议，要求客户端和服务器双方都出示并验证证书。在 API7 中，数据面作为客户端发起连接，控制面作为服务器。

该过程遵循标准 PKI 信任模型：

1. **信任锚**：控制面维护一个自动生成的唯一证书颁发机构（CA）。此 CA 是该 API7 部署唯一的信任根。
2. **证书签发**：控制面使用其私有 CA 为自身签发唯一的服务器证书，并为每个数据面节点签发客户端证书。
3. **握手与验证**：数据面节点尝试连接控制面时，会出示客户端证书。控制面验证该证书是否由其可信 CA 签发；同时，数据面使用同一 CA 验证控制面的服务器证书。

在 `7943` 端口上，双方在 TLS 握手期间验证对方证书。DP Manager 会拒绝未提供其可信 CA 签发证书的客户端；数据面会拒绝非配置 CA 签发的服务器证书。请将 CA 私钥和数据面端点配置作为敏感部署材料加以保护。

<!-- -->

### CA 和证书管理[​](#ca-和证书管理 "CA 和证书管理的直接链接")

API7 旨在尽可能自动且安全地完成证书管理。

#### 自动生成 CA[​](#自动生成-ca "自动生成 CA的直接链接")

API7 控制面首次启动时会检查数据库中是否已有 CA。如果未找到 CA，则自动生成新的根 CA。每个客户的部署都有唯一 CA，确保一个客户环境中的证书不会被另一个环境信任。随后，控制面立即使用该 CA 签发建立安全通信所需的服务器和客户端证书。

#### 证书有效期[​](#证书有效期 "证书有效期的直接链接")

安装新的数据面节点时，可以根据组织的安全策略指定证书有效期。API7 提供以下预定义选项：

| 有效期 | 使用场景                           |
| ------ | ---------------------------------- |
| 1 年   | 需要频繁轮换证书的高安全环境       |
| 2 年   | 采用定期轮换周期的均衡方案         |
| 3 年   | 标准企业部署                       |
| 5 年   | 长期运行的生产环境                 |
| 10 年  | 默认值；适用于稳定、低频轮换的部署 |

默认情况下，新数据面节点会获得有效期为 **10 年**的证书。不过，你可以在数据面安装过程中选择更短的有效期，以便更频繁地轮换证书并满足安全合规要求。

#### 证书轮换[​](#证书轮换 "证书轮换的直接链接")

证书会自动生成，但当前仍需手动执行轮换。管理员负责跟踪证书到期时间，并在安全策略要求或可能发生泄露时启动轮换。

#### 灵活部署[​](#灵活部署 "灵活部署的直接链接")

API7 支持灵活部署数据面节点。可以为每个数据面节点配置由控制面 CA 签名的唯一证书；在较简单的部署场景中，多个数据面节点也可以共享同一个客户端证书。

### 部署和配置[​](#部署和配置 "部署和配置的直接链接")

从控制台生成数据面部署时，配置会连接到 `7943` 端口，并提供所需的 CA 和客户端证书。这是正常的生成部署方式，但并不是 DP Manager 唯一的监听入口。

为保持兼容，`7900` 端口接受使用实例 Token 认证的 HTTP 连接。即使当前所有数据面都使用 mTLS，也应限制对该端口的访问。

### 验证 mTLS 配置[​](#验证-mtls-配置 "验证 mTLS 配置的直接链接")

确认数据面连接端点使用 `https` 和端口 `7943`，并已安装生成的 CA、客户端证书和客户端私钥。健康状态确认连接正常，但仅凭健康状态不能证明连接使用了 mTLS，因为 `7900` 端口也可以为已连接的数据面提供服务。

* **连接成功**：如果配置为使用 `7943` 端口的数据面在控制台中显示为健康且已连接，则表示 mTLS 连接已建立。
* **连接失败**：如果 mTLS 配置不正确，例如证书缺失或无效，数据面将无法连接 `7943` 端口获取配置。另行配置到 `7900` 端口的连接不能证明 mTLS 正常工作。

### 故障排查[​](#故障排查 "故障排查的直接链接")

CP-DP 通信最常见的问题与网络连接有关，而非 mTLS 配置本身。如果数据面节点无法连接，请检查：

* **网络可达性**：确保数据面节点与控制面的所需 HTTPS 端口之间存在畅通的网络路径。
* **防火墙规则**：确认没有防火墙、安全组或网络策略阻止 CP 与 DP 之间的流量。
* **DNS 解析**：确认数据面节点可以正确解析控制面的主机名。

### 性能注意事项[​](#性能注意事项 "性能注意事项的直接链接")

用于保护 CP-DP 通道的 mTLS 机制对数据面处理的 API 流量**没有性能影响**。该安全通道仅用于管理任务，例如控制面向数据面推送配置更新，以及数据面向控制面上报指标。面向客户端的所有 API 请求都由独立且高度优化的数据路径处理，不参与此 mTLS 握手。
