企业官网建设流程全解析

简介：这是一份面向ARM架构服务器环境的Harbor容器镜像仓库离线部署包，对应Harbor 2.13.1版本，适合在无法访问外网或网络受限的国产化、信创及ARM服务器场景中搭建私有镜像仓库的运维与开发人员使用。压缩包共包含6个文件，以sh安装脚本、gz离线镜像包、license授权文件、prepare预检脚本及tmpl配置模板等类型为主，整体约513.28MB，覆盖了从环境预检、配置生成到服务安装的完整离线部署链路。目前已有414人学习下载，说明该版本在ARM生态中具备一定实用参考价值。借助这份离线包，读者可省去逐一下载依赖组件的繁琐过程，直接完成Harbor仓库的本地化安装与初始化配置，并依据模板文件快速调整端口、存储与认证等参数，为后续镜像推送、拉取及权限管理打下基础，适合需要在内网或离线环境中落地私有镜像仓库的技术人员参考使用。

1. arm环境harbor2.13.1离线包：为什么ARM架构的私有镜像仓库总在部署环节翻车

在ARM服务器上部署私有镜像仓库，很多人第一反应是找x86的安装包直接跑，结果容器起不来、二进制格式不兼容、镜像拉取报exec format error。harbor-offline-installer-v2.13.1-arm64.tgz这个包，解决的就是ARM64架构下Harbor 2.13.1版本的离线部署问题——不需要外网、不需要逐层拉取镜像、不需要手动编译ARM版本组件。它适合两类人：一是在信创或国产化ARM服务器上搭建内部镜像仓库的运维工程师，二是需要在隔离网络环境中快速交付容器基础设施的交付团队。这个包把Harbor核心组件、PostgreSQL、Redis、Nginx等所有依赖镜像和二进制文件全部打包，解压后一条命令完成安装。但ARM环境下的坑和x86完全不同，从内核参数到镜像架构匹配，每一步都可能让你卡住半天。

2. 拆开离线包：ARM64版本里到底装了什么

2.1 离线包目录结构与组件清单

拿到harbor-offline-installer-v2.13.1-arm64.tgz后，先别急着解压安装。用tar命令看一下包内结构，心里有数再动手。

# 查看离线包内容，不实际解压 tar -tzf harbor-offline-installer-v2.13.1-arm64.tgz | head -50 # 解压到当前目录 tar -xzf harbor-offline-installer-v2.13.1-arm64.tgz cd harbor ls -la

解压后你会看到几个关键文件：harbor.v2.13.1.tar.gz是所有容器镜像的离线包，harbor_prepare是环境预检脚本，prepare是配置生成脚本，install.sh是主安装脚本，harbor.yml.tmpl是配置模板。ARM64版本的镜像包和x86版本在镜像tag上完全一致，但底层manifest的architecture字段是arm64。这意味着你不能把x86的镜像包混进来用，哪怕tag看起来一样。

# 确认镜像包内的架构信息 docker load -i harbor.v2.13.1.tar.gz docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" | grep goharbor

加载完成后，用docker inspect检查任意一个镜像的Architecture字段，确认是arm64而不是amd64。这一步很多人跳过，结果安装完发现容器反复重启，日志里全是exec format error。

2.2 各组件在ARM环境下的角色与依赖关系

Harbor 2.13.1在ARM64下运行的组件和x86一致，但资源占用和调度行为有差异。核心组件包括：harbor-core（API服务）、harbor-portal（前端）、harbor-jobservice（任务调度）、harbor-registry（镜像存储）、harbor-db（PostgreSQL）、harbor-redis（缓存）、harbor-proxy（Nginx反向代理）、harbor-trivy（漏洞扫描，可选）。ARM64下PostgreSQL和Redis的官方镜像本身支持arm64，但Trivy的ARM版本在2.13.1中需要确认是否包含在离线包内。

# 查看离线包中是否包含trivy镜像 docker images | grep trivy # 查看所有goharbor镜像的架构 docker images --format "{{.Repository}}:{{.Tag}}" | grep goharbor | while read img; do arch=$(docker inspect --format '{{.Architecture}}' "$img") echo "$img -> $arch" done

如果Trivy镜像缺失或架构不对，可以在harbor.yml中先关闭trivy，后续再补。ARM环境下Trivy的漏洞库更新可能因为网络问题失败，离线场景下建议先禁用，等仓库跑通后再单独处理。

2.3 离线包与在线安装的本质区别

在线安装harbor时，install.sh会从Docker Hub拉取镜像，ARM64环境下如果Docker Hub的manifest list里没有arm64条目，拉取会直接失败。离线包的价值在于把所有镜像预先打包，安装时用docker load导入，完全不依赖外网。但离线包也有代价：包体积大（通常2GB以上），传输和存储需要规划；镜像版本固定，升级需要重新获取新版本的离线包。

# 对比在线安装和离线安装的脚本差异 diff <(grep -E "docker (pull|load)" install.sh) <(echo "离线安装使用docker load")

离线安装的install.sh中，镜像加载步骤是docker load -i harbor.v2.13.1.tar.gz，而在线安装是docker pull。这个差异决定了离线包在隔离网络中的不可替代性，但也意味着你无法在安装过程中动态调整镜像版本。

3. 在ARM服务器上跑通Harbor：从系统预检到服务启动

3.1 系统预检：内核参数、文件句柄与SELinux

ARM服务器上跑Harbor，系统层面的预检比x86更严格。很多ARM发行版默认的内核参数和文件句柄数不够，导致PostgreSQL或Redis启动失败。

# 检查内核版本和架构 uname -a # 确认是aarch64或arm64 # 检查文件句柄限制 ulimit -n # 如果小于65535，需要调整 # 临时调整 ulimit -n 65535 # 永久调整，编辑/etc/security/limits.conf echo "* soft nofile 65535" >> /etc/security/limits.conf echo "* hard nofile 65535" >> /etc/security/limits.conf # 检查SELinux状态 getenforce # 如果是Enforcing，建议临时设为Permissive setenforce 0

内核参数方面，net.ipv4.ip_forward必须为1，否则容器网络不通。vm.max_map_count建议调到262144以上，否则Elasticsearch相关组件（如果启用）会报错。ARM架构下这些参数的默认值可能和x86不同，不要假设x86的经验直接套用。

# 检查并设置内核参数 sysctl net.ipv4.ip_forward sysctl vm.max_map_count # 永久生效 cat >> /etc/sysctl.conf <<EOF net.ipv4.ip_forward = 1 vm.max_map_count = 262144 EOF sysctl -p

3.2 配置harbor.yml：ARM环境下必须改的五个参数

harbor.yml.tmpl是配置模板，复制为harbor.yml后逐项修改。ARM环境下有五个参数必须关注，否则安装后服务异常。

# harbor.yml 关键配置段 hostname: harbor.internal.example.com # 改为你的实际域名或IP http: port: 80 # https配置，离线环境建议先用http跑通 # https: # port: 443 # certificate: /your/certificate/path # private_key: /your/private/key/path harbor_admin_password: Harbor12345 # 首次登录后立即修改 database: password: root123 # 建议改为强密码 max_idle_conns: 100 max_open_conns: 900 data_volume: /data/harbor # 确保该目录所在分区有足够空间 trivy: ignore_unfixed: false skip_update: true # 离线环境必须设为true，否则启动时尝试更新漏洞库会失败 offline_scan: true jobservice: max_job_workers: 10 notification: webhook_job_max_retry: 3 log: level: info local: rotate_count: 50 rotate_size: 200M location: /var/log/harbor

hostname不要用localhost或127.0.0.1，否则docker login会失败。data_volume要确保有至少50GB可用空间，ARM环境下镜像层解压可能比x86更占空间。trivy.skip_update在离线环境必须为true，否则Trivy容器启动时会尝试联网更新漏洞库，超时后反复重启。

# 复制模板并修改 cp harbor.yml.tmpl harbor.yml vi harbor.yml # 检查配置语法 ./prepare --help

3.3 执行安装：prepare与install.sh的完整流程

配置改好后，先跑./prepare生成最终配置，再跑./install.sh。ARM环境下这两个步骤都可能因为权限或路径问题失败。

# 生成配置 ./prepare # 如果报错，检查data_volume目录权限 mkdir -p /data/harbor chmod 755 /data/harbor # 执行安装 ./install.sh # 安装完成后检查容器状态 docker-compose -f docker-compose.yml ps

prepare脚本会根据harbor.yml生成docker-compose.yml和各个组件的配置文件。如果data_volume目录不存在或权限不对，prepare会报错退出。install.sh会先加载镜像，然后启动所有容器。ARM环境下启动时间可能比x86长，耐心等待2-3分钟。

# 查看安装日志 tail -f /var/log/harbor/install.log # 检查所有容器是否healthy docker ps --format "table {{.Names}}\t{{.Status}}" # 如果有容器反复重启，查看日志 docker logs harbor-core --tail 50 docker logs harbor-db --tail 50

3.4 验证部署：从docker login到推送第一个ARM镜像

安装完成后，用docker login验证仓库可用性，然后推送一个ARM64镜像测试完整流程。

# 登录仓库 docker login harbor.internal.example.com -u admin -p Harbor12345 # 拉取一个ARM64测试镜像 docker pull arm64v8/alpine:latest # 打tag docker tag arm64v8/alpine:latest harbor.internal.example.com/library/alpine:arm64 # 推送 docker push harbor.internal.example.com/library/alpine:arm64 # 在另一台ARM机器上拉取验证 docker pull harbor.internal.example.com/library/alpine:arm64

如果推送时报manifest invalid或architecture mismatch，说明镜像架构和仓库期望的不一致。Harbor 2.13.1默认不强制架构校验，但某些配置下会检查。确保推送的镜像确实是arm64架构。

# 确认镜像架构 docker inspect arm64v8/alpine:latest --format '{{.Architecture}}' # 应输出arm64

4. ARM环境部署Harbor的避坑记录：五个让你卡半天的真实问题

4.1 容器启动报exec format error

现象：docker-compose up后，harbor-core、harbor-db等容器状态一直是Restarting，日志显示exec format error。

原因：加载的镜像架构是amd64，不是arm64。可能是离线包下载错了，或者之前加载过x86镜像导致tag冲突。

解决：删除所有goharbor镜像，重新从正确的离线包加载。

# 删除所有goharbor镜像 docker images --format "{{.Repository}}:{{.Tag}}" | grep goharbor | xargs docker rmi -f # 重新加载ARM64离线包 docker load -i harbor.v2.13.1.tar.gz # 确认架构 docker inspect goharbor/harbor-core:v2.13.1 --format '{{.Architecture}}'

4.2 PostgreSQL容器启动后立即退出

现象：harbor-db容器启动几秒后退出，日志显示could not resize shared memory segment或out of memory。

原因：ARM服务器上/dev/shm默认大小可能只有64MB，PostgreSQL需要更大的共享内存。

解决：在docker-compose.yml中为harbor-db添加shm_size参数，或直接调整宿主机/dev/shm大小。

# 在docker-compose.yml的harbor-db服务下添加 services: harbor-db: shm_size: 1g

# 或者重新挂载/dev/shm mount -o remount,size=2G /dev/shm

4.3 Trivy容器反复重启导致安装卡住

现象：install.sh执行到Trivy相关步骤时卡住，或Trivy容器不断重启，日志显示failed to download vulnerability DB。

原因：离线环境下Trivy尝试联网更新漏洞库，超时后重试，形成死循环。

解决：在harbor.yml中设置trivy.skip_update: true和trivy.offline_scan: true，然后重新执行./prepare和./install.sh。

trivy: skip_update: true offline_scan: true

如果已经安装但Trivy仍在重启，直接停掉Trivy容器，Harbor核心功能不受影响。

docker stop harbor-trivy docker update --restart=no harbor-trivy

4.4 docker login成功但push时报413 Request Entity Too Large

现象：docker login正常，但推送较大镜像时返回413错误。

原因：Nginx反向代理的client_max_body_size默认值太小，ARM环境下镜像层可能更大。

解决：修改harbor.yml中的proxy相关配置，或直接调整Nginx配置。

# harbor.yml中 proxy: http_proxy: https_proxy: no_proxy: components: - core - jobservice - trivy

更直接的方式是修改common/config/nginx/nginx.conf，将client_max_body_size设为0（不限制）或足够大的值。

client_max_body_size 0;

修改后重启harbor-proxy容器。

docker restart harbor-proxy

4.5 数据卷权限问题导致core服务无法写入

现象：harbor-core容器启动后日志报permission denied，无法写入/var/log/harbor或/data/harbor。

原因：ARM环境下宿主机目录权限和容器内用户UID不匹配。Harbor容器内通常以UID 10000运行，而宿主机目录可能是root所有。

解决：调整宿主机目录权限。

# 查看容器内用户UID docker run --rm goharbor/harbor-core:v2.13.1 id # 调整目录权限 chown -R 10000:10000 /data/harbor chown -R 10000:10000 /var/log/harbor

如果不想改UID，也可以在docker-compose.yml中指定user: root，但不推荐在生产环境这样做。

5. 让ARM Harbor跑得更稳：离线环境下的备份、升级与性能调优

5.1 离线备份：用docker commit和volume快照保住配置

Harbor的配置数据分布在PostgreSQL、Redis和文件系统中。离线环境下没有云备份，必须手动做。最可靠的方式是定期导出数据库和备份数据卷。

# 备份PostgreSQL数据库 docker exec harbor-db pg_dump -U postgres registry > /backup/harbor_db_$(date +%Y%m%d).sql # 备份数据卷 tar -czf /backup/harbor_data_$(date +%Y%m%d).tar.gz /data/harbor # 备份配置文件 cp harbor.yml /backup/harbor.yml_$(date +%Y%m%d)

恢复时先停掉所有容器，恢复数据卷和数据库，再启动。

docker-compose down tar -xzf /backup/harbor_data_20250101.tar.gz -C / docker-compose up -d docker exec -i harbor-db psql -U postgres registry < /backup/harbor_db_20250101.sql

5.2 ARM64镜像的跨架构推送与manifest管理

ARM环境下经常需要同时管理arm64和amd64镜像。Harbor 2.13.1支持manifest list，但需要手动创建。

# 创建多架构manifest docker manifest create harbor.internal.example.com/library/myapp:latest \ harbor.internal.example.com/library/myapp:amd64 \ harbor.internal.example.com/library/myapp:arm64 # 推送manifest docker manifest push harbor.internal.example.com/library/myapp:latest

注意：ARM64的Harbor实例本身不能构建amd64镜像，manifest list中的amd64镜像必须从其他来源推送。离线环境下这个操作需要提前规划。

5.3 资源限制与性能调优参数

ARM服务器的CPU和内存资源有限，Harbor默认配置可能过于激进。在docker-compose.yml中为每个服务设置合理的资源限制。

services: harbor-core: deploy: resources: limits: cpus: '2' memory: 2G reservations: cpus: '1' memory: 1G harbor-db: deploy: resources: limits: cpus: '2' memory: 4G

同时调整PostgreSQL的连接数和共享缓冲区。

# 进入harbor-db容器 docker exec -it harbor-db psql -U postgres # 查看当前连接数 SELECT count(*) FROM pg_stat_activity; # 调整max_connections（需重启） ALTER SYSTEM SET max_connections = 200;

5.4 从2.13.1升级到更高版本的离线路径

Harbor的离线升级不能跨大版本，2.13.1只能先升到2.13.x的最新patch，再升2.14。ARM64的升级包需要单独获取。

# 升级前备份 docker-compose down tar -czf /backup/harbor_pre_upgrade.tar.gz /data/harbor # 下载新版本离线包并解压 tar -xzf harbor-offline-installer-v2.13.2-arm64.tgz cd harbor # 复制旧配置 cp ../harbor/harbor.yml . # 执行升级 ./install.sh

升级后检查数据库迁移日志，确保所有migration执行成功。

docker logs harbor-core | grep -i migration

我自己的习惯是每次升级前先在测试环境跑一遍完整流程，确认ARM64镜像加载、数据库迁移、Trivy离线扫描都没问题，再动生产环境。ARM环境下最怕的就是升级到一半发现某个组件的arm64镜像缺失，回滚又因为数据库已迁移而失败。所以离线包到手第一件事就是解压检查所有镜像的架构，确认无误再规划升级窗口。希望帮到你。

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