服务公告

服务公告 > 综合新闻 > Harbor：故障排查

Harbor：故障排查

发布时间:2026-04-22 16:01
标签： 故障排查

一、前言

搞过Harbor的人都知道，这玩意儿平时没事，一出事儿就是大事——不是登录界面502，就是镜像push到一半卡死，要么就是Web界面能打开但API彻底挂掉。最坑的是出问题你连从哪下手都不知道。本文直接甩实战排查路径，遇到问题照着走，别慌。

二、操作步骤

第1步：先看服务状态，别上来就翻日志

# 看Harbor核心组件状态（CentOS/RHEL用systemd，Ubuntu用systemd或docker-compose） $ docker ps | grep -E 'harbor-core|harbor-portal|harbor-registry|harbor-jobservice' CONTAINER ID IMAGE COMMAND STATUS a1b2c3d4e5f6 goharbor/harbor-core ... Up 2 hours b2c3d4e5f6a1 goharbor/harbor-portal ... Up 2 hours c3d4e5f6a1b2 goharbor/registry ... Up 2 weeks d4e5f6a1b2c3 goharbor/harbor-jobservice ... Up 2 hours # 正常情况所有容器都应该是Up状态，如果哪个Exit了或者Restarting，问题多半出在那

预期输出：所有容器应该是Up状态，运行时间应该是稳定增长。如果某个容器频繁重启，用docker logs看看。

第2步：检查核心日志，别只看nginx日志

# Harbor所有组件日志统一在这里（docker-compose部署） $ docker logs harbor-core --tail 100 # CentOS/RHEL用systemd的话看journald $ journalctl -u harbor-core -n 100 --no-pager # Ubuntu 22.04+用snap或独立安装的 $ journalctl -u harbor -n 100 --no-pager # 关键看这几类错误： # - "connection refused" → 服务没启动或端口被占用 # - "dial tcp: connection timeout" → 网络不通 # - "certificate has expired" → 证书过期 # - "database is locked" → SQLite/MySQL出了问题

预期输出：正常日志应该只有info级别的心跳日志。如果出现error或fatal，基本就是问题根源。

第3步：检查数据库连接（出问题的重灾区）

# Harbor用PostgreSQL的话，先测试数据库是否可达 $ docker exec harbor-db pg_isready -U postgres -h postgresql # 测试下能不能登录 $ docker exec harbor-db psql -U postgres -d registry -c "SELECT 1" # 正常输出 pg_isready ----------------- accepting connections # 如果报错 "could not connect to server" 或 "Connection refused" # 说明数据库服务挂了或者Harbor连不上数据库

预期输出：PostgreSQL应该accepting connections。如果数据库本身有问题，先重启数据库容器。

第4步：检查存储是否满了（90%的push失败原因）

# 查看Docker存储目录使用率（CentOS/RHEL默认路径） $ df -h /var/lib/docker $ docker info | grep "Data Space" # 查看Harbor registry数据卷 $ docker volume ls | grep harbor $ docker volume inspect harbor_registry_data # 检查实际占用 $ du -sh /var/lib/docker/volumes/harbor_registry_data/_data # ⚠️ 警告：不要轻易删数据，先清理无用的镜像和构建缓存 # 如果存储真满了，先扩容再排查

预期输出：如果使用率超过85%，基本就是存储导致的问题。清理空间后重启registry容器。

第5步：检查证书是否过期（自签名证书的坑）

# 检查Harbor域名证书有效期 $ echo | openssl s_client -connect harbor.example.com:443 -servername harbor.example.com 2>/dev/null | openssl x509 -noout -dates notBefore=Jan 15 09:00:00 2024 GMT notAfter=Feb 15 09:00:00 2025 GMT # 如果显示过期了，或者notAfter日期是过去的时间 # 马上要换证书，否则所有docker login都会失败 # 检查Harbor内部证书配置 $ cat /data/harbor/common/config/registry/root.crt

预期输出：证书应该在有效期内。如果快过期或已过期，必须立即处理。

第6步：验证网络连通性（DNS和端口最容易出问题）

# 测试Harbor核心端口是否通 $ nc -zv harbor.example.com 443 Connection to harbor.example.com 443 port [tcp/https] succeeded! # 测试registry端口 $ nc -zv harbor.example.com 5000 Connection to harbor.example.com 5000 port [tcp/*] succeeded! # 检查DNS解析（CoreDNS出问题时docker pull会报奇怪的错） $ nslookup harbor.example.com # 从外部机器测试（模拟客户端行为） $ docker login harbor.example.com -u admin -p YOUR_PASSWORD Error response from daemon: Get "https://harbor.example.com/v2/": dial tcp 10.0.0.100:443: connect: connection refused

预期输出：所有端口应该能连通。如果connection refused，说明防火墙或服务没开。

第7步：重启核心服务（有时候脏数据需要清理）

# docker-compose方式重启（Ubuntu/CentOS通用） $ cd /opt/harbor $ docker-compose down $ docker-compose up -d # 如果Harbor使用 systemd（CentOS/RHEL） $ systemctl restart harbor $ systemctl status harbor # 重启后观察日志 $ docker logs -f harbor-core

预期输出：服务应该正常启动，所有组件Up。如果启动失败，看docker-compose.yml配置是否被改过。

三、常见问题FAQ

Q1：Harbor Web界面能打开，但docker login一直报x509: certificate signed by unknown authority

这不是Harbor的问题，是你客户端没装证书。Ubuntu/Debian把Harbor的证书复制过去：

# CentOS/RHEL $ cp /data/harbor/ca.crt /etc/pki/ca-trust/source/anchors/ $ update-ca-trust # Ubuntu/Debian $ cp /data/harbor/harbor.example.com.crt /usr/local/share/ca-certificates/harbor.crt $ update-ca-certificates # 改完后再登录试试

Q2：镜像push到一半报错repository does not exist，可能是权限问题

别急着建仓库，先看用户有没有项目权限：

# 检查用户所属项目 $ docker login harbor.example.com -u testuser # 用API查用户角色 $ curl -k https://harbor.example.com/api/v2.0/users/2/permissions | jq # 常见坑：项目是私有的但用户没被加进去 # 或者用户被加了但没给push权限（只有pull）

Q3：Harbor升级后所有镜像都pull不下来了，提示manifest unknown

这通常是registry的schema版本不兼容。解决办法：

# 查看registry版本 $ docker exec harbor-registry registry --version # 强制切换schema版本 $ docker exec harbor-registry sh -c "registry serve /etc/registry/config.yml &" $ docker exec harbor-registry /bin/sh -c "cat /etc/registry/config.yml | grep schema" # 如果配置里有v2_manifests相关的设置，删掉重试 # 升级后配置有残留导致兼容性问题

Q4：harbor-db容器启动失败，磁盘IO特别高

可能是PostgreSQL写wal日志卡住了，清理下：

# 先检查是不是真的IO问题 $ iostat -x 1 # 如果是MySQL/PostgreSQL的临时文件问题 $ docker exec harbor-db sh -c "rm -rf /var/lib/postgresql/data/pg_xlog/*" $ docker restart harbor-db # ⚠️ 警告：生产环境谨慎操作，可能丢数据 # 先备份pg_xlog目录再清

四、总结

核心要点：

  1. 先看容器状态，别上来就翻日志，80%的问题看docker ps就能定位
  2. 存储满了是最常见的push/pull失败原因，定期清理不用镜像
  3. 证书过期前2周就要盯紧了，到期那天所有操作直接挂
  4. 数据库连接问题往往跟着OOM或者磁盘满，先查硬件资源

延伸阅读：

遇到问题先冷静，把服务状态→日志→数据库→存储→网络这条线排查完，基本没有解决不了的。急躁容易判断失误，多看少动。

相关推荐

上一篇： Windows系统管理：服务管理

下一篇： Apache：Apache日常运维