Linux下如何部署Konga管理Kong网关

Konga启动后报500错误的根本原因是数据库连接失败或权限不匹配，而非UI问题；其0.14.x版本仅兼容Kong 1.x且必须使用PostgreSQL，需手动创建konga库、执行prepare初始化，并确保DB_URI完整、网络互通、Kong Admin API监听0.0.0.0:8001。

为什么Konga启动后打不开页面或报500错误

根本原因通常是数据库连接失败或权限不匹配，而不是UI本身问题。Konga 0.14.x 只兼容 Kong 1.x，且必须用 PostgreSQL（不能用 DB-less 模式）。常见现象是浏览器显示 500 Internal Server Error 或空白页，docker logs konga 里出现 Connection refused、permission denied to create database 或 relation "users" does not exist。

• 确保 PostgreSQL 容器已运行且暴露了 5432 端口，Konga 容器能通过 Docker 网络解析到它（比如用 kong-database 这个别名）
• DB_URI 必须完整包含协议、用户、密码、主机、端口和数据库名，例如：postgresql://kong:kong@kong-database:5432/konga —— 漏掉 :5432 或写成 localhost 就连不上
• Konga 自己需要一个独立数据库（konga），不能复用 Kong 的 kong 数据库；初始化前必须先手动创建该库：CREATE DATABASE konga OWNER kong;
• 执行初始化命令时，-c prepare 是必需步骤，否则表结构为空，后续请求直接 500；命令必须在 Konga 镜像内执行，且网络要和数据库容器一致

怎么用 Docker 正确启动 Konga 并连上 PostgreSQL

别跳过 prepare 阶段，也别指望 Konga 自动建库。Docker 启动分两步：先准备 schema，再运行服务。

• 第一步（仅一次）：

  docker run --rm --network=kong-net pantsel/konga:0.14.9 -c prepare -a postgres -u postgresql://kong:kong@kong-database:5432/konga

  其中 kong-net 是你之前为 Kong 创建的自定义网络，kong-database 是 PostgreSQL 容器名
• 第二步（长期运行）：

  docker run -d -p 1337:1337 --network=kong-net --name konga   -e "DB_ADAPTER=postgres"   -e "DB_URI=postgresql://kong:kong@kong-database:5432/konga"   -e "NODE_ENV=production"   pantsel/konga:0.14.9

  注意这里没加 -u root，Konga 不需要 root 权限
• 验证：curl http://localhost:1337 应返回 HTML；若超时，先 docker exec -it konga ping kong-database 确认网络连通性

Konga 登录失败或注册被拒怎么办

默认不开放注册，首次登录必须用管理员账号。Konga 不读取 Kong 的 Admin API 凭据，它有自己的用户体系。

• 首次启动后，Konga 会生成一个默认管理员账户：email: [email protected]，password: konga（不是 Kong 的密码）
• 如果改过密码但忘了，无法通过 UI 重置；只能进数据库手动更新：UPDATE users SET password='$2a$10$...' WHERE email='[email protected]';（哈希值需用 bcrypt 生成）
• 若想开放注册，启动时加环境变量：-e "KONGA_HOOKS_ENABLED=true" 并在 UI 中开启 “Allow user registration” 开关（路径：Settings → General）
• 登录页提示 Invalid credentials 但密码没错？检查 PostgreSQL 里 users 表的 active 字段是否为 true，有时邮件确认未完成会导致该字段为 false

访问 Konga 页面但看不到 Kong 节点或同步失败

Konga 和 Kong 是松耦合关系，Konga 不自动发现 Kong 实例 —— 所有 Kong Admin API 地址必须手动添加，且要求网络可达、认证通过。

• 在 Konga UI 的 Add new Kong node 页面填：http://kong:8001（Docker 内网地址）或 http://宿主机IP:8001（宿主机访问场景）；千万别填 localhost:8001，那是 Konga 容器自己的 loopback
• Kong 的 Admin API 必须监听 0.0.0.0:8001（不是 127.0.0.1:8001），检查 Kong 容器启动参数里是否有 -e "KONG_ADMIN_LISTEN=0.0.0.0:8001"
• 如果 Kong 启用了 Admin API 认证（kong.conf 中 admin_api_auth=on），Konga 添加节点时得填上 admin_key，否则同步失败且无明确报错
• 同步后仍显示 “No services found”？确认 Kong 本身已配置至少一个 service 和 route，Konga 只展示 Kong Admin API 返回的数据，不缓存也不生成

Konga 的核心陷阱不在前端，而在它和后端服务之间的三重网络隔离：Konga 容器 ↔ PostgreSQL 容器 ↔ Kong 容器。每层 DNS 解析、端口暴露、权限配置出一点偏差，整个链路就静默断裂。调试时优先查日志，而不是刷新页面。