APISIX 教程

1. 核心概念

APISIX 是一款云原生的开源 API 网关，专为微服务架构设计，提供了路由、负载均衡、认证、限流、监控等丰富的功能。它基于 Nginx 和 etcd 构建，具有高性能、可扩展性和可靠性。

1.1 基本概念

• 路由（Route）：定义如何将请求路由到上游服务，包含规则、方法、路径等。
• 上游（Upstream）：定义后端服务的集群，包含多个节点（Node）。
• 节点（Node）：后端服务的具体实例，包含 IP 地址和端口。
• 服务（Service）：定义后端服务的基本信息，如名称、上游等。
• 插件（Plugin）：扩展 APISIX 功能的组件，如认证、限流、监控等。
• 消费者（Consumer）：API 的使用者，用于认证和授权。
• SSL：SSL/TLS 证书，用于 HTTPS 服务。
• 服务发现：自动发现后端服务的机制，如 Nacos、Consul、Kubernetes 等。

1.2 工作原理

• 请求处理：接收客户端请求，根据路由规则匹配到对应的服务。
• 插件执行：按照配置的插件顺序执行插件逻辑，如认证、限流等。
• 负载均衡：如果服务配置了上游，则在多个节点之间进行负载均衡。
• 请求转发：将处理后的请求转发到后端服务。
• 响应处理：接收后端服务的响应，经过插件处理后返回给客户端。
• 配置管理：使用 etcd 存储配置，支持动态配置更新，无需重启。

2. 安装配置

2.1 安装 APISIX

2.1.1 使用 Docker 安装

# 启动 etcd
docker run -d --name etcd \n  -p 2379:2379 \n  -p 2380:2380 \n  -e ETCD_ADVERTISE_CLIENT_URLS=http://0.0.0.0:2379 \n  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \n  bitnami/etcd:latest

# 启动 APISIX
docker run -d --name apisix \n  -p 9080:9080 \n  -p 9443:9443 \n  -p 9091:9091 \n  -e APISIX_LISTEN_PORT=9080 \n  -e APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1 \n  --link etcd:etcd \n  -e APISIX_ETCD_ENDPOINTS=http://etcd:2379 \n  apache/apisix:latest

# 启动 APISIX Dashboard（可选）
docker run -d --name apisix-dashboard \n  -p 9000:9000 \n  -e APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1 \n  -e APISIX_ADMIN_API_HOST=apisix \n  -e APISIX_ADMIN_API_PORT=9091 \n  --link apisix:apisix \n  apache/apisix-dashboard:latest

2.1.2 使用 Helm 安装

# 添加 APISIX Helm 仓库
helm repo add apisix https://charts.apiseven.com

# 更新 Helm 仓库
helm repo update

# 安装 APISIX
helm install apisix apisix/apisix \n  --namespace apisix \n  --create-namespace \n  --set gateway.type=NodePort \n  --set admin.allow.ipList=0.0.0.0/0

# 安装 APISIX Dashboard
helm install apisix-dashboard apisix/apisix-dashboard \n  --namespace apisix \n  --set service.type=NodePort

2.1.3 从源码安装

可以从 APISIX 官方网站 下载源码，按照官方文档进行编译和安装。

2.2 配置 APISIX

2.2.1 配置文件

APISIX 的配置文件通常位于 /usr/local/apisix/conf/config.yaml，可以根据需要修改配置：

# 基本配置
apisix:
  node_listen: 9080  # 代理监听端口
  enable_ipv6: false

# 管理 API 配置
deployment:
  admin:
    allow_admin:  # 允许访问管理 API 的 IP 列表
      - 0.0.0.0/0
    admin_key:  # 管理 API 的密钥
      - name: "admin"
        key: "edd1c9f034335f136f87ad84b625c8f1"
        role: "admin"

# etcd 配置
etcd:
  host:  # etcd 服务器地址
    - "http://127.0.0.1:2379"
  prefix: "apisix"
  timeout: 30

# 插件配置
plugins:
  - name: "limit-count"
  - name: "key-auth"
  - name: "jwt-auth"
  - name: "basic-auth"
  - name: "cors"
  - name: "prometheus"
  - name: "zipkin"
  - name: "file-logger"

2.2.2 环境变量

# 常用环境变量
APISIX_LISTEN_PORT=9080  # 代理监听端口
APISIX_ADMIN_KEY=edd1c9f034335f136f87ad84b625c8f1  # 管理 API 密钥
APISIX_ETCD_ENDPOINTS=http://127.0.0.1:2379  # etcd 服务器地址
APISIX_ENABLE_IPV6=false  # 是否启用 IPv6

2.3 验证安装

# 检查 APISIX 状态
curl -i http://localhost:9091/status

# 查看已启用的插件
curl -i http://localhost:9091/plugins

# 访问 Dashboard
# http://localhost:9000

3. 基本使用

3.1 创建上游和路由

示例：创建上游和路由

# 创建上游
curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "backend-upstream",
    "name": "backend-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.10:8080": 100,
      "192.168.1.11:8080": 50
    }
  }'

# 创建路由
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "backend-route",
    "uri": "/api/*",
    "methods": ["GET", "POST", "PUT", "DELETE"],
    "upstream_id": "backend-upstream"
  }'

# 测试路由
curl -i http://localhost:9080/api/get

3.2 配置插件

示例：配置限流插件

# 创建路由并添加限流插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "rate-limit-route",
    "uri": "/api/rate-limit",
    "plugins": {
      "limit-count": {
        "count": 10,
        "time_window": 60,
        "policy": "local",
        "key": "remote_addr"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

# 测试限流
for i in {1..15}; do curl -i http://localhost:9080/api/rate-limit; done

3.3 配置服务和路由

示例：创建服务和路由

# 创建服务
curl -i -X POST http://localhost:9091/apisix/admin/services \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "backend-service",
    "name": "backend-service",
    "upstream_id": "backend-upstream"
  }'

# 创建路由并关联服务
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "service-route",
    "uri": "/api/service/*",
    "service_id": "backend-service"
  }'

# 测试路由
curl -i http://localhost:9080/api/service/get

3.4 配置 HTTPS

示例：配置 HTTPS

# 上传 SSL 证书
curl -i -X POST http://localhost:9091/apisix/admin/ssls \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "example-com-ssl",
    "cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
    "snis": ["example.com"]
  }'

# 创建 HTTPS 路由
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "https-route",
    "uri": "/api/https",
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

# 测试 HTTPS
curl -i -k https://localhost:9443/api/https/get

4. 高级功能

4.1 插件配置

示例：配置认证插件

# 创建消费者
curl -i -X POST http://localhost:9091/apisix/admin/consumers \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "user1",
    "username": "user1"
  }'

# 添加密钥认证
curl -i -X POST http://localhost:9091/apisix/admin/consumers/user1/plugins \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "key-auth": {
      "key": "secret-key"
    }
  }'

# 创建路由并添加密钥认证插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "auth-route",
    "uri": "/api/auth/*",
    "plugins": {
      "key-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

# 测试认证
curl -i http://localhost:9080/api/auth/get  # 应该返回 401
curl -i http://localhost:9080/api/auth/get -H "apikey: secret-key"  # 应该成功

示例：配置 CORS 插件

# 创建路由并添加 CORS 插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "cors-route",
    "uri": "/api/cors",
    "plugins": {
      "cors": {
        "allow_origins": "*",
        "allow_methods": "GET,POST,PUT,DELETE",
        "allow_headers": "Origin,Content-Type,Accept,Authorization",
        "allow_credentials": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

# 测试 CORS
curl -i -X OPTIONS http://localhost:9080/api/cors \n  -H "Origin: http://example.com" \n  -H "Access-Control-Request-Method: GET"

4.2 服务发现配置

示例：配置 Kubernetes 服务发现

# 创建上游并配置 Kubernetes 服务发现
curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "k8s-upstream",
    "name": "k8s-upstream",
    "type": "roundrobin",
    "discovery_type": "kubernetes",
    "service_name": "backend-service",
    "namespace": "default"
  }'

# 创建路由
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "k8s-route",
    "uri": "/api/k8s/*",
    "upstream_id": "k8s-upstream"
  }'

# 测试路由
curl -i http://localhost:9080/api/k8s/get

4.3 健康检查和熔断

示例：配置健康检查和熔断

# 创建上游并配置健康检查
curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "health-check-upstream",
    "name": "health-check-upstream",
    "type": "roundrobin",
    "nodes": {
      "192.168.1.10:8080": 100,
      "192.168.1.11:8080": 50
    },
    "checks": {
      "active": {
        "http_path": "/health",
        "host": "localhost",
        "port": 8080,
        "interval": 3,
        "timeout": 1,
        "fall": 3,
        "rise": 2
      }
    }
  }'

# 创建路由并添加熔断插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "circuit-breaker-route",
    "uri": "/api/circuit-breaker",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/get"
      },
      "limit-count": {
        "count": 10,
        "time_window": 60,
        "policy": "local",
        "key": "remote_addr"
      }
    },
    "upstream_id": "health-check-upstream"
  }'

4.4 监控和日志

示例：配置 Prometheus 插件

# 启用 Prometheus 插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "prometheus-route",
    "uri": "/apisix/prometheus/metrics",
    "plugins": {
      "prometheus": {}
    }
  }'

# 访问 Prometheus 指标
curl -i http://localhost:9080/apisix/prometheus/metrics

# 配置文件日志插件
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "file-log-route",
    "uri": "/api/log",
    "plugins": {
      "file-logger": {
        "path": "/var/log/apisix/access.log",
        "log_format": {
          "host": "$host",
          "uri": "$uri",
          "status": "$status",
          "remote_addr": "$remote_addr"
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

5. 最佳实践

5.1 配置最佳实践

• 使用路由和服务：为每个后端服务创建单独的路由和服务，便于管理和监控。
• 合理使用插件：只启用必要的插件，避免过多插件影响性能。
• 配置上游和节点：对于多个后端实例，使用上游和节点进行负载均衡。
• 启用健康检查：为上游配置健康检查，及时发现和排除故障实例。
• 使用服务发现：对于动态环境，使用服务发现自动发现后端服务。

5.2 性能优化

• 调整 Nginx 配置：根据硬件资源调整 Nginx 的 worker 进程数和连接数。
• 使用缓存：对于频繁请求的静态资源，使用缓存插件。
• 优化插件配置：合理配置插件参数，避免过度限制或监控。
• 使用 etcd 集群：对于生产环境，使用 etcd 集群提高可靠性。
• 启用 HTTP/2：对于 HTTPS 服务，启用 HTTP/2 提高传输效率。

5.3 安全最佳实践

• 使用 HTTPS：为所有服务启用 HTTPS，保护数据传输安全。
• 配置认证：为敏感 API 配置认证插件，限制访问。
• 启用 CORS：合理配置 CORS 插件，避免跨站请求伪造。
• 使用限流：为 API 配置限流插件，防止滥用和 DDoS 攻击。
• 定期更新：及时更新 APISIX 到最新版本，修复安全漏洞。

5.4 高可用配置

• 使用 etcd 集群：部署 etcd 集群，提高配置存储的可靠性。
• 部署多个 APISIX 实例：部署多个 APISIX 实例，使用负载均衡器分发请求。
• 配置健康检查：为 APISIX 实例配置健康检查，实现故障转移。
• 使用 Kubernetes 部署：在 Kubernetes 中使用 Deployment 或 DaemonSet 部署 APISIX，提高可用性。
• 定期备份：定期备份 etcd 数据，防止数据丢失。

6. 实用应用案例

6.1 微服务架构中的 API 网关

场景：在微服务架构中，使用 APISIX 作为 API 网关，管理服务间的通信，提供认证、限流、监控等功能。

配置：

# 创建上游
curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "user-upstream",
    "name": "user-upstream",
    "type": "roundrobin",
    "nodes": {
      "user-service:8000": 100
    }
  }'

curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "product-upstream",
    "name": "product-upstream",
    "type": "roundrobin",
    "nodes": {
      "product-service:8000": 100
    }
  }'

curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "order-upstream",
    "name": "order-upstream",
    "type": "roundrobin",
    "nodes": {
      "order-service:8000": 100
    }
  }'

# 创建服务
curl -i -X POST http://localhost:9091/apisix/admin/services \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "user-service",
    "name": "user-service",
    "upstream_id": "user-upstream"
  }'

curl -i -X POST http://localhost:9091/apisix/admin/services \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "product-service",
    "name": "product-service",
    "upstream_id": "product-upstream"
  }'

curl -i -X POST http://localhost:9091/apisix/admin/services \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "order-service",
    "name": "order-service",
    "upstream_id": "order-upstream"
  }'

# 创建路由
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "user-route",
    "uri": "/api/users/*",
    "service_id": "user-service",
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "local",
        "key": "remote_addr"
      }
    }
  }'

curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "product-route",
    "uri": "/api/products/*",
    "service_id": "product-service",
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "local",
        "key": "remote_addr"
      }
    }
  }'

curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "order-route",
    "uri": "/api/orders/*",
    "service_id": "order-service",
    "plugins": {
      "key-auth": {},
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "local",
        "key": "remote_addr"
      }
    }
  }'

# 创建消费者
curl -i -X POST http://localhost:9091/apisix/admin/consumers \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "app1",
    "username": "app1"
  }'

# 添加密钥认证
curl -i -X POST http://localhost:9091/apisix/admin/consumers/app1/plugins \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "key-auth": {
      "key": "app1-secret-key"
    }
  }'

6.2 Kubernetes 部署

场景：在 Kubernetes 集群中部署 APISIX，使用 Helm 进行管理。

配置：

# 添加 APISIX Helm 仓库
helm repo add apisix https://charts.apiseven.com

# 更新 Helm 仓库
helm repo update

# 创建命名空间
kubectl create namespace apisix

# 安装 APISIX
helm install apisix apisix/apisix \n  --namespace apisix \n  --set gateway.type=NodePort \n  --set admin.allow.ipList=0.0.0.0/0 \n  --set etcd.persistence.enabled=true \n  --set etcd.persistence.size=10Gi

# 安装 APISIX Dashboard
helm install apisix-dashboard apisix/apisix-dashboard \n  --namespace apisix \n  --set service.type=NodePort

# 查看 APISIX 资源
kubectl get all -n apisix

# 创建 Ingress
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: apisix-ingress
  namespace: apisix
  annotations:
    kubernetes.io/ingress.class: apisix
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 80
EOF

6.3 服务发现集成

场景：使用 APISIX 集成 Kubernetes 服务发现，自动发现后端服务。

配置：

# 创建上游并配置 Kubernetes 服务发现
curl -i -X POST http://localhost:9091/apisix/admin/upstreams \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "k8s-discovery-upstream",
    "name": "k8s-discovery-upstream",
    "type": "roundrobin",
    "discovery_type": "kubernetes",
    "service_name": "backend-service",
    "namespace": "default"
  }'

# 创建路由
curl -i -X POST http://localhost:9091/apisix/admin/routes \n  -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \n  -d '{
    "id": "k8s-discovery-route",
    "uri": "/api/k8s/*",
    "upstream_id": "k8s-discovery-upstream"
  }'

# 测试路由
curl -i http://localhost:9080/api/k8s/get

7. 总结

APISIX 是一款功能强大的云原生 API 网关，专为微服务架构设计，提供了路由、负载均衡、认证、限流、监控等丰富的功能。它基于 Nginx 和 etcd 构建，具有高性能、可扩展性和可靠性。

通过本教程的学习，您应该已经掌握了 APISIX 的核心概念、安装配置、基本使用、高级功能和最佳实践。在实际应用中，您可以根据具体的需求，灵活配置 APISIX，以满足不同场景的要求。

7.1 核心优势

• 功能丰富：提供了路由、负载均衡、认证、限流、监控等丰富的功能。
• 可扩展性：通过插件系统，可以轻松扩展功能。
• 高性能：基于 Nginx 和 etcd，具有高性能和可靠性。
• 易于使用：提供了 RESTful API 和 Dashboard，便于管理和配置。
• 丰富的集成：支持与 Kubernetes、Nacos、Consul 等工具集成。
• 开源免费：开源软件，免费使用。

7.2 应用前景

随着微服务架构的普及，API 网关的需求越来越高。APISIX 作为一款成熟的 API 网关，在以下场景中有着广泛的应用前景：

• 微服务架构：作为微服务架构的入口点，管理服务间的通信。
• API 管理：管理和监控 API 的使用，提供认证和限流。
• 服务网格：在服务网格中作为控制平面，管理服务间的通信。
• 多环境部署：在开发、测试和生产环境中统一管理 API。
• 云原生应用：与 Kubernetes 等云原生工具集成，提供完整的 API 管理解决方案。

通过不断学习和实践 APISIX 的功能和最佳实践，您可以充分发挥 APISIX 的优势，构建现代化、可靠、安全的 API 管理系统。