Kong API网关配置 - 在线学习与练习平台

1. Kong核心概念

1.1 基本实体

1.1.1 Service（服务）

服务是Kong中的核心实体，代表后端API或微服务。

# 创建服务
curl -X POST http://localhost:8001/services \
  --data "name=my-service" \
  --data "url=http://httpbin.org"

# 查看服务
curl http://localhost:8001/services/my-service

1.1.2 Route（路由）

路由定义了请求如何被代理到服务。

# 创建路由
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=my-route" \
  --data "paths[]=/api/v1"

# 查看路由
curl http://localhost:8001/routes/my-route

1.1.3 Consumer（消费者）

消费者代表API的使用者，用于认证和授权。

# 创建消费者
curl -X POST http://localhost:8001/consumers \
  --data "username=john" \
  --data "custom_id=user123"

# 查看消费者
curl http://localhost:8001/consumers/john

1.1.4 Plugin（插件）

插件为服务、路由或消费者添加功能。

# 为服务添加插件
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=100"

1.1.5 Upstream（上游）

上游代表虚拟主机名，用于负载均衡。

# 创建上游
curl -X POST http://localhost:8001/upstreams \
  --data "name=my-upstream" \
  --data "algorithm=round-robin"

1.1.6 Target（目标）

目标是上游的后端服务实例。

# 添加目标
curl -X POST http://localhost:8001/upstreams/my-upstream/targets \
  --data "target=192.168.1.10:8080" \
  --data "weight=100"

1.2 实体关系

Consumer ──┐
           ├── Plugin
Service ───┤
           └── Route ──── Plugin
           
Upstream ──── Target

2. 服务配置

2.1 基本服务配置

2.1.1 HTTP服务

# 创建HTTP服务
curl -X POST http://localhost:8001/services \
  --data "name=http-service" \
  --data "protocol=http" \
  --data "host=api.example.com" \
  --data "port=80" \
  --data "path=/v1"

2.1.2 HTTPS服务

# 创建HTTPS服务
curl -X POST http://localhost:8001/services \
  --data "name=https-service" \
  --data "protocol=https" \
  --data "host=secure-api.example.com" \
  --data "port=443" \
  --data "path=/api"

2.1.3 使用URL简化配置

# 使用完整URL创建服务
curl -X POST http://localhost:8001/services \
  --data "name=simple-service" \
  --data "url=https://api.example.com:443/v2"

2.2 高级服务配置

2.2.1 连接超时设置

curl -X POST http://localhost:8001/services \
  --data "name=timeout-service" \
  --data "url=http://slow-api.example.com" \
  --data "connect_timeout=5000" \
  --data "write_timeout=10000" \
  --data "read_timeout=10000"

2.2.2 重试配置

curl -X POST http://localhost:8001/services \
  --data "name=retry-service" \
  --data "url=http://unreliable-api.example.com" \
  --data "retries=3"

2.2.3 客户端证书配置

curl -X POST http://localhost:8001/services \
  --data "name=cert-service" \
  --data "url=https://client-cert-api.example.com" \
  --data "client_certificate=cert-id" \
  --data "tls_verify=true"

2.3 服务管理

2.3.1 查看所有服务

curl http://localhost:8001/services

2.3.2 更新服务

curl -X PATCH http://localhost:8001/services/my-service \
  --data "connect_timeout=3000"

2.3.3 删除服务

curl -X DELETE http://localhost:8001/services/my-service

3. 路由配置

3.1 基本路由配置

3.1.1 路径匹配

# 精确路径匹配
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=exact-path" \
  --data "paths[]=/api/users"

# 前缀匹配
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=prefix-path" \
  --data "paths[]=/api/v1" \
  --data "strip_path=true"

# 正则表达式匹配
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=regex-path" \
  --data "paths[]=~/api/v\\d+/users"

3.1.2 主机匹配

# 单个主机
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=host-route" \
  --data "hosts[]=api.example.com"

# 多个主机
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=multi-host" \
  --data "hosts[]=api.example.com" \
  --data "hosts[]=api.test.com"

# 通配符主机
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=wildcard-host" \
  --data "hosts[]=*.api.example.com"

3.1.3 方法匹配

# 特定HTTP方法
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=method-route" \
  --data "methods[]=GET" \
  --data "methods[]=POST" \
  --data "paths[]=/api/data"

3.1.4 头部匹配

# 基于请求头匹配
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=header-route" \
  --data "headers.x-api-version=v1" \
  --data "paths[]=/api"

3.2 高级路由配置

3.2.1 协议配置

# 仅HTTPS
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=https-only" \
  --data "protocols[]=https" \
  --data "paths[]=/secure"

# HTTP和HTTPS
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=both-protocols" \
  --data "protocols[]=http" \
  --data "protocols[]=https" \
  --data "paths[]=/flexible"

3.2.2 路径处理

# 保留路径
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=preserve-path" \
  --data "paths[]=/api/v1" \
  --data "strip_path=false"

# 去除路径前缀
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=strip-path" \
  --data "paths[]=/api/v1" \
  --data "strip_path=true"

# 路径重写
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=rewrite-path" \
  --data "paths[]=/old-api" \
  --data "strip_path=true"
# 配合request-transformer插件使用

3.2.3 优先级配置

# 设置路由优先级
curl -X POST http://localhost:8001/services/my-service/routes \
  --data "name=high-priority" \
  --data "paths[]=/api" \
  --data "regex_priority=100"

3.3 复杂路由示例

3.3.1 API版本路由

# v1 API路由
curl -X POST http://localhost:8001/services/api-v1/routes \
  --data "name=api-v1" \
  --data "hosts[]=api.example.com" \
  --data "paths[]=/v1" \
  --data "strip_path=true"

# v2 API路由
curl -X POST http://localhost:8001/services/api-v2/routes \
  --data "name=api-v2" \
  --data "hosts[]=api.example.com" \
  --data "paths[]=/v2" \
  --data "strip_path=true"

# 默认版本路由
curl -X POST http://localhost:8001/services/api-v2/routes \
  --data "name=api-default" \
  --data "hosts[]=api.example.com" \
  --data "paths[]=~/^(?!/v[12]).*" \
  --data "regex_priority=1"

3.3.2 移动端专用路由

# 移动端API路由
curl -X POST http://localhost:8001/services/mobile-api/routes \
  --data "name=mobile-route" \
  --data "hosts[]=api.example.com" \
  --data "paths[]=/mobile" \
  --data "headers.user-agent=~*mobile|android|iphone" \
  --data "strip_path=true"

4. 负载均衡配置

4.1 上游配置

4.1.1 基本上游

# 创建上游
curl -X POST http://localhost:8001/upstreams \
  --data "name=backend-api" \
  --data "algorithm=round-robin"

4.1.2 负载均衡算法

# 轮询算法
curl -X POST http://localhost:8001/upstreams \
  --data "name=round-robin-upstream" \
  --data "algorithm=round-robin"

# 一致性哈希
curl -X POST http://localhost:8001/upstreams \
  --data "name=consistent-hashing" \
  --data "algorithm=consistent-hashing" \
  --data "hash_on=ip"

# 最少连接
curl -X POST http://localhost:8001/upstreams \
  --data "name=least-connections" \
  --data "algorithm=least-connections"

4.1.3 健康检查配置

curl -X POST http://localhost:8001/upstreams \
  --data "name=health-checked-upstream" \
  --data "algorithm=round-robin" \
  --data "healthchecks.active.type=http" \
  --data "healthchecks.active.http_path=/health" \
  --data "healthchecks.active.healthy.interval=30" \
  --data "healthchecks.active.unhealthy.interval=10" \
  --data "healthchecks.passive.healthy.successes=3" \
  --data "healthchecks.passive.unhealthy.http_failures=3"

4.2 目标配置

4.2.1 添加目标

# 添加后端服务器
curl -X POST http://localhost:8001/upstreams/backend-api/targets \
  --data "target=192.168.1.10:8080" \
  --data "weight=100"

curl -X POST http://localhost:8001/upstreams/backend-api/targets \
  --data "target=192.168.1.11:8080" \
  --data "weight=100"

curl -X POST http://localhost:8001/upstreams/backend-api/targets \
  --data "target=192.168.1.12:8080" \
  --data "weight=50"

4.2.2 动态权重调整

# 降低权重（灰度发布）
curl -X POST http://localhost:8001/upstreams/backend-api/targets \
  --data "target=192.168.1.13:8080" \
  --data "weight=10"

# 禁用目标
curl -X POST http://localhost:8001/upstreams/backend-api/targets \
  --data "target=192.168.1.10:8080" \
  --data "weight=0"

4.3 服务与上游关联

# 创建使用上游的服务
curl -X POST http://localhost:8001/services \
  --data "name=load-balanced-service" \
  --data "host=backend-api"  # 使用上游名称作为host

# 创建路由
curl -X POST http://localhost:8001/services/load-balanced-service/routes \
  --data "name=lb-route" \
  --data "paths[]=/api"

5. SSL/TLS配置

5.1 证书管理

5.1.1 上传证书

# 上传SSL证书
curl -X POST http://localhost:8001/certificates \
  --form "cert=@/path/to/cert.pem" \
  --form "key=@/path/to/key.pem" \
  --form "snis=api.example.com,www.api.example.com"

5.1.2 SNI配置

# 创建SNI
curl -X POST http://localhost:8001/snis \
  --data "name=api.example.com" \
  --data "certificate.id=cert-id"

5.2 HTTPS重定向

# 安装HTTPS重定向插件
curl -X POST http://localhost:8001/plugins \
  --data "name=request-termination" \
  --data "config.status_code=301" \
  --data "config.message=Moved Permanently"

# 或使用专门的重定向插件
curl -X POST http://localhost:8001/plugins \
  --data "name=redirect-https"

5.3 客户端证书认证

# 启用客户端证书验证
curl -X POST http://localhost:8001/services/secure-service/plugins \
  --data "name=mtls-auth" \
  --data "config.ca_certificates[]=ca-cert-id"

6. 高级配置

6.1 请求/响应转换

6.1.1 请求转换

# 添加请求头
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=request-transformer" \
  --data "config.add.headers=X-API-Key:secret-key" \
  --data "config.add.headers=X-Client-IP:$(client_ip)"

# 修改请求路径
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=request-transformer" \
  --data "config.replace.uri=/new-path"

6.1.2 响应转换

# 添加响应头
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=response-transformer" \
  --data "config.add.headers=X-Powered-By:Kong" \
  --data "config.remove.headers=Server"

6.2 缓存配置

# 启用代理缓存
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=proxy-cache" \
  --data "config.response_code=200,301,404" \
  --data "config.request_method=GET,HEAD" \
  --data "config.cache_ttl=300" \
  --data "config.strategy=memory"

6.3 压缩配置

# 启用响应压缩
curl -X POST http://localhost:8001/services/my-service/plugins \
  --data "name=response-ratelimiting" \
  --data "config.limits.video=10" \
  --data "config.limits.image=20"

7. 配置管理最佳实践

7.1 配置版本控制

7.1.1 导出配置

# 导出所有配置
curl http://localhost:8001/config > kong-config.json

# 使用deck工具
deck dump

7.1.2 导入配置

# 导入配置
deck sync

# 验证配置
deck validate

7.2 环境配置管理

7.2.1 开发环境配置

# dev-config.yaml
_format_version: "3.0"

services:
- name: dev-api
  url: http://dev-backend:8080
  routes:
  - name: dev-route
    paths:
    - /api
  plugins:
  - name: cors
    config:
      origins:
      - "*"

7.2.2 生产环境配置

# prod-config.yaml
_format_version: "3.0"

services:
- name: prod-api
  url: https://prod-backend:8443
  routes:
  - name: prod-route
    paths:
    - /api
    protocols:
    - https
  plugins:
  - name: rate-limiting
    config:
      minute: 1000
  - name: cors
    config:
      origins:
      - "https://app.example.com"

7.3 配置验证

7.3.1 语法检查

# 检查Kong配置
kong check

# 检查deck配置
deck validate kong.yaml

7.3.2 连通性测试

# 测试服务连通性
curl -I http://localhost:8001/services/my-service/health

# 测试路由
curl -I http://localhost:8000/api/test

8. 监控和调试

8.1 状态检查

# Kong状态
curl http://localhost:8001/status

# 服务状态
curl http://localhost:8001/services/my-service/health

# 上游健康状态
curl http://localhost:8001/upstreams/backend-api/health

8.2 日志配置

# 启用文件日志插件
curl -X POST http://localhost:8001/plugins \
  --data "name=file-log" \
  --data "config.path=/var/log/kong/access.log"

# 启用HTTP日志插件
curl -X POST http://localhost:8001/plugins \
  --data "name=http-log" \
  --data "config.http_endpoint=http://log-server:8080/logs"

8.3 性能监控

# 启用Prometheus插件
curl -X POST http://localhost:8001/plugins \
  --data "name=prometheus"

# 查看指标
curl http://localhost:8001/metrics

9. 故障排除

9.1 常见问题

9.1.1 路由不匹配

# 检查路由配置
curl http://localhost:8001/routes

# 测试路由匹配
curl -H "Host: api.example.com" http://localhost:8000/api/test

9.1.2 上游连接失败

# 检查上游状态
curl http://localhost:8001/upstreams/backend-api/health

# 检查目标状态
curl http://localhost:8001/upstreams/backend-api/targets

9.1.3 SSL证书问题

# 检查证书
curl http://localhost:8001/certificates

# 检查SNI
curl http://localhost:8001/snis

# 测试SSL连接
openssl s_client -connect api.example.com:443 -servername api.example.com

9.2 调试技巧

9.2.1 启用调试日志

# 设置日志级别
export KONG_LOG_LEVEL=debug
kong restart

# 查看错误日志
tail -f /usr/local/kong/logs/error.log

9.2.2 使用curl调试

# 详细输出
curl -v http://localhost:8000/api/test

# 显示响应头
curl -I http://localhost:8000/api/test

# 跟踪重定向
curl -L http://localhost:8000/api/test

10. 总结

Kong的API网关配置涵盖了服务、路由、负载均衡、SSL/TLS等多个方面。通过合理的配置，可以实现灵活的API管理、高可用的负载均衡和强大的安全防护。

在下一章节中，我们将详细介绍Kong的安全认证与授权机制。

📂 分类导航

▶ 学与练
- ▶ 软件技术基础
  - ▶ 操作系统技术
    - Linux实战
    - ▶ Linux技巧
      - debug-remote-api.md
  - ▶ 容器化与编排
    - Docker实战
    - ▶ Docker高级
- ▶ 前端开发技术
  - ▶ 框架与库
    - js
    - vue
  - ▶ 前端生态
    - bootstrap
    - vue-ssr
- ▶ 后端开发技术
  - ▶ 编程语言
    - ▶ Java
    - ▶ Go
      - go-server.md
      - mini.md
    - Rust
    - Python
    - csharp
  - ▶ 中间件
    - redis
    - ▶ minio
      - minio.md
    - elasticsearch
    - kafka
    - elk
    - caddy
  - ▶ 数据库
    - MySQL
    - SQLServer
    - ▶ Dameng
      - sql.md
    - clickhouse
- ▶ 数据开发与运维
  - ▶ 数据开发
    - hadoop
  - ▶ 运维开发
    - ▶ CI/CD
      - jenkins
    - ▶ 自动化
      - allinssl.md
    - ▶ 日志处理
      - elk
    - ▶ 监控
- 软件速学教程
▶ 软件园
- AI智能体与应用
- 开发工具与环境
- AI 开发和编排
- 业务与生产力应用
- 数据和中间件
▶ 工具箱
- 内容管理
- 编码解码
- ▶ 系统监控
  - miaotixing.md
- ▶ 日常工具
- 工具命令
- 使用教程

📚 Kong API网关配置