简介面向麒麟V10与ARM64架构环境运维人员、容器平台搭建者的Harbor v2.4.0镜像仓库离线部署资源包。整套方案覆盖从环境准备、配置文件编写、证书生成到docker-compose安装启动的关键环节适配国产化操作系统与ARM处理器可帮助用户规避原生x86安装包不兼容、依赖缺失等常见问题快速落地内网镜像仓库。压缩包共包含8个文件整体约407.22MB文件类型以shell脚本环境检查、安装、证书生成、离线镜像压缩包、docker-compose YAML配置模板及license等为主并提供prepare初始化脚本与tmpl模板文件便于按实际域名、端口调整参数后直接执行整体结构清晰。目前已有314人学习下载适合具备Docker、Docker Compose基础、正在为麒麟V10匹配K8s集群镜像源的运维工程师参考。通过该资源可掌握ARM64架构下Harbor离线安装的完整流程、配置模板的调整思路以及国产化环境中容器镜像仓库的部署要点便于在生产环境中复用。1. 麒麟V10ARM64部署Harbor v2.4.0离线部署镜像仓库的实战起点在银河麒麟V10ARM64架构服务器上部署Harbor v2.4.0镜像仓库工具是很多国产化替代项目里的第一个硬骨头。官方默认安装包大多面向amd64直接拿x86的离线包到飞腾、鲲鹏机器上装prepare阶段就会报错甚至镜像加载完成也拉不起容器。而harbor-offline-installer-v2.4.0-aarch64.tgz这个离线包把Harbor核心镜像、安装脚本、配置模板全打成了aarch64版本配合麒麟V10 SP3常见环境一次prepare、install就能把仓库跑起来。这篇文章基于我实际拆包部署的完整过程从版本核对到推送镜像再到对接k8s拉取把命令、参数和翻车点写透。适合手里只有ARM64银河麒麟机器、想在纯内网搭镜像仓库的运维和开发。2. 部署前准备核对麒麟V10版本、ARM64架构与Docker环境2.1 为什么必须选aarch64离线包以及如何核对系统底子Harbor从v2.x开始官方在release里同时发布amd64和arm64两种离线安装包。harbor-offline-installer-v2.4.0-aarch64.tgz里的harbor.v2.4.0.tar.gz是已经打好tag的镜像包内部所有容器镜像都是aarch64架构。如果你在飞腾FT-2000、鲲鹏920这类ARM64 CPU上强行用amd64包docker load阶段大概率不会报错但启动容器时会直接提示“bad linux arm64 image magic”之类的错误原因就是镜像层平台不匹配内核不认。拿到机器后第一步不是解压安装包而是确认系统、架构和内核版本。常规做法是执行下面三条命令cat /etc/os-release uname -m uname -r命令里各参数的含义cat /etc/os-release查看是不是Kylin V10以及具体SP版本。我这边是银河麒麟V10 SP3kernel版本5.4.x。SP1、SP2、SP3在docker和containerd兼容性上差异不大但SP3默认的yum源里python、openssl版本更高对Harbor v2.4.0的prepare二进制更友好。uname -m必须显示aarch64这是ARM64跑起来的前提。如果显示x86_64说明装的还是amd64系统那用aarch64包也会出问题。uname -r内核版本建议4.19以上。我在麒麟V10 SP1上遇到过内核4.19.18的机器overlayfs和iptables兼容性一般nginx容器起来后端口映射异常后来升到5.4问题消失。这里顺便提一句qemu模拟arm64如果你手上没有真机只会在一台x86服务器上用qemu-system-aarch64模拟ARM64环境我建议别把它当成生产验证环境。qemu模拟的CPU性能很低Harbor七个容器全部启动可能需要十几分钟而且模拟环境下docker的overlay2驱动偶尔出现页缓存异常结论不能代表真实飞腾机器。有条件一定要用真机。2.2 安装Docker与docker-compose看清Harbor到底调用哪个命令麒麟V10自带的yum源里默认没有docker-ce直接执行yum install docker装出来的是1.13时代的“docker”包那个跑不起来Harbor v2.4.0。现场有两种路线。第一种机器能连外网直接加docker官方yum源。注意银河麒麟V10兼容CentOS 8repo路径要用linux/centos/docker-ce.repo不要用CentOS 9路径yum install -y yum-utils yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo yum install -y docker-ce docker-ce-cli containerd.io第二种内网环境没有外网那就找一台能联网的AMD64机器把arm64版本的rpm包下载好拷进去再rpm -ivh。这一步最容易翻车的是误下成x86_64的包教大家一个快速判断法file docker-ce-20.10.9-3.el8.aarch64.rpm输出里会带ARM aarch64字样。如果是x86_64的rpm在aarch64机器上安装时yum会直接报“wrong architecture”。docker-compose方面Harbor v2.4.0的install.sh内部调用的是docker-compose命令不是docker compose子命令。compose v2已经变成了docker的子命令很多教程让你直接装v2结果install.sh报“command not found”。我一般固定用v1.29.2的aarch64二进制curl -L https://github.com/docker/compose/releases/download/v1.29.2/docker-compose-linux-aarch64 -o /usr/local/bin/docker-compose chmod x /usr/local/bin/docker-compose docker-compose --version注意下错版本时的表现x86_64的compose二进制放在aarch64机器上执行时会报Exec format error而不是提示版本不对。这个错误非常容易误判成权限问题。另外麒麟V10自带yum源里如果已经有老版docker-compose python包建议先yum remove docker-compose再放二进制否则which docker-compose会先找到yum装的旧版导致Harbor觉得版本太老直接拒绝启动。2.3 初始化数据目录、关闭防火墙与放行端口Harbor默认监听80和443端口。安装前建议先确认这两个端口没被其他服务占用ss -lntp | grep -E :80|:443如果被占用后面harbor的nginx容器会反复重启。在麒麟V10上常见的是httpd或caddy占着80。占用时有两个选择改Harbor的http.port或者停掉占用服务。我习惯把Harbor放在独立服务器上直接把防火墙关了systemctl stop firewalld systemctl disable firewalld setenforce 0这里有一个很隐蔽的坑麒麟V10默认selinux状态是enforcing直接停firewalld不关selinuxHarbor的数据卷data_volume如果正好放在某个带特殊SELinux上下文的位置nginx容器往里面写缓存文件时会报权限拒绝而且日志里只显示“permission denied”。所以上面两行是一起执行的。如果公司安全规范强制要求开selinux那要写好多安全上下文规则不太划算内网环境一般直接关。数据目录也要提前规划好。Harbor离线包解压后大约2GB镜像加载后占用大约8~10GB再加上数据库和registry镜像存储一个初始化的Harbor仓库大概要吃15GB。我一般给/data单独分50GB以上。检查磁盘df -h /data如果/data空间紧张至少保证:Warning否则后面docker load -i harbor.v2.4.0.tar.gz一执行磁盘马上写满docker daemon进入只读状态还会连累其他容器。注意确认harbor.yml里的data_volume路径最好也放在这个盘下。时钟同步也得提前做。Harbor的nginx容器启动时会校验服务端证书有效期如果机器时钟漂移严重刚生成的自签证书显示“not yet valid”所有https请求全部失败。麒麟V10默认带chrony执行一下systemctl enable chronyd systemctl start chronyd chronyc sources -vchronyc sources -v能看到时钟源是否处于^*状态一个星号都没有说明没同步成功这时候生成的证书和后续的docker登录都会踩x509时间坑。这段虽然不起眼但生产环境里我排查过好几次都是挂在时钟上。3. 修改harbor.yml与执行install.sh从自签证书到仓库初始化3.1 解压离线包并理解它的文件结构先把aarch64离线包放到目标机器的/tmp或/root目录然后建一个专门的部署目录mkdir -p /opt/harbor_install cd /opt/harbor_install tar -zxvf /tmp/harbor-offline-installer-v2.4.0-aarch64.tgz cd harbor ls -l解压后的关键文件如下文件/目录作用是否必须修改harbor.yml.tmpl官方配置模板需要复制为harbor.yml必须harbor.v2.4.0.tar.gz整包Harbor容器镜像供docker load不修改install.sh主部署脚本含镜像加载、prepare、compose up不修改prepare编译好的prepare二进制生成配置不修改common.sh公共函数install.sh执行时source不修改config配置目录nginx、db等模板一般不改cert.sh自签证书生成脚本可能需要修改LICENSE许可文件不修改这里必须强调的是别从Windows解压tar再上传文件。tar在Linux下带有软链接和可执行权限位Windows解压会把这些信息丢掉。我见过有人把整个目录在Windows下解压后用ftp传上去文件都在但install.sh无法执行因为权限位变成了普通文本文件。正确做法是把tar原封不动传到Linux机器上再解压。解压后先校验一下install.sh和prepare有没有执行权限ls -l install.sh prepare如果-rw-r--r--没有x执行chmod x install.sh prepare common.sh cert.sh3.2 修改harbor.ymlhostname、密码、端口与数据目录官方模板harbor.yml.tmpl不能直接用必须复制成harbor.ymlcp harbor.yml.tmpl harbor.yml vim harbor.yml列出最关键的配置段并解释每个参数hostname: 192.168.209.133 http: port: 80 https: port: 443 certificate: /data/certs/harbor.crt private_key: /data/certs/harbor.key harbor_admin_password: Harbor12345 database: password: HarborDB123 max_idle_conns: 50 max_open_conns: 100 max_lifetime: 10m data_volume: /data/harbor log: level: info rotate_count: 10 rotate_size: 50M quota: per_project_enabled: true参数说明hostname必须写内网IP或域名这是Harbor对外访问的唯一入口。写localhost的话本机浏览器能打开页面但docker push会去访问“localhost”客户端解析的却是自己的回环地址镜像怎么都推不上去。我推荐直接用IP省去内网DNS配置。http.port、https.port默认80、443。如果这两口被占可以改成8080、8443但要连带改docker客户端的insecure-registries和登录端口。后面推送命令里必须带端口号。https.certificate和private_key证书路径一定要写绝对路径。这里的坑在于如果你用的相对路径Harbor的prepare阶段不一定报错但nginx容器启动时挂载不到证书文件会一直重启。harbor_admin_passwordadmin初始密码最少8位必须同时包含大写、小写和数字。这里设置的密码是给web登录和docker login初始用的。database.passwordHarbor内置postgres数据库的密码同样要不少于8位且够复杂。强烈建议和管理员密码区分开。max_idle_conns、max_open_conns数据库连接池参数。连接数开太小多项目并发推送时会出现“database: too many connections”。按你的并发量调默认值一般够用。data_volume镜像、数据库、缓存的所有存储根目录。生产环境一定要放到独立大分区并且备份时只需要备份这个目录。quota.per_project_enabled表示是否开启每个项目的配额开启后可以在web台上按项目限制存储空间。这个配置对多团队共用仓库很重要默认是true不用改。注意yaml里的冒号后面必须有空格否则Harbor的prepare读取配置时会直接报“Failed to parse yaml file”。改完文件后强烈建议做一次语法检查python3 -c import yaml; print(yaml.safe_load(open(harbor.yml)))麒麟V10自带的python3可能没有yaml模块会报ModuleNotFoundError。这时可以改用cat -A harbor.yml | grep -n \^M凡是带^M的行都是Windows换行符需要整体转换。用sed -i s/\r$// harbor.yml清理掉。3.3 用cert.sh生成自签证书注意CN与SAN的一致性如果你的内网没有正式CAHarbor提供了cert.sh脚本生成自签证书。它的用法./cert.sh 192.168.209.133它会生成私钥harbor.key和证书harbor.crt放到指定路径。这里有一个非常关键的点cert.sh生成的证书默认可能不包含SAN扩展。Go 1.15之后的docker客户端在验证证书时不再只看Common Name必须检查SAN。如果SAN里没有你的IP或域名docker login会报x509: cannot validate certificate for 192.168.209.133 because it doesnt contain any IP SANs碰到这个问题不要急着改docker配置直接用openssl重新生成mkdir -p /data/certs cd /data/certs cat openssl.cnf EOF [req] distinguished_name dn req_extensions ext prompt no [dn] CN 192.168.209.133 [ext] subjectAltName IP:192.168.209.133 extendedKeyUsage serverAuth EOF openssl req -newkey rsa:2048 -nodes -keyout harbor.key -x509 -days 3650 -config openssl.cnf生成后检查openssl x509 -in harbor.crt -text -noout | grep -A2 Subject Alternative Name确认输出里有IP Address:192.168.209.133再更新harbor.yml中的certificate和private_key路径。另外注意到cert.sh在部分离线包版本里写的证书路径是相对路径导致prepare时找不到密钥。所以无论用哪个脚本最终都要确认/data/certs/harbor.crt和/data/certs/harbor.key两个文件存在ls -l /data/certs/3.4 执行prepare和install.sh分步执行比一把梭更可控直接执行./install.sh会依次完成四件事docker load -i harbor.v2.4.0.tar.gz加载镜像、./prepare生成配置文件、docker-compose up -d启动容器、最后做健康检查。第一次执行比较慢因为镜像文件约1GB加载需要几分钟。我不想等的时候会先单独加载镜像再单独跑prepare能清楚看到是哪一步出的问题docker load -i harbor.v2.4.0.tar.gz ./prepare docker-compose up -d分开执行的好处是docker load输出的“Loaded image”列表能确认镜像是否包含aarch64架构./prepare能提前暴露配置语法和目录挂载问题最后docker-compose up -d才是真正启动容器。如果一步到位install.sh出现错误时你不容易判断是镜像损坏还是配置问题。prepare阶段如果成功会在当前目录生成docker-compose.yml这就是Harbor真正启动的编排文件。你可以打开看一眼里面包含了nginx、registry、harbor-core等服务的定义。查看容器状态docker ps标准情况下会有以下容器在运行容器名作用harbor-core核心API服务harbor-dbPostgreSQL数据库harbor-registry镜像存储的registry服务harbor-portalWeb前端页面nginx反向代理、路由转发harbor-log统一日志收集harbor-redisredis缓存如果某个容器处于Restarting状态不要立刻重跑install.sh先看日志docker logs harbor-core --tail 100最常见的错误是failed to connect to database数据库容器还没起来或数据库密码不对。EOF或connection refusednginx容器启动慢等待重试即可。这里有一个容易被误判的现象第一次启动时harbor-core会等harbor-db完成postgres初始化这个过程在ARM64真机上大约30秒。如果你用qemu模拟ARM64环境可能要等3-5分钟期间日志里一直出现“dial tcp ... connection refused”。这不是故障是初始化还没完成。我的建议是多等一会儿不要看到失败日志就重装。3.5 HTTP模式与HTTPS模式的选择内网部署的最省事路径如果你不想花时间弄证书这里有个非常务实的方案直接关闭HTTPS只用HTTP跑内网。改harbor.yml时把https段整个注释掉或删除hostname: 192.168.209.133 http: port: 8080 # https: # port: 443 # certificate: /data/certs/harbor.crt # private_key: /data/certs/harbor.key注意harbor.yml里不能保留空的https:键prepare阶段会报错“https configuration is empty”。然后把http.port设成非特权端口8080避免和其他服务冲突。执行./prepare和docker-compose up -d后所有客户机都要在docker daemon里把这个地址加入insecure-registries{ insecure-registries: [192.168.209.133:8080] }改完daemon.json后必须systemctl restart docker这样docker login、tag、push都要带端口号。内网测试环境这么跑最省事但要注意docker客户端访问HTTP仓库时必须显式加端口否则默认走443会直接超时。生产环境如果安全要求严格建议把HTTPS做规范毕竟Harbor的web页面管理员密码、镜像标签都是明文HTTP传输有被内网嗅探的风险。4. Harbor部署避坑五条会翻车的现场记录与排查4.1 推送失败dial tcp IP:端口 connect: connection refused现象执行docker push时报Get https://192.168.209.133/v2/: dial tcp 192.168.209.133:443 connect: connection refused原因Harbor实际监听的端口和docker客户端访问的端口不一致。比如你配置的是http.port: 8080但docker登录时写的是docker login 192.168.209.133没带端口docker默认走443当然连不上。还有一种情况是https.port配置了443但证书路径配错nginx容器起不来443端口就没有监听。解决先看端口ss -lntp | grep -E :80|:443|:8080如果Harbor监听的是8080那docker命令里所有地址都要写192.168.209.133:8080。同时检查daemon.json里的insecure-registries是否也带上了端口。注意insecure-registries里写的端口必须和harbor.yml里http.port一致少写一个冒号都连不上。这个坑在k8s节点上尤其常见因为kubelet和containerd各自配置一套漏掉一个就会出现“镜像拉不到”。4.2 镜像加载后容器一直重启看harbor-log而不是harbor-core现象docker ps里harbor-log状态为Restarting或者过几秒钟反复重启。执行docker logs harbor-log时却发现几乎没内容。原因Harbor的日志容器负责收集所有容器日志如果它起不来通常是因为宿主机上/var/log/harbor目录权限不对或者日志轮转参数rotate_count、rotate_size设置不合法。我遇到过安全加固过的麒麟V10把/var/log挂成了只读harbor-log往里写日志直接失败。解决先去看真正的系统日志而不是harbor-log自己的日志docker inspect harbor-log | grep -i mount ls -la /var/log/harbor确保该目录存在且属主是root、权限755。然后修改harbor.yml里的log段把rotate_size改小一点再重新prepare。如果还不行检查磁盘inode是否耗尽df -i /var/loginode满也会导致日志文件创建失败。现场排查时不少新手被“harbor-log重启”误导疯狂改数据库配置其实是日志目录的问题。所以先看docker logs没内容就一定优先查宿主机目录。4.3 docker login报x509错误证书信任与daemon配置没有同步现象执行docker login时报Error response from daemon: Get https://192.168.209.133/v2/: x509: certificate signed by unknown authority原因Harbor用的是自签证书docker daemon默认不信任它。很多人拿到报错后去改harbor.yml以为服务端要修其实问题出在客户端。客户端必须在/etc/docker/daemon.json里把Harbor地址加入insecure-registries或者把Harbor的ca.crt放到/etc/docker/certs.d/目录下。解决两种方式任选其一。第一种跳过证书校验{ insecure-registries: [192.168.209.133:8080] }第二种正规的证书信任方式mkdir -p /etc/docker/certs.d/192.168.209.133:8080 cp /data/certs/harbor.crt /etc/docker/certs.d/192.168.209.133:8080/ca.crt systemctl restart docker注意目录名必须是“IP:端口”的形式和你在docker login里写的一致。如果端口变了目录名也要变。另外如果用的是域名hostname目录名就是“域名:端口”。我习惯用证书方式因为insecure-registries会让所有镜像对话都跳过加密安全审计过不了。改完daemon.json必须重启docker这个动作很多人漏掉然后反复纠结证书内容。4.4 prepare阶段报“Compose version not compatible”现象执行./install.sh或./prepare时输出ERROR: Docker Compose version is not compatible原因Harbor v2.4.0的脚本里对docker-compose版本有下限要求。如果你的compose是v1.9.x这类远古版本或者装的是v2.x但以docker compose子命令形式存在都会触发这个错误。更有意思的情况是机器上同时存在python版compose和二进制版composePATH里先找到的是python版。解决统一使用v1.29.2的aarch64二进制。先清理旧版本yum remove docker-compose -y rm -f /usr/local/bin/docker-compose /usr/bin/docker-compose which docker-compose然后把下载的aarch64二进制放到/usr/local/bin并验证curl -L https://github.com/docker/compose/releases/download/v1.29.2/docker-compose-linux-aarch64 -o /usr/local/bin/docker-compose chmod x /usr/local/bin/docker-compose docker-compose --version确认输出为docker-compose version 1.29.2。这里有个习惯安装任何软件前先执行which确认没有旧版残留能省掉后面排查的半小时。4.5 数据目录或证书相对路径导致nginx容器挂载失败现象harbor-nginx容器启动后马上退出。查看日志nginx configuration test failed原因harbor.yml里data_volume和certificate用的是相对路径没有用绝对路径。prepare在生成配置文件时把相对路径原样写进了docker-compose.ymlnginx容器挂载时找不到这些目录直接失败。我遇到过把data_volume: ./data写进配置的容器起来后所有镜像存储都写到了容器内部重启后数据全丢。解决harbor.yml里所有路径一律用绝对路径。最稳的方式mkdir -p /data/harbor mkdir -p /data/certs然后修改harbor.ymldata_volume: /data/harbor https: certificate: /data/certs/harbor.crt private_key: /data/certs/harbor.key修改后别直接docker-compose up -d先重新执行./prepare再启动。如果之前已经跑过install.sh修改路径后要清掉旧的容器层docker-compose down -v-v会删除volumes中的旧数据所以只有确认旧数据没用时才加。如果你是在部署阶段反复调试目录搞乱了可以直接删掉重来如果已经在线运行必须先把/data/harbor备份好。4.6 给避坑章的最后提醒避坑章列到第五条还想单独强调一点遇到Harbor出了问题很多人的第一反应是反复重跑install.sh。其实install.sh是幂等的重跑不会修复配置错误反而会掩盖日志里的真实报错。正确做法是先看docker ps里哪个容器在重启再去看对应容器的日志harbor-db对应数据库错误harbor-core对应API连接错误nginx对应证书和端口问题。把每条日志都读完整比盲目重装有价值得多。5. 验证与进阶从push/pull到对接K8s与版本升级5.1 打通第一条基线登录、建项目、推送、拉取仓库启动后先做一条完整的端到端验证。假设是HTTP模式docker login 192.168.209.133:8080 -u admin -p Harbor12345 docker tag busybox:latest 192.168.209.133:8080/library/busbox:latest docker push 192.168.209.133:8080/library/busbox:latest docker pull 192.168.209.133:8080/library/busbox:latestdocker tag时写的仓库名要包含项目路径library是Harbor默认公共项目。推送前最好先执行docker pull busybox确认本地有基础镜像。如果push过程很慢先检查网络再考虑是否要调整Harbor的nginx配置。验证通过后再在另一台机器上执行同样的pull确认跨主机访问没问题。这一步很关键很多部署只在服务器本机验证本机能拉不代表k8s节点能拉。5.2 对接K8simagePullSecret与containerd配置K8s节点从Harbor拉取私有镜像需要创建docker-registry类型的Secretkubectl create secret docker-registry harbor-secret \ --docker-server192.168.209.133:8080 \ --docker-usernameadmin \ --docker-passwordHarbor12345 \ --namespacedefault然后在deployment的spec里指定spec: imagePullSecrets: - name: harbor-secret如果k8s节点用的是containerd而非docker还需要配置/etc/containerd/config.toml。找到[plugins.io.containerd.grpc.v1.cri.registry]区段加上Harbor的地址和证书目录。这一步最容易漏漏掉的报错通常是“failed to pull image ... not found”或者“connection refused”。我在k8s集群里排查过一次deployment一直ImagePullBackOff结果发现只有三个节点里两个配了containerd默认没加registry。这个坑在国产化环境特别常见因为很多k8s集群底层用的是containerd。5.3 保留镜像数据的版本升级从v2.4.0到后续版本Harbor版本升级在ARM64环境里的坑比部署多一些。从v2.4.0升级先备份数据库和镜像数据cp -r /data/harbor /data/harbor_backup_$(date %F)然后下载对应新版本的aarch64离线包解压后用新的harbor.yml覆盖旧配置但不要无脑覆盖先对比差异diff harbor.yml /opt/harbor_install/harbor/harbor.yml新版本的参数如果和旧版不兼容prepare阶段会提示。Harbor的install.sh会自动执行数据库migration不需要手动升级数据库。我在这里的经验是升级前必须确认新旧版本之间允许跨版本升级官方release notes里一般会写升级路径。比如从v2.4.0到v2.6.0要分两步升不能直接跳到v2.10.0。一旦升级失败用备份目录回滚而不是手动改数据库结构。5.4 我踩过的坑与形成的手感那次改数据库密码的教训很深。当时只是把admin密码改了一下以为docker-compose down再up就够了结果harbor-core一直连不上库最后发现数据库卷里的postgres密码还是旧值。从那以后我每次操作数据库密码或admin密码都会强制走一遍“备份→down -v→清data_volume→重新install”的流程。另外每一次在麒麟V10上装Harbor我都要先打印uname -m、docker version和docker-compose version三行命令确认架构与版本无误后再动手。虽然慢一点但避免了后面几小时的排错。希望这些记录能帮你在同样的ARM64环境里少走弯路。本文还有配套的精品资源点击获取