企业官网建设流程全解析

简介：面向需要在 ARM 架构服务器上私有化部署容器镜像仓库的运维与开发人员，这份资源提供 Harbor v2.4.0 的离线安装包，可解决内网环境无法拉取镜像、部署流程繁琐的问题。压缩包共 6 个文件，约 402.34MB，包含 sh 安装与辅助脚本、gz 镜像归档、yml 配置文件以及 license 等，覆盖从环境准备到服务启动的完整链路，其中 prepare 与 common.sh 负责前置检查与公共逻辑，install.sh 承担一键安装入口。使用前需自行准备 docker 与 docker-compose 环境，执行安装脚本即可完成部署，适合具备一定 Linux 基础、希望快速搭建企业级镜像仓库的读者。目前已有 1574 人学习下载，可作为 ARM 平台 Harbor 落地的参考方案，帮助减少离线环境下的配置与排错成本。

1. 从一台内网 ARM 服务器说起：harbor-v2.4.0 离线安装到底解决什么

很多做信创或边缘计算项目的同行都遇到过这种场景：客户现场给了一台 ARM 架构的服务器，系统是麒麟或者 openEuler，网络完全隔离，连个 yum 源都连不上，但项目要求必须有一套私有镜像仓库来管理容器镜像。这时候你打开 Harbor 官方文档，发现全是 x86 的在线安装脚本，./install.sh一跑就卡在拉取镜像那一步，因为docker pull根本出不去。harbor-v2.4.0 离线安装包就是为这种场景准备的——它把 Harbor 核心组件、依赖镜像、Docker Compose 编排文件全部打包成一个压缩包，你只需要在 ARM 服务器上解压、改配置、执行安装脚本，就能在纯内网环境里跑起一套功能完整的私有仓库。这套方案适合两类人：一是需要在 ARM 服务器上搭建内网镜像仓库的运维工程师，二是做国产化替代项目、必须用离线方式交付的交付工程师。它不解决镜像构建问题，也不解决跨架构镜像转换问题，它只解决一件事：让 Harbor 在 ARM 架构、无外网的环境里跑起来。

2. 动手之前先把 ARM 离线包的组成和依赖理清楚

2.1 离线包里到底有什么

harbor-v2.4.0 的 ARM 离线安装包通常是一个.tgz文件，解压后你会看到harbor/目录下包含这几类东西：harbor.v2.4.0.tar.gz是 Harbor 自身所有组件的镜像归档，docker-compose.yml是编排模板，prepare脚本负责根据harbor.yml生成最终配置，install.sh是入口脚本。另外还有common.sh、harbor.yml.tmpl这些辅助文件。和在线安装最大的区别在于，离线包里已经包含了registry、portal、core、jobservice、redis、postgresql、nginx、trivy等组件的 ARM 架构镜像，你不需要再联网拉取。但要注意，这些镜像的架构必须是arm64，如果你拿到的是 x86 的离线包，在 ARM 机器上docker load之后启动会直接报exec format error，这是第一个要确认的点。

2.2 系统层面的依赖检查

在解压安装包之前，先在目标服务器上确认三件事。第一，Docker 和 Docker Compose 是否已经安装，并且 Docker 版本不低于 17.06，Compose 版本不低于 1.18.0。ARM 架构下 Docker 的安装本身也可能需要离线包，常见做法是提前准备好docker-ce和docker-compose的 ARM 版本二进制文件。第二，检查内核参数，Harbor 的prepare脚本会读取vm.max_map_count，如果这个值小于 262144，Elasticsearch 组件（如果你启用了 Trivy 扫描）可能启动失败。第三，确认 80、443、5432、6379 这些端口没有被占用，尤其是 80 端口，Harbor 默认用 nginx 监听它。

# 检查 Docker 和 Compose 版本 docker --version docker-compose --version # 检查内核参数 sysctl vm.max_map_count # 如果小于 262144，临时调整 sysctl -w vm.max_map_count=262144 # 检查端口占用 ss -tlnp | grep -E ':(80|443|5432|6379)\s'

上面这几条命令是安装前的例行检查。docker --version输出里如果看到arm64或aarch64字样，说明 Docker 本身是 ARM 版本。sysctl vm.max_map_count返回的值如果偏小，用sysctl -w临时改大，但重启后会失效，持久化需要写进/etc/sysctl.conf。端口检查那一条如果发现 80 被 nginx 或 httpd 占了，要么停掉对应服务，要么在harbor.yml里把http.port改成其他值。

2.3 解压与目录规划

我一般会把离线包放在/opt下面，解压后得到/opt/harbor目录。不要放在/root或/home下，因为 Harbor 运行时会挂载一些卷，路径权限容易出问题。解压命令很简单，但要注意tar的参数，-xzf是解压 gzip 压缩的 tar 包，-C指定目标目录。

# 创建安装目录 mkdir -p /opt/harbor-install cd /opt/harbor-install # 解压离线包 tar -xzf harbor-offline-installer-v2.4.0-arm64.tgz # 进入解压后的目录 cd harbor # 查看目录结构 ls -la

解压完成后，你会看到harbor.v2.4.0.tar.gz这个镜像包，它可能有几个 GB，取决于是否包含了 Trivy 的漏洞库。harbor.yml.tmpl是配置模板，你需要把它复制成harbor.yml再修改。prepare和install.sh是两个关键脚本，前者负责校验配置和生成docker-compose.yml，后者负责加载镜像并启动容器。目录权限方面，确保当前用户对/opt/harbor-install/harbor有读写权限，否则prepare脚本生成配置文件时会失败。

3. 配置 harbor.yml 与执行安装：参数怎么改、脚本怎么跑

3.1 harbor.yml 里必须改的四个参数

复制模板之后，用编辑器打开harbor.yml，重点改四个地方。第一是hostname，改成目标服务器的 IP 地址或者域名，不要用localhost或127.0.0.1，否则客户端推送镜像时会报dial tcp连接错误。第二是http.port，默认是 80，如果被占用就改成 8080 或其他端口。第三是harbor_admin_password，这是管理员初始密码，不改的话默认是Harbor12345，生产环境必须改掉。第四是data_volume，默认是/data，如果服务器上/data分区空间不够，改成其他大容量路径。

# 复制配置文件模板 cp harbor.yml.tmpl harbor.yml # 编辑关键参数（示例片段） hostname: 192.168.1.100 http: port: 80 harbor_admin_password: YourStrongPassword123 data_volume: /data

上面这段 YAML 是harbor.yml里最核心的几行。hostname填 IP 时不要带端口，端口在http.port里单独指定。harbor_admin_password要满足复杂度要求，至少 8 位，包含大小写字母和数字。data_volume指向的目录如果不存在，prepare脚本会自动创建，但前提是父目录有写权限。另外，如果你不需要 HTTPS，就把https那段整个注释掉，否则prepare会要求你提供证书文件。

3.2 执行 prepare 和 install.sh 的完整流程

配置改好之后，先跑./prepare，它会做几件事：检查harbor.yml语法、根据配置生成docker-compose.yml、创建数据目录、检查端口冲突。如果这一步报错，通常是 YAML 缩进问题或者端口被占用。prepare成功后再跑./install.sh，它会先docker load加载离线镜像包，然后docker-compose up -d启动所有容器。

# 执行准备脚本 ./prepare # 如果 prepare 成功，执行安装 ./install.sh # 查看容器状态 docker-compose ps # 查看 Harbor 核心服务日志 docker-compose logs -f core

./prepare的输出里会显示它生成了哪些配置文件，如果看到Generated configuration file: ./common/config/...就说明成功了。./install.sh执行时间取决于镜像包大小和磁盘速度，ARM 服务器上可能跑几分钟。docker-compose ps里所有容器的状态应该是Up或Up (healthy)，如果有Exit或Restarting，就要看对应容器的日志。docker-compose logs -f core是排查启动问题最常用的命令，core是 Harbor 的核心 API 服务，它起不来后面都白搭。

3.3 验证安装是否成功

安装完成后，打开浏览器访问http://<hostname>，用admin和你设置的密码登录。如果能进到项目列表页面，说明 Web 层没问题。然后在本机用docker login测试一下，再推送一个测试镜像。

# 登录 Harbor docker login 192.168.1.100 -u admin -p YourStrongPassword123 # 拉一个 ARM 架构的测试镜像（如果本地没有） docker pull arm64v8/nginx:latest # 打标签 docker tag arm64v8/nginx:latest 192.168.1.100/library/nginx:test # 推送 docker push 192.168.1.100/library/nginx:test

docker login如果返回Login Succeeded就说明认证通了。推送镜像时要注意，Harbor 的项目名必须提前在 Web 界面创建，或者用library这个默认项目。docker push如果卡住或者报dial tcp错误，多半是hostname配置不对或者防火墙没放行端口。推送成功后，在 Harbor 的 Web 界面里能看到这个镜像，说明整套流程闭环了。

4. 避坑与排查：ARM 离线安装最容易翻车的五个地方

4.1 镜像架构不匹配导致容器起不来

现象：docker-compose up -d之后，docker-compose ps显示某些容器状态是Exit 255或者Restarting，看日志报exec format error。

原因：离线包里的镜像不是arm64架构，可能是 x86 的，或者混合了多种架构。ARM 服务器上的 Docker 无法运行 x86 镜像，除非你装了 QEMU 模拟，但 Harbor 这种 IO 密集型的服务用模拟跑性能极差。

解决：用docker inspect <image> | grep Architecture确认每个镜像的架构。如果发现是amd64，必须换一个正确的 ARM 离线包。不要试图用--platform参数强行指定，docker load加载的镜像架构是固定的，改不了。

4.2 hostname 配成 localhost 导致推送失败

现象：docker push报Get "https://127.0.0.1/v2/": dial tcp 127.0.0.1:443: connect: connection refused或者类似的连接错误。

原因：harbor.yml里的hostname写成了localhost或127.0.0.1，Harbor 的 nginx 配置和证书都是基于这个 hostname 生成的，客户端从其他机器访问时解析不到。

解决：把hostname改成服务器的真实 IP 或域名，然后重新跑./prepare和./install.sh。如果已经安装过，需要先docker-compose down停掉旧容器，再重新安装。注意，改 hostname 后原来的镜像数据还在，但配置会重新生成。

4.3 磁盘空间不足导致 postgresql 启动失败

现象：docker-compose ps显示postgresql容器不断重启，日志里报No space left on device或者could not write to file。

原因：data_volume指向的目录所在分区空间不够，PostgreSQL 启动时需要初始化数据库文件，至少需要几百 MB 的可用空间。ARM 服务器上如果/data分区很小，就容易出这个问题。

解决：用df -h检查data_volume所在分区的可用空间，如果不足 5GB，把data_volume改到一个大容量分区，然后重新./prepare和./install.sh。如果数据已经写入，需要先备份再迁移。

4.4 防火墙未放行端口导致客户端无法访问

现象：浏览器打不开 Harbor 页面，或者docker login超时，但服务器本机curl http://localhost是通的。

原因：服务器防火墙（firewalld 或 iptables）没有放行 Harbor 使用的端口，默认是 80 和 443，如果改了http.port就要放行对应端口。

解决：用firewall-cmd --list-ports查看已放行端口，如果没有 80，执行firewall-cmd --add-port=80/tcp --permanent然后firewall-cmd --reload。如果是 iptables，用iptables -I INPUT -p tcp --dport 80 -j ACCEPT临时放行，持久化需要保存规则。

4.5 docker-compose 版本过低导致语法不兼容

现象：./install.sh执行到docker-compose up -d时报Unsupported config option for services或者Version in "./docker-compose.yml" is unsupported。

原因：ARM 服务器上安装的docker-compose版本太老，不支持 Harbor v2.4.0 生成的docker-compose.yml里的某些语法，比如depends_on的条件格式。

解决：升级docker-compose到 1.18.0 以上版本。ARM 架构下可以从 GitHub Releases 下载对应的二进制文件，或者用 pip 安装。升级后重新跑./install.sh，不需要重新./prepare。

5. 进阶技巧：离线环境下的镜像同步与版本升级验证

5.1 用 skopeo 在离线环境里同步镜像

Harbor 跑起来之后，你可能会遇到一个新问题：怎么把外网的镜像弄到内网的 Harbor 里？常见做法是在一台能上网的机器上用skopeo把镜像复制成 tar 包，再拷贝到内网机器上推送到 Harbor。skopeo支持copy命令，可以直接从 registry 复制到本地目录，不需要 Docker daemon。

# 在外网机器上复制镜像到本地目录 skopeo copy docker://nginx:latest dir:/tmp/nginx-image # 打包拷贝到内网 tar -czf nginx-image.tar.gz -C /tmp nginx-image # 在内网机器上从目录复制到 Harbor skopeo copy dir:/tmp/nginx-image docker://192.168.1.100/library/nginx:latest

skopeo copy的第一个参数是源，docker://表示从 registry 拉取，dir:表示存到本地目录。第二个参数是目标，反过来就是推送到 Harbor。这种方式比docker save和docker load更灵活，因为它不需要本地 Docker daemon，而且可以跨架构复制。注意，skopeo本身也有 ARM 版本，在内网机器上安装时同样需要离线包。

5.2 验证 Harbor 版本升级的兼容性

如果你后续要升级 Harbor，比如从 v2.4.0 升到 v2.5.0，在离线环境里不能直接跑在线升级脚本。正确做法是下载新版本的 ARM 离线包，解压后把旧的harbor.yml复制过去，然后执行./prepare和./install.sh。但升级前必须做一件事：备份数据库和镜像数据。

# 备份 PostgreSQL 数据库 docker exec -it harbor-db pg_dump -U postgres registry > /backup/registry.sql # 备份镜像存储目录 tar -czf /backup/registry-storage.tar.gz /data/registry # 备份配置文件 cp harbor.yml /backup/harbor.yml.bak

上面三条命令分别备份了数据库、镜像文件和配置。pg_dump导出的是 registry 数据库，包含了项目、用户、权限等元数据。/data/registry是镜像层实际存储的位置，备份它才能保证镜像不丢。升级完成后，如果新版本启动失败，可以用这些备份回滚到旧版本。我一般会在升级前把旧版本的离线包也留着，万一新版本跑不起来，直接解压旧包恢复。

5.3 一个容易被忽略的细节：时间同步

ARM 服务器如果长时间运行在内网，系统时间可能会漂移。Harbor 的 token 认证机制依赖时间戳，如果服务器时间和客户端时间相差太大，docker login会报token expired或者unauthorized。这个坑很隐蔽，因为 Harbor 本身运行正常，Web 界面也能打开，就是推送和拉取镜像时认证失败。

# 检查系统时间 date # 如果时间偏差大，手动同步（需要外网 NTP 或内网 NTP 源） ntpdate ntp.aliyun.com # 或者用 chrony 配置内网时间源 chronyc sources -v

date命令输出的时间如果和实际时间差了几分钟甚至几小时，就要同步。内网环境如果没有 NTP 服务器，可以在 Harbor 服务器上手动设置一个接近的时间，然后让客户端也同步到这个时间。chrony是 CentOS 和 openEuler 上常用的时间同步工具，配置内网 NTP 源后可以自动校准。从那以后我每次部署 Harbor 之前都会先跑一遍date和chronyc sources，确认时间没问题再往下走，这个习惯帮我省了好几次排查认证问题的时间。希望帮到你。

本文还有配套的精品资源，点击获取