APISIX Dashboard中文文档（一）

最新推荐文章于 2026-04-26 09:54:11 发布

原创最新推荐文章于 2026-04-26 09:54:11 发布 · 4.4k 阅读

本内容遵循CC 4.0 BY-SA版权协议

本文围绕APISIX Dashboard展开，介绍了用户指南，包括监控页面和路由模块。重点讲解导入OpenAPI 3.0文件创建路由，提及OAS3.0兼容性问题及扩展字段。给出不同用户场景下OAS3.0配置示例，还详细说明了管理API的API文档，涵盖各接口的简介、参数和返回信息。

2022年7月6日13:24:56

APISIX Dashboard中文文档(一)APISIX Dashboard中文文档(二)APISIX Dashboard中文文档(三)

官方文档：https://apisix.apache.org/zh/docs/dashboard/USER_GUIDE/

用户指南

以下是模块快照的一部分。

仪表板＃
我们通过在 iframe 中引用来支持监控页面。在访问 Grafana 之前，请启用 allow_embedding=true，默认为 false。由于安全策略，这会导致浏览器无法正确呈现 Grafana 页面。

路由＃
Route 模块旨在通过 UI 控制路由，而不是调用 API。

列表＃

创建＃

设置＃

导入 OpenAPI 指南

概述#
OpenAPI 规范 (OAS) 为 RESTful API 定义了一个与语言无关的标准接口，它允许人类和计算机在不访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。

Apache APISIX Dashboard 支持导入OpenApi3.0(我们将简称为 OAS3.0)文件，json并且yaml都支持，以创建一个或多个路由。目前我们支持大部分的 OpenApi 规范，但还是有一些区别，比如兼容性和扩展字段。

扩展字段#
APISIX Route 中有些字段是必填的，但 OAS3.0 的属性中没有包含，为了方便基于 OAS3.0 扩展自定义路由实体，我们增加了一些扩展字段，如上游、插件、主机等上。所有扩展都以 x-apisix 开头。

Extended fields	APISIX Route Properties
x-apisix-plugins	plugins
x-apisix-script	script
x-apisix-upstream	upstream
x-apisix-host	host
x-apisix-hosts	hosts
x-apisix-remote_addr	remote_addr
x-apisix-priority	priority
x-apisix-vars	vars
x-apisix-filter_func	filter_func
x-apisix-labels	labels
x-apisix-enable_websocket	enable_websocket
x-apisix-status	status
x-apisix-service_id	service_id
x-apisix-upstream_id	upstream_id

请注意，我们只扩展了第一级字段，子级字段仍然保持不变。以 x-apisix-upstream 为例。

...
# 我们在 OAS3.0 中添加 x-apisix-upstream 作为扩展字段代表上游
x-apisix-upstream:
  # x-apisix-upstream 的子字段仍然与上游的子字段保持一致
  type: roundrobin
  nodes:
    - host: 172.16.238.20
      port: 1980
      weight: 1
...

有关 APISIX 路由属性的更多详细信息，请参阅

OAS3.0 兼容性

当我们从 OAS3.0 导入路由时，会因为 APISIX 的 Route 中没有对应的字段而遗漏 OAS3.0 中的一些字段：

API General Info：用于描述你的API的一般信息，有时，一个OAS3.0文件包含一系列属于应用程序的 api，因此此信息不同于 api 的名称和额外的基本信息。

例子:

# this part of information will be missed
openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
...

API 服务器和基本路径：上游 url + url 前缀(选项)

例子:

# this part of information will be missed
...
servers:
  - url: https://api.example.com/v1
...

Path params: 路径中描述的 api 参数.

例子:

# 不管 uri 中有多少路径参数
# 从 OAS3.0 文件导入路由后，我们将得到带有 uri 的路由，如 `/get/*`
...
paths:
  /get/{id}/{name}:
    delete:
      operationId: api1DELETE
...

Query params: 查询中描述的 api 参数.

Example:

...
paths:
  /users:
    get:
      summary: Get a user by ID
      # this part of information will be missed
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get
...

Responses description and links: 定义 API 操作的响应.

Example:

...
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-service_id: service1
      # this part of information will be missed
      responses:
        '200':
          description: list response
        default:
          description: unexpected error
...

不同用户场景下OAS3.0配置示例

配置基本发布路由

提示：导入的路由默认的status为unpublished，表示该路由不能访问，如果要导入一个published的路由，需要在里面加上x-apisix-status: 1 你的OAS3.0文件

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello: # route uri
    get: # route method
      description: hello world. # route desc
      operationId: hello # route name
      x-apisix-upstream: # route upstream
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-status: 1 # the route will be published after imported
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

使用插件配置路由

提示:扩展字段支持的大多数插件 x-apisix-plugins

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-plugins:
        limit-count:
          count: 2
          time_window: 60
          rejected_code: 503
          key: remote_addr
          policy: local
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

配置带有参数验证的路由

提示:对于插件 request-validation，我们将使用参数序列化用于标头参数验证和描述请求正文用于 OAS3.0 中的正文参数验证

openapi: 3.0.0
info:
  version: "1"
  description: |-
    test desc
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    test title
paths:
  /hello:
    post:
      description: |-
        hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      parameters:
        - name: id
          in: header
          description: ID of pet to use
          required: true
          schema:
            type: string
          style: simple

      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              properties:
                name:
                  description: Update pet's name
                  type: string
                status:
                  description: Updated status of the pet
                  type: string
              required:
                - status
      responses:
        200:
          description: list response
        default:
          description: unexpected error

使用身份验证插件配置路由

注意: 对于插件 basic-auth jwt-auth 和 key-auth 我们将使用 Authentication 在 OAS3.0 中

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
openapi: 3.0.0
info:
  version: "1"
  description: |-
    test desc
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    test title
paths:
  /hello:
    post:
      description: |-
        hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      security:
        - basicAuth: []
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        200:
          description: list response
        default:
          description: unexpected error

配置现有服务或上游的路由

提示: 如果 APISIX 中不存在 service_id 或 upstream_id，从配置文件导入路由会报错

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-service_id: service1
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

配置多个路由

info:
  title: RoutesExport
  version: 3.0.0
openapi: 3.0.0
paths:
  /get:
    delete:
      operationId: api1Delete
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
    get:
      operationId: api1Get
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
  /post:
    post:
      operationId: test_post
      requestBody: {}
      responses:
        default:
          description: ''
      security: []
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v1
        version: v1
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []

管理API 的 API 文档

Manager API 直接操作 ETCD 并为 Apache APISIX 提供数据管理，为前端或其他客户端提供 API.

License: Apache License 2.0

/apisix/admin/migrate/export

GET

简介

导出配置文件以进行迁移

参数

None.

A file for download.

/apisix/admin/migrate/import

简介

导入配置文件以恢复配置

POST

参数 (FORM)

Name	Located in	Description	Required	Schema
mode	body(form)	import mode (return, skip or overwrite)	Yes	string
file	body(form)	file to upload	Yes	string

Code	Description	Schema
0	import success	ApiError
20001	Config conflict	ApiError

/apisix/admin/check_ssl_cert

POST

简介

验证 SSL 证书和密钥

参数

Name	Located in	Description	Required	Schema
cert	body	cert of SSL	Yes	string
key	body	key of SSL	Yes	string

Code	Description	Schema
0	SSL verify passed	ApiError
default	unexpected error	ApiError

/apisix/admin/check_ssl_exists

POST

简介

检查 SSL 是否存在

参数

Name	Located in	Description	Required	Schema
cert	body	cert of SSL	Yes	string
key	body	key of SSL	Yes	string

Code	Description	Schema
0	SSL exists	ApiError
default	unexpected error	ApiError

/apisix/admin/consumers

GET

简介

根据指定的页码和页面大小返回消费者列表，可以通过用户名搜索消费者。

参数

Name	Located in	Description	Required	Schema
page	query	page number	No	integer
page_size	query	page size	No	integer
username	query	username of consumer	No	string

Code	Description	Schema
0	list response	[ consumer ]
default	unexpected error	ApiError

/apisix/admin/notexist/routes

GET

简介

路由的返回结果通过名称和排除ID检查是否存在

参数

Name	Located in	Description	Required	Schema
name	query	name of route	No	string
exclude	query	id of route that exclude checking	No	string

Code	Description	Schema
0	route not exists	ApiError
default	unexpected error	ApiError

/apisix/admin/routes

GET

简介

根据指定的页码和页面大小返回路由列表，可以按名称和uri搜索路由

参数

Name	Located in	Description	Required	Schema
page	query	page number	No	integer
page_size	query	page size	No	integer
name	query	name of route	No	string
uri	query	uri of route	No	string
label	query	label of route	No	string

Code	Description	Schema
0	list response	[ route ]
default	unexpected error	ApiError

/apisix/admin/services

GET

简介

根据指定的页码和页面大小返回服务列表，并可按名称搜索服务

参数

Name	Located in	Description	Required	Schema
page	query	page number	No	integer
page_size	query	page size	No	integer
name	query	name of service	No	string

Code	Description	Schema
0	list response	[ service ]
default	unexpected error	ApiError

/apisix/admin/ssl

GET

简介

根据指定的页码和页面大小返回 SSL 列表，可以通过 sni 进行 SSL 搜索。

参数

Name	Located in	Description	Required	Schema
page	query	page number	No	integer
page_size	query	page size	No	integer
sni	query	sni of SSL	No	string

Code	Description	Schema
0	list response	[ ssl ]
default	unexpected error	ApiError

/apisix/admin/upstreams

GET

简介

根据指定的页码和页面大小返回上游列表，可以按名称搜索上游

参数

Name	Located in	Description	Required	Schema
page	query	page number	No	integer
page_size	query	page size	No	integer
name	query	name of upstream	No	string

Code	Description	Schema
0	list response	[ upstream ]
default	unexpected error	ApiError

/apisix/admin/user/login

POST

简介

用户登录.

参数

Name	Located in	Description	Required	Schema
username	body	user name	Yes	string
password	body	password	Yes	string

Code	Description	Schema
0	login success	ApiError
default	unexpected error	ApiError

Models

ApiError

Name	Type	Description	Required
code	long	response code	No
message	string	response message	No

BaseInfo

Name	Type	Required
create_time	long	No
id	object	No
update_time	long	No

Consumer

Name	Type	Required
create_time	long	No
desc	string	No
id	object	No
labels	object	No
plugins	object	No
update_time	long	No
username	string	No

LoginInput

Name	Type	Description	Required
password	string	password	No
username	string	user name	No

Route

Name	Type	Required
create_time	long	No
desc	string	No
enable_websocket	boolean	No
filter_func	string	No
host	string	No
hosts	[ string ]	No
id	object	No
labels	object	No
methods	[ string ]	No
name	string	No
plugins	object	No
priority	long	No
remote_addr	string	No
remote_addrs	[ string ]	No
script	object	No
service_id	object	No
service_protocol	string	No
update_time	long	No
upstream	UpstreamDef	No
upstream_id	object	No
uri	string	No
uris	[ string ]	No
vars	object	No

SSL

Name	Type	Required
cert	string	No
certs	[ string ]	No
create_time	long	No
exptime	long	No
id	object	No
key	string	No
keys	[ string ]	No
labels	object	No
sni	string	No
snis	[ string ]	No
status	long	No
update_time	long	No
validity_end	long	No
validity_start	long	No

Service

Name	Type	Required
create_time	long	No
desc	string	No
enable_websocket	boolean	No
id	object	No
labels	object	No
name	string	No
plugins	object	No
script	string	No
update_time	long	No
upstream	UpstreamDef	No
upstream_id	object	No

Upstream

Name	Type	Required
checks	object	No
create_time	long	No
desc	string	No
hash_on	string	No
id	object	No
k8s_deployment_info	object	No
key	string	No
labels	object	No
name	string	No
nodes	object	No
pass_host	string	No
retries	long	No
service_name	string	No
timeout	object	No
type	string	No
update_time	long	No
upstream_host	string	No

UpstreamDef

Name	Type	Required
checks	object	No
desc	string	No
hash_on	string	No
k8s_deployment_info	object	No
key	string	No
labels	object	No
name	string	No
nodes	object	No
pass_host	string	No
retries	long	No
service_name	string	No
timeout	object	No
type	string	No
upstream_host	string	No