Harbor 连接 PostgreSQL 报错 SQLSTATE XX000 排查指南

在维护 Harbor 镜像仓库时，我们可能会遇到 Harbor 核心服务无法连接数据库的情况，导致无法推送镜像或查看项目。本文将针对一个特定的 PostgreSQL 连接错误进行排查分析。

问题描述

在 Harbor 的 core 或 jobservice 等组件的日志中，出现了如下错误信息：

1

2026-01-26T09:15:06Z [ERROR] [/controller/event/handler/webhook/artifact/artifact.go:75]: failed to find policy for PUSH_ARTIFACT event: failed to get notification policies with projectID 34: failed to connect to `host=postgresql-postgresql-ha-pgpool.harbor.svc.kubeyy.com user=postgres database=harbor_db`: server error (ERROR: unable to read message kind (SQLSTATE XX000))

关键信息提取：

• 错误组件：Artifact Webhook (Harbor Core)
• 操作：PUSH_ARTIFACT (推送镜像后触发)
• 连接目标：postgresql-postgresql-ha-pgpool (使用了 Pgpool-II 组件)
• 错误内容：server error (ERROR: unable to read message kind (SQLSTATE XX000))

此外，在数据库连接不稳定期间，你可能还会看到类似以下的副作用报错（通常发生在 P2P 预热或扫描等异步任务中）：

1

[ERROR] [/pkg/notifier/notifier.go:218]: Error occurred when triggering handler *p2p.Handler of topic PUSH_ARTIFACT: artifact 93262 not found

这是因为事件被触发了，但后续尝试去数据库查询该 Artifact 详情时，由于连接断开而失败，导致报 “not found”。

故障分析

什么是 SQLSTATE XX000？

XX000 是 PostgreSQL 的一个通用“内部错误”代码。当数据库遇到它无法归类为特定错误（如权限拒绝、表不存在等）的情况时，就会抛出这个代码。

“unable to read message kind” 是什么意思？

这个错误信息非常关键。它通常意味着通信协议错乱。

想象一下你正在打电话，对方突然不说话了，或者发出了奇怪的噪音，你无法理解对方在说什么。在数据库通信中，客户端（Harbor）期待服务器（Pgpool）发送特定格式的数据包，但服务器发送的数据无法被解析，或者连接突然中断了。

在 Harbor 使用 Pgpool-II 的高可用架构中，最常见的原因是：Pgpool 与后端真实的 PostgreSQL 数据库节点断开了连接。当后端数据库重启、网络抖动或发生主从切换时，Pgpool 可能会暂时无法正确处理客户端的请求，导致返回错误的数据包，从而引发这个报错。

排查与解决步骤

作为一名初学者，你可以按照以下步骤一步步排查。

第一步：检查数据库 Pod 状态

首先，我们需要确认数据库相关的 Pod 是否都正常运行。

打开终端，运行以下命令（假设 Harbor 部署在 harbor 命名空间）：

1

kubectl get pods -n harbor -l app.kubernetes.io/name=postgresql-ha

预期结果： 你应该看到类似以下的输出，所有 Pod 的状态都应该是 Running 且 READY 为 1/1（或更多）。

1
2
3
4

NAME                                            READY   STATUS    RESTARTS   AGE
postgresql-postgresql-ha-pgpool-5c7d6d7f9-abcde 1/1     Running   0          5d
postgresql-postgresql-ha-postgresql-0           1/1     Running   0          5d
postgresql-postgresql-ha-postgresql-1           1/1     Running   0          5d

异常情况：

• 如果看到 CrashLoopBackOff 或 Error，说明数据库挂了，需要查看该 Pod 的日志。
• 如果看到 RESTARTS 次数在最近增加，说明数据库刚刚重启过，这可能就是导致连接中断的原因。

第二步：查看 Pgpool 日志

如果 Pod 状态看起来正常，我们需要看看 Pgpool 到底经历了什么。

1

kubectl logs -n harbor -l app.kubernetes.io/component=pgpool --tail=100

在日志中搜索 “Error” 或 “Failover” 等关键字。你可能会看到类似 “backend 0 is down” 或 “failed to connect to backend” 的信息，这证实了 Pgpool 失去了与后端数据库的连接。

第三步：重启 Pgpool（快速恢复）

对于 SQLSTATE XX000 这种协议类错误，最简单有效的恢复方法通常是重启 Pgpool Pod。这会强制它重新建立与后端数据库的连接。

1

kubectl delete pod -n harbor -l app.kubernetes.io/component=pgpool

注意：Kubernetes 会自动重建这个 Pod，不会导致数据丢失。

等待 Pod 重启变为 Running 状态后，再次尝试推送镜像或访问 Harbor，问题通常就会解决。

第四步：验证连接（进阶）

如果你想确认连接是否完全恢复，可以进入 Harbor Core 的 Pod 手动测试数据库连接。

1. 找到 Harbor Core 的 Pod 名称：

   1	kubectl get pods -n harbor -l app=harbor,component=core

2. 进入 Pod：

   1	kubectl exec -it -n harbor <harbor-core-pod-name> -- bash

3. 测试网络连通性（如果 Pod 里有 nc 或 telnet）：

   1	nc -zv postgresql-postgresql-ha-pgpool.harbor.svc.kubeyy.com 5432

   如果显示 Open 或 Connected，说明网络通了。

验证修复

当问题解决后，你可能会在 Harbor 日志中看到类似以下的 INFO 信息，这标志着 Harbor 已经能够正常连接数据库并处理业务逻辑了：

1

2026-01-26T09:43:43Z [INFO] [/controller/blob/controller.go:118][requestID="..."]: artifact digest sha256:... already exist, skip to associate blobs with the artifact

这条日志说明：

1. 数据库连接成功：Harbor 成功查询了数据库，确认了该镜像层（Artifact Digest）已经存在。
2. 业务逻辑正常：系统正确执行了“跳过已存在层”的优化逻辑，这是正常且健康的表现。

总结

server error (ERROR: unable to read message kind (SQLSTATE XX000)) 这个错误虽然看起来很吓人，但通常只是暂时的连接状态不同步。

• 根本原因：Pgpool 中间件与后端数据库连接异常。
• 最快解法：删除（重启）Pgpool Pod。

只要数据库后端节点（StatefulSet）是正常的，重启无状态的 Pgpool 中间件是非常安全的操作。