From 05eecef62af9d693c5126e659c0e731c2b692fd1 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Fri, 28 Feb 2025 14:20:43 +0800 Subject: [PATCH 01/24] copy --- .../api-consumption/consumer-restriction.md | 211 ++++ .../manage-consumer-credentials.md | 229 ++++ .../version-3.6.x/api-observability/alert.md | 444 ++++++++ .../api-observability/logging.md | 121 ++ .../api-observability/monitoring.md | 68 ++ .../version-3.6.x/api-portal/developer-sso.md | 115 ++ .../api-portal/productize-services.md | 120 ++ .../api-security/api-authentication.md | 1009 +++++++++++++++++ .../api-security/aws-secrets-manager.md | 474 ++++++++ .../version-3.6.x/api-security/block-ip.md | 157 +++ .../version-3.6.x/api-security/client-mtls.md | 204 ++++ .../api-security/configure-mtls.md | 184 +++ .../api-security/hashicorp-vault.md | 519 +++++++++ .../api-security/rate-limiting.md | 593 ++++++++++ .../best-practices/api-version-control.md | 84 ++ .../best-practices/configure-grpc.md | 434 +++++++ .../best-practices/custom-plugin.md | 40 + .../design-custom-role-system.md | 200 ++++ .../best-practices/devops-adc.md | 692 +++++++++++ .../manage-services-in-multi-environments.md | 133 +++ .../best-practices/manage-token.md | 85 ++ .../best-practices/service-discovery.md | 85 ++ .../version-3.6.x/best-practices/sso.md | 212 ++++ .../best-practices/upstream-ha.md | 74 ++ .../deployment/ingress-controller.md | 111 ++ .../version-3.6.x/deployment/k8s-openshift.md | 399 +++++++ .../getting-started/add-gateway-group.md | 27 + .../getting-started/add-gateway-instance.md | 59 + .../getting-started/audit-logging.md | 68 ++ .../getting-started/canary-upstream.md | 551 +++++++++ .../getting-started/create-custom-role.md | 157 +++ .../deploy-resources-on-k8s.md | 114 ++ .../getting-started/install-api7-ee.md | 72 ++ .../getting-started/launch-your-first-api.md | 239 ++++ .../version-3.6.x/getting-started/license.md | 17 + .../getting-started/proxy-l4-traffic.md | 247 ++++ .../getting-started/publish-service.md | 287 +++++ .../version-3.6.x/getting-started/rbac.md | 267 +++++ .../getting-started/rollback-service.md | 36 + .../getting-started/sync-service.md | 118 ++ .../data-plane-resilience.md | 281 +++++ .../high-availability-installation.md | 117 ++ .../high-availability/overview.md | 21 + .../prepare-for-high-availability.md | 54 + .../introduction/api7-ee-architecture.md | 30 + .../introduction/what-is-api7-ee.md | 222 ++++ .../version-3.6.x/key-concepts/api-portal.md | 68 ++ .../key-concepts/api-products.md | 52 + .../key-concepts/authentication.md | 32 + .../key-concepts/certificates.md | 50 + .../version-3.6.x/key-concepts/consumers.md | 74 ++ .../version-3.6.x/key-concepts/developers.md | 53 + .../key-concepts/gateway-groups.md | 77 ++ .../version-3.6.x/key-concepts/overview.md | 10 + .../version-3.6.x/key-concepts/plugins.md | 80 ++ .../roles-and-permission-policies.md | 165 +++ .../version-3.6.x/key-concepts/routes.md | 39 + .../version-3.6.x/key-concepts/secrets.md | 58 + .../version-3.6.x/key-concepts/services.md | 79 ++ .../version-3.6.x/key-concepts/snis.md | 28 + .../key-concepts/ssl-certificates.md | 39 + .../key-concepts/stream-routes.md | 27 + .../version-3.6.x/key-concepts/upstreams.md | 60 + .../version-3.6.x/performance/aws-eks.md | 303 +++++ .../version-3.6.x/performance/benchmark.md | 142 +++ .../performance/performance-testing.md | 72 ++ .../version-3.6.x/reference/adc.md | 197 ++++ .../version-3.6.x/reference/alert-template.md | 70 ++ .../reference/build-api-endpoints.md | 43 + .../reference/configuration-adc.md | 99 ++ .../version-3.6.x/reference/configuration.md | 597 ++++++++++ .../version-3.6.x/reference/design-apis.md | 33 + .../version-3.6.x/reference/hardening.md | 59 + .../version-3.6.x/reference/openapi-adc.md | 83 ++ .../permission-policy-action-and-resource.md | 245 ++++ .../reference/permission-policy-example.md | 318 ++++++ .../version-3.6.x/release-notes.md | 893 +++++++++++++++ .../version-3.6.x-sidebars.json | 167 +++ 78 files changed, 14293 insertions(+) create mode 100644 enterprise_versioned_docs/version-3.6.x/api-consumption/consumer-restriction.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-consumption/manage-consumer-credentials.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-observability/alert.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-observability/logging.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-observability/monitoring.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-portal/developer-sso.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/api-authentication.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/aws-secrets-manager.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/block-ip.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/client-mtls.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/configure-mtls.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/hashicorp-vault.md create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/rate-limiting.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/api-version-control.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/configure-grpc.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/custom-plugin.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/design-custom-role-system.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/devops-adc.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/manage-services-in-multi-environments.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/manage-token.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/service-discovery.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/sso.md create mode 100644 enterprise_versioned_docs/version-3.6.x/best-practices/upstream-ha.md create mode 100644 enterprise_versioned_docs/version-3.6.x/deployment/ingress-controller.md create mode 100644 enterprise_versioned_docs/version-3.6.x/deployment/k8s-openshift.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-group.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-instance.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/audit-logging.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/canary-upstream.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/create-custom-role.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/deploy-resources-on-k8s.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/install-api7-ee.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/launch-your-first-api.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/license.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/proxy-l4-traffic.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/rbac.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/rollback-service.md create mode 100644 enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md create mode 100644 enterprise_versioned_docs/version-3.6.x/high-availability/data-plane-resilience.md create mode 100644 enterprise_versioned_docs/version-3.6.x/high-availability/high-availability-installation.md create mode 100644 enterprise_versioned_docs/version-3.6.x/high-availability/overview.md create mode 100644 enterprise_versioned_docs/version-3.6.x/high-availability/prepare-for-high-availability.md create mode 100644 enterprise_versioned_docs/version-3.6.x/introduction/api7-ee-architecture.md create mode 100644 enterprise_versioned_docs/version-3.6.x/introduction/what-is-api7-ee.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/api-portal.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/api-products.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/authentication.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/certificates.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/consumers.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/developers.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/gateway-groups.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/overview.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/plugins.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/roles-and-permission-policies.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/routes.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/secrets.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/services.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/snis.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/ssl-certificates.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/stream-routes.md create mode 100644 enterprise_versioned_docs/version-3.6.x/key-concepts/upstreams.md create mode 100644 enterprise_versioned_docs/version-3.6.x/performance/aws-eks.md create mode 100644 enterprise_versioned_docs/version-3.6.x/performance/benchmark.md create mode 100644 enterprise_versioned_docs/version-3.6.x/performance/performance-testing.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/adc.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/alert-template.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/build-api-endpoints.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/configuration-adc.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/configuration.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/design-apis.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/hardening.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/openapi-adc.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/permission-policy-action-and-resource.md create mode 100644 enterprise_versioned_docs/version-3.6.x/reference/permission-policy-example.md create mode 100644 enterprise_versioned_docs/version-3.6.x/release-notes.md create mode 100644 enterprise_versioned_sidebars/version-3.6.x-sidebars.json diff --git a/enterprise_versioned_docs/version-3.6.x/api-consumption/consumer-restriction.md b/enterprise_versioned_docs/version-3.6.x/api-consumption/consumer-restriction.md new file mode 100644 index 00000000..54ae02cf --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-consumption/consumer-restriction.md @@ -0,0 +1,211 @@ +--- +title: 基于黑白名单的访问控制 +slug: /api-consumption/consumer-restriction +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +有时候，你需要比身份验证插件提供的更精确的访问控制。例如，你可能希望保留可以访问 API 的[消费者](../key-concepts/consumers.md)白名单。现在，消费者必须发送经过身份验证的请求，并且在白名单上（而且不在黑名单上）才能访问 API。 + +:::note + +在实施基于消费者的访问控制之前，请考虑 [API 门户](../key-concepts/api-portal) 是否是更好的解决方案。 + +::: + +本教程将指导你通过 [Consumer Restriction](https://docs.api7.ai/hub/consumer-restriction) 插件创建消费者白名单来配置精确的访问控制。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 +3. [已有一个启用了身份验证的消费者](manage-consumer-credentials.md)。 + +## 通过消费者名称限制访问 + +当消费者发出经过身份验证的请求时，API7 网关会将消费者的名称传递给路由。因此，路由不需要直接访问消费者的凭据，这对用户更加友好。 + + + + + +1. 从侧边栏选择网关组的 **已发布服务**，然后选择要配置的服务，例如，版本为 `1.0.0` 的 `httpbin API`。 +2. 从侧边栏选择 **插件**。 +3. 搜索 `consumer-restriction` 插件。 +4. 点击 **新增插件**。 +5. 在对话框中，执行以下操作： + +* 如果你已按照前提条件教程操作，那么你应该已经拥有一个启用了 `key-auth` 插件的消费者 `Alice`。将以下配置添加到**JSON 编辑器**： + + ```json + { + "whitelist": [ + "Alice" + ] + } + ``` + + + +* 点击 **新增**。 + +6. 用同样的方法添加一个新的消费者 `Lisa` 并使用以下配置启用 `key-auth` 插件。 + + ```json + { + "key": "secret-key2" + } + ``` + + + + + +下面的配置启用了 `consumer-restriction` 插件并创建了一个新的消费者 `Lisa`： + +```yaml title="adc.yaml" +services: + - name: httpbin Service + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + plugins: + consumer-restriction: + _meta: + disable: false + whitelist: + - Alice + key-auth: + _meta: + disable: false + routes: + - uris: + - /ip + name: api-security-ip + methods: + - GET +consumers: + - username: Alice + plugins: + key-auth: + _meta: + disable: false + key: secret-key + - username: Lisa + plugins: + key-auth: + _meta: + disable: false + key: secret-key-2 +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + + + + + +创建一个 Kubernetes manifest 文件来配置另一个消费者 `lisa`： + +```yaml title="consumer2.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixConsumer +metadata: + name: lisa + # namespace: api7 # replace with your namespace +spec: + authParameter: + keyAuth: + value: + key: "secret-key2" +``` + +对于消费者限制，由于 ApisixService 自定义资源尚不可用，你可以在 ApisixRoute 上配置 `consumer-restriction` 插件： + +[//]: + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin-route + # namespace: api7 # replace with your namespace +spec: + http: + - name: httpbin-route + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + plugins: + - name: consumer-restriction + enable: true + config: + whitelist: + - alice +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f consumer2.yaml -f httpbin-route.yaml +``` + + + + + + +## 验证 + +以消费者 `Alice` 的身份向服务发起请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -H "apikey: secret-key" +``` + +你将看到请求成功，并收到 `200 OK` 响应，因为消费者 `Alice` 在白名单中。 + +现在，以新创建的消费者 Lisa 的身份向服务发起请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -H "apikey: secret-key2" +``` + +你将收到 `403 Forbidden` 响应，并附带以下请求正文，因为消费者 Lisa 未添加到白名单中： + +```text +{"message":"The consumer_name is forbidden."} +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [路由](../key-concepts/routes.md) + * [插件](../key-concepts/plugins.md) + * [消费者](../key-concepts/consumers.md) +* API 安全 + * [设置 API 身份验证](../api-security/api-authentication.md) +* API 消费 + * [管理消费者的访问凭证](../api-consumption/manage-consumer-credentials.md) diff --git a/enterprise_versioned_docs/version-3.6.x/api-consumption/manage-consumer-credentials.md b/enterprise_versioned_docs/version-3.6.x/api-consumption/manage-consumer-credentials.md new file mode 100644 index 00000000..4946e4e9 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-consumption/manage-consumer-credentials.md @@ -0,0 +1,229 @@ +--- +title: 管理消费者凭据 +slug: /api-consumption/manage-consumer-credentials +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +[消费者](../key-concepts/consumers)是指使用你的 API 的应用程序或开发者。在[服务](../key-concepts/services)上启用身份验证可以让你控制访问，要求消费者在访问 API 之前获得凭据。 + +在服务上启用的身份验证插件就像 API 上的锁，而消费者凭据则是解锁它们的钥匙。在 API7 企业版中，你需要一个唯一的用户名和至少一个凭据来设置消费者。 + +消费者可以使用多种不同类型的凭据，所有凭据在身份验证方面都被视为平等的。 + +:::note + +在实施基于消费者的凭据管理之前，请考虑 [开发者](../key-concepts/developers) 是否是更好的解决方案。 + +::: + +本教程将指导你创建消费者和配置身份验证凭据。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee)。 +2. [在网关组上运行 API](../getting-started/launch-your-first-api)。 + +## 配置 Key Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**+ 新增消费者**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `Alice`。 + * 点击**新增**。 +4. **凭据**选项卡下，点击**+ 新增 Key Authentication 凭据**。 +5. 在对话框中，执行以下操作： + * **名称**，输入 `primary-key`。 + * **Key**，选择**手动输入**，然后输入 `alice-primary-key`。 + * 如果你想选择**引用 Secret 提供商**，请参阅[引用 HashiCorp Vault 中的密钥](../api-security/hashicorp-vault) 或 [引用 AWS Secrets Manager 中的密钥](../api-security/aws-secrets-manager)。 + * 点击**新增**。 + +6. 再次尝试新增另一个名为 `backup-key` 的 Key Authentication 凭据，Key 为 `alice-backup-key`。所有凭据都是有效的，可以互换使用以进行 API 身份验证。 + +下面是一个交互式演示，提供了使用 API7 企业版配置 Key Authentication 凭据的实践介绍。 + + + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice + credentials: + - name: primary-key + type: key-auth + config: + key: alice-primary-key + - name: backup-key + type: key-auth + config: + key: alice-backup-key +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +暂不支持。 + + + + + +### 验证 + +有关说明，请参阅[为 API 启用 Key Authentication](../api-security/api-authentication#enable-key-authentication-for-apis)，并在服务级别启用 `Key Auth 插件`。 + +然后按照[验证 Key Authentication](../api-security/api-authentication#validate-key-authentication) 说明进行操作。 + +## 配置 Basic Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**新增消费者**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `Alice`。 + * 点击**新增**。 +4. **凭据**选项卡下，点击**Basic Authentication**选项卡，然后点击**新增 Basic Authentication 凭据**。 +5. 在对话框中，执行以下操作： + * **名称**，输入 `primary-basic`。 + * **用户名**，输入 `alice`。 + * **密码**，选择**手动输入**，然后输入 `alice-password`。 + * 如果你想选择**引用 Secret 提供商**，请参阅[引用 HashiCorp Vault 中的密钥](../api-security/hashicorp-vault) 或 [引用 AWS Secrets Manager 中的密钥](../api-security/aws-secrets-manager)。 + * 点击**新增**。 + +6. 再次尝试新增另一个名为 `backup-basic` 的 Basic Authentication 凭据，用户名为 `alice-backup`，密码为 `alice-backup-password`。所有凭据都是有效的，可以互换使用以进行 API 身份验证。 + + + + + +即将推出。 + + + + + +Ingress Controller 目前不支持凭据和匿名消费者。 + + + + + +### 验证 + +有关说明，请参阅[为 API 启用 Basic Authentication](../api-security/api-authentication#enable-basic-authentication-for-apis)，并在服务级别启用 `Basic Auth 插件`。 + +然后按照[验证 Basic Authentication](../api-security/api-authentication#validate-basic-authentication) 说明进行操作。 + +## 配置不同的身份验证凭据 + +虽然消费者可以拥有多个不同类型的凭据，但已发布服务中的每个路由都应该只配置一个身份验证插件。这允许消费者使用他们喜欢的身份验证方法访问多个路由。 + +下面是一个交互式演示，提供了使用 API7 企业版配置各种身份验证凭据的实践介绍。 + + + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**+ 新增消费者**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `John`。 + * 点击**新增**。 +4. **凭据**选项卡下，点击**新增 Key Authentication 凭据**。 +5. 在对话框中，执行以下操作： + * **名称**，输入 `key-auth`。 + * **密钥**，选择**手动输入**，然后输入 `john-key-auth`。 + * 点击**新增**。 + +6. **凭据**选项卡下，选择**Basic Authentication**，然后点击**新增 Basic Authentication 凭据**。 +7. 在对话框中，执行以下操作： + * **名称**，输入 `basic-auth`。 + * **用户名**，输入 `john`。 + * **密码**，选择**手动输入**，然后输入 `john-password`。 + * 点击**新增**。 + +8. **凭据**选项卡下，选择**JWT**，然后点击**新增 JWT 凭据**。 +9. 在对话框中，执行以下操作： + * **名称**，输入 `jwt-auth`。 + * **密钥**，输入 `john-jwt-key`。 + * **算法**，选择 `RS256`。 + * **公钥**，选择**手动输入**，然后输入你的公钥。 + * 点击**新增**。 + +10. **凭据**选项卡下，选择**HMAC 认证**，然后点击**新增 HMAC 认证凭据**。 +11. 在对话框中，执行以下操作： + +* **名称**，输入 `hmac-auth`。 +* **密钥 ID** ，输入 `john-key`。 +* **密钥**，选择**手动输入**，然后输入 `john-hmac-key`。 +* 点击**新增**。 + + + + + +暂不支持。 + + + + + +Ingress Controller 目前不支持凭据和匿名消费者。 + + + + + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services) + * [路由](../key-concepts/routes) + * [插件](../key-concepts/plugins) + * [消费者](../key-concepts/consumers) +* API 安全 + * [设置 API 身份验证](../api-security/api-authentication) +* API 使用 + * [应用基于列表的访问控制](./consumer-restriction) diff --git a/enterprise_versioned_docs/version-3.6.x/api-observability/alert.md b/enterprise_versioned_docs/version-3.6.x/api-observability/alert.md new file mode 100644 index 00000000..d56af26c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-observability/alert.md @@ -0,0 +1,444 @@ +--- +title: 网关告警通知 +slug: /api-observability/alert +--- + +异常流量模式或 API 网关使用错误可能表明存在问题或恶意攻击。通过为特定阈值和活动设置告警，你可以快速检测并深入了解可能的安全漏洞、滥用或异常使用。 + +本教程将指导你创建告警策略，以便在特定事件发生时接收邮件和 webhook 通知。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上运行 API](../getting-started/launch-your-first-api.md)。 +3. 获取通知系统的 webhook URL。 + +## 设置 SMTP 服务器 + +1. 从顶部导航栏中选择**组织**，然后选择**设置**。 +2. 点击**SMTP 服务器**选项卡。 +3. 点击**启用**。 +4. 在对话框中，执行以下操作： + * **SMTP 服务器地址**，输入你的 SMTP 服务器的地址。例如，`127.0.0.1`。 + * **用户名**和**密码**，输入连接到你的 SMTP 服务器的凭据。 + * **发件人姓名**，输入 `API7 企业版` 以在邮件中将此名称显示为发件人。 + * **发件人邮箱地址**，输入 `noreply@api7.ai`。这将用作实际的发件人地址。 + * 点击**启用**。 + +## 添加联系人 + +_联系人_ 定义了一组可由多个告警策略复用的邮件地址或 webhook URL。 + +### 添加邮件联系人 + +1. 从顶部导航栏中选择**组织**，然后选择**联系人**。 +2. 点击**新增联系人**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `应急小组邮件列表`。 + * **类型**，选择 `邮件`。 + * **邮件地址**，输入 `emergencyteamlist@api7.ai`。 + * 点击**新增**。 + +### 添加 Webhook 联系人 + +使用 [Slack 接收 webhook](https://api.slack.com/messaging/webhooks) 将来自 API7 企业版的消息发布到 Slack。 + +1. 从顶部导航栏中选择**组织**，然后选择**联系人**。 +2. 点击**新增联系人**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `Slack 通知`。 + * **类型**，选择 `Webhook`。 + * **URL**，输入 `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`。 + * 点击**新增**。 + +## 添加告警策略 + +有关更多告警邮件内容示例，请参阅[告警变量和模板](../reference/alert-template.md)。告警策略会在创建或更新后立即开始监控，首次检查会在指定的检查间隔后进行。 + +### 监控 SSL 证书到期 + +要主动监控即将过期的 SSL 证书并发出告警，可以配置一个每日告警任务以检查证书到期日期。如果证书即将到期（30 天内），请向应急小组发送邮件告警，并在 Slack 上发布通知。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `SSL 证书将过期`。 + * **告警等级**，选择 `高`。 + * **检查间隔**，输入 `1440` 分钟。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (AND)`。 + * **事件**，选择 `SSL 证书即将过期`。 + * **触发网关组**，选择 `全选`。 + * **规则**，填空 `SSL 证书将在 30 天内过期`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] [{{.Severity}}] SSL 证书到期警告`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}" + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设网关组 `生产网关组` 中的 SSL 证书将于 2024-12-31 过期。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：SSL 证书过期 + * 告警等级：高 + * 告警时间：5 分钟前 + * 触发网关组：生产网关组 + * 告警详情：Certificate will expire in 21 days. + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警][高] SSL 证书到期警告 +* 告警时间：2024 DEC 10 17:00:00，详情：Certificate will expire in 21 days. +``` + +4. 你将在 Slack 中收到一条消息： + +```text +Certificate will expire in 21 days. +``` + +### 监控控制面到数据面的 mTLS 证书到期 + +CA 证书支持控制面和数据面之间安全的 mTLS 通信，并在实例部署时激活，有 13 个月的有效期。 + +要主动监控即将过期的控制面 CA 证书并发出告警，请配置每日告警任务以检查 CA 证书到期日期。如果 CA 证书即将到期（30 天内），请向应急小组发送邮件告警，并在 Slack 上发布通知。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `控制面 CA 证书过期`。 + * **告警等级**，选择 `高`。 + * **检查间隔**，输入 `1440` 分钟。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (AND)`。 + * **事件**，选择 `控制面和数据面之间的 mTLS 证书将要过期`。 + * **触发网关组**，选择 `选择全部`。 + * **规则**，填空 `数据面和控制面之间的 mTLS 证书将在 30 天内过期`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] 控制面 CA 证书到期警告`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}" + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设网关组 `生产网关组` 中的网关实例 `gateway 123` 的控制面 CA 证书将于 2024-12-31 过期。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：控制面 CA 证书过期 + * 告警等级：高 + * 告警时间：5 分钟前 + * 触发网关组：生产网关组 + * 告警详情：CA Certificate of gateway instance: gateway 123 will expire in 21 days. + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警] 控制面 CA 证书到期警告 +* 告警时间：2024 DEC 10 17:00:00，详情：CA Certificate of gateway instance: gateway 123 will expire in 21 days. +``` + +4. 你将在 Slack 中收到一条消息： + +```text +CA Certificate of gateway instance: gateway 123 will expire in 21 days. +``` + +### 检测网关实例离线 + +如果网关实例（数据面节点）超过 2 小时未向控制面报告心跳, 并且此状态持续 7 天，则数据面节点将被自动删除，并标记为 `离线`。 + +配置每小时告警任务以检测并在出现问题时向应急小组发送邮件告警和 Slack 通知。然后，应该有人尝试恢复离线的网关实例。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `网关实例离线`。 + * **告警等级**，选择 `中`。 + * **检查间隔**，输入 `60` 分钟。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (AND)`。 + * **事件**，选择 `网关实例离线`。 + * **触发网关组**，选择 `选择全部`。 + * **规则**，填空 `网关组中的任何网关实例离线超过 1 小时`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] 网关实例离线警告`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}" + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设网关组 `生产网关组` 中的网关实例 `gateway 123` 在 2024-12-31 14:00:00 离线，网关组 `测试网关组` 中的网关实例 `gateway 456` 在 2024-12-31 13:00:00 离线。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：网关实例离线 + * 告警等级：高 + * 告警时间：5 分钟前 + * 触发网关组：生产网关组 + * 告警详情：Gateway instance: gateway 123 in the gateway group: 生产网关组 offline for 3 hours \n Gateway instance: gateway 456 in the gateway group: 测试网关组 offline for 4 hours + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警] 网关实例离线警告 +* 告警时间：2024 DEC 31 17:00:00，详情：Gateway instance: gateway 123 in the gateway group: production group offline for 3 hours +Gateway instance: gateway 456 in the gateway group: test group offline for 4 hours +``` + +4. 你将在 Slack 中收到一条消息： + +```text +Gateway instance: gateway 123 in the gateway group: 生产网关组 offline for 3 hours +Gateway instance: gateway 456 in the gateway group: 测试网关组 offline for 4 hours +``` + +### 检测 CPU 核数超出限制 + +如果所有网关组的 CPU 核使用量连续七天超过许可的 CPU 核心数限制，则资源添加或修改将受到限制。但是，现有的服务和路由将继续运行。 + +配置每小时告警任务以检测生产环境的所有网关组，并在出现问题时向应急小组发送邮件告警和 Slack 通知。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `CPU 核数超出限制`。 + * **告警等级**，选择 `高`。 + * **检查间隔**，输入 `60` 分钟。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (AND)`。 + * **事件**，选择 `CPU 核心数超出 License 限制`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] CPU 核数超出限制`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}" + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设你的 API7 企业版许可证限制为 100 个 CPU 核，并且从 2024-12-1 开始已连续 21 天超出此限制。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：CPU 核数超出限制 + * 告警等级：中 + * 告警时间：5 分钟前 + * 触发网关组：生产网关组 + * 告警详情：Total CPU usage for all gateway groups is 110c, exceeded allowed license CPU quota 100c. + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警] 网关实例离线警告 +* 告警时间：2024 DEC 31 17:00:00，详情：Total CPU usage for all gateway groups is 110c, exceeded allowed license CPU quota 100c. +``` + +4. 你将在 Slack 中收到一条消息： + +```text +Total CPU usage for all gateway groups is 110c, exceeded allowed license CPU quota 100c. +``` + +### 统计网关组中的健康网关实例数 + +如果网关组中健康网关实例的数量低于临界阈值，则表明可能会出现服务中断并影响流量处理。 +这种情况在 Kubernetes 部署中尤其重要，因为网关实例可能会遇到故障或意外缩减。 + +实施高频告警任务以检测并在出现问题时向应急小组发送邮件告警和 Slack 通知。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `生产网关组中没有足够的健康网关实例`。 + * **告警等级**，选择 `高`。 + * **检查间隔**，输入 `30` 分钟。 + * **触发网关组**，选择 `生产网关组`。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (AND)`。 + * **事件**，选择 `健康网关实例的数量`。 + * **规则**，填空 `网关组中的健康网关实例数少于 50`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] 生产网关组中没有足够的健康网关实例`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}." + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设你的网关组 `生产网关组` 至少需要 50 个健康的网关实例。但是，截至 2024 年 12 月 31 日 17:00:00，只有 40 个实例正在运行。这种严重的不足可能会导致服务降级和潜在的停机。需要立即关注以解决此问题。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：生产网关组中没有足够的健康网关实例 + * 告警等级：高 + * 告警时间：5 分钟前 + * 触发网关组：生产组 + * 告警详情：Number of healthy gateway instances in the gateway group: 生产网关组 is 40. + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警] 生产组中没有足够的健康网关实例 +* 告警时间：2024 DEC 31 17:00:00，详情：Number of healthy gateway instances in the gateway group: 生产网关组 is 40. +``` + +4. 你将在 Slack 中收到一条消息： + +```text +Number of healthy gateway instances in the gateway group: 生产网关组 is 40. +``` + +### 监控状态码 + +如果特定 API 响应状态码的数量超过阈值（例如，过多的 `500` 错误），则表明可能会出现服务中断并影响流量处理。 + +实施高频告警任务以检测并在出现问题时向应急小组发送邮件告警和 Slack 通知。 + +1. 从侧边栏选择**告警**，然后点击**策略**。 +2. 点击**新增告警策略**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `生产网关组中的 500 状态码过多`。 + * **告警等级**，选择 `高`。 + * **检查间隔**，输入 `30` 分钟。 + * **触发网关组**，选择 `标签匹配`，然后输入键/值 `环境类型: 生产`。 + * **触发条件**，执行以下操作： + * **条件类型**，选择 `满足下列所有条件 (OR)`。 + * **事件**，选择 `状态码 500 的数量`。 + * **规则**，填空 `网关组的所有已发布服务收到的状态码为 500 的请求数量已达到或超过 100 次在过去 60 分钟内`。 + * 点击**新增条件**。 + * **触发条件**，执行以下操作： + * **事件**，选择 `状态码 500 的比例`。 + * **规则**，填空 `网关组的所有已发布服务收到的状态码为 500 的请求比率已达到或超过 10% 在过去 60 分钟内`。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `邮件`。 + * **联系人**，选择 `应急小组邮件列表`。 + * **告警邮件主题**，输入 `[API7 告警] {{ .TriggerGatewayGroup }} 中的 500 状态码过多`。 + * **告警邮件内容**，输入 `告警时间：{{.AlertTime.Format "2024 Dec 31 17:00:00"}}，详情：{{.AlertDetail}}`。 + * 点击**新增**。 + * 点击**新增通知**。 + * 在对话框中，执行以下操作： + * **类型**，选择 `Webhook`。 + * **联系人**，选择 `Slack 通知`。 + * **告警消息**，输入 + + ```json + "text": "{{ .AlertDetail }}" + ``` + + * 点击**新增**。 + +5. 点击**新增**。 + +#### 验证 + +假设你的网关组 `VIP 网关组` 具有标签 `环境类型：生产`，在 2024 年 12 月 31 日 16:00 到 17:00 之间达到了 15% 的错误率，在 1000 个请求中，有 150 个响应为 500 错误。 + +并且网关组 `US 网关组` 具有标签 `环境类型：生产`，在 2024 年 12 月 31 日 16:00 到 17:00 之间达到了了 10% 的错误率，在 500 个请求中，有 50 个响应为 500 错误。 + +1. 从侧边栏选择**告警**，然后点击**历史**。 +2. 你应该会看到一个告警记录。点击**详情**： + * 告警策略：生产网关组中的 500 状态码过多 + * 告警等级：高 + * 告警时间：5 分钟前 + * 触发网关组：VIP 组 + * 告警详情：Number of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 150 times in the last 60 minutes.\n Ratio of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 15% in the last 60 minutes.\n Ratio of requests with status code 500 received by all published services of the gateway group: US 网关组 is 10% in the last 60 minutes. + +3. 发送的邮件将类似于： + +```text +* 主题：[API7 告警] [API7 告警] VIP 网关组、US 网关组组中的 500 状态码过多 +* 告警时间：2024 DEC 31 17:00:00，详情：Number of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 150 times in the last 60 minutes. +Ratio of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 15% in the last 60 minutes. +Ratio of requests with status code 500 received by all published services of the gateway group: US 网关组 is 10% in the last 60 minutes. +``` + +4. 你将在 Slack 中收到一条消息： + +```text +Number of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 150 times in the last 60 minutes. +Ratio of requests with status code 500 received by all published services of the gateway group: VIP 网关组 is 15% in the last 60 minutes. +Ratio of requests with status code 500 received by all published services of the gateway group: US 网关组 is 10% in the last 60 minutes. +``` diff --git a/enterprise_versioned_docs/version-3.6.x/api-observability/logging.md b/enterprise_versioned_docs/version-3.6.x/api-observability/logging.md new file mode 100644 index 00000000..41cb43be --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-observability/logging.md @@ -0,0 +1,121 @@ +--- +title: API 日志管理 +slug: /api-observability/logging +--- + +API7 企业版支持收集 API 的访问信息并记录为日志，如主机、客户端 IP 地址、请求时间戳等。这些信息有助于解决问题。API7 企业版提供了灵活的插件扩展系统和日志记录插件。例如： + +- 推送到 HTTP/TCP/UDP 日志服务器 +- SkyWalking +- Kafka +- RocketMQ +- Clickhouse +- Syslog +- 阿里云 SLS +- 谷歌云日志服务 +- Splunk HTTP Event Collector (HEC) +- 磁盘上的特定文件 +- Elasticsearch +- 腾讯云 CLS +- Grafana Loki + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 +3. 获取自己的 ClickHouse 数据库的主机地址。 + +## 配置 ClickHouse + +1. 在 Docker 中启动一个名为 `quickstart-clickhouse-server` 的 ClickHouse 实例，并使用默认数据库 `quickstart_db`、默认用户`quickstart-user` 和密码 `quickstart-pass`： + + ```bash + docker network create apisix-quickstart-net + + docker run -d \ + --name quickstart-clickhouse-server \ + --network=apisix-quickstart-net \ + -e CLICKHOUSE_DB=quickstart_db \ + -e CLICKHOUSE_USER=quickstart-user \ + -e CLICKHOUSE_PASSWORD=quickstart-pass \ + -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \ + --ulimit nofile=262144:262144 \ + clickhouse/clickhouse-server + ``` + +2. 使用 Docker 中的命令行工具 `clickhouse-client` 连接到 ClickHouse 实例： + + ```shell + docker exec -it quickstart-clickhouse-server clickhouse-client + ``` + +3. 在数据库 `quickstart_db` 中创建一个表 `test`，字段为 `String` 类型的 `host`、`client_ip`、`route_id`、`@timestamp`： + + ```sql + CREATE TABLE quickstart_db.test ( + `host` String, + `client_ip` String, + `route_id` String, + `@timestamp` String, + PRIMARY KEY(`@timestamp`) + ) ENGINE = MergeTree() + ``` + + 如果成功，你应该在输出中看到 `Ok`。 + +4. 输入`exit`命令，退出 Docker 命令行界面。 + +## 为所有服务开启日志记录 + +为了实现最佳监控和跟踪，强烈建议启用日志记录插件作为全局规则，以确保所有服务和路由都得到跟踪记录。 + +1. 从左侧导航栏中选择 **网关组**，然后选择 **测试网关组**。 +2. 从左侧导航栏中选择 **插件设置**。 +3. 选择 **插件全局规则** 页签，在 **插件** 字段中，搜索 `clickhouse-logger` 插件。 +4. 单击 **加号** 图标 (+)，弹出对话框。 +5. 应用以下配置： + + ```json + { + "log_format": { + "host": "$host", + "@timestamp": "$time_iso8601", + "client_ip": "$remote_addr" + }, + "user": "quickstart-user", + "password": "quickstart-pass", + "database": "quickstart_db", + "logtable": "test", + "endpoint_addrs": ["http://quickstart-clickhouse-server:8123"] + } + ``` + +6. 单击 **启用**。 + +## 验证 + +1. 向路由发送请求，生成访问日志条目： + + ```bash + curl -i "http://127.0.0.1:9080/pet/1" + ``` + +2. 使用 Docker 中的命令行工具 `clickhouse-client` 连接到 ClickHouse 实例： + + ```bash + docker exec -it 快速启动-clickhouse-server clickhouse-client + ``` + +3. 查询表`quickstart_db.test`中的所有记录： + + ```sql + SELECT * from quickstart_db.test + ``` + + 你应该看到类似于以下内容的访问记录： + + ```text + ┌─host───────────┬─client_ip───┬─route_id─────────────────────────────┬─@timestamp────────────────┐ + │ 127.0.0.1 │ 172.19.0.15 │ 6433300c-311b-4047-800e-579244d42aa7 │ 2023-09-01T09:24:16+00:00 │ + └────────────────┴─────────────┴──────────────────────────────────────┴───────────────────────────┘ + ``` diff --git a/enterprise_versioned_docs/version-3.6.x/api-observability/monitoring.md b/enterprise_versioned_docs/version-3.6.x/api-observability/monitoring.md new file mode 100644 index 00000000..049fc183 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-observability/monitoring.md @@ -0,0 +1,68 @@ +--- +title: API 指标监控 +slug: /api-observability/monitoring +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +API7 网关支持以最小的延迟向监控系统公开全面的指标，方便持续的监控和诊断。 + +API7 网关的监控和告警框架建立在 Prometheus 之上，这是一个广泛使用的系统监控和告警工具包。Prometheus 收集并存储多维时间序列数据，包括带有键值标签注释的指标。 + +本文档介绍了如何集成 `prometheus` 插件和监控系统，以便收集和可视化 HTTP 指标。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 + +## 监控所有服务 + +建议启用 `prometheus` 插件作为全局规则，确保所有服务和路线都得到一致的监控和跟踪。 + + + + +1. 从侧边栏选择网关组的**插件设置**。 +2. 选择**插件全局规则**选项卡，然后在**插件**字段中搜索 `prometheus` 插件。 +3. 点击**新增插件**。 +4. 在出现的对话框中，点击**新增**。 +5. 进行一些 API 调用以测试监控。 +6. 从侧边栏选择**监控**以查看指标。 + + + + + +要使用 ADC 启用监控，请创建以下配置： + +```yaml title="adc.yaml" +global_rules: + prometheus: + _meta: + disable: false +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。确保使用 `-f` 标志将所有配置文件传递给 `adc sync` 命令。 + +::: + +在 API7 企业版控制台中，从侧边栏选择 **监控** 以查看指标。 + + + diff --git a/enterprise_versioned_docs/version-3.6.x/api-portal/developer-sso.md b/enterprise_versioned_docs/version-3.6.x/api-portal/developer-sso.md new file mode 100644 index 00000000..ce60bd4f --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-portal/developer-sso.md @@ -0,0 +1,115 @@ +--- +title: 配置开发者门户 SSO 登录 +slug: /api-portal/developer-sso +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +API7 的开发者门户可以配置为支持单点登录 (SSO)，以便内部和合作伙伴开发者无缝登录，从而增强用户体验和安全性。 + +* 通常不建议对公共开发者使用 SSO，因为它可能要求他们在你的组织的身份提供者处创建帐户。 +* 开发者 SSO 配置独立于用于 API7 网关用户和 API 提供者的 API7 企业版 SSO。 + +## 与 SSO 集成 + +对于 API 提供者和开发者都属于同一组织的内部 API 门户，可以集成同一个身份提供者 (IDP) 以支持开发者 SSO 和 API7 企业版 SSO。 + + + + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 从侧边导航栏中选择 **登录设置**，然后选择 **登录选项** 选项卡。 +3. 点击 **新增登录选项**。 +4. 填写表单： + * **名称**：唯一的登录名称。该名称应可供用户识别。例如，如果你将名称配置为 `Employee Account`，你将在仪表板登录中看到 `使用 Employee Account 登录` 选项。 + * **提供者**：选择 `LDAP`。 + * **主机**：LDAP 主机域。例如 `ldap.example.com`。 + * **端口**：例如 `1563`。 + * **基本识别名**：例如 `oc=users,dc=org,dc=example`。 + * **绑定识别名**：用于对用户执行 LDAP 搜索的 LDAP 绑定识别名 (DN)。此 LDAP 绑定 DN 应具有搜索要进行身份验证的用户的权限。例如 `cn=admin,dc=org,dc=example`。 + * **绑定密码**：用于向 LDAP 服务器进行身份验证的 LDAP 绑定密码。 + * **标识符**：用于标识 LDAP 用户的属性。例如 `cn`。 + * **属性映射**：将 API7 内部字段映射到相关的 LDAP 属性，以无缝集成和同步数据。 +5. 点击 **新增**。 + + + + + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 从侧边导航栏中选择 **登录设置**，然后选择 **登录选项** 选项卡。 +3. 点击 **新增登录选项**。 +4. 填写表单： + * **名称**：唯一的登录名称。该名称应可供用户识别。例如，如果你将名称配置为 `Employee Account`，你将在仪表板登录中看到 `使用 Employee Account 登录` 选项。 + * **提供者**：选择 `OIDC`。 + * **颁发者**：OpenID connect 提供者的标识符。例如 `https://accounts.example.com`。 + * **客户端 ID**：你的应用程序的唯一标识符，由 OIDC 提供者分配。例如 `API7`。 + * **客户端密钥**：用于身份验证的密钥，由 OIDC 提供者分配。 + * **请求范围**：访问令牌通常具有不同的范围，这会限制它们的使用。例如 `profile,email`。 + * **根 URL**：用于访问 API7 以生成回调 URL 的 URL。例如 `https://auth.example.com/oidc`。 + * **SSL 验证**：默认值为开启。 +5. 点击 **新增**。 + + + + + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 从侧边导航栏中选择 **登录设置**，然后选择 **登录选项** 选项卡。 +3. 点击 **新增登录选项**。 +4. 填写表单： + * **名称**：唯一的登录名称。该名称应可供用户识别。例如，如果你将名称配置为 `Employee Account`，你将在仪表板登录中看到 `使用 Employee Account 登录` 选项。 + * **提供者**：选择 `SAML`。 + * **身份提供者元数据 URL**：用于获取有关身份提供者信息的 URL，例如其公钥、支持的 SAML 版本、签名算法等。例如 `https://idp.example.com/metadata`。 + * **服务提供者根 URL**：从身份提供者 (IdP) 请求身份验证和授权的实体。例如 `https://sp.example.com`。 + * **实体 ID**：服务提供者 (SP) 或身份提供者 (IdP) 实体的唯一标识符。它通常用作 SAML 联合中实体的全局唯一标识符。例如 `https://sp.example.com/saml/metadata`。 +5. 点击 **新增**。 + + + + +## 从 IdP 同步开发者数据 + +SCIM（跨域身份管理系统）是一种协议，可用于将用户和组信息从原始身份提供者 (IdP) 同步到 API7 企业版。这可以消除在多个系统中手动管理开发者和组信息的需要，从而节省时间并降低出错的风险。 + +使用 SCIM 配置，每当在你的 IdP 中注册或删除新用户时，API7 企业版都会自动同步开发者数据。 + +:::note +当开发者 SSO 和 API7 企业版 SSO 集成同一个身份提供者 (IDP) 时，请确保为每个 SSO 定义单独的 SCIM 配置。 +::: + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 从侧边导航栏中选择 **登录设置**，然后选择 **SCIM** 选项卡。 +3. 点击 **启用**。 +4. 复制 `API7 SCIM 端点 URL` 和 `SCIM 令牌`。 +5. 配置你的 IdP（如果它支持 SCIM）： + * 登录到你的 IdP 管理控制台。 + * 找到 SCIM 配置设置（这些设置可能因你的 IdP 而异）。 + * 将复制的 API7 SCIM 端点 URL 和 SCIM 令牌粘贴到相应的字段中。 + * 保存你的配置更改并在你的 IdP 端配置它们（确保你的 IdP 支持 SCIM 协议）。 + +### 删除开发者登录选项 + +:::warning + +删除登录选项将导致删除与其关联的所有开发者。 + +::: + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 从侧边导航栏中选择 **登录设置**，然后选择 **登录选项** 选项卡。 +3. 点击目标登录选项的 **删除**。 +4. 再次确认。 + +## 相关阅读 + +* 核心概念 + * [开发者](../key-concepts/developers) diff --git a/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md b/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md new file mode 100644 index 00000000..277a3514 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md @@ -0,0 +1,120 @@ +--- +title: 服务产品化 +slug: /api-portal/productize-services +--- + +创建和管理 [API 产品](../key-concepts/api-products.md) 以将你发布的服务产品化。每个 API 产品至少包含一个带有 OpenAPI 规范的已发布服务。 + +通过已发布的 API7 网关服务创建 API 产品可以简化开发工作流程。对已发布服务的更改会自动反映在关联的 API 产品中，无需手动更新，从而节省大量时间和精力。开发者可以专注于 API 使用，而无需关心底层服务配置或插件详细信息。 + +本教程演示如何为内部开发者创建 API 产品，并概述订阅流程。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee)。 +2. 激活启用了 API7 门户的许可证。 +3. [拥有一个正在运行的已发布服务](../getting-started/launch-your-first-api)。 + +## 添加 OpenAPI 规范 + +1. 从侧边导航栏中选择网关组的 **已发布服务**，然后点击要修改的服务，例如无版本的 `httpbin` 服务。 +2. 在已发布服务下，从侧边导航栏中选择 **OpenAPI 规范**。 +3. 点击 **上传 OpenAPI 规范**。 +4. 填写表单： + * 使用以下 OpenAPI 示例： + + ```yaml title="httpbin.yaml" + openapi: 3.0.0 + info: + title: HTTPBin + description: A simple HTTP request and response service. + version: 1.0.0 + servers: + - url: https://httpbin.org + + paths: + /ip: + get: + summary: Returns GET request information + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/Get' + + components: + schemas: + Get: + type: object + properties: + args: + type: object + headers: + type: object + origin: + type: string + ``` + +5. 点击 **保存**。 +6. 为避免身份验证冲突，请勿在已发布的服务中启用任何身份验证插件。API 产品配置将处理身份验证。 + +:::note + +请确保 OpenAPI 规范与你发布的服务匹配： + +* OpenAPI 规范中的 `Servers` 字段对应于已发布服务中的 `Hosts` 字段。 +* OpenAPI 规范中定义的每个 `Path` 必须与路由中的特定 `path` 和 `method` 组合匹配。 + +::: + +## 添加 API 产品 + +1. 使用导航栏左上角的按钮切换到 API7 门户。 +2. 点击 **新增 API 产品**，然后选择 **从 API7 网关创建**。 +3. 填写表单： + * **名称** 输入 `httpbin`。 + * **认证方式** 选择 `Key Authentication`。 + * 关闭 **订阅自动审批** 开关。 + * **API Hub 列表可见性** 选择 `仅对登录的开发者可见`。 + * 打开 **未订阅的开发者可以查看 API 详情** 开关。 + * 点击 **添加关联的网关服务**。 + * 在对话框中，执行以下操作： + * **网关组** 选择你的目标网关组。例如 `default`。 + * **已发布服务** 选择你的目标服务。例如 `httpbin`。 + * 点击 **新增**。 +4. 点击 **新增**。 +5. 默认情况下，新创建的 API 产品处于 `未发布` 状态，并且在开发者门户上不可见。点击顶部的 **操作** 按钮，然后选择 **发布**。 +6. 点击 **确认**。 + +## 开发者请求订阅 + +1. 使用开发者帐户登录开发者门户。 +2. 从顶部导航栏中选择 **API Hub**。 +3. 选择 `httpbin`。 +4. 浏览 API 详细信息以确保它们满足特定需求。 +5. 点击 **立即订阅**。 +6. 等待批准。 + +## 提供者审批同意 + +1. 从顶部导航栏中选择 **组织**，然后选择 **审批**。 +2. 点击特定请求的 **接受**。 + +## 开发者验证 API + +1. 使用开发者帐户登录开发者门户。 +2. 从顶部导航栏中选择 **API Hub**。 +3. 选择 `httpbin`。 +4. 点击 **Test Request**。 +5. 预先选择了 **Auth Type**，并自动填写 API 密钥，从开发者的凭据中复制。 +6. 点击 **Send**。 +7. 接收 `200` 响应。 + +## 相关阅读 + +* 核心概念 + * [API 产品](../key-concepts/api-products) + * [开发者](../key-concepts/developers) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/api-authentication.md b/enterprise_versioned_docs/version-3.6.x/api-security/api-authentication.md new file mode 100644 index 00000000..fff4c034 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/api-authentication.md @@ -0,0 +1,1009 @@ +--- +title: 设置 API 身份认证 +slug: /api-security/api-authentication +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +为了安全起见，你应该只允许经过身份认证和授权的[消费者](../key-concepts/consumers)访问你的 API。API7 网关提供了多种插件来启用身份认证和授权。 + +在服务上启用的身份认证插件就像给 API 上的锁，而消费者凭据则是解锁它们的钥匙。在 API7 网关中，你需要一个唯一的用户名和至少一个认证凭据来设置消费者。 + +消费者可以使用多种不同类型的认证凭据，所有认证凭据在身份认证方面都被视为平等的。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee)。 +2. [在网关组上运行 API](../getting-started/launch-your-first-api)。 + +:::note + +避免在同一服务/路由上配置多个身份认证插件，以防止冲突。 + +::: + +## 为 API 启用 Key Authentication + +### 针对服务 + +要在服务中的所有路由上使用 Key Authentication，请在服务上启用 `Key Auth 插件`。 + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 从侧边栏选择**插件**，然后点击**启用插件**。 +3. 搜索 `key-auth` 插件，然后点击**启用**。 +4. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新服务配置以使用 Key Authentication： + +```yaml title="adc-service.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + plugins: + key-auth: + _meta: + disable: false + routes: + - uris: + - /ip + name: get-ip + methods: + - GET +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml -f adc-service.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +暂不支持。 + + + + + +### 针对单个路由 + + + + + +要对特定路由使用 Key Authentication，请在路由上启用 `Key Auth 插件`，而不是在服务上启用。 + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. **插件**，点击**启用插件**。 +5. 搜索 `key-auth` 插件，然后点击**启用**。 +6. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新路由配置以使用Key Authentication： + +```yaml title="adc-route.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + key-auth: + _meta: + disable: false +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc-consumer.yaml -f adc-route.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +创建一个启用了 Key Authentication 的路由的 Kubernetes mainfest 文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + authentication: + enable: true + type: keyAuth +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +### 验证 Key Authentication + +按照[配置 Key Authentication 凭据](../api-consumption/manage-consumer-credentials#configure-key-authentication-credentials)创建具有 Key Authentication 凭据的消费者。 + +然后按照以下步骤验证 Key Authentication。 + +1. 发送不带 `apikey` 请求头的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" +``` + +由于未提供密钥，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Missing API key found in request"} +``` + +2. 在 `apikey` 请求头中发送带有错误密钥的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -H "apikey: wrongkey" +``` + +由于密钥错误，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Invalid API key in request"} +``` + +3. 在 `apikey` 请求头中发送带有正确密钥的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -H "apikey: alice-primary-key" +``` + +使用正确的密钥发送请求，你将收到一个 `HTTP/1.1 200 OK` 响应。 + +## 为 API 启用Basic Authentication + +### 针对服务 + +要在服务中的所有路由上使用Basic Authentication，请在服务上启用 `Basic Auth 插件`。 + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 从侧边栏选择**插件**，然后点击**启用插件**。 +3. 搜索 `basic-auth` 插件，然后点击**启用**。 +4. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新服务配置以使用 Basic Authentication： + +```yaml title="adc-service.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + plugins: + basic-auth: + _meta: + disable: false + routes: + - uris: + - /ip + name: get-ip + methods: + - GET +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml -f adc-service.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +暂不支持。 + + + + + +### 针对单个路由 + + + + + +要对特定路由使用 Basic Authentication，请在路由上启用 `Basic Auth 插件`，而不是在服务上启用。 + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. **插件**，点击**启用插件**。 +5. 搜索 `basic-auth` 插件，然后点击**启用**。 +6. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新路由配置- name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + basic-auth: + _meta: + disable: false +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc-consumer.yaml -f adc-route.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +创建一个启用了 Basic Authentication 的路由的 Kubernetes mainfest 文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + authentication: + enable: true + type: basicAuth +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +### 验证 Basic Authentication + +按照[配置 Basic Authentication 凭据](../api-consumption/manage-consumer-credentials#configure-basic-authentication-credentials)创建具有 Basic Authentication 凭据的消费者。 + +请按照以下步骤验证 Basic Authentication。 + +1. 发送不带 Basic Authentication 凭据的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" +``` + +由于未提供凭据，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Missing authorization in request"} +``` + +2. 发送带有无效 Basic Authentication凭 据（用户名密码不匹配，或用户名不存在）的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -u alice:wrong-password +``` + +由于密码与任何消费者凭据都不匹配，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Invalid user authorization"} +``` + +3. 发送带有正确 Basic Authentication 凭据的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -u alice:alice-password +``` + +使用正确的凭据发送请求，你将收到一个 `HTTP/1.1 200 OK` 响应。 + +## 为 API 启用 JWT 认证 + +### 针对服务 + +要在服务中的所有路由上使用 JWT 认证，请在服务上启用 `JWT Auth 插件`。 + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 从侧边栏选择**插件**，然后点击**启用插件**。 +3. 搜索 `jwt-auth` 插件，然后点击**启用**。 +4. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新服务配置以使用 Basic Authentication： + +```yaml title- name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + plugins: + jwt-auth: + _meta: + disable: false + routes: + - uris: + - /ip + name: get-ip + methods: + - GET +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml -f adc-service.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +暂不支持。 + + + + + +### 针对单个路由 + + + + + +要对特定路由使用 JWT 认证，请在路由上启用 `JWT Auth 插件`，而不是在服务上启用。 + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. **插件**，点击**启用插件**。 +5. 搜索 `jwt-auth` 插件，然后点击**启用**。 +6. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新路由配置以使用 JWT 认证： + +```yaml title="adc-route.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + jwt-auth: + _meta: + disable: false +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc-consumer.yaml -f adc-route.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +创建一个启用了 JWT 认证的路由的 Kubernetes mainfest文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + authentication: + enable: true + type: jwtAuth +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +### 暴露 JWT 签名端点 + +这是在 API7 企业版中暴露 JWT 签名端点的准备步骤。如果你使用的是对称算法（例如 HS256（默认）或 HS512），其中 API7 企业版既是 JWT 签发者又是验证者，则此步骤是强制性的。如果你使用的是非对称算法（例如 RS256 或 ES256），则此步骤是可选的，因为签发者和验证者可以是不同的两方。 + +`jwt-auth 插件`会在 `/apisix/plugin/jwt/sign` 创建一个内部端点来签署 JWT。使用 `Public API 插件` 暴露该端点： + +1. 添加一个名为 `jwt-auth-api` 的已发布服务，以及一个名称为 `jwt-auth-api` 且路径为 `/api7/plugin/jwt/sign` 的路由。 +2. 从侧边栏选择**插件**，然后点击**启用插件**。 +3. 搜索 `public-api` 插件，然后点击**启用**。 +4. 在对话框中执行以下操作： + * 将一个空配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + +### 验证 JWT 认证 + +按照[配置 JWT 认证凭据](../api-consumption/manage-consumer-credentials#configure-varied-authentication-credentials)创建具有 JWT 凭据的消费者。 + +请按照以下步骤验证 JWT 认证。 + +1. 发送不带凭据的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" +``` + +由于未提供凭据，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Missing authorization in request"} +``` + +2. 使用消费者 JWT 凭据中的 `key` 获取 JWT 令牌： + +```bash +jwt_token=$(curl -s "http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=john-jwt-key") && echo $jwt_token +``` + +3. 在请求头中携带 `jwt_token` 向你的 API 发送请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" -H "Authorization: ${jwt_token}" +``` + +使用正确的凭据发送请求，你将收到一个 `HTTP/1.1 200 OK` 响应。 + +30 秒后，令牌应该会过期。使用相同的令牌发送请求以进行验证，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"failed to verify jwt"} +``` + +## 为 API 启用 HMAC 认证 + +### 针对服务 + +要在服务中的所有路由上使用 HMAC 认证，请在服务上启用 `HMAC Auth 插件`。 + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 从侧边栏选择**插件**，然后点击**启用插件**。 +3. 搜索 `hmac-auth` 插件，然后点击**启用**。 +4. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新服务配置以使用 HMAC Authentication： + +```yaml title="adc-service.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + plugins: + jwt-auth: + _meta: + disable: false + routes: + - uris: + - /ip + name: get-ip + methods: + - GET +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml -f adc-service.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +暂不支持。 + + + + + +### 针对单个路由 + + + + + +要对特定路由使用 HMAC 认证，请在路由上启用 `HMAC Auth 插件`，而不是在服务上启用。 + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. **插件**，点击**启用插件**。 +5. 搜索 `hmac-auth` 插件，然后点击**启用**。 +6. 在对话框中执行以下操作： + * 将以下配置添加到**JSON 编辑器**： + + ```json + { + } + ``` + + * 点击**启用**。 + + + + + +更新路由配置以使用 HMAC 认证： + +```yaml title="adc-route.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + jwt-auth: + _meta: + disable: false +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc-consumer.yaml -f adc-route.yaml +``` + +:::note + +ADC 使用配置文件作为单一事实来源。因此，请确保将消费者和服务配置文件都传递给 `adc sync` 命令，以使两种配置都生效。 + +::: + + + + + +创建一个启用了 HMAC 认证的路由的 Kubernetes mainfest文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + authentication: + enable: true + type: hmacAuth +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +### 验证 HMAC 认证 + +按照[配置 HMAC 认证凭据](../api-consumption/manage-consumer-credentials#configure-varied-authentication-credentials)创建具有 HMAC 凭据的消费者。 + +请按照以下步骤验证 HMAC 认证。 + +1. 生成签名 + +你可以使用以下 Python 代码段或你选择的其他堆栈： + +```python title="hmac-sig-header-gen.py" +import hmac +import hashlib +import base64 +from datetime import datetime, timezone +key_id = "john-key" # 密钥 ID +secret_key = b"john-hmac-key" # 密钥 +request_method = "GET" # HTTP 方法 +request_path = "/headers" # 路由 URI +algorithm= "hmac-sha256" # 可以使用 allowed_algorithms 中的其他算法 +# 获取 GMT 当前日期时间 +# 注意：签名将在时钟偏差（默认 300 秒）后失效 +# 你可以在签名失效后重新生成签名，或者增加时钟偏差以延长有效期，但建议在安全边界内 +gmt_time = datetime.now(timezone.utc).strftime('%a, %d %b %Y %H:%M:%S GMT') +# 构造签名字符串（有序） +# 日期和任何后续的自定义请求头应小写，并用单个空格字符分隔，即 `:` +# [https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12#section-2.1.6](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12#section-2.1.6) +signing_string = ( + f"{key_id}\n" + f"{request_method} {request_path}\n" + f"date: {gmt_time}\n" +) + +# 创建签名 +signature = hmac.new(secret_key, signing_string.encode('utf-8'), hashlib.sha256).digest() +signature_base64 = base64.b64encode(signature).decode('utf-8') + +# 构造请求请求头 +headers = { + "Date": gmt_time, + "Authorization": ( + f'Signature keyId="{key_id}",algorithm="{algorithm}",' + f'headers="@request-target date",' + f'signature="{signature_base64}"' + ) +} + +# 打印请求头 +print(headers) +``` + +运行脚本： + +```shell +python3 hmac-sig-header-gen.py +``` + +2. 发送不带请求头的请求： + +```bash +curl -i "http://127.0.0.1:9080/ip" +``` + +由于未提供认证凭据，你将收到一个 `HTTP/1.1 401 Unauthorized` 响应，其请求正文如下： + +```text +{"message":"Missing authorization in request"} +``` + +3. 使用请求头向你的 API 发送请求： + +```bash +curl -X GET "http://127.0.0.1:9080/ip" \ + -H "Date: Fri, 06 Sep 2024 06:41:29 GMT" \ + -H 'Authorization: Signature keyId="alice-keyid",algorithm="hmac-sha256",headers="@request-target date",signature="wWfKQvPDr0wHQ4IHdluB4IzeNZcj0bGJs2wvoCOT5rM="' +``` + +因为使用了正确的凭据发送请求，你将收到一个类似于以下内容的 `HTTP/1.1 200 OK` 响应： + +```json +{ + "headers":{ + "Accept": "*/*", + "Authorization": "Signature keyId=\"john-key\",aigorithm=\'hmac-sha256\",headers=\"@reques + t-target date\", signature=\'HtQm1m8kGvnVlztZ59)XokweovFqQN04Ui6P6NfzjRr4=\'" + "Date": "Tue, 24 Sep 2024 10:28:41 GMT", + "Host": "127.0.0.1", + "User-Agent":"curl/8.7.1", + "X-Amzn-Trace-Id": "Root=1-66f29481-7355340a05778cbb21e9b25a", + "X-Consumer-Username": "John", + "X-Credential-Identifier": "4130bb4a-0fdc-461d-be8d-2bba8a1e36dc", + "X-Forwarded-Host": "127.0.0.1" +} +} +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services) + * [路由](../key-concepts/routes) + * [插件](../key-concepts/plugins) +* API 消费 + * [管理消费者凭据](../api-consumption/manage-consumer-credentials) + * [应用基于黑白名单的访问控制](../api-consumption/consumer-restriction) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/aws-secrets-manager.md b/enterprise_versioned_docs/version-3.6.x/api-security/aws-secrets-manager.md new file mode 100644 index 00000000..602b416c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/aws-secrets-manager.md @@ -0,0 +1,474 @@ +--- +title: 引用 AWS Secrets Manager 中的密钥 +slug: /api-security/aws-secrets-manager +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) 是一项完全托管的服务，你可以将其与 API7 企业版集成，以安全地存储、管理和检索敏感信息，例如 API 密钥、密码和其他类型的凭据。它允许自动轮换密钥，从而降低凭据随时间推移而暴露的风险。 + +本教程演示了如何将 API7 企业版与 AWS Secrets Manager 集成，使你能够安全地存储和引用消费者凭据和插件配置。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. 在你的网关组中[至少有一个网关实例](../getting-started/add-gateway-instance.md)。 +3. 拥有一个 [AWS 账户](https://aws.amazon.com)，以访问 IAM 和 Secrets Manager 模块。 + +## 获取 IAM 访问密钥 ID 和 Secret 访问密钥 + +获取 [IAM 用户访问密钥和 Secret 访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)，这些密钥将在下一步中配置到 API7 企业版中以访问 AWS Secrets Manager。 + +:::note + +请确保相应的权限已正确分配给用户，从而避免因权限不足导致验证失败的情况。 + +::: + +## 在网关组中新增 Secret 提供商 + + + + + +1. 从侧边栏选择网关组的**Secret 提供商**，然后点击**新增 Secret 提供商**。 +2. 在对话框中，执行以下操作： + * **Secret 提供商 ID** ，输入 `my-secrets-manager`。 + * **Secret 管理服务**，选择 `AWS Secrets Manager`。 + * **区域**，选择你的 AWS Secrets Manager 服务所在的区域。例如，`us-east-1`。 + * 使用[上一步](#obtain-iam-access-key-id-and-secret-access-key)中获取的访问密钥和秘密访问密钥填写**访问密钥 ID** 和**Secret 访问密钥**字段。 + * 点击**新增**。 + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +## 引用密钥以创建消费者凭据 + +消费者凭据中的以下敏感字段可以存储在外部Secret 管理服务（HashiCorp Vault、AWS Secrets Manager 等）中，并在 API7 企业版中引用： + +* Key Authentication凭据中的 `key` +* Basic Authentication凭据中的 `password` +* JWT 认证凭据中的 `secret`、`public key` +* HMAC 认证凭据中的 `secret_key` + +### 新增消费者 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**新增消费者**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `Alice`。 + * 点击**新增**。 + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +暂不支持。 + + + + + +### 在 AWS Secrets Manager 中创建密钥 + +在本节中，你将创建一个密钥来存储用户 `alice` 的消费者凭据。 + +1. 在控制台中导航到 AWS Secrets Manager 并创建一个密钥。选择 **Other type of secret** 作为密钥类型，并在键值对中输入密钥名称 `alice-key-auth` 和值 `alice-key`。 +2. 在下一步中，将密钥名称配置为 `alice-credentials`，并可选择新增描述。 +3. 点击下一步查看其余信息并完成密钥创建。你应该会在 AWS Secrets Manager 中看到创建好的密钥。 +4. 重复创建步骤，使用以下键/值对创建其他消费者凭据： + +* Basic Authentication 凭据： `password:alice-password`。 +* JWT 认证凭据： `secret:alice-secret`。 +* HMAC 认证凭据： `secret-key:alice-secret-key`。 + +### 新增 Key Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**新增 Key Authentication 凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-key`。 + * **Key**，选择**从 Secret 提供商引用**，然后输入 `$secret://aws/my-secrets-manager/alice-credentias/alice-key-auth`。 + * 点击**新增**。 + +:::note + +所有密钥引用都以 `$secret://` 开头。`aws` 是 **Secret 提供商**，`my-secrets-manager` 是**Secret 提供商 ID**，`alice-credentials` 是在 AWS Secrets Manager 控制台上 **Secret** 的名称，`alice-key-auth` 是在 AWS Secrets Manager 控制台中 **Key** 的名称。 + +::: + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice + credentials: + - name: primary-key + type: key-auth + config: + key: `$secret://aws/my-secrets-manager/alice-credentias/alice-key-auth` +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +暂不支持。 + + + + + +### 新增 Basic Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**Basic Authentication**选项卡，然后点击**新增Basic Authentication凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-basic`。 + * **用户名**，输入 `alice`。 + * **密码**，选择**从Secret 提供商引用**，然后输入 `$secret://aws/my-secrets-manager/alice-credentias/password`。 + * 点击**新增**。 + +:::note + +所有密钥引用都以 `$secret://` 开头。`aws` 是**Secret 管理服务**，`my-secrets-manager` 是**Secret 提供商 ID**。 + +::: + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice + credentials: + - name: primary-basic + type: basic-auth + config: + username: alice + password: $secret://aws/my-secrets-manager/alice-credentias/password` +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +尚不支持。 + + + + + +### 新增 JWT 认证凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**JWT**选项卡，然后点击**新增 JWT 凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-jwt`。 + * **Key**，输入 `alice-key`。 + * **算法**，选择 `HS256`。 + * **Secret**，选择**从Secret 提供商引用**，然后输入 `$secret://aws/my-secrets-manager/alice-credentias/secret`。 + * 点击**新增**。 + +:::note + +所有密钥引用都以 `$secret://` 开头。`aws` 是 Secret 提供商的**Secret 管理服务**，`my-secrets-manager` 是**Secret 提供商 ID**。 + +::: + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice + credentials: + - name: primary-jwt + type: jwt-auth + config: + key: alice-key + algorithm: HS256 + secret: `$secret://aws/my-secrets-manager/alice-credentias/secret` +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +尚不支持。 + + + + + +### 新增 HMAC 认证凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**HMAC 认证**选项卡，然后点击**新增 HMAC 认证凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-hmac`。 + * **Key ID** ，输入 `alice-keyid`。 + * **Secret Key**，选择**从 Secret 提供商引用**，然后输入 `$secret://aws/my-secrets-manager/alice-credentias/secret-key`。 + * 点击**新增**。 + +:::note + +所有密钥引用都以 `$secret://` 开头。`aws` 是Secret 提供商的**Secret 管理服务**，`my-secrets-manager` 是**Secret 提供商 ID**。 + +::: + + + + + +```yaml title="adc-consumer.yaml" +consumers: + - username: Alice + credentials: + - name: primary-hmac + type: key-auth + config: + keyid: alice-keyid + secret_key: `$secret://aws/my-secrets-manager/alice-credentias/secret-key` +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc-consumer.yaml +``` + + + + + +尚不支持。 + + + + + +### 验证 + +有关说明，请参阅[为 API 启用 Key Authentication](../api-security/api-authentication#enable-key-authentication-for-apis)，并在服务级别启用 `Key Auth 插件`。 + +发送请求验证配置了有效凭证的路由： + +```shell +curl -i "http://127.0.0.1:9080/ip" -H 'apikey: alice-key' +``` + +你应该收到 `HTTP/1.1 200 OK` 的响应。 + +:::note + +`alice-key` 是你在 AWS Secrets Manager 中创建的键/值对中的**值**，而不是健的名称。 + +::: + +* Basic-auth 凭证，请使用：password: alice-password 进行验证。 +* JWT-auth 凭证，请使用：secret: alice-secret 进行验证。 +* HMAC-auth 凭证，请使用：secret-key: alice-secret-key 进行验证。 + +## 引用密钥以启用插件 + +插件配置中的以下敏感字段可以存储在外部 Secret 管理服务（HashiCorp Vault、AWS Secrets Manager 等）中，并在 API7 企业版中引用： + +|插件|字段| +|:---|:---| +|Limit Count|`redis_username`、`redis_password`| +|[Authz-Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/)|`client_id`、`client_secret`| +|[Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/)|`appid`| +|[LDAP 认证](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/)|`user_dn`| + +本节以配置 `limit-count 插件` 为例进行演示。 + +### 创建密钥 + +在你的 AWS Secrets Manager 中，使用键/值对 `username:api7` 和 `password:redis-api7` 在密钥名称 `redis` 下创建密钥。 + +### 配置 Limit Count 插件 + +有关在何处以及如何启用 `limit-count 插件`，请参阅 [API 限流限速](../api-security/rate-limiting.md)。 + + + + + +将以下配置新增到**JSON 编辑器**： + +```json +{ + "count": 3, + "time_window": 60, + "key_type": "var", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "key": "remote_addr", + "policy": "redis", + "redis_host": "127.0.0.1", + "redis_port": 6379, + "redis_username": "$secret://aws/my-secrets-manager/redis/username", + "redis_password": "$secret://aws/my-secrets-manager/redis/password", + "redis_database": 1, + "redis_timeout": 1001, + "allow_degradation": false, + "show_limit_quota_header": true +} +``` + +:::note + +所有密钥引用都以 `$secret://` 开头。`aws` 是 Secret 提供商的**Secret 管理服务**，`my-secrets-manager` 是**Secret 提供商 ID**。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +## 相关阅读 + +* 核心概念 + * [密钥](../key-concepts/secrets.md) + * [插件](../key-concepts/plugins.md) + * [消费者](../key-concepts/consumers.md) +* API 使用 + * [管理消费者凭据](../api-consumption/manage-consumer-credentials.md) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/block-ip.md b/enterprise_versioned_docs/version-3.6.x/api-security/block-ip.md new file mode 100644 index 00000000..9498065d --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/block-ip.md @@ -0,0 +1,157 @@ +--- +title: 屏蔽恶意 IP 地址 +slug: /api-security/block-ip +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +你可以基于 IP 地址配置访问控制，以防止不必要的用户访问你的 API。 + +本指南将引导你在网关组上配置 `ip-restriction` 插件作为全局规则，以阻止黑名单中的 IP 地址。如果请求来自黑名单中的 IP 地址，API7 网关将拒绝该请求并返回 `403` 响应代码。请求的 IP 地址可以是实际的客户端 IP 地址，也可以是 `X-Forwarded-For` 地址。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 + +## 为网关组内所有 API 设置共享 IP 地址黑名单 + +一旦发现恶意 IP 地址正在攻击 API，最好将该 IP 地址添加到共享黑名单中以保护其他 API。 + + + + + +1. 选择你的服务所在的网关组。 +2. 从侧边栏选择 **插件设置**，然后选择 **插件全局规则**。 +3. 在 **插件** 字段中，搜索 `ip-restriction` 插件。 +4. 点击 **新增插件** +5. 在出现的对话框中，将以下配置添加到 **JSON 编辑器** 中，将 IP 地址 `127.0.0.1` 添加到黑名单中： + + ```json + { + "blacklist": ["127.0.0.1"], + "message": "Sorry, your IP address is not allowed." + } + ``` + +6. 点击 **新增**。 + + + + + +要使用 ADC 配置 IP 限制，请创建以下配置： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: security-ip + methods: + - GET +global_rules: + ip-restriction: + _meta: + disable: false + blacklist: + - 127.0.0.1 + message: Sorry, your IP address is not allowed. +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + + + + + +创建一个路由的 Kubernetes manifest 文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin-route + # namespace: api7 # replace with your namespace +spec: + http: + - name: httpbin-route + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 +``` + +创建另一个启用了密钥认证的路由的 manifest 文件： + +```yaml title="global-ip-restriction.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixGlobalRule +metadata: + name: global-ip-restriction + # namespace: api7 # replace with your namespace +spec: + plugins: + - name: ip-restriction + enable: true + config: + blacklist: + - "127.0.0.1" + message: Sorry, your IP address is not allowed. +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml -f global-ip-restriction.yaml +``` + + + + + +## 验证 + +从受限的 IP 地址发送请求。在本例中，`127.0.0.1` 被配置为黑名单 IP 地址： + +```shell +curl -i "http://127.0.0.1:9080/ip" +``` + +你将收到一个 `503 Service Temporarily Unavailable` 响应，并附带以下消息： + +```text +{"error_msg":"Sorry, your IP address is not allowed."} +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [路由](../key-concepts/routes.md) + * [插件](../key-concepts/plugins.md) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/client-mtls.md b/enterprise_versioned_docs/version-3.6.x/api-security/client-mtls.md new file mode 100644 index 00000000..0dcdb0dd --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/client-mtls.md @@ -0,0 +1,204 @@ +--- +title: 配置客户端与 API7 网关之间的 mTLS +slug: /api-security/client-mtls +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +双向传输层安全性（mTLS），作为 TLS（传输层安全性）的一种高级应用，旨在通过客户端与服务器之间的双向身份验证机制，显著提升通信安全性。这一过程依赖于精心设计的握手流程，双方不仅交换加密密钥，还相互验证对方的数字证书，从而确保通信双方身份的准确无误。 + +本指南将阐述如何在客户端应用程序和 API7 企业版之间配置 mTLS，以有效阻止未经授权的访问并加固整体安全防线。 + +下面是一个互动演示，提供配置 mTLS 的实践入门。通过点击并按照步骤操作，你将更好地了解如何在 API7 企业版中使用。 + + + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md), 并确保你的服务已配置主机名 `test.com`。 + +## 生成证书和密钥 + +1. 生成证书颁发机构（CA）的密钥和证书。 + + ``` + openssl genrsa -out ca.key 2048 && \ + openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt + ``` + +2. 为 API7 企业版生成一个公用名为 `test.com` 的密钥和证书，并使用 CA 证书签名。 + + ``` + openssl genrsa -out server.key 2048 && \ + openssl req -new -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_req \ + -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \ + -in server.csr -out server.crt + ``` + +3. 为客户端生成一个公用名为 `CLIENT` 的密钥和证书，并使用 CA 证书签名。 + + ``` + openssl genrsa -out client.key 2048 && \ + openssl req -new -sha256 -key client.key -out client.csr -subj "/CN=CLIENT" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_req \ + -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \ + -in client.csr -out client.crt + ``` + +4. 生成证书和密钥后，检查并确保以下文件已保存至你的本地设备。 + + ❶ `server.crt`: 服务器证书 + + ❷ `server.key`: 服务器证书的密钥 + + ❸ `ca.crt`: CA 证书 + +## 创建证书 + +1. 从侧边导航栏中选择网关组的 **证书**，进入 **SSL 证书** 选项卡。 +2. 单击 **新增 SSL 证书**。 +3. 在对话框中，执行以下操作： + +* 在 **名称** 字段中，输入 `测试 SSL 证书`。 +* 在 **证书** 字段中，上传 `server.crt` 文件。 +* 在 **私钥** 字段中，上传 `server.key` 文件。 +* 单击 **新增**。 + +4. 从侧边导航栏中选择网关组的 **证书**，然后单击 **CA 证书** 选项卡。 +5. 单击 **新增 CA 证书**。 +6. 在对话框中，执行以下操作： + +* 在 **名称** 字段中，输入 `测试 CA 证书`。 +* 在 **证书** 字段中，上传 `ca.crt` 文件。 +* 单击 **新增**。 + +## 创建 SNI + +1. 从侧边导航栏中选择网关组的 **SNI**。 +2. 单击 **新增 SNI**。 +3. 在对话框中，执行以下操作： + +* 在 **名称** 字段中，输入 `测试 SNI`。 +* 在 **域名** 字段中，输入 `test.com`。 +* 在 **SSL 协议** 字段中，选择 `TLS 1.2` 和 `TLS 1.3`。 +* 在 **SSL 证书** 字段中，选择你之前创建的 `测试 SSL 证书`。 +* 打开 **mTLS** 开关。 +* 在 **CA 证书** 字段中，选择你之前创建的 `测试 CA 证书`。 +* 单击 **新增**。 + +4. 在 **使用情况** 字段中，你应该会看到一个与主机名 `test.com` 匹配的已发布服务。然后你就可以进行验证了。 + +## 验证客户端与 API7 网关之间的 mTLS 连接 + +### 使用客户端证书进行请求 + +由于已配置的 SSL 证书针对公用名（CN）`test.com`，因此请确保在测试或生产环境中，使用 `test.com` 作为 API7 网关中服务的访问域名。 + +使用客户端证书发送请求至 `https://test.com:9443/ip`，并将 `test.com` 解析为 `127.0.0.1`。 + +``` +curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" \ + --cert client.crt --key client.key +``` + +可以看到类似以下内容的响应，说明客户端与 API7 网关之间已启用 mTLS。 + +``` +* Added test.com:9443:127.0.0.1 to DNS cache +* Hostname test.com was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to test.com (127.0.0.1) port 9443 +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* (304) (IN), TLS handshake, Unknown (8): +# highlight-start +* (304) (IN), TLS handshake, Request CERT (13): +* (304) (IN), TLS handshake, Certificate (11): +* (304) (IN), TLS handshake, CERT verify (15): +* (304) (IN), TLS handshake, Finished (20): +* (304) (OUT), TLS handshake, Certificate (11): +* (304) (OUT), TLS handshake, CERT verify (15): +* (304) (OUT), TLS handshake, Finished (20): +# highlight-end +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF +* ALPN: server accepted h2 +* Server certificate: +* subject: CN=test.com +* start date: Jul 31 08:50:42 2024 GMT +* expire date: Jul 7 08:50:42 2124 GMT +* issuer: CN=ROOTCA +* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. +* using HTTP/2 +* [HTTP/2] [1] OPENED stream for https://test.com:9443/ip +* [HTTP/2] [1] [:method: GET] +* [HTTP/2] [1] [:scheme: https] +* [HTTP/2] [1] [:authority: test.com:9443] +* [HTTP/2] [1] [:path: /ip] +* [HTTP/2] [1] [user-agent: curl/8.6.0] +* [HTTP/2] [1] [accept: */*] +> GET /ip HTTP/2 +> Host: test.com:9443 +> User-Agent: curl/8.6.0 +> Accept: */* +> +# highlight-start +< HTTP/2 200 +HTTP/2 200 +# highlight-end +... +``` + +> 注意，在握手期间，API7 网关和客户端成功验证了彼此的证书并建立了连接。 + +### 无客户端证书情况下进行请求 + +在无客户端证书的情况下，发送请求到 `https://test.com:9443/ip`。 + +``` +curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" +``` + +可以看到类似以下内容的响应，说明客户端与 API7 网关之间 mTLS 握手失败。 + +``` +* Added test.com:9443:127.0.0.1 to DNS cache +* Hostname test.com was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to test.com (127.0.0.1) port 9443 +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* (304) (IN), TLS handshake, Unknown (8): +# highlight-start +* (304) (IN), TLS handshake, Request CERT (13): +* (304) (IN), TLS handshake, Certificate (11): +* (304) (IN), TLS handshake, CERT verify (15): +* (304) (IN), TLS handshake, Finished (20): +* (304) (OUT), TLS handshake, Certificate (11): +* (304) (OUT), TLS handshake, Finished (20): +# highlight-end +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF +* ALPN: server accepted h2 +* Server certificate: +* subject: CN=test.com +* start date: Jul 31 08:50:42 2024 GMT +* expire date: Jul 7 08:50:42 2124 GMT +* issuer: CN=ROOTCA +# highlight-start +* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. +# highlight-end +* using HTTP/2 +* [HTTP/2] [1] OPENED stream for https://test.com:9443 +``` + +## 相关阅读 + +* 核心概念 + * [证书](../key-concepts/certificates) + * [SNI](../key-concepts/snis) +* 快速入门 + * [创建一个简单的 API](../getting-started/launch-your-first-api) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/configure-mtls.md b/enterprise_versioned_docs/version-3.6.x/api-security/configure-mtls.md new file mode 100644 index 00000000..7ae5ec76 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/configure-mtls.md @@ -0,0 +1,184 @@ +--- +title: 配置客户端与 API7 网关之间的 mTLS +slug: /api-security/configure-mtls +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +双向传输层安全性（mTLS），作为 TLS（传输层安全性）的一种高级应用，旨在通过客户端与服务器之间的双向身份验证机制，显著提升通信安全性。这一过程依赖于精心设计的握手流程，双方不仅交换加密密钥，还相互验证对方的数字证书，从而确保通信双方身份的准确无误。 + +本指南将阐述如何在客户端应用程序和 API7 企业版之间配置 mTLS，以有效阻止未经授权的访问并加固整体安全防线。 + +下面是一个互动演示，提供配置 mTLS 的实践入门。通过点击并按照步骤操作，你将更好地了解如何在 API7 企业版中使用。 + + + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 + +## 生成证书和密钥 + +1. 生成证书颁发机构（CA）的密钥和证书。 + + ``` + openssl genrsa -out ca.key 2048 && \ + openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt + ``` + +2. 为 API7 企业版生成一个公用名为 `test.com` 的密钥和证书，并使用 CA 证书签名。 + + ``` + openssl genrsa -out server.key 2048 && \ + openssl req -new -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_req \ + -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \ + -in server.csr -out server.crt + ``` + +3. 为客户端生成一个公用名为 `CLIENT` 的密钥和证书，并使用 CA 证书签名。 + + ``` + openssl genrsa -out client.key 2048 && \ + openssl req -new -sha256 -key client.key -out client.csr -subj "/CN=CLIENT" && \ + openssl x509 -req -days 36500 -sha256 -extensions v3_req \ + -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \ + -in client.csr -out client.crt + ``` + +4. 生成证书和密钥后，检查并确保以下文件已保存至你的本地设备。 + + ❶ `server.crt`: 服务器证书 + + ❷ `server.key`: 服务器证书的密钥 + + ❸ `ca.crt`: CA 证书 + +## 为 API7 企业版配置 mTLS + +1. 从侧边栏选择网关组的 **SSL 证书**，然后点击 **+ 新增 SSL 证书**。 + +2. 在对话框中，执行以下操作： + +* **类型** 选择 `服务器`。 +* 选择 **上传** 方法。 +* 在 **证书** 字段中上传 `server.crt` 文件。 +* 在 **私钥** 字段中上传 `server.key` 文件。 +* 打开 **对等验证** 按钮。 +* 在 **CA 证书（可选）** 字段中上传 `ca.crt` 文件。 +* 点击 **新增**。 + +3. 添加完成后，可以在 SSL 证书列表中看到一个新条目，包含一个唯一的 ID 和 `test.com` 作为其服务名称指示符（SNIS）。 + +## 验证客户端与 API7 网关之间的 mTLS 连接 + +### 使用客户端证书进行请求 + +由于已配置的 SSL 证书针对公用名（CN）`test.com`，因此请确保在测试或生产环境中，使用 `test.com` 作为 API7 网关中服务的访问域名。 + +使用客户端证书发送请求至 `https://test.com:9443/ip`，并将 `test.com` 解析为 `127.0.0.1`。 + +``` +curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" \ + --cert client.crt --key client.key +``` + +可以看到类似以下内容的响应，说明客户端与 API7 网关之间已启用 mTLS。 + +``` +* Added test.com:9443:127.0.0.1 to DNS cache +* Hostname test.com was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to test.com (127.0.0.1) port 9443 +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* (304) (IN), TLS handshake, Unknown (8): +# highlight-start +* (304) (IN), TLS handshake, Request CERT (13): +* (304) (IN), TLS handshake, Certificate (11): +* (304) (IN), TLS handshake, CERT verify (15): +* (304) (IN), TLS handshake, Finished (20): +* (304) (OUT), TLS handshake, Certificate (11): +* (304) (OUT), TLS handshake, CERT verify (15): +* (304) (OUT), TLS handshake, Finished (20): +# highlight-end +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF +* ALPN: server accepted h2 +* Server certificate: +* subject: CN=test.com +* start date: Jul 31 08:50:42 2024 GMT +* expire date: Jul 7 08:50:42 2124 GMT +* issuer: CN=ROOTCA +* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. +* using HTTP/2 +* [HTTP/2] [1] OPENED stream for https://test.com:9443/ip +* [HTTP/2] [1] [:method: GET] +* [HTTP/2] [1] [:scheme: https] +* [HTTP/2] [1] [:authority: test.com:9443] +* [HTTP/2] [1] [:path: /ip] +* [HTTP/2] [1] [user-agent: curl/8.6.0] +* [HTTP/2] [1] [accept: */*] +> GET /ip HTTP/2 +> Host: test.com:9443 +> User-Agent: curl/8.6.0 +> Accept: */* +> +# highlight-start +< HTTP/2 200 +HTTP/2 200 +# highlight-end +... +``` + +> 注意，在握手期间，API7 网关和客户端成功验证了彼此的证书并建立了连接。 + +### 无客户端证书情况下进行请求 + +在无客户端证书的情况下，发送请求到 `https://test.com:9443/ip`。 + +``` +curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" +``` + +可以看到类似以下内容的响应，说明客户端与 API7 网关之间 mTLS 握手失败。 + +``` +* Added test.com:9443:127.0.0.1 to DNS cache +* Hostname test.com was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to test.com (127.0.0.1) port 9443 +* ALPN: curl offers h2,http/1.1 +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* (304) (IN), TLS handshake, Unknown (8): +# highlight-start +* (304) (IN), TLS handshake, Request CERT (13): +* (304) (IN), TLS handshake, Certificate (11): +* (304) (IN), TLS handshake, CERT verify (15): +* (304) (IN), TLS handshake, Finished (20): +* (304) (OUT), TLS handshake, Certificate (11): +* (304) (OUT), TLS handshake, Finished (20): +# highlight-end +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF +* ALPN: server accepted h2 +* Server certificate: +* subject: CN=test.com +* start date: Jul 31 08:50:42 2024 GMT +* expire date: Jul 7 08:50:42 2124 GMT +* issuer: CN=ROOTCA +# highlight-start +* SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. +# highlight-end +* using HTTP/2 +* [HTTP/2] [1] OPENED stream for https://test.com:9443 +``` + +## 相关阅读 + +* 核心概念 + * [SSL 证书](../key-concepts/services.md) +* 快速入门 + * [创建一个简单的 API](../getting-started/launch-your-first-api.md) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/hashicorp-vault.md b/enterprise_versioned_docs/version-3.6.x/api-security/hashicorp-vault.md new file mode 100644 index 00000000..ff48e0c6 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/hashicorp-vault.md @@ -0,0 +1,519 @@ +--- +title: 引用 HashiCorp Vault 中的密钥 +slug: /api-security/hashicorp-vault +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +[HashiCorp Vault](https://www.vaultproject.io/) 是一个集中式平台，用于管理不同环境和应用程序中的密钥和加密。它提供了一个统一的密钥管理平台，用于存储和访问 API 密钥、密码、证书等。 + +本教程演示了如何将 API7 企业版与 HashiCorp Vault 集成，使你能够安全地存储和引用 Vault 中的消费者凭据和插件配置。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. 在你的网关组中[至少有一个网关实例](../getting-started/add-gateway-instance.md)。 +3. 安装 [Docker](https://docs.docker.com/get-docker/)。 +4. 安装 [cURL](https://curl.se/) 以向服务发送请求进行验证。 +5. 安装 [ZIP](https://infozip.sourceforge.net/Zip.html) 以解压缩 [官方分发的压缩文件](https://developer.hashicorp.com/vault/downloads) 中的 Vault 二进制文件。 + +## 配置 Vault 服务器 + +在 Docker 中以开发模式启动一个名为 `api7-quickstart-vault` 的 Vault 实例，令牌为 `api7-quickstart-vault-token`。暴露的端口映射到主机上的 `8200`： + +```shell +docker run -d --cap-add=IPC_LOCK \ + -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' \ + -e 'VAULT_ADDR=http://127.0.0.1:8200' \ +# highlight-start + -e 'VAULT_DEV_ROOT_TOKEN_ID=api7-quickstart-vault-token' \ + -e 'VAULT_TOKEN=api7-quickstart-vault-token' \ + --name api7-quickstart-vault \ +# highlight-end + -p 8200:8200 vault:1.13.0 +``` + +选择 `kv` 作为 API7 网关的 SSL 证书存储路径： + +API7 网关需要访问 Vault 和检索密钥的权限。你应该创建一个 [HashiCorp 配置语言 (HCL)](https://github.com/hashicorp/hcl) 策略文件来为 API7 网关生成 Vault 访问令牌。在 Vault 实例中创建一个名为 `api7-policy.hcl` 的 Vault 策略文件，以授予 API7 网关对路径 `secret/` 的读取权限。你可以将密钥放在路径 `secret/` 下以允许 API7 网关读取它们： + +```shell +docker exec api7-quickstart-vault /bin/sh -c "echo ' +# highlight-start +path \"secret/data/*\" { + capabilities = [\"read\"] +} +# highlight-end +' > /etc/api7-policy.hcl" +``` + +将策略文件应用于 Vault 实例： + +```shell +docker exec api7-quickstart-vault vault policy write api7-policy /etc/api7-policy.hcl +``` + +接下来，生成附加到新定义的策略的访问令牌，以供 API7 网关访问 Vault： + +```shell +docker exec api7-quickstart-vault vault token create -policy="api7-policy" +``` + +每次执行上述命令都会生成不同的令牌。如果成功，输出应类似于以下内容： + +```text +Key Value +--- ----- +# highlight-start +token hvs.CAESIHUznrV4wgcifUia0FROd6iprK7NjipAiHBYwiZDQP9TGh4KHGh2cy5ndHc5dzBPbXd5Y1pzblZXd2ZuQXA3ZHI +# highlight-end +token_accessor YY4iCj2lICDNd50ZJDsBjvZK +token_duration 768h +token_renewable true +token_policies ["api7-policy" "default"] +identity_policies [] +policies ["api7-policy" "default"] +``` + +## 在网关组中新增 Secret 提供商 + + + + + +1. 从侧边栏选择网关组的**Secret 提供商**，然后点击**新增 Secret 提供商**。 +2. 在对话框中，执行以下操作： + * **Secret 提供商 ID**，输入 `my-vault`。 + * **Secret 管理服务**，选择 `HashiCorp Vault`。 + * **KV 版本**，选择 `KV version 1`。 + * 填写**Vault 服务器 URL**字段。例如，`127.0.0.1:8200`。 + * 填写**Secret 前缀**字段。例如，`kv/api7`。 + * **身份验证方法**，选择 `Token`。 + * 填写**令牌**字段。 + * 点击**新增**。 + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +## 引用密钥以创建消费者凭据 + +消费者凭据中的以下敏感字段可以存储在外部Secret 管理服务（HashiCorp Vault、AWS Secret Manager 等）中，并在 API7 网关中引用： + +* Key Authentication 凭据中的 `key` +* Basic Authentication 凭据中的 `password` +* JWT 认证凭据中的 `secret`、`public key` +* HMAC 认证凭据中的 `secret key` + +### 新增消费者 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**新增消费者**。 +3. 在对话框中，执行以下操作： + * **名称**，输入 `Alice`。 + * 点击**新增**。 + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +### 存储密钥 + +为 Key Authentication 凭据创建一个密钥 `key=alice-primary-key`，并将其存储在 Vault 的路径 `secret/api7/consumer/alice` 中。**确保路径与你配置的Secret 前缀一致**： + +```shell +docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice key=alice-primary-key +``` + +预期响应类似于以下内容： + +```text +=== Secret Path === +secret/data/api7 + +======= Metadata ======= +Key Value +--- ----- +created_time 2023-03-15T11:42:17.123175125Z +custom_metadata +deletion_time n/a +destroyed false +version 1 +``` + +重复创建其他消费者凭据的更多密钥，所有密钥都在同一路径下： + +* 对于Basic Authentication 凭据： + +```shell +docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice password=alice-password +``` + +* 对于 JWT 认证凭据： + +```shell +docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice secret=alice-secret +``` + +* 对于 HMAC 认证凭据： + +```shell +docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice secret-key=alice-secret-key +``` + +### 新增Key Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**新增Key Authentication 凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-key`。 + * **Key**，选择**引用 Secret 提供商**，然后输入 `$secret://vault/my-vault/consumer/alice/key`。 + * 点击**新增**。 + +:::note + + 所有密钥引用都以 `$secret://` 开头。`vault` 是 Secret 提供商的**Secret 管理服务**，`my-vault` 是**Secret 提供商 ID**。连接到 HashiCorp Vault 时，`$secret://vault/my-vault` 将替换为 Secret 提供商的实际**Secret 前缀**。最后，发送到 HashiCorp Vault 的路径将是 `secret/api7/consumer/alice/key`。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +### 新增Basic Authentication 凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**基本认证**选项卡，然后点击**新增Basic Authentication 凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-basic`。 + * **用户名**，输入 `Alice`。 + * **密码**，选择**引用 Secret 提供商**，然后输入 `$secret://vault/my-vault/consumer/alice/password`。 + * 点击**新增**。 + +:::note + + 所有密钥引用都以 `$secret://` 开头。`vault` 是 Secret 提供商的**Secret 管理服务**，`my-vault` 是**Secret 提供商 ID**。连接到 HashiCorp Vault 时，`$secret://vault/my-vault` 将替换为 Secret 提供商的实际**Secret 前缀**。最后，发送到 HashiCorp Vault 的路径将是 `secret/api7/consumer/alice/password`。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +### 新增 JWT 认证凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**JWT**选项卡，然后点击**新增 JWT 凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-jwt`。 + * **Key**，输入 `alice-key`。 + * **算法**，选择 `HS256`。 + * **密钥**，选择**引用 Secret 提供商**，然后输入 `$secret://vault/my-vault/consumer/alice/secret`。 + * 点击**新增**。 + +:::note + + 所有密钥引用都以 `$secret://` 开头。`vault` 是 Secret 提供商的**Secret 管理服务**，`my-vault` 是**Secret 提供商 ID**。连接到 HashiCorp Vault 时，`$secret://vault/my-vault` 将替换为 Secret 提供商的实际**Secret 前缀**。最后，发送到 HashiCorp Vault 的路径将是 `secret/api7/consumer/alice/secret`。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +### 新增 HMAC 认证凭据 + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 选择你的目标消费者，例如，`Alice`。 +3. **凭据**选项卡下，点击**HMAC 认证**选项卡，然后点击**新增 HMAC 认证凭据**。 +4. 在对话框中，执行以下操作： + * **名称**，输入 `primary-hmac`。 + * **Key ID**，输入 `alice-keyid`。 + * **Secret Key**，选择**引用 Secret 提供商**，然后输入 `$secret://vault/my-vault/consumer/alice/secret-key`。 + * 点击**新增**。 + +:::note + + 所有密钥引用都以 `$secret://` 开头。`vault` 是 Secret 提供商的**Secret 管理服务**，`my-vault` 是**Secret 提供商 ID**。连接到 HashiCorp Vault 时，`$secret://vault/my-vault` 将替换为 Secret 提供商的实际**Secret 前缀**。最后，发送到 HashiCorp Vault 的路径将是 `secret/api7/consumer/alice/secret-key`。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +## 验证 + +### 验证 Key Authentication + +有关说明，请参阅[为 API 启用 Key Authentication](../api-security/api-authentication#enable-key-authentication-for-apis)，并在服务级别启用 `Key Auth 插件`。 + +然后按照[验证 Key Authentication](../api-security/api-authentication#validate-key-authentication) 说明进行操作。 + +### 验证 Basic Authentication + +有关说明，请参阅[为 API 启用 Basic Authentication](../api-security/api-authentication#enable-basic-authentication-for-apis)，并在服务级别启用 `Basic Auth 插件`。 + +然后按照[验证 Basic Authentication](../api-security/api-authentication#validate-basic-authentication) 说明进行操作。 + +### 验证 JWT Authentication + +有关说明，请参阅[为 API 启用 JWT Authentication](../api-security/api-authentication#enable-jwt-authentication-for-apis)，并在服务级别启用 `JWT Auth 插件`。 + +然后按照[验证 JWT Authentication](../api-security/api-authentication#validate-jwt-authentication) 说明进行操作。 + +### 验证 HMAC Authentication + +有关说明，请参阅[为 API 启用 HMAC Authentication](../api-security/api-authentication#enable-hmac-authentication-for-apis)，并在服务级别启用 `HMAC Auth 插件`。 + +然后按照[验证 HMAC Authentication](../api-security/api-authentication#validate-hmac-authentication) 说明进行操作。 + +## 引用密钥以启用插件 + +插件配置中的以下敏感字段可以存储在外部Secret 管理服务（HashiCorp Vault、AWS Secret Manager 等）中，并在 API7 网关中引用： + +|插件|字段| +|:---|:---| +|Limit Count|`redis_username`、`redis_password`| +|[Authz-Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/)|`client_id`、`client_secret`| +|[Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/)|`appid`| +|[LDAP 认证](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/)|`user_dn`| + +本节以配置 `Limit Count 插件` 为例进行演示。 + +### 创建密钥 + +创建一个密钥 `username=api7`，并将其存储在 Vault 的路径 `secret/api7/redis` 中。**确保路径与你配置的Secret 前缀一致**： + +```shell +docker exec api7-quickstart-vault vault kv put secret/api7/redis username=api7 +``` + +预期响应类似于以下内容： + +```text +=== Secret Path === +secret/data/api7 + +======= Metadata ======= +Key Value +--- ----- +created_time 2023-03-15T11:42:17.123175125Z +custom_metadata +deletion_time n/a +destroyed false +version 1 +``` + +再次尝试存储 Redis 密码的密钥： + +```shell +docker exec api7-quickstart-vault vault kv put secret/api7/redis password=redis-api7 +``` + +### 配置 Limit Count 插件 + +有关在何处以及如何启用 `Limit Count 插件`，请参阅 [API 限流限速](../api-security/rate-limiting.md)。 + + + + + +将以下配置添加到**JSON 编辑器**： + +```json +{ + "count": 3, + "time_window": 60, + "key_type": "var", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "key": "remote_addr", + "policy": "redis", + "redis_host": "127.0.0.1", + "redis_port": 6379, + "redis_username": "$secret://vault/my-vault/redis/username", + "redis_password": "$secret://vault/my-vault/redis/password", + "redis_database": 1, + "redis_timeout": 1001, + "allow_degradation": false, + "show_limit_quota_header": true +} +``` + +:::note + +所有密钥引用都以 `$secret://` 开头。`vault` 是Secret 提供商的**Secret 管理服务**，`my-vault` 是**Secret 提供商 ID**。连接到 HashiCorp Vault 时，`$secret://vault/my-vault` 将替换为Secret 提供商的实际**Secret 前缀**。最后，发送到 HashiCorp Vault 的路径将是 `secret/api7/redis/username` 和 `secret/api7/redis/password`。 + +::: + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +## 相关阅读 + +* 核心概念 + * [密钥](../key-concepts/secrets.md) + * [插件](../key-concepts/plugins.md) + * [消费者](../key-concepts/consumers.md) +* API 使用 + * [管理消费者凭据](../api-consumption/manage-consumer-credentials.md) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/rate-limiting.md b/enterprise_versioned_docs/version-3.6.x/api-security/rate-limiting.md new file mode 100644 index 00000000..33f5cda6 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/rate-limiting.md @@ -0,0 +1,593 @@ +--- +title: API 限流限速 +slug: /api-security/rate-limiting +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +应用速率限制可以控制发送到 API 后端的请求数量。这可以保护你的后端免受过多流量（包括正常流量和恶意流量（网络爬虫、DDoS 攻击））的影响，这些流量可能导致运营效率低下和成本增加。 + +本指南将引导你应用速率限制来控制随时间推移发送到上游节点的请求。 + +
+速率限制 +
+ +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee)。 +2. [在网关组上运行 API](../getting-started/launch-your-first-api)。 + +## 对所有服务应用速率限制（不推荐） + +你不应该全局配置速率限制插件，因为不同的 API 通常需要不同的速率限制配额。如果在全局（全局规则中）和本地（路由中）配置相同的插件，API7 网关将按顺序执行这两个插件实例。 + +## 对单个路由应用速率限制 + +### 限制请求计数 + +本节配置一个具有速率限制的路由，在 60 秒内仅允许 3 个请求。当超出限制时，将向消费者返回 429 状态码。 + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后点击要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. 在**插件**字段中，点击**新增插件**。 +5. 搜索 `limit-count` 插件，然后点击**新增**。 +6. 在对话框中，执行以下操作： + * 将以下配置新增到**JSON 编辑器**： + + ```json + { + "count": 3, + "time_window": 60, + "key_type": "var", + "key": "remote_addr", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "policy": "local", + "allow_degradation": false, + "show_limit_quota_header": true + } + ``` + + 如果你想引用 Secret 提供商中的密钥，请参阅 [引用 HashiCorp Vault 中的密钥](./hashicorp-vault) 和 [引用 AWS Secrets Manager 中的密钥](./aws-secrets-manager)，并使用以下带有密钥的配置： + + ```json + { + "count": 3, + "time_window": 60, + "key_type": "var", + "key": "remote_addr", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "policy": "redis", + "redis_host": "127.0.0.1", + "redis_port": 6379, + "redis_username": "$secret://vault/my-vault/redis/username", + "redis_password": "$secret://vault/my-vault/redis/password", + "redis_database": 1, + "redis_timeout": 1001, + "allow_degradation": false, + "show_limit_quota_header": true + } + ``` + + * 点击**新增**。 + +下面是一个交互式演示，提供了限制请求数量的实践介绍。通过点击并按照步骤操作，你将更好地了解如何在 API7 企业版中使用它。 + + + + + + + +要使用 ADC 配置路由，请创建以下配置： + +```yaml title="adc.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + limit-count: + _meta: + disable: false + count: 3 + time_window: 60 + key_type: var + key: remote_addr + policy: local + rejected_code: 429 + rejected_msg: Too many requests + allow_degradation: false + show_limit_quota_header: true +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc.yaml +``` + + + + + +创建一个启用了速率限制的路由的 Kubernetes mainfest 文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + plugins: + - name: limit-count + enable: true + config: + count: 3 + time_window: 60 + key_type: var + key: remote_addr + policy: local + rejected_code: 429 + rejected_msg: Too many requests + allow_degradation: false + show_limit_quota_header: true +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +#### 验证 + +要进行验证，请发送五个连续的请求： + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +你应该会看到以下响应，表明在 5 个请求中，有 3 个请求成功（状态码 200），而其他请求被拒绝（状态码 429）。 + +```text +200: 3, 429: 2 +``` + +### 每秒限制请求数 + +本节配置一个具有速率限制的路由，每秒仅允许 1 个请求。当每秒请求数在 1 到 3 之间时，它们将被延迟/限制。当每秒请求数超过 3 时，将返回 429 状态码。 + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后选择要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. 在**插件**字段中，点击**新增插件**。 +5. 搜索 `limit-req` 插件，然后点击**新增**。 +6. 在对话框中，执行以下操作： + * 将以下配置新增到**JSON 编辑器**： + + ```json + { + "rate": 1, + "burst": 2, + "key_type": "var", + "key": "remote_addr", + "rejected_code": 429, + "rejected_msg": "Requests are too frequent, please try again later." + } + ``` + + * 点击**新增**。 + + + + + +要使用 ADC 配置路由，请创建以下配置： + +```yaml title="adc.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + limit-req: + _meta: + disable: false + rate: 1 + burst: 2 + key_type: var + key: remote_addr + rejected_code: 429 + rejected_msg: Requests are too frequent, please try again later. +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + + + + + +创建一个启用了速率限制的路由的 Kubernetes mainfest 文件： + +```yaml title="httpbin-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: get-ip + # namespace: api7 # replace with your namespace +spec: + http: + - name: get-ip + match: + paths: + - /ip + methods: + - GET + backends: + - serviceName: httpbin + servicePort: 80 + plugins: + - name: limit-req + enable: true + config: + rate: 1 + burst: 2 + key_type: var + key: remote_addr + rejected_code: 429 + rejected_msg: Requests are too frequent, please try again later. +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + + + + + +#### 验证 + +要进行验证，请向路由发送三个请求： + +```bash +resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200 responses: $count_200 ; 429 responses: $count_429" +``` + +你可能会看到所有三个请求都成功了： + +```bash +200 responses: 3 ; 429 responses: 0 +``` + +将插件配置中的 `burst` 更新为 `0`，然后向路由发送三个请求： + +```bash +resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200 responses: $count_200 ; 429 responses: $count_429" +``` + +你应该会看到类似于以下内容的响应，表明超过速率的请求已被拒绝： + +```bash +200 responses: 1 ; 429 responses: 2 +``` + +## 具有消费者的速率限制 + +以下示例演示了如何按常规和匿名消费者配置不同的速率限制策略，其中匿名消费者不需要身份验证并且配额较少。虽然此示例使用 `Key Auth 插件` 进行身份验证，但也可以使用 `Basic Auth 插件`、`JWT Auth 插件` 和 `HMAC Auth 插件` 配置匿名消费者。 + +### 新增普通消费者 + +创建一个具有 Key Authentication凭据的常规消费者 `Alice`，并将 `Limit Count 插件` 配置为允许在 60 秒窗口内使用 3 个配额： + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**新增消费者**。 +3. 在对话框中，执行以下操作： + * 在**名称**字段中，输入 `Alice`。 + * 点击**新增**。 +4. 在**凭据**选项卡下，点击**新增Key Authentication凭据**。 +5. 在对话框中，执行以下操作： + * 在**名称**字段中，输入 `alice-key`。 + * 在**密钥**字段中，选择**手动输入**，然后输入 `alice-key`。 + * 如果你想选择**从Secret 提供商引用**，请参阅 [引用 HashiCorp Vault 中的密钥](./hashicorp-vault) 或 [引用 AWS Secrets Manager 中的密钥](./aws-secrets-manager)。 + * 点击**新增**。 + +6. 转到**插件**选项卡，点击**新增插件**。 +7. 搜索 `limit-count` 插件，然后点击**新增**。 +8. 在对话框中，执行以下操作： + * 将以下配置新增到**JSON 编辑器**： + + ```json + { + "count": 3, + "time_window": 60, + "key_type": "var", + "key": "remote_addr", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "policy": "local", + "allow_degradation": false, + "show_limit_quota_header": true + } + ``` + + * 点击**新增**。 + + + + + +即将推出。 + + + + + +Ingress Controller 目前不支持凭据和匿名消费者。 + + + + + +### 新增匿名消费者 + +创建一个匿名消费者 `anonymous` 并配置 `Limit Count 插件` 以允许在 60 秒窗口内使用 1 个配额： + + + + + +1. 从侧边栏选择网关组的**消费者**。 +2. 点击**新增消费者**。 +3. 在对话框中，执行以下操作： + * 在**名称**字段中，输入 `anonymous`。 + * 点击**新增**。 +4. 转到**插件**选项卡，点击**新增插件**。 +5. 搜索 `limit-count` 插件，然后点击**新增**。 +6. 在对话框中，执行以下操作： + * 将以下配置新增到**JSON 编辑器**： + + ```json + { + "count": 1, + "time_window": 60, + "key_type": "var", + "key": "remote_addr", + "rejected_code": 429, + "rejected_msg": "Too many requests", + "policy": "local", + "allow_degradation": false, + "show_limit_quota_header": true + } + ``` + + * 点击**新增**。 + + + + + +暂不支持。 + + + + + +暂不支持。 + + + + + +### 配置路由 + +创建路由并配置 `Key Auth 插件` 以允许匿名消费者 `anonymous` 绕过身份验证： + + + + + +1. 从侧边栏选择网关组的**已发布服务**，然后点击要修改的服务，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布的服务下，从侧边栏选择**路由**。 +3. 选择你的目标路由，例如，`get-ip`。 +4. 在**插件**字段中，点击**新增插件**。 +5. 搜索 `key-auth` 插件，然后点击**新增**。 +6. 在对话框中，执行以下操作： + * 将以下配置新增到**JSON 编辑器**： + + ```json + { + "anonymous_consumer": "anonymous" + } + ``` + + * 点击**新增**。 + + + + + +要使用 ADC 配置路由，请创建以下配置： + +```yaml title="adc.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: get-ip + methods: + - GET + plugins: + key-auth: + _meta: + disable: false + anonymous_consumer: anonymous +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + + + + + +暂不支持。 + + + + + +### 验证 + +要进行验证，请使用 `Alice` 的密钥发送五个连续的请求： + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/ip" -H 'apikey: alice-key' -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +你应该会看到以下响应，表明在 5 个请求中，有 3 个请求成功（状态码 200），而其他请求被拒绝（状态码 429）。 + +```text +200: 3, 429: 2 +``` + +发送五个匿名请求： + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/ip" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +你应该会看到以下响应，表明只有一个请求成功： + +```text +200: 1, 429: 4 +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services) + * [路由](../key-concepts/routes) + * [插件](../key-concepts/plugins) + * [消费者](../key-concepts/consumers) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/api-version-control.md b/enterprise_versioned_docs/version-3.6.x/best-practices/api-version-control.md new file mode 100644 index 00000000..dfc71e35 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/api-version-control.md @@ -0,0 +1,84 @@ +--- +title: API 版本控制 +slug: /best-practices/api-version-control +--- + +在逻辑变更后保持 API 功能需要更新 API 网关上的配置。API7 网关通过强大的服务级版本控制简化了这一过程。你可以将特定的服务版本及其相应的配置发布到不同的网关组，从而确保一致的部署和更平滑的回滚。 + +API7 网关并不强制要求强版本控制。是否实施甚至一个基本的版本控制系统取决于你的组织的具体需求和对 API 网关配置所需的控制级别。 + +## 版本控制范围 + +唯一的服务版本号表示一致的业务逻辑。 + +### 路由/四层路由 - 包含 + +API7 网关中的路由/四层路由更改与服务版本相关联。修改已发布服务版本中的路由/四层路由可能会对使用这些 API 的开发者造成干扰。这是因为他们现有的代码可能依赖于先前路由配置的特定行为。 + +### 上游 - 不包含 + +API7 网关依赖上游配置来管理与其后端应用程序（例如，服务器和数据库）的连接。这些配置决定了网关如何与后端交互，并且它们通常因部署环境而异。 + +例如，在开发环境中，API 网关可以配置为连接到开发者机器上运行的应用程序（例如，devserver）。而在生产环境中，它将连接到部署在数据中心中的实际后端服务器。 + +但是，需要注意的是，上游配置本身独立于 API 实现的核心逻辑。它们专注于通信的“方式”，而你的 API 代码专注于“内容”——它提供的特定功能。 + +即使使用相同的 API 版本，不同的网关组也可以通过上游配置指向不同的后端服务器。使用这些 API 的开发者不受影响。无论底层后端配置如何，他们的代码对 API 的调用都将以相同的方式运行。 + +通常，API7 网关中的上游配置提供了“运行时配置”的灵活性。它们独立于版本控制，允许你随时修改它们而无需发布新版本。 + +### 主机，路径前缀 - 不包含 + +主机和路径前缀是 API7 网关中的配置元素，用于管理客户端如何访问你的 API。它们独立于 API 实现的核心逻辑，专注于 API 调用的“位置”和“方式”。 + +主机和路径前缀可以根据你的部署环境（开发、暂存、生产）而变化，为每个阶段提供适当的接入点。更改主机或路径前缀通常需要开发人员更新他们的代码以反映新的访问详细信息。然而，与修改核心 API 逻辑相比，这种更新通常涉及替换代码中的主机地址或路径前缀，而不是完全重写。这最大限度地减少了开发人员在管理特定于环境的配置时受到的干扰。 + +例如： + +* `test` 环境中的 API 网址为 https://api7-test.ai/v1/pet，而端点地址为 127.0.0.1:80。 +* `production` 环境中的 API 网址为 https://api7.ai/petstore/pet，而端点地址为 192.168.0.1:80。 + +通常，API7 网关中的主机和路径前缀提供了“运行时配置”的灵活性。它们独立于版本控制，允许你随时修改它们而无需发布新版本。 + +## 关键特性 + +1. **服务变更跟踪：保持清晰的历史记录** + + 服务版本记录对你的服务所做的每一个修改，包括所做的具体变更、变更人以及变更的确切时间等细节。这种详细的历史记录提供了几个优势。它允许通过使你能够将问题追溯到特定的更改来更快地调试。 + +2. **服务回滚：意外问题的安全网** + + 这可以作为安全网，以防新的配置部署引入问题。如果出现意外后果或故障，你可以快速回滚到已知的良好版本。这种回滚能力最大限度地减少了停机时间，并确保了用户的服务连续性，防止了中断。 + +3. **网关组同步：跨部署的一致配置** + + 对于涉及多个网关组的复杂部署，在所有组中保持相同的配置至关重要。服务版本管理通过同步功能简化了这一过程。这确保了所有网关组具有完全相同的 API 逻辑相关配置，从而保证了你的 API 调用的行为一致性，而不受开发人员体验的影响。 + +## 使用合理的版本号 + +* 主版本增量（v1、v2）仅在需要重大更改时才使用。 +* 小版本增量（v1.1）优先用于向后兼容性。 +* 错误修复版本增量（v1.1.1）对 API 使用者应该是无害的。 +* 不要重复使用已弃用的版本号。 + +## 典型的版本控制工作流程 + +1. 为 `测试` 和 `生产` 环境添加两个网关组。 +2. 将服务发布到 `测试网关组`，服务版本为 `1.0.0`。 +3. 在测试环境中验证 API。 +4. 更新服务模板中的 API 配置。 +5. 使用版本 `1.0.1` 再次将错误修复发布到 `测试网关组`。 +6. 使用服务版本 `1.0.1` 将服务同步到 `生产网关组`。 +7. 对于新的迭代，编辑服务模板以添加更多路由。 +8. 使用服务版本 `1.1.0` 将服务发布到 `测试网关组`。 +9. 在测试环境中验证 API 并发生紧急情况。 +10. 将服务版本回滚到 `1.0.0` 进行恢复。 + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) +* 快速入门 + * [发布服务版本](../getting-started/publish-service.md) + * [在网关组之间同步已发布的服务版本](../getting-started/sync-service.md) + * [回滚已发布的服务](../getting-started/rollback-service.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/configure-grpc.md b/enterprise_versioned_docs/version-3.6.x/best-practices/configure-grpc.md new file mode 100644 index 00000000..afd37fb0 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/configure-grpc.md @@ -0,0 +1,434 @@ +--- +title: 使用 API7 企业版代理 gRPC 服务 +slug: /best-practices/configure-grpc +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +Google Remote Procedure Call（gRPC）是基于 HTTP/2 协议的开源高性能远程过程调用（Remote Procedure Call，RPC）框架。gRPC 使用 Protocol Buffers（protobuf）作为接口描述语言（Interface Description Language，IDL）。API7 企业版提供协议转换、负载均衡、身份验证和授权等关键功能，增强了 gRPC 的潜力。 + +本指南介绍如何使用 API7 企业版代理 gRPC 服务。 + +下面是一个互动演示，介绍了如何使用 API7 企业版代理 gRPC 流量。 + + + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [安装 gRPCurl](https://github.com/fullstorydev/grpcurl)，将请求发送到 gRPC 服务器进行验证。 + +## 部署示例 gRPC 服务器 + + + + + +API7 提供了一个 gRPC 服务示例，用于测试。你可以使用以下命令在端口 `50051` 上启动示例 gRPC 服务器的 Docker 实例 `grpc-service`： + +```shell +docker run -d \ + --name grpc-service \ + --network=api7-ee_api7 \ + -p 50051:50051 \ + --restart always api7/grpc-server-example:1.0.0 +``` + + + + + +Start an example gRPC server listening on port `50051`: + +```shell +kubectl run grpc-service \ + --image=api7/grpc-server-example:1.0.0 \ + --port=50051 \ + --restart=Always +``` + +你应该能看到类似 `pod/grpc-service created` 的响应。 + + + + + +### 验证 gRPC 服务器启动成功 + + + + + + + + + + + +暴露应用的 `50051` 端口： + +```shell +kubectl expose pod grpc-service --port 50051 +``` + +你应该看到类似 `service/grpc-service exposed` 的响应。 + +将端口`50051` 转发到 localhost： + +```shell +kubectl port-forward svc/grpc-service 50051:50051 & +``` + + + + + +通过列出所有可用的 gRPC 服务和方法来验证 gRPC 服务器是否成功启动： + +```shell +grpcurl -plaintext 127.0.0.1:50051 list +``` + +你应该能看到以下输出： + +```text +grpc.reflection.v1alpha.ServerReflection +helloworld.Greeter +helloworld.TestImport +``` + +列出所有 `helloworld.Greeter` 服务可用的方法: + + +```shell +grpcurl -plaintext 127.0.0.1:50051 list helloworld.Greeter +``` + +你应该能看到以下输出： + +```text +helloworld.Greeter.GetErrResp +helloworld.Greeter.Plus +helloworld.Greeter.SayHello +helloworld.Greeter.SayHelloAfterDelay +helloworld.Greeter.SayHelloBidirectionalStream +helloworld.Greeter.SayHelloClientStream +helloworld.Greeter.SayHelloServerStream +``` + +## 创建服务和路由 + +本示例创建一个名为 `grpc-example` 的服务和一个名为 `helloworld.Greeter` 的路由，将请求转发到上面的示例 gRPC 服务。 + + + + + +

新增服务

+ +1. 在左侧菜单选择目标网关组下的 **已发布服务** 菜单，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在对话框中执行以下操作： + +* **名称** 填写 `grpc-example`。 +* **服务类型** 选择 `HTTP （七层）`。 +* **上游 Scheme** 选择 `gRPC`。 +* **如何找到上游** 选择 `使用节点`。 +* 点击 **新增节点**。 +* 在新增节点对话框中，执行以下操作： + * **主机** 填写你的私有 IP 地址，例如`192.168.2.103`。 + * **端口** 填写 `50051`。 + * **权重** 填写 `100`。 + +4. 点击 **新增**。 + +

创建一条路由

+ +1. 进入刚才创建好的服务，然后点击 **新增路由**。 +2. 在对话框中，执行以下操作： + +* **名称** 填写 `helloworld.Greeter`。 +* **路径** 填写 `helloworld.Greeter/SayHello`。 +* **HTTP 方法** 选择 `GET` 和 `POST`。 +* 点击 **新增**。 + + + + + +创建一个 ADC 配置文件: + +```yaml title="adc.yaml" +services: + - name: grpc-example + upstream: + name: gRPC Upstream + scheme: grpc + type: roundrobin + nodes: + - host: 192.168.2.103 + port: 50051 + weight: 100 + routes: + - uris: + - /helloworld.Greeter/SayHello + name: helloworld.Greeter + methods: + - GET + - POST +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + + + + + +使用 ApisixRoute 自定义资源创建一个 Kubernetes mainfest 文件来配置到 gRPC 服务的路由： + +```yaml title="grpc-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: grpc-route + # namespace: api7 # replace with your namespace +spec: + http: + - name: helloworld-greeter + match: + paths: + - /helloworld.Greeter/SayHello + methods: + - GET + - POST + backends: + - serviceName: grpc-service + servicePort: 50051 +``` + +使用 ApisixUpstream 自定义资源创建另一个 Kubernetes mainfest 文件，将上游配置为 `grpc`： + +```yaml title="grpc-upstream.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixUpstream +metadata: + name: grpc-service +# namespace: api7 # replace with your namespace +spec: + scheme: grpc +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f grpc-route.yaml -f grpc-upstream.yaml +``` + + + + + +## 更新 API7 网关实例以支持 HTTP/2 + +默认情况下，API7 网关实例在端口 `9443` 上支持 TLS 加密的 HTTP/2。在本教程中，你可以添加端口 `9081`，支持不加密的 HTTP/2，然后将端口 `9081` 映射到主机上的同一端口。 + +在本节中，你将更新 API7 网关配置和部署以支持 `9081` 端口上的非加密 HTTP/2。 + + + + + +由于 Docker 不支持在容器运行时更新端口映射，因此首先请移除 `api7-ee-gateway-1` 网关容器（[随安装一起启动](../getting-started/install-api7-ee.md#install-api7-enterprise)）。 + +接下来，[在 Docker 中启动一个新的网关实例](../getting-started/add-gateway-instance.md)。在运行生成的部署命令之前，添加 `-p 9081:9081` 标志。修改后的命令应类似于： + +```shell +docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://:7943"]' \ + -e API7_GATEWAY_GROUP_SHORT_ID=default \ + -e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + " \ + -e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY----- + + -----END PRIVATE KEY----- + " \ + -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE----- + " \ + -e API7_CONTROL_PLANE_SNI="api7ee3-dp-manager" \ + -p 9080:9080 \ + # highlight-next-line + -p 9081:9081 \ + -p 9443:9443 \ + api7/api7-ee-3-gateway: +``` + +运行命令启动网关。 + +网关运行后，更新网关配置以允许 `9081` 端口上的 HTTP/2： + +```shell +docker exec /bin/sh -c "echo ' +nginx_config: + error_log_level: warn + +apisix: + node_listen: + - port: 9080 + enable_http2: true +# highlight-start + - port: 9081 + enable_http2: true +# highlight-end +' > /usr/local/apisix/conf/config.yaml" +``` + +重新加载容器以使配置更改生效： + +```shell +docker exec apisix reload +``` + + + + + +编辑网关 ConfigMap： + +```shell +kubectl edit cm api7-ee-3-gateway +``` + +在 ConfigMap 中添加允许 `9081` 端口上 HTTP/2 的配置： + +```yaml +apisix: + node_listen: + - port: 9080 + enable_http2: false +# highlight-start + - port: 9081 + enable_http2: true +# highlight-end +``` + +保存 ConfigMap 并重新启动部署： + +```shell +kubectl rollout restart deployment api7-ee-3-gateway +``` + +要将 `9081` 添加为服务端口，请编辑服务： + +```shell +kubectl edit svc/api7-ee-3-gateway-gateway +``` + +将以下配置添加到 `ports`： + +```yaml +spec: + ports: + ... + # highlight-start + - name: http2-non-tls + port: 9081 + protocol: TCP + targetPort: 9081 + # highlight-end + ... +``` + +保存服务 mainifest 以使更改生效。 + + + + + +## 验证 gRPC 服务 + +[下载 `helloworld.proto` 文件](https://github.com/api7/grpc_server_example/blob/master/proto/helloworld.proto) 。 + +此示例使用 `helloworld.proto` 文件来确保 gRPCurl CLI 工具使请求和响应格式与 gRPC 服务定义一致。 + + + + + +如果你在 Docker 中安装了网关实例并使用控制台或 ADC 进行配置，请向路由发送请求： + + + + + +如果你在 Kubernetes 上安装了网关实例并使用 Ingress Controller 进行配置，请先通过端口转发将服务端口暴露给你的本地机器： + +```shell +kubectl port-forward svc/api7-ee-3-gateway-gateway 9081:9081 & +``` + +向路由发送请求： + + + + + +```shell +grpcurl -plaintext \ + -proto helloworld.proto \ + -d '{"name":"API7"}' \ + "127.0.0.1:9081" \ + "helloworld.Greeter.SayHello" +``` + +你应该能看到如下类似的响应： + +```text +{ + "message": "Hello API7" +} +``` + +## 相关阅读 + +* Key Concepts + * [Services](../key-concepts/services.md) + * [Routes](../key-concepts/routes.md) + * [Plugins](../key-concepts/plugins.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/custom-plugin.md b/enterprise_versioned_docs/version-3.6.x/best-practices/custom-plugin.md new file mode 100644 index 00000000..da819686 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/custom-plugin.md @@ -0,0 +1,40 @@ +--- +title: 新增自定义插件 +slug: /best-practices/custom-plugin +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +API7 网关的一个关键特性是其通过插件的可扩展性。除了各种现有的插件之外，API7 网关还允许你构建自定义插件，以新增额外的功能并通过自定义流程管理 API 流量。通常，你可以使用 Lua 编程语言来实现新的插件。API7 网关分阶段处理请求，相关的插件逻辑会在请求路由过程中的每个阶段执行。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [用 Lua 编写自定义插件](https://docs.api7.ai/apisix/how-to-guide/custom-plugins/create-plugin-in-lua). + +## 新增自定义插件 + +1. 从侧边栏选择 **网关设置**，然后选择 **自定义插件**。 +2. 点击 **新增自定义插件**。 +3. 在新增自定义插件对话框中，执行以下操作： + +* **插件源代码文件**：上传用 Lua 编写的插件文件。 +* **插件目录**：目录将用于过滤和搜索插件。例如，选择 `Traffic`。 +* **插件描述**：例如 `使用规则拆分流量`。 +* **插件文档链接**：例如 `https://docs.api7.ai/hub/traffic-split`。 +* **插件作者**：例如 `Tom`。 +* **部署的网关组**: 选择`全选`。 + +4. 点击**新增**。 +5. 现在你的自定义插件已新增到插件列表中。可以在**启用插件**对话框中的服务/路由/消费者/插件的全局规则中选择它。 + +下面是一个交互式演示，提供了新增自定义服务的实践介绍。 + + + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [路由](../key-concepts/routes.md) + * [插件](../key-concepts/plugins.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/design-custom-role-system.md b/enterprise_versioned_docs/version-3.6.x/best-practices/design-custom-role-system.md new file mode 100644 index 00000000..d15bdb52 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/design-custom-role-system.md @@ -0,0 +1,200 @@ +--- +title: 设计自定义角色系统 +slug: /best-practices/design-custom-role-system +--- + +本教程将介绍如何为你的组织设计和实现自定义角色系统。自定义角色允许你授予用户细粒度的访问权限，从而增强安全性并提高数据完整性。 + +## 关键因素 + +1. 清晰的需求和目标 + +首先，明确定义设计自定义角色系统的具体需求和目标。例如，你是想提高应用程序安全性，简化访问控制管理，还是满足更复杂的访问控制要求？明确的需求可以帮助你更好地定义角色和权限，并选择正确的实现方式。 + +2. 合理的角色划分 + +根据应用程序功能和用户职责合理划分角色。角色划分应粒度适中，既要避免过于细粒度的角色导致管理复杂，又要避免过于粗粒度的角色导致权限控制不够精细。 + +3. 清晰的权限定义 + +每个角色都应该有明确的权限定义。权限定义应清晰易懂，并与角色的职责相符。避免向同一角色授予过多或不相关的权限。 + +在不同的角色中复用权限策略可能是一把双刃剑。它为简化和管理提供了好处，但如果不小心也会带来潜在的安全风险。如果复用的策略受到破坏，则会影响所有继承该策略的角色，从而可能授予对多个资源的未经授权的访问。这会放大安全漏洞的潜在损害。过于宽泛的策略会使最小权限原则难以实施，授予用户超出其严格需要的更多访问权限。 + +4. 清晰的层次结构和可扩展性 + +一个用户友好的自定义角色系统应该具有高度的可扩展性和面向未来的能力。这使得职责分离能够为用户分配适当的角色。部门需求可以通过定制的角色和权限策略来满足，减少对单个“超级管理员”的日常权限管理的依赖。或者，小组负责人可以在其团队内分配角色和权限，确保精细控制并将对其他小组的影响降至最低。 + +## 使用案例 + +一般来说，API7 企业版建议在团队内采用一种平衡的方法来进行角色管理。在大多数情况下，可以增加并利用好更细分一层的团队领导角色，并且仅在明确需要并且进行了彻底的安全审查时，才考虑创建更小的领导角色。 + +### 团队各自分配角色 + +想象一下，你需要一个 RBAC 系统，多个团队需要使用共享的角色（例如，“测试工程师”、“开发工程师”）。然而，当出现以下情况时，可能会遇到挑战： + +- 团队组成频繁变化：经常有新成员加入，或者团队成员会经常调整角色。 +- 团队分工不同：每个团队可能有独特的工作流程或职责，虽然用到的角色是跨团队共享的，但是需要不同的角色分配原则和不同的细粒度访问控制。 +- 有限的用户可见性：用户可能不熟悉其他团队的同事，没有一个人可以为所有团队成员分配合适的角色。 + +#### 解决方案 + +1. 设置超级管理员或具有 `角色管理员` 自定义角色的用户（授予以下权限）专门负责维护 API7 企业版中的所有角色： + +```json +{ + "statement": [ // 同一个策略中的多个语句之间是 OR 关系 + { + "resources": [ + "arn:api7:iam:user/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:role/<.*>" // 即便拥有通用权限也不能修改超级管理员角色 + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:permissionpolicy/<.*>" // 即便拥有通用权限也不能修改默认的超级管理员关联的权限策略 + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] +} +``` + +2. 创建一个自定义角色 `组长`，关联以下权限策略。被授予这个角色的用户，可以为他的小组成员分配已有的角色。 + +```json + { + "statement": [ + { + "resources": [ + "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", // 小组成员的用户 ID + "arn:api7:iam:users/n5p1u6y-0df3-4a5b-c90fe1-32kasd789b", + "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", + "arn:api7:iam:users/gt8h2x3-1fe4-5678-d21b0a-98zxc1b546", + "arn:api7:iam:users/y7u8i9o-pasd-fghj-123456-7klmnop12" + ], + "actions": [ // 包括所有与小组管理相关的权限，不包括邀请新用户和编辑角色 + "iam:GetUser", + "iam:UpdateUserRole", + "iam:ResetPassword", + "iam:DeleteUser" + ], + "effect": "allow" + } + ] + } +``` + +### 团队特定角色设计 + +一个具有团队特定角色和权限创建的模块化 RBAC 系统允许每个团队管理自己的访问需求，从而减少对“超级管理员”或“角色管理员”的依赖。 + +#### 解决方案 + +1. 创建一个具有以下两个权限策略的自定义角色 `组长`。分配了此角色的用户将同时负责设计和管理其小团队中的角色并将角色分配给小团队的成员。 + +权限策略 1 用于为团队成员分配角色： + +```json + { + "statement": [ + { + "resources": [ + "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", // 小组成员的用户 ID + "arn:api7:iam:users/n5p1u6y-0df3-4a5b-c90fe1-32kasd789b", + "arn:api7:iam:users/23w9q4t-ba7e-f310-a1d45b-78jklz1234", + "arn:api7:iam:users/gt8h2x3-1fe4-5678-d21b0a-98zxc1b546", + "arn:api7:iam:users/y7u8i9o-pasd-fghj-123456-7klmnop12" + ], + "actions": [ // 包括所有与小组管理相关的权限，不包括邀请新用户和编辑角色 + "iam:GetUser", + "iam:UpdateUserRole", + "iam:ResetPassword", + "iam:DeleteUser" + ], + "effect": "allow" + } + ] + } +``` + +权限策略 2 负责为小组创建专属的自定义角色和权限策略： + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:iam:role/<.*>>", + ], + "actions": [ // 包括所有与角色设计和管理相关的权限 + "<.*>" + ], + "conditions": { + "role_label": { + "type": "MatchLabel", + "options": { + "key": "team", + "operation": "exact_match", + "value": "champion" + } + } + }, + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:permissionpolicy/<.*>>" + ], + "actions": [ // 包括所有与权限策略设计和管理相关的权限 + "<.*>" + ], + "conditions": { + "permissionpolicy_label": { + "type": "MatchLabel", + "options": { + "key": "team", + "operation": "exact_match", + "value": "champion" + } + } + }, + "effect": "allow" + } + ] +} +``` + +2. 作为 `组长`，请始终在你创建的资源中包含你团队的指定标签。这可以确保对你的角色和权限策略的正确访问控制，不会和其他团队的角色和权限策略混淆。 + +3. 你依然可以使用由 `超级管理员` 或 `角色管理员` 设计的共享角色，并将其分配给你的小组成员。 + +4. API7 企业版允许在团队内部进行进一步的权限分层管理。作为 `组长`，你甚至可以创建一个关联了相同权限策略的自定义角色，让更多角色也可以创建自定义角色和权限策略，不断细分。这种方法可以大大减轻团队领导者管理角色的负担。 + +虽然权限分层管理提供了效率优势，但需要同时兼顾安全性的考虑。 + +## 相关阅读 + +- 核心概念 + - [角色和权限策略](../key-concepts/roles-and-permission-policies.md) +- 快速入门 + - [更新用户角色](../getting-started/rbac.md) + - [创建自定义角色](../getting-started/create-custom-role.md) +- 开发参考 + - [权限策略操作和资源](../reference/permission-policy-action-and-resource.md) + - [权限策略示例](../reference/permission-policy-example.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/devops-adc.md b/enterprise_versioned_docs/version-3.6.x/best-practices/devops-adc.md new file mode 100644 index 00000000..826430a5 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/devops-adc.md @@ -0,0 +1,692 @@ +--- +title: DevOps 声明式配置和 CI/CD 管道 +slug: /best-practices/devops-adc +--- + +本文档将引导你使用声明式配置工具 ADC（APISIX/API7 Declarative Configuration CLI）来设置 API7 企业版。为实现配置的自动化 GitOps 管理，我们将 `adc.yaml` 文件作为配置的唯一真实来源。 + +### ADC 简介 + +ADC 将 `adc.yaml` 文件作为唯一的来源，并自动将配置同步至 API 网关，从而确保网关的实时状态与 `adc.yaml` 中定义的配置状态保持一致。 + +### 步骤 + +1. 配置 ADC 并将其连接到网关实例 +2. 发布配置、代理请求并为消费者启用密钥认证 +3. 修改配置并应用更改 + +### 注意事项 + +1. 本文档以 API7 企业版网关 v3.2.10.0 为例，该版本基于 Apache APISIX 3.2，尚不支持配置验证 API。因此，你无法使用 ADC 的验证命令进行配置验证。该功能将从 Apache APISIX 的 v3.5 版本以后开始提供。 + +2. ADC 支持加载 OpenAPI 3.0 规范文件，也支持将其转换为 `adc.yaml` 格式。但转换后的文件需要你手动进行调整，例如添加身份验证策略及绑定服务 ID。为提供更加流畅的用户体验，这些功能正在计划中。 + +3. 企业可能采用不同的 Git/SVN 版本控制服务和防火墙策略。只要 ADC 工具能够通过网络访问到网关的 Admin API，它就能够正常工作。本文档中的示例操作将在本地计算机上进行演示。 + +## 前提条件 + +- API7 企业版：3.2.10.1 +- ADC：0.8.0 + +### 部署 API7 企业版 + +API7 企业版支持 Docker 和 [Kubernetes](https://docs.api7.ai/enterprise/deployment/kubernetes) 两种部署方式。请结合自身的业务需求和技术栈选择合适的部署方法。 + +部署 API7 企业版后，你应该可以看到以下组件和信息： + +- Dashboard 组件：`7443/7080 端口` +- API7 Gateway 组件：`http://152.42.234.39:9080` +- Admin API：`https://152.42.234.39:7443` + +![ee-component-diagram](https://static.apiseven.com/uploads/2024/04/11/5ZUDl6rt_ee-sec-0411.png) + +### 下载 ADC + +- +- +- + +```bash +$ ./adc -h + +Usage: adc [options] [command] + +Options: + -V, --version output the version number + -h, --help display help for command + +Commands: + ping [options] Verify connectivity with backend + dump [options] Dump configurations from the backend + diff [options] Show the difference between local and backend configurations + sync [options] Sync local configurations to backend + convert Convert other API spec to ADC configurations + lint [options] Check provided configuration files, local execution only, ensuring inputs meet ADC requirements + help [command] display help for com +``` + +## 步骤 + +### 生成 API 令牌 + +ADC 需要一个 API 令牌来访问 Admin API，你可以通过 Dashboard 或 Admin API 生成 API 令牌。 + +- 从 Dashboard 生成 API 令牌：登录 -> 组织 -> 令牌 -> 生成新令牌 +- 在 [Admin API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Tokens) 中生成 API 令牌 + +### 配置 ADC 证书 + +1. 在与 ADC 二进制文件相同的目录中创建一个 `.env` 文件。 + +本文档创建了一个 `.env` 文件来存储 API 令牌和 Admin API 端点。你还可以将这些值作为标志传递或存储在 GitHub Action、Jenkins 或 GitLab 中。 + +```bash +ADC_BACKEND=api7ee +ADC_SERVER=https://152.42.234.39:7443 +ADC_TOKEN=a7ee-6baF8488i8wJ5aj7mEo3BT705573eC8GH905qGrdn889zUWcR37df66a34e9954b61918c5dfd13abce3e +``` + +2. 验证 Admin API 是否可访问。 + +```bash +$ ./adc ping + +Connected to backend successfully! +``` + +### 发布配置 + +1. 创建 `adc.yaml` 文件： + +```yaml +services: + - name: SOAP Service + description: "This Service is for SOAP requests" + upstream: + name: default + scheme: https + type: roundrobin + hash_on: vars + nodes: + - host: apps.learnwebservices.com + port: 443 + weight: 1 + priority: 0 + retry_timeout: 0 + pass_host: pass + routes: + - uris: + - /services/hello + name: SOAP proxy + methods: + - POST + - uris: + - /SayHello + name: REST to SOAP + methods: + - POST + plugins: + soap: + wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl + - name: httpbin Service + description: "This is the httpbin Services proxy service" + labels: + app: httpbin + custom_key: custom_value + routes: + - name: Generate UUID + methods: + - GET + uris: + - /uuid + - name: Anything + methods: + - GET + uris: + - /anything + plugins: + key-auth: + _meta: + disable: false + - name: Rate Limited IP + methods: + - GET + uris: + - /ip + plugins: + limit-count: + _meta: + disable: false + count: 2 + time_window: 10 + rejected_code: 429 + policy: local + upstream: + name: default + scheme: http + type: roundrobin + hash_on: vars + nodes: + - host: httpbin.org + port: 80 + weight: 1 + priority: 0 + retry_timeout: 0 + pass_host: pass + - name: SSE Service + labels: + service: sse + upstream: + scheme: https + nodes: + - host: www.esegece.com + port: 2053 + weight: 1 + priority: 0 + type: roundrobin + pass_host: node + plugins: + proxy-buffering: + disable_proxy_buffering: true + routes: + - name: SSE API + uris: + - /sse + methods: + - GET +consumers: + - username: tom + plugins: + key-auth: + key: tomskey +ssls: [] +global_rules: {} +``` + +2. 同步 `adc.yaml` 至网关实例 + +```bash +$ ./adc sync -f adc.yaml + +✔ Load local configuration +✔ Load remote configuration +✔ Diff configuration +✔ Sync configuration +``` + +3. 验证代理 + +```bash +$ curl 152.42.234.39:9080/uuid -v + +* Trying 152.42.234.39:9080... +* Connected to 152.42.234.39 (152.42.234.39) port 9080 +> GET /uuid HTTP/1.1 +> Host: 152.42.234.39:9080 +> User-Agent: curl/8.4.0 +> Accept: */* +> +< HTTP/1.1 200 OK +< Content-Type: application/json +< Content-Length: 53 +< Connection: keep-alive +< Date: Wed, 17 Apr 2024 09:56:22 GMT +< Access-Control-Allow-Origin: * +< Access-Control-Allow-Credentials: true +< Server: API7/3.2.8 +< + +{ + "uuid": "22b888f4-9e96-4d09-93a2-408b14e772fe" +} + +* Connection #0 to host 152.42.234.39 left intact +``` + +4. 验证插件：Key Authentication + +```bash +$ curl 152.42.234.39:9080/anything + +{"message":"Missing API key found in request"} + +$ curl 152.42.234.39:9080/anything -H "apikey: tomskey" + +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Apikey": "tomskey", + "Host": "152.42.234.39", + "User-Agent": "curl/8.4.0", + "X-Amzn-Trace-Id": "Root=1-661f9d57-42c4a66b07b361713713da44", + "X-Forwarded-Host": "152.42.234.39" + }, + "json": null, + "method": "GET", + "origin": "182.255.32.50, 152.42.234.39", + "url": "http://152.42.234.39/anything" +} +``` + +### 修改配置并应用更改 + +1. 将 `adc.yaml` 更新为以下配置（为 httpbin 服务添加一个新路由 `/headers`）： + +```yaml +services: + - name: SOAP Service + description: "" + upstream: + name: default + scheme: https + type: roundrobin + hash_on: vars + nodes: + - host: apps.learnwebservices.com + port: 443 + weight: 1 + priority: 0 + retry_timeout: 0 + pass_host: pass + routes: + - uris: + - /services/hello + name: SOAP proxy + methods: + - POST + - uris: + - /SayHello + name: REST to SOAP + methods: + - POST + plugins: + soap: + wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl + - name: httpbin Service + description: "" + labels: + app: httpbin + custom_key: custom_value + routes: + - name: Get Headers + methods: + - GET + uris: + - /headers + - name: Generate UUID + methods: + - GET + uris: + - /uuid + - name: Anything + methods: + - GET + uris: + - /anything + plugins: + key-auth: + _meta: + disable: false + - name: Rate Limited IP + methods: + - GET + uris: + - /ip + plugins: + limit-count: + _meta: + disable: false + count: 2 + time_window: 10 + rejected_code: 429 + policy: local + upstream: + name: default + scheme: http + type: roundrobin + hash_on: vars + nodes: + - host: httpbin.org + port: 80 + weight: 1 + priority: 0 + retry_timeout: 0 + pass_host: pass + - name: SSE Service + labels: + service: sse + upstream: + scheme: https + nodes: + - host: www.esegece.com + port: 2053 + weight: 1 + priority: 0 + type: roundrobin + pass_host: node + plugins: + proxy-buffering: + disable_proxy_buffering: true + routes: + - name: SSE API + uris: + - /sse + methods: + - GET +consumers: + - username: tom + plugins: + key-auth: + key: tomskey +ssls: [] +global_rules: {} +``` + +2. 确定本地配置和远程配置之间的差异。 + +:::info +ADC 仍在开发中，差异算法将会优化。 +::: + +```bash +$ ./adc diff -f ./adc.yaml + +✔ Load local configuration +✔ Load remote configuration +✔ Diff configuration + › update consumer: "tom" + update route: "REST to SOAP" + update route: "SOAP proxy" + update route: "Rate Limited IP" + update route: "Anything" + update route: "Generate UUID" + create route: "Get Headers" + update service: "SSE Service" + update route: "SSE API" + Summary: 1 will be created, 8 will be updated, 0 will be deleted +✔ Write detail diff result to file +``` + +此命令还会生成一个带有详细差异的 `diff.yaml` 文件。 + +```yaml +- resourceType: consumer + type: update + resourceId: tom + resourceName: tom + oldValue: + username: tom + description: "" + plugins: + key-auth: + key: tomskey + newValue: + username: tom + plugins: + key-auth: + key: tomskey + diff: + added: {} + deleted: {} + updated: {} +- resourceType: route + type: update + resourceId: bef0a3351a392e74c960f9a58c1d025d803f2aef + resourceName: REST to SOAP + oldValue: + uris: + - /SayHello + name: REST to SOAP + methods: + - POST + enable_websocket: false + plugins: + soap: + wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl + newValue: + uris: + - /SayHello + name: REST to SOAP + methods: + - POST + plugins: + soap: + wsdl_url: https://apps.learnwebservices.com/services/hello?wsdl + diff: + added: {} + deleted: {} + updated: {} + parentId: 602dfcf4c39218f87d40c5d1df8b531b49ca88e8 +- resourceType: route + type: update + resourceId: da37e65d428446d156279156ac3248c00d0a1533 + resourceName: SOAP proxy + oldValue: + uris: + - /services/hello + name: SOAP proxy + methods: + - POST + enable_websocket: false + newValue: + uris: + - /services/hello + name: SOAP proxy + methods: + - POST + diff: + added: {} + deleted: {} + updated: {} + parentId: 602dfcf4c39218f87d40c5d1df8b531b49ca88e8 +- resourceType: route + type: update + resourceId: b586591b59c13461ed8932228cb23e53040c09d4 + resourceName: Rate Limited IP + oldValue: + uris: + - /ip + name: Rate Limited IP + methods: + - GET + enable_websocket: false + plugins: + limit-count: + _meta: + disable: false + count: 2 + policy: local + rejected_code: 429 + time_window: 10 + newValue: + name: Rate Limited IP + methods: + - GET + uris: + - /ip + plugins: + limit-count: + _meta: + disable: false + count: 2 + time_window: 10 + rejected_code: 429 + policy: local + diff: + added: {} + deleted: {} + updated: {} + parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302 +- resourceType: route + type: update + resourceId: 5f2de5df1a292b4c8a73f0ec23271233d75707c6 + resourceName: Anything + oldValue: + uris: + - /anything + name: Anything + methods: + - GET + enable_websocket: false + plugins: + key-auth: + _meta: + disable: false + newValue: + name: Anything + methods: + - GET + uris: + - /anything + plugins: + key-auth: + _meta: + disable: false + diff: + added: {} + deleted: {} + updated: {} + parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302 +- resourceType: route + type: update + resourceId: ed048a2f75fe33eab67319810fbb94bb778d7d97 + resourceName: Generate UUID + oldValue: + uris: + - /uuid + name: Generate UUID + methods: + - GET + enable_websocket: false + newValue: + name: Generate UUID + methods: + - GET + uris: + - /uuid + diff: + added: {} + deleted: {} + updated: {} + parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302 +- resourceType: route + resourceId: 6b124aff482499cbf7bdad5a56b13205b24ba58e + resourceName: Get Headers + type: create + newValue: + name: Get Headers + methods: + - GET + uris: + - /headers + parentId: 5ce4033cfe1015450e0b81186f7d54b9327cc302 +- resourceType: service + type: update + resourceId: 54154d3cdf6379ab8686890d27fabb6bf8fa3ace + resourceName: SSE Service + oldValue: + name: SSE Service + description: "" + labels: + service: sse + upstream: + name: default + scheme: https + type: roundrobin + hash_on: vars + nodes: + - host: www.esegece.com + port: 2053 + weight: 1 + priority: 0 + retry_timeout: 0 + pass_host: node + plugins: + proxy-buffering: + disable_proxy_buffering: true + newValue: + name: SSE Service + labels: + service: sse + upstream: + scheme: https + nodes: + - host: www.esegece.com + port: 2053 + weight: 1 + priority: 0 + type: roundrobin + pass_host: node + plugins: + proxy-buffering: + disable_proxy_buffering: true + diff: + added: {} + deleted: + upstream: {} + updated: {} + subEvents: + - &a1 + resourceType: route + type: update + resourceId: 6b808fa543c7c3391321b813d0dc2d658ab02c10 + resourceName: SSE API + oldValue: + uris: + - /sse + name: SSE API + methods: + - GET + enable_websocket: false + newValue: + name: SSE API + uris: + - /sse + methods: + - GET + diff: + added: {} + deleted: {} + updated: {} + parentId: 54154d3cdf6379ab8686890d27fabb6bf8fa3ace +- *a1 +``` + +3. 应用更改 + +```bash +$ ./adc sync -f ./adc.yaml + +✔ Load local configuration +✔ Load remote configuration +✔ Diff configuration +✔ Sync configuration +``` + +4. 验证 + +注意：由于已经为 httpbin 服务添加了一个新路由 `/headers`，你可以访问新路由，并且它应该返回请求头信息。 + +```bash +$ curl 152.42.234.39:9080/headers + +{ + "headers": { + "Accept": "*/*", + "Host": "152.42.234.39", + "User-Agent": "curl/8.4.0", + "X-Amzn-Trace-Id": "Root=1-661f9edd-188a0adf5d3bf0a509f5b034", + "X-Forwarded-Host": "152.42.234.39" + } +} +``` + +## 结论 + +本文档演示了如何使用 ADC 工具发布配置、代理请求，以及为消费者启用密钥验证。 + +你还可以修改配置并将更改应用到网关实例。ADC 工具是一个强大的工具，可以帮助你有效地管理 API 网关配置。将 ADC 与你的 CI/CD 管道集成后，你可以进行自动化的配置发布和验证，这有助于确保你配置的准确性和 API 的安全性。 diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/manage-services-in-multi-environments.md b/enterprise_versioned_docs/version-3.6.x/best-practices/manage-services-in-multi-environments.md new file mode 100644 index 00000000..d2600cd1 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/manage-services-in-multi-environments.md @@ -0,0 +1,133 @@ +--- +title: 使用网关组在多环境中管理服务 +slug: /best-practices/manage-services-in-multi-environments +--- + +[网关组](../key-concepts/gateway-groups.md)是一个由一个或多个共享相同配置的网关实例组成的逻辑分组，这些网关实例在处理 API 请求时表现一致。用户可以为网关组命名，并为其添加标签，以此来区分和管理不同的环境和集群。 + +API7 企业版支持 `API 网关`和 `Ingress Controller` 两种类型的网关组管理，能帮助企业进行环境和集群的隔离，多区域多集群管理，以及根据业务线实现服务级别目标管理。 + +这篇指南将向你展示如何通过网关组实现在 `测试`、`UAT`、 `生产` 三个环境中的服务管理。 + +## 背景介绍 + +为确保服务稳定、合规及数据安全，服务的上线经历多个环境，包括测试环境、UAT 环境和生产环境。在没有多环境管理功能的情况下，研发人员需要部署 3 套独立的 API7 企业版，开发工程师、QA 工程师和运维工程师需要分别登录不同域名下的 API7 企业版控制台，对同一个 API 进行开发、测试和上线，在业务线非常多的情况下，会浪费大量机器和管理资源。 + +API7 企业版的网关组功能为研发人员提供了一个统一的入口，避免在多控制台中切换，可以实现简单便捷的发布操作，从而提高工作效率并减少操作错误。 + +![Multi-Environment Service Publishing](https://static.apiseven.com/uploads/2024/07/08/uxX5p7xl_multi-environment%20release.PNG) + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. 准备好服务在三个环境内的不同域名：`test.acme.com`、`uat.acme.com`、`prod.acme.com`。 +3. 参考[新增网关组](../getting-started/add-gateway-group.md)，创建三个网关组：`测试`、`UAT` 和 `生产`，对应测试环境、UAT 环境和生产环境的使用。 + +## 在测试环境新增服务和路由 + +1. 从左侧菜单选择 `测试` 网关组下的**已发布服务**，然后点击**新增服务**。 +2. 选择**手动新增**。 +3. 在对话框中，执行以下操作： + * **名称**填写 `httpbin`。 + * 点击 **+ 添加节点**。 + * 在对话框中，执行以下操作： + * **主机**填写 `test.api7.org`。 + * **端口**填写 `80`。 + * 点击**新增**。 +4. 在**主机**字段中，点击 **+ 新增**。 + * 输入 `test.acme.com`。 +5. 打开**添加第一条路由**按钮。 +6. 在**第一个路由**对话框中，执行以下操作： + * **名称**填写 `get-headers`。 + * **路径**填写 `headers`。 + * **HTTP 方法**选择 `GET`。 + * 点击**新增**。将创建一个处于“无版本”状态的新服务 `httpbin`。 +7. 进入**上游**页面。 +8. （可选）在**连接配置**模块中，点击**编辑**图标。 +9. （可选）在**编辑连接配置**对话框中，执行以下操作： + * **传递给上游的 Host 请求头**选择 `使用上游中指定的 Host`。 + * 点击**保存**。 + +> 注意：步骤 8 和 9 是可选的。必须将 **传递给上游的 Host 请求头* 参数更改为`使用上游中指定的 Host`，以确保与上游的握手成功。请根据你的用例进行相应的调整。 + +10. 模拟真实用户场景进行功能测试、性能测试和安全测试。 + +### 验证服务 + +测试后，发送请求以验证测试网关组中的 httpbin 服务： + +```bash +curl "http://localhost:9080/headers" -v -H "Host: test.acme.com" +``` + +你应该能收到 `200 OK` 的响应。 + +## 将服务部署到 UAT 环境 + +1. 从左侧菜单选择 `测试` 网关组下的**已发布服务**。 +2. 点击 `httpbin` 服务旁边的 **...**，然后点击**同步到其他网关组**。 +3. 在**选择要同步到的网关组**字段中，选择 `UAT` 网关组，然后点击**下一步**。 +4. 在对话框中，执行以下操作： + * **版本**填写`1.0.0`。 + * **请求 URL** 填写`uat.acme.com`。 + * 在**上游配置**模块中，点击**编辑**。 + * 在对话框中，执行以下操作： + * **主机**和**端口**填写入 `uat.api7.org` 作为主机，`80` 作为端口。 + * **权重** 使用默认值 `100`。 + * 点击**保存**。 + * 确认服务信息，然后点击**同步**。`httpbin` 服务将同步到 `UAT` 网关组。 +5. （可选）在**连接配置**模块中，点击**编辑**图标。 +6. （可选）在**编辑连接配置**对话框中，执行以下操作： + * **传递给上游的 Host 请求头**选择 `使用上游中指定的 Host`。 + * 点击**保存**。 + +> 注意：步骤 5 和 6 是可选的。必须将 **传递给上游的 Host 请求头* 参数更改为`使用上游中指定的 Host`，以确保与上游的握手成功。请根据你的用例进行相应的调整。 + +7. 在 `UAT` 网关组中，配置网关组的安全策略和合规性检查功能，例如进行[日志审计](../api-observability/logging.md)。 + +### 验证服务 + +测试后，发送请求以验证测试网关组中的 httpbin 服务： + +```bash +curl "http://localhost:9080/headers" -v -H "Host: uat.acme.com" +``` + +你应该能收到 `200 OK` 的响应。 + +## 将服务部署到生产环境 + +1. 从左侧菜单选择 `UAT` 网关组下的**已发布服务**。 +2. 点击 `httpbin` 服务旁边的 **...**，然后点击**同步到其他网关组**。 +3. 在**选择要同步到的网关组**字段中，选择 `生产` 网关组，然后点击**下一步**。 +4. 在对话框中，执行以下操作： + * **请求 URL**填写 `production.acme.com`。 + * 在**上游配置**模块中，点击**编辑**。 + * 在**编辑节点**对话框中，执行以下操作： + * **主机**和**端口**填写 `prod.api7.org` 作为主机，`80` 作为端口。 + * **权重**使用默认值 `100`。 + * 点击**保存**。 + * 确认服务信息，然后点击**同步**。`httpbin` 服务将同步到 `生产` 网关组。 +8. （可选）在**连接配置**模块中，点击**编辑**图标。 +9. （可选）在**编辑连接配置**对话框中，执行以下操作： + * **传递给上游的 Host 请求头**选择 `使用上游中指定的 Host`。 + * 点击**保存**。 + +> 注意：步骤 5 和 6 是可选的。必须将 **传递给上游的 Host 请求头* 参数更改为`使用上游中指定的 Host`，以确保与上游的握手成功。请根据你的用例进行相应的调整。 + +7. 定期审查和分析 `httpbin` 的日志，执行日志管理，并识别潜在的问题以进行改进。 +8. 制定详细的回滚计划，包括回滚步骤、所需时间和责任人员，并在必要时[回滚已发布的服务](../getting-started/rollback-service.md)。 + +### 验证服务 + +测试后，发送请求以验证测试网关组中的 httpbin 服务： + +```bash +curl "http://localhost:9080/headers" -v -H "Host: production.acme.com" +``` + +你应该能收到 `200 OK` 的响应。 + +## 总结 + +测试、UAT 和生产环境是软件开发生命周期的重要组成部分。通过利用 API7 企业版的网关组，你可以实现物理和逻辑隔离，从而增强安全性、可控性和效率。此外，灵活调整路由规则和管理服务版本的能力可确保应用程序的平滑和敏捷版本管理。 \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/manage-token.md b/enterprise_versioned_docs/version-3.6.x/best-practices/manage-token.md new file mode 100644 index 00000000..86f6fe77 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/manage-token.md @@ -0,0 +1,85 @@ +--- +title: 使用 Token 集成 GitOps 工作流 +slug: /best-practices/manage-token +--- + +访问令牌是一种包含用户身份验证信息和授权数据的数字凭证，用于在客户端和服务器之间进行安全通信。它允许用户在无需直接提供敏感信息（如用户名和密码）的情况下，访问受保护的资源或执行特定操作。作为一种广泛应用于现代 Web 应用程序和 API 安全性的重要机制，访问令牌可以帮助实现安全、可扩展和无状态的身份验证和授权。 + +## 背景介绍 + +企业在应用交付时，通常会采用多种不同的平台，例如安全漏洞分析平台、资源管理平台等，以满足各种特定的需求和场景。然而，在公司系统规模庞大且复杂性较高的情况下，系统之间的集成以及如何实现研发的自动化就成为了亟待解决的重要问题。 + +为了更灵活地应对这些挑战，企业可以选择不使用 API7 企业版的控制面板进行集成，而是利用 API7 企业版所提供的系统 token 进行鉴权和认证，实现一键将 API7 企业版与自有系统的无缝对接。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 + +## 实施步骤 + +![How Does Token Work in API7 Enterprise](https://static.apiseven.com/uploads/2024/07/30/qjh8vCQB_img_v3_02d9_52472ff9-521b-4ffb-acc5-352b100940bg.jpg) + +### 1. 注册账号 + +由于 token 权限和账户角色是同步的，为避免人员变动对账户权限造成影响，因而注册一个专门用于 GitOps 集成的账号，用于管理 token。 + +### 2. 查阅 API 文档 + + - 查阅 API7 企业版的 API 文档，了解可用的 API 接口、请求参数和响应格式。 + - 根据需要调用的 API，确定需要的角色和权限，将角色权限授权给当前系统账号。 + - 再确定与待调用的 API 接口相应的请求参数，以避免因权限不足导致无权调用的情况。 + +### 3. 获取 Token + +在 API7 企业版中，点击生成 token，选择合适的到期时间，如：7 天 / 30 天 / 60天。 + +![Generate Token](https://static.apiseven.com/uploads/2024/07/29/5Piy3cuR_token-cn-2.png) + +> 注意：token 只显示一次，生成后需复制并妥善保管。 + +### 4. 编写 API 调用代码 + + - 开发人员在产研系统中编写代码，实现 API7 企业版 API 的调用。 + - 代码包括构建请求 URL、设置请求头（包含 token）、发送请求并处理响应。 + +#### 代码示例一 + +调用 API7 企业版的 API 有两种方式：一是获取所有 API 数据，并将 token 添加到请求头中进行鉴权和认证。 + +``` +curl -k \ +-X GET "http://api.example.com/api7ee/admin/services" \ +-H "X-API-KEY: $API_KEY" +``` + +#### 代码示例二 + +二是在请求头的 Cookie 中添加 token。 + +``` +curl -k \ +-X GET "http://api.example.com/api7ee/admin/services" \ +-H "Cookie: X-API-KEY=$API_KEY" +``` + +### 5. 测试 API 调用 + +- 开发人员在本地环境测试 API 调用代码，确保能够正确调用 API7 企业版的 API 并获取预期的响应。 +- 测试过程中，开发人员使用之前获取的 token 进行鉴权和认证。 + +### 6. 部署与集成 + +- 测试通过后，开发人员将 API 调用代码部署到产研系统中，建议使用与测试环境不同的 token 以提升安全性。 +- 产研系统与 API7 企业版的 API 进行集成，实现数据交换和功能互通。 + +### 7. 实现自动工作流程 + +通过集成 API7 企业版的 API，公司可以实现自动的工作流程。例如，当产研系统中的某个任务完成时，可以自动调用 API7 企业版的 API 来发送通知、更新数据或触发其他操作。 + +### 8. Token 更新和管理 + +为了加强安全性，生产环境中的 token 应该定期更新，如每 90 天更新一次，并对新的 token 进行妥善保管。你可以在 API7 企业版控制台上进行 token 更新操作。一旦 token 被更新，之前的 token 就会立即失效。 + +## 总结 + +在企业环境中，特别是在管理多平台代码和集成复杂系统时，访问令牌的作用尤为突出。通过生成系统 token 进行鉴权和认证，企业能够实现 API7 企业版与自有系统的无缝对接，进而实现自动化的工作流程，提高研发效率和系统间的数据交换能力。 diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/service-discovery.md b/enterprise_versioned_docs/version-3.6.x/best-practices/service-discovery.md new file mode 100644 index 00000000..bdd6d4e8 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/service-discovery.md @@ -0,0 +1,85 @@ +--- +title: 上游使用服务发现 +slug: /best-practices/service-discovery +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +除了直接配置上游，还可以使用 Consul、Eureka、Nacos 或 Kubernetes 服务发现等服务发现机制来动态检测上游节点。 + +:::info + +一旦发布，服务不能直接在配置的上游节点和服务发现之间切换。如有需要，你必须通过[灰度部署](../getting-started/canary-upstream.md)来配置。 + +::: + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. 在你的网关组中[至少有一个网关实例](../getting-started/add-gateway-instance.md)。 + +## Kubernetes + +### 添加服务注册中心连接 + +1. 从侧边栏选择网关组的 **服务注册表**，然后点击 **新增服务注册中心连接**。 +2. 在对话框中，执行以下操作： + * **名称** 输入 `测试环境注册中心`。 + * **发现类型** 选择 `Kubernetes`。 + * 填写 **API 服务器地址** 和 **令牌值** 字段。 + * 点击 **新增**。 +3. 等待，确保服务注册中心的状态为 `健康`。 + +### 配置上游 + +1. 从侧边栏选择网关组下的 **已发布服务**，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在对话框中，执行以下操作： + * **名称** 输入 `httpbin`。 + * **服务类型** 选择 `HTTP (七层代理)`。 + * **上游 Scheme** 选择 `HTTP`。 + * **如何查找上游** 选择 `使用服务发现`。 + * **服务注册中心** 选择 `测试环境注册中心`，然后选择 **命名空间** 和 **服务名称**。 +4. 点击 **新增**。这将创建一个“无版本”的新服务。 + +下面是一个互动演示，提供连接 Kubernetes 服务发现的实践入门。通过点击并按照步骤操作，你将更好地了解如何在 API7 网关中使用它： + + + + +## Nacos + +### 添加服务注册中心连接 + +1. 从侧边栏选择网关组的 **服务注册表**，然后点击 **新增服务注册中心连接**。 +2. 在对话框中，执行以下操作： + * **名称** 输入 `测试环境注册中心`。 + * **发现类型** 选择 `Nacos`。 + * **主机** 填写主机地址和端口。 + * **如何获取令牌** 选择一种获取令牌的方式并配置相关参数。 + * 点击 **新增**。 +3. 等待，确保服务注册中心的状态为 `健康`。 + +### 配置上游 + +1. 从侧边栏选择网关组下的 **已发布服务**，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在对话框中，执行以下操作： + * **名称** 输入 `httpbin`。 + * **服务类型** 选择 `HTTP (七层代理)`。 + * **上游 Scheme** 选择 `HTTP`。 + * **如何查找上游** 选择 `使用服务发现`。 + * **服务注册中心** 选择 `测试环境注册中心`，然后选择 **命名空间**、**组**和**服务名称**。 +4. 点击 **新增**。这将创建一个“无版本”的新服务。 + +下面是一个互动演示，提供连接 Nacos 服务发现的实践入门。通过点击并按照步骤操作，你将更好地了解如何在 API7 网关中使用它： + + + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [上游](../key-concepts/upstreams.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/sso.md b/enterprise_versioned_docs/version-3.6.x/best-practices/sso.md new file mode 100644 index 00000000..bfca6d88 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/sso.md @@ -0,0 +1,212 @@ +--- +title: SSO 第三方登录 +slug: /best-practices/sso +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +单点登录（SSO）允许用户一次登录即可访问多个系统，而无需重新输入凭据。它通过消除对多个密码的需求，提高了效率，增强了用户体验，并加强了安全性。 + +在 API7 企业版中，你可以同时使用多种登录选项。你可以在 API7 内部创建用户，同时也可以从其他现有系统中导入用户。 + +## 架构原理 + +以 LDAP 为例： + +![Architecture of LDAP](https://static.apiseven.com/uploads/2024/03/12/B3YpRXbf_LDAP-2.png) + +1. **用户登录请求**：用户在登录 API7 企业版时输入他们的用户名和密码。 +2. **LDAP验证**：API7 企业版将用户提供的凭据传输到 LDAP 服务器进行验证。LDAP 服务器是一个集中的用户信息管理系统，存储了用户的用户名、密码以及其他相关信息。 +3. **身份验证**：LDAP 服务器验证用户的凭据是否与 LDAP 目录中存储的用户信息匹配。如果用户名和密码与 LDAP 服务器中的记录相匹配，那么身份验证就成功了。 +4. **授权**：如果身份验证成功，LDAP 服务器将授权信息返回给 API7 企业版。系统基于这些信息授权用户访问相应的资源。这通常涉及到角色和权限的分配，确保用户只能访问他们被授权访问的资源。 +5. **访问资源**：用户以经过验证的身份访问API7 企业版，无需重新输入凭据。 + +## 集成 SSO + +API7 企业版支持以下实现的单点登录（SSO）。将 API7 企业版与其他用户系统集成后，你可以让现有用户登录 API7 企业版，而无需注册新的 API7 帐户。 + + + + + +1. 从顶部导航栏中选择 **组织**，然后选择 **设置**。 +2. 点击 **新增登录选项**。 +3. 填写表单： + +* **名称**：唯一的登录名称，必须与用户相同。例如：`Employee Account`。 +* **Provider**：选择 `LDAP`。 +* **Host**：LDAP 主机域名。例如，`ldap.example.com`。 +* **Port**：例如，`1563`。 +* **Base Distinguished Name**：例如，`oc=users,dc=org,dc=example`。 +* **Bind Distinguished Name**：用于执行 LDAP 搜索用户的 LDAP Bind Distinguished Name (DN)。此 LDAP Bind DN 应具有搜索被身份验证用户的权限。例如，`cn=admin,dc=org,dc=example`。 +* **Bind Password**：用于 LDAP 服务器身份验证的 LDAP 绑定密码。 +* **Identifier**：用于标识 LDAP 用户的属性。例如，`cn`。 +* **Attributes Mapping**：将 API7 内部字段映射到相关的 LDAP 属性，以无缝集成和同步数据。 + +4. 点击 **新增**。 + + + + + +1. 从顶部导航栏中选择 **组织**，然后选择 **设置**。 +2. 点击 **新增登录选项**。 +3. 填写表单： + +* **Name**：唯一的登录名称，必须与用户相同。例如：`Employee Account`。 +* **Provider**：选择 `OIDC`。 +* **Issuer**：OpenID connect 提供商的标识符。例如，`https://accounts.example.com`。 +* **Client ID**：OIDC 提供商分配的应用程序唯一标识符。例如，`API7`。 +* **Client Secret**：用于身份验证的密钥，由 OIDC 提供商分配。 +* **Request Scope**：访问令牌通常具有不同的范围，这会限制其使用。例如，`profile,email`。 +* **Root URL**：用于访问 API7 以生成回调 URL 的 URL。例如，`https://auth.example.com/oidc`。 +* **SSL verify**：默认值是打开的。 + +4. 点击 **新增**。 + +下面是一个交互式演示，它介绍了如何使用 OpenID Connect (OIDC) 协议实现单点登录。跟随演示，你将直观了解如何在 API7 企业版中使用这个功能。 + + + + + + + +1. 从顶部导航栏中选择 **组织**，然后选择 **设置**。 +2. 点击 **新增登录选项**。 +3. 填写表单： + +* **Name**：唯一的登录名称，必须与用户相同。例如 `Employee Account`。 +* **Provider**：选择 `SAML`。 +* **Identity Provider Metadata URL**：用于获取有关身份提供商信息的 URL，例如其公钥、支持的 SAML 版本、签名算法等。例如，`https://idp.example.com/metadata`。 +* **Service Provider Root URL**：从身份提供商 (IdP) 请求身份验证和授权的实体。例如，`https://sp.example.com`。 +* **Entity ID**：服务提供商 (SP) 或身份提供商 (IdP) 实体的唯一标识符。它通常在 SAML 联合中充当实体的全局唯一标识符。例如，`https://sp.example.com/saml/metadata`。 + +4. 点击 **新增**。 + + + + +## 用 SSO 登录 + +一旦配置了登录选项，外部用户将能够直接登录到 API7 企业版控制台，而无需进行注册。 + +请按照以下步骤操作： + +1. 访问位于 http://localhost:7080 的 API7 企业版控制台。 +2. 从登录选项名称中选择，例如`使用员工帐户登录`。 +3. 输入用户名和密码。 +4. 点击登录。 + +## 删除导入的用户 + +如果你在 **用户** 中删除了使用 SSO 登录选项的用户，这仅仅意味着该用户将失去其所有角色。但是，他们仍然可以作为新用户登录到 API7 企业版控制台。要完全阻止他们访问 API7 企业版控制台，你必须从来源的用户系统中删除他们。 + +如果你希望完全阻止某个用户访问 API7 企业版，需要在身份提供系统中删除或禁用该用户的帐户。这样，当该用户尝试通过 SSO 登录 API7 企业版时，身份提供商将不会验证他们的身份，从而阻止他们访问系统。 + +## 从身份提供商同步用户数据 + +SCIM（系统跨域身份管理）是一种协议，可用于将用户和组信息从原始身份提供商（IdP）同步到 API7 企业版。这样就无需在多个系统中重复创建和管理用户，从而节省时间并降低出错风险。 + +通过 SCIM 用户同步，只要在你的 IdP 中注册或删除新用户，API7 企业版就会自动同步用户数据。 + +1. 在顶部导航栏中，选择 **组织**，然后选择 **设置**。 +2. 点击 **SCIM 配置** 的 **启用** 按钮。 +3. 复制 **API7 SCIM 端点 URL** 和 **SCIM 令牌**。 +4. 到身份提供商的设置页面进行配置（如果支持 SCIM）： + +* 登录到身份提供商管理控制台。 +* 找到 SCIM 配置设置（这些可能因你的 IdP 而异）。 +* 将复制的 **API7 SCIM 端点 URL** 和 **SCIM 令牌**粘贴到相应的字段中。 +* 保存配置更改并在身份提供商端进行配置。 + +## 为导入的用户分配角色 + +### 手动更新角色 + +请参阅[如何更新用户角色](../getting-started/rbac.md)。 + +### 设置角色映射 + +导入的用户会根据其原始系统中的相关属性（头衔、职位、部门等）自动分配角色。这些角色会在用户登录时同步和刷新，以实现无缝访问。角色映射可以包含多个规则，这些规则共同决定用户的角色和访问权限。 + +:::info + +角色映射优先于手动角色分配。当角色映射启用时，对用户角色的任何手动调整都将在下次用户登录时被覆盖。 + +::: + +1. 在顶部导航栏中，选择 **组织**，然后选择**设置**。 +2. 选择要设置的登录选项，点击名称进入。例如，`员工账户`。 +3. 点击 **角色映射**的 **启用**按钮。 +4. 填写表单： + +* ***内部角色**: 例如，`超级管理员`。 +* **角色属性**: 在身份提供商系统中的字段名称，例如，`Position`. +* **运算符**: 例如，`=`. +* **角色值**: 例如，`研发组长`. + +5. 点击 **开启**. + +现在，通过 `员工账户` 登录，且在原始系统中职位为研发组长 (Position = 研发组长) 的所有用户将自动获得 **超级管理员** 角色。 + +值得注意的是，这种角色映射是动态的。如果用户的职位在身份提供商中发生变化，例如从“研发组长”变为“团队成员”，那么他们下次登录 API7 企业版时，角色将自动更新。 + +### 设置权限边界映射 + +导入的用户会根据其原始系统（职称、职位、部门等）中的相关属性自动分配权限边界。这些权限边界会在登录时同步和刷新，以实现无缝访问。 +登录选项的权限边界映射可以涉及多个规则，这些规则协同工作以确定用户访问权限。 + +:::note + +权限边界映射优先于手动权限边界修改。当权限边界映射启用时，对用户权限边界的任何手动调整都将在下次用户登录时被覆盖。 + +::: + +1. 从顶部导航栏中选择 **组织**，然后选择 **设置**。 +2. 通过点击其名称来选择登录选项。 +3. 点击 **权限边界映射** 的 **启用**。 +4. 填写表单： + +* **权限策略**：例如 `禁止许可证操作`。 +* **权限边界属性**：例如 `职位`。 +* **操作**：例如 `=`。 +* **权限边界值**：例如 `团队成员`。 + +5. 点击 **启用**。 + +现在，即使分配了 **超级管理员** 角色，所有来自 IdP 的 `职位` = `团队成员` 的用户都将受到 `禁止许可证操作` 策略的限制。 + +请注意，此权限边界映射是动态的。如果用户的职位在身份提供商中发生变化，例如从 `团队成员` 变为 `团队领导`，那么他们下次登录 API7 企业版时，他们的权限边界将自动更新。 + +## 删除登录选项 + +:::warning + +删除一个登录选项会同时删除所有使用这个登录选项导入的用户。 + +::: + +1. 在顶部导航栏中，选择**组织**，然后选择**用户**。 +2. 检查是否还有用户正在使用此登录选项。如果有，请先通知他们。 +3. 在顶部导航栏中，选择**组织**，然后选择**设置**。 +4. 单击目标登录选项的**删除**。 +5. 二次确认。 + +## 相关阅读 + +* 核心概念 + * [角色和权限策略](../key-concepts/roles-and-permission-policies.md) +* 快速入门 + * [创建自定义角色](../getting-started/create-custom-role.md) +* 开发参考 + * [权限策略操作和资源](../reference/permission-policy-action-and-resource.md) + * [权限策略示例](../reference/permission-policy-example.md) diff --git a/enterprise_versioned_docs/version-3.6.x/best-practices/upstream-ha.md b/enterprise_versioned_docs/version-3.6.x/best-practices/upstream-ha.md new file mode 100644 index 00000000..3adf259e --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/best-practices/upstream-ha.md @@ -0,0 +1,74 @@ +--- +title: 上游高可用 +slug: /best-practices/upstream-ha +--- + +当 API7 企业版向上游发送 API 请求时，如果上游系统发生故障，就会出现可用性和可靠性问题。本文档介绍上游依赖系统的高可用性策略。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 + +## 添加多个上游节点 + +使用多个上游节点可以防止单节点故障。对网关组中的上游节点所做的修改不会影响发布到其他网关组的同一服务版本。 + +1. 从侧边栏选择网关组的 **已发布服务**，然后点击要修改的服务，例如，版本为 `1.0.0` 的 `httpbin API`。 +2. 在已发布的服务下，从侧边栏选择 **上游**。 +3. 点击 **节点** > **新增节点**。 +4. 在对话框中，执行以下操作： + +* 在 **主机** 和 **端口**字段中，输入另一个 API 端点。 +* 在 **权重** 字段中，输入 `100`，与第一个节点相同。 +* 点击 **新增**。 + +## 修改负载均衡类型 + +负载均衡将网络请求分配到多个节点。这对于处理高流量的系统至关重要，可以提高性能、可扩展性和可靠性。 + +API7 网关支持多种负载均衡算法： + +* 加权轮询（WRR） +* 一致性哈希 +* 指数加权移动平均（EWMA） +* 最少连接 + +默认情况下，API7 网关支持 WRR 算法。该算法以循环模式根据一组节点的权重分配传入请求。 + +1. 从侧边栏选择网关组的 **已发布服务**，然后点击要修改的服务，例如，版本为 `1.0.0` 的 `httpbin API`。 +2. 在已发布的服务下，从侧边栏选择 **上游**。 +3. 在 **上游配置** 字段中，点击 **编辑**。 +4. 在对话框中，将 **负载均衡类型** 编辑为 `Least Connection`。 +5. 点击 **编辑**。 + +## 启用健康检查 + +健康检查是一种机制，用于根据上游节点的响应能力来确定它们是健康还是不健康。启用健康检查后，API7 企业版将只转发请求到被认为是健康的上游节点，而不转发请求到被认为是不健康的节点。 + +健康检查有两种基本方法： + +* 主动健康检查：通过主动探测节点来确定上游节点的健康状况。 +* 被动健康检查：根据节点如何响应用户请求来确定上游节点的健康状况，而无需启动额外的探测。被动检查必须与主动检查一起使用。它们不能单独使用。 + +:::info + +请确保在启用健康检查之前，你的 API 后端已经实现了健康检查的端点。 + +::: + +1. 从侧边栏选择网关组的 **已发布服务**，然后点击要修改的服务，例如，版本为 `1.0.0` 的 `httpbin API`。 +2. 在已发布的服务下，从侧边栏选择 **上游**。 +3. 在 **健康检查** 字段中，点击 **启用**。 +4. 在对话框中，执行以下操作： + +* 在 **探针协议** 字段中，选择 `HTTP`。 +* 在 **HTTP 探针路径**字段中，输入 `/health`。 +* 对其余字段使用默认值。 +* 点击 **启用**。 + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [上游](../key-concepts/upstreams.md). diff --git a/enterprise_versioned_docs/version-3.6.x/deployment/ingress-controller.md b/enterprise_versioned_docs/version-3.6.x/deployment/ingress-controller.md new file mode 100644 index 00000000..2122afdb --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/deployment/ingress-controller.md @@ -0,0 +1,111 @@ +--- +title: 在 Kubernetes 上使用 API7 Ingress Controller 进行部署 +slug: /deployment/ingress-controller +--- + +本教程将向你展示如何在 Kubernetes 上部署 API7 网关和 Ingress Controller。API7 Ingress Controller 允许你在 Kubernetes 中以声明方式配置 API7 网关。如果你不希望使用 Kubernetes 和 API7 Ingress Controller，则可以跳过本教程，从 [启动你的第一个 API](../getting-started/launch-your-first-api.md) 开始。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +2. 拥有一个正在运行的 Kubernetes 集群。 +3. 已安装 [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)。 + +## 创建和设置命名空间 + +你可以选择为资源创建一个新的命名空间并将其设置为首选命名空间，这样你就不需要在每个命令中显式指定命名空间。 + +创建一个新的命名空间 `api7` 并将其设置为首选命名空间： + +```shell +kubectl create namespace api7 && \ + kubectl config set-context --current --namespace=api7 +``` + +要验证默认命名空间是否已修改： + +```shell +kubectl config view --minify | grep namespace: +``` + +你应该会看到命名空间已设置： + +```text +namespace: api7 +``` + +## 新增网关组 + +导航到控制台： + +1. 从侧边栏选择**网关组**，然后点击**新增网关组**。 +2. 选择 **Ingress Controller** 作为**类型**。 +3. **名称**输入 `api7-ingress`。 +3. 点击**新增**。 + +## 安装 Ingress Controller + +复制生成的部署脚本并在终端中运行它。如果部署成功，你应该会看到类似于以下内容的响应： + +```text +NAME: api7-ingress +LAST DEPLOYED: Wed Jun 19 17:20:24 2024 +NAMESPACE: api7 +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +## 安装网关实例 + +导航到控制台： + +1. 从侧边栏选择**网关实例**，然后点击**新增网关实例**。 +2. 切换到**Kubernetes**选项卡。 +3. 填写命名空间和其他参数，然后点击**生成**以查看部署脚本。 +3. 在终端中运行部署脚本。 + +:::info + +[安装 API7 企业版](../getting-started/install-api7-ee.md) 时，将使用一个网关实例初始化网关组 `default`。为避免端口冲突，你可以修改新网关实例的监听端口，或移除 `default` 网关组中未使用的实例。 + +::: + +## 验证 + +检查 Pod 状态： + +```shell +kubectl get pods +``` + +你应该会看到所有 Pod 都处于 `Running` 状态： + +```text +NAME READY STATUS RESTARTS AGE +api7-ee-3-gateway-698f85d98b-jxrwp 1/1 Running 0 6m +api7-ingress-api7-ingress-controller-b4487c7c-p5qzk 1/1 Running 0 10m +``` + +检查服务： + +```shell +kubectl get services +``` + +你应该会看到类似于以下内容的响应： + +```text +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +api7-ee-3-gateway-gateway NodePort 10.96.106.11 80:32469/TCP 6m +api7-ingress-api7-ingress-controller ClusterIP 10.96.61.45 80/TCP 10m +api7-ingress-api7-ingress-controller-apisix-gateway NodePort 10.96.85.233 80:32160/TCP,443:31815/TCP 10m +kubernetes ClusterIP 10.96.0.1 443/TCP 10m +``` + +导航回控制台并选择**网关实例**，你应该会看到一个处于 `healthy` 状态的网关实例。请注意，使用 API7 Ingress Controller 创建的资源在控制台中将是只读的。 + +## 下一步 + +1. 了解如何在网关组中创建[网关实例](../getting-started/add-gateway-instance.md)。 +2. 按照[入门教程](../getting-started/launch-your-first-api.md)了解更多关于在 API7 企业版中使用 API7 Ingress Controller 的信息。 diff --git a/enterprise_versioned_docs/version-3.6.x/deployment/k8s-openshift.md b/enterprise_versioned_docs/version-3.6.x/deployment/k8s-openshift.md new file mode 100644 index 00000000..3ac59171 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/deployment/k8s-openshift.md @@ -0,0 +1,399 @@ +--- +title: 在 OpenShift 上安装 API7 企业版 +slug: /deployment/openshift +--- + +本指南将引导你完成在 OpenShift 集群上部署 API7 企业版的步骤。 + +## 架构 + +### 概述 + +API7 企业版包括两组组件： + +1. 控制面：API7 控制台、API7 DP 管理器、数据库（可以使用 RDS 代替）、其他组件。 +2. 数据面：API7 网关 + +![架构概述](https://static.apiseven.com/uploads/2024/04/12/jdit8lBM_1.png) + +### 高可用部署模式 + +![高可用部署架构图](https://static.apiseven.com/uploads/2024/04/12/71h8UOEy_2.png) + +## 前提条件 + +### 部署 OpenShift 集群 + +拥有一个正在运行的 OpenShift 集群： + +![集群概览](https://static.apiseven.com/uploads/2024/04/12/d0bHSGin_3.png) + +![集群机器池](https://static.apiseven.com/uploads/2024/04/12/HGuUkgnc_4.png) + +### 管理安全上下文约束 (SCC) + +[安全上下文约束 (SCC)](https://docs.openshift.com/container-platform/3.11/architecture/additional_concepts/authorization.html#security-context-constraints) 是 OpenShift 上的一组 API，用于管理 Pod 的安全策略约束。 + +OpenShift 中默认启用的 SCC 非常严格，要求容器中的进程对文件系统是只读的。按照[管理安全上下文约束](https://docs.openshift.com/dedicated/authentication/managing-security-context-constraints.html) 文档为 API7 企业版使用更灵活的 SCC `nonroot-v2`。 + +### 配置 OpenShift CLI + +安装 [OpenShift CLI (oc)](https://docs.openshift.com/container-platform/4.12/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli) 或从控制台下载它： + +![在控制台上下载 OpenShift CLI (oc)](https://static.apiseven.com/uploads/2024/04/12/HprnNscc_5.png) + +在控制台上找到登录命令： + +![从控制台复制登录命令](https://static.apiseven.com/uploads/2024/04/12/r4W6gsFW_6.png) + +使用你的令牌和服务器地址登录到 OpenShift 集群： + +```shell +oc login \ + --token=sha256~pesd0RAyKiKJLkkKJ4Oh2lmy4KSX9b5J6Fc24FYM2EQ \ + --server=[https://api.api7.93ew.p1.openshiftapps.com:6443](https://api.api7.93ew.p1.openshiftapps.com:6443) +```` + +:::info + +确保你的用户帐户具有 [`cluster-admin` 角色](https://docs.openshift.com/container-platform/3.11/architecture/additional_concepts/authorization.html#roles) 以执行集群管理。 + +::: + +你应该会看到类似于以下内容的响应： + +```text +Logged into "[https://api.api7.93ew.p1.openshiftapps.com:6443](https://api.api7.93ew.p1.openshiftapps.com:6443)" as "admin" using the token provided. + +You have access to 102 projects, the list has been suppressed. You can list all projects with 'oc projects' + +Using project "default". +``` + +### 创建项目 + +在控制台中创建一个项目： + +![在 OpenShift 控制台中创建项目](about:sanitized) + +或者，你可以使用 CLI 创建项目： + +```shell +oc new-project api7-enterprise-project +``` + +项目名称将用作 Kubernetes 命名空间。 + +将默认项目切换到 `api7-enterprise-project`： + +```shell +oc project api7-enterprise-project +``` + +## 安装 API7 企业版 + +### 添加 API7 Helm Chart 仓库 + +添加 API7 仓库 `https://charts.api7.ai`： + +![添加 API7 Helm Chart 仓库](about:sanitized) + +![填写 Helm Chart 仓库的详细信息](about:sanitized) + +### 安装控制面 + +选择 `Api7ee3` Helm Chart 并创建： + +![选择控制面 Helm Chart](about:sanitized) + +![安装控制面 Chart](about:sanitized) + +选择 Chart 版本： + +![选择 Chart 版本](about:sanitized) + +粘贴以下代码段以替换默认值： + +```yaml +# 如果需要进行其他自定义，请调整这些值 +postgresql: + primary: + podSecurityContext: + fsGroup: 1001020000 + containerSecurityContext: + runAsUser: 1001020000 +prometheus: + server: + podSecurityContext: + fsGroup: 1001020000 + containerSecurityContext: + runAsUser: 1001020000 +``` + +点击 **创建** 完成。你应该会看到已安装的组件： + +![完成安装](about:sanitized) + +查看所有已创建的服务： + +```shell +kubectl get svc -owide -l app.kubernetes.io/name=api7ee3 + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR +api7ee3-dashboard ClusterIP 172.30.249.55 7080/TCP 28m app.kubernetes.io/component=dashboard,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3 +api7ee3-dp-manager ClusterIP 172.30.43.83 7900/TCP,7943/TCP 28m app.kubernetes.io/component=dp-manager,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3 +``` + +### 在控制台中激活许可证 + +将控制台服务端口转发到 `localhost:7443`： + +```shell +kubectl port-forward svc/api7ee3-dashboard 7443:7443 +``` + +如果成功，你应该能够在 [https://localhost:7443](https://localhost:7443) 访问控制台。 + +使用 `admin` 作为用户名和密码登录： + +
+使用 admin/admin 登录 +
+ +然后上传你的许可证。如果你没有许可证，可以[申请 30 天试用许可证](https://api7.ai/try?product=enterprise)。 + +
+上传许可证 +
+ +选择 **激活**： + +
+激活许可证 +
+ +现在你应该会被重定向到控制台主界面。 + +### 添加控制面地址 + +在添加更多[网关实例](../key-concepts/gateway-groups.md)之前，首先配置控制面的连接地址。 + +在同一个集群中，数据面和控制面遵循 \`https://{service-name}.{namespace}.svc.cluster:7943\` 的格式，无论它们是否部署在同一命名空间下。 + +![添加控制面地址](https://static.apiseven.com/uploads/2024/08/09/Zzgc5aic_20240809-150435.jpeg) + +默认情况下，API7 网关和控制面将使用 mTLS 进行身份验证。你应该将 `https://{service-name}.{namespace}.svc.cluster:7943` 配置为控制面地址。 + +````markdown +### 安装数据面 + +#### 为 API7 网关配置 SCC + +API7 网关需要在运行时生成本地文件，包括 `nginx.conf`、日志和缓存文件。`nonroot-v2` SCC 具有所需的权限就足够了。 + +创建服务帐户： + +```shell +oc create serviceaccount api7-gateway +```` + +创建具有 `nonroot-v2` SCC 的角色： + +```shell +oc create role api7-gateway \ + --verb=use \ + --resource=scc + --resource-name=nonroot-v2 +``` + +将角色绑定到服务帐户： + +```shell +oc create rolebinding api7-gateway \ + --role=api7-gateway + --serviceaccount=api7-enterprise-project:api7-gateway +``` + +#### 生成并运行部署脚本 + +与 Apache APISIX 相比，API7 企业版引入了一个额外的逻辑分组，称为[网关组](../key-concepts/gateway-groups.md)，你可以在其中使用同一个 API7 控制台管理不同的网关实例集。 + +首先，你应该创建或选择目标网关组。在本指南中，你将使用 `default` 网关组： + +![在控制台中查找默认网关组](about:sanitized) + +接下来，选择 **添加网关实例**： + +![添加网关实例](about:sanitized) + +切换到 **Kubernetes** 选项卡并填写参数。完成后，点击**生成**以查看部署脚本。 + +![生成部署脚本](about:sanitized) + +复制生成的脚本并设置额外的 `securityContext`。该命令应类似于以下内容： + +```shell +helm repo add api7 [https://charts.api7.ai](https://charts.api7.ai) +helm repo update +cat > /tmp/tls.crt < /tmp/tls.key < /tmp/ca.crt < 80:31649/TCP 3m51s +api7-postgresql ClusterIP 172.30.215.68 5432/TCP 56m +api7-postgresql-hl ClusterIP None 5432/TCP 56m +api7-prometheus-server ClusterIP 172.30.3.68 9090/TCP 56m +api7ee3-dashboard ClusterIP 172.30.249.55 7080/TCP 56m +api7ee3-dp-manager ClusterIP 172.30.43.83 7900/TCP,7943/TCP 56m +``` + +接下来，将网关端口 `80` 转发到 `localhost:9080`： + +```shell +kubectl port-forward svc/api7-ee-3-gateway-gateway 9080:80 +``` + +### 发送请求 + +此请求收到正确的响应，这意味着安装成功。 + +```shell +curl "http://127.0.0.1:9080/anything" -i +``` + +你应该会收到一个类似于以下内容的 `HTTP/1.1 200 OK` 响应： + +```json +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "localhost", + "User-Agent": "curl/8.4.0", + "X-Amzn-Trace-Id": "Root=1-65fa9071-7506ab7b0e98d7546e3c0845", + "X-Forwarded-Host": "localhost" + }, + "json": null, + "method": "GET", + "origin": "::1, 3.1.235.149", + "url": "http://localhost/anything" +} +``` + +## 下一步 + +除了通过控制台 UI 发布服务外，API7 还提供了一个可以操作声明式配置的命令行工具，因此你可以将 API7 操作与内部 GitOps 集成。请参阅[使用 APISIX Declarative CLI (ADC) 以声明方式管理 APISIX](https://api7.ai/blog/managing-apisix-declaratively)。 + +请参阅[入门教程](../getting-started/install-api7-ee.md)以了解更多关于如何使用 ADC 的信息。 + +## 常见问题解答 + +### 如何连接到现有的 PostgreSQL？ + +在 [Helm values 文件](https://github.com/api7/api7-helm-chart/blob/main/charts/api7/values.yaml) 中配置你的数据库 DSN： + +```yaml +dashboard_configuration: + database: + dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee" + +dp_manager_configuration: + database: + dsn: "postgres://api7ee:changeme@api7-postgresql:5432/api7ee" +``` diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-group.md b/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-group.md new file mode 100644 index 00000000..9f3f9539 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-group.md @@ -0,0 +1,27 @@ +--- +title: 新增网关组 +slug: /getting-started/add-gateway-group +--- + +本教程将指导你添加一个新的 [网关组](../key-concepts/gateway-groups.md)。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 + +## 步骤 + +1. 从侧边导航栏中选择 **网关组**，然后点击 **添加网关组**。 +2. 在表单中执行以下操作： + * **类型** 选择 `API7 网关`。 + * **名称** 填写 `生产网关组`。 + * 点击 **添加**。 + +继续 [新增网关实例](./add-gateway-instance.md) 保证你新添加的网关组可以正常使用。 + +## 相关阅读 + +* 核心概念 + * [网关组与网关实例](../key-concepts/gateway-groups.md) +* 快速入门 + * [新增网关实例](add-gateway-instance.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-instance.md b/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-instance.md new file mode 100644 index 00000000..7cac4eee --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/add-gateway-instance.md @@ -0,0 +1,59 @@ +--- +title: 新增网关实例 +slug: /getting-started/add-gateway-instance +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +本教程介绍如何将网关实例添加到网关组。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. [准备一个网关组](../getting-started/add-gateway-group.md)。 + +:::info + +若使用 OpenShift 等平台，需事先授予 API7 企业版安全上下文约束 (SCC)。 + +::: + +## 步骤 + + + + +1. 从侧边栏导航选择你的目标网关组下的 **网关实例**，然后点击 **新增网关实例**。 +2. 按页面说明进行以下操作： + +* 分别设置 HTTP 端口 ID 和 HTTPS 端口 ID 为 `9080` 和 `9443`。 +* (可选) 将网关实例名称设置为 `test`。 + +4. 点击 **生成** 获取用于将网关实例添加到网关组的命令。 +5. 打开终端并运行生成的命令。 + + + + + +1. 从侧边栏导航选择你的目标网关组下的 **网关实例**，然后点击 **新增网关实例**。 +2. 按页面说明进行以下操作： + +* 设置 **Helm 发布名称** 为 `api7-ee-3-gateway`。 +* 设置 **命名空间**为 `api7-ee`。 +* 设置 **副本数** 为 `1`。 + +4. 点击 **生成** 获取用于将网关实例添加到网关组的命令或 YAML 配置文件。 +5. CLI 用户请打开终端运行生成的命令。 +6. YAML 文件用户请更新并应用你的 YAML 配置文件。 + + + + +## 相关阅读 + +* 核心概念 + * [网关组与网关实例](../key-concepts/gateway-groups.md) +* 快速入门 + * [新增网关组](add-gateway-group.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/audit-logging.md b/enterprise_versioned_docs/version-3.6.x/getting-started/audit-logging.md new file mode 100644 index 00000000..1f1f9a19 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/audit-logging.md @@ -0,0 +1,68 @@ +--- +title: 使用审计日志追踪用户操作 +slug: /getting-started/audit-logging +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +API7 企业版提供审计日志功能，用于监控和记录用户在 API7 企业版上的各项操作活动，其中涵盖用户登录控制台以及调用 API / ADC 时进行的所有操作。API7 企业版使用 token 作为身份凭证，用于验证用户或应用程序的身份；而审计日志则会记录所有涉及 token 的身份认证和授权操作，与 token 机制相辅相成，为平台的安全性提供有力保障。 + +所有用户对 API 的调用操作都会生成相应的审计日志。具有审计日志查看和下载权限的用户，可以查看这些日志的详细信息，并将其导出为 JSON 或 CSV 格式，便于进一步分析。每条审计日志包含操作时间、操作者、事件类型、被操作的资源 ID 和名称、操作者的 IP 地址以及操作来源等信息。 + +为保护日志中的敏感信息，API7 企业版制定了严格的脱敏处理机制。同时，为满足用户的合规性需求，这些审计日志默认保留 180 天。通过审计日志功能，用户可以全面掌握 API7 企业版的使用情况，及时发现并应对可能的安全隐患，从而有效提高平台的安全性和合规性。 + +## 背景介绍 + +随着对 API 接口的调用和系统操作变得日益频繁，缺乏有效的监控和记录机制容易导致出现安全隐患和操作风险。许多行业都面临着合规性管理的要求，需要对关键操作进行详细记录和审计。 + +审计日志可以详细记录用户的各种操作行为，企业可以借此及时发现异常情况，也能帮助企业快速定位问题并采取相应的安全防护措施，有效降低安全风险。同时，企业对关键操作进行详细记录和审计，能为后续的合规性审计提供依据。 + +## 前提条件 + +1. [安装 API7 企业版](../getting-started/install-api7-ee.md)。 + +2. 准备一个 `super admin` 权限的账号，或者由 `super admin` 配置了查看/下载审计日志权限的账号。 + +## 案例 1 ：审计 30 天内创建服务的日志 + +1. 进入组织分类下的审计日志模块。 + +2. 可以通过在事件中选择 **Add Service**，操作者选择对应的用户，如运维人员 `Ops`。 + +3. 在顶部限定日期，选择 **30 天**。 + +4. 点击 **搜索**，即可显示最近 30 天内 `Ops` 用户创建服务的所有日志记录。 + +5. 点击 **详情** 即可查看对应事件的操作日志。每一条日志记录中包含“时间”、“操作者”、“事件”、“资源 ID”、“资源名称”、“IP 地址”、“来源”这些信息。 + +6. 点击 **导出**，选择 **JSON** 或 **CSV** 格式，即可下载。 + +以下是此用例的互动演示。点击并按照演示中的步骤操作，将更好地理解如何在 API7 企业版中使用审计日志功能。 + + + +## 案例 2：审计 7 天内 `httpbin` 服务的日志 + +1. 进入模板复制 `httpbin` 服务的 ID：`fb2a549b-f5a8-46ee-b9c6-b0cc167ec5ae`。 + +2. 进入组织分类下的 **审计日志** 模块，粘贴复制的服务 ID 至 **资源 ID** 栏。 + +3. 在顶部限定日期，选择 **7 天**。 + +4. 点击 **搜索**，即可显示最近 7 天内 `httpbin` 服务的所有日志记录。 + +5. 点击 **详情** 即可查看对应事件的操作日志。每一条日志记录中包含“时间”、“操作者”、“事件”、“资源 ID”、“资源名称”、“IP 地址”、“来源”这些信息。 + +6. 点击 **导出**，选择 **JSON** 或 **CSV** 格式，即可下载。 + +以下是此用例的互动演示。点击并按照演示中的步骤操作，将更好地理解如何在 API7 企业版中使用审计日志功能。 + + + +## 分析日志数据 + +除了基本的查询和筛选功能外，API7 企业版还支持将审计日志导出为 JSON 或 CSV 格式的文件。推荐把这些数据导入专门的分析平台，如 ELK Stack（Elasticsearch、Logstash、Kibana）进行进一步的分析和处理，如使用数据分析工具进行数据挖掘和可视化展示等。 + +## 结论 + +API7 企业版的日志审计功能通过提供全面的日志记录和实时分析能力，帮助管理员快速定位问题根源并采取相应的修复措施。此外，该功能还为企业的信息安全和合规性管理提供了有力支持。 diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/canary-upstream.md b/enterprise_versioned_docs/version-3.6.x/getting-started/canary-upstream.md new file mode 100644 index 00000000..71048f5f --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/canary-upstream.md @@ -0,0 +1,551 @@ +--- +title: 灰度流量 +slug: /getting-started/canary-upstream +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +灰度流量功能可以让你使用一小部分流量安全地测试新的上游，同时将大部分流量保持在默认上游。 + +:::note + +* 灰度流量不同于灰度发布，因为 API/服务的版本保持不变。灰度发布指的是同一个 API/服务同时有两个版本都在运行并可被调用。 + +::: + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. [在网关组上有一个运行的 API](../getting-started/launch-your-first-api.md)。 + +## 按百分比切分流量 + +在这个示例中，你将把 10% 的流量引导到一个新的上游。其余 90% 将继续转发到默认上游。测试新的上游后，请考虑使用新值重写默认上游配置，并删除插件以停止灰度过程。 + + + + +1. 从侧边导航栏中选择网关组的 **已发布服务**，然后单击要修改的服务，例如版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布服务下，从侧边导航栏中选择 **上游**。 +3. 在 **连接配置** 模块中，单击 **编辑**，选择 `使用节点主机`，然后单击 **保存**。 + > 注意：由于 `mock.api7.ai` 强制执行 HTTPS 访问，因此上游需要配置为使用端口 `443` 才能访问 HTTPS 端点。请根据您的使用情况相应地调整 `pass_host` 参数。 +4. 单击 **添加上游**。 +5. 在对话框中，执行以下操作： + * 在 **上游名称** 字段中，输入 `newupstream`。 + * 单击 **添加节点** 以调整节点的主机指向新后端。例如，使用 `mock.api7.ai` 作为主机和 `443` 作为端口。 + * 单击 **添加**。 +6. 单击上游标题（在 **操作** 按钮下）中的 **查看 ID** 并复制以供使用。 +7. 在已发布服务下，从侧边导航栏中选择 **插件**。 +8. 单击 **新增插件**。 +9. 搜索 `traffic-split` 插件，然后单击 **新增**。 +10. 在对话框中，执行以下操作： + +* 将以下配置输入到 **JSON Editor**: + + ```json + { + "rules": [ + { + "weighted_upstreams": [ + { + "upstream_id": new_upstream_id, // Use upstream id, not upstream name + "weight": 1 + }, + { + "weight": 9 + } + ] + } + ] + } + ``` + +* 点击 **新增**。 + +### 验证 + +通过发送 10 个请求来验证灰度规则： + + ```bash + for i in {1..10}; do "curl 127.0.0.1:9080/headers"; done + ``` + + 其中大约 9 次请求会被转发到默认上游的地址 `httpbin.org`，然后你应该能收到如下类似的响应： + + ```json + { + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } + } + ``` + + 剩下 1 次请求会被转发到新上游的地址`mock.api7.ai`： + + ```json + { + "headers": { + "accept": "*/*", + "accept-encoding": "gzip, br", + "cf-connecting-ip": "159.89.160.194", + "cf-ipcountry": "IN", + "cf-ray": "888e28733f9604aa", + "cf-visitor": "{\"scheme\":\"https\"}", + "connection": "Keep-Alive", + "content-type": "application/json", + "host": "mock.api7.ai", + "user-agent": "curl/7.74.0", + "x-application-owner": "API7.ai", + "x-forwarded-for": "127.0.0.1", + "x-forwarded-host": "127.0.0.1", + "x-forwarded-port": "9080", + "x-forwarded-proto": "https", + "x-real-ip": "159.89.160.194", + "X-Application-Owner": "API7.ai", + "Content-Type": "application/json" + } + } + ``` + + + + + +更新你的 ADC 配置文件（`adc.yaml`）以包含新上游。完整的配置如下所示： + + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: Test Group + scheme: https + nodes: + - host: httpbin.org + port: 443 + weight: 100 + plugins: + api7-traffic-split: + rules: + - canary_upstreams: + - upstream_name: newupstream + weight: 10 + - weight: 90 + upstreams: + - name: newupstream + nodes: + - host: mock.api7.ai + port: 443 + weight: 100 + scheme: https + routes: + - uris: + - /headers + name: getting-started-headers + methods: + - GET +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + +发送 10 次请求以验证灰度上游： + +```bash +for i in {1..10}; do curl "127.0.0.1:9080/headers"; done +``` + +其中大约 9 次请求会被转发到默认上游的地址 `httpbin.org`，然后你应该能收到如下类似的响应： + +```json +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +剩下 1 次请求会被转发到灰度上游的地址`mock.api7.ai`： + +```json +{ + "headers": { + "accept": "*/*", + "accept-encoding": "gzip, br", + "cf-connecting-ip": "159.89.160.194", + "cf-ipcountry": "IN", + "cf-ray": "888e28733f9604aa", + "cf-visitor": "{\"scheme\":\"https\"}", + "connection": "Keep-Alive", + "content-type": "application/json", + "host": "mock.api7.ai", + "user-agent": "curl/7.74.0", + "x-application-owner": "API7.ai", + "x-forwarded-for": "127.0.0.1", + "x-forwarded-host": "127.0.0.1", + "x-forwarded-port": "9080", + "x-forwarded-proto": "https", + "x-real-ip": "159.89.160.194", + "X-Application-Owner": "API7.ai", + "Content-Type": "application/json" + } +} +``` + +现在，将权重更新为 `50:50`，以允许一半的流量路由到灰度上游： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: Test Group + scheme: https + nodes: + - host: httpbin.org + port: 443 + weight: 100 + plugins: + api7-traffic-split: + rules: + - canary_upstreams: + - upstream_name: newupstream + weight: 50 + - weight: 50 + upstreams: + - name: newupstream + nodes: + - host: mock.api7.ai + port: 443 + weight: 100 + scheme: https + routes: + - uris: + - /headers + name: getting-started-headers + methods: + - GET +``` + +发送更多请求以测试灰度上游，直到它达到你的业务预期。最后，使用当前上游的值更新默认上游，完成灰度流量转移： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: Test Group + scheme: https + nodes: + - host: mock.api7.ai + port: 443 + weight: 100 + routes: + - uris: + - /headers + name: getting-started-headers + methods: + - GET +``` + + + + +## 按请求头转移流量 + +在本例中，你将把带有请求头 `version = test` 的请求引导到新上游，而其余流量将继续流向默认上游。灰度规则适用于服务中的所有路由，不能应用于单个路由。 + + + + +1. 从侧边导航栏中选择网关组的 **已发布服务**，然后单击要修改的服务，例如版本为 `1.0.0` 的 `httpbin`。 +2. 在已发布服务下，从侧边导航栏中选择 **上游**。 +3. 在 **连接配置** 模块中，单击 **编辑**，选择 `使用节点主机`，然后单击 **保存**。 + > 注意：由于 `mock.api7.ai` 强制执行 HTTPS 访问，因此上游需要配置为使用端口 `443` 才能访问 HTTPS 端点。请根据您的使用情况相应地调整 `pass_host` 参数。 +4. 单击 **添加上游**。 +5. 在对话框中，执行以下操作： + * 在 **上游名称** 字段中，输入 `newupstream`。 + * 单击 **添加节点** 以调整节点的主机指向新后端。例如，使用 `mock.api7.ai` 作为主机和 `443` 作为端口。 + * 单击 **添加**。 +6. 单击上游标题（在 **操作** 按钮下）中的 **查看 ID** 并复制以供使用。 +7. 在已发布服务下，从侧边导航栏中选择 **插件**。 +8. 单击 **新增插件**。 +9. 搜索 `traffic-split` 插件，然后单击 **新增**。 +10. 在对话框中，执行以下操作： + +* 将以下配置输入到 **JSON Editor**: + + ```json + { + "rules": [ + { + "match": [ + { + "vars": [ + ["version","==","test"] + ] + } + ], + "weighted_upstreams": [ + { + "upstream_id": new_upstream_id, // Use upstream id, not upstream name + "weight": 1 + }, + { + "weight": 9 + } + ] + } + ] + } + ``` + +* 点击 **新增**。 + +### 验证 + +通过发送多个请求来验证灰度规则： + + 发送一个带有正确请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers -H "version:test" + ``` + 你应该能收到来自新上游的如下类似的响应： + + ```json + { + "headers": { + "accept": "*/*", + "accept-encoding": "gzip, br", + "cf-connecting-ip": "159.89.160.194", + "cf-ipcountry": "IN", + "cf-ray": "888e28733f9604aa", + "cf-visitor": "{\"scheme\":\"https\"}", + "connection": "Keep-Alive", + "content-type": "application/json", + "host": "mock.api7.ai", + "user-agent": "curl/7.74.0", + "x-application-owner": "API7.ai", + "x-forwarded-for": "127.0.0.1", + "x-forwarded-host": "127.0.0.1", + "x-forwarded-port": "9080", + "x-forwarded-proto": "https", + "x-real-ip": "159.89.160.194", + "X-Application-Owner": "API7.ai", + "Content-Type": "application/json" + } + } + ``` + + 发送一个带有错误请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers -H "version:new" + ``` + + 你应该能收到来自默认上游的如下类似的响应： + + ```json + { + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } + } + ``` + + 发送一个不带请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers + ``` + + 你应该能收到来自默认上游的如下类似的响应： + + ```json + { + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } + } + ``` + + + + + +更新你的 ADC 配置文件 (`adc.yaml`) 以包含新上游。完整的配置如下所示： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: default + scheme: https + nodes: + - host: httpbin.org + port: 443 + weight: 100 + plugins: + api7-traffic-split: + rules: + - canary_upstreams: + - upstream_name: newupstream + weight: 100 + match: + - exprs: + - - http_version + - == + - test + upstreams: + - name: newupstream + nodes: + - host: mock.api7.ai + port: 443 + weight: 100 + scheme: https + routes: + - uris: + - /headers + name: getting-started-headers + methods: + - GET +``` + +将配置同步到 API7 网关： + +```shell +adc sync -f adc.yaml +``` + +发送一个带有正确请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers -H "version:test" + ``` + 你应该能收到来自新上游的如下类似的响应： + + ```json + { + "headers": { + "accept": "*/*", + "accept-encoding": "gzip, br", + "cf-connecting-ip": "159.89.160.194", + "cf-ipcountry": "IN", + "cf-ray": "888e28733f9604aa", + "cf-visitor": "{\"scheme\":\"https\"}", + "connection": "Keep-Alive", + "content-type": "application/json", + "host": "mock.api7.ai", + "user-agent": "curl/7.74.0", + "x-application-owner": "API7.ai", + "x-forwarded-for": "127.0.0.1", + "x-forwarded-host": "127.0.0.1", + "x-forwarded-port": "9080", + "x-forwarded-proto": "https", + "x-real-ip": "159.89.160.194", + "X-Application-Owner": "API7.ai", + "Content-Type": "application/json" + } + } + ``` + + 发送一个带有错误请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers -H "version:new" + ``` + + 你应该能收到来自默认上游的如下类似的响应： + + ```json + { + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } + } + ``` + + 发送一个不带请求头的请求： + + ```bash + curl 127.0.0.1:9080/headers + ``` + + 你应该能收到来自默认上游的如下类似的响应： + + ```json + { + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } + } + ``` + +使用当前上游的值更新默认上游，完成灰度流量转移： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: Test Group + scheme: https + nodes: + - host: mock.api7.ai + port: 443 + weight: 100 + routes: + - uris: + - /headers + name: getting-started-headers + methods: + - GET +``` + + + + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [上游](../key-concepts/upstreams.md) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/create-custom-role.md b/enterprise_versioned_docs/version-3.6.x/getting-started/create-custom-role.md new file mode 100644 index 00000000..ff16512a --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/create-custom-role.md @@ -0,0 +1,157 @@ +--- +title: 创建自定义角色 +slug: /getting-started/create-custom-role +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +API7 企业版默认配置了一个锁定的、内置的 `超级管理员` 角色和策略，以提供初始设置的完全访问权限。默认的 `admin` 账户永久绑定到此角色，以便在紧急情况下进行恢复。 + +通过自定义角色，你可以创建一个适合你特定需求的精细权限系统。本教程将指导你在 API7 企业版中定义自定义角色的过程，让你能够更精确地管理访问控制。 + +本教程展示了一个具有生产网关组只读访问权限和测试网关组完全访问权限（查看和编辑）的自定义角色。你将完成以下步骤： + +1. 创建两个权限策略，一个用于定义生产网关组的只读权限，另一个用于定义测试网关组的完全访问权限。 +2. 创建一个名为 `开发团队成员` 的自定义角色，并将其关联到上述两个权限策略。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 有两个[网关组](./add-gateway-group.md)用于测试和生产环境，每个组中至少有一个网关实例。 +3. 在两个网关组中发布一个服务，用于验证。 + +## 创建权限策略 + +### 创建生产权限策略 + +1. 从顶部导航栏中选择 **组织**，然后选择 **权限策略**。 +2. 点击 **添加权限策略**。 +3. 在表单中执行以下操作： + * **名称** 填写 `生产网关组只读`。 + * **策略编辑器** 输入JSON： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}" // 使用网关组 ID 来匹配资源 + ], + "actions": [ // 列出所有查看类权限 + "gateway:GetGatewayGroup", + "gateway:GetGatewayInstance", + "gateway:GetConsumer", + "gateway:GetSSLCertificate", + "gateway:GetGlobalPluginRule", + "gateway:GetPluginMetadata", + "gateway:GetServiceRegistry", + "gateway:GetPublishedService" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>" // 查看指定网关组上所有已发布服务 + ], + "actions": [ + "gateway:GetPublishedService" + ], + "effect": "allow" + } + ] + } + ``` + + 你也可以使用通配符来编写： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group ID}" // 使用网关组 id 来匹配资源 + ], + "actions": [ // 匹配所有包含 "Get" 的权限 + "<.*>Get<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>" // 查看指定网关组上所有已发布服务 + ], + "actions": [ + "gateway:GetPublishedService" + ], + "effect": "allow" + } + ] + } + ``` + + * 点击 **新增**。 + +### 创建测试权限策略 + +1. 从顶部导航栏中选择 **组织**，然后选择 **权限策略**。 +2. 点击 **添加权限策略**。 +3. 在表单执行以下操作： + * **名称** 填写 `测试网关组完全访问`。 + * **策略编辑器** 输入 JSON： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}}" // 使用网关组 ID 来匹配资源 + ], + "actions": [ // 包含所有网关组相关权限 + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>" // 对指定网关组上所有已发布服务的完全访问权限 + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] + } + ``` + + * 点击 **新增**。 + +## 创建自定义角色 + +1. 从顶部导航栏中选择 **组织**，然后选择 *角色**。 +2. 点击 **添加自定义角色**。 +3. 在表单中执行以下操作： + - **名称** 填写 `开发团队成员`。 + - （可选）**描述** 填写 `生产网关组只读访问权限和测试网关组完全访问权限（查看和编辑）`。 + - 点击 **新增**。 +4. 在角色详情页面，点击 **关联策略**。 +5. 选择 `生产网关组只读` 和 `测试网关组完全访问`。 +6. 点击 **提交**。 + +## 验证自定义角色 + +1. 按照教程 [更新用户角色](rbac.md) 将 `开发团队成员` 分配给另一个用户，例如 `Tom`。 +2. 让 Tom 登录并验证他的权限。 + +## 相关阅读 + +* 核心概念 + * [角色和权限策略](../key-concepts/roles-and-permission-policies.md) +* 快速入门 + * [更新用户角色](../getting-started/rbac.md) +* 最佳实践 + * [设计自定义角色系统](../best-practices/design-custom-role-system.md) +* 开发参考 + * [权限策略操作和资源](../reference/permission-policy-action-and-resource.md) + * [权限策略示例](../reference/permission-policy-example.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/deploy-resources-on-k8s.md b/enterprise_versioned_docs/version-3.6.x/getting-started/deploy-resources-on-k8s.md new file mode 100644 index 00000000..07e013eb --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/deploy-resources-on-k8s.md @@ -0,0 +1,114 @@ +--- +title: 在 Kubernetes 上部署网关和 Ingress Controller +slug: /getting-started/kubernetes-api7-ingress-controller +--- + +本教程将向你展示如何在 Kubernetes 上部署 API7 网关和 Ingress Controller。API7 Ingress Controller 允许你在 Kubernetes 中以声明方式配置 API7 网关。 + +如果你不希望使用 Kubernetes 和 API7 Ingress Controller，你可以跳过本教程，开始[创建一个简单的 API](./launch-your-first-api.md)。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 准备好一个运行中的 Kubernetes 集群。 +3. 安装 [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)。 + +## 创建并设置命名空间 + +你可以选择为资源创建一个新的命名空间，并将其设置为首选命名空间，这样就不需要在每个命令中明确指定命名空间。 + +创建一个新的命名空间 `api7` 并将其设置为首选命名空间： + +```shell +kubectl create namespace api7 && \ + kubectl config set-context --current --namespace=api7 +``` + +验证默认命名空间是否已被成功修改： + +```shell +kubectl config view --minify | grep namespace: +``` +你应该能看到命名空间已经被设置： + +```text +namespace: api7 +``` + +## 新增一个网关组 + +打开控制台: + +1. 在左侧菜单中选择 **网关组**，然后下拉弹出网关组列表，点击 **新增网关组**。 +2. 在新增网关组对话框中，执行如下操作： + 1. **网关类型** 选择 **Ingress Controller**。 + 2. **名称** 输入 `api7-ingress`。 + 3. 点击 **新增**。 + +## 安装 Ingress Controller + +复制生成的部署脚本，然后在终端中运行它。如果部署成功，你应该会看到类似以下内容的响应： + +```text +NAME: api7-ingress +LAST DEPLOYED: Wed Jun 19 17:20:24 2024 +NAMESPACE: api7 +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +## 安装网关实例 + +打开控制台： + +1. 在左侧 **网关组** 下的子菜单中，选择 **网关实例**， 然后点击 **新增网关实例**。 +2. 切换到 **Kubernetes** 栏。 +3. 填写命名空间及其他参数，然后点击 **生成** 来获取部署脚本。 +3. 在终端中运行部署脚本。 + +:::info + +当你完成 [安装 API7 企业版](./install-api7-ee.md) 教程后，会得到一个默认的网关组，里面会有一个部署好的网关实例。为了避免端口冲突，你可以修改新网关实例的监听端口，或者在默认网关组中移除掉这个没有使用的网关实例。 + +::: + +## 验证 + +1. 检查 pod 状态： + +```shell +kubectl get pods +``` + +你应该可以看到所有 pod 都处于 `Running` 状态： + +```text +NAME READY STATUS RESTARTS AGE +api7-ee-3-gateway-698f85d98b-jxrwp 1/1 Running 0 6m +api7-ingress-api7-ingress-controller-b4487c7c-p5qzk 1/1 Running 0 10m +``` + +2. 检查服务： + +```shell +kubectl get services +``` + +你应该会看到类似以下内容的响应： + +```text +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +api7-ee-3-gateway-gateway NodePort 10.96.106.11 80:32469/TCP 6m +api7-ingress-api7-ingress-controller ClusterIP 10.96.61.45 80/TCP 10m +api7-ingress-api7-ingress-controller-apisix-gateway NodePort 10.96.85.233 80:32160/TCP,443:31815/TCP 10m +kubernetes ClusterIP 10.96.0.1 443/TCP 10m +``` + +回到控制台，在左侧 **网关组** 下的子菜单中，选择 **网关实例**，你应该能看到一个 `healthy` 状态的网关实例。请注意，通过 API7 Ingress Controller 创建的资源，在控制台中都是只读的。 + +## 相关阅读 + +- 快速入门 + - [新增网关实例](./add-gateway-instance.md) + - [创建一个简单的 API](./launch-your-first-api.md) \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/install-api7-ee.md b/enterprise_versioned_docs/version-3.6.x/getting-started/install-api7-ee.md new file mode 100644 index 00000000..9cd66b4e --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/install-api7-ee.md @@ -0,0 +1,72 @@ +--- +title: 安装指南 +slug: /getting-started/install-api7-ee +--- + +本教程将指导你使用快速入门脚本在 Docker 中安装 API7 企业版。 + +安装将包括 [API7 企业版组件](../introduction/api7-ee-architecture.md): 数据面、控制面、控制台以及用于管理配置和监控的外部组件 PostgreSQL 和 Prometheus。 + +:::tip + +本教程提供了一个包含 PostgreSQL 和 Prometheus 的容器化一体式解决方案，用于概念验证 (PoC) 测试。你无需提前准备好数据库与监控，从而简化了你的 PoC 流程。 + +对于生产环境部署，API7 企业版还支持 MySQL 和 OceanBase 来代替 PostgreSQL。请[联系 API7 专家](https://api7.ai/contact)获取高可用性和可扩展性解决方案。 + +::: + +## 前提条件 + +- 安装 [Docker](https://docs.docker.com/get-docker/) 和 [Docker Compose](https://docs.docker.com/compose/install) 。3.10.0-327 或更早版本不兼容，建议使用 3.10.0-927 或更高版本。 +- 安装 [cURL](https://curl.se/)。 +- 获取为期 30 天的[免费试用许可证](https://api7.ai/try?product=enterprise)。 +- 操作系统：Linux CentOS 7.2 或更早版本不兼容，建议使用 Linux CentOS 7.6 或更高版本。 + +## 安装 API7 企业版 + +```bash +curl -sL "https://run.api7.ai/api7/quickstart" | bash +``` + +你应该看到如下类似响应： + +```bash +✔ Container api7-ee-postgresql +✔ Container api7-ee-prometheus +✔ Container api7-ee-api7-ee-dashboard +✔ Container api7-ee-api7-ee-dp-manager +✔ Container api7-ee-api7-ee-gateway +... +✔ API7-EE is ready! + +API7-EE Listening: Dashboard(https://192.168.2.102:7443), Control Plane Address(http://192.168.2.102:7900, https://192.168.2.102:7943), Gateway(http://192.168.2.102:9080, https://192.168.2.102:9443) +API7-EE Listening: Dashboard(https://26.26.26.1:7443), Control Plane Address(http://26.26.26.1:7900, https://26.26.26.1:7943), Gateway(http://26.26.26.1:9080, https://26.26.26.1:9443) +If you want to access Dashboard with HTTP Endpoint(:7080), you can turn server.listen.disable to false in dashboard_conf/conf.yaml, then restart dashboard container +``` + +## 激活 API7 企业版 + +1. 访问 API7 企业版控制台 `https://{your_inet_ip_addr}:7443`，使用默认用户名 `admin` 和密码 `admin` 登录。 + +:::info + +你也可以通过 `https://localhost:7443/login` 访问控制台。然而，控制台中后续生成的部署脚本将默认使用 `localhost` 作为 IP 地址，这可能导致在 Kubernetes 上部署 API7 网关和 Ingress Controller 时产生网络连接问题。 + +::: + +2. 选择要上传的许可证，然后单击 **上传** 激活 API7 企业版。 + +## 终止 API7 企业版 + +如果已完成 API7 企业版的测试，可以在 `api7-ee` 目录下使用以下命令终止 API7 企业版： + +```bash +bash run.sh stop +``` + +## 后续步骤 + +1. 如果你想在 Kubernetes 上部署 API7 网关并使用 Ingress Controller，请参阅[在 Kubernetes 上部署网关和 Ingress Controller](./deploy-resources-on-k8s.md)。 +2. 按照“快速入门”了解更多关于使用 API7 企业版的信息。 +3. 了解 API7 企业版[高可用部署](../high-availability/overview.md)。 +4. [联系 API7 专家](https://api7.ai/contact)，开始在生产环境中使用 API7 企业版。 diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/launch-your-first-api.md b/enterprise_versioned_docs/version-3.6.x/getting-started/launch-your-first-api.md new file mode 100644 index 00000000..69cbfd3f --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/launch-your-first-api.md @@ -0,0 +1,239 @@ +--- +title: 创建一个简单的 API +slug: /getting-started/launch-your-first-api +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +本教程介绍如何创建一个简单的 API 并对其进行验证。你将完成以下步骤： + +1. 创建指向 `httpbin.org` 的[服务](../key-concepts/services)，并为其创建[路由](../key-concepts/routes)和[上游](../key-concepts/upstreams)。 +2. 通过发送一个请求，验证创建的 API 是否正常工作。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 确保网关组中至少有一个网关实例。 + +## 启动一个示例上游服务 + +如果你想在 Kubernetes 上运行 API7 企业版，你需要将在本节中将一个 `httpbin` 应用部署到你的 Kunbernetes 集群中作为示例上游服务。否则，请跳到下一节，直接使用托管的 `httpbin` 应用作为上游。 + +启动一个 [httpbin](https://hub.docker.com/r/kennethreitz/httpbin/) 应用： + +```shell +kubectl run httpbin --image kennethreitz/httpbin --port 80 +``` + +你应该会看到类似以下内容的响应： + +```shell +pod/httpbin created` +``` + +通过服务暴露 `httpbin` 应用的 `80` 端口： + +```shell +kubectl expose pod httpbin --port 80 +``` + +你应该会看到类似以下内容的响应： + +```shell + `service/httpbin exposed` +``` + +## 创建服务与路由 + + + + + +

创建服务

+ +1. 在左侧菜单选择目标网关组下的 **已发布服务** 菜单，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在新增服务表单页中, 执行以下操作： + +* **名称** 填写 `httpbin`。 +* **服务类型** 选择 `HTTP （七层代理）`。 +* **上游 Scheme** 选择 `HTTP`。 +* **如何找到上游** 选择 `使用节点`。 +* 点击 **新增节点**。 +* 在新增节点对话框中，执行以下操作： + * **主机** 填写 `httpbin.org`。 + * **端口** 填写 `80`。 + * **权重** 填写 `100`。 +* 点击 **新增**。 此时创建出的新服务处于“无版本”状态。 + +

创建一条路由

+ +1. 进入刚才创建好的服务，然后点击 **新增路由**。 +2. 在新增路由对话框中，执行以下操作： + +* **名称** 填写 `getting-started-ip`。 +* **路径** 填写 `/ip`。 +* **HTTP 方法** 选择 `GET`。 +* 点击 **新增**。 + + + + + +创建如下的配置文件： + +```yaml title="adc.yaml" +services: + - name: httpbin + upstream: + name: default + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /ip + name: getting-started-ip + methods: + - GET +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc.yaml +``` + + + + + +创建一个包含了 API7 Ingress Controller 路由自定义资源的配置文件： + +```yaml +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: httpbin-route + namespace: api7 +spec: + http: + - name: httpbin-route + match: + paths: + - /ip + backends: + - serviceName: httpbin + servicePort: 80 +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f httpbin-route.yaml +``` + +你应该会看到类似以下内容的响应： + +```text +apisixroute.apisix.apache.org/httpbin-route created +``` + + + + + +## 验证 API + + + + + +向刚才创建好的路由发送 API 请求： + +```bash +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似以下内容的响应： + +```text +{ + "origin": "127.0.0.1" +} +``` + + + + + +向刚才创建好的路由发送 API 请求： + +```bash +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似以下内容的响应： + +```text +{ + "origin": "127.0.0.1" +} +``` + + + + + +1. 打开控制台，在默认网关组的 **已发布服务** 菜单中，你应该能看到一个叫做 `api7_httpbin_80` 的服务。 +2. 将这个服务的端口通过端口转发的方式在你的本地机器上暴露： + +```shell +kubectl port-forward svc/api7-ingress-api7-ingress-controller-apisix-gateway 9080:80 & +``` + +上述命令会在后台运行，将 `api7-ingress-api7-ingress-controller-apisix-gateway` 服务的 `80` 端口 映射到本地机器的 `9080` 端口。 + +3. 向刚才创建好的路由发送 API 请求： + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似以下内容的响应： + +```text +{ + "origin": "127.0.0.1" +} +``` + + + + + +恭喜你，现在你的第一个 API 已经成功运行。 + +## 相关阅读 + +* 快速入门 + * [发布服务版本](publish-service.md) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/license.md b/enterprise_versioned_docs/version-3.6.x/getting-started/license.md new file mode 100644 index 00000000..e49bda49 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/license.md @@ -0,0 +1,17 @@ +--- +title: 许可证管理 +slug: /getting-started/license +--- + +API7 企业版提供 [30 天免费试用许可证](https://api7.ai/try?product=enterprise)。你可以使用该许可证配置 API 管理平台的功能、容量限制和支持条款。 + +## 更新许可证 + +许可证有一个基于购买条款的到期日。确保在到期前续订许可证，以避免服务中断和无法使用功能。到期日临近时，API7 控制台将显示续订通知。请联系我们的专家购买续期服务。 + +要续订新许可证，请按照以下步骤操作： + +1. 从顶部导航栏选择 **组织**，然后选择 **许可证**。 +2. 单击 **编辑** 图标。 +3. 选择要上传的许可证，然后单击 **上传**。 +4. 确认新的有效期，然后单击 **更新**。 diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/proxy-l4-traffic.md b/enterprise_versioned_docs/version-3.6.x/getting-started/proxy-l4-traffic.md new file mode 100644 index 00000000..c5ad18f7 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/proxy-l4-traffic.md @@ -0,0 +1,247 @@ +--- +title: 转发四层流量 +slug: /getting-started/proxy-l4-traffic +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +API7 网关除了处理应用层（L7）流量外，还可以处理传输层（L4）TCP 和 UDP 流量。 + +本教程将演示如何配置 [四层路由](../key-concepts/stream-routes.md) 在客户端和 MySQL 服务器之间代理 L4 流量。 + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 网关组中至少有一个 [网关实例](./add-gateway-instance.md)。 +3. 安装 [MySQL 客户端](https://dev.mysql.com/doc/refman/8.4/en/installing.html) 以验证四层路由。 + +## 启动 MySQL 服务器 + + + + + +如果你在 Docker 中安装了网关实例并使用 Dashboard 或 ADC 进行配置，请在默认的 API7 企业版网络 `api7-ee_api7` 中启动 MySQL 服务器： + +```shell +docker run -d \ + --name mysql \ + --network=api7-ee_api7 \ + -p 3306:3306 \ + -e MYSQL_ROOT_PASSWORD=password \ + mysql:8.4 \ + mysqld --mysql-native-password=ON +``` + + + + + +如果你在 Kubernetes 上安装了网关实例并使用 Ingress Controller 进行配置，请在 Kubernetes 上启动 MySQL 服务器： + +```shell +kubectl run mysql --image mysql:8.4 --port 3306 --env="MYSQL_ROOT_PASSWORD=password" +``` + +通过服务暴露服务器端口： + +```shell +kubectl expose pod mysql --port 3306 +``` + + + + +## 添加具有四层路由的服务 + + + + +1. 从侧导航栏中选择网关组的 **已发布服务**，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在表单中执行以下操作： + +* **名称** 填写 `MySQL`。 +* **服务类型** 选择 `Stream(四层代理)`。 +* **上游 Scheme** 选择`TCP`。 +* **如何找到上游** 选择`使用节点`。 +* 点击**新增节点**。 +* 在表单中执行以下操作： + * **主机** 填写 `127.0.0.1`。 + * **端口** 填写 `3306`。 + * **权重** 使用默认值 `100`。 + * 点击 **新增**。这将新建一个 “无版本” 状态的新服务。 + +5. 在服务内，点击 **新增四层路由**。 +6. 在表单中执行以下操作： + +* **名称** 填写 `stream-route-mysql`。 +* **服务器地址** 填写 `127.0.0.1`。 +* 在**服务器端口** 填写 `2000`。 +* 点击 **新增**。 + + + + + +要使用 ADC 创建四层路由，请使用以下配置： + +```yaml title="adc.yaml" +services: + - name: MySQL + upstream: + name: default + scheme: tcp + nodes: + - host: 127.0.0.1 + port: 3306 + weight: 100 + stream_routes: + - name: stream-route-mysql + server_addr: 127.0.0.1 + server_port: 2000 +``` + +将配置同步到 API7 企业版： + +```shell +adc sync -f adc.yaml +``` + + + + + + +创建一个 Kubernetes manifest 文件，使用 ApisixRoute 自定义资源来配置一个四层路由： + +```yaml title="stream-route.yaml" +apiVersion: apisix.apache.org/v2 +kind: ApisixRoute +metadata: + name: stream-route-mysql + namespace: api7 +spec: + stream: + - name: stream-route-mysql + protocol: TCP + match: + ingressPort: 2000 + backend: + serviceName: mysql + servicePort: 3306 +``` + +将配置应用到你的集群： + +```shell +kubectl apply -f stream-route.yaml +``` + +你应该能看到如下类似的响应： + +```text +apisixroute.apisix.apache.org/stream-route-mysql created +``` + + + + + +## 验证四层路由 + + + + + +如果你在 Docker 中安装了网关实例并使用控制台或 ADC 进行配置，在继续验证步骤之前，请确保将服务器端口 `2000` 暴露给宿主机（`-p2000:2000`）。 + + + + + +如果你已经在 Kubernetes 上安装了网关实例，并使用 Ingress Controller 进行配置，那么要添加服务端口，你需要编辑对应的服务。 + +```shell +kubectl edit svc/api7-ee-3-gateway-gateway +``` + +为 MySQL 添加服务端口： + +```yaml +spec: + ports: + ... + # highlight-start + - name: apisix-gateway-mysql + port: 2000 + protocol: TCP + targetPort: 2000 + # highlight-end + ... +``` + +为服务转发端口 `2000` ： + +```shell +kubectl port-forward svc/api7-ee-3-gateway-gateway 2000:2000 & +``` + + + + + +使用 MySQL 客户端通过 API7 Gateway 与 MySQL 服务器建立连接。以 root 身份连接，并使用之前配置的密码。 + +```shell +mysql --host=127.0.0.1 --port=2000 -u root -p +``` + +你应该会看到如下的 MySQL 提示符： + +```text +Welcome to the MySQL monitor. Commands end with ; or \g. +Your MySQL connection id is 9 +Server version: 8.4.0 MySQL Community Server - GPL + +Copyright (c) 2000, 2024, Oracle and/or its affiliates. + +Oracle is a registered trademark of Oracle Corporation and/or its +affiliates. Other names may be trademarks of their respective +owners. + +Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. + +mysql> +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [路由](../key-concepts/routes.md) + * [上游](../key-concepts/upstreams.md) +* 快速入门 + * [发布服务版本](publish-service.md) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md new file mode 100644 index 00000000..70a6098c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md @@ -0,0 +1,287 @@ +--- +title: 发布服务版本 +slug: /getting-started/publish-service +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +当你的 API 设计、开发和部署完成后，如果有版本管理的场景和需求，可以使用 API7 网关将服务发布到不同的网关组，而非直接在网关组上对配置进行修改。 通常，API 会先发布到测试环境，然后再发布到生产环境。API7 企业版通过网关组来隔离不同的环境，在各个环境中，API 从属于一个服务（Service），服务内所有 API 拥有共享的上游 (Upstream)。 + +本教程将指导你将 [httpbin](https://httpbin.org/) 服务发布到一个网关组。你将学习如何： + +1. 手动创建服务模板以及通过 OpenAPI 文件创建服务模板。 +2. 通过配置上游节点和使用服务发现机制来发布服务。 + +## 前提条件 + +1. [安装 API7 企业版](install-api7-ee.md)。 +2. 确保网关组中至少[有一个网关实例](add-gateway-instance.md)。 + +## 新增服务模板并添加路由 + +### 手动新增 + + + + + +1. 在左侧导航栏中选择 **服务中心**， 然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在表单中执行以下操作： + +* **名称** 填写 `httpbin API`。 +* **服务类型** 选择 `HTTP （七层代理）`。 +* **上游 Scheme** 选择 `HTTP`。 +* 点击 **新增**。 + +4. 进入服务内，点击 **新增路由**。 +5. 在表单中，执行以下操作： + +* **名称** 填写 `getting-started-anything`. +* **路径** 填写 `/anything/*`。 +* **HTTP 方法** 选择 `GET`。 + +6. 点击 **新增**。 + + + + + +创建一个 ADC 配置文件，包含服务及其上游和路由： + +```yaml title="adc.yaml" +services: + - name: httpbin API + upstream: + name: httpbin upstream + scheme: http + nodes: + - host: httpbin.org + port: 80 + weight: 100 + routes: + - uris: + - /anything/* + name: getting-started-anything + methods: + - GET +``` + + + + + +### 导入 OpenAPI 文件 + +控制台和 ADC 都支持导入 [OpenAPI v3.0](https://swagger.io/specification/) 规范。 + +在 YAML/JSON 文件中定义你的 API，如下所示： + +```yaml title="OpenAPI.yaml" +openapi: 3.1.0 +info: + title: httpbin API + description: "httpbin API for the API7 Enterprise Getting Started guides." + version: 1.0.0 +paths: + "/anything/*": + get: + tags: + - Anything + summary: Returns anything that is passed into the request. + operationId: getting-started-anything + responses: + "200": + description: Successful Response + content: + application/json: + schema: + type: string +tags: + - name: Anything + description: Return anything that is passed in on the request. +``` + +然后在 API7 网关中使用： + + + + + +1. 在左侧导航栏中选择 **服务中心**， 然后点击 **新增服务**。 +2. 选择 **导入 OpenAPI**。 +3. 在表单中执行以下操作： + +* 上传你的 YAML/JSON 文件。 +* **上游 Scheme** 选择 `HTTP`。 +* 点击 **下一步**。 + +4. 确认以下信息： + +* **名称**：来自 OpenAPI 文件的 `title`。 +* **标签**：来自 OpenAPI 文件的 `tag`。 +* **描述**：来自 OpenAPI 文件的 `description`。 +* **路由**: 来自 OpenAPI 文件的 `Paths`。 + +5. 点击 **新增**。 + + + + + +使用 ADC 将 OpenAPI 文件转换成 ADC 配置文件： + +```shell +adc convert openapi -f openapi.yaml -o adc.yaml +``` + + + + + +## 将服务版本发布到网关组 + +在 API7 网关中，你可以使用静态上游节点或动态服务发现来定义请求的目标。静态上游节点适用于地址固定的、定义明确的服务，而动态服务发现则更适合于服务实例可以动态添加或删除的微服务架构。 + +### 发布单个服务 + + + + + +1. 在左侧导航栏中选择 **服务中心**， 然后选择之前创建的 `httpbin API` 服务。 +2. 点击 **发布新版本**。 +3. 在对话框中选择目标网关组，例如 `默认网关组`， 然后点击 **下一步**。 +4. 在表单中执行以下操作： + +* **新版本** 填写 `1.0.0`。 +* **如何找到上游** 选择 `使用节点`。 +* 点击 **新增节点**。在表单中执行以下操作： + * **主机** 和 **端口** 填写 `httpbin.org` 和 `80`。 + * **权重** 使用默认值 `100`。 + * 点击 **新增**。 +* 确认服务信息，然后点击 **发布**。 + + + + + +将上一步中创建的配置文件同步到你的目标网关组，例如 `default`: + +```shell +adc sync -f adc.yaml --gateway-group default +``` + + + + + +### 批量发布服务 + + + + + +1. 从侧边栏选择 **服务中心**，然后点击 **批量发布服务**。 +2. 选择你的目标网关组，例如，`default`，然后点击 **下一步**。 +3. 点击 **新增服务**。 +4. 在对话框中，执行以下操作： + + * 在 **服务** 下拉列表中，选择你要发布的服务。 + * **新版本** 输入 `1.0.0`。 + * 点击 **新增**。 + +5. 重复上述步骤以添加更多服务。 +6. 点击 **下一步** 继续发布服务。 +7. 在新窗口中，为每个服务执行以下操作： + + * 在**如何查找上游**字段中，选择 `使用节点`。 + * 点击 **新增节点**。在对话框中，执行以下操作： + * **主机**和**端口** 输入 `httpbin.org` 作为主机，`80` 作为端口。 + * **权重** 使用默认值 `100`。 + * 点击 **新增**。 + +8. 确认信息，然后点击**发布**。 + +下面是一个交互式演示，提供了发布版本化服务的实践介绍。跟随演示，你将直观了解如何在 API7 企业版中使用这个功能。 + + + + + + + +要发布多个服务，你可以更新你的 ADC 配置文件以包含其他服务，或者使用多个配置文件并将它们同步到你的目标网关组，例如 `default`，如下所示： + + +```shell +adc sync -f adc-1.yaml -f adc-2.yaml +``` + + + + + +## 验证 API + +```bash +curl "http://127.0.0.1:9080/anything/publish" +``` + +你应该会看到以下输出： + +```json +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "localhost", + "User-Agent": "curl/7.88.1", + "X-Amzn-Trace-Id": "Root=1-664cc6d6-10fe9f740ab1629e19cf85a2", + "X-Forwarded-Host": "localhost" + }, + "json": null, + "method": "GET", + "origin": "152.15.0.1, 116.212.249.196", + "url": "http://localhost/anything/publish" +} +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) +* 快速入门 + * [将已发布的服务版本同步到其他网关组](sync-service.md) + * [回滚已发布的服务版本](rollback-service.md) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/rbac.md b/enterprise_versioned_docs/version-3.6.x/getting-started/rbac.md new file mode 100644 index 00000000..342d3638 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/rbac.md @@ -0,0 +1,267 @@ +--- +title: 更新用户角色 +slug: /getting-started/rbac +--- + +import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; + +基于角色的访问控制（RBAC）将权限链接到角色而不是直接链接到用户。然后为用户分配这些角色，从而简化访问管理，提高效率并减少错误。本指南将引导你使用 API7 企业版的自定义角色、权限策略和权限边界来管理基于角色的访问控制。 + +## 更新用户角色 + +1. 从顶部导航栏中选择 **组织**，然后选择 **用户**。 +2. 点击目标用户的 **更新角色**。 +3. 添加或删除角色。 +4. 点击 **更新**。 + +:::tip + +要查看每个角色的权限，请从顶部导航栏中选择 **组织**，然后选择 **角色**。 + +::: + +结合角色和权限策略能有效控制访问权限。以下是使用自定义角色和权限策略隔离环境访问的示例。 + + + +### 定义权限策略 + +1. 创建三个网关组：`测试`、`UAT` 和 `生产`。 +2. 从顶部导航栏中选择**组织**，然后选择**权限策略**。 +3. 点击 **+ 新增策略**。 +4. 在对话框中，执行以下操作： + * **名称**填写 `完全操作测试网关组`。 + * 在**策略编辑器**字段中，输入配置： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/b6db7341-fc1f-4cee-a318-3e782a163d24" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/b6db7341-fc1f-4cee-a318-3e782a163d24/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] + } + ``` + :::note + + 资源 ID 应与创建的网关组一致。请根据你的使用情况进行更改。 + + ::: + + * 点击**新增**。 +5. 点击 **+ 新增策略**。 +6. 在对话框中，执行以下操作： + * **名称**填写 `完全操作 UAT 网关组`。 + * 在**策略编辑器**字段中，输入配置： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/45a06edc-4a93-4bea-a437-3f153b56254c" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/45a06edc-4a93-4bea-a437-3f153b56254c/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] + } + ``` + + * 点击 **新增**。 +7. 点击 **+ 新增策略**。 +8. 在对话框中，执行以下操作： + * **名称**填写 `完全操作生产网关组`。 + * 在**策略编辑器**字段中，输入配置： + + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/edc12ecd-94a5-49b2-b82d-8d1113e6cd86" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/edc12ecd-94a5-49b2-b82d-8d1113e6cd86/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] + } + ``` + + * 点击 **新增**。 + +### 自定义角色 + +1. 从顶部导航栏中选择**组织**，然后选择**角色**。 +2. 点击 **+ 新增自定义角色**。 +3. 在对话框中，执行以下操作： + * **名称**填写 `研发组成员`。 + * 点击**新增**。 +4. 以相同的方式创建另外两个角色 `研发组长` 和 `测试工程师`。 + +### 分配具有受控访问权限的角色 + +1. 点击 `研发组成员` 并进入角色页面。 +2. 点击 **+ 关联策略**。 +3. 在对话框中，执行以下操作： + * 在**权限策略**字段中，选择 `完全操作测试网关组`。 + * 点击**提交**。这允许他们仅在测试环境中进行更改。 +4. 将 `完全操作测试网关组` 和 `完全操作 UAT 网关组` 策略分配给 `研发组长`。这使他们能够在测试和 UAT 环境中工作，可能包括将稳定配置从测试同步到 UAT 的能力。 +5. 将 `完全操作 UAT 网关组` 和 `完全操作生产网关组` 策略分配给 `测试工程师`。这将他们的访问权限限制在 UAT 和生产环境，专注于新的 API 测试和发布任务。 + +### 验证 + +1. 使用具有 `研发组成员` 角色的帐户登录 API7 企业版，并且只能操作 `测试` 网关组。 +2. 使用具有 `研发组长` 角色的帐户登录 API7 企业版，并且只能操作 `测试` 和 `UAT` 网关组。 +3. 使用具有 `测试工程师` 角色的帐户登录 API7 企业版，并且只能操作 `UAT` 和 `生产` 网关组。 + +## 设置角色映射（需要 SSO） + +满足定义的键值映射规则的用户将在登录时自动分配相应的角色。有关详细信息，请参阅[设置角色映射](../best-practices/sso.md#设置角色映射)。 + +:::note + +角色映射优先于手动角色分配。当角色映射启用时，对用户角色的任何手动调整都将在下次用户登录时被覆盖。 + +::: + + +## 设置用户权限边界 + +用户的有效权限由其分配的角色与其权限边界的交集决定。 +这意味着仅当满足以下条件时才允许用户执行操作： + +* 被至少一个角色允许。 +* 被至少一个权限边界（如果存在）允许。 +* 所有被授权的角色或权限边界均未拒绝。 + +以下是一个交互演示，通过使用权限边界限制对许可证的访问。 + + + +### 创建权限策略并设置权限边界 + +1. 从顶部导航栏中选择**组织**，然后选择**权限策略**。 +2. 点击 **+ 新增策略**。 +3. 在对话框中，执行以下操作： + * **名称**填写 `无法访问许可证`。 + * 在**策略编辑器**字段中，输入配置： + ```json + { + "statement": [ + { + "resources": [ + "arn:api7:iam:organization/*" + ], + "actions": [ + "iam:UpdateLicense" + ], + "effect": "deny" + }, + { + "resources": [ + "<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] + } + ``` + + :::note + + 此策略允许访问除许可证之外的所有资源。 + + ::: + + * 点击**新增**。 +4. 从顶部导航栏中选择**组织**，然后选择**用户**。 +5. 点击 **+ 邀请用户**。 +6. 在对话框中，执行以下操作： + * **用户名**填写 `Tom`。 + * 为 Tom 设置一次性密码。 + * **权限边界**选择 `无法访问许可证`。 + * 点击**邀请**。 +7. 点击**更新角色**。 +8. 在对话框中，执行以下操作： + * **角色** 选择 `超级管理员`。 + * 点击**更新**。 + +### 验证 + +1. 使用 Tom 的帐户登录 API7 企业版。 +2. 从顶部导航栏中选择**组织**，然后选择**许可证**。 +3. 点击许可证页面上的编辑图标，可以看到以下提示，表明访问被拒绝：**权限被拒绝。你的角色不允许此操作。如果你需要额外的访问权限，请联系你的管理员。** + +### 更新 Tom 的角色 + +1. 从顶部导航栏选择**组织**，然后选择**角色**。 +2. 点击**更新角色**。 +3. 在**更新角色**对话框中，执行以下操作： + * 在**角色**字段中，添加一个新角色并选择**超级管理员**。 + * 点击“更新”。 + +### 验证 + +1. 使用 Tom 的帐户登录 API7 企业版。 +2. 从顶部导航栏中选择**组织**，然后选择**许可证**。 +3. 点击许可证页面上的编辑图标，可以看到以下提示，表明访问被拒绝：**权限被拒绝。你的角色不允许此操作。如果你需要额外的访问权限，请联系你的管理员**。 + +## 设置权限边界映射（需要 SSO） + +满足定义的键值映射规则的用户将在登录时自动分配相应的权限边界。有关详细信息，请参阅[设置权限边界映射](../best-practices/sso.md#设置权限边界映射)。 + +:::note + +权限边界映射优先于手动权限边界修改。当权限边界映射启用时，对用户权限边界的任何手动调整都将在下次用户登录时被覆盖。 + +::: + +## 相关阅读 + +* 核心概念 + * [角色和权限策略](../key-concepts/roles-and-permission-policies.md) +* 快速入门 + * [创建自定义角色](../getting-started/create-custom-role.md) +* 最佳实践 + * [SSO 第三方登录](../best-practices/sso.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/rollback-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/rollback-service.md new file mode 100644 index 00000000..66e522c9 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/rollback-service.md @@ -0,0 +1,36 @@ +--- +title: 回滚已发布的服务版本 +slug: /getting-started/rollback-service +--- + +回滚允许你在新版本出现问题时将服务恢复到当前网关组之前发布过的旧版本。 + +:::note + +* 旧的服务版本不包含任何[服务运行时配置](../key-concepts/services.md#service-runtime-configurations)。回滚后将继续使用同样的运行时配置。 + +* 你只能回滚到在同一网关组上发布过的服务版本。 + +::: + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 在网关组上有一个服务的旧版本。 + +## 步骤 + +1. 从侧边栏选择网关组的 **已发布服务**，然后点击要回滚的服务版本，例如版本为 `1.2.0` 的 `httpbin API`。 +2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 **查看历史版本**。 +3. 选择版本 `1.0.0`，然后点击 **回滚**。 + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) + * [网关组](../key-concepts/gateway-groups.md) +* 快速入门 + * [发布服务版本](publish-service.md) + * [在网关组之间同步已发布的服务版本](sync-service.md) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md new file mode 100644 index 00000000..ce3832cf --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md @@ -0,0 +1,118 @@ +--- +title: 将已发布的服务版本同步到其他网关组 +slug: /getting-started/sync-service +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +网关组之间同步已发布的服务版本是 API 版本控制的一个很有用的功能。例如： + +1. 当使用网关组来分隔环境（如测试和生产）时，你可以在运行测试后将服务版本从测试同步到生产。 +2. 或者，如果你使用网关组来划分区域或团队，同步服务可以帮助在它们之间分发服务。 + +:::note + +* 同步使服务版本在网关组之间保持一致，而发布则每次创建一个新的服务版本。 + +::: + +## 前提条件 + +1. [安装 API7 企业版](./install-api7-ee.md)。 +2. 配置两个网关组： 一个用于初始测试环境，另一个作为最终目的环境（例如生产环境）。每个网关组至少[包含一个网关实例](./add-gateway-instance.md)。 +3. 在初始测试环境的网关组中[发布一个服务版本](./publish-service.md)。 + +## 步骤 + +* 同一个服务版本发布/同步到不同网关组时，可以使用不同的上游地址对应不同环境里的后端服务。 +* “无版本”状态的服务也可以同步到其他网关组，同步之后将同时在两个网关组上都拥有一个相同版本号。 +* 你只能同步当前运行的服务版本，不能同步旧的服务版本。 + + + + +### 使用上游节点 + +1. 从侧边栏选择服务来源网关组的 **已发布服务**，然后点击你要同步的服务版本，例如版本为 `1.0.0` 的服务 `httpbin API`。 +2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 `同步到其他网关组`。 +3. 在表单中执行以下操作： + +* **网关组** 选择要同步去的目的网关组，例如 `生产网关组`。 +* 点击 **下一步**。 + +4. 在表单中执行以下操作： + +* **如何查找上游** 选择`使用节点`。 +* 点击**拟增节点**。在表单中执行以下操作： + * **主机**和**端口** 填写 `httpbin.org` 作为主机，`80` 作为端口。 + * **权重**使用默认值 `100`。 + * 点击**新增**。 +* 确认服务信息，然后点击 **同步**。 + +### 使用服务发现 + +1. 从侧边栏选择服务来源网关组的 **已发布服务**，然后点击你要同步的服务版本，例如版本为 `1.0.0` 的服务 `httpbin API`。 +2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 `同步到其他网关组`。 +3. 在表单中执行以下操作： + + * **网关组** 选择要同步去的目的网关组，例如 `生产网关组`。 + * 点击 **下一步**。 + +4. 在表单中执行以下操作： + +* **如何查找上游**，选择 `使用服务发现`。 +* **服务注册表** 选择 `生产用注册中心`，以及注册表中的命名空间和服务名称。 +* 确认服务信息，然后点击 **同步**。 + + + + + +为了通过 ADC 将 [对应的配置](./publish-service.md#use-adc-to-publish-the-api) 同步到 `Production Group`，需要运行： + +```shell +adc sync -f adc.yaml --gateway-group "Production Group" +``` + + + + +## 验证同步之后的 API + +发送一个请求来验证同步到 `生产网关组` 上的 API： + +```bash +# 替换成生产网关组对应的地址 +curl "http://127.0.0.1:9080/headers" +``` + +你应该能看到如下类似的响应： + +```json +{ + "headers": { + "Accept": "*/*", + "Host": "httpbin.org", + "User-Agent": "curl/7.74.0", + "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", + "X-Forwarded-Host": "127.0.0.1" + } +} +``` + +## 相关阅读 + +* 核心概念 + * [服务](../key-concepts/services.md) +* 快速入门 + * [发布服务版本](publish-service.md) + * [回滚已发布的服务](rollback-service.md) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/high-availability/data-plane-resilience.md b/enterprise_versioned_docs/version-3.6.x/high-availability/data-plane-resilience.md new file mode 100644 index 00000000..db1c2e6d --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/high-availability/data-plane-resilience.md @@ -0,0 +1,281 @@ +--- +title: 实现数据面弹性 +slug: /high-availability/cp-outage-dp-resilience +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +弹性是指系统承受和从故障、中断或意外事件中恢复的能力。 + +在本文档中，你将学习为什么你应该在 API7 中考虑数据面 (DP) 弹性模式以及如何实现它，以便当控制面 (CP) 不可用时，DP 实例仍然可以正常运行。这可以帮助你制定灾难恢复计划，并在控制面 (CP) 不可用时快速恢复关键任务功能，从而确保系统的高可用性。 + +## 为什么考虑 DP 弹性 + +DP 可能会遇到连接 CP 的问题。以下是一些可能的原因： + +* DP 和 CP 实例之间的网络连接不良 +* CP 数据库崩溃 +* CP 升级 +* CP 主机上的资源争用 +* CP 主机硬件故障 + +## DP 弹性模式 + +API7 企业版支持将 CP 配置为定期将配置转储到 AWS S3 存储桶，以便在 CP 发生故障时，DP 可以以 `独立模式` 启动，并从存储中提取最新的网关配置以继续代理请求。 + +![解决方案图](https://static.apiseven.com/uploads/2024/07/01/yAwwzGkt_dp-resilience.png) + +CP 恢复后，DP 应继续从 CP 获取配置。 + +## 实现 DP 弹性 + +### 前提条件 + +* [安装 API7 企业版](../getting-started/install-api7-ee.md)。 +* 如果你想在 Kubernetes 上部署资源，请完成[在 Kubernetes 上使用 API7 Ingress Controller 进行部署](../deployment/ingress-controller.md)。 +* 完成[启动示例上游服务](../getting-started/launch-your-first-api.md#start-a-sample-upstream-service)和[创建服务和路由](../getting-started/launch-your-first-api.md#create-service-and-route)。 + +### 配置 AWS 资源 + +1. 创建一个 AWS 账户并以 IAM 用户身份登录。 +2. 创建[两个 S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)，一个用于网关实例配置，例如密钥环和发现；另一个用于网关资源配置，例如路由和服务。 +3. 获取 [IAM 用户访问密钥和秘密访问密钥](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)。 +4. 将[允许对 S3 存储桶中的对象进行读写访问的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_s3_rw-bucket.html)附加到 IAM 用户。 + +### 将 CP 配置为备份配置 + +在你运行[快速入门命令安装 API7 企业版](../getting-started/install-api7-ee.md#install-api7-enterprise)的工作目录中，你应该找到一个 `api7-ee` 目录，其中包含 `docker-compose.yaml` 和各种服务配置文件。 + +将 `fallback_cp` 配置添加到控制台配置文件： + +```yaml title="api7-ee/dashboard_conf/conf.yaml" +# highlight-start +fallback_cp: + aws_s3: + // 注释 1 + access_key: your-aws-iam-access-key + // 注释 2 + region: ap-south-1 + // 注释 3 + config_bucket: bucket-to-push-config-data + // 注释 4 + resource_bucket: bucket-to-push-resource-data + // 注释 5 + secret_key: your-aws-iam-secret-access-key + // 注释 6 + cron_spec: '@every 1m' +# highlight-end +``` + +❶ 替换为你的 AWS IAM 用户访问密钥。 + +❷ 替换为你的 AWS 区域。 + +❸ 替换为你的 S3 存储桶名称，应将实例配置详细信息（例如密钥环和发现）推送到该存储桶。 + +❹ 替换为你的 S3 存储桶名称，应将 APISIX 资源配置（例如路由和服务）推送到该存储桶。 + +❺ 替换为你的 AWS IAM 用户秘密访问密钥。 + +❻ 将推送到 S3 存储桶的频率配置为每分钟一次。 + +重新启动控制台容器： + +```shell +docker-compose -f api7-ee/docker-compose.yaml restart api7-ee-dashboard +``` + +API7 应该开始每分钟将 CP 配置推送到 S3 存储桶。 + +### 验证 + +在本节中，你将首先向路由发送请求以查看预期的上游响应。然后，你将在`独立模式` 下重新启动 DP 部署，以便它开始从 S3 存储桶获取配置，并验证 DP 是否照常代理请求。 + + + + + +向路由发送请求： + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似于以下内容的响应： + +```text +{ + "origin": "127.0.0.1" +} +``` + +假设 CP 现在不可用。将以下配置添加到 DP 配置文件以启动`独立模式`： + +```shell +docker exec /bin/sh -c "echo ' +nginx_config: + error_log_level: warn + +# highlight-start +deployment: + role: data_plane + role_data_plane: + config_provider: yaml + fallback_cp: + aws_s3: + access_key: your-aws-iam-access-key + secret_key: your-aws-iam-secret-access-key + bucket: bucket-to-push-config-data + region: ap-south-1 +# highlight-end +' > /usr/local/apisix/conf/config.yaml" +``` + +重新加载容器以使配置更改生效： + +```shell +docker exec apisix reload +``` + +DP 实例应以独立模式启动并从 S3 存储桶获取配置。 + +向路由发送请求： + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似于以下内容的响应，验证 DP 是否正在根据 S3 中的配置路由请求： + +```text +{ + "origin": "127.0.0.1" +} +``` + +当 CP 恢复后，移除之前对部署模式的更改： + +```shell +docker exec /bin/sh -c "echo ' +nginx_config: + error_log_level: warn +' > /usr/local/apisix/conf/config.yaml" +``` + +重新加载容器以使配置更改生效： + +```shell +docker exec apisix reload +``` + +DP 实例现在应该开始同步来自 CP 的配置。 + + + + + +通过端口转发将服务端口暴露给你的本地机器： + +```shell +kubectl port-forward svc/api7ee3-apisix-gateway 9080:80 & +``` + +向路由发送请求： + +```shell +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似于以下内容的响应： + +```text +{ + "origin": "127.0.0.1" +} +``` + +假设 CP 现在不可用。编辑 DP ConfigMap： + +```shell +kubectl edit cm api7-ee-3-gateway +``` + +在 ConfigMap 中将配置更新为`独立模式`： + +```yaml +apiVersion: v1 +data: + config.yaml: | + ... + # highlight-start + deployment: + role: data_plane + role_data_plane: + config_provider: yaml + # highlight-end +... +``` + +```markdown +```shell +curl "http://127.0.0.1:9080/ip" +``` + +你应该会看到类似于以下内容的响应，验证 DP 是否正在根据 S3 中的配置路由请求： + +```text +{ + "origin": "127.0.0.1" +} +``` + +当 CP 恢复后，编辑 DP ConfigMap： + +```shell +kubectl edit cm api7-ee-3-gateway +``` + +将部署模式更新回之前的配置： + +```yaml +apiVersion: v1 +data: + config.yaml: | + ... + # highlight-start + deployment: + role: traditional + role_traditional: + config_provider: etcd + + admin: + allow_admin: + - 127.0.0.1/24 + etcd: + host: + - "http://192.168.101.10:7900" # 替换为你的地址 + prefix: "/apisix" + timeout: 30 + # highlight-end +... +``` + +保存 ConfigMap 并重新启动资源： + +```shell +kubectl rollout restart deployment api7-ee-3-gateway +``` + +DP 实例现在应该开始同步来自 CP 的配置。 + + + + +``` diff --git a/enterprise_versioned_docs/version-3.6.x/high-availability/high-availability-installation.md b/enterprise_versioned_docs/version-3.6.x/high-availability/high-availability-installation.md new file mode 100644 index 00000000..ed3aaa90 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/high-availability/high-availability-installation.md @@ -0,0 +1,117 @@ +--- +title: 高可用部署步骤 +slug: /high-availability/high-availability-installation +--- + +本文档介绍了如何对 API7 网关的以下组件进行高可用部署： + +- 控制面： + - API7 Dashboard + - DP Manager +- 数据面： + - API7 Gateway + +不包括以下组件的高可用部署： + +- PostgreSQL +- Prometheus + +### 前提条件 + +- 完成 [高可用配置准备](./prepare-for-high-availability.md)。 +- 自行另外安装 PostgreSQL 和 Prometheus (可选)。 + +## 控制面部署步骤 + +API7 Dashboard 是控制面中的主要组件，它是一个 Web GUI 并处理业务逻辑。API7 Dashboard 是一个无状态服务，所有数据信息都存储在关系型数据库中（默认使用 PostgreSQL）。 + +为达到高可用，需要不只一个控制面节点，而是一个包含多个节点的集群。同时，你需要在多个控制面节点之前部署一个负载均衡。通过负载均衡，可以将进入的流量均匀分配到多个控制面节点上，如果某个节点发生故障，负载均衡可以将其移除，确保流量不会被发送到不可用的节点上。 + +对于所有控制面节点，请执行以下操作： + +1. 将控制面软件包复制到主机。你可以从[高可用配置准备](./prepare-for-high-availability.md)中获取合适的软件包。 +2. 配置 `dashboard-config.yaml` 以修改数据库地址： + +```bash +server: + listen: + host: "0.0.0.0" + port: 17080 + +database: + dsn: "postgres://$user:$password@$postgresql_address:$postgresql_port/api7ee" +``` + +3. 启动 API7 Dashboard： + +```bash +docker run -d -p 17080:17080 -v ./dashboard-config.yaml:/app/conf/config.yaml api7/api7-ee-3-integrated:v3.2.16.3 +``` + +4. 配置 `dp-manager-config.yaml`： + +打开配置文件，修改其中数据库地址的配置项: + +```bash +server: + listen: + host: "0.0.0.0" + port: 17900 + +database: + dsn: "postgres://$user:$password@$postgresql_address:$postgresql_port/api7ee" +``` + +5. 启动 DP Manager： + +```bash +docker run -d -p 17900:17900 -v ./dp-manager-config.yaml:/usr/local/api7/conf/config.yaml api7/api7-ee-dp-manager:v3.2.9.1 +``` + +## 数据面部署步骤 + +API7 网关根据接受来自客户端的流量并将其转发到上游进行收费，因此数据面节点也可以称为网关实例。API7 网关是一个无状态组件，所有配置信息都存储在 PostgreSQL 中。因此，您可以部署多个节点来提高数据面的高可用性。 + +### 添加网关组 + +为了确保高可用性，您需要一个包含多个数据面节点的数据面集群。数据面集群也可以称为[网关组](../key-concepts/gateway-groups.md)。有关说明，请参阅[新增网关组](../getting-started/add-gateway-group.md)。 + +### 健康检查 + +在数据面节点前面部署负载均衡器并启用健康检查对于保持高可用性和防止流量路由到不健康的节点至关重要。 + +1. 配置 `gateway_conf/config.yaml` 以添加用于监听接口的 `status` 模块： + +```bash +apisix: + status: + ip: 0.0.0.0 + port: 7085 +``` + +2. 将负载均衡器设置为定期检查所有健康检查接口。根据你的具体要求和应用程序的预期响应时间确定合适的健康检查频率。通常的做法是将健康检查设置为每 30 秒探测一次。 + +```bash +curl "http://127.0.0.1:7085/status" -v +``` + +如果数据面是健康的，你应该会看到以下 `200 OK` 响应： + +```text +* Trying 127.0.0.1:7085... +* Connected to 127.0.0.1 (127.0.0.1) port 7085 (#0) +> GET /status HTTP/1.1 +> Host: 127.0.0.1:7085 +> User-Agent: curl/7.74.0 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< Server: openresty +< Date: Thu, 17 Oct 2024 06:27:38 GMT +< Content-Type: text/plain; charset=utf-8 +< Transfer-Encoding: chunked +< Connection: keep-alive +< +* Connection #0 to host 127.0.0.1 left intact +``` diff --git a/enterprise_versioned_docs/version-3.6.x/high-availability/overview.md b/enterprise_versioned_docs/version-3.6.x/high-availability/overview.md new file mode 100644 index 00000000..67ffe8fa --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/high-availability/overview.md @@ -0,0 +1,21 @@ +--- +title: API7 高可用概述 +slug: /high-availability/overview +--- + +你可以在搭建 API 网关环境时采用高可用架构，以确保系统不会产生单点故障，有助于消除生产环境中任何可能的系统宕机。本文档将介绍生产环境中推荐的 API 网关高可用架构。 + +## 什么是高可用 + +高可用性（High Availability，可简写为 HA）是指系统在某些组件发生故障时仍能够正常工作的特性。它的目标是确保事前约定的系统稳定性和性能水平，并保证系统在理想的长时间内保持连续可操作性。高可用性能够保护企业免受系统宕机带来的业务风险。 + +## API7 高可用架构 + +
+
+ HA Architecture +
+

+ +- 数据面负责将 API 流量转发到上游端点。如果数据面发生故障，网关服务将会中断，无法转 API 流量并响应，API 调用会报错。因此，需要在数据面上配置高可用性，以防止单点故障。 +- 控制面通过直观的 Web 界面（API7 控制台）负责网关管理。当控制面发生故障时，无法更改 API 网关上的配置，但不会影响当前服务请求，即 API 仍可以按照发生故障前保存的配置正常运行。因此，控制面的高可用性是可选配置的。 diff --git a/enterprise_versioned_docs/version-3.6.x/high-availability/prepare-for-high-availability.md b/enterprise_versioned_docs/version-3.6.x/high-availability/prepare-for-high-availability.md new file mode 100644 index 00000000..2468a180 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/high-availability/prepare-for-high-availability.md @@ -0,0 +1,54 @@ +--- +title: 高可用配置准备 +slug: /high-availability/prepare-for-high-availability +--- + +本文档介绍了推荐的、最低限度要求的高可用配置。 + +## 获取安装包 + +请[联系 API7 专家](https://api7.ai/contact)，以获取适合你的安装包。 + +## 准备主机 + +要部署 API7 企业版高可用性架构，至少需要 4 台主机（2 台用于控制面高可用，2 台用于数据面高可用）。 + +请注意，虽然数据库高可用也是一个需要考虑的重要方面，但本文档并未涵盖。建议你根据自己实际使用的关系型数据库单独处理这个问题，以确保数据存储系统的弹性和容错性。有关如何为 PostgreSQL 配置高可用的详细信息，请参阅 [PostgreSQL 文档](https://www.postgresql.org/docs/current/high-availability.html)。 + +Prometheus 是一个可选组件，仅当你希望使用 API7 企业版自带的监控功能时才使用。如果你不需要此功能（已经自建监控系统），则 Prometheus 不是部署必需的。有关如何为 Prometheus 配置高可用的详细信息，请参阅 [Prometheus 文档](https://prometheus.io/docs/introduction/faq/#can-prometheus-be-made-highly-available). + +在实际场景中，高可用架构可能会因具体情况而异。请[联系API7专家](https://api7.ai/contact)，我们将很高兴为你量身定制满足你需求的高可用解决方案。 + +## 最低硬件要求 + +| 主机 | 处理器 | CPU | RAM | Free Disk Space | 部署组件 | +| ----------- | ----------| -------- | --- | --------------- | ------------------- | +| CP Host1 | x86_64 | 2 Cores | 4G | 80 GB | API7 Dashboard, DP Manager | +| CP Host2 | x86_64 | 2 Cores | 4G | 80 GB | API7 Dashboard DP Manager | +| DP Host3 | x86_64 | 2 Cores | 4G | 80 GB | API7 Gateway | +| DP Host4 | x86_64 | 2 Cores | 4G | 80 GB | API7 Gateway | + +## 最低软件要求 + +对于每台主机，必须满足以下要求： + +- **操作系统**：推荐使用 Linux CentOS 7.6 或更高版本。已知 Linux CentOS 7.2 或更早版本可能存在不兼容的情况。 + +- **Docker**： 推荐使用 3.10.0-927 或更高版本。已知 3.10.0-327 或更早版本可能存在不兼容的情况。 + +注意：在实际配置环境中，务必核实并确保你的系统和应用软件版本都符合官方的支持和兼容要求。特别是像Docker这样的关键组件，安装不正确或不兼容的版本可能会导致系统不稳定或应用运行失败。 + +## 安全设置 + +由于每个组件都需要对外暴露节点，因此你应该在这些主机上配置 SELinux 和防火墙。 + +解释：SELinux（Security-Enhanced Linux）是一个 Linux 内核的安全模块，用于提供强制访问控制。防火墙则是用于监控和控制网络流量的系统，可以帮助保护主机免受未经授权的访问和攻击。在配置高可用性系统时，确保这些安全设置正确配置是非常重要的，以保护系统的各个组件和数据的安全。 + +| 组件 | 暴露端口 | 说明 | +| -------------- | ------| ------------------------------ | +| API7 Gateway | 9080 | 接收 HTTP 请求 | +| API7 Gateway | 9443 | 接收 HTTPs 请求 | +| API7 Dashboard | 7080 | 管理员入口 | +| DP Manager | 7900 | 管理数据面节点，包括配置下发、心跳检查，上报监控指标等| +| Prometheus | 9090 | 收集并展示监控指标 | +| PostgreSQL | 5432 | Version 15, 存储网关配置数据，可以替换为其他关系型数据库如 MySQL 5.7 或 OceanBase 4.2.2 | diff --git a/enterprise_versioned_docs/version-3.6.x/introduction/api7-ee-architecture.md b/enterprise_versioned_docs/version-3.6.x/introduction/api7-ee-architecture.md new file mode 100644 index 00000000..b892d4a0 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/introduction/api7-ee-architecture.md @@ -0,0 +1,30 @@ +--- +title: 产品架构 +slug: /introduction/architecture +--- + +## API7 企业版组件架构 + +API7 企业版作为基于 Apache APISIX 构建的高性能云原生 API 网关，其具有的可灵活扩展架构可以满足企业级 API 管理的需求。这个基础架构能够处理大规模的流量控制，并保证安全性和弹性。 + +![how api7 works](https://static.apiseven.com/uploads/2024/03/24/b4cGaMuC_%E6%9E%B6%E6%9E%84%E5%9B%BE-%E4%B8%AD%E6%96%87.jpg) + +API7 企业版的架构可以大致分为数据面和控制面两部分。 + +### 数据面（Data Plane） + +数据面主要由 API7 Gateway 组件构成，负责处理所有 API 流量。管理员在配置路由规则后，可以根据预定义的标准将传入的请求路由到适当的上游服务。API7 企业版提供了 60 多个内置插件，以满足常见的需求，如身份验证、流量控制、转换、分析等。这些插件可以轻松地集成到网关中，以在请求/响应生命周期的各个阶段进行干预。 + +如果需要，用户还可以使用 Lua、Java、Go 或 Python 等语言开发自定义插件，并将其与 API7 企业版集成。这种灵活性使得 API7 企业版能够适应各种复杂和特定的用例，从而满足企业的个性化需求。 + +### 控制面（Control Plane） + +控制面通过直观的 Web 界面（API7 Dashboard）简化了网关管理。这个集中化的 API 控制台提供了一系列关键功能，包括监控 API、分析流量、审计日志以及在网关组之间进行切换等。通过这些功能，管理员可以更加高效地管理网关，并提高对 API 操作的可见性。 + +此外，控制面还支持动态配置更新和策略管理，使得管理员能够在不中断现有服务的情况下对网关进行配置更改或策略调整。这种分离架构的设计有助于提高系统的可维护性和可扩展性。 + +:::提示 + +API7 企业版也支持使用 MySQL 或 OceanBase 代替 PostgreSQL。 + +::: diff --git a/enterprise_versioned_docs/version-3.6.x/introduction/what-is-api7-ee.md b/enterprise_versioned_docs/version-3.6.x/introduction/what-is-api7-ee.md new file mode 100644 index 00000000..5d9713a6 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/introduction/what-is-api7-ee.md @@ -0,0 +1,222 @@ +--- +title: 概览 +slug: /introduction +--- + +**API7 企业版扩展了 [Apache APISIX](https://github.com/apache/apisix) 的核心开源功能，为企业提供定制化、全生命周期的 API 管理。** 这是一个全面的 API 管理解决方案，包括 API7 网关和全新推出的 API7 门户（内测中，欢迎联系我们试用）。它将提供全天候企业级支持、高级功能、系统集成和 SLA 服务，以充分释放 APISIX 驱动的 API 管理的潜力。 + +**API7 企业版包含最受欢迎的企业级功能。**凭借对安全、流量管理和分析的强大支持，以及友好的开发人员体验，API7 企业版可满足大多数行业企业对 API 管理的需求和应用场景。 + +**API7 企业版可让企业专注于通过 API 提供商业价值，而非复杂的基础架构运维管理。**企业可轻松利用功能强大的 API 网关，加快访问速度，端到端优化 API 的整个生命周期，而无需花费大量时间钻研专业知识和进行自主开发： + +- 大规模 API 的安全管理和验证访问。 +- 通过生命周期分析提高 API 的可观察性。 +- API 网关与现有系统和管道的深度集成。 +- 遵循未来技术和管理趋势的 API 基础设施，可轻松适应快速增长的需求。 +- 通过动态负载均衡、熔断降级和速率限制实现精细的流量控制。 + +Apache APISIX 作为顶级开源 API 网关，为企业控制和保护 API 流量提供了坚实的基础。凭借其高性能架构和活跃的开源社区，API7 企业版可帮助企业释放 API 的最大潜能，同时应对大规模 API 带来的复杂性。 + +## 优势和亮点 + +![advantages-and-highlights](https://static.apiseven.com/uploads/2023/08/29/XAO2dI0y_Advantages.PNG) + +- **云原生** + + API7 企业版是一个云原生网关，与平台无关，没有锁定供应商的风险。它支持裸机、虚拟机、Kubernetes、OpenShift、ARM64 等。此外，API7 企业版还能与 SkyWalking、Prometheus、Kafka 和 Zipkin 等其他组件轻松集成，共同为企业赋能。 + +- **高可用性** + + 默认情况下，API7 企业版使用 etcd 作为配置中心。etcd 天然支持分布式和高可用性，并在 Kubernetes 等领域拥有丰富的实践经验。因此，API7 企业版可以轻松支持毫秒级的配置更新，并支持数千个网关节点。网关节点是无状态的，可根据需要扩大或缩小。 + +- **协议转换** + + API7 企业版支持多种协议类型，包括 TCP/UDP、Dubbo、MQTT、gRPC、SOAP、WebSocket 等。 + +- **安全保护** + + 内置多种认证和安全保护功能，如基本认证、JSON Web 令牌、IP 黑名单/白名单、OAuth 等。 + +- **极高性能** + + API7 企业版采用 Radixtree 算法实现高性能和灵活的路由选择。在 AWS 8 核服务器上，QPS 约为 140K，延迟约为 0.2ms。 + +- **完全动态能力** + + 可实时修改网关配置、添加或修改插件等，无需重启网关服务。它支持动态加载 SSL 证书。 + +- **强大的扩展能力** + + 通过灵活的插件机制，API7 企业版可根据内部业务功能进行定制。它支持自定义负载均衡和路由算法，不受 API 网关实施的限制。运行时执行用户定义的功能，实现无服务器，使网关边缘节点更加灵活。 + +- **丰富的治理能力** + + 如故障隔离、熔断降级、限流限速等功能。启用主动健康检查后，网关将支持智能跟踪并自动过滤掉不健康的上游节点，提高整体服务的稳定性。 + +## 功能概述 + +### API 发布 + +**请求路由** + +- URI 参数匹配 +- HTTP 请求标头匹配 +- HTTP 请求方法匹配 +- 条件表达式 +- IPv6 +- GeoIP 位置匹配 +- 路由生存时间 (Time To Live，TTL) +- 优先级匹配 + +**请求重写** + +- URI 重写 +- 添加、修改和删除 HTTP 请求标头 +- 301、302 重定向 +- 强制重定向到 HTTPS +- 响应重写 + +**响应重写** + +- 添加、修改和删除 HTTP 响应标头 +- 修改 HTTP 响应代码 +- 修改响应正文 + +**协议转换** + +- HTTP/1.1、HTTP2 +- HTTP/3 +- TLS/HTTPS +- MQTT +- UDP +- WebSocket +- Dubbo +- 自定义第 4 层协议 +- 自定义第 7 层协议 + +**灰度版本** + +- 灰度版本 +- 蓝绿部署 + +**响应缓存** + +**流量镜像** + +**熔断** + +- API 熔断 +- 服务降级 + +**故障注入** + +**流量染色** + +### API 消费 + +- 消费者管理 + +### API 运行时 + +**监测** + +- 数据吞吐量 +- 响应时间 +- 上游响应时间 +- 状态代码 +- API 调用量 +- 网关实例版本和状态 +- 证书过期 + +**日志** + +- 推送到 HTTP/TCP/UDP 日志服务器 +- SkyWalking +- Kafka +- RocketMQ +- Clickhouse +- 系统日志 +- 阿里云 SLS +- 谷歌云日志服务 +- Splunk HTTP 事件收集器 (HEC) +- 磁盘上的特定文件 +- 弹性搜索 +- 腾讯云 CLS +- Grafana Loki + +**追踪** + +- SkyWalking +- Zipkin +- 开放追踪 + +### API 安全性 + +**请求验证** + +- JWT +- 密钥验证 +- HMAC +- 基本认证 +- Keycloak +- Casdoor +- OpenID connect +- LDAP +- Lua Casbin +- 开源策略代理 +- 外部认证服务器（Auth0、Okta 等） +- OAuth2 + +**速率限制** + +- 基于固定窗口的请求限制 +- 基于漏桶原则的请求限制 +- 限制并发请求 + +**IP 限制** + +- 黑名单 +- 白名单 +- 防止 ReDOS 攻击 +- 防止重放攻击 + +**URI 限制** + +- 黑名单 +- 白名单 + +**CORS** + +### 用户管理 + +- RBAC + +### 数据安全 + +- mTLS +- FIP +- SSL 证书轮换 + +### 工具 + +- CLI +- Helm Chart +- 回滚 +- 用于独立部署模式的 YAML 文件 + +### 高级 + +- 数据主权 +- 配置热更新 + +## 部署方法 + +- 裸机 +- 虚拟机 +- Kubernetes +- ARM64 +- 华为鲲鹏 +- AWS +- GCP +- 阿里云 +- 腾讯云 \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/api-portal.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/api-portal.md new file mode 100644 index 00000000..fe290b3b --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/api-portal.md @@ -0,0 +1,68 @@ +--- +title: API 门户（API Portal） +slug: /key-concepts/api-portal +--- + +API7 门户是 API7 企业版推出的 API 门户产品， 是一个集中式的在线平台，充当 API 提供者和 [开发者](./developers.md) 之间的桥梁。 + +## 概述 + +API7 门户主要用于： + +* **展示 API：** 就像商店橱窗一样，它展示了可用的 API、它们的功能以及如何使用它们。 +* **提供文档：** 提供详细的指南、教程和代码示例，以帮助开发者理解和集成 API。 +* **方便访问：** 允许开发者自行注册、订阅 API 并管理其使用情况。 +* **支持测试：** 通常包括 API 控制台或沙盒等交互式工具，供开发者在集成 API 之前进行试用。 + +### 对于 API 提供者 + +* **提高 API 使用率：** 使开发者更容易找到和使用他们的 API。 +* **改善开发者体验：** 为所有 API 相关信息和支持提供一个中心枢纽。 +* **更好的 API 管理：** 允许对 API 访问、使用和文档进行集中控制。 +* **盈利潜力：** 可用于打包和销售 API 访问权限。 + +### 对于开发者 + +* **简化 API 检索：** 在集中位置轻松找到他们需要的 API。 +* **更快的集成：** 访问全面的文档和测试工具可加快集成过程。 +* **提高生产力：** 通过提供对必要信息的快速访问并减少研究和集成时间来简化开发工作流程。 +* **访问社区：** 与其他开发者联系，分享知识并获得支持。 + +## 使用场景 + +API7 门户有三个主要使用场景： + +* **内部 API 门户：** 专为组织内部使用而设计，促进团队之间的 API 共享和协作。这可以促进 API 设计的一致性，防止重复开发，并实现内部 API 的集中管理。 +* **合作伙伴 API 门户：** 用于与来自合作伙伴组织的开发者安全地共享 API，同时限制公众访问。可以为每个合作伙伴自定义 API 产品的可见性。 +* **公共 API 门户：** 充当向外部开发者提供 API 的市场，通过 API 订阅实现盈利机会。 + +你还可以采用混合解决方案，同时支持内部、合作伙伴和公共 API 门户。这种灵活性允许你： + +* 定制开发者管理策略：为内部开发者、外部合作伙伴和公共用户实施不同的身份验证和授权机制。 +* 自定义 API 可见性和访问控制：为不同的用户组定义精细的访问级别和可见性规则。 +* 提供免费和付费 API 产品的组合：通过公共 API 获利，同时为内部和合作伙伴 API 提供免费或受限访问。 + +这种混合解决方案提供了最大的灵活性，使你能够根据你的特定需求和业务目标定制 API 门户。 + +## 提供者门户 vs 开发者门户 + +API7 门户包含两个不同的控制台： + +* 提供者门户：专为管理员和 API 提供者设计。此控制台与 API7 网关共享相同的域名和入口，从而简化用户体验和访问。它使管理员能够有效地创建、管理和监控 API。 +* 开发者门户：专为开发者发现、探索和使用 API 而设计。 + +这种双控制台结构提供了明确的职责分离，并增强了提供者和开发者的整体用户体验。 + +| | 开发者门户 | 提供者门户 | +| ------------| ----------------------| ------------------------------------- | +| 用户 | 内部或外部用户，非 API7 网关用户 | 内部用户，也是 API7 网关用户 | +| 域名 | 独立域 | API7 企业域，与 API7 网关相同 | +| 自定义 UI | 支持 | 不支持 | + +## 相关阅读 + +* 核心概念 + * [API 产品](./api-products.md) + * [开发者](./developers.md) +* API 门户 + * [服务产品化](../api-portal/productize-services.md) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/api-products.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/api-products.md new file mode 100644 index 00000000..59e66b80 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/api-products.md @@ -0,0 +1,52 @@ +--- +title: API 产品 +slug: /key-concepts/api-products +--- + +将 API7 门户想象成你的数字店面，向开发者展示你提供的宝贵 API。 在此店面中，_API 产品_ 充当精选的 API 组合包，根据特定需求和用例量身定制。 就像商店可能会提供不同的产品套餐一样，你的 API 门户使用 API 产品会更易于理解、使用和管理你的 API。 + +## 概述 + +API 产品本质上是一个包含一个或多个 API 的集合，是开发者订阅或购买你的 API 的最小单位。 + +API7 门户支持两种类型的 API 产品： + +* **从 API7 网关创建（推荐）：** API 产品利用来自 API7 网关的已发布服务，实现集中管理并简化向开发者的交付。API7 门户将支持这些 API 产品的订阅管理和未来的货币化功能。对已发布服务的更改会自动反映在 API7 门户上的关联 API 产品中，从而确保为你的开发者提供无缝更新。 +* **导入 OpenAPI：** 使开发者能够在 API7 门户中探索外部 API。此功能为开发者提供了一个沙盒环境，以便与未托管在 API7 网关上的 API 进行交互。导入的 API 不支持身份验证、订阅和货币化等高级功能。 + +## 使用优势 + +* **简化使用：** 开发者可以轻松发现和订阅所需的 API 集合，而无需了解底层服务架构。 +* **有针对性的产品：** 为不同的受众或用例创建不同的 API 产品（例如，具有有限访问权限的“入门”产品，具有更高配额的“高级”产品）。 +* **高效管理：** 将策略应用于一组 API 并将其作为一个单元进行管理。 +* **改善开发者体验：** 清晰、有条理地展示你的 API 产品，使开发者更容易找到他们需要的内容并快速入门。 + +## 与已发布服务的关系 + +API 产品可以由来自 API7 网关的多个已发布服务组成。但是有以下限制： + +* 一对一关联：已发布的服务只能与单个 API 产品关联。 +* 网关组限制：来自相同服务模板的、不同网关组的已发布服务不能包含在同一 API 产品中。 + +已发布服务 - API 产品关系会帮助你的开发团队内部明确各自的角色和职责。 + +工程师专注于技术方面： + +* 设计、开发和维护已发布的服务。 +* 确保 OpenAPI 规范的准确性和质量。 + +API 产品经理专注于业务方面： + +* 根据开发者需求定义和管理 API 产品。 +* 监督订阅管理和开发者参与。 +* 驱动整体产品战略。 + +这种职责划分有助于更高效、更有效地进行 API 开发和管理。 + +## 相关阅读 + +* 核心概念 + * [服务](./services.md) +* API 门户 + * [服务产品化](../api-portal/productize-services.md) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/authentication.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/authentication.md new file mode 100644 index 00000000..78ae563c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/authentication.md @@ -0,0 +1,32 @@ +--- +title: 身份认证 +slug: /key-concepts/authentication +--- + +出于安全原因，API7 企业版支持消费者访问内部资源（API）之前对其进行身份验证和授权。API7 企业版具有灵活的插件扩展系统以及许多用于用户身份验证和授权的插件。 + +- [Key Authentication](https://docs.api7.ai/hub/key-auth) +- [Basic Authentication](https://docs.api7.ai/hub/basic-auth/) +- [JSON Web Token (JWT) Authentication](https://docs.api7.ai/hub/jwt-auth/) +- [Keycloak](https://docs.api7.ai/hub/authz-keycloak/) +- [Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/) +- [Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/) +- [OpenID Connect](https://apisix.apache.org/docs/apisix/plugins/openid-connect/) +- [Central Authentication Service (CAS)](https://apisix.apache.org/docs/apisix/plugins/cas-auth/) +- [HMAC](https://apisix.apache.org/docs/apisix/plugins/hmac-auth/) +- [Casbin](https://apisix.apache.org/docs/apisix/plugins/authz-casbin/) +- [LDAP](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/) +- [Open Policy Agent (OPA)](https://apisix.apache.org/docs/apisix/plugins/opa/) +- [Forward Authentication](https://apisix.apache.org/docs/apisix/plugins/forward-auth/) + +其中，密钥认证（Key Authentcation，简称 key-auth）是一种相对简单但广泛使用的认证方法。理想情况下，它的工作原理如下： + +1. 在路由中通过启用 key-auth 插件添加一个认证密钥机制。 +2. API 消费者在发送请求时，将密钥添加到查询字符串或请求头中以进行认证。 + +请注意，每个路由只能使用一种认证机制。不要在单个路由上启用多个认证插件，也不推荐将认证插件作为全局规则启用。 + +## 相关阅读 + +- [开启 API 身份认证](../api-security/api-authentication.md) +- [管理消费者访问凭证](../api-consumption/manage-consumer-credentials.md) \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/certificates.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/certificates.md new file mode 100644 index 00000000..638f9d3c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/certificates.md @@ -0,0 +1,50 @@ +--- +title: 证书 +slug: /key-concepts/certificates +--- + +证书用于在客户端应用程序和 API7 网关之间配置 TLS 或 mTLS。这种 SSL 和 CA 证书系统对于在线建立信任和安全至关重要，允许用户自信地浏览和与网站交互。 + +* SSL 证书：用于传输层安全 (TLS)。安全套接字层 (SSL) 协议是一种加密协议，旨在保护双方之间的通信安全。 +* CA 证书：用于双向传输层安全 (mTLS)。它就像一个用于安全连接的双重检查系统，双方在交换信息之前验证彼此的身份。 + +## SSL 证书 + +TLS 在现有协议（例如 HTTP 或 TCP）之上实现。它通过 TLS 握手建立连接和加密数据传输来提供额外的安全层。 + +下图重点介绍了以下内容中的**单向 TLS 握手**： + +* [TLS v1.2](https://www.rfc-editor.org/rfc/rfc5246) +* [TLS v1.3](https://www.rfc-editor.org/rfc/rfc8446)。 + +TLS v1.2 和 TLS v1.3 是两个最常用的 TLS 版本。 + +
+TLS v1.2 和 TLS v1.3 的 TLS 握手 +
+ +在此过程中，服务器通过出示其证书向客户端进行身份验证。 +客户端验证证书以确保其有效并且由受信任的机构颁发。 +证书验证完成后，客户端和服务器就共享密钥达成一致，该密钥用于加密和解密应用程序数据。 + +![SSL](https://static.api7.ai/uploads/2024/12/13/vtqOSnyr_key-concept-ssl.png) + +## CA 证书 + +API7 企业版还支持双向 TLS (mTLS)，其中客户端也通过出示其证书向 API7 网关进行身份验证，从而有效地创建双向 TLS 连接。 +这确保了双方都经过身份验证，并有助于防止网络攻击，例如 [中间人攻击](https://zh.wikipedia.org/wiki/%E4%B8%AD%E9%97%B4%E4%BA%BA%E6%94%BB%E5%87%BB)。 + +## 使用案例 + +要在你的系统中使用 API7 企业版启用 TLS 或 mTLS，你应该生成和配置证书并与 [SNI](./snis) 关联。 + +## 相关阅读 + +* 核心概念 + * [服务](./services) + * [SNI](./snis) +* API 安全 + * [在客户端和 API7 网关之间配置 mTLS](../api-security/client-mtls) \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/consumers.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/consumers.md new file mode 100644 index 00000000..93120900 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/consumers.md @@ -0,0 +1,74 @@ +--- +title: 消费者 +slug: /key-concepts/consumers +--- + +在本文档中，你将学习 API7 企业版中消费者的基本概念以及为什么需要它们。你将了解一些相关概念，包括如何将消费者信息传递到上游、消费者访问限制以及消费者身份验证和授权。 + +## 概述 + +消费者表示向 API 网关发送请求并使用后端服务的**用户**、**应用程序**或**主机**。它与身份验证系统一起使用。每个消费者都必须至少配置一个身份验证凭据或使用插件（如 **Authz Keycloak** 或 **OpenID Connect**）与外部身份验证系统集成。 + +下图说明了具有一个路由和两个消费者的 API7 企业版示例。一个消费者 `FetchBot` 是一个数据获取机器人，另一个消费者 `JohnDoe` 是一个用户。路由和消费者都启用了 `key-auth` 插件，因此，请求将使用 API 密钥进行身份验证。要访问内部服务，`FetchBot` 使用 `bot-key` 发送其请求，`JohnDoe` 使用 `john-key` 发送其请求。 + +
+
+消费者图表示例 +
+
+ +此配置可确保只有经过身份验证的请求才能与 `/petstore` 上公开的内部服务进行交互。 + +* 如果向 API7 企业版发送的请求没有任何密钥或密钥错误，则该请求将被拒绝。 +* 如果使用 `bot-key` 向 API7 企业版发送请求，则该请求将被验证并由 `FetchBot` 发送以从内部服务获取数据。`FetchBot` 消费者上的 `limit-count` 限速插件将生效，将 5 秒窗口内的请求数限制为 `2`。如果未达到限速阈值，则请求将转发到上游服务。否则，它将被拒绝。 +* 如果使用 `john-key` 向 API7 企业版发送请求，则该请求将被验证并由 `JohnDoe` 发送，随后转发到上游端点。 + +在这种情况下，身份验证插件将根据[插件执行阶段](./plugins.md#plugins-execution-lifecycle)在 `limit-count` 限速插件之前执行。 + + +## 消费者身份验证和授权 + +在基于 API7 企业版的架构中构建身份验证和授权有两种主要设计模式。 + +第一种也是最常用的方法是通过第三方[身份提供商 (IdP)](https://zh.wikipedia.org/wiki/%E8%BA%AB%E4%BB%BD%E6%8F%90%E4%BE%9B%E5%95%86)（例如 [Keycloak](https://www.keycloak.org)）对请求进行身份验证和授权： + +
+API7 企业版与 IdP 的集成 +
+
+ +在某些环境中，请求可能需要经过多个 IdP 才能转发到上游端点。在这种情况下，你可以在一个消费者上配置多个身份验证插件，每个插件对应一个 IdP。在所有 IdP 都授予请求访问权限之前，API7 企业版不会显示成功的响应。 + +第二种也是更基本的方法是直接在 API 网关上使用内置凭据执行身份验证和授权。到目前为止，支持 Key Authentication 验证、Basic Authentication 验证、JWT Authentication 验证和 HMAC Authentication 凭据验证。 + +与传统的用户登录类似，每个消费者可以创建多个凭据，所有凭据都链接到一个消费者身份。凭据应安全存储并定期更新。 + +:::note + +消费者凭据通过允许多个凭据对应每个消费者来增强灵活性。它们取代了传统的身份验证插件，如 key-auth、basic-auth、JWT-auth 和 HMAC-auth，提供了更友好的用户体验。 + +::: + +## 开发者 vs 消费者 + +来自 API7 门户的[开发者](./developers)也可以管理 API 凭据并通过订阅利用访问控制，但它们通常用于不同的场景。 + +| | 开发者 | 消费者 | +| ------------| ----------------------| ------------------------------------- | +| 凭据 | 由开发者自己管理，对提供者不可见 | 由提供者管理 | +| API 访问控制 | 开发者请求访问，提供者批准订阅 | 提供者可以直接从白名单/黑名单中添加或删除消费者 | + +开发者和消费者可以同时用于不同的 API，独立运行。但是，对于给定的已发布服务及其关联的 API 产品，应使用 API7 网关身份验证插件或 API 产品身份验证配置。 + +对于私有服务，通过 API7 网关中的消费者管理来限制访问。对于公共服务，将它们分组到定义良好的 API 产品中，并通过 API 产品配置管理开发者访问。 + +强烈建议不要将 API7 网关身份验证插件和 API 产品身份验证配置组合用于同一已发布服务（仅适用于非常特殊的情况）。这可能会导致身份验证冲突，需要多个凭据才能成功进行 API 请求。 + +## 相关阅读 + +* API 安全 + * [设置 API 身份验证](../api-security/api-authentication.md) +* API 消费 + * [管理消费者凭据](../api-consumption/manage-consumer-credentials.md)。 + * [应用基于黑白名单的访问控制](../api-consumption/consumer-restriction.md) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/developers.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/developers.md new file mode 100644 index 00000000..53ab1bbd --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/developers.md @@ -0,0 +1,53 @@ +--- +title: 开发者 +slug: /key-concepts/developers +--- + +API7 门户就像一个繁忙的市场，而 _开发者_ 是其中最重要的顾客。他们是构建者、创新者，以及 API 成功背后的驱动力。这些技术娴熟的人员来到你的 API7 门户，寻求他们创建出色应用程序、集成系统和解决现实问题所需的数字工具和资源。 + +## 概述 + +开发者是 API7 门户的最终用户。他们有能力： + +* **发现 API：** 浏览你的 API 目录并找到他们需要的功能。 +* **学习和实验：** 访问文档、教程和代码示例，以了解如何使用你的 API。 +* **试用 API：** 使用 API 控制台或沙盒等交互式工具在集成 API 之前对其进行测试。 +* **订阅 API 产品：** 获取他们项目所需的特定 API 集合的访问权限。 +* **管理他们的使用情况：** 监控他们的 API 使用情况，跟踪他们的订阅并管理他们的 API 密钥。 + +## 使用案例 + +### 内部开发者 + +对于内部用例，利用员工帐户通过单点登录 (SSO) 安全便捷地访问 API7 门户。这种方法简化了用户管理，因为开发者和提供者可以使用他们现有的员工凭据。 + +### 合作伙伴开发者 + +对于合作伙伴用户，可以通过 SSO 或电子邮件注册进行身份验证。 + +### 公共开发者 + +对于公共 API7 门户，匿名用户可以查看 API 中心和文档页面。通过电子邮件进行用户注册需要管理员批准。 + +## 开发者 vs 消费者 + +[消费者](./consumers) 也可以管理 API 凭据并通过插件利用访问控制，但与开发者相比，它们通常用于不同的场景。 + +| | 开发者 | 消费者 | +| ------------| ----------------------| ------------------------------------- | +| 凭据 | 由开发者自己管理，对提供者不可见 | 由提供者管理 | +| API 访问控制 | 开发者请求访问，提供者批准订阅 | 提供者可以直接从白名单/黑名单中添加或删除消费者 | + +开发者和消费者可以同时用于不同的 API，独立运行。但是，对于给定的已发布服务及其关联的 API 产品，应使用 API7 网关身份验证插件或 API 产品身份验证配置。 + +对于私有服务，通过 API7 网关中的消费者管理来限制访问。对于公共服务，将它们分组到定义良好的 API 产品中，并通过 API 产品配置管理开发者访问。 + +强烈建议不要将 API7 网关身份验证插件和 API 产品身份验证配置组合用于同一已发布服务（仅适用于非常特殊的情况）。这可能会导致身份验证冲突，需要多个凭据才能成功进行 API 请求。 + +## 相关阅读 + +* 核心概念 + * [API 产品](./api-products) +* API 门户 + * [支持开发者 SSO](../api-portal/developer-sso) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/gateway-groups.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/gateway-groups.md new file mode 100644 index 00000000..9b32b8ea --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/gateway-groups.md @@ -0,0 +1,77 @@ +--- +title: 网关组与网关实例 +slug: /key-concepts/gateway-groups +--- + +本文将介绍 API7 网关中的高级功能：网关组与网关实例的概念及用法。 + +## 概述 + +_网关实例_ 是处理流量的单个代理，而 _网关组_ 是一个逻辑单元，结合了一个或多个 API 网关实例。这确保了 API 处理的一致性，并简化了整个组的管理。网关组内的多个网关实例独立运行，以实现横向扩展和负载均衡。虽然使用集中配置，但网关实例不共享状态。 + +默认网关组足以应付简单的场景，例如只有一个集群或生产环境。高级网关组用于复杂的场景，针对不同的子公司、业务线、集群和环境（如 UAT 和 Staging）有单独的 API 策略。虽然 API7 企业版缺乏多个集群和环境的概念，但你可以通过命名和标记网关组来实现相同的目标。 + +一个网关组包含一个或多个网关实例，但每个网关实例只属于一个网关组。网关实例可以部署在相同或不同的虚拟机、裸机服务器或 Kubernetes 节点上。这样的组合可以满足用户在多条业务线、集群、工作区和环境中的不同需求。 + +例如，在下图中，有两个团队在公司中使用 API 网关：支付团队和报价团队。支付团队拥有生产和 UAT 环境，而报价团队只有一个生产环境。在这种情况下，可以创建三个网关组：`Payment Prod`、`Payment UAT` 和 `Quote Prod`，并用 `Env:Prod` 和 `Env:UAT` 对它们进行标记。 + +![Gateway Groups](https://static.apiseven.com/uploads/2024/05/20/LD9mpa5Y_gateway-groups.png) + +## 主要功能 + +- **API 网关组管理**：将 API 网关集合作为共享相同配置的逻辑单元进行管理。这简化了管理，并确保了跨网关实例的一致策略实施。 + +- **业务对齐的网关分区**：通过将企业的业务线和解决方案分配给专用的 API 网关组来隔离它们。这种架构方法可以更好地协调 API 基础架构和组织的功能域。 + +- **物理隔离**：网关组在不同的物理环境（包括数据中心、云平台和虚拟机）中隔离多个 API 网关实例。这有效防止了网关组之间的干扰，提高了系统的稳定性和安全性。 + +- **弹性扩展**：网关组根据流量波动动态添加或删除 API 网关实例，以满足业务需求。这提高了资源利用率并降低了运营成本。 + +- **可扩展且灵活的基础架构**：API 网关组的逻辑架构与单个网关实例的物理部署分离。这种方法为 API 基础架构提供了更大的灵活性和可扩展性。 + +- **细粒度的权限控制**：网关组可以为不同的网关实例和 API 启用不同的权限配置，以符合合规性要求。 + +- **Ingress Controller**：支持 Kubernetes Ingress Controller，使用 API7 企业版作为高性能反向代理。使用声明式方式来配置 API7 企业版提供的资源。 + +## 用例 + +### 隔离开发、测试、UAT 和生产环境 + +API 的部署和发布要经过不同的阶段和环境，这取决于公司的 API 管理流程。假设你的公司有四个环境：开发、测试、UAT 和生产。如果不使用网关组，你需要部署 4 个独立的 API7 企业版实例，每个实例都有独立的控制平面和数据平面。开发人员、QA 和运维工程师需要通过不同域名的 API7 企业版控制平面来开发、测试和发布同一个 API。 + +这种方法有很大的缺点。当你有 5 条业务线时，每条业务线有 4 个环境，你需要部署总共 20 套 API7 企业版，造成资源浪费，增加管理成本。 + +利用 API7 企业版的网关组功能，你可以轻松克服这一挑战。你可以创建 20 个不同的网关组，遵循结合业务线和环境名称的命名约定，并添加标签以便过滤和选择。此外，可以应用基于角色的访问控制（RBAC）来实现细粒度的权限控制。这样一来，开发人员就只能修改开发环境中的配置。 + +### 管理跨不同区域的多个集群 + +对于拥有全球客户群的公司来说，要管理跨多个区域和集群的 API 服务，同时确保数据合规性，是一项挑战。 +假设你的公司在北美、欧盟和亚太地区运营，每个地区有 4 个生产集群。如果没有网关组，你需要维护 12 套 API 网关控制平面和数据平面。 +然而，这种方法很容易出现配置不一致的问题。 + +一致的 API 网关配置并不能保证记录器、秘密和可观察性工具的加密、隐私和合规性--需要额外的工作。 + +API7 的网关组提供了一个解决方案，可以使用一个控制平面集中管理和配置跨多个地区的 API 网关集群。你可以使用环境变量、服务发现和注册中心来简化和统一管理和维护，从而降低总体维护成本。 + +此外，API7 网关支持多层网络，可以在不同区域实现无缝的数据处理和合规性。如果一个名为 John 的美国用户从欧洲登录，欧盟集群可以根据他的用户 ID 确定并将他的 API 请求重定向到北美集群。这种能力确保了合规性和高效的 API 请求处理。 + +### 满足不同项目的服务级别目标 + +不同项目的服务的服务级别目标（SLO）各不相同。例如，支付服务的 SLO 可以是 99.999%，而历史订单服务的 SLO 可能是 99%。可以针对每个服务使用特定的策略，以符合其各自的 SLO。 + +基础设施和运营团队可以在多个区域部署支付服务。然后为该网关组分配更多的网关实例和更高质量的机器资源，并为其设置严格的警报策略和详细的可观察性指标。相反，对 SLO 要求较低的历史订单服务可以采用轻量级部署策略，放松警报和监控，以减少资源分配。 + +## 网关实例状态 + +网关实例状态表示网关实例（数据面）与控制面之间的连接。每个网关实例会定期报告。只有健康的网关实例才能处理 API 流量。 + +- 健康：网关实例运行正常。 +- 仅心跳：此状态表示配置交付失败，即使网关实例通过心跳探针与 API7 控制面保持连接。 +- 连接丢失：API7 网关控制面超过 30 秒但少于 2 小时未检测到网关实例。 +- 离线：API7 网关控制面超过 2 小时未检测到网关实例。在这种情况下，如果网关实例仍然无法连接到 API7 网关控制面，则网关实例将在 7 天后被移除。 + +## 相关阅读 + +- 快速入门 + - [新增网关组](../getting-started/add-gateway-group.md) + - [将已发布的服务版本同步到其他网关组](../getting-started/sync-service.md) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/overview.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/overview.md new file mode 100644 index 00000000..b22382bc --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/overview.md @@ -0,0 +1,10 @@ +--- +title: 核心概念总览 +slug: /key-concepts/overview +--- + +
+
+key concept +
+
\ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/plugins.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/plugins.md new file mode 100644 index 00000000..8ac4c4d4 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/plugins.md @@ -0,0 +1,80 @@ +--- +title: 插件 +slug: /key-concepts/plugins +--- + +在本文档中，你将了解 API7 企业版中插件的基本概念以及为什么需要插件。你将了解一些插件的相关概念，包括插件启用、插件配置文件优先级、插件执行过滤器和顺序，以及插件开发。 + +## 概述 + +API7 企业版插件扩展了 API7 企业版的功能，满足组织或用户在流量管理、可观测性、安全性、请求/响应转换、无服务器计算等方面的特定要求。 + +API7 企业版提供了许多插件，可以根据你的需求进行定制和编排。这些插件可以全局启用，以便在每个传入请求上触发，或者本地绑定到其他对象，例如[路由](./routes.md)、[服务](./services.md)或[消费者](./consumers.md)。 + +如果现有的 API7 企业版插件不能满足你的需求，你还可以使用 Lua 或 Java、Python、Go、Wasm 等其他语言编写自己的插件。 + +## 插件执行生命周期 + +然后根据定义的 [JSON 架构](https://json-schema.org)检查插件的配置，以确保插件配置架构正确。 + +当发送请求到 API7 企业版时，会在以下一个或多个阶段执行插件相应的方法：`rewrite`、`access`、`before_proxy`、`header_filter`、`body_filter` 和 `log`。这些阶段很大程度上受到 [OpenResty 指令](https://openresty-reference.readthedocs.io/en/latest/Directives/)的影响。 + +
+
+路由图 +
+
+ +想要了解有关自定义插件开发阶段的更多信息，请参阅插件开发操作指南（即将推出）。 + +## 插件执行顺序 + +一般来说，插件按以下顺序执行： + +1. 全局规则中的插件 + 1. 重写阶段的插件 + 2. 接入阶段的插件 + +2. 与其他对象绑定的插件 + 1. 重写阶段的插件 + 2. 接入阶段的插件 + +在每个[阶段](#插件执行生命周期)中，你可以选择在插件的 `_meta.priority` 属性中定义一个新的优先级值，该值在执行期间优先于默认的插件优先级。具有较高优先级值的插件将首先执行。有关示例，请参阅插件通用配置。 + +## 插件合并优先级 + +当同一个插件在全局规则中全局配置和在对象（例如路由）中本地配置时，两个插件实例都会按顺序执行。 + +但是，如果在多个对象上本地配置同一个插件，例如在[路由](routes.md)、[服务](services.md)或[消费者](consumers.md)上配置同一个插件，则只有一份配置副本可用。这是因为在执行期间，这些对象中配置的插件会按照特定的优先顺序进行合并： + +`消费者` > `路由` > `服务` + +因此，如果一个插件在不同对象中有不同的配置，则在合并时将使用优先级最高的插件配置。 + +## 插件执行过滤器 + +默认情况下，所有插件均由与路由中配置的规则匹配的传入请求触发。有时你可能需要更精细地控制插件的执行，即有条件地确定请求触发哪些插件。 + +API7 企业版允许通过将 `_meta.filter` 配置应用于插件来动态控制插件执行。该配置支持评估各种内置变量和 API7 企业版表达式。 + +## 插件全局规则 + +全局规则对象用来启用每个传入请求上的[插件](./plugins.md)。在其他插件本地绑定到[路由](routes.md)、[服务](services.md)和[消费者](consumers.md)等其他对象之前，就会执行全局规则。某些插件（例如 `rate limiting` 和 `observability` 插件）经常在全局范围内启用，为 API 提供一致且全面的保护。 + +## 插件元数据 + +插件元数据对象用于配置共享相同插件名称的所有插件实例的公共元数据字段。它适用于跨多个对象启用插件并且需要对其元数据字段进行通用更新。插件元数据对象只能用于具有元数据字段的部分插件，大部分插件并没有元数据的设置。 + +下图说明了插件元数据的概念： + +
+ +
+具有两条路由和一个插件元数据的插件元数据图 +
+ +
+ +插件元数据对象上的 `log_format` 将相同的日志格式统一应用于两个 `syslog` 插件。 + +如果在插件元数据和另一个对象中都定义了插件字段，则对象上的定义**优先于**插件元数据中的定义。 diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/roles-and-permission-policies.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/roles-and-permission-policies.md new file mode 100644 index 00000000..40751bff --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/roles-and-permission-policies.md @@ -0,0 +1,165 @@ +--- +title: 角色与权限策略 +slug: /key-concepts/roles-and-permission-policies +--- + +本文档将介绍 API7 企业版中的高级功能：角色和权限策略的概念。 + +## 概述 + +* 角色：定义具有特定访问级别的用户组。你可以创建自定义角色，对具有相似权限需求的用户进行分类。**一个角色可以与多个权限策略相关联。** +* 权限策略：它们可以被视为一种蓝图，用来概括 API7 企业版中特定资源（例如，网关组、已发布的服务）的允许操作（权限）。**单个权限策略可以被多个角色同时关联，也可以被直接用作某些用户的权限边界，从而防止用户越权。** + +## 角色和权限策略工作原理 + +考虑这样一种场景：你创建了一个名为 `网关组管理员` 的自定义角色，并为其关联名为 `网关组基本操作` 的权限策略。 +此权限策略将 `GetGatewayGroups` 操作授予所有网关组资源（资源范围为 `*`），允许用户在控制台上查看网关组列表，并直接使用 `Get all gateway groups` API 或利用 API7 工具（如 ADC 和 API7 Ingress Controller）检索网关组列表。 + +关键点： + +* 角色用于根据用户的共享权限要求对用户进行分类。对角色的关联权限策略的更改将影响该角色关联的所有用户。 +* 权限策略指定了 API7 企业版（包括 API7 网关 和 API7 门户）内指定资源的授权操作。 +* 将权限策略关联到多个角色会将关联的权限授予这些角色中的所有用户。 +* 权限策略可以根据需要进行详细或广泛的定义。建议从基本设置开始，然后随着访问控制要求的发展对其进行细化。 + +## 使用案例 + +### 内置超级管理员角色 + +API7 企业版在初始系统设置时提供了一个预定义的角色，名为 `超级管理员`。此角色与内置的 `super-admin-permission-policy` 相关联，该策略授予对 API7 企业版内所有操作和资源的完全访问权限。内置的角色和策略都是不可编辑的，以确保核心系统安全。 + +初始 `admin` 帐户永久绑定到 `超级管理员` 角色，并且其角色无法更改。 + +### 使用自定义角色扩展访问控制 + +API7 企业版中还能够创建具有精细权限的自定义角色。对于需要完全访问的场景，你也可以直接将 `super-admin-permission-policy` 关联到你的自定义角色。 + +示例场景：隔离环境和定制安全性 + +通过将权限策略限定在特定网关组的资源范围内，你可以为每个环境定义精细的安全控制。与测试或 UAT 等开发环境中更宽松的权限设置相比，你可以在生产等环境中实施更严格的访问限制。 + +1. 定义权限策略 + +为每个网关组创建特定的权限策略，例如 `测试网关组完全操作`、`UAT网关组完全操作` 和 `生产网关组网完全操作`。这些策略分别定义了每个网关组（对应不同环境）中允许的操作和资源。 + +2. 分配角色 + +创建自定义角色以对具有相似访问需求的用户进行分类，然后将适当的权限策略关联到每个角色： + +* 开发团队成员：关联 `测试网关组完全操作` 策略，允许他们仅在测试环境中进行更改。 +* 开发团队领导：关联 `测试网关组完全操作` 和 `UAT网关组完全操作` 策略。这使他们能够在测试和 UAT 环境中工作，还包括将服务版本从测试同步到 UAT 的能力。 +* 测试工程师：关联 `UAT网关组完全操作` 和 `生产网关组完全操作` 策略。这将他们的访问权限限制在 UAT 和生产环境，专注于新的 API 测试和发布任务。 + +### 防止用户越权 + +用户的角色可能经常发生变化，因此你可能需要一种保障措施来确保边界限制。 例如，权限边界可用于防止 A 部门用户访问 B 部门拥有的资源。权限边界还可用于防止意外访问关键系统组件，例如许可证或组织设置。通过明确拒绝访问这些区域，你可以维持一个强大的安全层，保护敏感配置免遭未经授权的修改。 + +## 如何配置权限策略 + +API7 企业版目前将权限策略存储为 JSON 文件。 + +```json +// PermissionPolicy 示例 +{ + "statement": [ + { + "resources": [ + "arn:gatewaygroup:<[^:]*>" // 必填字段，可操作的资源范围，通过资源 ID 指定，可使用通配符。此示例中指所有网关组资源。 + ], + "actions": [ + "GatewayGroup:DeleteGatewayGroup" // 必填字段，允许的操作，从预定义好的操作集合中选择，注意和资源类型要配套。此示例中指删除网关组的操作。 + ], + + "conditions": { // 可选字段，用标签筛选可操作的资源范围。此示例中指所有带“环境类型：生产”标签的网关组。 + "gateway_group_label": { + "type": "MatchLabel", + "options": [ + { + "key": "环境类型", + "operator": "exact_match", + "value": "生产" + } + ] + } + }, + "effect": "allow" // 必填字段，指定 actions 的效果，只能是 allow 或者 deny。 + } + ] +} +``` + +* API7 企业版中的单个权限策略可以包含多个语句（Statement），这些语句定义的资源和操作可以重叠， 它们之间是 OR 的关系。 +* API7 企业版对权限策略执行“拒绝覆盖允许”的原则。 + * 对某个具体角色来说，如果关联了多个权限策略，只要有任意一个策略中有任意一个语句（Statement）定义为“拒绝”（deny），则其他关联的权限策略中所有语句中对同一个资源及操作的“允许”（allow）都将无效。 + * 对某个用户来说，如果被授权了多个角色，只要有任意一个角色或该用户的权限边界策略最终拒绝了对某一个资源及操作的“拒绝”（deny），则无论其他角色是否允许，该用户都无法对这个资源进行指定的操作。 + +### 示例 + +假设有三个网关组： + +* 名称：测试网关组，带有标签 `环境类型：测试`、`部门： A` +* 名称：蓝色网关组，带有标签 `环境类型：生产`、`部门： B` +* 名称：绿色网关组，带有标签 `环境类型：生产`、`部门： A` + +假设一个自定义角色，关联了上一个小节中示例权限策略，有一个用户被授予了这个角色。此用户可以通过控制台或 API7 工具删除 `蓝色网关组` 和 `绿色网关组`，但不能删除 `测试网关组`。 + +但是，如果 `测试网关组` 的标签更改为 `生产`，则由于匹配标签成功，用户可以将其删除。同样，新创建的带有 `环境类型：生产` 标签的 `黑色网关组` 也将能够被此用户删除。 + +### 在权限策略条件中使用标签 + +在权限策略条件中使用标签具有以下优点和缺点： + +#### 优点 + +* 动态访问控制：标签可以随时改变，但资源 ID 不可变更。使用标签可以在不改变权限策略本身的情况下变更对资源的访问控制。 +* 可扩展性：单个标签可以应用于多个资源，方便批量授权管理。使用标签可以避免以下情况：用户创建新资源（例如，网关组）但无法访问它，因为权限策略中只会引用其他存量资源 ID，无法包括还没创建出来的新资源 ID。 + +#### 缺点 + +* 清晰度降低：标签引入了一个抽象层，可能会使人更难一目了然地了解策略适用于哪些特定资源。 +* 错误配置风险：不一致或不准确的标签可能会导致意外的访问授予或拒绝。 +* 动态访问控制导致意外行为：虽然标签提供了灵活性，但它们可以引入动态访问控制。这意味着用户访问特定资源的能力可能会根据资源标签的更新而发生变化，与使用静态资源 ID 相比，这可能会导致访问行为更不可预测。 + +找到合适的平衡： + +* 标签适用较宽泛的分类：将标签用于更宽泛的访问控制类别（例如，“生产”、“测试”）。 +* 细粒度控制使用资源 ID：对需要细粒度控制的特定资源使用资源 ID。 +* 清晰的标签规划：确保在整个 API 环境中保持一致且定义明确的标签定义。 + +通过了解这些利弊并实施最佳实践，你可以有效地利用标签来增强 API7 企业版权限策略的安全性和可管理性。 + +### 使用技巧 + +#### 授予最小权限 + +仅授予用户在 API 环境中执行指定任务所需的最小权限。为了实现这一点，首先要明确定义用户和角色的需求。然后，制定具有一组受限操作和资源的权限策略。最后，仅在绝对必要时添加更多权限，确保管理效率和强访问控制之间的平衡。 + +优点： + +* 减少攻击：限制权限可最大限度地减少风险帐户的潜在影响。 +* 增强问责制：明确的用户访问限制可促进更好的所有权和责任感。 +* 简化管理：维护最小权限简化了权限管理并降低了意外疏忽的风险。 + +#### 配置角色和权限策略的权限 + +与 API7 企业版中的其他资源一样，角色和权限策略本身也需要明确定义的访问控制。以下是两种常用方法： + +1. 集中的角色和权限策略管理：指定专门的用户同时负责更新角色本身并修改其所有关联权限策略，以及将角色授权给其他用户。通过一起管理这两个方面来简化他们的工作流程。在这种情况下，用角色和权限策略一对一的原则来设计有助于简化。 + +2. 隔离管理角色和权限策略：指定专门的用户只负责更新角色及其关联权限策略，但不负责将角色授权给用户。这适合角色内容相对稳定，但被授予的用户频繁流动变化的情况。 + +最佳方法取决于你的具体需求。考虑以下因素来进行抉择： + +* 角色成员变更的频率 +* 维持稳定角色和策略内容的必要性 + +## 相关阅读 + +* 快速入门 + * [更新用户角色](../getting-started/rbac.md) + * [创建自定义角色](../getting-started/create-custom-role.md) +* 最佳实践 + * [设计自定义角色系统](../best-practices/design-custom-role-system.md) +* 开发参考 + * [权限策略操作和资源](../reference/permission-policy-action-and-resource.md) + * [权限策略示例](../reference/permission-policy-example.md) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/routes.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/routes.md new file mode 100644 index 00000000..9822ff23 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/routes.md @@ -0,0 +1,39 @@ +--- +title: 路由 +slug: /key-concepts/routes +--- + +API7 网关有两种主要的工作模式： + +1. 应用层代理，又称七层代理： 在此模式下，API7 网关 作为 HTTP 请求和响应的中介，在 OSI 模型的应用层（第7层）运作。路由用于定义如何处理这些 HTTP 请求。 +2. 传输层代理，又称四层代理： API7 网关还可以作为传输层代理，在 OSI 模型的传输层（第 4 层）运作。此模式非常适合处理 TCP 和 UDP 等协议。对于四层代理，将使用四层路由来定义传入的 TCP/UDP 连接如何路由到后端服务。 + +路由或者四层路由将根据配置的规则匹配客户端请求，加载并执行相关插件，然后将请求转发到指定的上游节点。一个路由必须属于一个服务，不能孤立或在多个服务之间共享。 + +## 路由工作原理 + +你可以把 API7 网关想象成 API 的智能交通指挥。当请求到达时，API7 网关会检查其定义的路由，找到最佳匹配，并将请求定向到对应的后端服务。 + +假设现在你有一个 API，其中有一个 `/pet` 的路由。这个路由可能匹配诸如 `GET /pet` 或 `POST /pet/create` 等请求。在将请求转发到对应的后端服务器之前，还可以配置该路由以应用特定的插件（例如，用于速率限制或身份验证）。 + +该图展示了如何向 API7 发送两个 HTTP 请求，然后根据路由中配置的规则进行转发： + +
+
+Routes Diagram +
+

+ +:::info + +如果你熟悉 Apache APISIX，请注意路由和服务之间的关系与 API7 企业版中的不同。 + +::: + +## 相关阅读 + +- 核心概念 + - [服务](services.md) + - [上游](upstreams.md) +- 快速入门 + - [创建一个简单的 API](../getting-started/launch-your-first-api.md) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/secrets.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/secrets.md new file mode 100644 index 00000000..55b3638b --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/secrets.md @@ -0,0 +1,58 @@ +--- +title: 密钥（Secret） +slug: /key-concepts/secrets +--- + +在本文档中，你将学习 API7 网关中 *密钥（Secret）* 和 *Secret 提供商* 的基本概念以及为什么你可能需要它们。 + +在文档末尾浏览其他资源以获取有关相关主题的更多信息。 + +## 概述 + +*密钥（Secret）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商* 对象用于设置与外部密钥管理服务（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理服务中获取密钥。 + +通过将密钥存储在专用的密钥管理服务中，你可以： + +* 降低数据泄露的风险：最大限度地减少 API7 网关中敏感信息的暴露。 +* 简化管理：集中密钥的存储和检索，简化配置和维护。 +* 增强安全性：利用外部密钥管理服务的高级安全功能和审计功能。 +* 提高合规性：确保符合行业法规和数据保护的最佳实践。 + +## 使用案例 + +### 保护消费者凭据 + +消费者凭据中的以下敏感字段可以存储在外部密钥管理服务（HashiCorp Vault、AWS Secret Manager 等）中，并在 API7 网关中引用： + +* Key Authentication 凭据中的 `key` +* Basic Authentication 凭据中的 `password` +* JWT 认证凭据中的 `secret`、`public key` +* HMAC 认证凭据中的 `secret key` + +有关详细教程，请参阅 [管理消费者凭据](../api-consumption/manage-consumer-credentials)。 + +### 保护插件配置中的敏感字段 + +插件配置中的以下敏感字段可以存储在外部密钥管理服务（HashiCorp Vault、AWS Secret Manager 等）中，并在 API7 网关中引用： + +|插件|字段| +|:---|:---| +|Limit Count|`redis_username`、`redis_password`| +|[Authz-Casdoor](https://apisix.apache.org/docs/apisix/plugins/authz-casdoor/)|`client_id`、`client_secret`| +|[Wolf RBAC](https://apisix.apache.org/docs/apisix/plugins/wolf-rbac/)|`appid`| +|[LDAP 认证](https://apisix.apache.org/docs/apisix/plugins/ldap-auth/)|`user_dn`| + +例如，请参阅 [API 限流限速](../api-security/rate-limiting) 并在插件配置中使用密钥。 + +## 相关阅读 + +* 核心概念 + * [插件](./plugins) + * [消费者](./consumers) +* API 安全 + * [引用 HashiCorp Vault 中的密钥](../api-security/hashicorp-vault) + * [引用 AWS Secrets Manager 中的密钥](../api-security/aws-secrets-manager) +* API 消费 + * [管理消费者凭据](../api-consumption/manage-consumer-credentials) + * [API 限流限速](../api-security/rate-limiting) +``` \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md new file mode 100644 index 00000000..7fe4dd82 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md @@ -0,0 +1,79 @@ +--- +title: 服务 +slug: /key-concepts/services +--- + +一个服务代表了一个后端应用或外部的微服务。它本质上将该应用或微服务提供的所有 API 进行了分组。以下是几个和服务有关的关键关系： + +* **路由（Route）与四层路由（Stream Route）**：大多数服务与路由或四层路由（二者不能共存于一个服务之内）之间是一对多的关系。这意味着一个服务可以与多个路由或流路由关联，定义了传入的 API 请求如何被导向到服务内的相应功能。 + +* **上游**： 通常，服务与上游保持一对一的关系。上游充当容器，指定处理服务请求的后端服务器的地址。但是，对于高级场景（例如灰度部署、蓝绿部署或管理多个集群），服务可能会使用多个上游。在这种情况下，默认上游充当大多数请求的主要目标，而其他上游可用于特定目的，例如将流量路由到金丝雀部署或辅助集群。 + +:::info + +对于熟悉 Apache APISIX 的人来说，需要注意的是，API7 企业版中的服务对象与 Apache APISIX 中的服务对象是不同的。 + +::: + +## 服务工作原理 + +下图展示了一个已发布的服务，该服务架构了一个宠物店（`Petstore`）服务。该服务具有两个具有分别配置的路由。你可以使用 HTTP GET 方法从该服务获取相关数据。 + +
+
+Services Diagram +
+

+ + +本示例仅将流量转发到一个上游节点。你可以根据需要为服务添加更多上游节点，以维持平稳的运行和响应，同时防止单点故障。 + +## 服务状态 + +一个服务可以有多个版本，每个版本有三种状态：模板、已发布和历史。这些状态代表了服务的整个 API 生命周期。每个服务都有自己的版本号体系。如果版本号相同，则说明服务的表现完全相同。 + +### 模板 + +模板是初始状态，代表最新的未发布配置草案。模板中的 API 不可访问，也没有特定的版本号。 + +### 已发布 + +将模板发布到网关组会创建一个具有唯一版本号的已激活版本。已发布版本中的 API 和网关组绑定，用户可以访问网关组内的 API，但是只能编辑其运行时配置（主机、路径前缀和上游节点）。更新正在运行中的 API 时，必须发布新的服务版本。模板更改不会影响已发布的版本。 + +### 历史 + +发布新版本时，以前的版本会转换为历史版本。请注意，一个服务不能同时在网关组中拥有两个已激活版本，但不同的网关组可以同时运行不同的版本。 + +历史版本为问题追踪提供了对过去配置的可见性，但不可编辑。它们主要用于紧急回滚。 + +历史版本不包括[运行时配置](#运行时配置)。回滚时会保留当前值。 + +## 运行时配置 + +以下配置被归类为运行时配置。这是因为当同一服务版本发布到不同网关组时，它们可能会有不同的值，而且可以在网关组内直接编辑。这些配置并不构成不同的版本。 + +* 上游配置 +* 服务发现 +* 服务主机 +* 路径前缀 + +:::info + +例如 + +* 测试环境中的 API URL 是 `https://api7-test.ai/v1/pet`，节点地址是 `127.0.0.1:80`。 +* 生产环境中的 API URL 是 `https://api7.ai/petstore/pet`，节点地址是 `192.168.0.1:80`。 + +::: + +## 相关阅读 + +* 核心概念 + * [路由](routes.md) + * [上游](upstreams.md) + * [四层路由](stream-routes.md) +* 快速入门 + * [发布服务](../getting-started/publish-service.md) + * [在不同网关组之间同步服务版本](/enterprise/getting-started/sync-service) +* 最佳实践 + * [API 版本控制](../best-practices/api-version-control.md) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/snis.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/snis.md new file mode 100644 index 00000000..b3d3b892 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/snis.md @@ -0,0 +1,28 @@ +--- +title: SNI +slug: /key-concepts/snis +--- + +SNI 对象表示 [服务](./services) 的主机名和 [证书](./certificates) 之间的多对多映射关系。因此，单个证书对象可以通过使用 SNI 由多个服务共享。 + +## SNI 工作原理 + +由于 API7 网关位于实际后端服务的前面，因此它在握手中充当服务器的角色。 + +当客户端发起 SSL/TLS 连接时，它会在 TLS 握手的服务器名称指示 (SNI) 字段中包含它尝试访问的主机名。服务器使用从客户端接收到的 SNI 从其存储库中选择合适的 SSL 证书。然后，服务器将匹配的证书呈现给客户端，完成 TLS 握手并建立安全连接。 + +在 mTLS 中，除了 SLL 证书之外，还需要 CA 证书。服务器出示其证书后，客户端也向服务器出示自己的证书。服务器使用公钥验证客户端证书。这确保了客户端经过身份验证并有权访问服务器的资源。客户端和服务器现在都验证了彼此的身份，建立了安全且相互认证的连接。 + +## 使用案例 + +* **有效利用资源：** 允许具有不同主机名的多个服务共享证书管理，从而降低基础架构成本和复杂性。 +* **增强的安全性：** 确保为每个主机名提供正确的 SSL 证书，维护安全连接并防止潜在的安全漏洞。 + +## 相关阅读 + +* 核心概念 + * [服务](./services) + * [SNI](./snis) +* API 安全 + * [在客户端和 API7 网关之间配置 mTLS](../api-security/client-mtls) + \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/ssl-certificates.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/ssl-certificates.md new file mode 100644 index 00000000..6c8f7e1f --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/ssl-certificates.md @@ -0,0 +1,39 @@ +--- +title: SSL 证书 +slug: /key-concepts/ssl-certificates +--- + +在本文档中，你将了解 SSL 证书对象的基本概念以及可能需要它们的场景。 + +传输层安全（Transport Layer Security，TLS）是安全套接字层（Secure Socket Layer，SSL）协议的后继者，是一种加密协议，旨在保护两方（例如 Web 浏览器和 Web 服务器）之间的通信安全。它是在现有协议（例如 HTTP 或 TCP）之上实现的，通过 TLS 握手建立连接并加密数据传输来提供额外的安全层。 + +下图展示了 [TLS v1.2](https://www.rfc-editor.org/rfc/rfc5246) 和 [TLS v1.3](https://www.rfc-editor.org/rfc/rfc8446) 两种最常用的 TLS 版本中的**单向 TLS 握手**： + +
+TLS v1.2 和 TLS v1.3 的 TLS 握手 +
+ +在此过程中，服务器通过提供其证书向客户端验证自身身份。客户端验证证书以确保其有效并且由受信任的机构颁发。验证证书后，客户端和服务器就共享密钥达成一致，该密钥用于加密和解密应用程序数据。 + +![SSL](https://static.apiseven.com/uploads/2024/03/19/hUPCVsL3_SSL%20%E6%A6%82%E5%BF%B5.png) + +API7 企业版还支持双向 TLS（mTLS），其中客户端通过提供其证书来向服务器验证自身身份，从而有效地创建 mTLS 连接。这可以确保双方都经过认证，并有助于防止类似于[中间人](https://zh.wikipedia.org/wiki/%E4%B8%AD%E9%97%B4%E4%BA%BA%E6%94%BB%E5%87%BB)这样的网络攻击。 + +要在具有 API7 企业版的系统中启用 TLS 或 mTLS，你应该在客户端应用程序、API7 企业版和/或上游服务器上等适当的位置生成和配置证书。对于 API7 企业版端的配置，可能需要 SSL 证书对象，具体取决于你要保护的通信段： + +
+ +| | **TLS** | **mTLS** | +|------------------------------------|------------- --|----------| +| **客户端应用程序 -- API7 企业版** |必填 |必填| +| **API7 企业版 -- 上游服务** |不需要|可选| + +
+ +[//]: +[//]: +[//]: +[//]: diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/stream-routes.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/stream-routes.md new file mode 100644 index 00000000..970c318a --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/stream-routes.md @@ -0,0 +1,27 @@ +--- +title: 四层路由 +slug: /key-concepts/stream-routes +--- + +API7 网关有两种主要的工作模式： + +1. 应用层代理，又称七层代理：在此模式下，API7 网关作为 HTTP 请求和响应的中介，在 OSI 模型的应用层（第7层）运作。路由用于定义如何处理这些 HTTP 请求。 +2. 传输层代理，又称四层代理：API7 网关还可以作为传输层代理，在 OSI 模型的传输层（第4层）运作。此模式非常适合处理 TCP 和 UDP 等协议。对于四层代理，将使用四层路由来定义传入的 TCP/UDP 连接如何路由到后端服务。 + +路由或者四层路由将根据配置的规则匹配客户端请求，加载并执行相关插件，然后将请求转发到指定的上游节点。一个路由必须属于一个服务，不能孤立或在多个服务之间共享。 + +## 四层路由工作原理 + +四层路由配置中的`远程地址`字段充当了基于客户端 IP 地址的过滤器。只有源自该字段明确列出的 IP 地址的请求才被允许通过路由并到达上游服务（例如 MySQL 服务器）。 + +例如，假设你有一个仅供内部使用的 MySQL 服务器。你可以创建一个四层路由，其远程地址过滤器设置为公司的内部 IP 范围。这将只允许来自你网络中授权机器的连接通过 API7 网关访问 MySQL 服务器。 + +API7 网关还提供除客户端 IP 过滤之外的额外过滤选项。四层路由配置中的`服务器地址`和`服务器端口`字段，让你可以对传入连接进行更精细的控制。你可以指定上游服务的允许服务器地址和端口，进一步限制对授权目的地的访问。 + +## 相关阅读 + +* 核心概念 + * [服务](services.md) + * [上游](upstreams.md) +* 快速入门 + * [转发四层流量](../getting-started/proxy-l4-traffic.md). diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/upstreams.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/upstreams.md new file mode 100644 index 00000000..7bb3fcad --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/upstreams.md @@ -0,0 +1,60 @@ +--- +title: 上游 +slug: /key-concepts/upstreams +--- + +上游就像一个容器，将一个或多个后端服务器地址分组在一起。它是服务中的关键要素，指定了 API 请求的路由方式和分发方式。大多数情况下，一个上游可以链接一个服务内的多个路由。 + +## 上游工作原理 + +想象一个繁忙的机场。旅客（API 请求）抵达，需要被引导到他们的登机口（后端服务）。API7 网关中的上游就像这些登机口。它们不是物理位置，而是定义了传入请求应该发送到哪里的逻辑分组。一个上游可以代表一个后端服务，也可以代表一个用于负载均衡的相同服务池，或者指向具有动态变化后端的注册中心。 + +本质上，上游在路由和它们所指向的实际后端服务之间提供了一层抽象。这种抽象简化了配置管理，并启用了负载均衡和容错等功能。 + +## 应用场景 + +### 单体后端服务 + +一个上游可以代表一个单体的后端服务，这对于后端定义明确且静态的场景非常理想。 + +例如，可以创建一个名为 `user-service` 的上游，指向负责用户数据管理（登录、注册、个人资料更新）的后端服务。这种直接的方式简化了用户相关 API 端点的配置。 + +### 负载均衡池 + +上游可以配置为相同后端的多个服务实例的池。然后，API7 网关可以在这些服务实例之间分配传入的请求，以提高性能和可扩展性。 + +例如，可以配置一个名为`product-service`的上游。但是，此上游将指向扩容的后端服务实例池。这样可以实现负载均衡，将传入的产品信息请求（检索产品详细信息、搜索产品）分配到多个服务实例。随着用户群的增长和产品信息请求的激增，这确保了最佳性能。 + +### 动态服务发现 + +上游可以对接并利用服务注册中心。这允许它们动态发现并连接到向注册中心（例如 Nacos、Kubernetes 等）注册自己的后端服务。这非常适用于后端不断变化或可以自我扩展的微服务。 + +### 灰度部署 + +API7 网关支持使用流量灰度简化后端服务的升级。为新服务版本创建一个单独的上游，并将一小部分流量路由到它。这允许与现有服务（原始上游）一起进行测试。逐渐增加到新版本的流量，同时监控性能。如果稳定，则切换所有流量。通过调整流量分配，回滚也很简单。这种方法最大限度地降低了风险，并简化了开发人员和用户的升级。 + +灰度部署对开发人员（API 的调用者）友好。在灰度阶段，开发人员可以继续使用现有的 API 进行调用，无需修改。API7 网关根据灰度规则处理流量转移，你无需添加更多路由或更改当前的路由配置。 + +下面是路由中上游配置的一个示例： + +
+
+Upstreams Diagram show three routes with different plugins pointing to the same upstream object with the desired upstream address +
+
+ +## 上游健康检查 + +API7 网关提供主动和被动健康检查。这些检查会持续监控你的后端服务（上游节点），以确保它们在线且健康。如果一个节点出现故障，API7 网关会自动停止向其路由流量，直到它恢复。这确保了你的 API 保持响应和可靠。要启用健康检查，你首先需要为后端服务添加 `/health` 端点。 + +## 相关阅读 + +* 核心概念 + * [服务](services.md) + * [上游](upstreams.md) +* 快速入门 + * [灰度流量](../getting-started/canary-upstream.md). +* 最佳实践 + * [上游高可用](../best-practices/upstream-ha.md) diff --git a/enterprise_versioned_docs/version-3.6.x/performance/aws-eks.md b/enterprise_versioned_docs/version-3.6.x/performance/aws-eks.md new file mode 100644 index 00000000..d8830874 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/performance/aws-eks.md @@ -0,0 +1,303 @@ +--- +title: 准备性能测试环境（AWS EKS） +slug: /performance/aws-eks +--- + +## AWS EKS 环境准备 + +### 创建集群 + +1. 在 AWS EKS 中添加一个新的测试集群 + +![create cluster](https://static.apiseven.com/uploads/2024/05/13/AcXSkWUI_create-cluster.png) + +2. 配置测试集群，如果之前没有使用过 EKS 服务配置过集群服务角色，可以根据文档创建一个 EKS 集群角色：[https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html#create-service-role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html#create-service-role) + +![config cluster](https://static.apiseven.com/uploads/2024/05/13/BYWC128m_config-cluster.png) + +3. 点击下一步配置网络设置 + +![cluster network](https://static.apiseven.com/uploads/2024/05/13/E2595vPU_cluster-network.png) + +4. 配置可观测性 + +![cluster observability](https://static.apiseven.com/uploads/2024/05/13/gqpKSq4K_cluster-observability.png) + +5. 选择插件（默认配置），点击下一步 + +![cluster plugin](https://static.apiseven.com/uploads/2024/05/13/EsY6qevQ_cluster-plugin.png) + +6. 点击创建集群，等待 EKS 创建 + +![create success](https://static.apiseven.com/uploads/2024/05/13/RYL1q741_create-success.png) + +### 添加 Node + +#### 创建 Key pair（选做） + +在 node 中配置了 Key Pair 就可以直接登录 node。如果已经有 Key Pair 的话，可以跳过创建 Key pair 这一步。 + +1. 在 AWS 中控台选择 “EC2”，进入 EC2 界面，点击左边的 “Key Pairs”，在右边点击 “Create key pair” + +![create key](https://static.apiseven.com/uploads/2024/05/21/1HYzAM9f_create-key.png) + +2. 添加名称 + +![update key name](https://static.apiseven.com/uploads/2024/05/21/kCRyzjj0_update-key-name.png) + +3. 创建密钥对，这时浏览器会自动下载 key pair，这个要保存好，方便之后使用命令登陆 node + +![create key success](https://static.apiseven.com/uploads/2024/05/21/Xy1gFW8N_create-key-success.png) + +#### 创建节点组 + +我们需要添加 3 个节点组，分别在不同的节点组部署 API7 EE，NGINX 上游，wrk2。 + +**注意：**如果之前没有创建过 EKS Node Role 需要先创建，步骤类似 EKS 创建集群服务角色的过程。可以参考文档：[https://docs.aws.amazon.com/zh_cn/eks/latest/userguide/create-node-role.html](https://docs.aws.amazon.com/zh_cn/eks/latest/userguide/create-node-role.html) + +1. 选择“计算”，点击添加“节点组” + +![add node](https://static.apiseven.com/uploads/2024/05/21/pbvC0F5t_add-node.png) + +2. 配置节点组 + +![config node](https://static.apiseven.com/uploads/2024/05/21/JLqesDKU_config-node.png) + +3. 这里我们选择 `c5.2xlarge` 进行测试，测试过程使用单节点。 + +![config ec2](https://static.apiseven.com/uploads/2024/05/21/eYMlTdkU_config-ec2.png) + +4. 配置网络，这里我们为了方便登陆到 node 中，开启了节点远程访问控制权限，不需要可以不开启。 + +![config node network](https://static.apiseven.com/uploads/2024/05/21/nL7hwmk2_config-node-network.png) + +5. 根据上面的步骤，我们需要创建 3 个节点，名字分别为 api7ee，upstream，wrk2 等待创建完成。 + +![create 3 node](https://static.apiseven.com/uploads/2024/05/21/Fcta9TjI_create-3-node.png) + +#### 使用 aws cli 配置 kubectl config + +1. 通过向 `kubectl` `config` 文件添加新上下文来启用 `kubectl` 与我们创建的集群通信。 + +具体细节参考文档：[https://docs.aws.amazon.com/zh_cn/eks/latest/userguide/create-cluster.html](https://docs.aws.amazon.com/zh_cn/eks/latest/userguide/create-cluster.html) + +```shell +aws eks update-kubeconfig --region region-code --name my-cluster +``` + +2. 执行 `kubectl get svc` 验证成功与集群的通信，输出如下 + +```shell +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +kubernetes ClusterIP 10.100.0.1 443/TCP 39m +``` + +#### 为 Node 打 label + +我们分别为 4 个不同的 Node 打上对应的 label，方便之后的部署 + +```shell +kubectl label nodes + +# example +kubectl label nodes nodeName=api7ee +kubectl label nodes nodeName=upstream +kubectl label nodes nodeName=wrk2 +``` + +## 安装过程 + +### 安装 API7 企业版 + +#### 控制面安装 + +1. 创建一个新的 namespace，之后所有的资源都在同一个 namespace 中管理 + +```shell +kubectl create namespace api7 +``` + +2. 使用 helm 安装 API7 EE CP + +```shell +helm repo add api7 https://charts.api7.ai +helm repo add apisix https://charts.apiseven.com +helm repo update +# 为安装 api7ee 指定 Node (之前我们为 Node 设置的 label) +helm install api7ee3 api7/api7ee3 --set nodeSelector."nodeName"=api7ee --set postgresql.primary.nodeSelector."nodeName"=api7ee --set prometheus.server.nodeSelector."nodeName"=api7ee --set postgresql.primary.persistence.enabled=false --set prometheus.server.persistence.enabled=false -n api7 +``` + +3. 检查部署情况 + +```shell +kubectl get svc -owide -l app.kubernetes.io/name=api7ee3 -n api7 + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR +api7ee3-dashboard ClusterIP 10.100.25.236 7080/TCP 18s app.kubernetes.io/component=dashboard,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3 +api7ee3-dp-manager ClusterIP 10.100.239.32 7900/TCP,7943/TCP 18s app.kubernetes.io/component=dp-manager,app.kubernetes.io/instance=api7ee3,app.kubernetes.io/name=api7ee3 +``` + +4. 将端口转发到本机，登陆控制台并上传 license + +```shell +kubectl -n api7 port-forward svc/api7ee3-dashboard 7443:7443 +``` + +License 试用申请地址：https://api7.ai/try?product=enterprise + +5. 在控制台配置控制面地址：http://api7ee3-dp-manager:7900 + +![config dp address](https://static.apiseven.com/uploads/2024/05/21/oaqJxisN_config-dp-address.png) + +#### 禁用 prometheus 插件 + +控制面默认会为网关组启用全局的 prometheus 插件，进行性能测试时，我们需要将它禁用掉。 + +![disable prometheus](https://static.apiseven.com/uploads/2024/05/21/gvIqecLX_disable-prometheus.png) + +#### 数据面安装 + +1. 点击进入网关组中 + +![access gateway group](https://static.apiseven.com/uploads/2024/05/21/yK4njyFR_access-gateway-group.png) + +2. 点击新增网关实例按钮 + +![add gateway](https://static.apiseven.com/uploads/2024/05/21/Vy0lCBvY_add-gateway.png) + +3. 选择 Kubernetes 方式添加，配置命名空间，生成安装脚本并运行 + +![get scripts](https://static.apiseven.com/uploads/2024/05/21/l8dnlT3Z_get-scripts.png) + +注意我们先修改 API7 Gateway 的 worker_process 数为 1，并指定安装的 Node + +```shell +helm install -n api7 --create-namespace api7-ee-3-gateway api7/gateway \ + --set "apisix.extraEnvVars[0].name=API7_CONTROL_PLANE_TOKEN" \ + --set "apisix.extraEnvVars[0].value=a7ee-1onxEIUNvKhihuwLKIfNvP61QzYisftJp7fwU3MBMNx9W4h1kdbdf9031a24d7448da69b6120a526f902" \ + --set "apisix.image.repository=api7/api7-ee-3-gateway" \ + --set "apisix.image.tag=3.2.8.1" \ + --set "etcd.host[0]=http://api7ee3-dp-manager:7900" \ + --set "apisix.replicaCount=1" \ + --set "nginx.workerProcesses"=1 \ + --set apisix.securityContext.runAsNonRoot=false \ + --set apisix.securityContext.runAsUser=0 \ + --set apisix.nodeSelector.nodeName=api7ee +``` + +### 安装 NGINX 上游 + +1. 创建 nginx-upstream.yaml 文件 + +```yaml +--- +# nginx conf configmap +apiVersion: v1 +kind: ConfigMap +metadata: + name: nginx-config + namespace: api7 +data: + nginx.conf: | + master_process on; + + worker_processes 1; + events { + worker_connections 4096; + } + + http { + resolver ipv6=off 8.8.8.8; + + #access_log logs/access.log; + access_log off; + server_tokens off; + keepalive_requests 10000000; + + server { + listen 1980; + server_name _; + + location / { + proxy_set_header Connection ""; + return 200 "hello world\n"; + } + } + } +--- +# nginx deployment +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + namespace: api7 +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx + volumeMounts: + - name: nginx-config-volume + mountPath: /etc/nginx/nginx.conf + subPath: nginx.conf + nodeSelector: + nodeName: upstream + volumes: + - name: nginx-config-volume + configMap: + name: nginx-config +--- +``` + +1. 部署 nginx 上游 + +```shell +kubectl apply -f nginx-upstream.yaml +``` + +### 安装 wrk2 + +创建 wrk2.yaml 文件，并运行 kubectl apply -f wrk2.yaml + +```yaml +# wrk2 deployment +apiVersion: apps/v1 +kind: Deployment +metadata: + name: wrk2-deployment + namespace: api7 +spec: + replicas: 1 + selector: + matchLabels: + app: wrk2 + template: + metadata: + labels: + app: wrk2 + spec: + containers: + - name: wrk2 + image: bootjp/wrk2 + nodeSelector: + nodeName: wrk2 +``` + +## 测试配置 + +- [1 条路由且未启用任何插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/1-one-route-without-plugin.yaml) +- [1 条路由只启用 limit-count 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/2-one-route-with-limit-count.yaml) +- [1 条路由同时启用 limit-count 和 key-auth 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/3-one-route-with-key-auth-and-limit-count.yaml) +- [1 条路由和 1 个消费者只启用 key-auth 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/4-one-route-with-key-auth.yaml) +- [100 条路由且未启用任何插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/5-100-route-without-plugin.yaml) +- [100 条路由只启用 limit-count 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/6-100-route-with-limit-count.yaml) +- [100 条路由和 100 个消费者同时启用 key-auth 和 limit-count 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/7-100-route-and-consumer-with-key-auth-limit-count.yaml) +- [100 条路由和 100 个消费者只启用 key-auth 插件](https://github.com/api7/api7-gateway-performance-benchmark/blob/main/adc_conf/8-100-route-and-consumer-with-key-auth.yaml) diff --git a/enterprise_versioned_docs/version-3.6.x/performance/benchmark.md b/enterprise_versioned_docs/version-3.6.x/performance/benchmark.md new file mode 100644 index 00000000..38ab7c48 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/performance/benchmark.md @@ -0,0 +1,142 @@ +--- +title: 建立 API7 Gateway 性能测试报告 +slug: /performance/benchmark +--- + +## 前置准备 + +为确保 API7 Gateway 性能评估的准确性，在进行基准测试之前，请遵循以下关键建议和步骤： + +- **选择合适的节点配置**： + 1. 使用单个 API7 Gateway 节点，并根据节点资源（CPU 核心数）合理配置 `worker_processes` 的数量，建议先配置 1 个 `worker_processes` 进行基线测试，确认[结果](#性能基线测试结果)无误后再进行多核心的性能测试。 + 2. 避免使用多个较小 `worker_processes` 数配置的 API7 Gateway 节点。 +- **逐步增加 worker_processes**： + 1. 初始测试时，配置 1 个 `worker_processes` 以获取单核心的性能基线。 + 2. 在确认单核心性能无误后，逐步增加 `worker_processes` 的数量，以评估多核心下的性能表现。 +- **排除上游网络等干扰**： + 1. 仅启用 [mocking](https://apisix.apache.org/docs/apisix/3.2/plugins/mocking/) 插件获取 API7 Gateway 的性能测试结果，此插件将以指定的格式返回模拟数据，且请求不会转发到上游服务器； +- **确保上游服务器性能**： + 1. 在测试过程中，密切监控 API7 Gateway 和上游服务器的性能表现，确保上游服务器不是性能瓶颈。 +- **收集基线值**： + 1. 在进行更多场景的测试之前，先收集基线值。配置 1 个 API7 Gateway 节点，启用 1 个 `worker_processes`。 + 2. 消除网关延迟干扰。将上游服务器和 API7 Gateway 部署在同一台机器，并使用 Host 网络。 + 3. 确保收集的基线值与我们提供的[参考结果](#性能基线测试结果)基本一致。 +- **收集并分析测试结果**： + 1. 收集多组测试结果，通过统计手段（如标准差）分析数据之间的差异，确保测试结果的稳定性和可靠性。 +- **参考优化建议**： + 1. 在遵循上述建议并完成测试后，可根据实际需求进行其他场景的基准测试。但在执行之前，请确保收集的**性能基线测试结果**与参考数据基本一致，并仔细阅读下方提供的优化建议，根据实际测试需求对配置进行必要的调整。 + +### 性能基线测试部署拓扑 + +![ec2 deploy](https://static.apiseven.com/uploads/2024/06/25/2bp54aMM_20240625-092434.jpeg) + +### 性能基线测试结果 + +统计基线测试结果时，我们将 API7 Gateway（1 `worker_processes`）、NGINX 上游服务器和压测工具 wrk2 部署在同一台机器上，并使用本机网络进行通信。 + +| 测试案例 | 路由/消费者数量| **QPS** | **P99 (MS)** | **P95 (MS)** | +| :--------------------------------- | :-------------------------------- | :----------------------------- | :----------------------------- | :----------------------------- | +| 未启用任何插件 | 1 条路由，0 个消费者 | 24,129.22 | 0.093 | 0.082 | +| 未启用任何插件 | 100 条路由，0 个消费者 | 23,652.91 | 0.096 | 0.084 | +| 只启用 limit-count 限流限速插件 | 1 条路由，0 个消费者 | 20,495.10 | 0.104 | 0.092 | +| 只启用 limit-count 限流限速插件 | 100 条路由，0 个消费者 | 20,462.31 | 0.104 | 0.094 | +| 只启用 key-auth 身份认证插件 | 1 条路由，1 个消费者 | 21,019.04 | 0.100 | 0.089 | +| 只启用 key-auth 身份认证插件 | 100 条路由，100 个消费者 | 20,444.81 | 0.109 | 0.095 | +| 同时启用 key-auth 和 limit-count 插件 | 1 条路由，1 个消费者 | 18,940.39 | 0.110 | 0.097 | +| 同时启用 key-auth 和 limit-count 插件 | 100 条路由，100 个消费者 | 18,193.88 | 0.110 | 0.098 | + +遵循以上步骤和建议，你将能够更准确地评估 API7 Gateway 在不同场景下的性能表现，并为后续的优化和部署提供有力的数据支持。 + +## 优化 API7 Gateway 性能 + +### 检查最大打开文件数 + +检查当前系统总体最大打开文件数： + +```shell +cat /proc/sys/fs/file-nr +3984 0 3255296 +``` + +最后一个数字 `3255296` 是打开文件的最大数量。如果这个数字在你的机器上很小，你需要修改 `/etc/sysctl.conf` 文件以增加它。 + +```shell +fs.file-max = 1020000 +net.ipv4.ip_conntrack_max = 1020000 +net.ipv4.netfilter.ip_conntrack_max = 1020000 + +# 重启后生效 +sudo sysctl -p /etc/sysctl.conf +``` + +### 检查 `ulimit` + +每个用户请求对应一个文件句柄，而在压力测试时会产生大量请求，因此我们需要增大这个值。使用 `ulimit -n` 检查，如果是一个很小的值（默认为 1024），我们需要修改它增加为百万级，如：1024000。 + +临时修改： + +```shell +ulimit -n 1024000 +``` + +Linux 永久修改： + +```shell +vim /etc/security/limits.conf + +# 添加如下行 +* hard nofile 1024000 +* soft nofile 1024000 +``` + +### 避免资源争夺 + +确保 wrk2、API7 Gateway、上游服务分别位于不同的机器上，并在同一本地网络上进行测试，降低网络延迟带来的开销。 + +如果这些资源都在 Kubernetes 集群中运行，请确保这三个系统的 Pod 调度在各自的节点上。避免它们之间产生资源争用（通常是 CPU 和网络）导致性能不佳。 + +### 上游服务器已达到极限 + +检查上游服务器是否达到极限，压测过程注意观测上游服务器的 CPU 和内存的使用情况来确定上游服务器是否已经达到了极限。如果增加 API7 Gateway 的 `worker_processes` 数之后的结果仍保持不变，那么上游服务器或者其他系统可能达到了瓶颈。 + +### 阻止访问日志 `I/O` + +在进行性能测试时，我们应该尽量减少访问日志对性能的影响，尤其是高流量场景下的大量日志写入操作，我们可以禁用 `access_log` 减轻对磁盘 `I/O` 的压力。 + +### 云供应商的性能问题 + +避免使用云服务器提供的**可突发实例**，这种实例的可用 CPU 是可变的，这会对测试数据带来不必要的影响。 + +:::info +不同云供应商提供的实例类型中，vCPU（虚拟CPU）和物理 CPU 之间的对应关系并不总是 1:1 的。部分实例的 vCPU 是超线程的，这意味着实际的物理 CPU 核心数可能仅为 vCPU 数量的一半。为了准确了解特定实例类型的 vCPU 与物理 CPU 对应关系，建议查阅云供应商官方公布的文档。如 [AWS 实例信息](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/cpu-options-supported-instances-values.html)。 +::: + +### API7 Gateway 中的内部错误 + +将 API7 Gateway 错误日志调整成 `error` 级别，确保错误日志中不存在内部错误后再开始进行性能测试。 + +### 使用 c1000k 检查并发连接 + +安装 [c1000k](https://github.com/ideawu/c1000k) 检查测试环境是否能够满足 100w 个并发连接的要求。 + +``` +# 启动服务器，监听 7000 +. /server 7000 + +# 运行客户端，模拟压力测试 +. /client 127.0.0.1 7000 +``` + +## API7 Gateway 配置示例 + +```yaml +# config.yaml +nginx_config: + error_log_level: error + worker_processes: auto + + http: + enable_access_log: false +``` + + diff --git a/enterprise_versioned_docs/version-3.6.x/performance/performance-testing.md b/enterprise_versioned_docs/version-3.6.x/performance/performance-testing.md new file mode 100644 index 00000000..9b47d31c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/performance/performance-testing.md @@ -0,0 +1,72 @@ +--- +title: 性能测试报告 +slug: /performance/performance-testing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +除了参考我们的性能测试报告外，你也可以访问我们公开的[性能测试仓库](https://github.com/api7/api7-gateway-performance-benchmark)。该仓库详细记录了所有用于测试的资源部署配置以及各个测试场景的具体配置信息。通过此仓库，你可以根据提供的指南对你自行部署的 API7 Gateway 进行性能测试。在开始测试之前，请确保你所测试的**[性能基线](./benchmark#性能基线测试结果)**与我们的测试结果保持大致一致。 + +接下来，我们将详细阐述我们的测试场景、测试方法、测试结果以及相关配置的具体细节。 + +## 测试方法 + +- **环境**：AWS 基础设施上的 Kubernetes 环境。 +- **测试场景**： + 1. 只启用 [mocking](https://apisix.apache.org/docs/apisix/3.2/plugins/mocking/) 插件获取 API7 Gateway 的性能测试结果，该插件将按照指定的格式返回模拟数据，并且**请求不会被转发**到上游服务器； + 2. 未启用任何插件； + 3. 只启用 [limit-count](https://docs.api7.ai/hub/limit-count) 限流限速插件； + 4. 只启用 [key-auth](https://docs.api7.ai/hub/key-auth) 身份认证插件； + 5. 同时启用 key-auth 和 limit-count 插件； +- **路由和消费者**： + 1. 单条路由和单个消费者； + 2. 100 条路由和 100 个消费者； +- **测试数据收集方式**：每个测试用例运行 5 次，每次持续 2 分钟。统计的结果为 5 次测试结果的平均值。 + +## 性能测试结果 + + + + +| 测试案例 | 路由/消费者数量 | 转发到上游| **QPS** | **P99 (MS)** | **P95 (MS)** | +| :--------------------------------- | :-------------------------------- | :----------------------------- | :----------------------------- | :----------------------------- | :----------------------------- | +| 只启用 mocking 插件 | 1 条路由，0 个消费者 | 否 | 310,392.07 | 1.16 | 1.08 | +| 未启用任何插件 | 1 条路由，0 个消费者 | 是 | 167,019.37 | 2.30 | 2.16 | +| 未启用任何插件 | 100 条路由，0 个消费者 | 是| 162,753.17 | 2.31 | 2.16 | +| 只启用 limit-count 限流限速插件 | 1 条路由，0 个消费者 | 是| 145,370.10 | 2.43 | 2.24 | +| 只启用 limit-count 限流限速插件 | 100 条路由，0 个消费者 |是 | 143,108.40 | 2.45 | 2.25 | +| 只启用 key-auth 身份认证插件 | 1 条路由，1 个消费者 | 是| 147,869.49 | 2.41 | 2.22 | +| 只启用 key-auth 身份认证插件 | 100 条路由，100 个消费者 | 是| 145,070.93 | 2.43 | 2.25 | +| 同时启用 key-auth 和 limit-count 插件 | 1 条路由，1 个消费者 | 是| 136,725.47 | 2.43 | 2.26 | +| 同时启用 key-auth 和 limit-count 插件 | 100 条路由，100 个消费者 | 是| 133,782.95 | 2.48 | 2.30 | + + + + +## 测试环境 + +本测试报告通过 AWS EKS 环境来执行性能测试。在构建测试环境时，请确保 API7 Gateway、NGINX Upstream 及性能测试工具 [wrk2](https://github.com/giltene/wrk2) 分别部署于独立的节点上，且所有节点均应采用 `c5.4xlarge` 型号的 EC2 实例进行安装，以确保资源分配的合理性，避免资源竞争现象的发生。 + +在进行压力测试时，推荐使用 `top` 命令或其他系统监控工具来实时监测 API7 Gateway 和 NGINX Upstream 服务器的进程资源占用情况，确保每次测试均能达到 API7 Gateway 的性能瓶颈，从而获取准确且可靠的性能测试结果。以下是参与本次测试的主要服务及其相关详细信息的概述： + +| 对象 | 详细信息 | +| ------------ | ------------------------- | +| Node 配置 | Amazon Linux2(AL2_x86_64) | +| Kubernetes | 1.29 | +| API7 Gateway | 3.2.11.1 | +| 上游服务 | nginx/1.25.4 | +| 压测工具 | wrk2 | + +## 部署拓扑 + +![k8s deploy](https://static.apiseven.com/uploads/2024/05/21/Z6eY5wZk_image-1.png) + +## 测试配置 + +对于本次测试，我们调整了工作进程的数量，使其与运行 API7 Gateway 的节点上的可用核心数量（即 16 个 **vCPU**）相匹配。除此之外，我们并未对系统配置进行其他调整。 + +## 更多信息 + +- [建立性能测试报告](./benchmark.md)：查看如何优化 API7 Gateway 性能。 +- [在 AWS EKS 对 API7 Gateway 进行性能测试指南](./aws-eks.md)：查看如何在 AWS EKS 上建立性能测试报告的详细步骤和指南。 diff --git a/enterprise_versioned_docs/version-3.6.x/reference/adc.md b/enterprise_versioned_docs/version-3.6.x/reference/adc.md new file mode 100644 index 00000000..65aef990 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/adc.md @@ -0,0 +1,197 @@ +--- +title: APISIX Declarative CLI (ADC) +slug: /reference/adc +--- + +APISIX Declarative CLI (ADC) 是一个命令行工具，用于声明式地管理 APISIX 和 API7 企业版。它提供了简单明了的方式来定义网关的期望状态，让开发人员和管理员专注于结果而非步骤。 + +声明式配置作为单一事实来源，开发人员可以通过他们现有的版本控制系统进行管理。 + +ADC 具有以下通用语法： + + +```shell +adc [command] [options] +``` + +以及全局选项： + +* `-V, --version` to check the version +* `-h, --help` to print the help menu of the command + +## 配置 ADC + +在使用 ADC 管理网关之前，需要先进行配置。你可以使用环境变量或命令行参数来配置 ADC。 + +### 使用环境变量 + +ADC 将所有配置选项暴露为环境变量。例如，你可以分别使用 `ADC_BACKEND` 和 `ADC_SERVER` 环境变量来配置后端类型和地址。 + +```shell +export ADC_BACKEND=api7ee +export ADC_SERVER=https://localhost:7443 +``` + +更好的方式是在 `.env` 文件中配置这些选项： + +```text title=".env" +ADC_BACKEND=api7ee +ADC_SERVER=https://localhost:7443 +``` + +### 使用命令行参数 + +你也可以使用命令行参数来配置 ADC 或覆盖环境变量中的配置。例如，为 `ping` 命令配置/覆盖后端类型和地址： + +```shell +adc ping --backend api7ee --server "https://localhost:7443" +``` + +运行 `adc help [command]` 以查看命令的可用配置选项。 + +## 命令 + +### `adc ping` + +Ping 已配置的后端以验证连接性。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `--verbose ` | `1` | Overrides verbose logging levels.`0` represents no log, `1` represents basic logs, and `2` represents debug logs. | `0`, `1` or `2` | | +| `--backend ` | `apisix` | Backend type to connect. | `apisix` or `api7ee` | `ADC_BACKEND` | +| `--server ` | `http://localhost:9180` | Backend server address. | | `ADC_SERVER` | +| `--token ` | | API token to access the backend. | | `ADC_TOKEN` | +| `--gateway-group ` | `default` | Gateway group to operate on. | | `ADC_GATEWAY_GROUP` | +| `--label-selector ` | | Resource labels to filter for. | | | +| `--include-resource-type ` | | Filter for resource types, such that the resource search results should only contain the specified type. | | | +| `--exclude-resource-type ` | | Filter for resource types, such that the resource search results should exclude the specified type. | | | +| `--timeout ` | `10s` | Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m. | | | +| `--ca-cert-file ` | | Path to CA certificate for verifying the backend Admin API. | | `ADC_CA_CERT_FILE` | +| `--tls-client-cert-file ` | | Path to mutual TLS client certificate for verifying the backend Admin API. | | `ADC_TLS_CLIENT_CERT_FILE` | +| `--tls-client-key-file ` | | Path to mutual TLS client key for verifying the backend Admin API. | `ADC_TLS_CLIENT_KEY_FILE` | | +| `--tls-skip-verify` | `false` | Whether to verify the TLS certificate when connecting to the backend Admin API. | `ADC_TLS_SKIP_VERIFY` | | + +#### 使用示例 + +```shell +adc ping --backend api7ee --server https://localhost:7443 +``` + +### `adc lint` + +在本地验证提供的配置文件。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `-f, --file ` | | Files to lint. | | | + +#### 使用示例 + +```shell +adc lint -f service-a.yaml -f service-b.yaml +``` + +### `adc sync` + +将本地配置同步到连接的后端。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `--verbose ` | `1` | Overrides verbose logging levels.`0` represents no log, `1` represents basic logs, and `2` represents debug logs. | `0`, `1` or `2` | | +| `--backend ` | `apisix` | Backend type to connect. | `apisix` or `api7ee` | `ADC_BACKEND` | +| `--server ` | `http://localhost:9180` | Backend server address. | | `ADC_SERVER` | +| `--token ` | | API token to access the backend. | | `ADC_TOKEN` | +| `--gateway-group ` | `default` | Gateway group to operate on. | | `ADC_GATEWAY_GROUP` | +| `--label-selector ` | | Resource labels to filter for. | | | +| `-f, --file ` | | Configuration files to synchronize. | | | +| `--include-resource-type ` | | Filter for resource types, such that the resource search results should only contain the specified type. | | | +| `--exclude-resource-type ` | | Filter for resource types, such that the resource search results should exclude the specified type. | | | +| `--timeout ` | `10s` | Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m. | | | +| `--ca-cert-file ` | | Path to CA certificate for verifying the backend Admin API. | | `ADC_CA_CERT_FILE` | +| `--tls-client-cert-file ` | | Path to mutual TLS client certificate for verifying the backend Admin API. | | `ADC_TLS_CLIENT_CERT_FILE` | +| `--tls-client-key-file ` | | Path to mutual TLS client key for verifying the backend Admin API. | `ADC_TLS_CLIENT_KEY_FILE` | | +| `--tls-skip-verify` | `false` | Whether to verify the TLS certificate when connecting to the backend Admin API. | `ADC_TLS_SKIP_VERIFY` | | + +#### 使用示例 + +```shell +adc sync -f service-a.yaml -f service-b.yaml --backend api7ee --server https://localhost:7443 +``` + +### `adc dump` + +将后端配置保存到本地文件。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `--verbose ` | `1` | Overrides verbose logging levels.`0` represents no log, `1` represents basic logs, and `2` represents debug logs. | `0`, `1` or `2` | | +| `--backend ` | `apisix` | Backend type to connect. | `apisix` or `api7ee` | `ADC_BACKEND` | +| `--server ` | `http://localhost:9180` | Backend server address. | | `ADC_SERVER` | +| `--token ` | | API token to access the backend. | | `ADC_TOKEN` | +| `--gateway-group ` | `default` | Gateway group to operate on. | | `ADC_GATEWAY_GROUP` | +| `--label-selector ` | | Resource labels to filter for. | | | +| `-o, --output ` | | Specify the file path where the backend data should be dumped. | | | +| `--include-resource-type ` | | Filter for resource types, such that the resource search results should only contain the specified type. | | | +| `--exclude-resource-type ` | | Filter for resource types, such that the resource search results should exclude the specified type. | | | +| `--timeout ` | `10s` | Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m. | | | +| `--ca-cert-file ` | | Path to CA certificate for verifying the backend Admin API. | | `ADC_CA_CERT_FILE` | +| `--tls-client-cert-file ` | | Path to mutual TLS client certificate for verifying the backend Admin API. | | `ADC_TLS_CLIENT_CERT_FILE` | +| `--tls-client-key-file ` | | Path to mutual TLS client key for verifying the backend Admin API. | `ADC_TLS_CLIENT_KEY_FILE` | | +| `--tls-skip-verify` | `false` | Whether to verify the TLS certificate when connecting to the backend Admin API. | `ADC_TLS_SKIP_VERIFY` | | + +#### 使用示例 + +```shell +adc dump -o apisix-dump.yaml --backend api7ee --server https://localhost:7443 +``` + +### `adc diff` + +显示本地文件和后端配置之间的差异。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `--verbose ` | `1` | Overrides verbose logging levels.`0` represents no log, `1` represents basic logs, and `2` represents debug logs. | `0`, `1` or `2` | | +| `--backend ` | `apisix` | Backend type to connect. | `apisix` or `api7ee` | `ADC_BACKEND` | +| `--server ` | `http://localhost:9180` | Backend server address. | | `ADC_SERVER` | +| `--token ` | | API token to access the backend. | | `ADC_TOKEN` | +| `--gateway-group ` | `default` | Gateway group to operate on. | | `ADC_GATEWAY_GROUP` | +| `--label-selector ` | | Resource labels to filter for. | | | +| `-f, --file ` | | Configuration files to compare. | | | +| `--include-resource-type ` | | Filter for resource types, such that the resource search results should only contain the specified type. | | | +| `--exclude-resource-type ` | | Filter for resource types, such that the resource search results should exclude the specified type. | | | +| `--timeout ` | `10s` | Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m. | | | +| `--ca-cert-file ` | | Path to CA certificate for verifying the backend Admin API. | | `ADC_CA_CERT_FILE` | +| `--tls-client-cert-file ` | | Path to mutual TLS client certificate for verifying the backend Admin API. | | `ADC_TLS_CLIENT_CERT_FILE` | +| `--tls-client-key-file ` | | Path to mutual TLS client key for verifying the backend Admin API. | `ADC_TLS_CLIENT_KEY_FILE` | | +| `--tls-skip-verify` | `false` | Whether to verify the TLS certificate when connecting to the backend Admin API. | `ADC_TLS_SKIP_VERIFY` | | + +#### 使用示例 + +```shell +adc diff -f service-a.yaml -f service-b.yaml --backend api7ee --server https://localhost:7443 +``` + +### `adc convert` + +将 API 规范转换为 ADC 配置。 + +| Option | Default Value | Description | Valid Values | Env Variable | +|--------------------------------------|-------------------------|------------------------------------------------------------------|----------------------|-------------------| +| `openapi` | | Convert an OpenAPI specification to ADC configuration. | | | + +#### 使用示例 + +```shell +adc convert openapi -f open-api-spec.yaml -o adc.yaml +``` + +### `adc help` + +打印通用帮助菜单或指定命令的帮助菜单。 + +#### 使用示例 + +```shell +adc help [command] +``` diff --git a/enterprise_versioned_docs/version-3.6.x/reference/alert-template.md b/enterprise_versioned_docs/version-3.6.x/reference/alert-template.md new file mode 100644 index 00000000..fa872ca2 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/alert-template.md @@ -0,0 +1,70 @@ +--- +title: 告警变量和模板 +slug: /reference/alert-template +--- + +告警策略通知（电子邮件和消息）可以使用预定义变量进行自定义，以提供动态内容。 + +## 告警变量 + +告警变量是模板中的数据评估，用 `{{` 和 `}}` 分隔。 + +以下变量可用于创建告警通知（告警消息、告警电子邮件主题、告警电子邮件内容） + +| **变量** | **描述** | +|----------------------------------|----------------------------------| +| `{{ .AlertPolicyName }}` | 告警策略的名称。 | +| `{{ .Description }}` | 告警策略的描述。 | +| `{{ .Severity }}` | 告警策略的严重性。 | +| `{{ .TriggerGatewayGroup }}` | 触发告警的网关组的名称。可以指定多个组，用逗号分隔。 | +| `{{ .AlertTime }}` | 告警时间。 | +| `{{ .AlertDetial }}` | 触发告警的特定事件的详细描述。多个事件将单独列出。| + +* AlertTime 可以自定义 [时间格式](https://go.dev/src/time/format.go)： + +```text +{{ .AlertTime.Format }} +``` + +* AlertDetail 是一个整体字符串，多个事件详情将用 `\n` 分隔。因此，如果要在 JSON 正文中引用 AlertDetail，请添加 `escape` 函数： + +```text +{{ .AlertDetail | escape }} +``` + +## 模板 + +配置告警通知的示例。 + +### 告警电子邮件主题 + +```text +`[API7 告警] {{{ .TriggerGatewayGruop}}} 中没有足够的健康网关实例 - [{{.Severity }}]`。 +``` + +### 告警电子邮件内容 + +```text +亲爱的 [收件人姓名]， + +我们写信通知你，API7 网关在 {{ .AlertTime.Format "2024 Dec 31 17:00:00" }} 触发了告警。具体的告警严重程度为 {{ .Severity }}。 + +告警详情： + +网关组：{{ .TriggerGatewayGroup }} +告警消息：{{ .AlertDetail }} +``` + +建议操作： + +进一步调查：请查看相关日志和指标以获取更多详细信息。 +重新启动服务：考虑重新启动服务。 +上报值班团队：如果问题仍然存在，请联系值班团队。 + +### 告警消息（JSON） + +```json +"text": "{{{ .AlertDetail \| escape }}}"。 +"timestamp": "{{{ .AlerTime.Format "2024 Dec 31 17:00:00" }}}" +"system": "API7 网关，{{ .TriggerGatewayGroup }}" +``` diff --git a/enterprise_versioned_docs/version-3.6.x/reference/build-api-endpoints.md b/enterprise_versioned_docs/version-3.6.x/reference/build-api-endpoints.md new file mode 100644 index 00000000..1d86a509 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/build-api-endpoints.md @@ -0,0 +1,43 @@ +--- +title: 构建 API 端点 +slug: "/reference/build-api-endpoints" +--- + +API 端点为 API 提供实际的业务逻辑和数据。在与 API7 企业版集成之前，需要对其进行开发和部署。 + +## 开发 API 端点 + +1. **日程安排**：日程安排是 API 开发过程的关键环节。团队中的人员需要根据预定的时间表完成并报告他们的工作，以确保项目的及时交付。 +2. **开发和自测**：开发阶段通常涉及编码和调试，而自测阶段涉及开发人员测试和验证自己开发的 API，以确保其功能符合预期。 +3. **集成测试**：集成测试是对不同模块之间的 API 进行调试和测试的阶段，以确保它们之间的交互和通信正确、稳定。 +4. **质量保证测试**：质量保证测试的目的是在向最终用户发布 API 之前，找出并消除其中的缺陷或漏洞。这一阶段对于确保 API的可靠性和安全性至关重要。 +5. **产品验收**：产品验收包括全面测试、评估和确认，以确定 API 是否符合预期目标和标准。这一阶段对于确保 API 可投入生产并满足用户需求至关重要。 +6. **部署**：API 通过所有必要的测试和评估后，即可部署到生产环境中。这样，用户就可以访问和使用 API。 + +## 部署 API 后端 + +可以通过不同方式部署 API 后端： + +- **虚拟机**：直接在虚拟机上部署服务二进制文件/软件包。 +- **容器**：将服务打包为 Docker 容器并部署在 Kubernetes Controller 上。 +- **无服务器**：在 AWS Lambda 等平台上开发和部署相关功能。 +- **内部部署**：在现有的内部部署基础设施上托管服务。 + +在选择部署选项时要考虑可扩展性、可用性和可移植性等因素。 + +## 定义端点 + +部署完成后，后端必须配置 API7 企业版可以路由请求的网络端点。 + +- **虚拟机**：在虚拟机防火墙上为服务端点分配公共 IP 地址并开放端口。 +- **容器**：使用 Kubernetes Ingress 或 LoadBalancer 服务公开端点。 +- **无服务器**：大多数无服务器平台会自动为函数分配调用 URL。 +- **内部部署**：为内部部署服务定义带端口的 URL 或 IP 地址，并允许列出 API7 企业版的 IP 地址。 + +## 使用服务发现（可选） + +服务发现机制（如 Consul、Eureka、Nacos 或 Kubernetes 服务发现）可用于动态检测后端节点。 + +## 实施健康检查（强烈推荐） + +为后端服务配置健康检查端点，以便 API7 企业版检测可用性并相应地路由流量。 \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/reference/configuration-adc.md b/enterprise_versioned_docs/version-3.6.x/reference/configuration-adc.md new file mode 100644 index 00000000..f2ffbd69 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/configuration-adc.md @@ -0,0 +1,99 @@ +--- +title: ADC 配置参考 +slug: /reference/configuration-adc +--- + +ADC 使用单个配置文件或多个配置文件来定义 API7 企业版中的服务、路由、插件和其他配置。配置文件可以是 YAML 或 JSON 格式，并作为单一事实来源。 + +本文档提供了一个示例配置文件，可用作创建你自己的配置文件的参考。有关将配置文件与 ADC 一起使用的更多信息，请参阅[命令参考](./adc.md)。 + +## 示例配置文件 + +以下配置文件定义了两个具有多个路由和标签的服务、两个具有密钥认证凭据的消费者以及一个配置 Prometheus 插件的全局规则： + +```yaml title="adc.yaml" +services: + - name: mockbin Service + labels: + deployment: staging + upstream: + name: Default Upstream + scheme: http + type: roundrobin + hash_on: vars + nodes: + - host: mock.api7.ai + port: 80 + weight: 100 + priority: 0 + timeout: + connect: 60 + send: 60 + read: 60 + retry_timeout: 0 + keepalive_pool: + size: 320 + idle_timeout: 60 + requests: 1000 + pass_host: pass + strip_path_prefix: true + routes: + - uris: + - /api + name: api + methods: + - GET + enable_websocket: false + priority: 0 + - name: httpbin Service + labels: + deployment: production + upstream: + name: Default Upstream + scheme: http + nodes: + - host: httpbin.org + port: 80 + routes: + - uris: + - /ip + name: ip + labels: + app: catalog + methods: + - GET + - uris: + - /anything/* + name: anything + methods: + - GET +consumers: + - username: Jane + labels: + organisation: ACME + credentials: + - name: primary-key + labels: + type: internal + type: key-auth + config: + key: c1_yN0nCWousUfiR4EzfH + metadata: + id: 9ae2df2b-e578-46d9-8357-cf7c3cd64d51 + - username: John + labels: + organisation: API7.ai + credentials: + - name: primary-key + type: key-auth + config: + key: EIul6mAuYkLJ27on1aJD4 + metadata: + id: c5e8c41e-37c5-4329-87a9-ba2e6916cfe3 +global_rules: + prometheus: + _meta: + disable: false + prefer_name: false +``` +``` \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/reference/configuration.md b/enterprise_versioned_docs/version-3.6.x/reference/configuration.md new file mode 100644 index 00000000..8da12cbc --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/configuration.md @@ -0,0 +1,597 @@ +--- +title: 配置文件 +slug: /reference/configuration +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +API7 企业版在 `/conf` 下有以下配置文件： + +* `config-default.yaml` +* `config.yaml` + +本文档提供了配置文件如何使用以及如何按环境管理配置文件的参考。 + +## 概述 + +API7 企业版附带一个名为 `config-default.yaml` 的默认配置文件和一个名为 `config.yaml` 的用户自定义配置文件。 + +默认情况下会使用 `config-default.conf` 中的配置，并且**不应修改**。它包含默认配置和文档注释。 + +自定义配置应添加到 `config.yaml` 中，它优先于 `config-default.yaml` 中的配置。 + +API7 网关（数据面）在启动时加载这些配置文件一次。如果对这些文件进行了更改，请重新加载 API7 网关以使更改生效： + + + + + +```shell + +docker exec {container_name} apisix reload + +``` + + + + + +```shell + +kubectl edit configmap $YOUR_GATEWAY_CONFIGMAP +kubectl rollout restart deployment $YOUR_GATEWAY_DEPLOYMENT + +``` + + + + +## `config-default.yaml` + +```yaml + +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# PLEASE DO NOT UPDATE THIS FILE! +# If you want to set the specified configuration value, you can set the new +# value in the conf/config.yaml file. +## +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# PLEASE DO NOT UPDATE THIS FILE! +# If you want to set the specified configuration value, you can set the new +# value in the conf/config.yaml file. +# + +apisix: + # node_listen: 9080 # API7 GATEWAY listening port + node_listen: # This style support multiple ports + - 9080 + # - port: 9081 + # enable_http2: true # If not set, the default value is `false`. + # - ip: 127.0.0.2 # Specific IP, If not set, the default value is `0.0.0.0`. + # port: 9082 + # enable_http2: true + enable_admin: true + enable_dev_mode: false # Sets nginx worker_processes to 1 if set to true + enable_reuseport: true # Enable nginx SO_REUSEPORT switch if set to true. + show_upstream_status_in_response_header: false # when true all upstream status write to `X-APISIX-Upstream-Status` otherwise only 5xx code + enable_ipv6: true + + #proxy_protocol: # Proxy Protocol configuration + # listen_http_port: 9181 # The port with proxy protocol for http, it differs from node_listen and admin_listen. + # This port can only receive http request with proxy protocol, but node_listen & admin_listen + # can only receive http request. If you enable proxy protocol, you must use this port to + # receive http request with proxy protocol + # listen_https_port: 9182 # The port with proxy protocol for https + # enable_tcp_pp: true # Enable the proxy protocol for tcp proxy, it works for stream_proxy.tcp option + # enable_tcp_pp_to_upstream: true # Enables the proxy protocol to the upstream server + enable_server_tokens: true # Whether the version number should be shown in Server header. + # It's enabled by default. + + # configurations to load third party code and/or override the builtin one. + extra_lua_path: "" # extend lua_package_path to load third party code + extra_lua_cpath: "" # extend lua_package_cpath to load third party code + lua_module_hook: "agent.hook" # the hook module which will be used to inject third party code into API7 GATEWAY + + proxy_cache: # Proxy Caching configuration + cache_ttl: 10s # The default caching time in disk if the upstream does not specify the cache time + zones: # The parameters of a cache + - name: disk_cache_one # The name of the cache, administrator can specify + # which cache to use by name in the admin api (disk|memory) + memory_size: 50m # The size of shared memory, it's used to store the cache index for + # disk strategy, store cache content for memory strategy (disk|memory) + disk_size: 1G # The size of disk, it's used to store the cache data (disk) + disk_path: /tmp/disk_cache_one # The path to store the cache data (disk) + cache_levels: 1:2 # The hierarchy levels of a cache (disk) + #- name: disk_cache_two + # memory_size: 50m + # disk_size: 1G + # disk_path: "/tmp/disk_cache_two" + # cache_levels: "1:2" + - name: memory_cache + memory_size: 50m + + delete_uri_tail_slash: false # delete the '/' at the end of the URI + # The URI normalization in servlet is a little different from the RFC's. + # See https://github.com/jakartaee/servlet/blob/master/spec/src/main/asciidoc/servlet-spec-body.adoc#352-uri-path-canonicalization, + # which is used under Tomcat. + # Turn this option on if you want to be compatible with servlet when matching URI path. + normalize_uri_like_servlet: false + router: + http: radixtree_uri # radixtree_uri: match route by uri(base on radixtree) + # radixtree_host_uri: match route by host + uri(base on radixtree) + # radixtree_uri_with_parameter: like radixtree_uri but match uri with parameters, + # see https://github.com/api7/lua-resty-radixtree/#parameters-in-path for + # more details. + ssl: radixtree_sni # radixtree_sni: match route by SNI(base on radixtree) + #stream_proxy: # TCP/UDP proxy + # only: true # use stream proxy only, don't enable HTTP stuff + # tcp: # TCP proxy port list + # - addr: 9100 + # tls: true + # - addr: "127.0.0.1:9101" + # udp: # UDP proxy port list + # - 9200 + # - "127.0.0.1:9201" + #dns_resolver: # If not set, read from `/etc/resolv.conf` + # - 1.1.1.1 + # - 8.8.8.8 + #dns_resolver_valid: 30 # if given, override the TTL of the valid records. The unit is second. + resolver_timeout: 5 # resolver timeout + enable_resolv_search_opt: true # enable search option in resolv.conf + ssl: + enable: true + listen: # API7 GATEWAY listening port in https. + - port: 9443 + enable_http2: true + # - ip: 127.0.0.3 # Specific IP, If not set, the default value is `0.0.0.0`. + # port: 9445 + # enable_http2: true + #ssl_trusted_certificate: /path/to/ca-cert # Specifies a file path with trusted CA certificates in the PEM format + # used to verify the certificate when API7 GATEWAY needs to do SSL/TLS handshaking + # with external services (e.g. etcd) + ssl_protocols: TLSv1.2 TLSv1.3 + ssl_ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 + ssl_session_tickets: false # disable ssl_session_tickets by default for 'ssl_session_tickets' would make Perfect Forward Secrecy useless. + # ref: https://github.com/mozilla/server-side-tls/issues/135 + + key_encrypt_salt: # If not set, will save origin ssl key into etcd. + - edd1c9f0985e76a2 # If set this, the key_encrypt_salt should be an array whose elements are string, and the size is also 16, and it will encrypt ssl key with AES-128-CBC + # !!! So do not change it after saving your ssl, it can't decrypt the ssl keys have be saved if you change !! + # Only use the first key to encrypt, and decrypt in the order of the array. + + #fallback_sni: "my.default.domain" # If set this, when the client doesn't send SNI during handshake, the fallback SNI will be used instead + enable_control: true + #control: + # ip: 127.0.0.1 + # port: 9090 + disable_sync_configuration_during_start: false # safe exit. Remove this once the feature is stable + data_encryption: # add `encrypt_fields = { $field },` in plugin schema to enable encryption + enable: false # if not set, the default value is `false`. + keyring: + - qeddd145sfvddff3 # If not set, will save origin value into etcd. + # If set this, the keyring should be an array whose elements are string, and the size is also 16, and it will encrypt fields with AES-128-CBC + # !!! So do not change it after encryption, it can't decrypt the fields have be saved if you change !! + # Only use the first key to encrypt, and decrypt in the order of the array. + +nginx_config: # config for render the template to generate nginx.conf + #user: root # specifies the execution user of the worker process. + # the "user" directive makes sense only if the master process runs with super-user privileges. + # if you're not root user,the default is current user. + error_log: logs/error.log + error_log_level: warn # warn,error + worker_processes: auto # if you want use multiple cores in container, you can inject the number of cpu as environment variable "APISIX_WORKER_PROCESSES" + enable_cpu_affinity: false # disable CPU affinity by default, if API7 GATEWAY is deployed on a physical machine, it can be enabled and work well. + worker_rlimit_nofile: 20480 # the number of files a worker process can open, should be larger than worker_connections + worker_shutdown_timeout: 240s # timeout for a graceful shutdown of worker processes + + max_pending_timers: 16384 # increase it if you see "too many pending timers" error + max_running_timers: 4096 # increase it if you see "lua_max_running_timers are not enough" error + + event: + worker_connections: 10620 + #envs: # allow to get a list of environment variables + # - TEST_ENV + + meta: + lua_shared_dict: + prometheus-metrics: 15m + + stream: + enable_access_log: false # enable access log or not, default false + access_log: logs/access_stream.log + access_log_format: "$remote_addr [$time_local] $protocol $status $bytes_sent $bytes_received $session_time" + # create your custom log format by visiting http://nginx.org/en/docs/varindex.html + access_log_format_escape: default # allows setting json or default characters escaping in variables + lua_shared_dict: + etcd-cluster-health-check-stream: 10m + lrucache-lock-stream: 10m + plugin-limit-conn-stream: 10m + worker-events-stream: 10m + tars-stream: 1m + config-stream: 5m + + # As user can add arbitrary configurations in the snippet, + # it is user's responsibility to check the configurations + # don't conflict with API7 GATEWAY. + main_configuration_snippet: | + # Add custom Nginx main configuration to nginx.conf. + # The configuration should be well indented! + http_configuration_snippet: | + # Add custom Nginx http configuration to nginx.conf. + # The configuration should be well indented! + http_server_configuration_snippet: | + # Add custom Nginx http server configuration to nginx.conf. + # The configuration should be well indented! + http_server_location_configuration_snippet: | + # Add custom Nginx http server location configuration to nginx.conf. + # The configuration should be well indented! + http_admin_configuration_snippet: | + # Add custom Nginx admin server configuration to nginx.conf. + # The configuration should be well indented! + http_end_configuration_snippet: | + # Add custom Nginx http end configuration to nginx.conf. + # The configuration should be well indented! + stream_configuration_snippet: | + # Add custom Nginx stream configuration to nginx.conf. + # The configuration should be well indented! + + http: + enable_access_log: true # enable access log or not, default true + access_log: logs/access.log + access_log_format: "$remote_addr - $remote_user [$time_local] $http_host \"$request_line\" $status $body_bytes_sent $request_time \"$http_referer\" \"$http_user_agent\" $upstream_addr $upstream_status $upstream_response_time \"$upstream_scheme://$upstream_host$upstream_uri\"" + access_log_format_escape: default # allows setting json or default characters escaping in variables + keepalive_timeout: 60s # timeout during which a keep-alive client connection will stay open on the server side. + client_header_timeout: 60s # timeout for reading client request header, then 408 (Request Time-out) error is returned to the client + client_body_timeout: 60s # timeout for reading client request body, then 408 (Request Time-out) error is returned to the client + client_max_body_size: 0 # The maximum allowed size of the client request body. + # If exceeded, the 413 (Request Entity Too Large) error is returned to the client. + # Note that unlike Nginx, we don't limit the body size by default. + + send_timeout: 10s # timeout for transmitting a response to the client.then the connection is closed + underscores_in_headers: "on" # default enables the use of underscores in client request header fields + real_ip_header: X-Real-IP # http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header + real_ip_recursive: "off" # http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive + real_ip_from: # http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from + - 127.0.0.1 + - "unix:" + custom_lua_shared_dict: # add custom shared cache to nginx.conf + # ipc_shared_dict: 100m # custom shared cache, format: `cache-key: cache-size` + config: 5m + kubernetes: 20m + nacos: 20m + + # Enables or disables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) + # when establishing a connection with the proxied HTTPS server. + proxy_ssl_server_name: true + upstream: + keepalive: 320 # Sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. + # When this number is exceeded, the least recently used connections are closed. + keepalive_requests: 1000 # Sets the maximum number of requests that can be served through one keepalive connection. + # After the maximum number of requests is made, the connection is closed. + keepalive_timeout: 60s # Sets a timeout during which an idle keepalive connection to an upstream server will stay open. + charset: utf-8 # Adds the specified charset to the "Content-Type" response header field, see + # http://nginx.org/en/docs/http/ngx_http_charset_module.html#charset + variables_hash_max_size: 2048 # Sets the maximum size of the variables hash table. + + lua_shared_dict: + internal-status: 10m + plugin-limit-req: 10m + plugin-limit-count: 10m + plugin-limit-conn: 10m + plugin-graphql-limit-count: 10m + plugin-graphql-limit-count-reset-header: 10m + upstream-healthcheck: 10m + worker-events: 10m + lrucache-lock: 10m + balancer-ewma: 10m + balancer-ewma-locks: 10m + balancer-ewma-last-touched-at: 10m + plugin-limit-count-redis-cluster-slot-lock: 1m + tracing_buffer: 10m + plugin-api-breaker: 10m + etcd-cluster-health-check: 10m + discovery: 1m + jwks: 1m + introspection: 10m + access-tokens: 1m + ext-plugin: 1m + tars: 1m + cas-auth: 10m + saml_sessions: 10m + +graphql: + max_size: 1048576 # the maximum size limitation of graphql in bytes, default 1MiB + +#ext-plugin: + #cmd: ["ls", "-l"] + +plugins: # plugin list (sorted by priority) + - real-ip # priority: 23000 + # - toolset # priority: 22901 + - ai # priority: 22900 + - client-control # priority: 22000 + - proxy-buffering # priority: 21991 + - proxy-control # priority: 21990 + - request-id # priority: 12015 + - zipkin # priority: 12011 + #- skywalking # priority: 12010 + #- opentelemetry # priority: 12009 + - ext-plugin-pre-req # priority: 12000 + - fault-injection # priority: 11000 + - mocking # priority: 10900 + - serverless-pre-function # priority: 10000 + #- batch-requests # priority: 4010 + - cors # priority: 4000 + - ip-restriction # priority: 3000 + - ua-restriction # priority: 2999 + - referer-restriction # priority: 2990 + - csrf # priority: 2980 + - uri-blocker # priority: 2900 + - request-validation # priority: 2800 + - multi-auth # priority: 2600 + - openid-connect # priority: 2599 + - saml-auth # priority: 2598 + - cas-auth # priority: 2597 + - authz-casbin # priority: 2560 + - authz-casdoor # priority: 2559 + - wolf-rbac # priority: 2555 + - ldap-auth # priority: 2540 + - hmac-auth # priority: 2530 + - basic-auth # priority: 2520 + - jwt-auth # priority: 2510 + - key-auth # priority: 2500 + - acl # priority: 2410 + - consumer-restriction # priority: 2400 + - forward-auth # priority: 2002 + - opa # priority: 2001 + - authz-keycloak # priority: 2000 + - data-mask # priority: 1500 + #- error-log-logger # priority: 1091 + - body-transformer # priority: 1080 + - proxy-mirror # priority: 1010 + - proxy-cache # priority: 1009 + - graphql-proxy-cache # priority: 1009 + - proxy-rewrite # priority: 1008 + - workflow # priority: 1006 + - api-breaker # priority: 1005 + - graphql-limit-count # priority: 1004 + - limit-conn # priority: 1003 + - limit-count # priority: 1002 + - limit-req # priority: 1001 + #- node-status # priority: 1000 + - traffic-label # priority: 996 + - gzip # priority: 995 + - server-info # priority: 990 + - api7-traffic-split # priority: 966 + - traffic-split # priority: 966 + - redirect # priority: 900 + - response-rewrite # priority: 899 + - oas-validator # priority: 510 + - degraphql # priority: 509 + - kafka-proxy # priority: 508 + #- dubbo-proxy # priority: 507 + - grpc-transcode # priority: 506 + - grpc-web # priority: 505 + - public-api # priority: 501 + - prometheus # priority: 500 + - datadog # priority: 495 + - error-page # priority: 450 + - elasticsearch-logger # priority: 413 + - echo # priority: 412 + - loggly # priority: 411 + - http-logger # priority: 410 + - splunk-hec-logging # priority: 409 + - skywalking-logger # priority: 408 + - google-cloud-logging # priority: 407 + - sls-logger # priority: 406 + - tcp-logger # priority: 405 + - kafka-logger # priority: 403 + - rocketmq-logger # priority: 402 + - syslog # priority: 401 + - udp-logger # priority: 400 + - file-logger # priority: 399 + - clickhouse-logger # priority: 398 + - tencent-cloud-cls # priority: 397 + #- log-rotate # priority: 100 + # <- recommend to use priority (0, 100) for your custom plugins + - example-plugin # priority: 0 + #- gm # priority: -43 + - aws-lambda # priority: -1899 + - azure-functions # priority: -1900 + - openwhisk # priority: -1901 + - openfunction # priority: -1902 + - serverless-post-function # priority: -2000 + - ext-plugin-post-req # priority: -3000 + - ext-plugin-post-resp # priority: -4000 + +stream_plugins: # sorted by priority + - ip-restriction # priority: 3000 + - limit-conn # priority: 1003 + - mqtt-proxy # priority: 1000 + #- prometheus # priority: 500 + - syslog # priority: 401 + # <- recommend to use priority (0, 100) for your custom plugins + +#wasm: + #plugins: + #- name: wasm_log + #priority: 7999 + #file: t/wasm/log/main.go.wasm + +#xrpc: + #protocols: + #- name: pingpong + +plugin_attr: + log-rotate: + interval: 3600 # rotate interval (unit: second) + max_kept: 168 # max number of log files will be kept + max_size: -1 # max size bytes of log files to be rotated, size check would be skipped with a value less than 0 + enable_compression: false # enable log file compression(gzip) or not, default false + skywalking: + service_name: API7 GATEWAY + service_instance_name: API7 GATEWAY Instance Name + endpoint_addr: http://127.0.0.1:12800 + opentelemetry: + trace_id_source: x-request-id + resource: + service.name: API7 GATEWAY + collector: + address: 127.0.0.1:4318 + request_timeout: 3 + request_headers: + Authorization: token + batch_span_processor: + drop_on_queue_full: false + max_queue_size: 1024 + batch_timeout: 2 + inactive_timeout: 1 + max_export_batch_size: 16 + prometheus: + export_uri: /apisix/prometheus/metrics + metric_prefix: apisix_ + enable_export_server: true + export_addr: + ip: 127.0.0.1 + port: 9091 + #metrics: + # http_status: + # # extra labels from nginx variables + # extra_labels: + # # the label name doesn't need to be the same as variable name + # # below labels are only examples, you could add any valid variables as you need + # - upstream_addr: $upstream_addr + # - upstream_status: $upstream_status + # http_latency: + # extra_labels: + # - upstream_addr: $upstream_addr + # bandwidth: + # extra_labels: + # - upstream_addr: $upstream_addr + server-info: + report_ttl: 60 # live time for server info in etcd (unit: second) + dubbo-proxy: + upstream_multiplex_count: 32 + request-id: + snowflake: + enable: false + snowflake_epoc: 1609459200000 # the starting timestamp is expressed in milliseconds + data_machine_bits: 12 # data machine bit, maximum 31, because Lua cannot do bit operations greater than 31 + sequence_bits: 10 # each machine generates a maximum of (1 << sequence_bits) serial numbers per millisecond + data_machine_ttl: 30 # live time for data_machine in etcd (unit: second) + data_machine_interval: 10 # lease renewal interval in etcd (unit: second) + proxy-mirror: + timeout: # proxy timeout in mirrored sub-request + connect: 60s + read: 60s + send: 60s +# redirect: +# https_port: 8443 # the default port for use by HTTP redirects to HTTPS + inspect: + delay: 3 # in seconds + hooks_file: "/usr/local/apisix/plugin_inspect_hooks.lua" + +deployment: + role: traditional + role_traditional: + config_provider: etcd + admin: + # Default token when use API to call for Admin API. + # *NOTE*: Highly recommended to modify this value to protect API7 GATEWAY's Admin API. + # Disabling this configuration item means that the Admin API does not + # require any authentication. + admin_key: + - + name: admin + key: edd1c9f034335f136f87ad84b625c8f1 + role: admin # admin: manage all configuration data + # viewer: only can view configuration data + - + name: viewer + key: 4054f7cf07e344346cd3f287985e76a2 + role: viewer + + enable_admin_cors: true # Admin API support CORS response headers. + allow_admin: # http://nginx.org/en/docs/http/ngx_http_access_module.html#allow + - 127.0.0.0/24 # If we don't set any IP list, then any IP access is allowed by default. + #- "::/64" + admin_listen: # use a separate port + ip: 0.0.0.0 # Specific IP, if not set, the default value is `0.0.0.0`. + port: 9180 # Specific port, which must be different from node_listen's port. + + #https_admin: true # enable HTTPS when use a separate port for Admin API. + # Admin API will use conf/apisix_admin_api.crt and conf/apisix_admin_api.key as certificate. + + admin_api_mtls: # Depends on `admin_listen` and `https_admin`. + admin_ssl_cert: "" # Path of your self-signed server side cert. + admin_ssl_cert_key: "" # Path of your self-signed server side key. + admin_ssl_ca_cert: "" # Path of your self-signed ca cert.The CA is used to sign all admin api callers' certificates. + + admin_api_version: v3 # The version of admin api, latest version is v3. + + etcd: + host: # it's possible to define multiple etcd hosts addresses of the same etcd cluster. + - "http://127.0.0.1:2379" # multiple etcd address, if your etcd cluster enables TLS, please use https scheme, + # e.g. https://127.0.0.1:2379. + prefix: /apisix # configuration prefix in etcd + timeout: 30 # The timeout when connect/read/write to etcd. + watch_timeout: 50 # The timeout when watch etcd + #resync_delay: 5 # when sync failed and a rest is needed, resync after the configured seconds plus 50% random jitter + #health_check_timeout: 10 # etcd retry the unhealthy nodes after the configured seconds + startup_retry: 2 # the number of retry to etcd during the startup, default to 2 + #user: root # root username for etcd + #password: 5tHkHhYkjr6cQY # root password for etcd + tls: + # To enable etcd client certificate you need to build APISIX-Base, see + # https://apisix.apache.org/docs/apisix/FAQ#how-do-i-build-the-apisix-base-environment + #cert: /path/to/cert # path of certificate used by the etcd client + #key: /path/to/key # path of key used by the etcd client + + verify: true # whether to verify the etcd endpoint certificate when setup a TLS connection to etcd, + # the default value is true, e.g. the certificate will be verified strictly. + #sni: # the SNI for etcd TLS requests. If missed, the host part of the URL will be used. + +api7ee: + telemetry: + enable: true # enable telemetry data report to the control plane + interval: 15 # interval in seconds to send telemetry data to the control plane + max_metrics_size: 33554432 # max size in bytes(32M) of the metrics data sent to the control plane, if the size exceeds, the data will be truncated + healthcheck_report_interval: 120 # healthcheck data report interval in seconds + +``` diff --git a/enterprise_versioned_docs/version-3.6.x/reference/design-apis.md b/enterprise_versioned_docs/version-3.6.x/reference/design-apis.md new file mode 100644 index 00000000..88221257 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/design-apis.md @@ -0,0 +1,33 @@ +--- +title: 设计 API +slug: "/reference/design-apis" +--- + +工程师总是强调在编码前设计计划的重要性。你需要根据业务需求明确 API 的功能目的，然后将业务语言转化为技术语言。通常，API 的设计围绕文档展开。 + +## 使用示例 + +在所有教程中，你将使用 [Swagger Petstore](https://petstore3.swagger.io/api/v3/openapi.json) 作为示例，指导你完成整个 API 生命周期的管理。 + +## 如何编写自己的 OpenAPI 规范 + +通过 JSON 或 YAML 格式的 OpenAPI 规范文件，可以定义遵循 API 设计最佳实践的 RESTful API。这可以确保可靠性、一致性和可扩展性。Swagger Editor 和 OpenAPI GUI 等开源工具可帮助创建、编辑和验证 OpenAPI 规范。许多集成开发环境和代码编辑器也有处理 OpenAPI 文件的插件。 + +你可以从示例中了解到 RESTful 架构风格的主要特点，包括： + +- 资源的唯一标识：每个资源都有一个唯一的标识符，如 URL。 +- 统一接口：使用标准化的 HTTP 方法和状态代码，如 GET、POST、PUT、DELETE 等。 +- 无状态：API 不应存储客户状态信息。每个请求都应包含处理所需的全部信息，从而提高横向可扩展性。 + +## 有用的工具 + +以下是一些有助于编写 OpenAPI（原 Swagger）规范文档的实用工具： + +- **Swagger Editor**：用于在线创建和测试 OpenAPI 规范的交互式编辑器。提供自动完成、实时验证和示例生成功能。 +- **Stoplight Studio**：可视化建模工具，用于设计 API 和生成带有模拟数据的 OpenAPI 规范。 +- **OpenAPI Generator**：根据 OpenAPI 规范自动生成客户端 SDK、服务器存根、文档等。支持多种语言。 +- **Postman**：提供 OpenAPI 导入器和导出器，用于在集合和规范之间进行转换。还可自动生成代码。 +- **OpenAPI CLI**：命令行工具，提供用于处理 OpenAPI 文件的完成、验证和其他实用程序。 +- **OpenAPI GUI**：适用于 Windows 和 Mac 的桌面应用程序，为编辑 OpenAPI 文件提供用户界面，支持 YAML 和 JSON。 +- **REST United**：OpenAPI 工具套件，包括模拟、文档、测试和代码生成。 +- **Apicurio**：基于 Web 的 OpenAPI 规范编辑器，具有实时验证和模拟功能。 \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/reference/hardening.md b/enterprise_versioned_docs/version-3.6.x/reference/hardening.md new file mode 100644 index 00000000..5186625f --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/hardening.md @@ -0,0 +1,59 @@ +--- +title: 安全加固参考 +slug: /reference/hardening +--- + +# 基础设施安全 + +基础设施安全是组织为了遵守最新的监管和法律要求而仔细审查的一个重要议题。了解敏感信息存储的位置和方式对于实施强有力的安全措施、防止未经授权的访问、数据泄露或恶意攻击至关重要。 + +![ee-component-diagram](https://static.apiseven.com/uploads/2024/04/11/5ZUDl6rt_ee-sec-0411.png) + +本文档提供了 API7 企业版中敏感信息存储位置、存储方式和保护方式的详细参考。 + +## 数据面 (DP) 和控制面 (CP) 之间 + +DP 和 CP 之间的通信可以通过令牌或 mTLS 来保护。 + +* 使用令牌时，令牌经过 PBKDF2 加密并保存到数据库中。 +* 使用 mTLS 时，CP 只存储服务器和 CA 证书。它不存储客户端证书。 + +## 控制面 (CP) + +### 数据库连接凭证 + +数据库连接凭证存储在控制面的配置文件中。它们也可以存储在环境变量中并注入到配置文件中。 + +### 插件资源 + +插件配置中的敏感[插件](../key-concepts/plugins.md)字段在插件模式中指定为 `encrypted_fields`。这些字段中的信息使用 AES256 加密并保存到数据库中。 + +用于加密敏感信息的密钥环因网关组而异，它们在保存到数据库之前也会被加密。 + +### SSL 资源 + +对于 [SSL 资源](../key-concepts/ssl-certificates.md)，元数据以明文保存，而证书则经过 AES 加密并保存到数据库中。 + +使用 API 或控制台查看 SSL 资源时，你只能看到元数据。 + +### 控制台和 DP 管理器连接 + +控制台和 DP 管理器之间的通信默认使用 HTTPS。如果未配置证书，API7 将使用自签名证书。 + +### 审计 + +敏感信息（例如密码）在审计日志保存到数据库之前会被屏蔽。禁止对审计日志进行任何其他修改。 + +### 用户凭证 + +用户凭证，包括用户名和密码以及访问令牌，在保存到数据库之前都会经过加盐和 PBKDF2 加密。 + +### 加密算法 + +在字段不应可逆的情况下，加密算法将是带有盐的 PBKDF2。 + +在字段应可逆的情况下，加密算法将是 AES。 + +## 数据面 (DP) + +在客户端和 API7 企业版之间，以及 API7 企业版和上游服务之间，你可以选择配置 TLS 或 mTLS 来保护通信。 diff --git a/enterprise_versioned_docs/version-3.6.x/reference/openapi-adc.md b/enterprise_versioned_docs/version-3.6.x/reference/openapi-adc.md new file mode 100644 index 00000000..40e252a9 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/openapi-adc.md @@ -0,0 +1,83 @@ +--- +title: OpenAPI 转换参考 +slug: /reference/openapi-adc +--- + +ADC 可以使用 `adc convert openapi` 命令将 OpenAPI v3.0 规范转换为 ADC 配置。本文档提供了支持的扩展/自定义属性的参考，用于配置 API7 企业版特定的功能，如路由、插件和标签。 + +在 API 规范的以下级别支持 ADC OpenAPI 扩展： + +- 根级别：API 规范的根级别。根级别的属性将应用于整个服务。 +- 路径级别：规范中的路径部分。路径级别的属性将应用于特定路由。 +- 操作级别：路径部分中的每个 HTTP 方法。操作级别的属性将应用于路由的特定 HTTP 方法。 +- 服务器级别：根级别、路径级别或操作级别中的服务器部分。服务器级别的属性将应用于上游。 + +## 支持的扩展 + +下表列出了支持的扩展及其级别： + +|扩展|级别|说明| +|:---|:---|:---| +|`x-adc-name`|根级别|设置服务名称。| +|`x-adc-name`|操作级别|设置特定路由名称。| +|`x-adc-labels`|根级别|将标签添加到服务、路由或方法，如级别指定的那样。值可以是字符串或字符串数组（用于多个标签）。| +|`x-adc-labels`|路径级别|将标签添加到服务、路由或方法，如级别指定的那样。值可以是字符串或字符串数组（用于多个标签）。| +|`x-adc-labels`|操作级别|将标签添加到服务、路由或方法，如级别指定的那样。值可以是字符串或字符串数组（用于多个标签）。| +|`x-adc-plugins`|根级别|将插件全局添加到服务。值是一个包含一个或多个插件的对象。| +|`x-adc-plugins`|路径级别|将插件添加到路由或方法，如级别指定的那样。在操作级别添加插件将拆分路由，一个包含插件，另一个不包含插件。| +|`x-adc-plugins`|操作级别|将插件添加到路由或方法，如级别指定的那样。在操作级别添加插件将拆分路由，一个包含插件，另一个不包含插件。| +|`x-adc-plugin-[plugin-name]`|根级别|类似于 `x-adc-plugins`，但适用于单个插件。这些插件将覆盖在 `x-adc-plugins` 中配置的同名插件。| +|`x-adc-plugin-[plugin-name]`|路径级别|类似于 `x-adc-plugins`，但适用于单个插件。这些插件将覆盖在 `x-adc-plugins` 中配置的同名插件。| +|`x-adc-plugin-[plugin-name]`|操作级别|类似于 `x-adc-plugins`，但适用于单个插件。这些插件将覆盖在 `x-adc-plugins` 中配置的同名插件。| +|`x-adc-service-defaults`|根级别|在服务、路由或方法上设置服务参数，如级别指定的那样。| +|`x-adc-service-defaults`|路径级别|在服务、路由或方法上设置服务参数，如级别指定的那样。| +|`x-adc-service-defaults`|操作级别|在服务、路由或方法上设置服务参数，如级别指定的那样。| +|`x-adc-upstream-defaults`|根级别|在服务、路由或方法上设置上游参数，如级别指定的那样。| +|`x-adc-upstream-defaults`|路径级别|在服务、路由或方法上设置上游参数，如级别指定的那样。| +|`x-adc-upstream-defaults`|操作级别|在服务、路由或方法上设置上游参数，如级别指定的那样。| +|`x-adc-upstream-node-defaults`|根级别 - 服务器|在服务、路由或方法上设置上游的节点参数，如级别指定的那样。| +|`x-adc-upstream-node-defaults`|路径级别 - 服务器|在服务、路由或方法上设置上游的节点参数，如级别指定的那样。| +|`x-adc-upstream-node-defaults`|操作级别 - 服务器|在服务、路由或方法上设置上游的节点参数，如级别指定的那样。| +|`x-adc-route-defaults`|根级别|在服务、路由或方法上设置路由参数，如级别指定的那样。| +|`x-adc-route-defaults`|路径级别|在服务、路由或方法上设置路由参数，如级别指定的那样。| +|`x-adc-route-defaults`|操作级别|在服务、路由或方法上设置路由参数，如级别指定的那样。| + +## 规范示例 + +以下规范示例显示了如何使用扩展： + +```yaml +openapi: 3.1.0 +info: + title: httpbin API + description: httpbin API for the API7 Enterprise Getting Started guides. + version: 1.0.0 +servers: + - url: 'http://httpbin.org:80' +x-adc-labels: + server: production + api: httpbin +x-adc-plugins: + key-auth: + _meta: + disable: false +paths: + /anything/*: + get: + summary: Returns anything that is passed into the request. + x-adc-name: httpbin-anything + x-adc-service-defaults: + path_prefix: /api/ + x-adc-upstream-defaults: + timeout: + connect: 10 + send: 10 + read: 10 + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string +``` \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-action-and-resource.md b/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-action-and-resource.md new file mode 100644 index 00000000..67b38d24 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-action-and-resource.md @@ -0,0 +1,245 @@ +--- +title: 权限策略 Actions 和 Resources +slug: /reference/permission-policy-action-and-resource +--- + +### 网关组 + +| Action | Resource | API | +| -------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:DeleteGatewayGroup | arn:api7:gateway:gatewaygroup/%s | [DELETE /api/gateway_groups/:gateway_group_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/deleteGatewayGroup) | +| gateway:GetGatewayGroup | arn:api7:gateway:gatewaygroup/%s | [GET /api/gateway_groups/:gateway_group_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/createGatewayGroup) | +| gateway:CreateGatewayGroup | arn:api7:gateway:gatewaygroup/\* | [POST /api/gateway_groups](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/createGatewayGroup) | +| gateway:UpdateGatewayGroup | arn:api7:gateway:gatewaygroup/%s | [PUT /api/gateway_groups/:gateway_group_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/updateGatewayGroup) | +| gateway:UpdateGatewayGroup | arn:api7:gateway:gatewaygroup/%s | [PUT /api/gateway_groups/:gateway_group_id/admin_key](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/GenerateAdminKey) | + +### 网关实例 + +| Action | Resource | API | +| ------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetGatewayInstance | arn:api7:gateway:gatewaygroup/%s | [GET /api/gateway_groups/:gateway_group_id/instances](https://docs.api7.ai/enterprise/reference/admin-api#tag/Instances/operation/listInstances) | +| gateway:GetGatewayInstanceCore | arn:api7:gateway:gatewaygroup/\* | GET /api/instances/cores | +| gateway:CreateGatewayInstance | arn:api7:gateway:gatewaygroup/%s | [POST /api/gateway_groups/:gateway_group_id/dp_client_certificates](https://docs.api7.ai/enterprise/reference/admin-api#tag/Data-Plane-Certificates) | +| gateway:CreateGatewayInstance | arn:api7:gateway:gatewaygroup/%s | [POST /api/gateway_groups/:gateway_group_id/instance_token](https://docs.api7.ai/enterprise/reference/admin-api#tag/Instances/operation/CreateGatewayInstanceToken) | + +### 消费者 + +| Action | Resource | API | +| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| gateway:GetConsumer | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/consumers](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers/get) | +| gateway:GetConsumer | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/consumers/:consumer_username](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers~1%7Busername%7D/get) | +| gateway:CreateConsumer | arn:api7:gateway:gatewaygroup/%s | [POST /apisix/admin/consumers](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers/post) | +| gateway:UpdateConsumer | arn:api7:gateway:gatewaygroup/%s | [PATCH /apisix/admin/consumers/:consumer_username](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers~1%7Busername%7D/patch) | +| gateway:UpdateConsumer | arn:api7:gateway:gatewaygroup/%s | [PUT /apisix/admin/consumers/:consumer_username](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers~1%7Busername%7D/put) | +| gateway:DeleteConsumer | arn:api7:gateway:gatewaygroup/%s | [DELETE /apisix/admin/consumers/:consumer_username](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers/paths/~1apisix~1admin~1consumers~1%7Busername%7D/delete) | + +### SSL 证书 + +| Action | Resource | API | +| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetCertificate | arn:api7:gateway:gatewaygroup/%s | [List all SSL certificates on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/listCertificates) , [Get a SSL certificate on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/getCertificate) | +| gateway:CreateCertificate | arn:api7:gateway:gatewaygroup/%s | [Create a SSL certificate on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/createCertificate) | +| gateway:UpdateCertificate | arn:api7:gateway:gatewaygroup/%s | [Update a SSL certificate on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/putCertificate) , [Patch a SSL certificate on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/patchCertificate) | +| gateway:DeleteCertificate | arn:api7:gateway:gatewaygroup/%s | [Delete a SSL certificate on a gateway group](/enterprise/reference/admin-api#tag/Certificate/operation/deleteCertificate) | + +### CA 证书 + +| Action | Resource | API | +| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetCertificate | arn:api7:gateway:gatewaygroup/%s | [List all CA certificates on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/listCACertificates) , [Get a CA certificate on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/getCACertificate) | +| gateway:CreateCertificate | arn:api7:gateway:gatewaygroup/%s | [Create a CA certificate on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/createCACertificate) | +| gateway:UpdateCertificate | arn:api7:gateway:gatewaygroup/%s | [Update a CA certificate on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/putCACertificate) , [Patch a CA certificate on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/patchCACertificate) | +| gateway:DeleteCertificate | arn:api7:gateway:gatewaygroup/%s | [Delete a CA certificate on a gateway group](/enterprise/reference/admin-api#tag/CACertificate/operation/deleteCACertificate) | + +### SNI + +| Action | Resource | API | +| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetSNI | arn:api7:gateway:gatewaygroup/%s | [List all SNIs on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/listSNI) , [Get a SNI on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/getCertificate) | +| gateway:CreateSNI | arn:api7:gateway:gatewaygroup/%s | [Create a SNI on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/createSNI) | +| gateway:UpdateSNI | arn:api7:gateway:gatewaygroup/%s | [Update a SNI on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/putSNI) , [Patch a SNI on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/patchSNI) | +| gateway:DeleteSNI | arn:api7:gateway:gatewaygroup/%s | [Delete a SNI on a gateway group](/enterprise/reference/admin-api#tag/SNI/operation/deleteSNI) | + +### 插件全局规则 + +| Action | Resource | API | +| ------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| gateway:GetGlobalPluginRule | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/global_rules](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules/get) | +| gateway:GetGlobalPluginRule | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/global_rules/:global_rule_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules~1%7Bglobal_rule_id%7D/get) | +| gateway:CreateGlobalPluginRule | arn:api7:gateway:gatewaygroup/%s | [POST /apisix/admin/global_rules](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules/post) | +| gateway:UpdateGlobalPluginRule | arn:api7:gateway:gatewaygroup/%s | [PUT /apisix/admin/global_rules/:global_rule_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules~1%7Bglobal_rule_id%7D/put) | +| gateway:DeleteGlobalPluginRule | arn:api7:gateway:gatewaygroup/%s | [DELETE /apisix/admin/global_rules/:global_rule_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules~1%7Bglobal_rule_id%7D/delete) | + +### 插件元数据 + +| Action | Resource | API | +| ---------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetPluginMetadata | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/plugin_metadata](https://docs.api7.ai/enterprise/reference/admin-api#tag/Global-Rules/paths/~1apisix~1admin~1global_rules~1%7Bglobal_rule_id%7D/delete) | +| gateway:GetPluginMetadata | arn:api7:gateway:gatewaygroup/%s | [GET /apisix/admin/plugin_metadata/:plugin_name](https://docs.api7.ai/enterprise/reference/admin-api#tag/Plugin-Metadata/paths/~1apisix~1admin~1plugin_metadata~1%7Bplugin_name%7D/delete) | +| gateway:UpdatePluginMetadata | arn:api7:gateway:gatewaygroup/%s | [PUT /apisix/admin/plugin_metadata/:plugin_name](https://docs.api7.ai/enterprise/reference/admin-api#tag/Plugin-Metadata/paths/~1apisix~1admin~1plugin_metadata~1%7Bplugin_name%7D/put) | +| gateway:DeletePluginMetadata | arn:api7:gateway:gatewaygroup/%s | [DELETE /apisix/admin/plugin_metadata/:plugin_name](https://docs.api7.ai/enterprise/reference/admin-api#tag/Plugin-Metadata/paths/~1apisix~1admin~1plugin_metadata~1%7Bplugin_name%7D/delete) | + +### 密钥 + +| Action | Resource | API | +| -------------------- | -------------------------------- | ------------------------------------------------------- | +| gateway:GetSecret | arn:api7:gateway:gatewaygroup/%s | GET /apisix/admin/secrets | +| gateway:GetSecret | arn:api7:gateway:gatewaygroup/%s | GET /apisix/admin/secrets/:secret_manager/:secret_id | +| gateway:PutSecret | arn:api7:gateway:gatewaygroup/%s | PUT /apisix/admin/secrets/:secret_manager/:secret_id | +| gateway:DeleteSecret | arn:api7:gateway:gatewaygroup/%s | DELETE /apisix/admin/secrets/:secret_manager/:secret_id | + +### 服务注册中心 + +| Action | Resource | API | +| --------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | [GET /api/gateway_groups/:gateway_group_id/service_registries](https://docs.api7.ai/enterprise/reference/admin-api#tag/Service-Registry/operation/listServiceRegistry) | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | [GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Service-Registry/operation/getServiceRegistry) | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/connected_services | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/health_check_history | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/kubernetes/internal_services | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/nacos/namespaces | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/nacos/namespaces/:nacos_namespace/groups | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/nacos/namespaces/:nacos_namespace/groups/:nacos_group/services | +| gateway:GetServiceRegistry | arn:api7:gateway:gatewaygroup/%s | GET /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id/nacos/namespaces/:nacos_namespace/groups/:nacos_group/services/:nacos_service/instances_metadata | +| gateway:ConnectServiceRegistry | arn:api7:gateway:gatewaygroup/%s | [POST /api/gateway_groups/:gateway_group_id/service_registries](https://docs.api7.ai/enterprise/reference/admin-api#tag/Service-Registry/operation/createServiceRegistry) | +| gateway:UpdateServiceRegistry | arn:api7:gateway:gatewaygroup/%s | [PUT /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Service-Registry/operation/updateServiceRegistry) | +| gateway:DisconnectServiceRegistry | arn:api7:gateway:gatewaygroup/%s | [DELETE /api/gateway_groups/:gateway_group_id/service_registries/:service_registry_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Service-Registry/operation/deleteServiceRegistry) | + +### 服务中心（模板） + +| Action | Resource | API | +| ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------ | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/routes/template/:route_id | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/service_versions/:service_version_id | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/service_versions/:service_version_id/routes | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/service_versions/:service_version_id/routes/:route_version_id | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/service_versions/:service_version_id/stream_routes | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/service_versions/:service_version_id/stream_routes/:stream_route_version_id | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/services/:service_id/versions/:version | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/services/template/:service_id | +| gateway:GetServiceTemplate | arn:api7:gateway:servicetemplate/%s | GET /api/stream_routes/template/:stream_route_id | +| gateway:CreateServiceTemplate | arn:api7:gateway:servicetemplate/\* | POST /api/import/services/template | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | PUT /api/services/template/:service_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | PATCH /api/services/template/:service_id | +| gateway:DeleteServiceTemplate | arn:api7:gateway:servicetemplate/%s | DELETE /api/services/template/:service_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | POST /api/routes/template | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | PATCH /api/routes/template/:route_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | PUT /api/routes/template/:route_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | DELETE /api/routes/template/:route_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | POST /api/stream_routes/template | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | PUT /api/stream_routes/template/:stream_route_id | +| gateway:UpdateServiceTemplate | arn:api7:gateway:servicetemplate/%s | DELETE /api/stream_routes/template/:stream_route_id | + +### 已发布服务 + +| Action | Resource | API | +| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /api/gateway_groups/:gateway_group_id/services/:service_version_service_id | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /api/gateway_groups/:gateway_group_id/services/:service_version_service_id/healthcheck | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /api/gateway_groups/:gateway_group_id/services/:service_version_service_id/runtime_configuration | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /api/gateway_groups/:gateway_group_id/services/:service_version_service_id/versions | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /apisix/admin/routes/:apisix_route_id | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /apisix/admin/services/:apisix_service_id | +| gateway:GetPublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | GET /apisix/admin/stream_routes/:apisix_stream_route_id | +| gateway:PublishServices | arn:api7:gateway:gatewaygroup/%s/publishedservice/\* | POST /api/services/publish | +| gateway:CreatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | POST /apisix/admin/services | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | PATCH /apisix/admin/services/:apisix_service_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | PUT /apisix/admin/services/:apisix_service_id | +| gateway:DeletePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | DELETE /apisix/admin/services/:apisix_service_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | PUT /apisix/admin/routes/:apisix_route_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | PATCH /apisix/admin/routes/:apisix_route_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | DELETE /apisix/admin/routes/:apisix_route_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | PUT /apisix/admin/stream_routes/:apisix_stream_route_id | +| gateway:UpdatePublishedService | arn:api7:gateway:gatewaygroup/%s/publishedservice/%s | DELETE /apisix/admin/stream_routes/:apisix_stream_route_id | + +### 部署设置 + +| Action | Resource | API | +| ------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| gateway:GetDeploymentSetting | arn:api7:gateway:gatewaysetting/\* | [GET /api/system_settings](https://docs.api7.ai/enterprise/reference/admin-api#tag/System-Settings/paths/~1api~1system_settings/get) | +| gateway:UpdateDeploymentSetting | arn:api7:gateway:gatewaysetting/\* | [PUT /api/system_settings](https://docs.api7.ai/enterprise/reference/admin-api#tag/System-Settings/operation/updateSystemSettings) | + +### 自定义插件 + +| Action | Resource | API | +| -------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetCustomPlugin | arn:api7:gateway:gatewaysetting/\* | [GET /api/custom_plugins](https://docs.api7.ai/enterprise/reference/admin-api#tag/Custom-Plugins/operation/ListCustomPlugins) | +| gateway:GetCustomPlugin | arn:api7:gateway:gatewaysetting/\* | [GET /api/custom_plugins/:custom_plugin_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Custom-Plugins/operation/GetCustomPlugin) | +| gateway:CreateCustomPlugin | arn:api7:gateway:gatewaysetting/\* | [POST /api/custom_plugins](https://docs.api7.ai/enterprise/reference/admin-api#tag/Custom-Plugins/operation/CreateCustomPlugin) | +| gateway:UpdateCustomPlugin | arn:api7:gateway:gatewaysetting/\* | [PUT /api/custom_plugins/:custom_plugin_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Custom-Plugins/operation/UpdateCustomPlugin) | +| gateway:DeleteCustomPlugin | arn:api7:gateway:gatewaysetting/\* | [DELETE /api/custom_plugins/:custom_plugin_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Custom-Plugins/operation/DeleteCustomPlugin) | + +### 告警 + +| Action | Resource | API | +| ----------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| gateway:GetAlertPolicy | arn:api7:gateway:alert/\* | [GET /api/alert/policies](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies/get) | +| gateway:GetAlertPolicy | arn:api7:gateway:alert/\* | [GET /api/alert/policies/:alert_policy_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies~1%7Balert_policy_id%7D/get) | +| gateway:GetAlertPolicy | arn:api7:gateway:alert/\* | [GET /api/alert/policies/histories](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy-History/paths/~1api~1alert~1policies~1histories/get) | +| gateway:CreateAlertPolicy | arn:api7:gateway:alert/\* | [POST /api/alert/policies](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies/post) | +| gateway:UpdateAlertPolicy | arn:api7:gateway:alert/\* | [PUT /api/alert/policies/:alert_policy_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies~1%7Balert_policy_id%7D/put) | +| gateway:UpdateAlertPolicy | arn:api7:gateway:alert/\* | PUT /api/alert/policies/:alert_policy_id/triggers | +| gateway:UpdateAlertPolicy | arn:api7:gateway:alert/\* | [PATCH /api/alert/policies/:alert_policy_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies~1%7Balert_policy_id%7D/patch) | +| gateway:DeleteAlertPolicy | arn:api7:gateway:alert/\* | [DELETE /api/alert/policies/:alert_policy_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Policy/paths/~1api~1alert~1policies~1%7Balert_policy_id%7D/delete) | +| gateway:GetWebhookTemplate | arn:api7:gateway:alert/\* | [GET /api/alert/webhook_templates/:webhook_template_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Webhook-Templates/paths/~1api~1alert~1webhook_templates~1%7Bwebhook_template_id%7D/get) | +| gateway:GetWebhookTemplate | arn:api7:gateway:alert/\* | [GET /api/alert/webhook_templates/:webhook_template_id/refer](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Webhook-Templates/paths/~1api~1alert~1webhook_templates~1%7Bwebhook_template_id%7D~1refer/get) | +| gateway:CreateWebhookTemplate | arn:api7:gateway:alert/\* | [POST /api/alert/webhook_templates](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Webhook-Templates/paths/~1api~1alert~1webhook_templates/post) | +| gateway:UpdateWebhookTemplate | arn:api7:gateway:alert/\* | [PUT /api/alert/webhook_templates/:webhook_template_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Webhook-Templates/paths/~1api~1alert~1webhook_templates~1%7Bwebhook_template_id%7D/put) | +| gateway:DeleteWebhookTemplate | arn:api7:gateway:alert/\* | [DELETE /api/alert/webhook_templates/:webhook_template_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Alert-Webhook-Templates/paths/~1api~1alert~1webhook_templates~1%7Bwebhook_template_id%7D/delete) | + +### 权限策略 + +| Action | Resource | API | +| -------------------------- | -------------------------------- | ----------------------------------------------------- | +| iam:GetPermissionPolicy | arn:api7:iam:permissionpolicy/%s | GET /api/permission_policies/:permission_policy_id | +| iam:CreatePermissionPolicy | arn:api7:iam:permissionpolicy/\* | POST /api/permission_policies | +| iam:UpdatePermissionPolicy | arn:api7:iam:permissionpolicy/%s | PUT /api/permission_policies/:permission_policy_id | +| iam:DeletePermissionPolicy | arn:api7:iam:permissionpolicy/%s | DELETE /api/permission_policies/:permission_policy_id | + +### 角色 + +| Action | Resource | API | +| -------------------- | -------------------- | --------------------------------------------------- | +| iam:GetRole | arn:api7:iam:role/%s | GET /api/roles/:role_id | +| iam:GetRole | arn:api7:iam:role/%s | GET /api/roles/:role_id/permission_policies | +| iam:CreateCustomRole | arn:api7:iam:role/\* | POST /api/roles | +| iam:UpdateCustomRole | arn:api7:iam:role/%s | POST /api/roles/:role_id/attach_permission_policies | +| iam:UpdateCustomRole | arn:api7:iam:role/%s | POST /api/roles/:role_id/detach_permission_policies | +| iam:UpdateCustomRole | arn:api7:iam:role/%s | PUT /api/roles/:role_id | +| iam:DeleteCustomRole | arn:api7:iam:role/%s | DELETE /api/roles/:role_id | + +### 用户 + +| Action | Resource | API | +| ------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| iam:GetUser | arn:api7:iam:user/%s | [GET /api/users/:user_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Users/operation/listUsers) | +| iam:InviteUser | arn:api7:iam:user/\* | [POST /api/invites](https://docs.api7.ai/enterprise/reference/admin-api#tag/Users/operation/inviteUser) | +| iam:UpdateUserRole | arn:api7:iam:user/%s | [PUT /api/users/:user_id/assigned_roles](https://docs.api7.ai/enterprise/reference/admin-api#tag/Users/operation/addAssignedRole) | +| iam:ResetPassword | arn:api7:iam:user/%s | [PUT /api/users/:user_id/password_reset](https://docs.api7.ai/enterprise/reference/admin-api#tag/Users/operation/passwordResetToDefault) | +| iam:DeleteUser | arn:api7:iam:user/%s | [DELETE /api/users/:user_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Users/operation/deleteUser) | + +### 证书 + +| Action | Resource | API | +| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | +| iam:UpdateLicense | arn:api7:iam:organization/\* | [PUT /api/license](https://docs.api7.ai/enterprise/reference/admin-api#tag/License/paths/~1api~1license/put) | + +### 审计 + +| Action | Resource | API | +| ---------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| iam:GetAudit | arn:api7:iam:organization/\* | [GET /api/audit_logs](https://docs.api7.ai/enterprise/reference/admin-api#tag/Audit-Logs/operation/listAuditLogs) | +| iam:ExportAudits | arn:api7:iam:organization/\* | [GET /api/audit_logs/export](https://docs.api7.ai/enterprise/reference/admin-api#tag/Audit-Logs/operation/exportAuditLogs) | + +### 设置 + +| Action | Resource | API | +| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| iam:GetSCIMProvisioning | arn:api7:iam:organization/\* | [GET /api/system_settings/scim](https://docs.api7.ai/enterprise/reference/admin-api#tag/System-Settings/paths/~1api~1system_settings~1scim/get) | +| iam:UpdateSCIMProvisioning | arn:api7:iam:organization/\* | [PUT /api/system_settings/scim](https://docs.api7.ai/enterprise/reference/admin-api#tag/System-Settings/operation/updateSCIMSettings) | +| iam:UpdateSCIMProvisioning | arn:api7:iam:organization/\* | [PUT /api/system_settings/scim/token](https://docs.api7.ai/enterprise/reference/admin-api#tag/System-Settings/operation/generateSCIMToken) | +| iam:GetLoginOption | arn:api7:iam:organization/\* | [GET /api/login_options/:login_option_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Login-Option/operation/get_login_option) | +| iam:CreateLoginOption | arn:api7:iam:organization/\* | [POST /api/login_options](https://docs.api7.ai/enterprise/reference/admin-api#tag/Login-Option/operation/create_login_option) | +| iam:UpdateLoginOption | arn:api7:iam:organization/\* | [PUT /api/login_options/:login_option_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Login-Option/operation/update_login_option) | +| iam:UpdateLoginOption | arn:api7:iam:organization/\* | [PATCH /api/login_options/:login_option_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Login-Option/operation/patch_login_option) | +| iam:DeleteLoginOption | arn:api7:iam:organization/\* | [DELETE /api/login_options/:login_option_id](https://docs.api7.ai/enterprise/reference/admin-api#tag/Login-Option/operation/delete_login_option) | diff --git a/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-example.md b/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-example.md new file mode 100644 index 00000000..01236947 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/reference/permission-policy-example.md @@ -0,0 +1,318 @@ +--- +title: 权限策略示例 +slug: /reference/permission-policy-examples +--- + +### 完全访问所有资源 + +```json +{ + "statement": [ + { + "resources": [ + "<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 只读所有资源 + +```json +{ + "statement": [ + { + "resources": [ + "<.*>" + ], + "actions": [ + "<.*>Get<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 只读指定网关组 + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}", + "arn:api7:gateway:gatewaygroup/{gateway group id}" + ], + "actions": [ + "<.*>Get<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>", + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 完全访问指定网关组 + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}", + "arn:api7:gateway:gatewaygroup/{gateway group id}" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/{gateway group id}/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 服务管理员 + +1. 直接在所有网关组上修改特定服务； +2. 修改服务中心中特定服务的模板，然后发布到所有网关组； +3. 将特定服务从一个网关组同步到另一个网关组。 + + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:servicetemplate/{service id}" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/<.*>/publishedservice/{service id}" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/<.*>" + ], + "actions": [ + "gateway:GetGatewayGroup" + ], + "effect": "allow" + } + ] +} +``` + +你也可以使用标签，如果你需要管理多个具有同样标签的服务： + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:servicetemplate/<.*>" + ], + "actions": [ + "<.*>" + ], + "conditions": { + "service_label": { + "type": "MatchLabel", + "options": { + "key": "team", + "operator": "exact_match", + "value": "enterprise" + } + } + }, + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/<.*>/publishedservice/<.*>" + ], + "actions": [ + "<.*>" + ], + "conditions": { + "service_label": { + "type": "MatchLabel", + "options": { + "key": "team", + "operator": "exact_match", + "value": "enterprise" + } + } + }, + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/<.*>" + ], + "actions": [ + "gateway:GetGatewayGroup" + ], + "effect": "allow" + } + ] +} +``` + +### 管理自定义插件 + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaysetting/*" + ], + "actions": [ + "gateway:<.*>CustomPlugin<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 角色管理员 + +1. 邀请/删除用户； +2. 帮助用户重置密码； +3. 设计自定义角色； +4. 为用户分配角色。 + + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:iam:user/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:role/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:permissionpolicy/<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + } + ] +} +``` + +### 创建并管理生产网关组 + +```json +{ + "statement": [ + { + "resources": [ + "arn:api7:gateway:gatewaygroup/<.*>" + ], + "actions": [ + "<.*>" + ], + "conditions": { + "gateway_group_label": { + "type": "MatchLabel", + "options": { + "key": "type", + "operator": "exact_match", + "value": "production" + } + } + }, + "effect": "allow" + }, + { + "resources": [ + "arn:api7:gateway:gatewaygroup/*" + ], + "actions": [ + "gateway:CreateGatewayGroup" + ], + "effect": "allow" + } + ] +} +``` + +### 完全访问除许可证外所有资源 + +```json +{ + "statement": [ + { + "resources": [ + "<.*>" + ], + "actions": [ + "<.*>" + ], + "effect": "allow" + }, + { + "resources": [ + "arn:api7:iam:organization/*" + ], + "actions": [ + "iam:UpdateLicense" + ], + "effect": "deny" // "deny" 优先，最终禁止访问 updateLicense 操作。 + } + ] +} +``` diff --git a/enterprise_versioned_docs/version-3.6.x/release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-notes.md new file mode 100644 index 00000000..45003992 --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/release-notes.md @@ -0,0 +1,893 @@ +--- +title: 更新日志 +slug: /release-notes +--- + +## 3.5.2 版本 + +**发布日期：** 2025-02-13 + +### 缺陷修复 + +* 修复了问题：无法启用 `log rotate` 插件。 +* 修复了问题：在升级过程中，尤其是在使用 MySQL 数据库时，网关实例中偶尔会出现重复数据。 +* 修复了问题：删除自定义插件偶尔会失败。 + +## 3.5.1 版本 + +**发布日期：** 2025-02-06 + +### 缺陷修复 + +* 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。 +* 支持在 OTEL 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 + +## 3.5.0 版本 + +**发布日期：** 2025-01-27 + +### 新功能 + +#### 服务中的多个上游 + +对于高级场景，例如灰度部署、蓝绿部署或管理多个集群，服务现在可以使用多个上游。在这种情况下，默认上游充当大多数请求的主要目标，而其他上游可用于特定目的，例如将流量路由到灰度部署或辅助集群。有关详细信息，请参阅更新后的[配置灰度流量转移](./getting-started/canary-upstream.md)。 + +:::info + +旧的 **灰度规则** 功能不再可用。 + +::: + +### 功能优化 + +* 支持通过 Prometheus 插件元数据自定义配置 DP 指标标签。 +* 优化了数据平面 Prometheus 指标报告的性能。 +* 禁止由于超过许可证 CPU 限制而创建新资源。 +* 为 API7 门户的控制台页面添加了页面大小选择。 +* 支持 YAML/JSON 格式的插件配置。 +* 改进了上游健康检查配置的 UI。 +* [Beta] 为上游配置了 mTLS。API 支持当前可用。完整支持即将推出。 + +### 缺陷修复 + +* 修复了问题：[Traffic Split](https://docs.api7.ai/hub/traffic-split) 插件的 LRU 缓存对象创建函数导致客户端请求异常。 +* 将“启用/禁用插件”重命名为“新增/删除插件”以提高准确性。 + +## 3.4.1 版本 + +**发布日期：** 2025-01-14 + +### 缺陷修复 + +* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 +* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 + +## 3.4.0 版本 + +**发布日期：** 2025-01-07 + +### 新功能 + +#### SNI 管理 + +引入了 [SNI](./key-concepts/snis) 作为管理 TLS 和 mTLS 身份验证以及证书匹配的新机制。有关详细信息，请参阅 [在客户端和 API7 网关之间配置 mTLS](./api-security/client-mtls)。 + +#### API7 门户监控 + +提供监控数据和可视化，以跟踪 API 产品指标。 + +### 功能优化 + +* 自定义插件配置现在应用于网关组级别。有关详细信息，请参阅 [添加自定义插件](./best-practices/custom-plugin)。 +* 数据面升级到 LuaJit 2.1-20240815。 +* 删除了 `grpc-client-nginx-module`。 + +### 缺陷修复 + +* 修复了问题：Redis 延迟同步功能使用的共享内存泄漏。 +* 修复了问题：批量发布超多 service 时审计日志记录失败。 + +## 3.3.3 版本 + +**发布日期：** 2025-01-14 + +### 缺陷修复 + +* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 +* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 + +## 3.3.2 版本 + +**发布日期：** 2024-12-24 + +### 缺陷修复 + +* 修复了问题：从 3.2.16.2 或更旧版本升级到 3.3.1 及更高版本时，控制台无法启动。 + +## 3.3.1 版本 + +**发布日期：** 2024-12-19 + +### 缺陷修复 + +* 修复了问题：运行在 rewrite 阶段的插件在命中消费者后会重复执行。 + +## 3.3.0 版本 + +**发布日期：** 2024-12-16 + +### 新功能 + +#### API7 门户 + +宣布 API7 门户正式发布 (GA)，这是一个用于 API 发现和使用的综合解决方案。探索 [API7 门户](./key-concepts/api-portal) 和 [开发者](./key-concepts/developers) 的关键概念，并开始你的 [服务产品化](./api-portal/productize-services.md) 之旅。 + +### 功能优化 + +* 为 [OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件同步了开源代码。 +* 在访问日志和错误日志中记录请求 ID。 +* 重构了数据面中的过期和淘汰机制。 +* 当告警策略未配置通知通道时，在告警历史记录中添加了提示。 +* 支持与外部 Prometheus 指标集成。 + +### 安全 + +* 解决了 CVE 报告中的漏洞。 + +### 缺陷修复 + +* 解决了问题：数据面到 DPM 的消费者查询（404 错误除外）不应被缓存。 +* 解决了问题：禁用 API7 集成身份验证后，登录页面上的密码登录不可用。 +* 修复了插件全局规则搜索问题。 + +## 3.2.16.7 版本 + +**发布日期：** 2024-12-13 + +### 缺陷修复 + +* 修复了问题：当 DP 管理器收到截断的 Prometheus 指标时，它会进入无限循环。 +* 修复了问题：由于 watch 中断，数据面与控制面的同步可能会中断。 +* 修复了问题：速率限制插件的 Redis 延迟同步功能对于低频请求无法按预期工作。 +* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件使用的共享内存存在故障。 +* 修复了问题：`radixtree_uri_with_parameter` 无法匹配包含带有特殊字符的路径参数的请求。 +* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件滑动窗口中的剩余值应向下舍入，重置值应保留两位小数。 + +## 3.2.16.6 版本 + +**发布日期：** 2024-11-25 + +### 功能优化 + +* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件支持 `key_claim_name`。 +* 为监控添加了网关组过滤。 + +### 缺陷修复 + +* 解决了告警页面中的 UI 问题。 +* 解决了问题：多个数据面容器在控制面中被识别为单个实例，这损害了许可证控制功能和一些指标报告显示功能。 +* 解决了问题：发布大量服务时，审计日志无法记录。 +* 修改了 SSL 证书到期告警条件文本。 +* 解决了问题：由于节点 IP 地址未更新，导致健康检查失败。 +* 将插件中 Lua 代码合法性的验证添加到控制面代码中。 +* 为 [Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件添加了子插件错误消息的记录。 +* 删除了 [Basic Auth](https://docs.api7.ai/hub/basic-auth) 插件中的额外警告日志。 +* 修复了添加新凭据时 Secret 提供商的权限验证错误。 +* 修复了问题：在网关组上添加的已发布服务缺少 `skip path prefix` 配置项。 + +## 3.2.16.5 版本 + +**发布日期：** 2024-11-21 + +### 功能优化 + +* 为 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件添加了 `multipart content type`。 +* 将资源 ID 长度限制从 64 调整为 256。 +* [Workflow](https://docs.api7.ai/hub/workflow) 插件支持 `limit-count-advanced` 作为操作项。 +* 重构了 `core.response.exit` 以阐明参数定义。 +* 在请求上下文中记录已执行的插件，以确保在使用 [Workflow](https://docs.api7.ai/hub/workflow) 插件时，同一插件仅被执行一次。 + +### 缺陷修复 + +* 解决了问题：在 [Prometheus](https://docs.api7.ai/hub/prometheus) 插件中启用 `prefer_name` 选项将导致监控页面上的过滤器发生故障。 +* 解决了问题：匹配匿名消费者时，不会将 `x-consumer-custom-id` 标头添加到请求中。 +* 解决了问题：当同时配置时，[Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件和 [CORS](https://docs.api7.ai/hub/cors) 插件会导致 OPTIONS 请求出错。 +* 临时删除了 [Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件中的沙箱机制。 + +## 3.2.16.4 版本 + +**发布日期：** 2024-11-01 + +### 新功能 + +#### 通过电子邮件发送通知 + +告警策略现在可以通过利用新的`联系人`同时通过 webhook 和电子邮件发送通知。_联系人_ 定义了一组可由多个告警策略使用的电子邮件地址或 webhook URL。 + +有关说明，请参阅[触发网关告警](./api-observability/alert)。 + +:::note + +现有的 `Webhook 模板` 将迁移到新的联系人和告警策略内的通知，确保告警策略的无缝过渡和向后兼容性。 + +::: + +#### 新的 Limit Count Advanced 插件 + +使用滑动窗口算法增强了开源的 limit count 插件，以实现更准确的速率限制。 + +有关详细信息，请参阅 [Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced)插件。 + +#### 新的 Exit Transformer 插件 + +[Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件支持根据 APISIX 插件返回的状态码、标头和正文来自定义网关响应。当配置为全局插件时，它还支持在请求不存在的路由时自定义响应。 + +#### 通过告警策略计算网关组中的健康网关实例数 + +如果网关组中健康网关实例的数量低于临界阈值，则表明可能会出现服务中断并影响流量处理。 +这种情况在 Kubernetes 部署中尤其重要，因为网关实例可能会遇到故障或意外缩减。 + +[创建用于统计网关组中健康网关实例数的告警策略](./api-observability/alert.md#count-healthy-gateway-instances-in-a-gateway-group) 并向相关人员发送通知。 + +### 功能优化 + +* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件 现在支持更多算法。 +* 支持利用表达式匹配来更精确地路由流量。 +* 在 [Grafana 控制台模板](https://grafana.com/grafana/dashboards/11719-apache-apisix/) 中丰富了更多指标。 +* 允许用户按 Enter 键登录。 + +### 缺陷修复 + +* 解决了问题：[CORS](https://docs.api7.ai/hub/cors)插件 `expose_header` 的默认值不应为 `*`。 +* 解决了问题：添加四层服务时可以成功添加第一个四层路由。 +* 解决了问题：`max_req_body_bytes` 限制在日志记录器插件中不起作用。 +* 解决了问题：[Limit Count](https://docs.api7.ai/hub/limit-count) 插件中速率限制参数的动态更新现在会反映在数据面中。 +* 解决了问题：通过 API 删除的服务可以从数据面中一致地删除。 + +## 3.2.16.3 版本 + +**发布日期：** 2024-10-21 + +### 新功能 + +#### 引用在 AWS Secrets Manager 中的密钥（Secrets） + +*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 + +有关更多详细信息，请参阅 [引用在 AWS Secrets Manager 中的密钥](./api-security/aws-secrets-manager.md)。 + +#### 用于 API 身份验证的匿名消费者 + +匿名消费者无需身份验证，但可以限制访问速率。你可以在服务/路由上的身份验证插件中配置匿名消费者，然后与速率限制插件结合使用。 + +有关详细信息，请参阅以下文档： + +* [对匿名消费者进行速率限制](./api-security/rate-limiting.md#add-an-anonymous-consumer) + +#### 安全 + +* 在数据面上添加了用于自身健康检查的状态接口。有关详细信息，请参阅 [启用数据面健康检查以实现高可用性](./high-availability/high-availability-installation.md#health-check)。 + +### 功能优化 + +* 支持 200 万量级消费者。 +* 消费者列表支持按名称排序。 +* 从 API7 网关中删除了 `conf_server`。 +* 改进了速率限制相关插件以使其更加灵活，允许针对每个服务/路由进行特定于消费者的速率限制。有关详细信息，请参阅 [Limit Count](https://docs.api7.ai/hub/limit-count) 插件 和 [Limit Req](https://docs.api7.ai/hub/limit-req) 插件。 +* 升级请求和响应转换插件： + * 在请求转换期间，支持传递 Lua 代码以获取值。 + * 对齐 Kong 的请求转换和响应转换的功能。 +* 显示服务中添加的路由总数。 +* 将插件列表从数据面配置更改为控制面配置。**与 3.2.15.0 以下版本不兼容** +* 在告警策略中添加了证书到期提醒。 +* 在因多设备登录而重定向到登录页面之前显示通知，说明登出原因。 +* 改善了前端页面响应速度和加载速度。 +* 优化了“使用上游超时”UI。 +* 优化了 API7 Portal (Beta) 列表页渲染速度。 + +### 缺陷修复 + +* 解决了问题：现在可以在控制台上为单个路由配置多个路径。 +* 解决了问题：[OpenTelemetry](https://docs.api7.ai/hub/opentelemetry) 插件不支持 `set_ngx_var`。 +* 解决了问题：[ACL](https://docs.api7.ai/hub/acl) 插件 在正常使用情况下不应输出警告日志。 +* 增强了数据面 `lua_ssl_trusted_certificate` 配置项。 +* 将 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件代码与 APISIX 主线版本同步。 +* 解决了问题：当在服务上配置了流模块不可用的插件时，数据面会打印错误日志。 +* 将 Token 的 `Edit` 操作更改为 `Edit Name`。 +* 解决了问题：编辑服务注册中心时，服务发现类型与表单不符。 + +## 3.2.16.2 版本 + +**发布日期：** 2024-10-11 + +### 缺陷修复 + +* 修复了消费者中插件配置更新不生效的问题。 + +## 3.2.16.1 版本 + +**发布日期：** 2024-10-04 + +### 功能优化 + +* 提升了 API7 Portal(Beta) 性能。 + +### 缺陷修复 + +* 解决了删除路由时 `radixtree_host_uri` 路由模式下的 panic 问题。 +* 解决了自定义认证类型插件与[Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件不兼容的问题。 + +## 3.2.16.0 版本 + +**发布日期：** 2024-09-30 + +### 新功能 + +#### 引用在 HashiCorp Vault 中的密钥 + +:::info + +这是一项不兼容变更。`secrets` 资源已重命名为 `secret provider（Secret 提供商）`，以符合最佳实践并促进与外部密钥管理工具的集成。所有相关的 API 都已相应更新。 + +::: + +*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 + +有关更多详细信息，请参阅 [在 HashiCorp Vault 中引用密钥](./api-security/hashicorp-vault.md)。 + +### 功能优化 + +* 【不兼容变更】**删除了 JWT 插件签发令牌的功能，并删除了上传私钥的功能。** 有关详细信息，请参阅 JWT Auth 插件文档。 +* 增加了对删除离线网关实例的支持。 +* 为使用 Redis 的插件添加了 `sync_rate` 参数，以控制与 Redis 同步计数器的频率。实时同步会给 Redis 带来很大的压力。 +* 支持通过 URL 访问特定的路由详情页。 +* 支持 API7 Portal(Beta) 的 API 在线测试。 +* UI 改进：缩短了自定义主机输入框。 +* UI 改进：将负载均衡算法下拉框改为单选框。 +* UI 改进：新建标签样式修改。 + +### 缺陷修复 + +* 修复了问题：未正确清理的 `config_listen.sock` 导致数据面无法启动。 +* 修复了问题：禁用服务后请求接口报 `404` 错误。 +* 为 [Splunk-Hec-Logging](https://docs.api7.ai/hub/splunk-hec-logging) 插件添加了 `keepalive_timeout` 配置。 +* 修复了消费者的标签分割后各元素还保留分隔符前后的空白问题。 +* 修复了问题：[Skywalking](https://docs.api7.ai/hub/skywalking) 插件销毁后无法重新启动。 +* 修复了问题：数据面没有正确处理非认证插件配置在消费者上时的加解密。 +* 修复了问题：内置权限策略应无法删除。 +* 修复了问题：ingress controller 类型网关组应能够删除。 +* 修复了问题：数据面 path prefix 应当支持配置 `/`。 +* 修复了 UI 问题：点击标签页面跳转到搜索框。 +* 修复了 UI 问题：新建令牌并删除令牌后，新建提示没有消失。 +* 为插件分类添加了中文翻译。 +* 扩大了插件描述文字框，以完整显示插件的介绍。 +* 修复了新建令牌并删除令牌后，新建提示没有消失的问题。 + + +## 3.2.15.2 版本 + +**发布日期：** 2024-09-19 + +### 缺陷修复 + +* 调整 [Attach Consumer Label](https://docs.api7.ai/hub/attach-consumer-label) 插件到 `before_proxy` 阶段执行。 + +## 3.2.15.1 版本 + +**发布日期：** 2024-09-18 + +### 缺陷修复 + +* 解决了使用令牌获取 `instance_token` 返回 401 的问题。 + +## 3.2.15.0 版本 + +**发布日期：** 2024-09-14 + +### 新功能 + +#### 消费者凭据 + +:::info + +这是一项不兼容变更。不再支持为消费者创建新的身份验证插件（Key Auth、Basic Auth、JWT Auth 或 HMAC Auth）。请改用消费者凭据。现有的插件配置将保持可访问和可编辑，直到被禁用。 + +::: + +消费者凭据通过允许多个凭据对应每个消费者来增强灵活性。它们取代了传统的身份验证插件，如 [Key Auth](https://docs.api7.ai/hub/key-auth)、[Basic Auth](https://docs.api7.ai/hub/basic-auth)、[JWT Auth](https://docs.api7.ai/hub/jwt-auth) 和 [HMAC Auth](https://docs.api7.ai/hub/hmac-auth)，提供了更友好的用户体验。有关详细信息，请参阅[管理消费者凭据](./api-consumption/manage-consumer-credentials.md)。 + +### 安全 + +* 根用户 `admin` 成为受保护帐户，角色、权限策略或其他用户无法对其进行修改。其他用户无法删除它或重置其密码。 + +### 功能优化 + +* 现在支持按名称按字母顺序对服务列表进行排序。 +* 向每个审计日志添加了网关组 ID，以便你可以按网关组搜索或过滤审计日志。 +* 为已离线超过 7 天的自动删除的网关实例记录了审计日志。 +* 支持按标签过滤网关组上发布的服务。 +* 确保控制面地址不以斜杠结尾。 +* 在 Helm 中支持注释。 +* 提供配置项控制数据面心跳、遥测请求的超时，并且调整默认值为 30s。 + +### 缺陷修复 + +* 优化了在启用 SCIM 后用户通过 SSO 登录但系统中不存在该用户时的错误消息。 +* 修复了修改未发布版本的服务后灰度配置调整失败的问题。 + +## 3.2.14.4 版本 + +**发布日期：** 2024-08-14 + +### 新功能 + +#### 覆盖每个路由的上游超时 + +API7 网关允许为各个路由配置不同的上游超时，以覆盖上游侧的超时配置，从而实现对请求处理的精细控制。 + +#### 用户权限边界 + +权限边界定义了用户的最大允许权限，作为防止用户越权的保障措施。 + +### 安全提升 + +* 升级了前端依赖项。 +* 确保单设备登录 - 新登录将撤销之前存在的活跃会话。 +* 禁止导入旧许可证。 +* 升级了 OpenResty 版本以修复安全漏洞。 + +### 功能优化 + +* 在服务中心列表和已发布服务列表中添加了服务描述。 +* 为服务注册中心添加了“连接中”状态，以避免误解。 +* 自定义插件支持代码混淆和加密存储。 +* 在使用测试环境许可证时显示通知。 +* 为插件管理和修改实现了基于卡片的 UI。 +* 支持配置自定义插件元数据。 +* 最小化了 API7 企业版的镜像大小。 + +### 缺陷修复 + +* 修复了将服务版本发布到网关组时，服务运行时配置参数（例如，主机、路径前缀）的空值丢失的问题。 +* 消除了 dry-run 模式下调用许可证上传时生成的不必要的审计日志。 +* 解决了路由创建和修改时间戳不正确的问题。 +* 解决了插件元数据 Schema 的校验报错。 +* 提高了服务搜索准确性。 +* 解决了服务模板发布期间插件丢失的问题。 + +## 3.2.14.3 版本 + +**发布日期：** 2024-08-06 + +### 缺陷修复 + +* 支持在 SSL 证书中引用 `$env`。 +* 解决了标签包含句点时 UI 不稳定的问题。 + +## 3.2.14.2 版本 + +**发布日期：** 2024-07-30 + +### 缺陷修复 + +* 解决了在控制台上查看 Ingress Controller 路由时的报错。 +* 修复了在 Kubernetes 上安装网关实例时缺少默认 Helm release 名称的问题。 +* 通过使用 ID 令牌优化了与 Azure AD 的集成。 +* 修复了服务模板和已发布的网关组之间可能出现插件不一致的问题。 + +## 3.2.14.1 版本 + +**发布日期：** 2024-07-22 + +### 功能优化 + +#### 导入 OpenAPI 以在网关组上创建服务 + +只需将 OpenAPI 文件直接导入网关组，即可创建新服务及其所有路由。 + +#### 通过 API7 Portal 实现精细的访问控制 + +利用自定义角色和权限策略对 API 产品的访问进行精细控制。 + +#### 安全提升 + +* 控制面地址必须为 HTTPs。 +* 移除 `ngx.req.get_post_args(0)` 的使用，改用默认值以避免潜在的攻击。 +* 重新生成 Ingress Controller 部署脚本现在需要二次确认。 + +#### 无需版本控制即可管理已发布服务基础信息 + +现在可以修改服务名称/描述/标签，而无需发布新版本。 + +#### 服务设置期间首次创建路由 + +你可以选择从一开始就定义服务里的第一条初始路由，无需额外的步骤，简化了工作流程。 + +### 缺陷修复 + +* 将 [Datadog](https://docs.api7.ai/hub/datadog) 插件修复 (https://github.com/apache/apisix/pull/11354) 合并到 API7 企业版。 +* 修复了控制台上数据面不可见的问题。 +* 修复了一个问题：将 Prometheus 数据报告方法从远程写入更改为抓取后，服务注册表状态始终显示为“断开连接”。 +* 修复了通过控制台部署自定义插件后，数据面遇到错误的问题。 +* 修复了前端错误：不应该允许通过控制台在 Ingress Controller 网关组上修改已发布服务的上游。 +* 去掉不该出现的报错通知：切换到节点时，即使启用了健康检查，仍然存在提示用户启用健康检查的提示。 +* 修复问题：上传自定义插件时，如果出现解析错误，错误消息中显示的插件名称与实际文件名不匹配。 + +## 3.2.14.0 版本 + +**发布日期：** 2024-07-08 + +### 新功能 + +#### 全新的访问控制机制 + +:::info + +这是一项不兼容变更。旧版本的规则不能保留。 + +::: + +API7 企业版改进了传统的基于角色的权限，采用了权限策略架构，通过分配给角色的可复用策略来实现精细的访问控制。请参阅[角色和权限策略](./key-concepts/roles-and-permission-policies.md)。 + +### 功能优化 + +#### 配置路由优先级 + +在特定场景下，你可以在两个不同的服务中配置相同的路由。通过优先级确定哪个路由处理请求。具有较高指定优先级的路由将首先被使用。 + +#### 强化 mTLS 证书安全 + +改进了以下问题： + +- 过长的证书：证书字符串太长，应该缩短。 +- 不必要的标记：证书包含不必要的标记，应该删除。 +- 共享 CA：为多个证书使用相同的证书颁发机构 (CA) 是不安全的。 +- 证书不匹配处理：当发生证书不匹配时，握手应立即失败，拒绝客户端的请求，而不是继续进行进一步的验证。 + +#### 在 API7 Helm Chart 中包含新的参数 `lua_shared_dict` + +为 Helm chart 引入了一个新的参数。 + +### 缺陷修复 + +- 从旧版本升级可能会导致上游数据丢失或 404 错误。 +- 服务请求 URL 更新期间遇到 UI 错误。 +- 修复了 API7 Portal (Beta) 库问题。 +- 修复了 [HTTP Logger](https://docs.api7.ai/hub/http-logger) 插件内存泄漏。 +- 前端和后端密码策略不一致。 +- 当 GET 请求与任何路由都不匹配时，[Data Mask](https://docs.api7.ai/hub/data-mask) 插件会报告错误。 +- ApisixUpstream CRD 的 status 字段记录不正确。 +- 数据面支持配置监控数据的报告间隔。 +- 修复了配置插件元数据后的警告日志。 +- 修复了插件重新加载问题。 +- 减少 PostgreSQL 连接数。 +- 优化前端资源消耗。 +- 删除 FQDN 中的尾随点。 +- 插件元数据应该能够被删除。 + +## 3.2.11.8 版本 + +**发布日期：** 2024-06-26 + +### 缺陷修复 + +- 通过减少 etcd 调用来降低 API 延迟。 +- Kine 数据库连接池配置可以正常工作。 + +## 3.2.11.7 版本 + +**发布日期：** 2024-06-24 + +### 缺陷修复 + +- 提升 API 性能。 +- 数据面支持禁用遥测数据收集和配置报告间隔。 +- 自定义插件即使没有 schema 定义也可以正常工作。 + +## 3.2.11.6 版本 + +**发布日期：** 2024-06-24 + +### 缺陷修复 + +- 大数据集不再导致 etcd range API 错误。 + +## 3.2.13.0 版本 + +**发布日期：** 2024-06-19 + +### Admin API 不兼容变更 + +1. 服务模板 API 已迁移到 "/api/services/template" 路径前缀下。 + +- [服务模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services-Template) +- [路由模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes-Template) + +2. 原始的 "/apisix/admin/services" 端点现在需要 gateway_group_id 参数。 + +- [网关组上的服务 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services) +- [网关组上的路由 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes) + +### 新增功能 + +#### 在网关组上创建/更新服务而不发布 + +如果版本控制不是你的要求，你现在可以直接在网关组上创建服务。这些服务会立即生效，无需单独的发布步骤。这简化了部署过程并节省了时间。 + +但是，重要的是要考虑所涉及的权衡。通过绕过发布阶段，你也失去了轻松回滚到以前版本或跟踪版本更改的能力。 + +有关详细信息，请参阅最新的入门教程：[启动你的第一个 API](./getting-started/launch-your-first-api.md)。 + +#### 与 Ingress Controller 集成（UI 支持） + +API7 Gateway 正式推出 Ingress Controllers，这是一种新型的网关组。虽然控制台提供了方便的管理功能来创建和查看你的 Ingress Controller，但配置修改需要对任何配置更改采用声明方式。 + +### 功能优化 + +#### 搜索网关组名称并按标签过滤 + +使在网关组列表中查找所需的特定网关组变得更加容易。 + +#### 保护配置文件中的敏感数据 + +数据库的 DSN 配置（包括访问地址、用户名和密码）可以通过环境变量和 Helm 图表进行配置。 + +#### 支持 Prometheus 认证 + +Prometheus 远程写入现在支持 Basic Auth/mTLS。 + +#### 支持 SSL 变量的 Secret 功能 + +使用加密的 Secret 保护 `ssl.certs` 和 `ssl.keys`。 + +### 缺陷修复 + +- 设置标头后，`ctx.var` 变量将立即更新。 +- 无法上传重复的 SSL 证书。 + +## 3.2.11.5 版本 + +**发布日期：** 2024-06-18 + +### 缺陷修复 + +- ssl_verify 配置现在适用于登录选项 OIDC 和 LDAP 协议。 + +## 3.2.11.4 版本 + +**发布日期：** 2024-06-07 + +### 缺陷修复 + +- 保护与 API 相关的登录选项中的敏感字段。 + +## 版本 3.2.12.0 + +**发布日期**: 2024-05-24 + +### Admin API 不兼容变更 + +1. service status 字段从“0: 启用，1: 禁用”变更为“0: 禁用，1: 启用” + +- [Publish a service](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services/paths/~1api~1services~1publish/post) +- [Update service runtime configurations by ID](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/changeServiceRuntimeConfiguration) +- [Get all published services in Gateway Group](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/listPublishedService) + +2. consumer api 移除 id 字段，使用 gateway group id & username 做查询、删除 + +- [Consumers APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers) + +3. ssl 相关 api 强制 gateway group id 参数 + +- [SSL APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/SSLs) + +### 新增功能 + +#### 四层路由（Stream Route） + +API7 网关现在可以处理四层流量，比如与数据库或 Kafka 的连接。 添加一个四层类型的服务，并在其中添加若干个四层路由（Stream Route，即可[转发四层流量](./getting-started/proxy-l4-traffic.md)。 + +#### 自定义角色 (控制台支持) + +当默认提供的角色无法满足需求时，你可以自行设计自定义角色，实现精细化权限控制。可参阅[添加自定义角色](./getting-started/rbac.md) + +#### Ingress Controller（Beta 测试版，仅 API 支持） + +集成 Ingress Controller。 + +### 功能优化 + +#### 优化左侧导航菜单 + +- 用户登录后落地页改为网关组菜单中已发布服务。 +- **服务** 菜单项改名为 **服务中心**。 + +### 缺陷修复 + +- 使用 [Key Auth](https://docs.api7.ai/hub/key-auth) 插件时，禁止出现重复的 API 密钥。 +- 使用 [UA Restriction](https://docs.api7.ai/hub/ua-restriction) 插件时，允许同时配置黑名单和白名单。 +- 重置用户密码时不会引起访问令牌失效。 +- 使用 [Loggly](https://apisix.apache.org/zh/docs/apisix/plugins/loggly/) 插件时配置能校验成功。 +- API7 网关中的状态字段取值含义和 Apache APISIX 保持一致。 + +## 版本 3.2.11.3 + +**发布日期: 2024-05-20 + +### 缺陷修复 + +- etcd watch 可以正确地传递 SNI。 +- API7 企业版在安装时会先尝试创建新的数据库。如果没有对应权限导致失败，会使用预先指定的已有数据库，避免安装失败。 + +## 版本 3.2.11.2 + +**发布日期**: 2024-05-20 + +### 缺陷修复 + +- 标签支持最长 64 个字符，且可以包含空格。 +- 即使包含 schema 校验错误，也可以正常完成与数据面的配置同步，避免数据丢失或工作流中断。 + +## 版本 3.2.11.1 + +**发布日期**: 2024-05-08 + +### 新增功能 + +#### SSO 角色映射 + +设置自动角色映射，可以避免超级管理员需要频繁为 SSO 登陆的用户分配角色。 满足预先设置的映射条件的用户，在登陆 API7 企业版时会自动获得相应的角色权限。详情参阅[设置角色映射](./best-practices/sso.md#设置角色映射)。 + +#### SCIM 用户同步 + +使用 SCIM 用户同步协议简化 SSO 用户管理。它可以自动从所有支持了 SCIM 协议的、已经添加了登陆选项的身份提供商同步用户数据，确保用户信息一致性。新用户在身份提供商注册，或用户在身份提供商注销，API7 企业版即可得到及时通知，避免新用户无法登陆或已注销用户非法登陆。详情参阅[Sync User Data from IdP](./best-practices/sso.md#从身份提供商同步用户数据)。 + +#### 自定义角色 (Beta, 仅 API 支持) + +如默认角色不满足业务需求，现在你可以设计自定义角色，自由组合权限，进行细粒度权限控制。 +该功能即将在后续版本支持控制台配置。 + +### 功能优化 + +#### 升级到 OpenSSL 3 + +提升安全性，性能，和可靠性。 + +#### 全局插件执行顺序优化 + +为了简化全局插件的管理，API7 企业版 会将多个全局插件配置整合到一起，确保插件配置和执行顺序不会产生冲突。 + +### 缺陷修复 + +#### 前端补全 HTTP 协议检测 + +生成的网关实例部署脚本有时无法正确检测是否需要 HTTP 或 HTTPS 协议，这可能会导致部署时出现错误。 + +#### 上传 SSL 证书错误 + +为网关组 A 上传的 SSL 证书可能会意外分配给网关组 B。 + +#### 支持主机级动态设置 TLS 协议版本 + +同步集成了在 Apache APISIX 中已解决的问题。 + +## 版本 3.2.10.1 + +**发布日期**：2024-04-28 + +### 新增功能 + +#### 支持 MySQL 5.7 + +现在起 API7 企业版支持使用 MySQL 5.7 作为持久化数据存储。 + +## 版本 3.2.10.0 + +**发布日期**: 2024-04-22 + +### 不兼容变更 + +#### 令牌绑定用户 + +令牌改为和具体用户绑定，且和用户享有相同的角色权限。如果用户被删除，绑定的令牌也将立刻失效被删除。 + +## 版本 3.2.9.5 + +**发布日期**：2024-04-16 + +### 新增功能 + +#### 上游 mTLS（仅 API 支持） + +支持在 API7 网关和上游服务之间配置 mTLS 认证。 mTLS 是一种通信安全形式，要求双方彼此展示证书。这确保了双方都是其声称的身份，并且在它们之间传输的数据是加密的。 +该功能即将在后续版本支持控制台配置。 + +## 版本 3.2.9.4 + +**发布日期**: 2024-04-07 + +### 缺陷修复 + +#### CPU 核心数判断 + +修复了当 CPU 核心数达到最大限制时出现的问题。 + +## 版本 3.2.9.3 + +**发布日期**: 2024-04-03 + +### 新增功能 + +#### 集成 Vault(Beta) + +将敏感信息存储到 Vault中。仅支持通过 Admin API 使用，UI 使用即将推出。 + +## 版本 3.2.9.2 + +**发布日期**: 2024-04-01 + +### 新增功能 + +#### 支持 SAML 第三方登录 + +API7 企业版新增支持对接 SAML 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md)。 + +#### 新插件： Data Mask + +[Data Mask](https://docs.api7.ai/hub/data-mask) 插件提供了在请求头、请求体和 URL 查询中移除或替换敏感信息的能力。 + +### 功能优化 + +#### 忽略路径前缀 + +你可以选择在向上游发送请求时跳过路径前缀。这种调整对用户来说是不感知的，并且在使用不同的路径前缀来识别发送到不同网关组的 API 时可能很有用。 + +#### 优化健康检查配置 UI + +提供一个更直观友好的健康检查配置交互界面。 + +#### 升级加密算法 + +从 AES128 升级到 AES 256。 + +#### 性能提升 + +消除了禁用插件后带来的性能损耗。 + +## 版本 3.2.9.1 + +**发布日期*: 2024-03-19 + +### 新增功能 + +#### 支持自定义插件管理 + +API7 企业版支持上传你自行编写的自定义插件，以扩展 API 管理的功能。详情见[新增自定义插件](./best-practices/custom-plugin.md). + +#### 支持 OIDC 第三方登录 + +API7 企业版即 LDAP 之后，新增支持对接 OIDC 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md). + +#### 将服务标签作为 API 提供者授权范围 + +通过将服务标签作为为API提供者的范围，你可以授予他们访问带有特定标签的所有服务的权限。这将有助于减轻超级管理员的工作负担。通常，可以使用“部门”标签对服务进行分组。此后该部门的用户将能够访问属于该部门的所有服务。 + +## 版本 3.2.8.1 + +**发布日期**： 2024-02-08 + +### 新增功能 + +#### 支持 Nacos 服务发现 + +API7 企业版利用服务发现功能自动检测可用的上游服务，并将其地址保存在数据库（也被称之为服务注册中心）中。因此，API 网关能够通过服务注册中心获取最新的上游地址列表，确保所有请求都被转发到健康的上游节点。 + +在本版本中，API7 企业版支持与 Nacos 服务发现集成。用户可以使用 Nacos 服务发现来[发布服务](./getting-started/publish-service.md)和[在网关组之间同步服务](./getting-started/sync-service.md)。 + +#### 支持 LDAP SSO 登录 + +API7 企业版支持 LDAP 单点登录（Single Sign-On，SSO）。将 API7 企业版与 LDAP 集成后，用户可以直接使用 LDAP 用户名和密码登录 API7 控制台，创建和管理 API7 网关资源。有关如何配置 LDAP SSO 登录方法的具体信息，参见[配置 LDAP 单点登录](./best-practices/sso.md)。 + +#### 支持使用 Kubernetes 添加网关实例 + +用户使用网关实例来处理流量。在本版本中，API7 企业版支持使用 Kubernetes 向网关组添加网关实例。有关如何通过 Kubernetes 添加网关实例的具体信息，参见[添加网关实例](./getting-started/add-gateway-instance.md)。 diff --git a/enterprise_versioned_sidebars/version-3.6.x-sidebars.json b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json new file mode 100644 index 00000000..b152a624 --- /dev/null +++ b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json @@ -0,0 +1,167 @@ +{ + "docs": [ + { + "type": "category", + "label": "产品介绍", + "items": [ + "introduction/what-is-api7-ee", + "introduction/api7-ee-architecture" + ] + }, + { + "type": "category", + "label": "核心概念", + "items": [ + "key-concepts/overview", + "key-concepts/services", + "key-concepts/routes", + "key-concepts/upstreams", + "key-concepts/gateway-groups", + "key-concepts/stream-routes", + "key-concepts/consumers", + "key-concepts/plugins", + "key-concepts/roles-and-permission-policies", + "key-concepts/certificates", + "key-concepts/snis", + "key-concepts/api-portal", + "key-concepts/api-products", + "key-concepts/developers" + ] + }, + { + "type": "category", + "label": "快速入门", + "items": [ + "getting-started/install-api7-ee", + "getting-started/deploy-resources-on-k8s", + "getting-started/launch-your-first-api", + "getting-started/add-gateway-group", + "getting-started/add-gateway-instance", + "getting-started/proxy-l4-traffic", + "getting-started/create-custom-role", + "getting-started/rbac", + "getting-started/license", + "getting-started/canary-upstream", + "getting-started/publish-service", + "getting-started/sync-service", + "getting-started/rollback-service", + "getting-started/audit-logging" + ] + }, + { + "type": "category", + "label": "API 安全", + "items": [ + "api-security/api-authentication", + "api-security/rate-limiting", + "api-security/block-ip", + "api-security/client-mtls", + "api-security/aws-secrets-manager", + "api-security/hashicorp-vault" + ] + }, + { + "type": "category", + "label": "API 可观测性", + "items": [ + "api-observability/monitoring", + "api-observability/logging", + "api-observability/alert" + ] + }, + { + "type": "category", + "label": "API 消费", + "items": [ + "api-consumption/manage-consumer-credentials", + "api-consumption/consumer-restriction" + ] + }, + { + "type": "category", + "label": "API 门户", + "items": [ + "api-portal/productize-services", + "api-portal/developer-sso" + ] + }, + { + "type": "category", + "label": "最佳实践", + "items": [ + "best-practices/api-version-control", + "best-practices/configure-grpc", + "best-practices/manage-token", + "best-practices/upstream-ha", + "best-practices/service-discovery", + "best-practices/manage-services-in-multi-environments", + "best-practices/sso", + "best-practices/devops-adc", + "best-practices/design-custom-role-system" + ] + }, + { + "type": "doc", + "label": "更新日志", + "id": "release-notes" + }, + { + "type": "category", + "label": "开发参考", + "items": [ + { + "type": "link", + "label": "Admin APIs", + "href": "/enterprise/reference/admin-api" + }, + { + "type": "category", + "label": "部署", + "items": [ + "deployment/k8s-openshift", + "deployment/ingress-controller" + ] + }, + { + "type": "category", + "label": "ADC", + "items": [ + "reference/adc", + "reference/configuration-adc", + "reference/openapi-adc" + ] + }, + { + "type": "category", + "label": "高可用", + "items": [ + "high-availability/overview", + "high-availability/prepare-for-high-availability", + "high-availability/high-availability-installation", + "high-availability/data-plane-resilience" + ] + }, + { + "type": "category", + "label": "性能报告", + "items": [ + "performance/performance-testing", + "performance/benchmark", + "performance/aws-eks" + ] + }, + { + "type": "category", + "label": "权限策略", + "items": [ + "reference/permission-policy-action-and-resource", + "reference/permission-policy-example" + ] + }, + "reference/hardening", + "reference/configuration", + "reference/alert-template" + ] + } + ] +} From 7c320b6ae4c5a0d2e4ab0aea8a75488965710609 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Fri, 7 Mar 2025 14:58:19 +0800 Subject: [PATCH 02/24] Create upstream-mtls.md --- .../api-security/upstream-mtls.md | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md new file mode 100644 index 00000000..fed55e6c --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md @@ -0,0 +1,229 @@ +--- +title: 配置 API7 企业版 和上游之间的 mTLS +slug: /api-security/upstream-mtls +description: 按照本指南配置 API 网关和上游之间的相互 TLS (mTLS)，通过双方的相互身份验证来增强安全性。 +--- + +Mutal TLS (mTLS) 是一种双向 TLS，客户端和服务器相互验证身份。它通常在对安全要求高的环境中采用，以防止未经授权的访问并加强安全性。 + +本指南将引导你完成如何在 API7 网关 和上游服务之间配置 mTLS 的过程，使用 NGINX 作为示例上游服务。 + +## 前提条件 + +* [安装 API7 企业版](../getting-started/install-api7-ee)。 +* 在 API7 企业版上创建令牌。 + +## 生成证书和密钥 + +1. 生成 CA 密钥和证书。 + + ```json + openssl genrsa -out ca.key 2048 + openssl req -x509 -new -nodes -key ca.key -sha256 -days 36500 -out ca.crt \ + -subj "/CN=ROOTCA" + ``` + +2. 使用 `test.com` 为 API7 企业版生成服务器密钥和证书，并使用 CA 证书签名。 + + ```json + openssl genrsa -out server.key 2048 && \ + openssl req -new -key server.key -out server.csr -subj "/CN=test.com" && \ + cat > server.ext << EOF + authorityKeyIdentifier=keyid,issuer + basicConstraints=CA:FALSE + keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment + subjectAltName = @alt_names + [alt_names] + DNS.1 = test.com + EOF + openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \ + -CAcreateserial -out server.crt -days 36500 \ + -sha256 -extfile server.ext + ``` + +3. 使用 `CLIENT` 为客户端生成密钥和证书，并使用 CA 证书签名。 + + ``` + openssl genrsa -out client.key 2048 && \ + openssl req -new -key client.key -out client.csr -subj "/CN=client" && \ + cat > client.ext << EOF + authorityKeyIdentifier=keyid,issuer + basicConstraints=CA:FALSE + keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment + extendedKeyUsage = clientAuth + EOF + openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 36500 -sha256 -extfile client.ext + ``` + +4. 生成证书和密钥后，检查本地设备以找到这些文件。 + + ❶ `client.crt`: 客户端证书 + + ❷ `client.key`: 客户端证书密钥 + + ❸ `ca.crt`: CA 证书 + +## 配置上游服务 + +启动 NGINX 服务器作为示例上游服务： + +```shell +docker run -d \ + --name quickstart-nginx \ + --network=apisix-quickstart-net \ + -p 8443:8443 \ + nginx +``` + +将 CA 证书、服务器证书公钥和私钥复制到 NGINX 中： + +```shell +docker cp ca.crt quickstart-nginx:/var/ca.crt +docker cp server.crt quickstart-nginx:/var/server.crt +docker cp server.key quickstart-nginx:/var/server.key +``` + +在 NGINX 配置文件中配置侦听 `/hello` 和端口 `8443` 的 HTTPs 服务器： + +```text title="/etc/nginx/nginx.conf" +user nginx; +worker_processes auto; + +error_log /var/log/nginx/error.log notice; +pid /var/run/nginx.pid; + + +events { + worker_connections 1024; +} + + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + + access_log /var/log/nginx/access.log main; + + sendfile on; + #tcp_nopush on; + + keepalive_timeout 65; + + #gzip on; + + server { + listen 8443 ssl; + # highlight-start + // Annotate 1 + server_name test.com; + // Annotate 2 + ssl_certificate /var/server.crt; + // Annotate 3 + ssl_certificate_key /var/server.key; + // Annotate 4 + ssl_client_certificate /var/ca.crt; + // Annotate 5 + ssl_verify_client on; + # highlight-end + location /hello { + return 200 "Hello API7!"; + } + } + + include /etc/nginx/conf.d/*.conf; +} +``` + +❶ `server_name`: 设置为 `test.com`，以便与服务器证书的 CN 值保持一致。 + +❷ `ssl_certificate`: 配置服务器证书公钥 `server.crt` 的路径。 + +❸ `ssl_certificate_key`: 配置服务器证书私钥 `server.key` 的路径。 + +❹ `ssl_client_certificate`: 配置 CA 证书公钥 `ca.crt` 的路径。 + +❺ `ssl_verify_client`: 设置为 `on`，以验证客户端证书。 + +重新加载 NGINX 服务器以应用配置更改： + +```shell +docker exec quickstart-nginx nginx -s reload +``` + +要验证 NGINX 实例是否已正确配置，请使用客户端证书和密钥向路由发送请求： + +```shell +curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key +``` + +你应该收到一个 `HTTP/1.1 200 OK` 响应。 + +## 为 API7 企业版配置 mTLS + +### 创建到 NGINX 服务器的路由 + +1. 从侧边导航栏中选择你的网关组下的 **已发布服务**，然后点击 **新增服务**。 +2. 选择 **手动新增**。 +3. 在 **新增服务** 对话框中，执行以下操作： + * 在 **服务基本信息** 的 **名称** 字段中，输入 `mtls-nginx`。 + * 在 **服务类型** 字段中，选择 `HTTP (七层代理)`。 + * 在 **上游基本信息** 的 **名称** 字段中，输入 `default`。 + * 在 **如何查找上游** 字段中，选择 `使用节点`。 + * 点击 **新增节点**。 + * 在 **新增节点** 对话框中，执行以下操作： + * 在 **主机** 字段中，输入你的 API7 控制面板的 IP 地址。 + * 在 **端口** 字段中，输入 `8443`。 + * 在 **权重** 字段中，输入 `100`。 + * 在 **上游协议** 字段中，选择 `HTTPs`。将 **客户端证书** 和 **CA 证书** 字段留给后续步骤。 + * 打开 **新增第一个路由** 开关，然后创建一个带有 `GET` 方法的 `/hello` 路由。 + * 点击 **新增**。 + +### 创建证书 + +1. 从侧边导航栏中选择你的网关组的 **证书**，进入 **SSL 证书** 选项卡。 +2. 点击 **新增 SSL 证书**。 +3. 在对话框中，执行以下操作： + +* 在 **名称** 字段中，输入 `Upstream SSL Certificate`。 +* 在 **证书** 字段中，上传 `client.crt` 文件。 +* 在 **私钥** 字段中，上传 `client.key` 文件。 +* 点击 **新增**。 + +4. 从侧边导航栏中选择你的网关组的 **证书**，然后点击 **CA 证书** 选项卡。 +5. 点击 **新增 CA 证书**。 +6. 在对话框中，执行以下操作： + +* 在 **名称** 字段中，输入 `Upstream CA Certificate`。 +* 在 **证书** 字段中，上传 `ca.crt` 文件。 +* 点击 **新增**。 + +### 配置上游证书 + +1. 从侧边导航栏中选择你的网关组的 **已发布服务**，进入你之前创建的 `mtls-nginx` 服务。 +2. 从侧边导航栏中选择 **上游**。 +3. 点击 **连接配置** 字段的编辑按钮。 +4. 在对话框中，执行以下操作： + +* 在 **客户端证书** 字段中，选择 `Upstream SSL Certificate`。 +* 在 **CA 证书** 字段中，选择 `Upstream CA Certificate`。 +* 点击 **保存**。 + +## 验证 API7 企业版和上游服务之间的 mTLS + +向路由发送请求： + +```shell +curl -ik "http://127.0.0.1:9080/hello" +``` + +你应该收到一个 `HTTP/1.1 200 OK` 响应，验证 API7 Enterprise 和上游之间的 mTLS 已成功设置。 + +## 相关阅读 + +* 核心概念 + * [证书](../key-concepts/certificates) + \ No newline at end of file From 3fa932159d0e62f0dba784a9e508e1ddb3282e4c Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Fri, 7 Mar 2025 14:59:22 +0800 Subject: [PATCH 03/24] Update release-notes.md --- enterprise_versioned_docs/version-3.5.x/release-notes.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/enterprise_versioned_docs/version-3.5.x/release-notes.md b/enterprise_versioned_docs/version-3.5.x/release-notes.md index 45003992..5e9bb4d0 100644 --- a/enterprise_versioned_docs/version-3.5.x/release-notes.md +++ b/enterprise_versioned_docs/version-3.5.x/release-notes.md @@ -3,6 +3,14 @@ title: 更新日志 slug: /release-notes --- +## 3.5.3 版本 + +**发布日期**: 2025-02-18 + +### 缺陷修复 + +* 修复问题：告警邮件主题现在支持使用变量。 + ## 3.5.2 版本 **发布日期：** 2025-02-13 From 2911d192fc721581a8546a7f594038cb2fcc7635 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:24:30 +0800 Subject: [PATCH 04/24] Update release-notes.md --- .../version-3.5.x/release-notes.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/enterprise_versioned_docs/version-3.5.x/release-notes.md b/enterprise_versioned_docs/version-3.5.x/release-notes.md index 5e9bb4d0..8f0a8edf 100644 --- a/enterprise_versioned_docs/version-3.5.x/release-notes.md +++ b/enterprise_versioned_docs/version-3.5.x/release-notes.md @@ -3,6 +3,20 @@ title: 更新日志 slug: /release-notes --- +## 3.5.4 版本 + +**发布日期**: 2025-03-07 + +## 功能优化 + +* 支持在 [Elasticsearch Logger](/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 +* 优化了慢查询。 + +### Bug 修复 + +* 修复问题：使用模板重新发布可能导致上游配置丢失。 +* 修复问题：使用 ADC 重建服务后，页面上的 OpenAPI 缓存无法失效。 + ## 3.5.3 版本 **发布日期**: 2025-02-18 From 778b053d0f51fa1bee54b1e5bdc900e71515355b Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:24:33 +0800 Subject: [PATCH 05/24] Create old-release-notes.md --- .../release-note/old-release-notes.md | 921 ++++++++++++++++++ 1 file changed, 921 insertions(+) create mode 100644 enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md new file mode 100644 index 00000000..9668e6fc --- /dev/null +++ b/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md @@ -0,0 +1,921 @@ +--- +title: API7 企业版更新日志(版本3.5.x及之前) +slug: /old-release-notes +--- + +:::note + +从 3.6.0 版本开始，数据面和控制面的版本将解耦，允许独立升级。控制面通常会兼容多个数据面版本，而数据面版本会以较慢的速度更新以保持稳定性。 + +::: + +## 3.5.4 版本 + +**发布日期**: 2025-03-07 + +## 功能优化 + +* 支持在 [Elasticsearch Logger](/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 +* 优化了慢查询。 + +### Bug 修复 + +* 修复问题：使用模板重新发布可能导致上游配置丢失。 +* 修复问题：使用 ADC 重建服务后，页面上的 OpenAPI 缓存无法失效。 + +## 3.5.3 版本 + +**发布日期**: 2025-02-18 + +### 缺陷修复 + +* 修复问题：告警邮件主题现在支持使用变量。 + +## 3.5.2 版本 + +**发布日期：** 2025-02-13 + +### 缺陷修复 + +* 修复了问题：无法启用 `log rotate` 插件。 +* 修复了问题：在升级过程中，尤其是在使用 MySQL 数据库时，网关实例中偶尔会出现重复数据。 +* 修复了问题：删除自定义插件偶尔会失败。 + +## 3.5.1 版本 + +**发布日期：** 2025-02-06 + +### 缺陷修复 + +* 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。 +* 支持在 OTEL 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 + +## 3.5.0 版本 + +**发布日期：** 2025-01-27 + +### 新功能 + +#### 服务中的多个上游 + +对于高级场景，例如灰度部署、蓝绿部署或管理多个集群，服务现在可以使用多个上游。在这种情况下，默认上游充当大多数请求的主要目标，而其他上游可用于特定目的，例如将流量路由到灰度部署或辅助集群。有关详细信息，请参阅更新后的[配置灰度流量转移](./getting-started/canary-upstream.md)。 + +:::info + +旧的 **灰度规则** 功能不再可用。 + +::: + +### 功能优化 + +* 支持通过 Prometheus 插件元数据自定义配置 DP 指标标签。 +* 优化了数据平面 Prometheus 指标报告的性能。 +* 禁止由于超过许可证 CPU 限制而创建新资源。 +* 为 API7 门户的控制台页面添加了页面大小选择。 +* 支持 YAML/JSON 格式的插件配置。 +* 改进了上游健康检查配置的 UI。 +* [Beta] 为上游配置了 mTLS。API 支持当前可用。完整支持即将推出。 + +### 缺陷修复 + +* 修复了问题：[Traffic Split](https://docs.api7.ai/hub/traffic-split) 插件的 LRU 缓存对象创建函数导致客户端请求异常。 +* 将“启用/禁用插件”重命名为“新增/删除插件”以提高准确性。 + +## 3.4.1 版本 + +**发布日期：** 2025-01-14 + +### 缺陷修复 + +* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 +* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 + +## 3.4.0 版本 + +**发布日期：** 2025-01-07 + +### 新功能 + +#### SNI 管理 + +引入了 [SNI](./key-concepts/snis) 作为管理 TLS 和 mTLS 身份验证以及证书匹配的新机制。有关详细信息，请参阅 [在客户端和 API7 网关之间配置 mTLS](./api-security/client-mtls)。 + +#### API7 门户监控 + +提供监控数据和可视化，以跟踪 API 产品指标。 + +### 功能优化 + +* 自定义插件配置现在应用于网关组级别。有关详细信息，请参阅 [添加自定义插件](./best-practices/custom-plugin)。 +* 数据面升级到 LuaJit 2.1-20240815。 +* 删除了 `grpc-client-nginx-module`。 + +### 缺陷修复 + +* 修复了问题：Redis 延迟同步功能使用的共享内存泄漏。 +* 修复了问题：批量发布超多 service 时审计日志记录失败。 + +## 3.3.3 版本 + +**发布日期：** 2025-01-14 + +### 缺陷修复 + +* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 +* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 + +## 3.3.2 版本 + +**发布日期：** 2024-12-24 + +### 缺陷修复 + +* 修复了问题：从 3.2.16.2 或更旧版本升级到 3.3.1 及更高版本时，控制台无法启动。 + +## 3.3.1 版本 + +**发布日期：** 2024-12-19 + +### 缺陷修复 + +* 修复了问题：运行在 rewrite 阶段的插件在命中消费者后会重复执行。 + +## 3.3.0 版本 + +**发布日期：** 2024-12-16 + +### 新功能 + +#### API7 门户 + +宣布 API7 门户正式发布 (GA)，这是一个用于 API 发现和使用的综合解决方案。探索 [API7 门户](./key-concepts/api-portal) 和 [开发者](./key-concepts/developers) 的关键概念，并开始你的 [服务产品化](./api-portal/productize-services.md) 之旅。 + +### 功能优化 + +* 为 [OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件同步了开源代码。 +* 在访问日志和错误日志中记录请求 ID。 +* 重构了数据面中的过期和淘汰机制。 +* 当告警策略未配置通知通道时，在告警历史记录中添加了提示。 +* 支持与外部 Prometheus 指标集成。 + +### 安全 + +* 解决了 CVE 报告中的漏洞。 + +### 缺陷修复 + +* 解决了问题：数据面到 DPM 的消费者查询（404 错误除外）不应被缓存。 +* 解决了问题：禁用 API7 集成身份验证后，登录页面上的密码登录不可用。 +* 修复了插件全局规则搜索问题。 + +## 3.2.16.7 版本 + +**发布日期：** 2024-12-13 + +### 缺陷修复 + +* 修复了问题：当 DP 管理器收到截断的 Prometheus 指标时，它会进入无限循环。 +* 修复了问题：由于 watch 中断，数据面与控制面的同步可能会中断。 +* 修复了问题：速率限制插件的 Redis 延迟同步功能对于低频请求无法按预期工作。 +* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件使用的共享内存存在故障。 +* 修复了问题：`radixtree_uri_with_parameter` 无法匹配包含带有特殊字符的路径参数的请求。 +* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件滑动窗口中的剩余值应向下舍入，重置值应保留两位小数。 + +## 3.2.16.6 版本 + +**发布日期：** 2024-11-25 + +### 功能优化 + +* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件支持 `key_claim_name`。 +* 为监控添加了网关组过滤。 + +### 缺陷修复 + +* 解决了告警页面中的 UI 问题。 +* 解决了问题：多个数据面容器在控制面中被识别为单个实例，这损害了许可证控制功能和一些指标报告显示功能。 +* 解决了问题：发布大量服务时，审计日志无法记录。 +* 修改了 SSL 证书到期告警条件文本。 +* 解决了问题：由于节点 IP 地址未更新，导致健康检查失败。 +* 将插件中 Lua 代码合法性的验证添加到控制面代码中。 +* 为 [Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件添加了子插件错误消息的记录。 +* 删除了 [Basic Auth](https://docs.api7.ai/hub/basic-auth) 插件中的额外警告日志。 +* 修复了添加新凭据时 Secret 提供商的权限验证错误。 +* 修复了问题：在网关组上添加的已发布服务缺少 `skip path prefix` 配置项。 + +## 3.2.16.5 版本 + +**发布日期：** 2024-11-21 + +### 功能优化 + +* 为 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件添加了 `multipart content type`。 +* 将资源 ID 长度限制从 64 调整为 256。 +* [Workflow](https://docs.api7.ai/hub/workflow) 插件支持 `limit-count-advanced` 作为操作项。 +* 重构了 `core.response.exit` 以阐明参数定义。 +* 在请求上下文中记录已执行的插件，以确保在使用 [Workflow](https://docs.api7.ai/hub/workflow) 插件时，同一插件仅被执行一次。 + +### 缺陷修复 + +* 解决了问题：在 [Prometheus](https://docs.api7.ai/hub/prometheus) 插件中启用 `prefer_name` 选项将导致监控页面上的过滤器发生故障。 +* 解决了问题：匹配匿名消费者时，不会将 `x-consumer-custom-id` 标头添加到请求中。 +* 解决了问题：当同时配置时，[Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件和 [CORS](https://docs.api7.ai/hub/cors) 插件会导致 OPTIONS 请求出错。 +* 临时删除了 [Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件中的沙箱机制。 + +## 3.2.16.4 版本 + +**发布日期：** 2024-11-01 + +### 新功能 + +#### 通过电子邮件发送通知 + +告警策略现在可以通过利用新的`联系人`同时通过 webhook 和电子邮件发送通知。_联系人_ 定义了一组可由多个告警策略使用的电子邮件地址或 webhook URL。 + +有关说明，请参阅[触发网关告警](./api-observability/alert)。 + +:::note + +现有的 `Webhook 模板` 将迁移到新的联系人和告警策略内的通知，确保告警策略的无缝过渡和向后兼容性。 + +::: + +#### 新的 Limit Count Advanced 插件 + +使用滑动窗口算法增强了开源的 limit count 插件，以实现更准确的速率限制。 + +有关详细信息，请参阅 [Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced)插件。 + +#### 新的 Exit Transformer 插件 + +[Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件支持根据 APISIX 插件返回的状态码、标头和正文来自定义网关响应。当配置为全局插件时，它还支持在请求不存在的路由时自定义响应。 + +#### 通过告警策略计算网关组中的健康网关实例数 + +如果网关组中健康网关实例的数量低于临界阈值，则表明可能会出现服务中断并影响流量处理。 +这种情况在 Kubernetes 部署中尤其重要，因为网关实例可能会遇到故障或意外缩减。 + +[创建用于统计网关组中健康网关实例数的告警策略](./api-observability/alert.md#count-healthy-gateway-instances-in-a-gateway-group) 并向相关人员发送通知。 + +### 功能优化 + +* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件 现在支持更多算法。 +* 支持利用表达式匹配来更精确地路由流量。 +* 在 [Grafana 控制台模板](https://grafana.com/grafana/dashboards/11719-apache-apisix/) 中丰富了更多指标。 +* 允许用户按 Enter 键登录。 + +### 缺陷修复 + +* 解决了问题：[CORS](https://docs.api7.ai/hub/cors)插件 `expose_header` 的默认值不应为 `*`。 +* 解决了问题：添加四层服务时可以成功添加第一个四层路由。 +* 解决了问题：`max_req_body_bytes` 限制在日志记录器插件中不起作用。 +* 解决了问题：[Limit Count](https://docs.api7.ai/hub/limit-count) 插件中速率限制参数的动态更新现在会反映在数据面中。 +* 解决了问题：通过 API 删除的服务可以从数据面中一致地删除。 + +## 3.2.16.3 版本 + +**发布日期：** 2024-10-21 + +### 新功能 + +#### 引用在 AWS Secrets Manager 中的密钥（Secrets） + +*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 + +有关更多详细信息，请参阅 [引用在 AWS Secrets Manager 中的密钥](./api-security/aws-secrets-manager.md)。 + +#### 用于 API 身份验证的匿名消费者 + +匿名消费者无需身份验证，但可以限制访问速率。你可以在服务/路由上的身份验证插件中配置匿名消费者，然后与速率限制插件结合使用。 + +有关详细信息，请参阅以下文档： + +* [对匿名消费者进行速率限制](./api-security/rate-limiting.md#add-an-anonymous-consumer) + +#### 安全 + +* 在数据面上添加了用于自身健康检查的状态接口。有关详细信息，请参阅 [启用数据面健康检查以实现高可用性](./high-availability/high-availability-installation.md#health-check)。 + +### 功能优化 + +* 支持 200 万量级消费者。 +* 消费者列表支持按名称排序。 +* 从 API7 网关中删除了 `conf_server`。 +* 改进了速率限制相关插件以使其更加灵活，允许针对每个服务/路由进行特定于消费者的速率限制。有关详细信息，请参阅 [Limit Count](https://docs.api7.ai/hub/limit-count) 插件 和 [Limit Req](https://docs.api7.ai/hub/limit-req) 插件。 +* 升级请求和响应转换插件： + * 在请求转换期间，支持传递 Lua 代码以获取值。 + * 对齐 Kong 的请求转换和响应转换的功能。 +* 显示服务中添加的路由总数。 +* 将插件列表从数据面配置更改为控制面配置。**与 3.2.15.0 以下版本不兼容** +* 在告警策略中添加了证书到期提醒。 +* 在因多设备登录而重定向到登录页面之前显示通知，说明登出原因。 +* 改善了前端页面响应速度和加载速度。 +* 优化了“使用上游超时”UI。 +* 优化了 API7 Portal (Beta) 列表页渲染速度。 + +### 缺陷修复 + +* 解决了问题：现在可以在控制台上为单个路由配置多个路径。 +* 解决了问题：[OpenTelemetry](https://docs.api7.ai/hub/opentelemetry) 插件不支持 `set_ngx_var`。 +* 解决了问题：[ACL](https://docs.api7.ai/hub/acl) 插件 在正常使用情况下不应输出警告日志。 +* 增强了数据面 `lua_ssl_trusted_certificate` 配置项。 +* 将 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件代码与 APISIX 主线版本同步。 +* 解决了问题：当在服务上配置了流模块不可用的插件时，数据面会打印错误日志。 +* 将 Token 的 `Edit` 操作更改为 `Edit Name`。 +* 解决了问题：编辑服务注册中心时，服务发现类型与表单不符。 + +## 3.2.16.2 版本 + +**发布日期：** 2024-10-11 + +### 缺陷修复 + +* 修复了消费者中插件配置更新不生效的问题。 + +## 3.2.16.1 版本 + +**发布日期：** 2024-10-04 + +### 功能优化 + +* 提升了 API7 Portal(Beta) 性能。 + +### 缺陷修复 + +* 解决了删除路由时 `radixtree_host_uri` 路由模式下的 panic 问题。 +* 解决了自定义认证类型插件与[Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件不兼容的问题。 + +## 3.2.16.0 版本 + +**发布日期：** 2024-09-30 + +### 新功能 + +#### 引用在 HashiCorp Vault 中的密钥 + +:::info + +这是一项不兼容变更。`secrets` 资源已重命名为 `secret provider（Secret 提供商）`，以符合最佳实践并促进与外部密钥管理工具的集成。所有相关的 API 都已相应更新。 + +::: + +*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 + +有关更多详细信息，请参阅 [在 HashiCorp Vault 中引用密钥](./api-security/hashicorp-vault.md)。 + +### 功能优化 + +* 【不兼容变更】**删除了 JWT 插件签发令牌的功能，并删除了上传私钥的功能。** 有关详细信息，请参阅 JWT Auth 插件文档。 +* 增加了对删除离线网关实例的支持。 +* 为使用 Redis 的插件添加了 `sync_rate` 参数，以控制与 Redis 同步计数器的频率。实时同步会给 Redis 带来很大的压力。 +* 支持通过 URL 访问特定的路由详情页。 +* 支持 API7 Portal(Beta) 的 API 在线测试。 +* UI 改进：缩短了自定义主机输入框。 +* UI 改进：将负载均衡算法下拉框改为单选框。 +* UI 改进：新建标签样式修改。 + +### 缺陷修复 + +* 修复了问题：未正确清理的 `config_listen.sock` 导致数据面无法启动。 +* 修复了问题：禁用服务后请求接口报 `404` 错误。 +* 为 [Splunk-Hec-Logging](https://docs.api7.ai/hub/splunk-hec-logging) 插件添加了 `keepalive_timeout` 配置。 +* 修复了消费者的标签分割后各元素还保留分隔符前后的空白问题。 +* 修复了问题：[Skywalking](https://docs.api7.ai/hub/skywalking) 插件销毁后无法重新启动。 +* 修复了问题：数据面没有正确处理非认证插件配置在消费者上时的加解密。 +* 修复了问题：内置权限策略应无法删除。 +* 修复了问题：ingress controller 类型网关组应能够删除。 +* 修复了问题：数据面 path prefix 应当支持配置 `/`。 +* 修复了 UI 问题：点击标签页面跳转到搜索框。 +* 修复了 UI 问题：新建令牌并删除令牌后，新建提示没有消失。 +* 为插件分类添加了中文翻译。 +* 扩大了插件描述文字框，以完整显示插件的介绍。 +* 修复了新建令牌并删除令牌后，新建提示没有消失的问题。 + + +## 3.2.15.2 版本 + +**发布日期：** 2024-09-19 + +### 缺陷修复 + +* 调整 [Attach Consumer Label](https://docs.api7.ai/hub/attach-consumer-label) 插件到 `before_proxy` 阶段执行。 + +## 3.2.15.1 版本 + +**发布日期：** 2024-09-18 + +### 缺陷修复 + +* 解决了使用令牌获取 `instance_token` 返回 401 的问题。 + +## 3.2.15.0 版本 + +**发布日期：** 2024-09-14 + +### 新功能 + +#### 消费者凭据 + +:::info + +这是一项不兼容变更。不再支持为消费者创建新的身份验证插件（Key Auth、Basic Auth、JWT Auth 或 HMAC Auth）。请改用消费者凭据。现有的插件配置将保持可访问和可编辑，直到被禁用。 + +::: + +消费者凭据通过允许多个凭据对应每个消费者来增强灵活性。它们取代了传统的身份验证插件，如 [Key Auth](https://docs.api7.ai/hub/key-auth)、[Basic Auth](https://docs.api7.ai/hub/basic-auth)、[JWT Auth](https://docs.api7.ai/hub/jwt-auth) 和 [HMAC Auth](https://docs.api7.ai/hub/hmac-auth)，提供了更友好的用户体验。有关详细信息，请参阅[管理消费者凭据](./api-consumption/manage-consumer-credentials.md)。 + +### 安全 + +* 根用户 `admin` 成为受保护帐户，角色、权限策略或其他用户无法对其进行修改。其他用户无法删除它或重置其密码。 + +### 功能优化 + +* 现在支持按名称按字母顺序对服务列表进行排序。 +* 向每个审计日志添加了网关组 ID，以便你可以按网关组搜索或过滤审计日志。 +* 为已离线超过 7 天的自动删除的网关实例记录了审计日志。 +* 支持按标签过滤网关组上发布的服务。 +* 确保控制面地址不以斜杠结尾。 +* 在 Helm 中支持注释。 +* 提供配置项控制数据面心跳、遥测请求的超时，并且调整默认值为 30s。 + +### 缺陷修复 + +* 优化了在启用 SCIM 后用户通过 SSO 登录但系统中不存在该用户时的错误消息。 +* 修复了修改未发布版本的服务后灰度配置调整失败的问题。 + +## 3.2.14.4 版本 + +**发布日期：** 2024-08-14 + +### 新功能 + +#### 覆盖每个路由的上游超时 + +API7 网关允许为各个路由配置不同的上游超时，以覆盖上游侧的超时配置，从而实现对请求处理的精细控制。 + +#### 用户权限边界 + +权限边界定义了用户的最大允许权限，作为防止用户越权的保障措施。 + +### 安全提升 + +* 升级了前端依赖项。 +* 确保单设备登录 - 新登录将撤销之前存在的活跃会话。 +* 禁止导入旧许可证。 +* 升级了 OpenResty 版本以修复安全漏洞。 + +### 功能优化 + +* 在服务中心列表和已发布服务列表中添加了服务描述。 +* 为服务注册中心添加了“连接中”状态，以避免误解。 +* 自定义插件支持代码混淆和加密存储。 +* 在使用测试环境许可证时显示通知。 +* 为插件管理和修改实现了基于卡片的 UI。 +* 支持配置自定义插件元数据。 +* 最小化了 API7 企业版的镜像大小。 + +### 缺陷修复 + +* 修复了将服务版本发布到网关组时，服务运行时配置参数（例如，主机、路径前缀）的空值丢失的问题。 +* 消除了 dry-run 模式下调用许可证上传时生成的不必要的审计日志。 +* 解决了路由创建和修改时间戳不正确的问题。 +* 解决了插件元数据 Schema 的校验报错。 +* 提高了服务搜索准确性。 +* 解决了服务模板发布期间插件丢失的问题。 + +## 3.2.14.3 版本 + +**发布日期：** 2024-08-06 + +### 缺陷修复 + +* 支持在 SSL 证书中引用 `$env`。 +* 解决了标签包含句点时 UI 不稳定的问题。 + +## 3.2.14.2 版本 + +**发布日期：** 2024-07-30 + +### 缺陷修复 + +* 解决了在控制台上查看 Ingress Controller 路由时的报错。 +* 修复了在 Kubernetes 上安装网关实例时缺少默认 Helm release 名称的问题。 +* 通过使用 ID 令牌优化了与 Azure AD 的集成。 +* 修复了服务模板和已发布的网关组之间可能出现插件不一致的问题。 + +## 3.2.14.1 版本 + +**发布日期：** 2024-07-22 + +### 功能优化 + +#### 导入 OpenAPI 以在网关组上创建服务 + +只需将 OpenAPI 文件直接导入网关组，即可创建新服务及其所有路由。 + +#### 通过 API7 Portal 实现精细的访问控制 + +利用自定义角色和权限策略对 API 产品的访问进行精细控制。 + +#### 安全提升 + +* 控制面地址必须为 HTTPs。 +* 移除 `ngx.req.get_post_args(0)` 的使用，改用默认值以避免潜在的攻击。 +* 重新生成 Ingress Controller 部署脚本现在需要二次确认。 + +#### 无需版本控制即可管理已发布服务基础信息 + +现在可以修改服务名称/描述/标签，而无需发布新版本。 + +#### 服务设置期间首次创建路由 + +你可以选择从一开始就定义服务里的第一条初始路由，无需额外的步骤，简化了工作流程。 + +### 缺陷修复 + +* 将 [Datadog](https://docs.api7.ai/hub/datadog) 插件修复 (https://github.com/apache/apisix/pull/11354) 合并到 API7 企业版。 +* 修复了控制台上数据面不可见的问题。 +* 修复了一个问题：将 Prometheus 数据报告方法从远程写入更改为抓取后，服务注册表状态始终显示为“断开连接”。 +* 修复了通过控制台部署自定义插件后，数据面遇到错误的问题。 +* 修复了前端错误：不应该允许通过控制台在 Ingress Controller 网关组上修改已发布服务的上游。 +* 去掉不该出现的报错通知：切换到节点时，即使启用了健康检查，仍然存在提示用户启用健康检查的提示。 +* 修复问题：上传自定义插件时，如果出现解析错误，错误消息中显示的插件名称与实际文件名不匹配。 + +## 3.2.14.0 版本 + +**发布日期：** 2024-07-08 + +### 新功能 + +#### 全新的访问控制机制 + +:::info + +这是一项不兼容变更。旧版本的规则不能保留。 + +::: + +API7 企业版改进了传统的基于角色的权限，采用了权限策略架构，通过分配给角色的可复用策略来实现精细的访问控制。请参阅[角色和权限策略](./key-concepts/roles-and-permission-policies.md)。 + +### 功能优化 + +#### 配置路由优先级 + +在特定场景下，你可以在两个不同的服务中配置相同的路由。通过优先级确定哪个路由处理请求。具有较高指定优先级的路由将首先被使用。 + +#### 强化 mTLS 证书安全 + +改进了以下问题： + +- 过长的证书：证书字符串太长，应该缩短。 +- 不必要的标记：证书包含不必要的标记，应该删除。 +- 共享 CA：为多个证书使用相同的证书颁发机构 (CA) 是不安全的。 +- 证书不匹配处理：当发生证书不匹配时，握手应立即失败，拒绝客户端的请求，而不是继续进行进一步的验证。 + +#### 在 API7 Helm Chart 中包含新的参数 `lua_shared_dict` + +为 Helm chart 引入了一个新的参数。 + +### 缺陷修复 + +- 从旧版本升级可能会导致上游数据丢失或 404 错误。 +- 服务请求 URL 更新期间遇到 UI 错误。 +- 修复了 API7 Portal (Beta) 库问题。 +- 修复了 [HTTP Logger](https://docs.api7.ai/hub/http-logger) 插件内存泄漏。 +- 前端和后端密码策略不一致。 +- 当 GET 请求与任何路由都不匹配时，[Data Mask](https://docs.api7.ai/hub/data-mask) 插件会报告错误。 +- ApisixUpstream CRD 的 status 字段记录不正确。 +- 数据面支持配置监控数据的报告间隔。 +- 修复了配置插件元数据后的警告日志。 +- 修复了插件重新加载问题。 +- 减少 PostgreSQL 连接数。 +- 优化前端资源消耗。 +- 删除 FQDN 中的尾随点。 +- 插件元数据应该能够被删除。 + +## 3.2.11.8 版本 + +**发布日期：** 2024-06-26 + +### 缺陷修复 + +- 通过减少 etcd 调用来降低 API 延迟。 +- Kine 数据库连接池配置可以正常工作。 + +## 3.2.11.7 版本 + +**发布日期：** 2024-06-24 + +### 缺陷修复 + +- 提升 API 性能。 +- 数据面支持禁用遥测数据收集和配置报告间隔。 +- 自定义插件即使没有 schema 定义也可以正常工作。 + +## 3.2.11.6 版本 + +**发布日期：** 2024-06-24 + +### 缺陷修复 + +- 大数据集不再导致 etcd range API 错误。 + +## 3.2.13.0 版本 + +**发布日期：** 2024-06-19 + +### Admin API 不兼容变更 + +1. 服务模板 API 已迁移到 "/api/services/template" 路径前缀下。 + +- [服务模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services-Template) +- [路由模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes-Template) + +2. 原始的 "/apisix/admin/services" 端点现在需要 gateway_group_id 参数。 + +- [网关组上的服务 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services) +- [网关组上的路由 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes) + +### 新增功能 + +#### 在网关组上创建/更新服务而不发布 + +如果版本控制不是你的要求，你现在可以直接在网关组上创建服务。这些服务会立即生效，无需单独的发布步骤。这简化了部署过程并节省了时间。 + +但是，重要的是要考虑所涉及的权衡。通过绕过发布阶段，你也失去了轻松回滚到以前版本或跟踪版本更改的能力。 + +有关详细信息，请参阅最新的入门教程：[启动你的第一个 API](./getting-started/launch-your-first-api.md)。 + +#### 与 Ingress Controller 集成（UI 支持） + +API7 Gateway 正式推出 Ingress Controllers，这是一种新型的网关组。虽然控制台提供了方便的管理功能来创建和查看你的 Ingress Controller，但配置修改需要对任何配置更改采用声明方式。 + +### 功能优化 + +#### 搜索网关组名称并按标签过滤 + +使在网关组列表中查找所需的特定网关组变得更加容易。 + +#### 保护配置文件中的敏感数据 + +数据库的 DSN 配置（包括访问地址、用户名和密码）可以通过环境变量和 Helm 图表进行配置。 + +#### 支持 Prometheus 认证 + +Prometheus 远程写入现在支持 Basic Auth/mTLS。 + +#### 支持 SSL 变量的 Secret 功能 + +使用加密的 Secret 保护 `ssl.certs` 和 `ssl.keys`。 + +### 缺陷修复 + +- 设置标头后，`ctx.var` 变量将立即更新。 +- 无法上传重复的 SSL 证书。 + +## 3.2.11.5 版本 + +**发布日期：** 2024-06-18 + +### 缺陷修复 + +- ssl_verify 配置现在适用于登录选项 OIDC 和 LDAP 协议。 + +## 3.2.11.4 版本 + +**发布日期：** 2024-06-07 + +### 缺陷修复 + +- 保护与 API 相关的登录选项中的敏感字段。 + +## 版本 3.2.12.0 + +**发布日期**: 2024-05-24 + +### Admin API 不兼容变更 + +1. service status 字段从“0: 启用，1: 禁用”变更为“0: 禁用，1: 启用” + +- [Publish a service](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services/paths/~1api~1services~1publish/post) +- [Update service runtime configurations by ID](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/changeServiceRuntimeConfiguration) +- [Get all published services in Gateway Group](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/listPublishedService) + +2. consumer api 移除 id 字段，使用 gateway group id & username 做查询、删除 + +- [Consumers APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers) + +3. ssl 相关 api 强制 gateway group id 参数 + +- [SSL APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/SSLs) + +### 新增功能 + +#### 四层路由（Stream Route） + +API7 网关现在可以处理四层流量，比如与数据库或 Kafka 的连接。 添加一个四层类型的服务，并在其中添加若干个四层路由（Stream Route，即可[转发四层流量](./getting-started/proxy-l4-traffic.md)。 + +#### 自定义角色 (控制台支持) + +当默认提供的角色无法满足需求时，你可以自行设计自定义角色，实现精细化权限控制。可参阅[添加自定义角色](./getting-started/rbac.md) + +#### Ingress Controller（Beta 测试版，仅 API 支持） + +集成 Ingress Controller。 + +### 功能优化 + +#### 优化左侧导航菜单 + +- 用户登录后落地页改为网关组菜单中已发布服务。 +- **服务** 菜单项改名为 **服务中心**。 + +### 缺陷修复 + +- 使用 [Key Auth](https://docs.api7.ai/hub/key-auth) 插件时，禁止出现重复的 API 密钥。 +- 使用 [UA Restriction](https://docs.api7.ai/hub/ua-restriction) 插件时，允许同时配置黑名单和白名单。 +- 重置用户密码时不会引起访问令牌失效。 +- 使用 [Loggly](https://apisix.apache.org/zh/docs/apisix/plugins/loggly/) 插件时配置能校验成功。 +- API7 网关中的状态字段取值含义和 Apache APISIX 保持一致。 + +## 版本 3.2.11.3 + +**发布日期: 2024-05-20 + +### 缺陷修复 + +- etcd watch 可以正确地传递 SNI。 +- API7 企业版在安装时会先尝试创建新的数据库。如果没有对应权限导致失败，会使用预先指定的已有数据库，避免安装失败。 + +## 版本 3.2.11.2 + +**发布日期**: 2024-05-20 + +### 缺陷修复 + +- 标签支持最长 64 个字符，且可以包含空格。 +- 即使包含 schema 校验错误，也可以正常完成与数据面的配置同步，避免数据丢失或工作流中断。 + +## 版本 3.2.11.1 + +**发布日期**: 2024-05-08 + +### 新增功能 + +#### SSO 角色映射 + +设置自动角色映射，可以避免超级管理员需要频繁为 SSO 登陆的用户分配角色。 满足预先设置的映射条件的用户，在登陆 API7 企业版时会自动获得相应的角色权限。详情参阅[设置角色映射](./best-practices/sso.md#设置角色映射)。 + +#### SCIM 用户同步 + +使用 SCIM 用户同步协议简化 SSO 用户管理。它可以自动从所有支持了 SCIM 协议的、已经添加了登陆选项的身份提供商同步用户数据，确保用户信息一致性。新用户在身份提供商注册，或用户在身份提供商注销，API7 企业版即可得到及时通知，避免新用户无法登陆或已注销用户非法登陆。详情参阅[Sync User Data from IdP](./best-practices/sso.md#从身份提供商同步用户数据)。 + +#### 自定义角色 (Beta, 仅 API 支持) + +如默认角色不满足业务需求，现在你可以设计自定义角色，自由组合权限，进行细粒度权限控制。 +该功能即将在后续版本支持控制台配置。 + +### 功能优化 + +#### 升级到 OpenSSL 3 + +提升安全性，性能，和可靠性。 + +#### 全局插件执行顺序优化 + +为了简化全局插件的管理，API7 企业版 会将多个全局插件配置整合到一起，确保插件配置和执行顺序不会产生冲突。 + +### 缺陷修复 + +#### 前端补全 HTTP 协议检测 + +生成的网关实例部署脚本有时无法正确检测是否需要 HTTP 或 HTTPS 协议，这可能会导致部署时出现错误。 + +#### 上传 SSL 证书错误 + +为网关组 A 上传的 SSL 证书可能会意外分配给网关组 B。 + +#### 支持主机级动态设置 TLS 协议版本 + +同步集成了在 Apache APISIX 中已解决的问题。 + +## 版本 3.2.10.1 + +**发布日期**：2024-04-28 + +### 新增功能 + +#### 支持 MySQL 5.7 + +现在起 API7 企业版支持使用 MySQL 5.7 作为持久化数据存储。 + +## 版本 3.2.10.0 + +**发布日期**: 2024-04-22 + +### 不兼容变更 + +#### 令牌绑定用户 + +令牌改为和具体用户绑定，且和用户享有相同的角色权限。如果用户被删除，绑定的令牌也将立刻失效被删除。 + +## 版本 3.2.9.5 + +**发布日期**：2024-04-16 + +### 新增功能 + +#### 上游 mTLS（仅 API 支持） + +支持在 API7 网关和上游服务之间配置 mTLS 认证。 mTLS 是一种通信安全形式，要求双方彼此展示证书。这确保了双方都是其声称的身份，并且在它们之间传输的数据是加密的。 +该功能即将在后续版本支持控制台配置。 + +## 版本 3.2.9.4 + +**发布日期**: 2024-04-07 + +### 缺陷修复 + +#### CPU 核心数判断 + +修复了当 CPU 核心数达到最大限制时出现的问题。 + +## 版本 3.2.9.3 + +**发布日期**: 2024-04-03 + +### 新增功能 + +#### 集成 Vault(Beta) + +将敏感信息存储到 Vault中。仅支持通过 Admin API 使用，UI 使用即将推出。 + +## 版本 3.2.9.2 + +**发布日期**: 2024-04-01 + +### 新增功能 + +#### 支持 SAML 第三方登录 + +API7 企业版新增支持对接 SAML 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md)。 + +#### 新插件： Data Mask + +[Data Mask](https://docs.api7.ai/hub/data-mask) 插件提供了在请求头、请求体和 URL 查询中移除或替换敏感信息的能力。 + +### 功能优化 + +#### 忽略路径前缀 + +你可以选择在向上游发送请求时跳过路径前缀。这种调整对用户来说是不感知的，并且在使用不同的路径前缀来识别发送到不同网关组的 API 时可能很有用。 + +#### 优化健康检查配置 UI + +提供一个更直观友好的健康检查配置交互界面。 + +#### 升级加密算法 + +从 AES128 升级到 AES 256。 + +#### 性能提升 + +消除了禁用插件后带来的性能损耗。 + +## 版本 3.2.9.1 + +**发布日期*: 2024-03-19 + +### 新增功能 + +#### 支持自定义插件管理 + +API7 企业版支持上传你自行编写的自定义插件，以扩展 API 管理的功能。详情见[新增自定义插件](./best-practices/custom-plugin.md). + +#### 支持 OIDC 第三方登录 + +API7 企业版即 LDAP 之后，新增支持对接 OIDC 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md). + +#### 将服务标签作为 API 提供者授权范围 + +通过将服务标签作为为API提供者的范围，你可以授予他们访问带有特定标签的所有服务的权限。这将有助于减轻超级管理员的工作负担。通常，可以使用“部门”标签对服务进行分组。此后该部门的用户将能够访问属于该部门的所有服务。 + +## 版本 3.2.8.1 + +**发布日期**： 2024-02-08 + +### 新增功能 + +#### 支持 Nacos 服务发现 + +API7 企业版利用服务发现功能自动检测可用的上游服务，并将其地址保存在数据库（也被称之为服务注册中心）中。因此，API 网关能够通过服务注册中心获取最新的上游地址列表，确保所有请求都被转发到健康的上游节点。 + +在本版本中，API7 企业版支持与 Nacos 服务发现集成。用户可以使用 Nacos 服务发现来[发布服务](./getting-started/publish-service.md)和[在网关组之间同步服务](./getting-started/sync-service.md)。 + +#### 支持 LDAP SSO 登录 + +API7 企业版支持 LDAP 单点登录（Single Sign-On，SSO）。将 API7 企业版与 LDAP 集成后，用户可以直接使用 LDAP 用户名和密码登录 API7 控制台，创建和管理 API7 网关资源。有关如何配置 LDAP SSO 登录方法的具体信息，参见[配置 LDAP 单点登录](./best-practices/sso.md)。 + +#### 支持使用 Kubernetes 添加网关实例 + +用户使用网关实例来处理流量。在本版本中，API7 企业版支持使用 Kubernetes 向网关组添加网关实例。有关如何通过 Kubernetes 添加网关实例的具体信息，参见[添加网关实例](./getting-started/add-gateway-instance.md)。 From 5217da40541fc6f06c9081fc54e1fb4822dac994 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:24:35 +0800 Subject: [PATCH 06/24] Delete release-notes.md --- .../version-3.6.x/release-notes.md | 893 ------------------ 1 file changed, 893 deletions(-) delete mode 100644 enterprise_versioned_docs/version-3.6.x/release-notes.md diff --git a/enterprise_versioned_docs/version-3.6.x/release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-notes.md deleted file mode 100644 index 45003992..00000000 --- a/enterprise_versioned_docs/version-3.6.x/release-notes.md +++ /dev/null @@ -1,893 +0,0 @@ ---- -title: 更新日志 -slug: /release-notes ---- - -## 3.5.2 版本 - -**发布日期：** 2025-02-13 - -### 缺陷修复 - -* 修复了问题：无法启用 `log rotate` 插件。 -* 修复了问题：在升级过程中，尤其是在使用 MySQL 数据库时，网关实例中偶尔会出现重复数据。 -* 修复了问题：删除自定义插件偶尔会失败。 - -## 3.5.1 版本 - -**发布日期：** 2025-02-06 - -### 缺陷修复 - -* 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。 -* 支持在 OTEL 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 - -## 3.5.0 版本 - -**发布日期：** 2025-01-27 - -### 新功能 - -#### 服务中的多个上游 - -对于高级场景，例如灰度部署、蓝绿部署或管理多个集群，服务现在可以使用多个上游。在这种情况下，默认上游充当大多数请求的主要目标，而其他上游可用于特定目的，例如将流量路由到灰度部署或辅助集群。有关详细信息，请参阅更新后的[配置灰度流量转移](./getting-started/canary-upstream.md)。 - -:::info - -旧的 **灰度规则** 功能不再可用。 - -::: - -### 功能优化 - -* 支持通过 Prometheus 插件元数据自定义配置 DP 指标标签。 -* 优化了数据平面 Prometheus 指标报告的性能。 -* 禁止由于超过许可证 CPU 限制而创建新资源。 -* 为 API7 门户的控制台页面添加了页面大小选择。 -* 支持 YAML/JSON 格式的插件配置。 -* 改进了上游健康检查配置的 UI。 -* [Beta] 为上游配置了 mTLS。API 支持当前可用。完整支持即将推出。 - -### 缺陷修复 - -* 修复了问题：[Traffic Split](https://docs.api7.ai/hub/traffic-split) 插件的 LRU 缓存对象创建函数导致客户端请求异常。 -* 将“启用/禁用插件”重命名为“新增/删除插件”以提高准确性。 - -## 3.4.1 版本 - -**发布日期：** 2025-01-14 - -### 缺陷修复 - -* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 -* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 - -## 3.4.0 版本 - -**发布日期：** 2025-01-07 - -### 新功能 - -#### SNI 管理 - -引入了 [SNI](./key-concepts/snis) 作为管理 TLS 和 mTLS 身份验证以及证书匹配的新机制。有关详细信息，请参阅 [在客户端和 API7 网关之间配置 mTLS](./api-security/client-mtls)。 - -#### API7 门户监控 - -提供监控数据和可视化，以跟踪 API 产品指标。 - -### 功能优化 - -* 自定义插件配置现在应用于网关组级别。有关详细信息，请参阅 [添加自定义插件](./best-practices/custom-plugin)。 -* 数据面升级到 LuaJit 2.1-20240815。 -* 删除了 `grpc-client-nginx-module`。 - -### 缺陷修复 - -* 修复了问题：Redis 延迟同步功能使用的共享内存泄漏。 -* 修复了问题：批量发布超多 service 时审计日志记录失败。 - -## 3.3.3 版本 - -**发布日期：** 2025-01-14 - -### 缺陷修复 - -* 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。 -* 修复了问题：在 DP 中配置 `access_log_format` 并将 `access_log_format_escape` 设置为 `json` 时，结果会附加一个额外的 `request_id`。 - -## 3.3.2 版本 - -**发布日期：** 2024-12-24 - -### 缺陷修复 - -* 修复了问题：从 3.2.16.2 或更旧版本升级到 3.3.1 及更高版本时，控制台无法启动。 - -## 3.3.1 版本 - -**发布日期：** 2024-12-19 - -### 缺陷修复 - -* 修复了问题：运行在 rewrite 阶段的插件在命中消费者后会重复执行。 - -## 3.3.0 版本 - -**发布日期：** 2024-12-16 - -### 新功能 - -#### API7 门户 - -宣布 API7 门户正式发布 (GA)，这是一个用于 API 发现和使用的综合解决方案。探索 [API7 门户](./key-concepts/api-portal) 和 [开发者](./key-concepts/developers) 的关键概念，并开始你的 [服务产品化](./api-portal/productize-services.md) 之旅。 - -### 功能优化 - -* 为 [OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件同步了开源代码。 -* 在访问日志和错误日志中记录请求 ID。 -* 重构了数据面中的过期和淘汰机制。 -* 当告警策略未配置通知通道时，在告警历史记录中添加了提示。 -* 支持与外部 Prometheus 指标集成。 - -### 安全 - -* 解决了 CVE 报告中的漏洞。 - -### 缺陷修复 - -* 解决了问题：数据面到 DPM 的消费者查询（404 错误除外）不应被缓存。 -* 解决了问题：禁用 API7 集成身份验证后，登录页面上的密码登录不可用。 -* 修复了插件全局规则搜索问题。 - -## 3.2.16.7 版本 - -**发布日期：** 2024-12-13 - -### 缺陷修复 - -* 修复了问题：当 DP 管理器收到截断的 Prometheus 指标时，它会进入无限循环。 -* 修复了问题：由于 watch 中断，数据面与控制面的同步可能会中断。 -* 修复了问题：速率限制插件的 Redis 延迟同步功能对于低频请求无法按预期工作。 -* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件使用的共享内存存在故障。 -* 修复了问题：`radixtree_uri_with_parameter` 无法匹配包含带有特殊字符的路径参数的请求。 -* 修复了问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件滑动窗口中的剩余值应向下舍入，重置值应保留两位小数。 - -## 3.2.16.6 版本 - -**发布日期：** 2024-11-25 - -### 功能优化 - -* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件支持 `key_claim_name`。 -* 为监控添加了网关组过滤。 - -### 缺陷修复 - -* 解决了告警页面中的 UI 问题。 -* 解决了问题：多个数据面容器在控制面中被识别为单个实例，这损害了许可证控制功能和一些指标报告显示功能。 -* 解决了问题：发布大量服务时，审计日志无法记录。 -* 修改了 SSL 证书到期告警条件文本。 -* 解决了问题：由于节点 IP 地址未更新，导致健康检查失败。 -* 将插件中 Lua 代码合法性的验证添加到控制面代码中。 -* 为 [Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件添加了子插件错误消息的记录。 -* 删除了 [Basic Auth](https://docs.api7.ai/hub/basic-auth) 插件中的额外警告日志。 -* 修复了添加新凭据时 Secret 提供商的权限验证错误。 -* 修复了问题：在网关组上添加的已发布服务缺少 `skip path prefix` 配置项。 - -## 3.2.16.5 版本 - -**发布日期：** 2024-11-21 - -### 功能优化 - -* 为 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件添加了 `multipart content type`。 -* 将资源 ID 长度限制从 64 调整为 256。 -* [Workflow](https://docs.api7.ai/hub/workflow) 插件支持 `limit-count-advanced` 作为操作项。 -* 重构了 `core.response.exit` 以阐明参数定义。 -* 在请求上下文中记录已执行的插件，以确保在使用 [Workflow](https://docs.api7.ai/hub/workflow) 插件时，同一插件仅被执行一次。 - -### 缺陷修复 - -* 解决了问题：在 [Prometheus](https://docs.api7.ai/hub/prometheus) 插件中启用 `prefer_name` 选项将导致监控页面上的过滤器发生故障。 -* 解决了问题：匹配匿名消费者时，不会将 `x-consumer-custom-id` 标头添加到请求中。 -* 解决了问题：当同时配置时，[Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件和 [CORS](https://docs.api7.ai/hub/cors) 插件会导致 OPTIONS 请求出错。 -* 临时删除了 [Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件中的沙箱机制。 - -## 3.2.16.4 版本 - -**发布日期：** 2024-11-01 - -### 新功能 - -#### 通过电子邮件发送通知 - -告警策略现在可以通过利用新的`联系人`同时通过 webhook 和电子邮件发送通知。_联系人_ 定义了一组可由多个告警策略使用的电子邮件地址或 webhook URL。 - -有关说明，请参阅[触发网关告警](./api-observability/alert)。 - -:::note - -现有的 `Webhook 模板` 将迁移到新的联系人和告警策略内的通知，确保告警策略的无缝过渡和向后兼容性。 - -::: - -#### 新的 Limit Count Advanced 插件 - -使用滑动窗口算法增强了开源的 limit count 插件，以实现更准确的速率限制。 - -有关详细信息，请参阅 [Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced)插件。 - -#### 新的 Exit Transformer 插件 - -[Exit Transformer](https://docs.api7.ai/hub/exit-transformer) 插件支持根据 APISIX 插件返回的状态码、标头和正文来自定义网关响应。当配置为全局插件时，它还支持在请求不存在的路由时自定义响应。 - -#### 通过告警策略计算网关组中的健康网关实例数 - -如果网关组中健康网关实例的数量低于临界阈值，则表明可能会出现服务中断并影响流量处理。 -这种情况在 Kubernetes 部署中尤其重要，因为网关实例可能会遇到故障或意外缩减。 - -[创建用于统计网关组中健康网关实例数的告警策略](./api-observability/alert.md#count-healthy-gateway-instances-in-a-gateway-group) 并向相关人员发送通知。 - -### 功能优化 - -* [JWT Auth](https://docs.api7.ai/hub/jwt-auth) 插件 现在支持更多算法。 -* 支持利用表达式匹配来更精确地路由流量。 -* 在 [Grafana 控制台模板](https://grafana.com/grafana/dashboards/11719-apache-apisix/) 中丰富了更多指标。 -* 允许用户按 Enter 键登录。 - -### 缺陷修复 - -* 解决了问题：[CORS](https://docs.api7.ai/hub/cors)插件 `expose_header` 的默认值不应为 `*`。 -* 解决了问题：添加四层服务时可以成功添加第一个四层路由。 -* 解决了问题：`max_req_body_bytes` 限制在日志记录器插件中不起作用。 -* 解决了问题：[Limit Count](https://docs.api7.ai/hub/limit-count) 插件中速率限制参数的动态更新现在会反映在数据面中。 -* 解决了问题：通过 API 删除的服务可以从数据面中一致地删除。 - -## 3.2.16.3 版本 - -**发布日期：** 2024-10-21 - -### 新功能 - -#### 引用在 AWS Secrets Manager 中的密钥（Secrets） - -*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 - -有关更多详细信息，请参阅 [引用在 AWS Secrets Manager 中的密钥](./api-security/aws-secrets-manager.md)。 - -#### 用于 API 身份验证的匿名消费者 - -匿名消费者无需身份验证，但可以限制访问速率。你可以在服务/路由上的身份验证插件中配置匿名消费者，然后与速率限制插件结合使用。 - -有关详细信息，请参阅以下文档： - -* [对匿名消费者进行速率限制](./api-security/rate-limiting.md#add-an-anonymous-consumer) - -#### 安全 - -* 在数据面上添加了用于自身健康检查的状态接口。有关详细信息，请参阅 [启用数据面健康检查以实现高可用性](./high-availability/high-availability-installation.md#health-check)。 - -### 功能优化 - -* 支持 200 万量级消费者。 -* 消费者列表支持按名称排序。 -* 从 API7 网关中删除了 `conf_server`。 -* 改进了速率限制相关插件以使其更加灵活，允许针对每个服务/路由进行特定于消费者的速率限制。有关详细信息，请参阅 [Limit Count](https://docs.api7.ai/hub/limit-count) 插件 和 [Limit Req](https://docs.api7.ai/hub/limit-req) 插件。 -* 升级请求和响应转换插件： - * 在请求转换期间，支持传递 Lua 代码以获取值。 - * 对齐 Kong 的请求转换和响应转换的功能。 -* 显示服务中添加的路由总数。 -* 将插件列表从数据面配置更改为控制面配置。**与 3.2.15.0 以下版本不兼容** -* 在告警策略中添加了证书到期提醒。 -* 在因多设备登录而重定向到登录页面之前显示通知，说明登出原因。 -* 改善了前端页面响应速度和加载速度。 -* 优化了“使用上游超时”UI。 -* 优化了 API7 Portal (Beta) 列表页渲染速度。 - -### 缺陷修复 - -* 解决了问题：现在可以在控制台上为单个路由配置多个路径。 -* 解决了问题：[OpenTelemetry](https://docs.api7.ai/hub/opentelemetry) 插件不支持 `set_ngx_var`。 -* 解决了问题：[ACL](https://docs.api7.ai/hub/acl) 插件 在正常使用情况下不应输出警告日志。 -* 增强了数据面 `lua_ssl_trusted_certificate` 配置项。 -* 将 [Body Transformer](https://docs.api7.ai/hub/body-transformer) 插件代码与 APISIX 主线版本同步。 -* 解决了问题：当在服务上配置了流模块不可用的插件时，数据面会打印错误日志。 -* 将 Token 的 `Edit` 操作更改为 `Edit Name`。 -* 解决了问题：编辑服务注册中心时，服务发现类型与表单不符。 - -## 3.2.16.2 版本 - -**发布日期：** 2024-10-11 - -### 缺陷修复 - -* 修复了消费者中插件配置更新不生效的问题。 - -## 3.2.16.1 版本 - -**发布日期：** 2024-10-04 - -### 功能优化 - -* 提升了 API7 Portal(Beta) 性能。 - -### 缺陷修复 - -* 解决了删除路由时 `radixtree_host_uri` 路由模式下的 panic 问题。 -* 解决了自定义认证类型插件与[Multi Auth](https://docs.api7.ai/hub/multi-auth) 插件不兼容的问题。 - -## 3.2.16.0 版本 - -**发布日期：** 2024-09-30 - -### 新功能 - -#### 引用在 HashiCorp Vault 中的密钥 - -:::info - -这是一项不兼容变更。`secrets` 资源已重命名为 `secret provider（Secret 提供商）`，以符合最佳实践并促进与外部密钥管理工具的集成。所有相关的 API 都已相应更新。 - -::: - -*密钥（Secrets）* 对象是一条需要防止未经授权访问的敏感信息，而 *Secret 提供商（Secret Provider）* 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。 - -有关更多详细信息，请参阅 [在 HashiCorp Vault 中引用密钥](./api-security/hashicorp-vault.md)。 - -### 功能优化 - -* 【不兼容变更】**删除了 JWT 插件签发令牌的功能，并删除了上传私钥的功能。** 有关详细信息，请参阅 JWT Auth 插件文档。 -* 增加了对删除离线网关实例的支持。 -* 为使用 Redis 的插件添加了 `sync_rate` 参数，以控制与 Redis 同步计数器的频率。实时同步会给 Redis 带来很大的压力。 -* 支持通过 URL 访问特定的路由详情页。 -* 支持 API7 Portal(Beta) 的 API 在线测试。 -* UI 改进：缩短了自定义主机输入框。 -* UI 改进：将负载均衡算法下拉框改为单选框。 -* UI 改进：新建标签样式修改。 - -### 缺陷修复 - -* 修复了问题：未正确清理的 `config_listen.sock` 导致数据面无法启动。 -* 修复了问题：禁用服务后请求接口报 `404` 错误。 -* 为 [Splunk-Hec-Logging](https://docs.api7.ai/hub/splunk-hec-logging) 插件添加了 `keepalive_timeout` 配置。 -* 修复了消费者的标签分割后各元素还保留分隔符前后的空白问题。 -* 修复了问题：[Skywalking](https://docs.api7.ai/hub/skywalking) 插件销毁后无法重新启动。 -* 修复了问题：数据面没有正确处理非认证插件配置在消费者上时的加解密。 -* 修复了问题：内置权限策略应无法删除。 -* 修复了问题：ingress controller 类型网关组应能够删除。 -* 修复了问题：数据面 path prefix 应当支持配置 `/`。 -* 修复了 UI 问题：点击标签页面跳转到搜索框。 -* 修复了 UI 问题：新建令牌并删除令牌后，新建提示没有消失。 -* 为插件分类添加了中文翻译。 -* 扩大了插件描述文字框，以完整显示插件的介绍。 -* 修复了新建令牌并删除令牌后，新建提示没有消失的问题。 - - -## 3.2.15.2 版本 - -**发布日期：** 2024-09-19 - -### 缺陷修复 - -* 调整 [Attach Consumer Label](https://docs.api7.ai/hub/attach-consumer-label) 插件到 `before_proxy` 阶段执行。 - -## 3.2.15.1 版本 - -**发布日期：** 2024-09-18 - -### 缺陷修复 - -* 解决了使用令牌获取 `instance_token` 返回 401 的问题。 - -## 3.2.15.0 版本 - -**发布日期：** 2024-09-14 - -### 新功能 - -#### 消费者凭据 - -:::info - -这是一项不兼容变更。不再支持为消费者创建新的身份验证插件（Key Auth、Basic Auth、JWT Auth 或 HMAC Auth）。请改用消费者凭据。现有的插件配置将保持可访问和可编辑，直到被禁用。 - -::: - -消费者凭据通过允许多个凭据对应每个消费者来增强灵活性。它们取代了传统的身份验证插件，如 [Key Auth](https://docs.api7.ai/hub/key-auth)、[Basic Auth](https://docs.api7.ai/hub/basic-auth)、[JWT Auth](https://docs.api7.ai/hub/jwt-auth) 和 [HMAC Auth](https://docs.api7.ai/hub/hmac-auth)，提供了更友好的用户体验。有关详细信息，请参阅[管理消费者凭据](./api-consumption/manage-consumer-credentials.md)。 - -### 安全 - -* 根用户 `admin` 成为受保护帐户，角色、权限策略或其他用户无法对其进行修改。其他用户无法删除它或重置其密码。 - -### 功能优化 - -* 现在支持按名称按字母顺序对服务列表进行排序。 -* 向每个审计日志添加了网关组 ID，以便你可以按网关组搜索或过滤审计日志。 -* 为已离线超过 7 天的自动删除的网关实例记录了审计日志。 -* 支持按标签过滤网关组上发布的服务。 -* 确保控制面地址不以斜杠结尾。 -* 在 Helm 中支持注释。 -* 提供配置项控制数据面心跳、遥测请求的超时，并且调整默认值为 30s。 - -### 缺陷修复 - -* 优化了在启用 SCIM 后用户通过 SSO 登录但系统中不存在该用户时的错误消息。 -* 修复了修改未发布版本的服务后灰度配置调整失败的问题。 - -## 3.2.14.4 版本 - -**发布日期：** 2024-08-14 - -### 新功能 - -#### 覆盖每个路由的上游超时 - -API7 网关允许为各个路由配置不同的上游超时，以覆盖上游侧的超时配置，从而实现对请求处理的精细控制。 - -#### 用户权限边界 - -权限边界定义了用户的最大允许权限，作为防止用户越权的保障措施。 - -### 安全提升 - -* 升级了前端依赖项。 -* 确保单设备登录 - 新登录将撤销之前存在的活跃会话。 -* 禁止导入旧许可证。 -* 升级了 OpenResty 版本以修复安全漏洞。 - -### 功能优化 - -* 在服务中心列表和已发布服务列表中添加了服务描述。 -* 为服务注册中心添加了“连接中”状态，以避免误解。 -* 自定义插件支持代码混淆和加密存储。 -* 在使用测试环境许可证时显示通知。 -* 为插件管理和修改实现了基于卡片的 UI。 -* 支持配置自定义插件元数据。 -* 最小化了 API7 企业版的镜像大小。 - -### 缺陷修复 - -* 修复了将服务版本发布到网关组时，服务运行时配置参数（例如，主机、路径前缀）的空值丢失的问题。 -* 消除了 dry-run 模式下调用许可证上传时生成的不必要的审计日志。 -* 解决了路由创建和修改时间戳不正确的问题。 -* 解决了插件元数据 Schema 的校验报错。 -* 提高了服务搜索准确性。 -* 解决了服务模板发布期间插件丢失的问题。 - -## 3.2.14.3 版本 - -**发布日期：** 2024-08-06 - -### 缺陷修复 - -* 支持在 SSL 证书中引用 `$env`。 -* 解决了标签包含句点时 UI 不稳定的问题。 - -## 3.2.14.2 版本 - -**发布日期：** 2024-07-30 - -### 缺陷修复 - -* 解决了在控制台上查看 Ingress Controller 路由时的报错。 -* 修复了在 Kubernetes 上安装网关实例时缺少默认 Helm release 名称的问题。 -* 通过使用 ID 令牌优化了与 Azure AD 的集成。 -* 修复了服务模板和已发布的网关组之间可能出现插件不一致的问题。 - -## 3.2.14.1 版本 - -**发布日期：** 2024-07-22 - -### 功能优化 - -#### 导入 OpenAPI 以在网关组上创建服务 - -只需将 OpenAPI 文件直接导入网关组，即可创建新服务及其所有路由。 - -#### 通过 API7 Portal 实现精细的访问控制 - -利用自定义角色和权限策略对 API 产品的访问进行精细控制。 - -#### 安全提升 - -* 控制面地址必须为 HTTPs。 -* 移除 `ngx.req.get_post_args(0)` 的使用，改用默认值以避免潜在的攻击。 -* 重新生成 Ingress Controller 部署脚本现在需要二次确认。 - -#### 无需版本控制即可管理已发布服务基础信息 - -现在可以修改服务名称/描述/标签，而无需发布新版本。 - -#### 服务设置期间首次创建路由 - -你可以选择从一开始就定义服务里的第一条初始路由，无需额外的步骤，简化了工作流程。 - -### 缺陷修复 - -* 将 [Datadog](https://docs.api7.ai/hub/datadog) 插件修复 (https://github.com/apache/apisix/pull/11354) 合并到 API7 企业版。 -* 修复了控制台上数据面不可见的问题。 -* 修复了一个问题：将 Prometheus 数据报告方法从远程写入更改为抓取后，服务注册表状态始终显示为“断开连接”。 -* 修复了通过控制台部署自定义插件后，数据面遇到错误的问题。 -* 修复了前端错误：不应该允许通过控制台在 Ingress Controller 网关组上修改已发布服务的上游。 -* 去掉不该出现的报错通知：切换到节点时，即使启用了健康检查，仍然存在提示用户启用健康检查的提示。 -* 修复问题：上传自定义插件时，如果出现解析错误，错误消息中显示的插件名称与实际文件名不匹配。 - -## 3.2.14.0 版本 - -**发布日期：** 2024-07-08 - -### 新功能 - -#### 全新的访问控制机制 - -:::info - -这是一项不兼容变更。旧版本的规则不能保留。 - -::: - -API7 企业版改进了传统的基于角色的权限，采用了权限策略架构，通过分配给角色的可复用策略来实现精细的访问控制。请参阅[角色和权限策略](./key-concepts/roles-and-permission-policies.md)。 - -### 功能优化 - -#### 配置路由优先级 - -在特定场景下，你可以在两个不同的服务中配置相同的路由。通过优先级确定哪个路由处理请求。具有较高指定优先级的路由将首先被使用。 - -#### 强化 mTLS 证书安全 - -改进了以下问题： - -- 过长的证书：证书字符串太长，应该缩短。 -- 不必要的标记：证书包含不必要的标记，应该删除。 -- 共享 CA：为多个证书使用相同的证书颁发机构 (CA) 是不安全的。 -- 证书不匹配处理：当发生证书不匹配时，握手应立即失败，拒绝客户端的请求，而不是继续进行进一步的验证。 - -#### 在 API7 Helm Chart 中包含新的参数 `lua_shared_dict` - -为 Helm chart 引入了一个新的参数。 - -### 缺陷修复 - -- 从旧版本升级可能会导致上游数据丢失或 404 错误。 -- 服务请求 URL 更新期间遇到 UI 错误。 -- 修复了 API7 Portal (Beta) 库问题。 -- 修复了 [HTTP Logger](https://docs.api7.ai/hub/http-logger) 插件内存泄漏。 -- 前端和后端密码策略不一致。 -- 当 GET 请求与任何路由都不匹配时，[Data Mask](https://docs.api7.ai/hub/data-mask) 插件会报告错误。 -- ApisixUpstream CRD 的 status 字段记录不正确。 -- 数据面支持配置监控数据的报告间隔。 -- 修复了配置插件元数据后的警告日志。 -- 修复了插件重新加载问题。 -- 减少 PostgreSQL 连接数。 -- 优化前端资源消耗。 -- 删除 FQDN 中的尾随点。 -- 插件元数据应该能够被删除。 - -## 3.2.11.8 版本 - -**发布日期：** 2024-06-26 - -### 缺陷修复 - -- 通过减少 etcd 调用来降低 API 延迟。 -- Kine 数据库连接池配置可以正常工作。 - -## 3.2.11.7 版本 - -**发布日期：** 2024-06-24 - -### 缺陷修复 - -- 提升 API 性能。 -- 数据面支持禁用遥测数据收集和配置报告间隔。 -- 自定义插件即使没有 schema 定义也可以正常工作。 - -## 3.2.11.6 版本 - -**发布日期：** 2024-06-24 - -### 缺陷修复 - -- 大数据集不再导致 etcd range API 错误。 - -## 3.2.13.0 版本 - -**发布日期：** 2024-06-19 - -### Admin API 不兼容变更 - -1. 服务模板 API 已迁移到 "/api/services/template" 路径前缀下。 - -- [服务模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services-Template) -- [路由模板 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes-Template) - -2. 原始的 "/apisix/admin/services" 端点现在需要 gateway_group_id 参数。 - -- [网关组上的服务 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services) -- [网关组上的路由 API](https://docs.api7.ai/enterprise/reference/admin-api#tag/Routes) - -### 新增功能 - -#### 在网关组上创建/更新服务而不发布 - -如果版本控制不是你的要求，你现在可以直接在网关组上创建服务。这些服务会立即生效，无需单独的发布步骤。这简化了部署过程并节省了时间。 - -但是，重要的是要考虑所涉及的权衡。通过绕过发布阶段，你也失去了轻松回滚到以前版本或跟踪版本更改的能力。 - -有关详细信息，请参阅最新的入门教程：[启动你的第一个 API](./getting-started/launch-your-first-api.md)。 - -#### 与 Ingress Controller 集成（UI 支持） - -API7 Gateway 正式推出 Ingress Controllers，这是一种新型的网关组。虽然控制台提供了方便的管理功能来创建和查看你的 Ingress Controller，但配置修改需要对任何配置更改采用声明方式。 - -### 功能优化 - -#### 搜索网关组名称并按标签过滤 - -使在网关组列表中查找所需的特定网关组变得更加容易。 - -#### 保护配置文件中的敏感数据 - -数据库的 DSN 配置（包括访问地址、用户名和密码）可以通过环境变量和 Helm 图表进行配置。 - -#### 支持 Prometheus 认证 - -Prometheus 远程写入现在支持 Basic Auth/mTLS。 - -#### 支持 SSL 变量的 Secret 功能 - -使用加密的 Secret 保护 `ssl.certs` 和 `ssl.keys`。 - -### 缺陷修复 - -- 设置标头后，`ctx.var` 变量将立即更新。 -- 无法上传重复的 SSL 证书。 - -## 3.2.11.5 版本 - -**发布日期：** 2024-06-18 - -### 缺陷修复 - -- ssl_verify 配置现在适用于登录选项 OIDC 和 LDAP 协议。 - -## 3.2.11.4 版本 - -**发布日期：** 2024-06-07 - -### 缺陷修复 - -- 保护与 API 相关的登录选项中的敏感字段。 - -## 版本 3.2.12.0 - -**发布日期**: 2024-05-24 - -### Admin API 不兼容变更 - -1. service status 字段从“0: 启用，1: 禁用”变更为“0: 禁用，1: 启用” - -- [Publish a service](https://docs.api7.ai/enterprise/reference/admin-api#tag/Services/paths/~1api~1services~1publish/post) -- [Update service runtime configurations by ID](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/changeServiceRuntimeConfiguration) -- [Get all published services in Gateway Group](https://docs.api7.ai/enterprise/reference/admin-api#tag/Gateway-Groups/operation/listPublishedService) - -2. consumer api 移除 id 字段，使用 gateway group id & username 做查询、删除 - -- [Consumers APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/Consumers) - -3. ssl 相关 api 强制 gateway group id 参数 - -- [SSL APIs](https://docs.api7.ai/enterprise/reference/admin-api#tag/SSLs) - -### 新增功能 - -#### 四层路由（Stream Route） - -API7 网关现在可以处理四层流量，比如与数据库或 Kafka 的连接。 添加一个四层类型的服务，并在其中添加若干个四层路由（Stream Route，即可[转发四层流量](./getting-started/proxy-l4-traffic.md)。 - -#### 自定义角色 (控制台支持) - -当默认提供的角色无法满足需求时，你可以自行设计自定义角色，实现精细化权限控制。可参阅[添加自定义角色](./getting-started/rbac.md) - -#### Ingress Controller（Beta 测试版，仅 API 支持） - -集成 Ingress Controller。 - -### 功能优化 - -#### 优化左侧导航菜单 - -- 用户登录后落地页改为网关组菜单中已发布服务。 -- **服务** 菜单项改名为 **服务中心**。 - -### 缺陷修复 - -- 使用 [Key Auth](https://docs.api7.ai/hub/key-auth) 插件时，禁止出现重复的 API 密钥。 -- 使用 [UA Restriction](https://docs.api7.ai/hub/ua-restriction) 插件时，允许同时配置黑名单和白名单。 -- 重置用户密码时不会引起访问令牌失效。 -- 使用 [Loggly](https://apisix.apache.org/zh/docs/apisix/plugins/loggly/) 插件时配置能校验成功。 -- API7 网关中的状态字段取值含义和 Apache APISIX 保持一致。 - -## 版本 3.2.11.3 - -**发布日期: 2024-05-20 - -### 缺陷修复 - -- etcd watch 可以正确地传递 SNI。 -- API7 企业版在安装时会先尝试创建新的数据库。如果没有对应权限导致失败，会使用预先指定的已有数据库，避免安装失败。 - -## 版本 3.2.11.2 - -**发布日期**: 2024-05-20 - -### 缺陷修复 - -- 标签支持最长 64 个字符，且可以包含空格。 -- 即使包含 schema 校验错误，也可以正常完成与数据面的配置同步，避免数据丢失或工作流中断。 - -## 版本 3.2.11.1 - -**发布日期**: 2024-05-08 - -### 新增功能 - -#### SSO 角色映射 - -设置自动角色映射，可以避免超级管理员需要频繁为 SSO 登陆的用户分配角色。 满足预先设置的映射条件的用户，在登陆 API7 企业版时会自动获得相应的角色权限。详情参阅[设置角色映射](./best-practices/sso.md#设置角色映射)。 - -#### SCIM 用户同步 - -使用 SCIM 用户同步协议简化 SSO 用户管理。它可以自动从所有支持了 SCIM 协议的、已经添加了登陆选项的身份提供商同步用户数据，确保用户信息一致性。新用户在身份提供商注册，或用户在身份提供商注销，API7 企业版即可得到及时通知，避免新用户无法登陆或已注销用户非法登陆。详情参阅[Sync User Data from IdP](./best-practices/sso.md#从身份提供商同步用户数据)。 - -#### 自定义角色 (Beta, 仅 API 支持) - -如默认角色不满足业务需求，现在你可以设计自定义角色，自由组合权限，进行细粒度权限控制。 -该功能即将在后续版本支持控制台配置。 - -### 功能优化 - -#### 升级到 OpenSSL 3 - -提升安全性，性能，和可靠性。 - -#### 全局插件执行顺序优化 - -为了简化全局插件的管理，API7 企业版 会将多个全局插件配置整合到一起，确保插件配置和执行顺序不会产生冲突。 - -### 缺陷修复 - -#### 前端补全 HTTP 协议检测 - -生成的网关实例部署脚本有时无法正确检测是否需要 HTTP 或 HTTPS 协议，这可能会导致部署时出现错误。 - -#### 上传 SSL 证书错误 - -为网关组 A 上传的 SSL 证书可能会意外分配给网关组 B。 - -#### 支持主机级动态设置 TLS 协议版本 - -同步集成了在 Apache APISIX 中已解决的问题。 - -## 版本 3.2.10.1 - -**发布日期**：2024-04-28 - -### 新增功能 - -#### 支持 MySQL 5.7 - -现在起 API7 企业版支持使用 MySQL 5.7 作为持久化数据存储。 - -## 版本 3.2.10.0 - -**发布日期**: 2024-04-22 - -### 不兼容变更 - -#### 令牌绑定用户 - -令牌改为和具体用户绑定，且和用户享有相同的角色权限。如果用户被删除，绑定的令牌也将立刻失效被删除。 - -## 版本 3.2.9.5 - -**发布日期**：2024-04-16 - -### 新增功能 - -#### 上游 mTLS（仅 API 支持） - -支持在 API7 网关和上游服务之间配置 mTLS 认证。 mTLS 是一种通信安全形式，要求双方彼此展示证书。这确保了双方都是其声称的身份，并且在它们之间传输的数据是加密的。 -该功能即将在后续版本支持控制台配置。 - -## 版本 3.2.9.4 - -**发布日期**: 2024-04-07 - -### 缺陷修复 - -#### CPU 核心数判断 - -修复了当 CPU 核心数达到最大限制时出现的问题。 - -## 版本 3.2.9.3 - -**发布日期**: 2024-04-03 - -### 新增功能 - -#### 集成 Vault(Beta) - -将敏感信息存储到 Vault中。仅支持通过 Admin API 使用，UI 使用即将推出。 - -## 版本 3.2.9.2 - -**发布日期**: 2024-04-01 - -### 新增功能 - -#### 支持 SAML 第三方登录 - -API7 企业版新增支持对接 SAML 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md)。 - -#### 新插件： Data Mask - -[Data Mask](https://docs.api7.ai/hub/data-mask) 插件提供了在请求头、请求体和 URL 查询中移除或替换敏感信息的能力。 - -### 功能优化 - -#### 忽略路径前缀 - -你可以选择在向上游发送请求时跳过路径前缀。这种调整对用户来说是不感知的，并且在使用不同的路径前缀来识别发送到不同网关组的 API 时可能很有用。 - -#### 优化健康检查配置 UI - -提供一个更直观友好的健康检查配置交互界面。 - -#### 升级加密算法 - -从 AES128 升级到 AES 256。 - -#### 性能提升 - -消除了禁用插件后带来的性能损耗。 - -## 版本 3.2.9.1 - -**发布日期*: 2024-03-19 - -### 新增功能 - -#### 支持自定义插件管理 - -API7 企业版支持上传你自行编写的自定义插件，以扩展 API 管理的功能。详情见[新增自定义插件](./best-practices/custom-plugin.md). - -#### 支持 OIDC 第三方登录 - -API7 企业版即 LDAP 之后，新增支持对接 OIDC 第三方登录。详情见[如何设置第三方登录](./best-practices/sso.md). - -#### 将服务标签作为 API 提供者授权范围 - -通过将服务标签作为为API提供者的范围，你可以授予他们访问带有特定标签的所有服务的权限。这将有助于减轻超级管理员的工作负担。通常，可以使用“部门”标签对服务进行分组。此后该部门的用户将能够访问属于该部门的所有服务。 - -## 版本 3.2.8.1 - -**发布日期**： 2024-02-08 - -### 新增功能 - -#### 支持 Nacos 服务发现 - -API7 企业版利用服务发现功能自动检测可用的上游服务，并将其地址保存在数据库（也被称之为服务注册中心）中。因此，API 网关能够通过服务注册中心获取最新的上游地址列表，确保所有请求都被转发到健康的上游节点。 - -在本版本中，API7 企业版支持与 Nacos 服务发现集成。用户可以使用 Nacos 服务发现来[发布服务](./getting-started/publish-service.md)和[在网关组之间同步服务](./getting-started/sync-service.md)。 - -#### 支持 LDAP SSO 登录 - -API7 企业版支持 LDAP 单点登录（Single Sign-On，SSO）。将 API7 企业版与 LDAP 集成后，用户可以直接使用 LDAP 用户名和密码登录 API7 控制台，创建和管理 API7 网关资源。有关如何配置 LDAP SSO 登录方法的具体信息，参见[配置 LDAP 单点登录](./best-practices/sso.md)。 - -#### 支持使用 Kubernetes 添加网关实例 - -用户使用网关实例来处理流量。在本版本中，API7 企业版支持使用 Kubernetes 向网关组添加网关实例。有关如何通过 Kubernetes 添加网关实例的具体信息，参见[添加网关实例](./getting-started/add-gateway-instance.md)。 From fab142b5e7fec4fe058215506f4776f0de8481e5 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:49:58 +0800 Subject: [PATCH 07/24] Create cp-release-notes.md --- .../version-3.6.x/release-note/cp-release-notes.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md new file mode 100644 index 00000000..e69de29b From 734ea0eb7774f6b9fc91887add10aa6a00208432 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:50:00 +0800 Subject: [PATCH 08/24] Create dp-release-notes.md --- .../version-3.6.x/release-note/dp-release-notes.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md new file mode 100644 index 00000000..e69de29b From a873eeab836431113d236b052db129af907b6cf7 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 10 Mar 2025 16:54:18 +0800 Subject: [PATCH 09/24] Update dp-release-notes.md --- .../release-note/dp-release-notes.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md index e69de29b..b453d95c 100644 --- a/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md +++ b/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md @@ -0,0 +1,18 @@ +--- +title: 数据面更新日志 +slug: /dp-release-notes +--- + +## DP3.6.0 版本 + +**发布日期**: 2025-02-26 + +### 新功能 + +#### 数据面和控制面版本解耦 + +从 3.6.0 版本开始，数据平面和控制平面的版本将解耦，允许独立升级。控制平面通常会兼容多个数据平面版本，而数据平面版本为了保持稳定性，会以较慢的速度演进。 + +### Apache APISIX 更新同步 + +* 修复服务发现问题：[使用节点缓存 original_nodes](https://github.com/apache/apisix/pull/10722)，[更新 upstream.nodes 时的竞争条件问题](https://github.com/apache/apisix/pull/11916)。 From 49c88baec196f683fc888172ffaaf92f11f84cf6 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Fri, 14 Mar 2025 14:08:27 +0800 Subject: [PATCH 10/24] Update cp-release-notes.md --- .../release-note/cp-release-notes.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md index e69de29b..d5c62149 100644 --- a/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md +++ b/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md @@ -0,0 +1,31 @@ +--- +title: 控制面更新日志 +slug: /cp-release-notes +--- + +## CP3.6.0 版本 + +**发布日期**: 2025-02-26 + +**兼容数据面版本**: 3.2.x.x - 3.6.x + +### 新功能 + +#### 数据平面和控制平面版本解耦 + +从 3.6.0 版本开始，数据平面和控制平面的版本将解耦，允许独立升级。控制平面通常会兼容多个数据平面版本，而数据平面版本为了保持稳定性，会以较慢的速度演进。 + +#### 为上游配置 mTLS + +为了防止未经授权的访问并加强安全性，请考虑[在 API7 Enterprise 和上游之间配置 mTLS](../api-security/upstream-mtls.md)。 + +#### 使用电子邮件登录 + +API7 Enterprise 现在支持使用用户名或电子邮件地址以及密码登录。要使用电子邮件登录或接收通知，请将电子邮件地址绑定到您的用户配置文件。 + +#### 改进 + +* 支持引用 SSO 连接信息的环境变量。 +* 为插件配置引入了基于表单的 UI。 +* 将基本身份验证添加为开发者门户凭据的身份验证选项。如果 API 产品允许多种身份验证类型，则可以使用任何有效凭据。 +* 移除了服务模板中的[服务运行时配置](../key-concepts/services.md#service-runtime-configurations)，以便在网关组之间更好地重用模板。**这是一项重大更改。服务模板中现有的服务运行时配置将被移除，但您已发布的服务的配置将保持不变。** 此外，发布过程得到了简化和优化，在此过程中不允许进行服务运行时配置。请参阅更新后的[发布服务](../getting-started/publish-service.md)指南。 \ No newline at end of file From b81c1b7b5be5ecad716108b82f7b237c47555146 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 17 Mar 2025 14:24:41 +0800 Subject: [PATCH 11/24] Update productize-services.md --- .../version-3.6.x/api-portal/productize-services.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md b/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md index 277a3514..90a075b8 100644 --- a/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md +++ b/enterprise_versioned_docs/version-3.6.x/api-portal/productize-services.md @@ -75,7 +75,7 @@ slug: /api-portal/productize-services 2. 点击 **新增 API 产品**，然后选择 **从 API7 网关创建**。 3. 填写表单： * **名称** 输入 `httpbin`。 - * **认证方式** 选择 `Key Authentication`。 + * **认证方式** 选择 `Key Authentication` 或者 `Basic Authentication`。 * 关闭 **订阅自动审批** 开关。 * **API Hub 列表可见性** 选择 `仅对登录的开发者可见`。 * 打开 **未订阅的开发者可以查看 API 详情** 开关。 @@ -109,6 +109,9 @@ slug: /api-portal/productize-services 3. 选择 `httpbin`。 4. 点击 **Test Request**。 5. 预先选择了 **Auth Type**，并自动填写 API 密钥，从开发者的凭据中复制。 + +* 如果 API 产品在设置时允许多种身份验证类型，则开发者可以使用任意一个有效的凭据来调用 API。 + 6. 点击 **Send**。 7. 接收 `200` 响应。 From ea4dd9053e32049c3abddb869bd32e908314f850 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 17 Mar 2025 14:24:43 +0800 Subject: [PATCH 12/24] Update old-release-notes.md --- .../version-3.6.x/release-note/old-release-notes.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md index 9668e6fc..4c0c2373 100644 --- a/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md +++ b/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md @@ -9,6 +9,18 @@ slug: /old-release-notes ::: +## 3.5.5 版本 + +**发布日期**: 2025-03-14 + +### 安全性 + +* 解决安全漏洞：[OpenID Connect](/hub/openid-connect) 插件现在支持配置验证发行者。 + +### Bug 修复 + +* 修复问题：[Limit Count Advanced](/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 + ## 3.5.4 版本 **发布日期**: 2025-03-07 From c7b50a74963cb79efa90deaedb7693d2f55840d4 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Mon, 17 Mar 2025 15:29:03 +0800 Subject: [PATCH 13/24] Update publish-service.md --- .../version-3.6.x/getting-started/publish-service.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md index 70a6098c..edcbc688 100644 --- a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md @@ -7,12 +7,14 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; -当你的 API 设计、开发和部署完成后，如果有版本管理的场景和需求，可以使用 API7 网关将服务发布到不同的网关组，而非直接在网关组上对配置进行修改。 通常，API 会先发布到测试环境，然后再发布到生产环境。API7 企业版通过网关组来隔离不同的环境，在各个环境中，API 从属于一个服务（Service），服务内所有 API 拥有共享的上游 (Upstream)。 +为了对已部署的 API 进行版本控制，可以利用 API7 企业版将可复用的服务模板发布到不同的[网关组](../key-concepts/gateway-groups.md)形成不同的服务版本，而不是在网关组上直接进行配置编辑。 -本教程将指导你将 [httpbin](https://httpbin.org/) 服务发布到一个网关组。你将学习如何： +通常，API 版本会在发布到生产环境之前，先发布到测试和暂存环境中。API7 Gateway 通过[网关组](../key-concepts/gateway-groups.md)管理这种环境隔离，其中 API 属于具有共享[上游](../key-concepts/upstreams.md)的单个[已发布服务](../key-concepts/services.md)。 -1. 手动创建服务模板以及通过 OpenAPI 文件创建服务模板。 -2. 通过配置上游节点和使用服务发现机制来发布服务。 +本教程将指导您在 API7 Gateway 上将 [httpbin](https://httpbin.org/) 服务发布到网关组。您将学习如何： + +1. 手动和通过 OpenAPI 规范文件创建服务。 +2. 通过配置上游节点和使用服务发现机制发布服务。 ## 前提条件 From 54c3584c554a1f0c7ade3bddd7d307496b602b86 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Tue, 25 Mar 2025 17:20:16 +0800 Subject: [PATCH 14/24] update --- .../version-3.5.x/release-notes.md | 14 +++- .../release-note/cp-release-notes.md | 31 -------- .../release-note/dp-release-notes.md | 18 ----- .../old-release-notes.md => release-notes.md} | 72 ++++++++++++++++--- 4 files changed, 74 insertions(+), 61 deletions(-) delete mode 100644 enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md delete mode 100644 enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md rename enterprise_versioned_docs/version-3.6.x/{release-note/old-release-notes.md => release-notes.md} (91%) diff --git a/enterprise_versioned_docs/version-3.5.x/release-notes.md b/enterprise_versioned_docs/version-3.5.x/release-notes.md index 8f0a8edf..9fe0632a 100644 --- a/enterprise_versioned_docs/version-3.5.x/release-notes.md +++ b/enterprise_versioned_docs/version-3.5.x/release-notes.md @@ -3,13 +3,23 @@ title: 更新日志 slug: /release-notes --- +## 3.5.5 版本 + +**发布日期**: 2025-03-14 + +### 缺陷修复 + +* 修复缺陷：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 +* 修复缺陷：[OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件现在支持配置验证发行者。 +* 修复缺陷：[无法使用 openid-connect 验证 audience claim](https://github.com/orgs/apache/projects/273/views/2?pane=issue&itemId=55833755&issue=apache%7Capisix%7C11018)。 + ## 3.5.4 版本 **发布日期**: 2025-03-07 ## 功能优化 -* 支持在 [Elasticsearch Logger](/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 +* 支持在 [Elasticsearch Logger](https://docs.api7.ai/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 * 优化了慢查询。 ### Bug 修复 @@ -42,7 +52,7 @@ slug: /release-notes ### 缺陷修复 * 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。 -* 支持在 OTEL 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 +* 支持在 [OpenTelemetry](https://docs.api7.ai/hub/opentelemetry) 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 ## 3.5.0 版本 diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md deleted file mode 100644 index d5c62149..00000000 --- a/enterprise_versioned_docs/version-3.6.x/release-note/cp-release-notes.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 控制面更新日志 -slug: /cp-release-notes ---- - -## CP3.6.0 版本 - -**发布日期**: 2025-02-26 - -**兼容数据面版本**: 3.2.x.x - 3.6.x - -### 新功能 - -#### 数据平面和控制平面版本解耦 - -从 3.6.0 版本开始，数据平面和控制平面的版本将解耦，允许独立升级。控制平面通常会兼容多个数据平面版本，而数据平面版本为了保持稳定性，会以较慢的速度演进。 - -#### 为上游配置 mTLS - -为了防止未经授权的访问并加强安全性，请考虑[在 API7 Enterprise 和上游之间配置 mTLS](../api-security/upstream-mtls.md)。 - -#### 使用电子邮件登录 - -API7 Enterprise 现在支持使用用户名或电子邮件地址以及密码登录。要使用电子邮件登录或接收通知，请将电子邮件地址绑定到您的用户配置文件。 - -#### 改进 - -* 支持引用 SSO 连接信息的环境变量。 -* 为插件配置引入了基于表单的 UI。 -* 将基本身份验证添加为开发者门户凭据的身份验证选项。如果 API 产品允许多种身份验证类型，则可以使用任何有效凭据。 -* 移除了服务模板中的[服务运行时配置](../key-concepts/services.md#service-runtime-configurations)，以便在网关组之间更好地重用模板。**这是一项重大更改。服务模板中现有的服务运行时配置将被移除，但您已发布的服务的配置将保持不变。** 此外，发布过程得到了简化和优化，在此过程中不允许进行服务运行时配置。请参阅更新后的[发布服务](../getting-started/publish-service.md)指南。 \ No newline at end of file diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md deleted file mode 100644 index b453d95c..00000000 --- a/enterprise_versioned_docs/version-3.6.x/release-note/dp-release-notes.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 数据面更新日志 -slug: /dp-release-notes ---- - -## DP3.6.0 版本 - -**发布日期**: 2025-02-26 - -### 新功能 - -#### 数据面和控制面版本解耦 - -从 3.6.0 版本开始，数据平面和控制平面的版本将解耦，允许独立升级。控制平面通常会兼容多个数据平面版本，而数据平面版本为了保持稳定性，会以较慢的速度演进。 - -### Apache APISIX 更新同步 - -* 修复服务发现问题：[使用节点缓存 original_nodes](https://github.com/apache/apisix/pull/10722)，[更新 upstream.nodes 时的竞争条件问题](https://github.com/apache/apisix/pull/11916)。 diff --git a/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-notes.md similarity index 91% rename from enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md rename to enterprise_versioned_docs/version-3.6.x/release-notes.md index 4c0c2373..d1cad7bc 100644 --- a/enterprise_versioned_docs/version-3.6.x/release-note/old-release-notes.md +++ b/enterprise_versioned_docs/version-3.6.x/release-notes.md @@ -1,13 +1,65 @@ --- -title: API7 企业版更新日志(版本3.5.x及之前) -slug: /old-release-notes +title: API7 企业版更新日志 +slug: /release-notes --- -:::note +## 3.6.1 版本 -从 3.6.0 版本开始，数据面和控制面的版本将解耦，允许独立升级。控制面通常会兼容多个数据面版本，而数据面版本会以较慢的速度更新以保持稳定性。 +**发布日期**: 2025-03-14 -::: +**兼容数据平面版本**: 3.2.x.x - 3.6.x + +### 缺陷修复 + +#### 插件 + +* 修复问题：[Limit Count Advanced](https://docs.api7.ai//hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 +* 修复问题：[OpenID Connect](https://docs.api7.ai//hub/openid-connect) 插件现在支持配置验证发行者。 + +## 3.6.0 版本 + +**发布日期**: 2025-02-26 + +**兼容数据平面版本**: 3.2.x.x - 3.6.x + +### 不兼容变更 + +* 移除了服务模板中的[服务运行时配置](./key-concepts/services.md#运行时配置)，以便在网关组之间更好地复用模板。**这是一项不兼容变更。服务模板中现有的服务运行时配置将被移除，但已发布的服务的配置将保持不变。** 此外，发布过程得到了简化和优化，在此过程中不需要进行服务运行时配置。请参阅更新后的[发布服务](./getting-started/publish-service.md)指南。 + +### 新功能 + +#### 数据面 + +* **为上游配置 mTLS**: 为了防止未经授权的访问并加强安全性，请考虑[在 API7 企业版和上游之间配置 mTLS](./api-security/upstream-mtls.md)。 + +#### Admin API + +* [Published Service](/enterprise/reference/admin-api#tag/Published-Service) API 当 `scheme` 为 `https` 时已更新，用于支持新功能：**为上游配置 mTLS**， +* [Login Option](/enterprise/reference/admin-api#tag/Login-Option) API 已扩展，接受环境变量作为值。 +* [Service Template](/enterprise/reference/admin-api#tag/Service-Template) API 已更新，用于支持新特性：**移除了服务运行时配置**。 + +#### 控制台 + +* **使用电子邮件登录**: API7 企业版控制台现在支持使用用户名或电子邮件地址以及密码登录。要使用电子邮件登录或接收通知，请将电子邮件地址绑定到您的用户配置文件。 +* 支持为上游配置 mTLS。 + +### 功能优化 + +#### 控制台 + +* 支持在 SSO 连接信息的中引用环境变量。 +* 为[Proxy Rewrite](https://docs.api7.ai/hub/proxy-rewrite)插件配置引入了表单样式的 UI。 + +#### API7 门户 + +* 将 Basic Authentication 添加为开发者门户的身份验证选项。如果 API 产品允许多种身份验证类型，则开发者可以使用任意一个有效凭据。 + +### 缺陷修复 + +#### 数据面 + +* 修复问题：更新 `upstream.nodes` 时的竞争条件问题。 +* 修复服务发现问题：[使用节点缓存 original_nodes](https://github.com/apache/apisix/pull/10722)，[更新 upstream.nodes 时的竞争条件问题](https://github.com/apache/apisix/pull/11916)。 ## 3.5.5 版本 @@ -15,11 +67,11 @@ slug: /old-release-notes ### 安全性 -* 解决安全漏洞：[OpenID Connect](/hub/openid-connect) 插件现在支持配置验证发行者。 +* 解决安全漏洞：[OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件现在支持配置验证发行者。 -### Bug 修复 +### 缺陷修复 -* 修复问题：[Limit Count Advanced](/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 +* 修复问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 ## 3.5.4 版本 @@ -27,7 +79,7 @@ slug: /old-release-notes ## 功能优化 -* 支持在 [Elasticsearch Logger](/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 +* 支持在 [Elasticsearch Logger](https://docs.api7.ai/hub/elasticsearch-logger) 插件中配置索引以根据当前日期动态发送数据。 * 优化了慢查询。 ### Bug 修复 @@ -60,7 +112,7 @@ slug: /old-release-notes ### 缺陷修复 * 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。 -* 支持在 OTEL 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 +* 支持在 [OpenTelemetry] 插件报告动态路由 `/v2/:customerNumber` 时将 `request.url` 报告为 `route.url`。 ## 3.5.0 版本 From da9ba2b5947269995dc7ab2267a8551bcd9175ad Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Tue, 25 Mar 2025 17:21:18 +0800 Subject: [PATCH 15/24] Update release-notes.md --- enterprise_versioned_docs/version-3.6.x/release-notes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/enterprise_versioned_docs/version-3.6.x/release-notes.md b/enterprise_versioned_docs/version-3.6.x/release-notes.md index d1cad7bc..7027dae6 100644 --- a/enterprise_versioned_docs/version-3.6.x/release-notes.md +++ b/enterprise_versioned_docs/version-3.6.x/release-notes.md @@ -71,7 +71,9 @@ slug: /release-notes ### 缺陷修复 -* 修复问题：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 +* 修复缺陷：[Limit Count Advanced](https://docs.api7.ai/hub/limit-count-advanced) 插件在负载测试期间偶尔出现 500 错误。 +* 修复缺陷：[OpenID Connect](https://docs.api7.ai/hub/openid-connect) 插件现在支持配置验证发行者。 +* 修复缺陷：[无法使用 openid-connect 验证 audience claim](https://github.com/orgs/apache/projects/273/views/2?pane=issue&itemId=55833755&issue=apache%7Capisix%7C11018)。 ## 3.5.4 版本 From 444dda225bf1eba20f3d2cb8ac5bf2b9c9d04e20 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Tue, 25 Mar 2025 17:30:33 +0800 Subject: [PATCH 16/24] Update version-3.6.x-sidebars.json --- .../version-3.6.x-sidebars.json | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/enterprise_versioned_sidebars/version-3.6.x-sidebars.json b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json index b152a624..0ad47fbe 100644 --- a/enterprise_versioned_sidebars/version-3.6.x-sidebars.json +++ b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json @@ -105,15 +105,22 @@ "label": "更新日志", "id": "release-notes" }, + { + "type": "link", + "label": "Admin APIs", + "href": "/enterprise/reference/admin-api" + }, + { + "type": "category", + "label": "Upgrade Guides", + "items": [ + "upgrade-guides/breaking-changes" + ] + }, { "type": "category", "label": "开发参考", "items": [ - { - "type": "link", - "label": "Admin APIs", - "href": "/enterprise/reference/admin-api" - }, { "type": "category", "label": "部署", From 388674fcb8928bbbaa9cd1692a96161e21abb8fc Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Tue, 25 Mar 2025 17:35:40 +0800 Subject: [PATCH 17/24] Update upstream-mtls.md --- .../version-3.6.x/api-security/upstream-mtls.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md index fed55e6c..1204b0fb 100644 --- a/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md +++ b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md @@ -188,7 +188,7 @@ curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key 2. 点击 **新增 SSL 证书**。 3. 在对话框中，执行以下操作： -* 在 **名称** 字段中，输入 `Upstream SSL Certificate`。 +* 在 **名称** 字段中，输入 `上游 SSL 证书`。 * 在 **证书** 字段中，上传 `client.crt` 文件。 * 在 **私钥** 字段中，上传 `client.key` 文件。 * 点击 **新增**。 @@ -197,7 +197,7 @@ curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key 5. 点击 **新增 CA 证书**。 6. 在对话框中，执行以下操作： -* 在 **名称** 字段中，输入 `Upstream CA Certificate`。 +* 在 **名称** 字段中，输入 `上游 CA 证书`。 * 在 **证书** 字段中，上传 `ca.crt` 文件。 * 点击 **新增**。 @@ -208,8 +208,8 @@ curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key 3. 点击 **连接配置** 字段的编辑按钮。 4. 在对话框中，执行以下操作： -* 在 **客户端证书** 字段中，选择 `Upstream SSL Certificate`。 -* 在 **CA 证书** 字段中，选择 `Upstream CA Certificate`。 +* 在 **客户端证书** 字段中，选择 `上游 SSL 证书`。 +* 在 **CA 证书** 字段中，选择 `上游 CA 证书`。 * 点击 **保存**。 ## 验证 API7 企业版和上游服务之间的 mTLS From f49e069a6d7cd8a0ac3050c8b1bf2aa736e039a8 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 14:27:25 +0800 Subject: [PATCH 18/24] Update publish-service.md --- .../getting-started/publish-service.md | 139 +++++------------- 1 file changed, 40 insertions(+), 99 deletions(-) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md index edcbc688..19af7310 100644 --- a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md @@ -11,9 +11,9 @@ import StorylaneEmbed from '@site/src/MDXComponents/StorylaneEmbed'; 通常，API 版本会在发布到生产环境之前，先发布到测试和暂存环境中。API7 Gateway 通过[网关组](../key-concepts/gateway-groups.md)管理这种环境隔离，其中 API 属于具有共享[上游](../key-concepts/upstreams.md)的单个[已发布服务](../key-concepts/services.md)。 -本教程将指导您在 API7 Gateway 上将 [httpbin](https://httpbin.org/) 服务发布到网关组。您将学习如何： +本教程将指导你在 API7 企业版上将 [httpbin](https://httpbin.org/) 服务发布到网关组。你将学习如何： -1. 手动和通过 OpenAPI 规范文件创建服务。 +1. 手动和通过 OpenAPI 文件创建服务。 2. 通过配置上游节点和使用服务发现机制发布服务。 ## 前提条件 @@ -39,19 +39,17 @@ values={[ 2. 选择 **手动新增**。 3. 在表单中执行以下操作： -* **名称** 填写 `httpbin API`。 * **服务类型** 选择 `HTTP （七层代理）`。 -* **上游 Scheme** 选择 `HTTP`。 +* **名称** 填写 `httpbin`。 * 点击 **新增**。 4. 进入服务内，点击 **新增路由**。 5. 在表单中，执行以下操作： -* **名称** 填写 `getting-started-anything`. -* **路径** 填写 `/anything/*`。 +* **名称** 填写 `get-ip`. +* **路径** 填写 `/ip`。 * **HTTP 方法** 选择 `GET`。 - -6. 点击 **新增**。 +* 点击 **新增**。 @@ -61,7 +59,7 @@ values={[ ```yaml title="adc.yaml" services: - - name: httpbin API + - name: httpbin upstream: name: httpbin upstream scheme: http @@ -71,8 +69,8 @@ services: weight: 100 routes: - uris: - - /anything/* - name: getting-started-anything + - /ip + name: get-ip methods: - GET ``` @@ -83,23 +81,23 @@ services: ### 导入 OpenAPI 文件 -控制台和 ADC 都支持导入 [OpenAPI v3.0](https://swagger.io/specification/) 规范。 +控制台和 ADC 都支持导入 [OpenAPI v3.0](https://swagger.io/specification/) 文件。 在 YAML/JSON 文件中定义你的 API，如下所示： ```yaml title="OpenAPI.yaml" openapi: 3.1.0 info: - title: httpbin API + title: httpbin description: "httpbin API for the API7 Enterprise Getting Started guides." version: 1.0.0 paths: "/anything/*": get: tags: - - Anything - summary: Returns anything that is passed into the request. - operationId: getting-started-anything + - ip + summary: Returns the ip of the request. + operationId: get-ip responses: "200": description: Successful Response @@ -108,8 +106,8 @@ paths: schema: type: string tags: - - name: Anything - description: Return anything that is passed in on the request. + - name: ip + description: Return the ip of the request. ``` 然后在 API7 网关中使用： @@ -129,7 +127,6 @@ values={[ 3. 在表单中执行以下操作： * 上传你的 YAML/JSON 文件。 -* **上游 Scheme** 选择 `HTTP`。 * 点击 **下一步**。 4. 确认以下信息： @@ -138,8 +135,7 @@ values={[ * **标签**：来自 OpenAPI 文件的 `tag`。 * **描述**：来自 OpenAPI 文件的 `description`。 * **路由**: 来自 OpenAPI 文件的 `Paths`。 - -5. 点击 **新增**。 +* 点击 **新增**。 @@ -157,10 +153,6 @@ adc convert openapi -f openapi.yaml -o adc.yaml ## 将服务版本发布到网关组 -在 API7 网关中，你可以使用静态上游节点或动态服务发现来定义请求的目标。静态上游节点适用于地址固定的、定义明确的服务，而动态服务发现则更适合于服务实例可以动态添加或删除的微服务架构。 - -### 发布单个服务 - -1. 在左侧导航栏中选择 **服务中心**， 然后选择之前创建的 `httpbin API` 服务。 +1. 在左侧导航栏中选择 **服务中心**， 然后选择之前创建的 `httpbin` 服务。 2. 点击 **发布新版本**。 -3. 在对话框中选择目标网关组，例如 `默认网关组`， 然后点击 **下一步**。 -4. 在表单中执行以下操作： +3. 在表单中执行以下操作：， +* **网关组** 中选择你要发布的目标网关组，例如 `默认网关组`。 * **新版本** 填写 `1.0.0`。 -* **如何找到上游** 选择 `使用节点`。 -* 点击 **新增节点**。在表单中执行以下操作： - * **主机** 和 **端口** 填写 `httpbin.org` 和 `80`。 - * **权重** 使用默认值 `100`。 - * 点击 **新增**。 -* 确认服务信息，然后点击 **发布**。 +* 点击 **发布**。 + +:::Note + +首次发布服务之后，请在网关组中配置必要的[服务运行时配置](../key-concepts/services.md#service-runtime-configurations)并**启用**该服务以激活你的 API。对于后续发布，服务状态和运行时配置将继承先前版本。 + +::: @@ -198,83 +191,31 @@ adc sync -f adc.yaml --gateway-group default -### 批量发布服务 - - - - - -1. 从侧边栏选择 **服务中心**，然后点击 **批量发布服务**。 -2. 选择你的目标网关组，例如，`default`，然后点击 **下一步**。 -3. 点击 **新增服务**。 -4. 在对话框中，执行以下操作： - - * 在 **服务** 下拉列表中，选择你要发布的服务。 - * **新版本** 输入 `1.0.0`。 - * 点击 **新增**。 - -5. 重复上述步骤以添加更多服务。 -6. 点击 **下一步** 继续发布服务。 -7. 在新窗口中，为每个服务执行以下操作： - - * 在**如何查找上游**字段中，选择 `使用节点`。 - * 点击 **新增节点**。在对话框中，执行以下操作： - * **主机**和**端口** 输入 `httpbin.org` 作为主机，`80` 作为端口。 - * **权重** 使用默认值 `100`。 - * 点击 **新增**。 - -8. 确认信息，然后点击**发布**。 - -下面是一个交互式演示，提供了发布版本化服务的实践介绍。跟随演示，你将直观了解如何在 API7 企业版中使用这个功能。 - - - - +## 配置服务运行时配置 - - -要发布多个服务，你可以更新你的 ADC 配置文件以包含其他服务，或者使用多个配置文件并将它们同步到你的目标网关组，例如 `default`，如下所示： - - -```shell -adc sync -f adc-1.yaml -f adc-2.yaml -``` +1. 发布后，你将被重定向到网关组上的已发布服务。 +2. 从侧边导航栏中选择 **上游**。 +3. 点击 **新增节点**。 +4. 在表单中执行以下操作： - +* **主机** 字段中，输入 `httpbin.org`。 +* **端口** 字段中，输入 `80`。 +* **权重** 字段中，输入 `100`。 +* 点击 **添加**。 - +5. 从已发布服务的顶部标题栏中点击 **启用** 并确认。 ## 验证 API ```bash -curl "http://127.0.0.1:9080/anything/publish" +curl "http://127.0.0.1:9080/ip" ``` 你应该会看到以下输出： -```json +```text { - "args": {}, - "data": "", - "files": {}, - "form": {}, - "headers": { - "Accept": "*/*", - "Host": "localhost", - "User-Agent": "curl/7.88.1", - "X-Amzn-Trace-Id": "Root=1-664cc6d6-10fe9f740ab1629e19cf85a2", - "X-Forwarded-Host": "localhost" - }, - "json": null, - "method": "GET", - "origin": "152.15.0.1, 116.212.249.196", - "url": "http://localhost/anything/publish" + "origin": "127.0.0.1" } ``` From 4173b23c6c15881b2e245f183db6a4773e1ab418 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 14:47:23 +0800 Subject: [PATCH 19/24] Update publish-service.md --- .../version-3.6.x/getting-started/publish-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md index 19af7310..dbb5790b 100644 --- a/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/publish-service.md @@ -201,7 +201,7 @@ adc sync -f adc.yaml --gateway-group default * **主机** 字段中，输入 `httpbin.org`。 * **端口** 字段中，输入 `80`。 * **权重** 字段中，输入 `100`。 -* 点击 **添加**。 +* 点击 **新增**。 5. 从已发布服务的顶部标题栏中点击 **启用** 并确认。 From c82da8c62f3838d0757475b3caf6078cb757acb9 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 14:47:25 +0800 Subject: [PATCH 20/24] Update sync-service.md --- .../getting-started/sync-service.md | 66 ++++++++----------- 1 file changed, 27 insertions(+), 39 deletions(-) diff --git a/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md b/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md index ce3832cf..c6a657b1 100644 --- a/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md +++ b/enterprise_versioned_docs/version-3.6.x/getting-started/sync-service.md @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; 网关组之间同步已发布的服务版本是 API 版本控制的一个很有用的功能。例如： -1. 当使用网关组来分隔环境（如测试和生产）时，你可以在运行测试后将服务版本从测试同步到生产。 +1. 当使用网关组来分隔环境（如测试和生产）时，你可以在测试后将服务版本从测试环境同步到生产环境。 2. 或者，如果你使用网关组来划分区域或团队，同步服务可以帮助在它们之间分发服务。 :::note @@ -20,12 +20,11 @@ import TabItem from '@theme/TabItem'; ## 前提条件 1. [安装 API7 企业版](./install-api7-ee.md)。 -2. 配置两个网关组： 一个用于初始测试环境，另一个作为最终目的环境（例如生产环境）。每个网关组至少[包含一个网关实例](./add-gateway-instance.md)。 +2. 配置两个网关组： 一个用于初始测试环境，另一个作为最终的目的地环境（例如生产环境）。每个网关组至少[包含一个网关实例](./add-gateway-instance.md)。 3. 在初始测试环境的网关组中[发布一个服务版本](./publish-service.md)。 ## 步骤 -* 同一个服务版本发布/同步到不同网关组时，可以使用不同的上游地址对应不同环境里的后端服务。 * “无版本”状态的服务也可以同步到其他网关组，同步之后将同时在两个网关组上都拥有一个相同版本号。 * 你只能同步当前运行的服务版本，不能同步旧的服务版本。 @@ -38,38 +37,19 @@ values={[ ]}> -### 使用上游节点 - -1. 从侧边栏选择服务来源网关组的 **已发布服务**，然后点击你要同步的服务版本，例如版本为 `1.0.0` 的服务 `httpbin API`。 -2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 `同步到其他网关组`。 +1. 从侧边导航栏中选择你的初始网关组的 **已发布服务**，然后点击要同步的服务版本，例如，版本为 `1.0.0` 的 `httpbin`。 +2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 **同步到其他网关组**。 3. 在表单中执行以下操作： -* **网关组** 选择要同步去的目的网关组，例如 `生产网关组`。 -* 点击 **下一步**。 - -4. 在表单中执行以下操作： - -* **如何查找上游** 选择`使用节点`。 -* 点击**拟增节点**。在表单中执行以下操作： - * **主机**和**端口** 填写 `httpbin.org` 作为主机，`80` 作为端口。 - * **权重**使用默认值 `100`。 - * 点击**新增**。 -* 确认服务信息，然后点击 **同步**。 - -### 使用服务发现 - -1. 从侧边栏选择服务来源网关组的 **已发布服务**，然后点击你要同步的服务版本，例如版本为 `1.0.0` 的服务 `httpbin API`。 -2. 点击页面标题中 **启用/禁用** 旁边的按钮，然后选择 `同步到其他网关组`。 -3. 在表单中执行以下操作： +* **网关组** 字段中，选择你的目标网关组，例如，`生产网关组`。 +* 如果服务处于“无版本”状态，请在 **版本** 字段中输入版本号（例如，“2.0.0”）。否则，将自动复制现有版本号，且无法编辑。 +* 点击 **同步**。 - * **网关组** 选择要同步去的目的网关组，例如 `生产网关组`。 - * 点击 **下一步**。 +:::Note -4. 在表单中执行以下操作： +首次同步服务后，请配置必要的[服务运行时配置](../key-concepts/services.md#service-runtime-configurations)并**启用**该服务以激活你的 API。对于后续的同步和发布，服务状态和运行时配置将继承先前版本。 -* **如何查找上游**，选择 `使用服务发现`。 -* **服务注册表** 选择 `生产用注册中心`，以及注册表中的命名空间和服务名称。 -* 确认服务信息，然后点击 **同步**。 +::: @@ -84,26 +64,34 @@ adc sync -f adc.yaml --gateway-group "Production Group" +## 配置服务运行时配置 + +1. 同步成功后，你将被重定向到目的地网关组上的已发布服务。 +2. 从侧边导航栏中选择 **上游**。 +3. 点击 **新增节点**。 +4. 在表单中执行以下操作： + +* **主机** 字段中，输入 `httpbin.org`。 +* **端口** 字段中，输入 `80`。 +* **权重** 字段中，输入 `100`。 +* 点击 **新增**。 + +5. 从已发布服务的顶部标题栏中点击 **启用** 并确认。 + ## 验证同步之后的 API 发送一个请求来验证同步到 `生产网关组` 上的 API： ```bash # 替换成生产网关组对应的地址 -curl "http://127.0.0.1:9080/headers" +curl "http://127.0.0.1:9080/ip" ``` 你应该能看到如下类似的响应： -```json +```text { - "headers": { - "Accept": "*/*", - "Host": "httpbin.org", - "User-Agent": "curl/7.74.0", - "X-Amzn-Trace-Id": "Root=1-6650ab7e-32c90eba787abbeb4e3dbb0c", - "X-Forwarded-Host": "127.0.0.1" - } + "origin": "127.0.0.1" } ``` From 19d2391d12d1435fb679d788fc4744e214d00952 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 15:40:00 +0800 Subject: [PATCH 21/24] Update services.md --- .../version-3.6.x/key-concepts/services.md | 31 +++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md b/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md index 7fe4dd82..c51bfb53 100644 --- a/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md +++ b/enterprise_versioned_docs/version-3.6.x/key-concepts/services.md @@ -53,11 +53,15 @@ slug: /key-concepts/services 以下配置被归类为运行时配置。这是因为当同一服务版本发布到不同网关组时，它们可能会有不同的值，而且可以在网关组内直接编辑。这些配置并不构成不同的版本。 * 上游配置 -* 服务发现 * 服务主机 * 路径前缀 +* 是否忽略路径前缀 +* 插件 +* 路由超时配置 -:::info +请注意，服务运行时配置可以针对每个网关组进行自定义，从而允许进行特定于环境的调整。这些配置与服务版本和服务模板无关，并且在每个网关组内独立管理。 + +:::note 例如 @@ -66,6 +70,29 @@ slug: /key-concepts/services ::: +## 服务ID vs 服务模板ID + +API7 企业版为服务使用了两个关键标识符：`服务模板ID` 和 `服务ID`，以及为路由和四层路由使用了类似的标识符。 + +* 服务模板仅有 `服务模板ID`。服务模板中的路由/四层路由仅有 `路由模板ID`/`四层路由模板ID`。 +* 网关组上已发布的服务同时具有 `服务模板ID` 和 `服务ID`，用于不同的用途。已发布服务中的路由/四层路由同时具有 `路由模板ID`/`四层路由模板ID` 和 `路由ID`/`四层路由ID`。 +* 历史版本仅有 `服务模板ID`。历史版本中的路由/四层路由仅有 `路由模板ID`/`四层路由模板ID`。 + +相比之下，`服务ID` 是特定于某个网关组中已发布的服务。你可以通过 ADC、管理 API 或 Ingress Controller 直接创建已发布的服务时自定义此 ID。 + +请注意，`服务ID` 仅在其所属的网关组内唯一。不同网关组上的两个已发布服务可以具有相同的 `服务ID`（不推荐）。 +**服务ID 不能用于权限策略。** + +`服务模板ID` 是自动生成的，作为在所有网关组中持久存在的唯一且不可变的标识符，用于服务版本控制。 +此 ID 适用于服务本身，包括服务模板、所有网关组中的所有已发布版本以及所有历史版本。 +它在权限策略中起着至关重要的作用，允许你根据服务的身份分配资源。 + +:::note + +路由ID vs 路由模板ID，四层路由ID vs 四层路由模板ID 类似。 + +::: + ## 相关阅读 * 核心概念 From a034ab23bab45f281838627429f00ce9b03f732c Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 15:43:41 +0800 Subject: [PATCH 22/24] Update enterprise_versions.json --- enterprise_versions.json | 1 + 1 file changed, 1 insertion(+) diff --git a/enterprise_versions.json b/enterprise_versions.json index 0696e693..f5e3c2d7 100644 --- a/enterprise_versions.json +++ b/enterprise_versions.json @@ -1,4 +1,5 @@ [ + "3.6.x", "3.5.x", "3.4.x", "3.3.x", From d329b6ac64095028dc471ddd13f21c8517d55089 Mon Sep 17 00:00:00 2001 From: sijingzhangzsj0604 Date: Wed, 26 Mar 2025 15:48:42 +0800 Subject: [PATCH 23/24] Update version-3.6.x-sidebars.json --- enterprise_versioned_sidebars/version-3.6.x-sidebars.json | 7 ------- 1 file changed, 7 deletions(-) diff --git a/enterprise_versioned_sidebars/version-3.6.x-sidebars.json b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json index 0ad47fbe..d8250111 100644 --- a/enterprise_versioned_sidebars/version-3.6.x-sidebars.json +++ b/enterprise_versioned_sidebars/version-3.6.x-sidebars.json @@ -110,13 +110,6 @@ "label": "Admin APIs", "href": "/enterprise/reference/admin-api" }, - { - "type": "category", - "label": "Upgrade Guides", - "items": [ - "upgrade-guides/breaking-changes" - ] - }, { "type": "category", "label": "开发参考", From d25d6ef3e40a756cb280347a8e8ac034180e4182 Mon Sep 17 00:00:00 2001 From: Zhihuang Lin <2228586315@qq.com> Date: Tue, 13 May 2025 11:36:32 +0800 Subject: [PATCH 24/24] Update enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md Co-authored-by: Yilia Lin <114121331+Yilialinn@users.noreply.github.com> --- .../version-3.6.x/api-security/upstream-mtls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md index 1204b0fb..3ac0ca20 100644 --- a/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md +++ b/enterprise_versioned_docs/version-3.6.x/api-security/upstream-mtls.md @@ -6,7 +6,7 @@ description: 按照本指南配置 API 网关和上游之间的相互 TLS (mTLS) Mutal TLS (mTLS) 是一种双向 TLS，客户端和服务器相互验证身份。它通常在对安全要求高的环境中采用，以防止未经授权的访问并加强安全性。 -本指南将引导你完成如何在 API7 网关 和上游服务之间配置 mTLS 的过程，使用 NGINX 作为示例上游服务。 +本指南将引导你完成如何在 API7 网关和上游服务之间配置 mTLS 的过程，使用 NGINX 作为示例上游服务。 ## 前提条件