Docker 构建环境隔离方案 - 团队公告

[zhongfangxiong]

Docker 构建环境隔离方案 - 团队公告

重要更新

生效日期： 2026年1月6日
影响范围： 所有使用 Docker 构建的项目
更新内容： Docker 构建现已支持基于分支的环境自动隔离

---

核心功能

1. 自动环境识别

GitLab CI 现在会根据分支自动选择正确的环境配置：

分支类型	环境	下载配置
master / main / hotfix/*	production	生产环境依赖版本
develop / feature/* / bugfix/* / fix/*	development	开发环境依赖版本

2. 参数化配置

所有 Dockerfile 现在支持以下构建参数：

ARG ENVIRONMENT=production          # 环境：production 或 development
ARG VERSION_BASE_URL=https://...    # 版本服务器地址
ARG PRODUCT_NAME=StoreManage        # 产品名称
ARG CACHEBUST=1                     # 缓存破坏参数（自动生成时间戳）

3. 完全禁用缓存

• 使用 --no-cache 标志
• 每次构建传入唯一的 CACHEBUST 时间戳
• 确保每次都重新下载最新的依赖版本配置

---

技术实现

GitLab CI 构建模板

文件位置： deploy/common-ci/docker/build.yml

# 根据分支确定环境
if [[ "${CI_COMMIT_BRANCH}" == "master" || "${CI_COMMIT_BRANCH}" == "main" || "${CI_COMMIT_BRANCH}" =~ ^hotfix/ ]]; then
  BUILD_ENVIRONMENT="production"
else
  BUILD_ENVIRONMENT="development"
fi

# 设置默认值（如果项目未配置）
VERSION_BASE_URL="${VERSION_BASE_URL:-https://version.lodatone.com}"
PRODUCT_NAME="${PRODUCT_NAME:-${CI_PROJECT_NAME}}"

# 构建镜像
docker build \
  --build-arg ENVIRONMENT=${BUILD_ENVIRONMENT} \
  --build-arg VERSION_BASE_URL=${VERSION_BASE_URL} \
  --build-arg PRODUCT_NAME=${PRODUCT_NAME} \
  --build-arg CACHEBUST=$(date +%s) \
  --no-cache \
  -t "${DOCKER_IMAGE_REPO}:${VERSION_ID}" \
  -f "${DOCKERFILE_PATH}" .

Dockerfile 标准模板

FROM docker-sz.loda.net.cn/tools/loda/dotnet/sdk-8.0:xxx AS build

# 环境参数：production 或 development，默认为 production
ARG ENVIRONMENT=production
# 版本服务器地址
ARG VERSION_BASE_URL=https://version.loda.net.cn
# 产品名称
ARG PRODUCT_NAME=StoreManage
# 缓存破坏参数（由 CI 传入时间戳）
ARG CACHEBUST=1

# 下载最新的依赖版本配置文件
WORKDIR /
RUN /srv/scripts/download-directory-builds-props.sh ${VERSION_BASE_URL}/${PRODUCT_NAME}/${ENVIRONMENT}/ /src

# ... 后续构建步骤 ...

---

已更新的项目

以下项目已完成升级：

1. 进销存系统（StoreManage）

• Loda.Abp.StoreManage (API)
• Loda.Abp.StoreManage.Auth (认证服务)
• Loda.Abp.StoreManage.Blazor (前端)

2. 子木测评系统（Change）

• Yee.Change.BlazorOne.Blazor (前端)

3. 通用 CI 模板

• deploy/common-ci/docker/build.yml
• 已同步到所有 GitLab 实例（深圳、子木测评、老挝）

---

使用示例

场景1：开发分支构建

# 在 feature/ZD-12345-new-feature 分支上提交代码
git push origin feature/ZD-12345-new-feature

# GitLab CI 自动执行：
# - 识别为开发分支
# - 下载 https://version.loda.net.cn/StoreManage/development/urls.txt
# - 使用开发环境的依赖版本

场景2：生产分支构建

# 在 master 分支上合并代码
git push origin master

# GitLab CI 自动执行：
# - 识别为生产分支
# - 下载 https://version.loda.net.cn/StoreManage/production/urls.txt
# - 使用生产环境的依赖版本

---

️ 自定义配置

如果你的项目需要自定义配置，可以在 .gitlab-ci.yml 中设置变量：

variables:
  VERSION_BASE_URL: "https://custom-version-server.com"
  PRODUCT_NAME: "MyProduct"

---

构建日志示例

成功构建时，你会看到以下日志：

========================================
🐳 构建 Docker 镜像
========================================
版本: 2855.2026.0106.12345
镜像: docker-sz.loda.net.cn/docker-pos/api:2855.2026.0106.12345
Dockerfile: src/Loda.Abp.StoreManage.HttpApi.Host/Dockerfile
========================================
📦 构建环境: development
📦 版本服务器: https://version.loda.net.cn
📦 产品名称: StoreManage
========================================

=== 构建配置下载脚本 v2026.01.04-19:30 ===
步骤2: 下载 urls.txt 文件...
下载 URL: https://version.loda.net.cn/StoreManage/development/urls.txt
✅ 成功: 所有文件下载完成

---

错误处理

下载失败会导致构建失败

如果版本配置下载失败，构建会立即终止：

❌ 错误: 无法下载 urls.txt 文件
❌ 错误: 有 1 个文件下载失败
请检查以上错误信息并确认URL是否正确

常见原因：

1. 版本服务器不可访问
2. URL 配置错误
3. 网络问题

解决方法：

1. 检查版本服务器状态
2. 确认 VERSION_BASE_URL 和 PRODUCT_NAME 配置正确
3. 查看完整的构建日志

---

迁移指南

如果你的项目还未升级

1. 更新 Dockerfile

   添加环境参数：

   ARG ENVIRONMENT=production
   ARG VERSION_BASE_URL=https://version.loda.net.cn
   ARG PRODUCT_NAME=YourProductName
   ARG CACHEBUST=1
   

   修改下载命令：

   # 旧版本（硬编码）
   RUN /srv/scripts/download-directory-builds-props.sh https://version.loda.net.cn/YourProduct/production/ /src
   
   # 新版本（参数化）
   RUN /srv/scripts/download-directory-builds-props.sh ${VERSION_BASE_URL}/${PRODUCT_NAME}/${ENVIRONMENT}/ /src
   

2. 更新 GitLab CI 配置

   确保使用最新的 deploy/common-ci/docker/build.yml 模板：

   include:
     - project: 'deploy/common-ci'
       ref: master
       file: 'docker/build.yml'
   

3. 测试验证

   • 在开发分支测试构建
   • 在主分支测试构建
   • 确认下载的是正确环境的配置文件

---

最佳实践

1. 版本服务器目录结构

wwwroot/
├── StoreManage/
│   ├── production/
│   │   ├── Directory.Build.props
│   │   ├── urls.txt
│   │   └── version-numbers/
│   │       ├── Loda.Abp.*.props
│   │       └── ...
│   └── development/
│       ├── Directory.Build.props
│       ├── urls.txt
│       └── version-numbers/
│           ├── Loda.Abp.*.props
│           └── ...

2. urls.txt 文件格式

# 主配置文件
Directory.Build.props

# 版本号文件（相对路径）
version-numbers/Loda.Abp.Core.props
version-numbers/Loda.Abp.StoreManage.props

# 或使用完整URL
https://version.loda.net.cn/StoreManage/production/version-numbers/Custom.props

3. 环境隔离原则

• 开发环境： 使用最新的开发版本，快速迭代
• 生产环境： 使用稳定的发布版本，严格测试

---

相关文档

• 基于分支的完整工作流程示例
• 基于分支的版本号管理方案
• 环境命名规范

---

问题反馈

如有问题或建议，请联系：

• 技术支持： DevOps 团队
• 文档维护： 熊中方
• GitLab Issues： deploy/common-ci

---

更新日志

v2026.01.06

• 实现基于分支的环境自动识别
• 参数化 Dockerfile 配置
• 完全禁用 Docker 缓存
• 增强错误处理和日志输出
• 更新 4 个项目的 Dockerfile
• 同步到所有 GitLab 实例

---

感谢大家的配合！让我们的构建更智能、更可靠！