flnxi-Wu/docs/guides/HARBOR_ENV_CONFIG.md

Harbor 镜像环境配置说明

📋 环境区分

测试镜像标签 - 开发团队专用

• Harbor 项目: flnxi（同一个项目）
• 镜像标签: pro-test
• 镜像路径: harbor.flnxi.com/flnxi/flnxi-material:pro-test
• 访问控制: 标签级别设置为私有，需要登录
• 用途: 内部测试、开发、验证新功能
• 特点:
  • 只有开发团队可以访问（通过标签权限控制）
  • 可能包含未完全稳定的功能
  • 用于内部测试和功能验证
  • 需要 Harbor 账号密码登录

正式镜像标签 - 客户使用

• Harbor 项目: flnxi（同一个项目）
• 镜像标签: pro-latest
• 镜像路径: harbor.flnxi.com/flnxi/flnxi-material:pro-latest
• 访问控制: 标签级别设置为公开，无需登录
• 用途: 生产环境、客户正式部署
• 特点:
  • 公开访问，客户可以直接拉取
  • 稳定版本，经过充分测试
  • 用于客户正式使用
  • 无需登录，直接拉取

🚀 安装时选择环境

运行 install.sh 时，脚本会询问：

选择部署环境:
  1) 测试环境 (test) - 使用测试镜像标签（需要登录）
  2) 正式环境 (prod) - 使用正式镜像标签（公开，无需登录）
请选择 [1/2，默认: 2]:

• 选择 1：使用测试镜像标签 (pro-test)
  • 需要输入 Harbor 用户名和密码
  • 只有开发团队可以使用
  • 镜像路径：harbor.flnxi.com/flnxi/flnxi-material:pro-test
• 选择 2 或直接回车：使用正式镜像标签 (pro-latest)
  • 无需登录，直接拉取
  • 客户使用此选项
  • 镜像路径：harbor.flnxi.com/flnxi/flnxi-material:pro-latest

📝 配置文件

环境选择会保存在 .env.production 文件中：

# 镜像环境配置
IMAGE_ENV=test          # 或 prod
IMAGE_TAG=test         # 或 latest
DOCKER_REGISTRY=harbor.flnxi.com/flnxi

🔄 切换环境

如果需要切换环境，可以：

1. 修改配置文件：

   # 编辑 .env.production
   IMAGE_TAG=latest  # 改为 latest 使用正式环境
   # 或
   IMAGE_TAG=test    # 改为 test 使用测试环境
   

2. 重新拉取镜像并启动：

   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml up -d
   

3. 或者重新运行安装脚本（会询问是否覆盖配置）

📦 Harbor 项目配置

项目结构（单一项目，通过标签区分）

Harbor 项目: flnxi（公开项目）

harbor.flnxi.com/flnxi/
├── runtime/              # 基础运行环境镜像（公开）
│   ├── postgres:15-alpine
│   ├── minio:RELEASE.2025-04-22T22-12-26Z
│   └── minio-mc:latest
└── flnxi-material/       # 应用镜像
    ├── pro-test          # 测试环境镜像（标签权限：私有）
    └── pro-latest        # 正式环境镜像（标签权限：公开）

访问控制说明

• 项目级别: flnxi 项目设置为公开（Public）
• 标签级别权限:
  • pro-test 标签：设置为私有，需要登录才能拉取
  • pro-latest 标签：设置为公开，无需登录即可拉取

镜像推送流程

1. 开发阶段：

   # 构建测试镜像
   docker build -t harbor.flnxi.com/flnxi/flnxi-material:pro-test .
   
   # 登录 Harbor（需要开发团队账号）
   docker login harbor.flnxi.com
   
   # 推送到测试标签（标签权限：私有）
   docker push harbor.flnxi.com/flnxi/flnxi-material:pro-test
   

2. 测试通过后：

   # 从测试标签拉取已验证的镜像
   docker pull harbor.flnxi.com/flnxi/flnxi-material:pro-test
   
   # 重新标记为正式版本
   docker tag harbor.flnxi.com/flnxi/flnxi-material:pro-test \
              harbor.flnxi.com/flnxi/flnxi-material:pro-latest
   
   # 推送到正式标签（标签权限：公开）
   docker push harbor.flnxi.com/flnxi/flnxi-material:pro-latest
   

⚠️ 注意事项

1. 测试镜像标签 (pro-test)：

   • 标签权限设置为私有：只有开发团队可以访问
   • 可能频繁更新
   • 用于验证新功能
   • 严禁客户使用

2. 正式镜像标签 (pro-latest)：

   • 标签权限设置为公开：客户可以直接拉取
   • 稳定版本，经过充分测试
   • 适合客户部署
   • 客户安装时默认使用此标签

3. 镜像推送流程：

   • 开发 → 推送到 pro-test 标签（标签权限：私有）
   • 测试验证通过 → 推送到 pro-latest 标签（标签权限：公开）
   • 确保测试环境验证通过后，再推送到正式标签
   • 建议使用版本标签（如 pro-v1.0.0）而不是 latest

4. 权限管理：

   • 在 Harbor 中设置 pro-test 标签的访问权限为私有
   • 在 Harbor 中设置 pro-latest 标签的访问权限为公开
   • 项目 flnxi 本身可以设置为公开，通过标签权限控制访问

🔧 手动指定镜像

如果需要使用特定版本的镜像，可以修改 .env.production：

# 使用特定版本
APP_IMAGE=harbor.flnxi.com/flnxi/flnxi-material:pro-v1.0.0

# 或使用测试版本
APP_IMAGE=harbor.flnxi.com/flnxi/flnxi-material:pro-test

然后重新启动：

docker compose -f docker-compose.prod.yml up -d