# 控制面 IP 限制

API7 控制面（控制台和 Admin API）是部署中权限最高的管理入口。限制可以访问控制面的 IP 地址，可以缩小凭证被盗、横向移动和暴力破解场景下的攻击面。

控制台和 Admin API 由同一个控制面进程提供，并共享同一个配置文件。在其中配置的内置 IP 允许列表同时应用于**两个**界面。

## 配置内置 IP 允许列表[​](#配置内置-ip-允许列表 "配置内置 IP 允许列表的直接链接")

控制面从配置文件中读取 `security.ip_restriction` 配置块。Docker Compose 布局使用 `dashboard_conf/conf.yaml`，Helm 使用相应的 ConfigMap。将受信任网络添加到 `allow_list`：

dashboard\_conf/conf.yaml

```
security:

  ip_restriction:

    allow_list:

      - 192.168.1.0/24

      - 10.0.0.5/32

      - 2001:db8::10/128

    deny_list: []

    message: "Access denied"

    response_code: 403
```

行为说明：

* 两个列表仅接受 CIDR 格式。单个 IPv4 地址使用 `/32`，单个 IPv6 地址使用 `/128`。不带前缀或格式错误的条目会导致控制面无法启动。
* 空 `allow_list` 表示**允许所有请求**；空 `deny_list` 表示**不拒绝任何请求**。要限制控制面，请将 `allow_list` 设置为非空列表。
* 来自不在允许列表中的 IP 的请求会在执行任何身份认证前收到 HTTP `403` 和 `{"error_msg":"Access denied"}`。这同时适用于同一监听端口（默认为 `7443`）上的控制台界面和 Admin API。
* `message` 和 `response_code` 用于自定义拒绝响应。

重启控制面容器或 Pod 以应用更改。

警告

启用 `allow_list` 前，请确保包含所有需要访问控制面的操作人员工作站、CI/CD Runner 和监控系统的 IP。列表配置错误可能导致无法访问控制台和 Admin API；恢复时需要通过控制面主机的 shell 访问还原文件。

## 此配置不涵盖的范围[​](#此配置不涵盖的范围 "此配置不涵盖的范围的直接链接")

通过 Admin API 配置为插件或全局规则的 `ip-restriction` 插件在**数据面**执行，只影响代理到服务的客户端流量。它不会限制控制面上的 Admin API 请求，不能替代上述配置。

## 纵深防御[​](#纵深防御 "纵深防御的直接链接")

控制面的内置允许列表应作为多层防御之一：

* **网络防火墙或安全组**：在平台层限制控制面 Admin API/控制台端口（默认为 `7443`）的入站流量，例如使用 AWS 安全组、Kubernetes `NetworkPolicy` 或硬件防火墙。
* **控制面前置反向代理**：在 NGINX、HAProxy 或云负载均衡器上终止控制面流量，并独立于控制面自身的允许列表实施 IP 允许列表。
* **Admin API Key 身份认证**：每个 Admin API 请求都必须携带有效的 `X-API-KEY` 请求头。请定期轮换密钥，并按用户或服务账号划分权限范围。
* **控制台 SSO**：在允许列表的基础上配置[控制台单点登录（SSO）](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-dashboard.md)，使处于允许网络中成为访问的必要条件，而非充分条件。
* **控制面与数据面之间的 mTLS**：参阅[控制面与数据面之间的双向 TLS](https://docs.apiseven.com/api7-gateway/security-and-compliance/authenticate/mutual-tls-cp-dp.md)，确保即使攻击者能够访问 Admin API 端口，也无法冒充数据面节点。

## 最佳实践[​](#最佳实践 "最佳实践的直接链接")

1. **在网络层默认拒绝**：仅允许已知操作人员子网、CI/CD Runner 和堡垒机访问控制面端口。
2. **审计变更**：将 IP 限制与[审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)结合使用，即使允许的网络遭到入侵，也能发现未经授权的配置变更。
3. **限制前先测试**：先在非生产环境中测试 `allow_list` 变更，并保留带外恢复路径，例如主机 shell 访问。

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

* [审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)，检测来自受限 IP 的失败登录尝试。
* [控制台单点登录（SSO）](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-dashboard.md)，集中管理用户身份认证。
