APISIX Dashboard 使用指南：路由、服务、上游与插件配置实践
APISIX Dashboard 是 APISIX 的可视化管理界面，可以通过页面方式管理 Route、Service、Upstream、Consumer、SSL 证书和插件配置。对于学习 APISIX 或进行日常运维，Dashboard 能降低上手成本。
不过需要先说明：APISIX 的核心配置入口始终是 Admin API，Dashboard 本质上是对 Admin API 的可视化封装。新版本部署和生产选型时，应以 APISIX 官方文档对 Dashboard 的说明为准；如果团队已经具备自动化能力，也可以优先使用 Admin API、APISIX Ingress Controller 或声明式配置工具来管理配置。
如果还不了解 APISIX 的基础概念，可以先看：APISIX 入门指南：核心概念、Docker 部署与基础路由配置。
Dashboard 能做什么
常见能力包括：
- 管理路由 Route。
- 管理服务 Service。
- 管理上游 Upstream。
- 配置插件 Plugin。
- 管理 Consumer。
- 配置证书 SSL。
- 查看部分运行状态和基础信息。
Dashboard 适合：
- 学习和演示 APISIX。
- 中小规模网关配置管理。
- 运维人员快速查看路由和插件配置。
- 对 Admin API 不熟悉时做可视化操作。
但生产环境仍建议：
- 配置变更纳入审批和审计。
- 关键配置通过 Git 管理。
- 避免多人直接在页面上无记录修改。
- Dashboard 只开放给可信内网和授权人员。
部署前准备
Dashboard 需要连接 APISIX 使用的 etcd，因此配置时要确保：
- Dashboard 能访问 etcd 地址。
- etcd 地址与 APISIX 网关使用的是同一套配置中心。
- 如果 etcd 开启认证，需要配置用户名和密码。
- 如果 etcd 开启 mTLS，需要配置证书。
典型配置关注点：
conf:
listen:
host: 0.0.0.0
port: 9000
allow_list:
- 127.0.0.1
- 10.0.0.0/8
etcd:
endpoints:
- 10.0.0.11:2379
- 10.0.0.12:2379
- 10.0.0.13:2379
# username: "root"
# password: "password"
安全建议：
- 不要把 Dashboard 暴露到公网。
- 不要使用弱密码。
- 配置
allow_list限制访问来源。 - 结合反向代理、HTTPS、统一认证或 VPN 使用。
安装方式
Dashboard 常见安装方式包括：
- Docker。
- RPM / 二进制包。
- Kubernetes / Helm。
实际部署方式应以当前官方文档和项目版本为准。下面给出通用思路。
Docker 部署思路
准备配置文件 conf.yaml 后挂载到容器中：
docker run -d \
--name apisix-dashboard \
-p 9000:9000 \
-v $(pwd)/conf.yaml:/usr/local/apisix-dashboard/conf/conf.yaml \
apache/apisix-dashboard:latest
生产环境不建议直接使用 latest，应固定版本号并记录变更。
RPM / 二进制部署思路
安装后通常需要：
- 修改 Dashboard 配置文件。
- 配置 etcd endpoints。
- 配置访问控制和账号。
- 启动 Dashboard 服务。
- 通过浏览器访问管理界面。
访问 Dashboard
默认访问地址通常类似：
http://<dashboard-host>:9000
如果无法访问，优先检查：
- Dashboard 进程是否启动。
- 9000 端口是否监听。
- 防火墙或安全组是否放行。
allow_list是否允许当前客户端 IP。- Dashboard 日志中是否存在 etcd 连接失败。
路由配置
Route 是 APISIX 的请求匹配规则。在 Dashboard 中配置路由时，通常需要关注：
- 路由名称。
- URI，例如
/api/users/*。 - Host，例如
api.example.com。 - 请求方法，例如 GET、POST。
- 上游服务或 Upstream。
- 插件配置。
建议命名规范：
业务域-服务名-接口类型
例如：
mall-user-query
mall-order-create
这样在路由数量增多后更容易检索和维护。
上游配置
Upstream 用于管理后端节点和负载均衡策略。
常见字段：
| 字段 | 说明 |
|---|---|
| nodes | 后端节点列表和权重 |
| type | 负载均衡算法，如 roundrobin |
| timeout | 连接、发送、读取超时 |
| retries | 重试次数 |
| checks | 健康检查配置 |
示例：
{
"type": "roundrobin",
"nodes": {
"10.0.0.11:8080": 1,
"10.0.0.12:8080": 1
},
"timeout": {
"connect": 3,
"send": 3,
"read": 5
}
}
生产建议：
- 为关键服务配置合理超时。
- 根据服务能力设置权重。
- 对核心服务启用健康检查。
- 避免把测试节点混入生产 Upstream。
服务配置
Service 用于复用公共配置。多个 Route 可以引用同一个 Service。
适合放在 Service 层的配置：
- 公共 Upstream。
- 公共认证插件。
- 公共限流策略。
- 公共日志插件。
使用 Service 的好处是减少重复配置。例如同一个用户服务有多个 API 路由，就可以让它们引用同一个 user-service。
插件配置
APISIX 的插件非常丰富，Dashboard 中通常会按类别展示。
流量控制类
常见插件：
limit-count：固定时间窗口请求数限制。limit-req：请求速率限制。limit-conn：并发连接数限制。
适用场景：
- 防止下游被突发流量打垮。
- 对不同租户或调用方做访问控制。
- 对高成本接口做保护。
安全防护类
常见插件：
key-auth。jwt-auth。basic-auth。ip-restriction。cors。
建议：
- 对公网 API 必须配置认证鉴权。
- 对管理类接口增加 IP 白名单。
- CORS 不要无脑配置
*，要结合业务域名控制。
可观测性和日志类
常见插件：
prometheus。http-logger。kafka-logger。skywalking-logger。zipkin/ tracing 相关能力。
日志采集可以参考：APISIX kafka-logger 日志采集实践：写入 Kafka 并接入 Elasticsearch / Kibana。
流量治理类
常见插件：
proxy-mirror：流量镜像。traffic-split：流量切分。mocking：模拟响应。fault-injection：故障注入。
Mock 和流量镜像可以参考：
证书配置
如果需要 HTTPS，可以在 Dashboard 中配置 SSL 证书。
注意事项：
- 证书和私钥需要匹配。
- SNI 要与访问域名一致。
- 证书过期前要提前续期。
- 私钥不要泄露到代码仓库或截图中。
配置变更建议
Dashboard 操作虽然方便，但生产环境要避免“点页面直接改生产”的不可追踪问题。
建议流程：
- 测试环境验证配置。
- 记录配置变更内容。
- 评估影响范围和回滚方案。
- 在低峰期发布。
- 观察网关日志、错误率和下游指标。
- 变更后沉淀为文档或配置文件。
常见问题
1. Dashboard 无法连接 etcd
检查：
- etcd endpoints 是否正确。
- Dashboard 容器网络是否能访问 etcd。
- etcd 是否开启认证。
- 证书配置是否正确。
2. Dashboard 上创建路由后不生效
检查：
- Dashboard 连接的 etcd 是否与 APISIX 使用的 etcd 一致。
- APISIX 是否正常监听网关端口。
- Route 匹配条件是否正确。
- 是否存在更高优先级路由抢先匹配。
3. 插件配置后请求异常
检查：
- 插件 JSON Schema 是否符合要求。
- 插件是否绑定在正确层级。
- 插件执行顺序是否影响请求。
- APISIX 日志中是否有 schema 校验错误。
总结
APISIX Dashboard 的价值在于降低网关配置门槛，但它不应该替代配置治理。生产环境更重要的是：
- 明确 Route、Service、Upstream、Plugin 的职责边界。
- 控制 Dashboard 访问权限。
- 对配置变更做审计和回滚。
- 与 Admin API、Ingress Controller 或声明式配置工具配合使用。