8.0 KiB
8.0 KiB
LJWX 镜像构建指南 (OrbStack + Harbor)
📋 概述
本文档说明如何使用优化后的 build-and-push.sh 脚本，将镜像构建并推送到本地 Harbor 仓库。
主要变更
- ✅ 运行时: 从 Docker Desktop 切换到 OrbStack
- ✅ 镜像仓库: 从阿里云切换到本地 Harbor (localhost:8080)
- ✅ 健康检查: 自动检查 Harbor 服务状态
- ✅ 多架构支持: 支持 linux/amd64 和 linux/arm64
🔧 前置要求
1. 安装 OrbStack
# 如果已安装 Docker Desktop，建议先卸载
# 然后安装 OrbStack (macOS)
brew install --cask orbstack
# 启动 OrbStack
open -a OrbStack
2. 部署 Harbor
确保 Harbor 服务运行在 localhost:8080：
# 检查 Harbor 是否运行
curl -f http://localhost:8080/api/v2.0/health
# 如果 Harbor 未运行，启动它
docker-compose -f harbor-compose.yml up -d
# 访问 Harbor Web UI
open http://localhost:8080
3. 验证环境
# 检查 Docker 是否使用 OrbStack
docker context ls
# 应该显示 orbstack 或 default
# 检查 Docker 版本
docker --version
# 检查 buildx 支持
docker buildx ls
🚀 使用方法
基本用法
# 查看帮助
./build-and-push.sh
# 构建所有镜像（应用 + 监控）
./build-and-push.sh all
# 仅构建应用镜像
./build-and-push.sh apps
# 仅构建监控镜像
./build-and-push.sh monitoring
# 构建单个镜像
./build-and-push.sh boot
./build-and-push.sh admin
./build-and-push.sh bigscreen
配置选项
使用环境变量
# 自定义 Harbor 地址
HARBOR_HOST=harbor.example.com:8080 ./build-and-push.sh apps
# 自定义 Harbor 凭证
HARBOR_USERNAME=myuser HARBOR_PASSWORD=mypass ./build-and-push.sh apps
# 仅构建，不推送
PUSH_TO_REGISTRY=false ./build-and-push.sh apps
修改配置文件
编辑 monitoring-versions.env：
# Harbor 配置
HARBOR_HOST=localhost:8080 # Harbor 地址
HARBOR_USERNAME=admin # Harbor 用户名
HARBOR_PASSWORD=admin123 # Harbor 密码
# 构建配置
REGISTRY=localhost:8080/ljwx # 镜像仓库地址
PLATFORMS=linux/amd64,linux/arm64 # 构建架构
LOCAL_BUILD=false # 多架构构建
PUSH_TO_REGISTRY=true # 推送到 Harbor
📦 构建流程
1. 完整构建流程
# Step 1: 检查 Harbor 状态
curl -f http://localhost:8080/api/v2.0/health
# Step 2: 准备数据（如果需要构建 MySQL 镜像）
./export-data.sh
# Step 3: 构建所有镜像
./build-and-push.sh all
# Step 4: 验证镜像已推送到 Harbor
# 访问 http://localhost:8080
# 登录: admin / admin123
# 查看 ljwx 项目下的镜像
2. 增量构建流程
# 仅构建并推送后端服务
./build-and-push.sh boot
# 仅构建并推送前端服务
./build-and-push.sh admin
# 仅构建并推送大屏服务
./build-and-push.sh bigscreen
3. 本地测试流程
# 构建但不推送到 Harbor
PUSH_TO_REGISTRY=false ./build-and-push.sh boot
# 本地运行测试
docker run -p 9998:9998 localhost:8080/ljwx/ljwx-boot:2.0.3
🔍 健康检查
脚本会自动执行以下健康检查：
1. Harbor 健康检查
# 脚本自动检查
GET http://localhost:8080/api/v2.0/health
# 如果 Harbor 不可用，脚本会提示：
⚠️ 无法连接到 Harbor (http://localhost:8080/api/v2.0/health)
💡 请确认 Harbor 服务已启动：
- 访问: http://localhost:8080
- 检查 Docker 容器: docker ps | grep harbor
是否继续构建（不推送到 Harbor）? (y/n)
2. 手动健康检查
# 检查 Harbor API
curl http://localhost:8080/api/v2.0/health
# 检查 Harbor Web UI
open http://localhost:8080
# 检查 Harbor 容器
docker ps | grep harbor
📊 镜像管理
查看本地镜像
# 查看所有 LJWX 镜像
docker images | grep localhost:8080/ljwx
# 查看特定镜像
docker images localhost:8080/ljwx/ljwx-boot
查看 Harbor 镜像
-
Web UI 方式:
- 访问 http://localhost:8080
- 登录: admin / admin123
- 进入
ljwx项目 - 查看镜像列表
-
API 方式:
# 列出所有仓库 curl -u admin:admin123 http://localhost:8080/api/v2.0/projects/ljwx/repositories # 列出镜像标签 curl -u admin:admin123 http://localhost:8080/api/v2.0/projects/ljwx/repositories/ljwx-boot/artifacts
拉取镜像
# 从 Harbor 拉取镜像
docker pull localhost:8080/ljwx/ljwx-boot:2.0.3
# 拉取最新版本
docker pull localhost:8080/ljwx/ljwx-boot:latest
🛠️ 故障排查
问题 1: Harbor 连接失败
症状:
⚠️ 无法连接到 Harbor (http://localhost:8080/api/v2.0/health)
解决方案:
# 1. 检查 Harbor 是否运行
docker ps | grep harbor
# 2. 启动 Harbor
docker-compose -f harbor-compose.yml up -d
# 3. 等待 Harbor 完全启动（约 30 秒）
sleep 30
# 4. 再次检查健康状态
curl http://localhost:8080/api/v2.0/health
问题 2: 登录失败
症状:
❌ Harbor 登录失败，请检查凭据
解决方案:
# 1. 检查凭证
echo "用户名: admin"
echo "密码: admin123"
# 2. 手动登录测试
docker login localhost:8080
# Username: admin
# Password: admin123
# 3. 检查 Harbor 配置
cat monitoring-versions.env | grep HARBOR
问题 3: 镜像推送失败
症状:
⚠️ ljwx-boot 镜像推送失败
解决方案:
# 1. 检查 insecure-registries 配置
# OrbStack 配置位置: ~/.orbstack/config/docker.json
cat ~/.orbstack/config/docker.json | grep insecure
# 2. 添加 insecure-registries
# 编辑 ~/.orbstack/config/docker.json
{
"insecure-registries": [
"localhost:8080",
"127.0.0.1:8080"
]
}
# 3. 重启 OrbStack
killall OrbStack
open -a OrbStack
# 4. 重新推送
./build-and-push.sh boot
问题 4: 多架构构建失败
症状:
ERROR: multiple platforms feature is currently not supported for docker driver
解决方案:
# 1. 创建 buildx builder
docker buildx create --name multiarch-builder --use
# 2. 启动 builder
docker buildx inspect --bootstrap
# 3. 重新构建
./build-and-push.sh boot
问题 5: OrbStack 不可用
症状:
Cannot connect to the Docker daemon
解决方案:
# 1. 检查 OrbStack 是否运行
ps aux | grep OrbStack
# 2. 启动 OrbStack
open -a OrbStack
# 3. 检查 Docker context
docker context ls
# 4. 切换到 OrbStack context（如果需要）
docker context use orbstack
📝 最佳实践
1. 构建前准备
# 检查 Harbor 状态
curl -f http://localhost:8080/api/v2.0/health || exit 1
# 检查磁盘空间
df -h
# 清理旧镜像（可选）
docker system prune -a
2. 分批构建
# 先构建基础设施镜像
./build-and-push.sh mysql redis
# 再构建应用镜像
./build-and-push.sh boot admin bigscreen
# 最后构建监控镜像
./build-and-push.sh monitoring
3. 版本管理
# 更新版本号
vim monitoring-versions.env
# 修改 LJWX_VERSION=2.0.4
# 构建新版本
./build-and-push.sh all
# 验证新版本
docker images localhost:8080/ljwx/ljwx-boot
4. 备份镜像
# 导出镜像到文件
docker save localhost:8080/ljwx/ljwx-boot:2.0.3 -o ljwx-boot-2.0.3.tar
# 从文件导入镜像
docker load -i ljwx-boot-2.0.3.tar
🎯 常用命令速查
# 健康检查
curl http://localhost:8080/api/v2.0/health
# 登录 Harbor
docker login localhost:8080
# 查看镜像
docker images | grep localhost:8080/ljwx
# 构建所有镜像
./build-and-push.sh all
# 构建单个镜像
./build-and-push.sh boot
# 拉取镜像
docker pull localhost:8080/ljwx/ljwx-boot:latest
# 清理缓存
./build-and-push.sh cache-clean
# 查看 Harbor 项目
open http://localhost:8080
📚 相关文档
最后更新: 2025-11-25 版本: 1.3.0