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这类报错。
为什么Konga启动后打不开页面或报500错误
先别急着怀疑前端，问题几乎都出在后端链路。排查的时候按下面几个点来捋：
- PostgreSQL容器得确保已经跑起来，并且暴露了
5432端口。Konga容器要通过Docker网络解析到它——比如你之前把PostgreSQL容器起名叫kong-database，那Konga这边就得用这个别名去连。 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 https://localhost:1337应该返回HTML。如果超时，先用docker exec -it konga ping kong-database确认网络连通性。
Konga登录失败或注册被拒怎么办
默认情况下Konga不开放注册，第一次登录必须用管理员账号。注意：Konga有自己的用户体系，跟Kong的Admin API凭据是两个东西。
- 首次启动后，Konga会生成一个默认管理员账户：
email: admin@konga.com，password: konga（不是Kong的密码）。 - 如果你改过密码但忘了，UI上没办法重置。只能进数据库手动更新：
UPDATE users SET password='$2a$10$...' WHERE email='admin@konga.com';——这里的哈希值需要用bcrypt生成。 - 如果想开放注册，启动时加环境变量
-e "KONGA_HOOKS_ENABLED=true"，然后在UI的Settings → General里开启“Allow user registration”开关。 - 登录页提示
Invalid credentials但密码明明没错？检查一下PostgreSQL里users表的active字段是不是true。有时候邮件确认没完成，这个字段会被设成false，导致认证被拒。
访问Konga页面但看不到Kong节点或同步失败
Konga和Kong是松耦合关系，Konga并不会自动发现Kong实例。所有Kong Admin API地址必须手动添加，并且网络要可达、认证要通。
- 在Konga UI的Add new Kong node页面，填入
https://kong:8001（Docker内网地址）或者https://宿主机IP:8001（宿主机访问场景）。千万别写localhost:8001，那是Konga容器自己的loopback，压根连不上Kong。 - 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解析、端口暴露、权限配置出一点偏差，整个链路就静默断裂。调试时优先查日志，而不是反复刷新页面——日志里往往已经写清楚了问题所在。
