java-template/ORBSTACK_CONFIG.md

OrbStack 全局配置指南

📋 配置概述

已为 OrbStack 配置全局设置，无需每次构建时手动设置代理和 Harbor 配置。

✅ 已完成的配置

配置文件位置

~/.orbstack/config/docker.json

配置内容

{
  "ipv6": true,
  "insecure-registries": [
    "127.0.0.1:8080",
    "localhost:8080"
  ],
  "proxies": {
    "default": {
      "httpProxy": "http://127.0.0.1:7890",
      "httpsProxy": "http://127.0.0.1:7890",
      "noProxy": "localhost,127.0.0.1,*.local,host.docker.internal"
    }
  }
}

配置说明

1. insecure-registries: 允许连接到本地 Harbor (127.0.0.1:8080)
2. proxies: 全局代理配置，自动使用 7890 端口代理
3. ipv6: 保持启用 IPv6 支持

🔧 IPv4 vs IPv6 问题

问题原因

当使用 localhost:8080 时，OrbStack 会优先尝试 IPv6 地址 [::1]:8080，但 Harbor 可能没有监听 IPv6，导致连接被拒绝。

解决方案

使用 IPv4 地址 127.0.0.1:8080 而不是 localhost:8080

# ❌ 错误 - 可能解析为 IPv6
REGISTRY=localhost:8080/ljwx

# ✅ 正确 - 强制使用 IPv4
REGISTRY=127.0.0.1:8080/ljwx

🚀 应用配置

重启 OrbStack

配置修改后需要重启 OrbStack 使其生效：

# 方法 1: 使用命令行
killall OrbStack
sleep 2
open -a OrbStack

# 方法 2: 手动操作
# 1. 退出 OrbStack (菜单栏 > OrbStack > Quit)
# 2. 重新启动 OrbStack

验证配置

# 1. 检查 Docker 配置
docker info | grep -A 5 "Insecure Registries"

# 应该看到：
#  Insecure Registries:
#   127.0.0.1:8080
#   localhost:8080

# 2. 检查代理配置
docker info | grep -i proxy

# 应该看到代理信息

测试连接

# 1. 测试 Harbor 连接
curl -L http://127.0.0.1:8080/api/v2.0/health

# 应该返回：
# {"status":"healthy",...}

# 2. 测试 Docker 登录
docker login 127.0.0.1:8080
# Username: admin
# Password: admin123

# 3. 测试代理拉取
docker pull mysql:8.0
# 应该很快完成，通过代理拉取

📦 构建流程

配置完成后，构建流程自动使用全局配置：

# 1. 重启 OrbStack（如果刚配置）
killall OrbStack && sleep 2 && open -a OrbStack

# 2. 等待 OrbStack 启动（约 10 秒）
sleep 10

# 3. 开始构建
./build-and-push.sh mysql

# 脚本会：
# ✅ 自动使用代理拉取基础镜像
# ✅ 自动登录 Harbor (127.0.0.1:8080)
# ✅ 自动推送到 Harbor

🔍 配置详解

1. insecure-registries

允许连接到不使用 HTTPS 的私有仓库：

"insecure-registries": [
  "127.0.0.1:8080",      // IPv4 地址
  "localhost:8080"       // 主机名（可能解析为 IPv6）
]

2. proxies

全局代理配置，所有 Docker 操作自动使用代理：

"proxies": {
  "default": {
    "httpProxy": "http://127.0.0.1:7890",    // HTTP 代理
    "httpsProxy": "http://127.0.0.1:7890",   // HTTPS 代理
    "noProxy": "localhost,127.0.0.1,*.local,host.docker.internal"  // 不使用代理的地址
  }
}

noProxy 说明

• localhost - 本地主机名
• 127.0.0.1 - 本地 IPv4 地址
• *.local - 本地域名
• host.docker.internal - Docker 内部主机地址

这些地址不会使用代理，确保本地服务（如 Harbor）的连接不经过代理。

3. ipv6

保持启用 IPv6 支持：

"ipv6": true

虽然启用了 IPv6，但通过使用 127.0.0.1 而不是 localhost，可以强制使用 IPv4 连接。

🛠️ 故障排查

问题 1: 配置未生效

症状:

docker info | grep -i proxy
# 没有代理信息

解决方案:

# 1. 检查配置文件是否正确
cat ~/.orbstack/config/docker.json

# 2. 确保 JSON 格式正确（无语法错误）
python3 -m json.tool ~/.orbstack/config/docker.json

# 3. 重启 OrbStack
killall OrbStack
sleep 2
open -a OrbStack

问题 2: Harbor 连接仍然失败

症状:

dial tcp [::1]:8080: connect: connection refused

解决方案:

# 1. 确认使用 IPv4 地址
echo $HARBOR_HOST
# 应该是: 127.0.0.1:8080

# 2. 检查 Harbor 监听地址
cd ~/work/codes/tools/macos/harbor
docker-compose ps | grep nginx
# 应该看到: 0.0.0.0:8080->8080/tcp

# 3. 测试直接连接
telnet 127.0.0.1 8080
# 应该能连接

问题 3: 代理不工作

症状:

docker pull mysql:8.0
# 超时或很慢

解决方案:

# 1. 检查代理服务
lsof -i :7890
# 应该看到代理进程

# 2. 测试代理
curl --proxy http://127.0.0.1:7890 https://registry-1.docker.io/v2/

# 3. 检查 Docker 代理配置
docker info | grep -i proxy

# 4. 重启 OrbStack
killall OrbStack && sleep 2 && open -a OrbStack

问题 4: 推送到 Harbor 失败

症状:

unauthorized: authentication required

解决方案:

# 1. 登录 Harbor
docker login 127.0.0.1:8080
# Username: admin
# Password: admin123

# 2. 检查凭证
cat ~/.docker/config.json | grep 127.0.0.1:8080

# 3. 在 Harbor 中创建 ljwx 项目
# 访问 http://127.0.0.1:8080
# 登录后创建名为 "ljwx" 的项目（公开）

📝 Harbor 项目配置

创建项目

1. 访问 Harbor: http://127.0.0.1:8080
2. 登录: admin / admin123
3. 点击 "Projects" > "New Project"
4. 填写项目信息：
   • Project Name: ljwx
   • Access Level: Public
   • Storage Quota: -1 (无限制)
5. 点击 "OK" 创建

检查项目

# 使用 API 检查项目
curl -u admin:admin123 http://127.0.0.1:8080/api/v2.0/projects/ljwx

# 应该返回项目信息

💡 最佳实践

1. 配置检查清单

在构建前检查：

# ✅ OrbStack 运行中
ps aux | grep OrbStack

# ✅ 配置文件正确
cat ~/.orbstack/config/docker.json | python3 -m json.tool

# ✅ 代理服务运行
lsof -i :7890

# ✅ Harbor 服务运行
curl -L http://127.0.0.1:8080/api/v2.0/health

# ✅ Docker 登录
docker login 127.0.0.1:8080

# ✅ ljwx 项目存在
curl -u admin:admin123 http://127.0.0.1:8080/api/v2.0/projects/ljwx

2. 日常使用

# 直接构建，无需设置环境变量
./build-and-push.sh mysql

# 脚本会自动：
# - 使用全局代理配置
# - 登录 Harbor
# - 推送到 127.0.0.1:8080/ljwx

3. 临时禁用代理

如果需要临时禁用代理：

# 方法 1: 使用环境变量覆盖
HTTP_PROXY="" HTTPS_PROXY="" ./build-and-push.sh mysql

# 方法 2: 修改 noProxy
# 编辑 ~/.orbstack/config/docker.json
# 添加 Docker Hub 到 noProxy 列表

🔗 相关文档

• BUILD_WITH_HARBOR.md - Harbor 构建指南
• PROXY_CONFIG.md - 代理配置详解
• DOCKER_README.md - Docker Compose 使用指南

---

最后更新: 2025-11-26 版本: 1.0.0