juzhiyuan commented on code in PR #8145: URL: https://github.com/apache/apisix/pull/8145#discussion_r1003928997
########## docs/zh/latest/admin-api.md: ########## @@ -23,76 +31,119 @@ title: Admin API ## 描述 -Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理，请参阅 [Architecture Design](./architecture-design/apisix.md) 中的文档。 +Admid API 是一组用于配置 Apache APISIX 路由、上游、服务、SSL 证书等功能的 RESTful API。 Review Comment: ```suggestion Admin API 是一组用于配置 Apache APISIX 路由、上游、服务、SSL 证书等功能的 RESTful API。 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -449,140 +575,177 @@ service 对象 json 配置内容： } ``` -具体示例： +### 使用示例： Review Comment: ```suggestion ### 使用示例 ``` ########## docs/zh/latest/admin-api.md: ########## @@ -23,76 +31,119 @@ title: Admin API ## 描述 -Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理，请参阅 [Architecture Design](./architecture-design/apisix.md) 中的文档。 +Admid API 是一组用于配置 Apache APISIX 路由、上游、服务、SSL 证书等功能的 RESTful API。 -启动 Apache APISIX 时，默认情况下 Admin API 将监听 `9180` 端口。您可以通过修改 [conf/config.yaml](https://github.com/apache/apisix/blob/master/conf/config.yaml) 文件来改变默认监听的端口。 +你可以通过 Admin API 来获取、创建、更新以及删除资源。同时得益于 APISIX 的热加载能力，资源配置完成后 APISIX 将会自动更新配置，无需重启服务。如果你想要了解其工作原理，请参考 [Architecture Design](./architecture-design/apisix.md)。 -在下面出现的 `X-API-KEY` 指的是 `conf/config.yaml` 文件中的 `deployment.admin.admin_key.key`，它是 Admin API 的访问 token。 +## 相关配置 -## V3 +当 APISIX 启动时，Admin API 默认情况下将会监听 `9180` 端口，并且会占用前缀为 `/apisix/admin` 的 API。 -Admin API 在 V3 版本中做了一些不向下兼容的调整，以及支持更多特性。 +因此，为了避免你设计的 API 与 `/apisix/admin` 冲突，你可以通过修改配置文件 [`/conf/config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) 中的配置修改默认监听端口。 -### 支持新的响应体格式 +APISIX 支持设置 Admin API 的 IP 访问白名单，防止 APISIX 被非法访问和攻击。你可以在 `./conf/config.yaml` 文件中的 `deployment.admin.allow_admin` 选项中，配置允许访问的 IP 地址。 -1. 移除响应体中的 `action` 字段； -2. 调整获取资源列表时的响应体结构，新的响应体结构示例如下： +在下文出现的 `X-API-KEY` 指的是 `./conf/config.yaml` 文件中的 `deployment.admin.admin_key.key`，它是 Admin API 的访问 token。 -返回单个资源： +:::tip 提示 -```json -{ - "modifiedIndex": 2685183, - "value": { - "id": "1", - ... - }, - "key": "/apisix/routes/1", - "createdIndex": 2684956 -} +建议你修改 Admin API 默认的监听端口、IP 访问白名单以及 Admin API 的 token，以保证你的 API 安全。 + +::: + +```yaml title="./conf/config.yaml" +deployment: + admin: + admin_key: + - name: admin + key: edd1c9f034335f136f87ad84b625c8f1 # using fixed API token has security risk, please update it when you deploy to production environment + role: admin + allow_admin: # http://nginx.org/en/docs/http/ngx_http_access_module.html#allow + - 127.0.0.0/24 + 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. Review Comment: Any plan to update those comments in Chinese? ########## docs/zh/latest/admin-api.md: ########## @@ -449,140 +575,177 @@ service 对象 json 配置内容： } ``` -具体示例： +### 使用示例： Review Comment: Note: when using Chinese as a Heading, I suggest adding an English hash. I forget how to set custom anchor 😅 ```suggestion ### 使用示例 {xxxx} ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
