Mac 上安装与配置 Harbor 的完整指南
Harbor 是一个企业级的容器镜像仓库，提供安全存储、管理、签名和扫描等功能。在 Mac 上安装 Harbor 需要特别注意 Apple Silicon 芯片 (M1/M2) 的兼容性问题。本文将详细介绍在 Mac 上安装和配置 Harbor 的完整流程，包括 ARM 架构适配、证书配置以及常见问题解决。
一、环境准备
在开始安装 Harbor 之前，需要确保 Mac 满足以下基础条件：
Docker 环境：必须安装 Docker Desktop，建议版本 20.10.10 及以上
Docker Compose：需要安装 docker-compose，建议版本 1.29.2 及以上
系统资源：至少 4GB 内存和 10GB 可用磁盘空间
操作系统：macOS Monterey 或更高版本
对于 Apple Silicon 芯片 (M1/M2) 的 Mac，需要特别注意：
默认的 Harbor 镜像是为 x86_64(amd64) 架构构建的，不兼容 ARM 架构
需要专门获取或编译 ARM 版本的 Harbor 镜像
二、安装步骤
1. 获取Harbor安装包
对于 Intel 芯片的 Mac，可以直接从官方 GitHub 下载最新版本：
wget https://github.com/goharbor/harbor/releases/download/v2.10.2/harbor-offline-installer-v2.10.2.tgz 对于 Apple Silicon 芯片 (M1/M2) 的 Mac，需要使用第三方编译的 ARM 版本：
wget https://github.com/wise2c-devops/build-harbor-aarch64/releases/download/v2.10.2/harbor-offline-installer-aarch64-v2.10.2.tgz 2. 解压安装包
tar -zxvf harbor-offline-installer-*.tgz
cd harbor建议将解压后的目录放在/usr/local/harbor或/home/[username]/harbor
3. 配置Harbor
复制模板配置文件并重命名：
cp harbor.yml.tmpl harbor.yml编辑harbor.yml文件，主要修改以下配置项：
hostname: harbor.yourdomain.com # 改为本地IP或域名
http:
port: 80
https:
port: 443
certificate: /path/to/cert.crt
private_key: /path/to/cert.key
harbor_admin_password: Harbor12345 # 管理员密码
data_volume: /usr/local/harbor/data # 数据存储路径
log:
local:
location: /usr/local/harbor/logs # 日志存储路径对于本地测试，可以注释掉 https 部分，仅使用 HTTP：
# https:
# port: 443
# certificate: /your/certificate/path
# private_key: /your/private/key/path4. 生成证书(如需HTTPS)
在/opt/cert目录下创建自签名证书：
sudo mkdir /opt/cert && cd /opt/cert创建openssl.cnf配置文件：
cat > openssl.cnf <<-EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn
[dn]
C = CN
ST = State
L = Locality
O = Organization
OU = Organizational Unit
CN = harbor.yourdomain.com
[req_ext]
subjectAltName = @alt_names
[alt_names]
DNS.1 = harbor.yourdomain.com
EOF生成私钥和证书：
openssl req -new -sha256 -nodes -out harbor.csr -newkey rsa:2048 -keyout harbor.key -config openssl.cnf
openssl x509 -req -in harbor.csr -signkey harbor.key -out harbor.crt -days 365 -extfile openssl.cnf -extensions req_ext5. 修改hosts文件(如使用域名)
编辑/etc/hosts文件，添加域名映射：
127.0.0.1 harbor.yourdomain.com6. Docker Desktop配置
在 Docker Desktop 中添加 harbor 目录的共享权限：
打开 Docker Desktop
进入 Preferences → Resources → File Sharing
添加 harbor 目录路径 ( 如
/usr/local/harbor)点击 "Apply & Restart"
7. 安装Harbor
执行安装脚本：
sudo ./install.sh安装完成后，Harbor 会自动启动相关容器服务
三、验证安装
1. 检查容器状态
docker-compose ps正常情况应显示所有服务均为 "healthy" 状态：
NAME COMMAND SERVICE STATUS PORTS
harbor-core "/harbor/entrypoint..." core healthy
harbor-portal "nginx -g 'daemon ..." portal healthy
...2. 访问Web界面
在浏览器中访问配置的 hostname 或 IP 地址：
http://harbor.yourdomain.com 使用默认凭据登录：
用户名：admin
密码：Harbor12345(或配置文件中设置的密码)
3. Docker登录测试
docker login harbor.yourdomain.com -u admin -p Harbor12345四、常见问题解决
1. ARM架构兼容性问题
错误信息：
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
exec /usr/bin/python3: exec format error解决方案：
使用专为 ARM 架构编译的 Harbor 镜像
或自行编译 ARM 版本的 Harbor 镜像
2. 推送/拉取镜像失败
错误信息：
Error response from daemon: Get " https://harbor.yourdomain.com/v2/ ": x509: certificate signed by unknown authority解决方案： 修改 Docker 配置，添加信任仓库：
# 编辑或创建/etc/docker/daemon.json
{
"insecure-registries": ["harbor.yourdomain.com"]
}
# 重启Docker
sudo systemctl restart docker3. 存储目录权限问题
错误信息：
Error starting userland proxy: listen tcp 0.0.0.0:80: bind: permission denied解决方案：
确保 harbor 目录有正确权限：
sudo chmod -R 777 /usr/local/harbor或使用非特权端口 (如 8080)
4. 证书相关问题
错误信息：
Error: error contacting notary server: dial tcp 192.168.1.104:443: connection refused临时解决方案：
unset DOCKER_CONTENT_TRUST但不推荐在生产环境使用
五、高级配置
1. 使用NFS存储(可选)
对于更稳定的存储方案，可以配置 NFS 共享存储：
mkdir -p /opt/data/nfs/harbor/{chartmuseum,jobservicemkdir,registry,database,redis,trivy}
sudo vim /etc/exports
sudo nfsd update
sudo nfsd restart2. 防火墙配置
确保相关端口开放：
sudo pfctl -s rules # 查看当前规则
sudo vim /etc/pf.conf # 添加规则
sudo pfctl -f /etc/pf.conf # 重新加载配置3. Kubernetes集成(高级)
在 Mac 的 K3s 集群中部署 Harbor：
kubectl rollout restart deployment.apps/harbor-core -n harbor
kubectl rollout restart deployment.apps/harbor-jobservice -n harbor
...六、维护与管理
1. 启动/停止Harbor
# 启动
docker-compose up -d
# 停止
docker-compose down2. 修改配置后重启
# 生成新配置
./prepare
# 停止现有实例(数据会保留)
docker-compose down -v
# 重启
docker-compose up -d3. 备份与恢复
定期备份以下目录：
配置文件：
/usr/local/harbor/harbor.yml数据目录：
/usr/local/harbor/data证书文件：
/opt/cert/
总结
在 Mac 上安装 Harbor 需要注意架构兼容性和目录权限问题，特别是对于 Apple Silicon 芯片的 Mac 用户。通过正确配置和解决常见问题，可以在 Mac 上建立功能完整的私有镜像仓库，为开发团队提供安全可靠的容器镜像管理服务。
对于生产环境，建议：
启用 HTTPS 加密通信
配置定期备份策略
监控资源使用情况
根据团队规模调整资源配置
通过本指南，您应该能够在 Mac 上成功安装和配置 Harbor，并解决可能遇到的大部分问题。如需更高级的功能如高可用部署或漏洞扫描，可以参考 Harbor 官方文档进行进一步配置。