1. 项目背景与整体架构拆解1.1 为什么要在 CentOS 上自建 Kong 网关很多团队在微服务改造到一定阶段后都会遇到一个绕不开的问题服务数量上去了认证、限流、日志、灰度这些横切关注点散落在每个业务服务里改一处要动十个仓库。这时候引入一个 API 网关做统一入口几乎是必然选择。Kong 就是这类场景里出现频率非常高的一个方案它基于 OpenRestyNginx Lua构建性能底子好插件生态成熟社区版免费够用而且配置方式灵活既能声明式管理也能通过 Admin API 动态调整。那为什么标题里还带了个 Konga因为 Kong 本身只提供 Admin API命令行操作虽然强大但日常运维、给团队里非技术同学看路由和上游配置时纯命令行体验很差。Konga 是一个开源的 Kong 可视化管理面板能图形化地管理服务、路由、插件、消费者还能做多节点管理、快照备份和恢复。把这两个组合起来就是一套“底层用 Kong 扛流量上层用 Konga 做管理”的完整方案。至于为什么是 CentOS这个不用多解释。大量企业的内网服务器、虚拟机模板、私有化交付环境仍然是 CentOS 系包括 Rocky、Alma 这些兼容发行版。虽然 CentOS 8 已经停止维护但 CentOS 7 和各类衍生版本在存量环境里占比依然很高所以这套搭建流程的适用面非常广。1.2 整体架构与组件关系在动手之前先把几个组件的关系理清楚不然后面配置数据库、端口、网络的时候容易乱。整套架构大致是这样分层的数据层PostgreSQL 数据库Kong 和 Konga 共用也可以分开但共用更省资源。Kong 存的是服务、路由、插件、消费者等配置Konga 存的是面板用户、连接信息、快照等。网关层Kong监听几个关键端口。默认情况下 8000 是 HTTP 代理端口8443 是 HTTPS 代理端口8001 是 Admin API 端口8444 是 Admin API 的 HTTPS 端口。管理层Konga默认监听 1337 端口通过浏览器访问它再通过 Admin API 去操作 Kong。这里有个关键点Konga 操作 Kong 走的是 Admin API不是直接连数据库。所以 Konga 配置连接信息时填的是 Kong 的 Admin API 地址比如http://127.0.0.1:8001。这一点新手特别容易搞混以为 Konga 要连 Postgres 才能管 Kong其实不是。提示生产环境里 Admin API 绝对不能暴露到公网8001 端口只允许内网或本机访问。Konga 面板同理最好放在内网或加一层反向代理做认证。1.3 部署方式选型容器还是裸机搭建方式主要有两种Docker Compose 一把梭或者裸机逐个安装。两种我都实际用过各有适用场景。Docker 方式的优势是隔离干净、版本可控、迁移方便一条docker-compose up就能起来。缺点是如果团队对容器不熟出问题时排查链路变长而且 CentOS 上装 Docker 本身也要折腾一下源。裸机方式也就是直接在系统上装 Postgres、Kong、Node 跑 Konga的优势是直观所有进程、端口、日志都在明面上适合需要深度定制或者环境不允许用容器的场景。缺点就是依赖管理麻烦尤其是 Konga 依赖 Node 环境版本不对就编译报错。这篇内容我以裸机部署为主线来讲因为标题是“centos 搭建”裸机更贴合这个语境而且把裸机搞明白了容器方式反而更简单。容器方式我会在最后补充关键差异点。2. 环境准备与依赖安装实操2.1 系统基础环境确认第一步永远是确认系统版本和基础环境别急着装东西。执行下面几条命令看清楚现状cat /etc/centos-release uname -r getenforce systemctl status firewalld这几条分别看的是系统发行版本、内核版本、SELinux 状态、防火墙状态。为什么要看这些因为 SELinux 和 firewalld 是 CentOS 上最容易让服务“明明装好了却连不上”的两个元凶。SELinux 会拦截非标准端口的网络绑定firewalld 会直接挡掉端口访问。我的建议是测试环境可以临时把 SELinux 设为 permissive、把 firewalld 关掉来快速验证生产环境不要关而是按需放行端口和配置 SELinux 策略。这个取舍后面会详细说。另外确认一下系统时间Kong 和 Konga 涉及 JWT、证书这些对时间敏感的东西时间偏差太大会出诡异问题timedatectl如果时间不对用timedatectl set-timezone Asia/Shanghai调整时区再配合时间同步服务校准。2.2 安装 PostgreSQL 数据库Kong 支持 PostgreSQL 和 Cassandra 两种存储但 Cassandra 在新版本里已经逐步被弱化社区版主推 Postgres所以直接上 Postgres 就对了。CentOS 7 自带的 yum 源里 Postgres 版本偏老建议加官方源装新一点的版本。以 Postgres 13 为例yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm yum install -y postgresql13-server postgresql13-contrib /usr/pgsql-13/bin/postgresql-13-setup initdb systemctl enable postgresql-13 systemctl start postgresql-13装完之后要做两件事建 Kong 的数据库和用户以及调整认证配置。先切到 postgres 用户建库建用户su - postgres psql在 psql 里执行CREATE USER kong WITH PASSWORD 你的强密码; CREATE DATABASE kong OWNER kong; \q然后处理认证方式。默认的pg_hba.conf里本地连接可能是peer或identKong 用密码连接会失败需要改成md5或scram-sha-256。文件位置一般在/var/lib/pgsql/13/data/pg_hba.conf。找到本地连接那几行改成host all all 127.0.0.1/32 md5 host all all ::1/128 md5改完重启 Postgressystemctl restart postgresql-13。注意改pg_hba.conf之前先备份一份改错了会导致数据库连不上那时候就只能靠单用户模式恢复了很麻烦。2.3 安装 Kong 网关Kong 官方提供了 CentOS 的 RPM 包安装相对省心。先加仓库curl -1sLf https://packages.konghq.com/public/gateway-37/gpg.key -o /etc/pki/rpm-gpg/kong.asc然后配置 yum 源文件/etc/yum.repos.d/kong.repo内容指向官方仓库地址。具体地址会随版本变化建议以官方文档当前给出的为准。配置好之后yum install -y kong安装完成后Kong 的配置文件默认在/etc/kong/kong.conf.default需要复制一份成kong.conf再改cp /etc/kong/kong.conf.default /etc/kong/kong.conf关键配置项有这么几个配置项作用建议值database存储类型postgrespg_host数据库地址127.0.0.1pg_port数据库端口5432pg_user数据库用户kongpg_password数据库密码你设置的密码pg_database数据库名kongproxy_listen代理监听0.0.0.0:8000admin_listen管理接口监听127.0.0.1:8001这里admin_listen我强烈建议绑到127.0.0.1而不是0.0.0.0除非你明确知道自己在做什么。Admin API 权限极大暴露出去等于把网关的控制权交出去了。配置改好后初始化数据库kong migrations bootstrap -c /etc/kong/kong.conf看到迁移成功的提示后启动 Kongkong start -c /etc/kong/kong.conf验证一下curl -i http://127.0.0.1:8001/能返回 JSON 格式的节点信息就说明 Kong 起来了。2.4 安装 Node 环境与 KongaKonga 是个 Node.js 应用所以要先有 Node 环境。这里有个坑Konga 对 Node 版本有要求太新的 Node 反而可能编译失败。实测下来 Node 14 或 16 比较稳Node 18 以上有时会遇到依赖编译问题。装 Node 可以用 NodeSource 的源curl -fsSL https://rpm.nodesource.com/setup_16.x | bash - yum install -y nodejs node -v npm -v然后拉 Konga 源码。Konga 官方仓库可以直接 clone也可以下 release 包git clone https://github.com/pantsel/konga.git cd konga npm installnpm install这一步是最容易出问题的环节网络、依赖、编译工具链都可能卡住。如果报node-gyp相关的错通常是缺编译工具yum install -y gcc-c make python3装完依赖后配置 Konga 的环境变量。复制一份.env.example成.env重点改这几个PORT1337 NODE_ENVproduction DB_ADAPTERpostgres DB_URIpostgresql://kong:你的密码127.0.0.1:5432/konga注意这里的DB_URI是Konga 自己的数据库不是 Kong 的。虽然可以共用同一个 Postgres 实例但库名建议分开比如给 Konga 单独建一个konga库避免表结构冲突。建库CREATE DATABASE konga OWNER kong;然后初始化 Konga 的数据库表node ./bin/konga.js prepare --adapter postgres --uri postgresql://kong:密码127.0.0.1:5432/konga启动 Konganpm start浏览器访问http://服务器IP:1337能看到注册页面就成功了。3. 核心配置与联调实现3.1 Konga 连接 Kong 的关键配置Konga 起来之后第一件事是注册管理员账号然后添加 Kong 连接。这一步是整套方案的核心联调点配置错了后面全白搭。登录后进入 Connections 页面新建一个连接关键字段Name随便起比如local-kongKong Admin URL填http://127.0.0.1:8001这里有个细节如果 Konga 和 Kong 不在同一台机器127.0.0.1就不对了要填 Kong 所在机器的内网 IP同时 Kong 的admin_listen要放开到对应网段。但如前所述生产环境不建议这么做更稳妥的做法是让 Konga 和 Kong 同机部署或者通过内网反向代理转发 Admin API。连接建好后点激活如果能看到 Kong 的版本、节点信息说明联调成功。如果报连接超时或 401按这个顺序排查Kong 进程是否在跑ps -ef | grep kongAdmin API 是否可达curl http://127.0.0.1:8001/Konga 所在机器的网络能否访问目标地址防火墙是否放行3.2 用 Konga 配置第一个服务与路由联调通了之后就可以在 Konga 里配置实际的代理规则了。Kong 的核心概念是 Service 和 RouteService代表一个后端上游服务比如你的业务 API配置里填上游的协议、主机、端口、路径。Route代表匹配规则定义什么样的请求会被转发到这个 Service比如按路径、按域名、按方法匹配。举个实际例子。假设你有个后端服务跑在192.168.1.100:8080想通过网关暴露成http://网关IP:8000/api/user/xxx。在 Konga 里操作进入 Services新建一个 ServiceName 填user-serviceProtocol 选httpHost 填192.168.1.100Port 填8080。进入 Routes给这个 Service 加一条路由Paths 填/api/userMethods 勾选需要的 HTTP 方法。保存后请求http://网关IP:8000/api/user/xxx就会被转发到http://192.168.1.100:8080/api/user/xxx。这里有个路径处理的坑Kong 默认会把匹配到的路径原样转发。如果你想让/api/user这段前缀在转发时被剥掉需要在 Service 或 Route 上配置strip_path。这个选项在 Konga 的 Route 编辑界面里能找到默认是开启的具体行为要按你的后端接口设计来定。3.3 插件配置认证与限流网关的价值很大程度体现在插件上。Kong 社区版自带一批常用插件在 Konga 里可以直接给 Service、Route 或全局启用。Key Authentication 插件是最常用的认证方式之一。启用后Kong 会要求请求头里带一个 API Key没有或不对就返回 401。配置步骤在 Plugins 页面给目标 Service 添加key-auth插件。在 Consumers 页面创建一个消费者比如叫mobile-app。给这个消费者添加key-auth凭证Kong 会生成一个 key。客户端请求时带上apikey: 生成的key请求头。Rate Limiting 插件用来做限流。可以按秒、分、时、天配置请求上限还能按消费者、按 IP 维度限流。比如给某个 Service 配rate-limitingsecond填 100policy选local就表示每秒最多 100 个请求。提示local策略是在单个 Kong 节点内存里计数多节点部署时每个节点独立计数总量会翻倍。要做集群级精确限流需要配合 Redis把 policy 改成redis并配置 Redis 连接。3.4 数据库与端口的安全加固前面反复强调 Admin API 和面板的安全这里集中说一下加固要点。端口层面8001 和 1337 这两个端口是管理入口绝对不能对公网开放。用 firewalld 限制firewall-cmd --permanent --add-rich-rulerule familyipv4 source address192.168.1.0/24 port port8001 protocoltcp accept firewall-cmd --reload只允许内网网段访问其他一律拒绝。1337 同理。数据库层面Postgres 只监听本地或内网postgresql.conf里listen_addresses不要设成*。密码用强密码不要用默认的。Konga 层面Konga 支持配置认证方式生产环境建议接入统一的认证体系而不是用本地账号。另外 Konga 的.env文件里有数据库密码文件权限要收紧chmod 600 .envSELinux 层面如果 SELinux 是 enforcing 状态Kong 绑定非标准端口可能被拦。可以用semanage port -a -t http_port_t -p tcp 8000这类命令把端口加入允许列表而不是直接关掉 SELinux。4. 常见问题排查与避坑经验4.1 启动类问题速查搭建过程中最容易卡住的就是各种启动失败。我把踩过的坑整理成一张表方便对照排查。现象可能原因排查方向Kong 启动报数据库连接失败pg_hba.conf 认证方式不对检查是否改成 md5密码是否正确Kong 启动报 migration 未执行没跑 bootstrap执行 kong migrations bootstrapKonga npm install 失败缺编译工具或 Node 版本不对装 gcc-c make python3换 Node 16Konga 连不上 KongAdmin URL 填错或端口不通curl 测 8001检查防火墙浏览器打不开 1337Konga 没起来或端口没放行看 npm start 日志放行端口代理请求 502上游服务不可达检查 Service 配置的 host/port4.2 几个容易忽略的细节第一个坑是 Postgres 的密码认证。很多人建完用户就直接去配 Kong结果连不上回头才发现pg_hba.conf还是peer。这个前面提过但真的太多人中招值得再强调一次。第二个坑是 Konga 的数据库和 Kong 的数据库混用。虽然理论上可以放一个实例但库一定要分开。我见过有人图省事让两者共用一个库结果 Konga 的迁移脚本和 Kong 的表结构打架最后只能重建。第三个坑是 Node 版本。Konga 这个项目更新不算特别活跃对新版 Node 的兼容性一般。如果你用 Node 20 装依赖报一堆错别怀疑人生降到 16 大概率就好了。第四个坑是路径转发。Kong 的strip_path行为如果不注意会导致后端收到的路径和预期不一致接口 404。配置完一定要用 curl 实测一遍看后端日志里收到的真实路径是什么。4.3 性能与稳定性调优建议跑起来只是第一步要稳定运行还得调。几个实际有效的点Nginx worker 配置。Kong 底层是 Nginxkong.conf里的nginx_worker_processes默认是auto一般够用。但如果服务器 CPU 核数很多可以手动指定避免 worker 过多导致上下文切换开销。连接池。Kong 到 Postgres 的连接数要合理设置pg_max_concurrent_queries这类参数按实际并发调。数据库连接打满会导致请求排队。日志轮转。Kong 的 access 日志和 error 日志默认写在/usr/local/kong/logs/下长期运行会撑爆磁盘。配 logrotate 定期切割或者把日志输出到统一日志系统。健康检查。Kong 支持对上游做主动和被动健康检查在 Service 或 Upstream 上配置。后端有多个实例时健康检查能自动摘除故障节点这个在生产环境几乎是必配的。监控。Kong 暴露了/status接口可以接 Prometheus。Konga 本身也有一定的状态展示但要做长期监控还是得靠专业工具。5. 容器化部署的差异补充前面走的是裸机路线这里补充一下容器方式的关键差异方便不同环境的读者按需选择。容器方式的核心是一个docker-compose.yml里面定义三个服务postgres、kong、konga。关键点在于网络三个容器放同一个自定义网络里容器间用服务名互相访问比如 Konga 连 Kong 填http://kong:8001Kong 连 Postgres 填postgres。数据持久化Postgres 的数据目录要挂 volume否则容器一删数据全没。Kong 的迁移容器方式下迁移命令是docker exec进去执行或者用kong migrations bootstrap作为启动命令的一部分。Konga 的 prepare同样要在容器里跑一次 prepare。容器方式省去了装 Node、装 Postgres 的麻烦但排查问题时多了一层容器需要熟悉docker logs、docker exec这些操作。两种方式没有绝对优劣看团队的技术栈和运维习惯。我个人在实际操作中的体会是第一次搭建强烈建议先用裸机走一遍把每个组件的作用、端口、依赖关系都摸清楚之后再上容器会顺畅很多。直接上容器虽然快但一旦出问题因为不清楚底层发生了什么排查会很痛苦。另外无论哪种方式Admin API 和面板的安全加固都不能省这是整套方案里最容易被忽视、也最要命的一环。
1. 项目背景与整体架构拆解1.1 为什么要在 CentOS 上自建 Kong 网关很多团队在微服务改造到一定阶段后都会遇到一个绕不开的问题服务数量上去了认证、限流、日志、灰度这些横切关注点散落在每个业务服务里改一处要动十个仓库。这时候引入一个 API 网关做统一入口几乎是必然选择。Kong 就是这类场景里出现频率非常高的一个方案它基于 OpenRestyNginx Lua构建性能底子好插件生态成熟社区版免费够用而且配置方式灵活既能声明式管理也能通过 Admin API 动态调整。那为什么标题里还带了个 Konga因为 Kong 本身只提供 Admin API命令行操作虽然强大但日常运维、给团队里非技术同学看路由和上游配置时纯命令行体验很差。Konga 是一个开源的 Kong 可视化管理面板能图形化地管理服务、路由、插件、消费者还能做多节点管理、快照备份和恢复。把这两个组合起来就是一套“底层用 Kong 扛流量上层用 Konga 做管理”的完整方案。至于为什么是 CentOS这个不用多解释。大量企业的内网服务器、虚拟机模板、私有化交付环境仍然是 CentOS 系包括 Rocky、Alma 这些兼容发行版。虽然 CentOS 8 已经停止维护但 CentOS 7 和各类衍生版本在存量环境里占比依然很高所以这套搭建流程的适用面非常广。1.2 整体架构与组件关系在动手之前先把几个组件的关系理清楚不然后面配置数据库、端口、网络的时候容易乱。整套架构大致是这样分层的数据层PostgreSQL 数据库Kong 和 Konga 共用也可以分开但共用更省资源。Kong 存的是服务、路由、插件、消费者等配置Konga 存的是面板用户、连接信息、快照等。网关层Kong监听几个关键端口。默认情况下 8000 是 HTTP 代理端口8443 是 HTTPS 代理端口8001 是 Admin API 端口8444 是 Admin API 的 HTTPS 端口。管理层Konga默认监听 1337 端口通过浏览器访问它再通过 Admin API 去操作 Kong。这里有个关键点Konga 操作 Kong 走的是 Admin API不是直接连数据库。所以 Konga 配置连接信息时填的是 Kong 的 Admin API 地址比如http://127.0.0.1:8001。这一点新手特别容易搞混以为 Konga 要连 Postgres 才能管 Kong其实不是。提示生产环境里 Admin API 绝对不能暴露到公网8001 端口只允许内网或本机访问。Konga 面板同理最好放在内网或加一层反向代理做认证。1.3 部署方式选型容器还是裸机搭建方式主要有两种Docker Compose 一把梭或者裸机逐个安装。两种我都实际用过各有适用场景。Docker 方式的优势是隔离干净、版本可控、迁移方便一条docker-compose up就能起来。缺点是如果团队对容器不熟出问题时排查链路变长而且 CentOS 上装 Docker 本身也要折腾一下源。裸机方式也就是直接在系统上装 Postgres、Kong、Node 跑 Konga的优势是直观所有进程、端口、日志都在明面上适合需要深度定制或者环境不允许用容器的场景。缺点就是依赖管理麻烦尤其是 Konga 依赖 Node 环境版本不对就编译报错。这篇内容我以裸机部署为主线来讲因为标题是“centos 搭建”裸机更贴合这个语境而且把裸机搞明白了容器方式反而更简单。容器方式我会在最后补充关键差异点。2. 环境准备与依赖安装实操2.1 系统基础环境确认第一步永远是确认系统版本和基础环境别急着装东西。执行下面几条命令看清楚现状cat /etc/centos-release uname -r getenforce systemctl status firewalld这几条分别看的是系统发行版本、内核版本、SELinux 状态、防火墙状态。为什么要看这些因为 SELinux 和 firewalld 是 CentOS 上最容易让服务“明明装好了却连不上”的两个元凶。SELinux 会拦截非标准端口的网络绑定firewalld 会直接挡掉端口访问。我的建议是测试环境可以临时把 SELinux 设为 permissive、把 firewalld 关掉来快速验证生产环境不要关而是按需放行端口和配置 SELinux 策略。这个取舍后面会详细说。另外确认一下系统时间Kong 和 Konga 涉及 JWT、证书这些对时间敏感的东西时间偏差太大会出诡异问题timedatectl如果时间不对用timedatectl set-timezone Asia/Shanghai调整时区再配合时间同步服务校准。2.2 安装 PostgreSQL 数据库Kong 支持 PostgreSQL 和 Cassandra 两种存储但 Cassandra 在新版本里已经逐步被弱化社区版主推 Postgres所以直接上 Postgres 就对了。CentOS 7 自带的 yum 源里 Postgres 版本偏老建议加官方源装新一点的版本。以 Postgres 13 为例yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm yum install -y postgresql13-server postgresql13-contrib /usr/pgsql-13/bin/postgresql-13-setup initdb systemctl enable postgresql-13 systemctl start postgresql-13装完之后要做两件事建 Kong 的数据库和用户以及调整认证配置。先切到 postgres 用户建库建用户su - postgres psql在 psql 里执行CREATE USER kong WITH PASSWORD 你的强密码; CREATE DATABASE kong OWNER kong; \q然后处理认证方式。默认的pg_hba.conf里本地连接可能是peer或identKong 用密码连接会失败需要改成md5或scram-sha-256。文件位置一般在/var/lib/pgsql/13/data/pg_hba.conf。找到本地连接那几行改成host all all 127.0.0.1/32 md5 host all all ::1/128 md5改完重启 Postgressystemctl restart postgresql-13。注意改pg_hba.conf之前先备份一份改错了会导致数据库连不上那时候就只能靠单用户模式恢复了很麻烦。2.3 安装 Kong 网关Kong 官方提供了 CentOS 的 RPM 包安装相对省心。先加仓库curl -1sLf https://packages.konghq.com/public/gateway-37/gpg.key -o /etc/pki/rpm-gpg/kong.asc然后配置 yum 源文件/etc/yum.repos.d/kong.repo内容指向官方仓库地址。具体地址会随版本变化建议以官方文档当前给出的为准。配置好之后yum install -y kong安装完成后Kong 的配置文件默认在/etc/kong/kong.conf.default需要复制一份成kong.conf再改cp /etc/kong/kong.conf.default /etc/kong/kong.conf关键配置项有这么几个配置项作用建议值database存储类型postgrespg_host数据库地址127.0.0.1pg_port数据库端口5432pg_user数据库用户kongpg_password数据库密码你设置的密码pg_database数据库名kongproxy_listen代理监听0.0.0.0:8000admin_listen管理接口监听127.0.0.1:8001这里admin_listen我强烈建议绑到127.0.0.1而不是0.0.0.0除非你明确知道自己在做什么。Admin API 权限极大暴露出去等于把网关的控制权交出去了。配置改好后初始化数据库kong migrations bootstrap -c /etc/kong/kong.conf看到迁移成功的提示后启动 Kongkong start -c /etc/kong/kong.conf验证一下curl -i http://127.0.0.1:8001/能返回 JSON 格式的节点信息就说明 Kong 起来了。2.4 安装 Node 环境与 KongaKonga 是个 Node.js 应用所以要先有 Node 环境。这里有个坑Konga 对 Node 版本有要求太新的 Node 反而可能编译失败。实测下来 Node 14 或 16 比较稳Node 18 以上有时会遇到依赖编译问题。装 Node 可以用 NodeSource 的源curl -fsSL https://rpm.nodesource.com/setup_16.x | bash - yum install -y nodejs node -v npm -v然后拉 Konga 源码。Konga 官方仓库可以直接 clone也可以下 release 包git clone https://github.com/pantsel/konga.git cd konga npm installnpm install这一步是最容易出问题的环节网络、依赖、编译工具链都可能卡住。如果报node-gyp相关的错通常是缺编译工具yum install -y gcc-c make python3装完依赖后配置 Konga 的环境变量。复制一份.env.example成.env重点改这几个PORT1337 NODE_ENVproduction DB_ADAPTERpostgres DB_URIpostgresql://kong:你的密码127.0.0.1:5432/konga注意这里的DB_URI是Konga 自己的数据库不是 Kong 的。虽然可以共用同一个 Postgres 实例但库名建议分开比如给 Konga 单独建一个konga库避免表结构冲突。建库CREATE DATABASE konga OWNER kong;然后初始化 Konga 的数据库表node ./bin/konga.js prepare --adapter postgres --uri postgresql://kong:密码127.0.0.1:5432/konga启动 Konganpm start浏览器访问http://服务器IP:1337能看到注册页面就成功了。3. 核心配置与联调实现3.1 Konga 连接 Kong 的关键配置Konga 起来之后第一件事是注册管理员账号然后添加 Kong 连接。这一步是整套方案的核心联调点配置错了后面全白搭。登录后进入 Connections 页面新建一个连接关键字段Name随便起比如local-kongKong Admin URL填http://127.0.0.1:8001这里有个细节如果 Konga 和 Kong 不在同一台机器127.0.0.1就不对了要填 Kong 所在机器的内网 IP同时 Kong 的admin_listen要放开到对应网段。但如前所述生产环境不建议这么做更稳妥的做法是让 Konga 和 Kong 同机部署或者通过内网反向代理转发 Admin API。连接建好后点激活如果能看到 Kong 的版本、节点信息说明联调成功。如果报连接超时或 401按这个顺序排查Kong 进程是否在跑ps -ef | grep kongAdmin API 是否可达curl http://127.0.0.1:8001/Konga 所在机器的网络能否访问目标地址防火墙是否放行3.2 用 Konga 配置第一个服务与路由联调通了之后就可以在 Konga 里配置实际的代理规则了。Kong 的核心概念是 Service 和 RouteService代表一个后端上游服务比如你的业务 API配置里填上游的协议、主机、端口、路径。Route代表匹配规则定义什么样的请求会被转发到这个 Service比如按路径、按域名、按方法匹配。举个实际例子。假设你有个后端服务跑在192.168.1.100:8080想通过网关暴露成http://网关IP:8000/api/user/xxx。在 Konga 里操作进入 Services新建一个 ServiceName 填user-serviceProtocol 选httpHost 填192.168.1.100Port 填8080。进入 Routes给这个 Service 加一条路由Paths 填/api/userMethods 勾选需要的 HTTP 方法。保存后请求http://网关IP:8000/api/user/xxx就会被转发到http://192.168.1.100:8080/api/user/xxx。这里有个路径处理的坑Kong 默认会把匹配到的路径原样转发。如果你想让/api/user这段前缀在转发时被剥掉需要在 Service 或 Route 上配置strip_path。这个选项在 Konga 的 Route 编辑界面里能找到默认是开启的具体行为要按你的后端接口设计来定。3.3 插件配置认证与限流网关的价值很大程度体现在插件上。Kong 社区版自带一批常用插件在 Konga 里可以直接给 Service、Route 或全局启用。Key Authentication 插件是最常用的认证方式之一。启用后Kong 会要求请求头里带一个 API Key没有或不对就返回 401。配置步骤在 Plugins 页面给目标 Service 添加key-auth插件。在 Consumers 页面创建一个消费者比如叫mobile-app。给这个消费者添加key-auth凭证Kong 会生成一个 key。客户端请求时带上apikey: 生成的key请求头。Rate Limiting 插件用来做限流。可以按秒、分、时、天配置请求上限还能按消费者、按 IP 维度限流。比如给某个 Service 配rate-limitingsecond填 100policy选local就表示每秒最多 100 个请求。提示local策略是在单个 Kong 节点内存里计数多节点部署时每个节点独立计数总量会翻倍。要做集群级精确限流需要配合 Redis把 policy 改成redis并配置 Redis 连接。3.4 数据库与端口的安全加固前面反复强调 Admin API 和面板的安全这里集中说一下加固要点。端口层面8001 和 1337 这两个端口是管理入口绝对不能对公网开放。用 firewalld 限制firewall-cmd --permanent --add-rich-rulerule familyipv4 source address192.168.1.0/24 port port8001 protocoltcp accept firewall-cmd --reload只允许内网网段访问其他一律拒绝。1337 同理。数据库层面Postgres 只监听本地或内网postgresql.conf里listen_addresses不要设成*。密码用强密码不要用默认的。Konga 层面Konga 支持配置认证方式生产环境建议接入统一的认证体系而不是用本地账号。另外 Konga 的.env文件里有数据库密码文件权限要收紧chmod 600 .envSELinux 层面如果 SELinux 是 enforcing 状态Kong 绑定非标准端口可能被拦。可以用semanage port -a -t http_port_t -p tcp 8000这类命令把端口加入允许列表而不是直接关掉 SELinux。4. 常见问题排查与避坑经验4.1 启动类问题速查搭建过程中最容易卡住的就是各种启动失败。我把踩过的坑整理成一张表方便对照排查。现象可能原因排查方向Kong 启动报数据库连接失败pg_hba.conf 认证方式不对检查是否改成 md5密码是否正确Kong 启动报 migration 未执行没跑 bootstrap执行 kong migrations bootstrapKonga npm install 失败缺编译工具或 Node 版本不对装 gcc-c make python3换 Node 16Konga 连不上 KongAdmin URL 填错或端口不通curl 测 8001检查防火墙浏览器打不开 1337Konga 没起来或端口没放行看 npm start 日志放行端口代理请求 502上游服务不可达检查 Service 配置的 host/port4.2 几个容易忽略的细节第一个坑是 Postgres 的密码认证。很多人建完用户就直接去配 Kong结果连不上回头才发现pg_hba.conf还是peer。这个前面提过但真的太多人中招值得再强调一次。第二个坑是 Konga 的数据库和 Kong 的数据库混用。虽然理论上可以放一个实例但库一定要分开。我见过有人图省事让两者共用一个库结果 Konga 的迁移脚本和 Kong 的表结构打架最后只能重建。第三个坑是 Node 版本。Konga 这个项目更新不算特别活跃对新版 Node 的兼容性一般。如果你用 Node 20 装依赖报一堆错别怀疑人生降到 16 大概率就好了。第四个坑是路径转发。Kong 的strip_path行为如果不注意会导致后端收到的路径和预期不一致接口 404。配置完一定要用 curl 实测一遍看后端日志里收到的真实路径是什么。4.3 性能与稳定性调优建议跑起来只是第一步要稳定运行还得调。几个实际有效的点Nginx worker 配置。Kong 底层是 Nginxkong.conf里的nginx_worker_processes默认是auto一般够用。但如果服务器 CPU 核数很多可以手动指定避免 worker 过多导致上下文切换开销。连接池。Kong 到 Postgres 的连接数要合理设置pg_max_concurrent_queries这类参数按实际并发调。数据库连接打满会导致请求排队。日志轮转。Kong 的 access 日志和 error 日志默认写在/usr/local/kong/logs/下长期运行会撑爆磁盘。配 logrotate 定期切割或者把日志输出到统一日志系统。健康检查。Kong 支持对上游做主动和被动健康检查在 Service 或 Upstream 上配置。后端有多个实例时健康检查能自动摘除故障节点这个在生产环境几乎是必配的。监控。Kong 暴露了/status接口可以接 Prometheus。Konga 本身也有一定的状态展示但要做长期监控还是得靠专业工具。5. 容器化部署的差异补充前面走的是裸机路线这里补充一下容器方式的关键差异方便不同环境的读者按需选择。容器方式的核心是一个docker-compose.yml里面定义三个服务postgres、kong、konga。关键点在于网络三个容器放同一个自定义网络里容器间用服务名互相访问比如 Konga 连 Kong 填http://kong:8001Kong 连 Postgres 填postgres。数据持久化Postgres 的数据目录要挂 volume否则容器一删数据全没。Kong 的迁移容器方式下迁移命令是docker exec进去执行或者用kong migrations bootstrap作为启动命令的一部分。Konga 的 prepare同样要在容器里跑一次 prepare。容器方式省去了装 Node、装 Postgres 的麻烦但排查问题时多了一层容器需要熟悉docker logs、docker exec这些操作。两种方式没有绝对优劣看团队的技术栈和运维习惯。我个人在实际操作中的体会是第一次搭建强烈建议先用裸机走一遍把每个组件的作用、端口、依赖关系都摸清楚之后再上容器会顺畅很多。直接上容器虽然快但一旦出问题因为不清楚底层发生了什么排查会很痛苦。另外无论哪种方式Admin API 和面板的安全加固都不能省这是整套方案里最容易被忽视、也最要命的一环。
