PuppyIP 资源中心
网络与连接排错 8 分钟 发布于 2026-11-17

Sub2API 数据库连接失败:区分 connection refused 与数据库不存在

连接拒绝先查监听;明确提示数据库不存在时,先确认实例和库名。只有确定是全新安装且缺库,才由数据库管理员补建,再用应用角色真实登录查询。

Sub2API PostgreSQL connection refused 数据库不存在

服务对象与地域限制

PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。

代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。

本文要点

  • 原生二进制安装不代表 PostgreSQL 和 Redis 已就绪。
  • Linux 服务账号、数据库角色和网站管理员需要分清。
  • 缺库只在确认实例与数据恢复需求后补建,不授予超级用户。
  • SQL、Redis、向导、迁移和业务调用分别验收。

连接拒绝与缺数据库是两个不同阶段

Sub2API 原生安装的数据库测试如果返回 connect: connection refused,先检查所填主机与端口是否确有 PostgreSQL 监听;如果返回 database "sub2api" does not exist,说明已经到达会响应的 PostgreSQL 实例,应核对实例和库名,再决定是否补建目标库。反复修改网页密码不能创建数据库。

本文适用于由 systemd 管理的原生部署,不把 Docker Compose 的服务名自动当作本机主机名。历史 Sub2API v0.2.15 的安装材料要求预备 PostgreSQL 和 Redis;安装了应用二进制不等于依赖、数据库角色、目标数据库和安装向导都已经准备完成。新版本应先对照对应版本的原生说明。

先核对监听、部署方式与依赖响应

在应用所在服务器本机检查监听端口。127.0.0.1 指当前网络命名空间的回环地址;在容器内部执行时,它通常指容器自己,而不是宿主机。下面保留 PostgreSQL 的 5432 与 Redis 的 6379 作为常见示例,实际部署如果改端口,应同步替换查询和应用配置。

只有表头或没有匹配项,说明本次未在这些端口观察到监听,不证明机器从未安装过数据库。先查实际服务、集群和端口,不要直接重新安装。Redis 的 PONG 只能说明这次 Redis 请求可用;如果当前 Redis 需要认证,应使用部署规定的安全认证方式,不要为照抄示例而关闭密码或公开监听。

查看依赖监听

bash
ss -lntp '( sport = :5432 or sport = :6379 )'
只读;进程详情可能需要相应权限。

验证本机 Redis 响应

bash
redis-cli -h 127.0.0.1 -p 6379 ping
只读请求;本示例仅适合已确认允许本机无密码访问的 Redis。

用应用数据库角色实际登录目标库

Linux 服务账号、PostgreSQL 登录角色和网站管理员是三种身份。用实际数据库角色替换 APP_DB_ROLE,使用 -W 交互输入密码,避免把密码写进命令、终端历史或公开工单。不要为了通过连接测试给应用角色超级用户权限。

保留错误原文,但删除服务器入口和账号细节。连接拒绝先回到监听层;password authentication failed 要核对当前实例、角色和认证设置;明确的数据库不存在错误才进入下一步。成功返回 current_user 与 current_database() 后,仍应确认查询连的是计划使用的实例,而不是另一套同端口部署。

执行一次真实数据库查询

bash
psql -h 127.0.0.1 -p 5432 -U APP_DB_ROLE -d sub2api -W -c 'SELECT current_user, current_database();'
只读 SQL;将 APP_DB_ROLE 换为已创建的普通应用角色,密码在提示中输入。

确认库确实缺失后,由数据库管理员补建

补建之前,确认目标实例、数据库名称和既有角色,并核对是否存在应当恢复的数据。若这是迁移后的旧业务,缺库可能是连错实例或尚未恢复备份;不能通过创建一个空库掩盖数据缺失,更不要删除、重建已有数据库。

对于确认是全新安装、目标库确实不存在且普通应用角色已存在的本机 PostgreSQL,可由有权限的数据库管理员创建数据库并指定该角色为所有者。下例保留系统管理员入口 postgres 和端口 5432,使用前必须与现场相符。创建完成后,重新执行上一节的应用角色 TCP 查询,而不是只看 createdb 没有输出。

这条 createdb 命令未指定 --host,默认通过本机 Unix socket 连接。端口相同不代表一定是同一套集群;执行前须由管理员确认该 socket 与前文 127.0.0.1:5432 属于同一个目标实例。若部署使用另一个集群、socket 目录或远程数据库,应改用该准确实例已批准的管理员连接方式,再创建目标库。

为全新安装创建目标库

bash
sudo -u postgres createdb --port=5432 --owner=APP_DB_ROLE sub2api
会创建数据库;仅适用于已确认的新安装和准确目标实例,不用于替代旧数据恢复。

把依赖验收与应用安装分开完成

数据库查询和 Redis PING 都通过后,把同一组已验证连接信息填写到应用向导,再分别检查网页测试连接、配置保存、迁移、管理员登录和实际业务调用。不要把本机 SQL 成功写成整个 Sub2API 已安装完成,也不要把空闲健康检查当作多人并发容量证明。

以后升级或迁移时,记录应用版本、部署方式、依赖实例和凭据保存位置,凭据本身留在受限环境。保留最小权限和本机监听边界;如果需要远程数据库,应另行设计网络、TLS 与访问控制,而不是把本机排错教程扩展成开放数据库端口的命令。

资料来源

常见问题

需要删除旧数据库重新建吗?

不需要,也不能由连接失败推出应删库。先确认实例、数据库名称和需要保留的数据;旧业务应按备份恢复流程处理。

Redis PONG 能证明整个应用正常吗?

不能。它只验证一次 Redis 请求,数据库、应用向导、迁移、登录和上游业务各有自己的验收结果。