Felix's Blog

Apisix

felix.shao2025-07-19

Apisix

TIP

 API KEY 说明如下。

  • 我们先关闭 api 权限，先 apisix 入门，打开 api 权限后，对应 curl 接口添加 -H "X-API-KEY: xx" 即可。
  • 便捷查看 API KEY 命令：docker exec apisix cat /usr/local/apisix/conf/config.yaml | grep -A 5 "admin_key"。

1 安装

1.1 docker 安装

1 etcd 服务安装

 apisix 默认使用 etcd 存储配置，先启动一个 etcd 实例。

docker pull bitnami/etcd:3.4.15

docker run -d \
  --name etcd \
  -p 2379:2379 \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://0.0.0.0:2379 \
  -e ETCD_ENABLE_V2="true" \
  bitnami/etcd:3.4.15
  
# 启动日志查看
docker logs etcd

# 查看状态
curl -L http://127.0.0.1:2379/version

# V2 API 查看，apisix dashboard 需要开启此功能
curl -XPUT http://localhost:2379/v2/keys/test -d value="testvalue"
2 apisix 服务安装
 2.1 启动 apisix 容器

 先启动 apisix，启动成功后，我们修改下配置完善安装。

# 版本是 3.13.0
docker pull apache/apisix:latest

docker run -d \
  --name apisix \
  -p 9080:9080 -p 9180:9180 -p 9443:9443 \
  -e APISIX_DEPLOYMENT_ETCD_HOST='["http://192.168.37.200:2379"]' \
  -e APISIX_DEPLOYMENT_ETCD_PREFIX=/apisix \
  apache/apisix:latest

# 启动日志查看
docker logs apisix
 2.2 修改配置

 修改配置，尤其是 api 权限，我们先关闭 api 权限，入门。
 我们直接将宿主机的配置，拿出来修改后，再替换回去，重新启动容器即可。

  1. 拷贝源配置，docker cp apisix:/usr/local/apisix/conf/config.yaml /mnt/hgfs/apisix/。
  2. 编辑配置，vim config.yaml。
deployment:
  admin:
    allow_admin:
    - 0.0.0.0/0
    admin_key_required: false

# 启用 server-info 插件，dashboard 可以读取节点信息
plugins:
- server-info
  1. 覆盖源配置，docker cp /mnt/hgfs/apisix/config.yaml apisix:/usr/local/apisix/conf/config.yaml。
  2. 重启容器，docker restart apisix。

 配置好后测试。

# 查看版本
apisix version
# 查看 apisix 服务管理接口
curl -i http://127.0.0.1:9180/apisix/admin/services
# 测试 apisix 路由管理接口
curl -v http://127.0.0.1:9180/apisix/admin/routes
# 查看生成的 nginx 配置，复制出来查看 docker cp apisix:/usr/local/apisix/conf/nginx.conf /mnt/hgfs/apisix/
docker exec -it apisix cat /usr/local/apisix/conf/nginx.conf
3 dashboard 服务安装
 3.1 安装 Dashboard

 APISIX 的默认安装不包含 Web 管理界面（Dashboard），Dashboard 需要独立安装。

# pull 镜像
docker pull apache/apisix-dashboard

# 启动容器，我们用 host 模式启动，注意端口是 -p 9000:9000 
docker run -d --name apisix-dashboard \
  --network host \
  -e APISIX_API_URL=http://192.168.37.200:9180/apisix/admin \
  apache/apisix-dashboard

# 验证
docker logs apisix-dashboard

# 页面访问 http://192.168.37.200:9000, ip 未允许等，我们继续下一步修改配置
 3.2 修改配置

 快捷查看配置，docker exec asdboard cat /usr/local/apisix-dashboard/conf/conf.yaml。

  1. 拷贝源配置，docker cp apisix-dashboard:/usr/local/apisix-dashboard/conf/conf.yaml /mnt/hgfs/apisix/。
  2. 编辑配置，vim /mnt/hgfs/apisix/conf.yaml
conf:
  listen:
    host: 0.0.0.0       
  allow_list:            
    - 0.0.0.0/0           
    - ::1                
  etcd:
    endpoints:            
      - "http://192.168.37.200:2379"

# 待定配置
conf:
  authentication:
    disable: true  # 关闭所有认证（不安全，仅用于测试）
  apisix:
    base_url: "http://192.168.37.200:9180"  # 必须带协议
    admin_key:
      - name: admin
        key: UbrAqgqQJozITWigzEycrebMMfWQgmud
        role: admin
  1. 覆盖源配置，docker cp /mnt/hgfs/apisix/conf.yaml apisix-dashboard:/usr/local/apisix-dashboard/conf/conf.yaml。
  2. 重启容器, docker restart apisix-dashboard。

 打开地址测试 dashboardopen in new window。允许的用户在 conf.yaml 文件中，默认有两个 admin/admin，user/user。

 3.3 新增路由

 登录 dashboardopen in new window，新增 route，页面依次执行 点击菜单 route --> 点击 create 按钮，在打开的窗口里面按步骤配置路由即可，以下的新增的示例路由关键信息。

  • 第一页
    • name: getting-started-get
    • path: /get,注意上游服务要有对应的路径处理，不然会是 404，或者用重写路径插件处理
    • http-method: all。
  • 第二页
    • host: httpbin.org
    • post: 80

&emsp:进入到第三页，直接提交。
 验证：执行命令 curl http://127.0.0.1:9080/get，

4 启用 admin_key
 4.1 apisix 配置变更
  1. 拷贝源配置，docker cp apisix:/usr/local/apisix/conf/config.yaml /mnt/hgfs/apisix/。
  2. 编辑配置，vim config.yaml。
deployment:
  admin:
    admin_key_required: true
  1. 覆盖源配置，docker cp /mnt/hgfs/apisix/config.yaml apisix:/usr/local/apisix/conf/config.yaml。
  2. 重启容器，docker restart apisix。

 记录下 deployment.etcd.admin.admin_key: ifbfNwzoolkkOYloFUfIcxHMSsZQlDJb，后续会用到。
 测试。

  • 未授权测试命令，curl -i http://127.0.0.1:9180/apisix/admin/services。
  • 已授权测试命令，curl -i http://127.0.0.1:9180/apisix/admin/services -H "X-API-KEY: ifbfNwzoolkkOYloFUfIcxHMSsZQlDJb"。

 验证下来 dashboard 不需要配置 api key。
 待研究 http://192.168.37.200:9000/apisix/dashboard，会报 {"code":4107,"message":"request unauthorized"}。

2 快速入门

 按步骤执行，因为后续的步骤依赖于前面的一些步骤。

2.1 配置路由

创建路由
curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-ip",
  "uri": "/ip",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'
验证

 curl "http://127.0.0.1:9080/ip"，以下是结果。

{
  "origin": "172.17.0.1, 61.170.149.74"
}

2.2 负载均衡

创建路由
curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "getting-started-headers",
  "uri": "/headers",
  "upstream" : {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:443": 1,
      "mock.api7.ai:443": 1
    },
    "pass_host": "node",
    "scheme": "https"
  }
}'
验证

 curl "http://127.0.0.1:9080/headers"，执行 2 次，返回结果会不一样。

2.3 认证

创建消费者

 创建一些消费者，密钥是 secret-key。

curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT -d '
{
  "username": "tom",
  "plugins": {
    "key-auth": {
      "key": "secret-key"
    }
  }
}'
启用认证
curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {}
  }
}'
禁用认证
curl "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {
      "_meta": {
        "disable": true
      }
    }
  }
}'
验证

 按不同场景进行验证。

# 1 直接验证
curl -i "http://127.0.0.1:9080/ip"
# 2 错误的 key 验证
curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key'
# 3 正确的 key 验证
curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key'

2.4 限流

启用限流

 创建一些消费者，密钥是 secret-key。

curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "limit-count": {
        "count": 2,
        "time_window": 10,
        "rejected_code": 503
     }
  }
}'
禁用限流
curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
    "plugins": {
        "limit-count": {
            "_meta": {
                "disable": true
            }
        }
    }
}'
验证

 注意关闭认证插件，否则会影响测试结果。
 跑一百次，再启用、禁用限流插件时查看结果。

count=$(seq 100 | xargs -i curl "http://127.0.0.1:9080/ip" -I -sL | grep "503" | wc -l); echo \"200\": $((100 - $count)), \"503\": $count

3 进阶

路由配置说明

 问题：apisix 创建的 route path 配置，在 nginx 配置中看不到。
 原因如下。

  • 1 动态配置机制：
    • APISIX 使用 etcd 或其它存储后端动态管理路由配置
    • 路由规则不会硬编码在 nginx.conf 中，而是通过 Lua 代码动态加载
  • 2 运行时处理：
    • 路由匹配是在运行时由 APISIX 的 Lua 代码处理的
    • 实际的路径匹配发生在 apisix/http/route.lua 等模块中
  • 3 性能优化：
    • 避免每次路由变更都重载 Nginx 配置
    • 路由信息存储在共享内存中供所有 worker 进程访问

 实际生效配置可以通过以下方式查看。

  • 通过 Admin API 查看。
  • 检查 etcd 中的数据。
  • 查看运行时信息。
  • 检查 APISIX 日志（调试模式）。

附录一、参考文献

Last Updated 7/20/2025, 12:38:03 PM
ON THIS PAGE