Kong API 网关加固的重点不是装插件,而是先回答一个问题:谁能调用管理接口。Kong 开源版的 Admin API 默认监听 8001 且不做任何身份校验,只要该端口可达,任何人都能新增路由、读取消费者密钥、把流量转发到任意上游——这比任何一个业务漏洞都严重。
第二个重点是「谁是真的来源 IP」。Kong 的 ip-restriction、rate-limiting 都依赖客户端地址,而地址来自 X-Forwarded-For。信任链没配好,攻击者自己填一个 X-Forwarded-For: 10.0.0.1 就能同时绕过 IP 白名单和限流。本文按「端口收口 — 信任链校正 — 鉴权限流 — 声明式配置」的顺序落地。
适用场景
- Kong 作为对外 API 统一入口,后端有多个微服务,需要在一处做鉴权、限流与来源限制
- 等保或接口安全检查指出「API 无认证」「无调用频次限制」「管理端口对公网开放」
- 多个合作方共用同一套接口,需要按消费者发放密钥并单独计量配额
- 出现过来源 IP 判断错误导致白名单失效,或日志里的客户端地址全是同一个网关 IP
前置条件
- Kong Gateway 3.4 及以上(OSS 版即可,本文不依赖企业版 RBAC)
- Docker 24+ 与 docker compose v2,或 RPM/DEB 原生部署;数据库可选 PostgreSQL 12+ 或 DB-less 声明式模式
- 前置 Nginx 或云负载均衡已终结 TLS,Kong 只处理明文 8000
- 上游服务地址与健康检查路径已确认,例如
http://10.0.0.21:8080/health - 注意:开源版 Admin API 没有任何内置认证,唯一可靠的保护是「只监听回环 + 前置代理鉴权 + 网络层白名单」,三者缺一不可
原理说明
Kong 的进程里同时跑着几张面孔:8000/8443 是数据面(代理流量),8001 是控制面(Admin API),8002 是 Kong Manager 图形界面,8003 是 Dev Portal。四个端口共用同一个进程,区分只靠监听地址。所以加固的第一步不是写插件,而是把 8001 从 0.0.0.0 改成 127.0.0.1——这一步能挡掉绝大多数自动化扫描器,因为公网上扫 8001 的僵尸网络比扫 22 端口的还勤。
插件模型是「绑定在服务或路由上的执行链」。同一类插件在服务级与路由级各配一份时,路由级优先;key-auth 负责认证、rate-limiting 负责配额、ip-restriction 负责来源、request-size-limiting 负责体积、response-transformer 负责补安全响应头。顺序上认证必须在限流之前,否则未认证请求会先消耗配额,形成「一个无效密钥打满全局限流」的拒绝服务面。
来源 IP 的正确性由三个配置决定:trusted_ips 声明哪些地址发来的 X-Forwarded-For 可信,real_ip_header 指定取哪个头,real_ip_recursive 决定是否从右往左剥掉可信跳数。三者不配,Kong 会把 TCP 连接的对端地址当客户端地址——在 Nginx 反代场景下,那个地址永远是 Nginx 自己,于是所有请求共享一个 IP,限流与白名单同时失效。
DB-less 模式下,所有配置来自一份 kong.yml,通过 kong reload 生效,不落库。它的好处是配置可进 Git、可审计、可回滚;代价是没有 Admin API 的写操作,改一条路由就要重新加载。对「变更走发布流程」的团队,这个约束反而是优点。
操作步骤
1. 端口收口
用环境变量方式部署,把 Admin API 与状态接口都压到回环,图形界面与门户直接关闭:
cat > /opt/kong/docker-compose.yml <<'EOF'
services:
kong:
image: kong:3.6
container_name: kong
restart: unless-stopped
environment:
KONG_DATABASE: "off"
KONG_DECLARATIVE_CONFIG: /kong/declarative/kong.yml
KONG_PROXY_LISTEN: "0.0.0.0:8000"
KONG_ADMIN_LISTEN: "127.0.0.1:8001"
KONG_ADMIN_GUI_LISTEN: "off"
KONG_PORTAL: "off"
KONG_STATUS_LISTEN: "127.0.0.1:8100"
KONG_TRUSTED_IPS: "10.0.0.0/8,127.0.0.1"
KONG_REAL_IP_HEADER: "X-Forwarded-For"
KONG_REAL_IP_RECURSIVE: "on"
KONG_HEADERS: "off"
KONG_LOG_LEVEL: "notice"
volumes:
- ./declarative:/kong/declarative
ports:
- "8000:8000"
EOF
sudo mkdir -p /opt/kong/declarative
cd /opt/kong && docker compose up -d
KONG_ADMIN_LISTEN 写成 127.0.0.1:8001 是本文最重要的一行,容器内回环意味着宿主机只能通过 docker exec 或 --network host 访问,公网彻底不可达。KONG_HEADERS: off 会关掉 Server: kong/x.y.z 的版本暴露,避免被按版本匹配 CVE,安全响应头统一由外层 Nginx 输出,避免两处重复添加。
2. 校正来源 IP 信任链
Nginx 反代 Kong 时,必须把真实客户端地址写进 X-Forwarded-For,并让 Kong 只信任 Nginx 所在网段:
server {
listen 443 ssl;
http2 on;
server_name api.example.com;
ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
client_max_body_size 4m;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 60s;
}
}
proxy_add_x_forwarded_for 会把真实地址追加到已有的头后面,而不是覆盖。Kong 侧 real_ip_recursive: on 从右往左剥掉可信网段,最后剩下的第一个不可信地址才是客户端真实 IP。若写成 proxy_set_header X-Forwarded-For $remote_addr;(覆盖式),攻击者伪造的头会被丢弃,反而更安全;两种写法都能用,但只要有一层不校验就前功尽弃。
3. 声明式配置:鉴权、限流与来源限制
下面这份 kong.yml 定义了单个服务、一条路由、四个插件与一个消费者,可直接导入。密钥务必现场生成,不要用示例值:
_format_version: "3.0"
services:
- name: order-api
url: http://10.0.0.21:8080
connect_timeout: 5000
read_timeout: 10000
routes:
- name: order-api-route
paths:
- /api/order
strip_path: true
protocols:
- http
- https
plugins:
- name: key-auth
config:
key_names:
- apikey
hide_credentials: true
- name: rate-limiting
config:
minute: 120
hour: 3000
policy: local
limit_by: ip
fault_tolerant: false
- name: ip-restriction
config:
allow:
- 10.0.0.0/8
- 203.0.113.0/24
- name: request-size-limiting
config:
allowed_payload_size: 2
require_content_length: true
- name: response-transformer
config:
add:
headers:
- "Referrer-Policy:strict-origin-when-cross-origin"
- "X-Content-Type-Options:nosniff"
consumers:
- username: partner-a
keyauth_credentials:
- key: 9f2c7a41d8e35b06c1a4f7d29b8e5301
几个参数值得单独说明:hide_credentials: true 会从转发给上游的请求里删掉 apikey,防止密钥在后端日志里落地;fault_tolerant: false 让限流在存储不可用时直接拒绝(默认是失败放行,等于攻击期间自动解除限流);allowed_payload_size 单位是 MB,配合 require_content_length 可拦住不带长度头的分块上传;strip_path: true 会把 /api/order 前缀剥掉再转给上游,与后端路由约定不一致时先改成 false 试。
4. 导入并校验
# 语法解析,不加载,先确认 YAML 与 schema 无误
docker exec kong kong config parse /kong/declarative/kong.yml
# DB-less 模式:重载声明式配置
docker exec kong kong reload
# 确认服务与路由已加载
curl -s http://127.0.0.1:8001/services | head -c 300
curl -s http://127.0.0.1:8001/routes | head -c 300
kong config parse 失败会直接指出字段名与行号,比 import 后才报错好排查。DB 模式(有 PostgreSQL)则改用 kong config db_import /kong/declarative/kong.yml,导入是幂等的,同名服务会被更新而不是重复创建。
5. 密钥轮换与最小权限
消费者密钥一旦泄露,必须在声明式文件里换掉并重载。批量生成与核对:
# 生成 32 位十六进制密钥
openssl rand -hex 16
# 查看全部消费者的密钥(仅允许在本机执行)
curl -s http://127.0.0.1:8001/key-auths | grep -o '"key":"[^"]*"'
# 为已有消费者追加一个密钥,便于平滑切换
curl -s -X POST http://127.0.0.1:8001/consumers/partner-a/key-auth \
-d '{"key":"<新密钥>","ttl":2592000}'
ttl 以秒计,2592000 即 30 天,到期自动失效,避免「一次发放永久有效」。轮换流程建议「先发新密钥 → 通知对方切换 → 观察两周调用量 → 删除旧密钥」,直接删旧密钥会造成硬中断。
配置验证
# 1) Admin API 仅本机可达
ss -tlnp | grep -E '8001|8100'
curl -s -o /dev/null -w 'local admin: %{http_code}\n' http://127.0.0.1:8001/
# 2) 公网访问业务接口,无密钥应 401
curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/api/order/list
# 3) 带密钥应 200
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
https://api.example.com/api/order/list
# 4) 超频应 429
for i in $(seq 1 150); do
curl -s -o /dev/null -w '%{http_code} ' \
-H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
https://api.example.com/api/order/list
done; echo
# 5) 伪造来源头不应绕过白名单
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'X-Forwarded-For: 10.0.0.9' \
-H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
https://api.example.com/api/order/list
# 6) 健康与版本
curl -s http://127.0.0.1:8100/status | head -c 200
预期:8001 只绑定 127.0.0.1;无密钥 401;带密钥 200;第 4 步在第 120 次之后开始出现 429;第 5 步应从公网来源拿到 403(被 ip-restriction 拒绝)而不是 200——如果拿到 200,说明 trusted_ips 把公网段也当成可信,伪造头生效了。
常见问题
FAQ 1:配了 ip-restriction 白名单,攻击者照样能进来?
先看 KONG_TRUSTED_IPS 是否过大。Kong 只信任来自 trusted_ips 网段的 X-Forwarded-For,若填成 0.0.0.0/0,任何人都能自带一个内网地址通过校验。正确做法是只填前置代理的地址段,并确保 real_ip_recursive 为 on。排查方法是在上游打印收到的 X-Real-IP,与实际出口 IP 对比。
FAQ 2:限流阈值明明是 120 次/分钟,却经常提前触发或根本不触发?
两种原因。一是 policy: local:计数存在各节点内存里,多副本部署时每个实例单独计数,实际阈值等于「120 × 副本数」;需要全局精确计数就换 redis 策略并指定 redis.host。二是 limit_by 选了 credential 或 consumer,此时同一 IP 上多个密钥互不影响,与你预期的「按 IP 限」不一致。fault_tolerant 为 true 时 Redis 抖动会让限流整体失效,安全场景应设为 false。
FAQ 3:DB-less 模式改了 kong.yml,为什么接口行为没变?
声明式配置不会自动热加载,必须执行 kong reload(容器内)。kong reload 只重读配置不重启进程,连接不会中断;但如果文件有语法错误,reload 会失败并保留旧配置,此时 docker logs kong 里能看到解析错误。生产环境建议先 kong config parse 再 reload,把错误挡在生效之前。
总结
Kong 的风险不在插件能力,而在「默认太开放」。加固的四步是递进的:KONG_ADMIN_LISTEN 收回到 127.0.0.1 解决控制面裸奔,trusted_ips 与 real_ip_recursive 校正来源 IP 解决白名单与限流被伪造头绕过,key-auth + rate-limiting + ip-restriction 三层插件解决调用侧准入,最后用 kong.yml 进版本库让每次变更可审计、可回滚。做完这四步,网关才真正成为「统一入口」而不是「统一后门」。