GitLab CI + Docker 流水线

按「build → deploy」两阶段、分支触发规则与 Docker 多阶段构建，生成或维护 .gitlab-ci.yml 、分支使用说明及部署脚本。部署方式固定为 dev → prod，且必须使用 Kubernetes（K8s）部署；在 .gitlab-ci.yml 中通过 dev_deploy / prod_deploy 调用 K8s 部署脚本，使用模板（如 dev_deployment.yaml.tpl ）经 envsubst 替换后 kubectl apply 。详细约定见 references/REFERENCE.md。

何时使用

• 用户要求「配置 GitLab CI」「写 .gitlab-ci.yml」「Docker 多阶段构建 + CI」「分支与部署流程」

• 用户需要流水线说明、分支约定或部署后 Docker 运行说明；或需区分「本地 Docker 构建测试」与「Git 提交触发流水线」两种方式、以及远程仓库前置检查

使用流程

0. 前置：远程仓库与构建方式

推荐顺序：先使用本地 Docker 构建测试，再通过 Git 提交触发流水线。

• 先：本地 Docker 构建与测试（必须优先执行）：在项目根目录执行多阶段构建（见 assets/docker-build-commands.md），本地验证镜像能否正常构建与运行，并可本地 docker run 做接口或功能验证；无需推送代码。在确认本地构建与运行无误后，再执行步骤 2，避免有问题的提交触发流水线、占用 Runner 与部署环境。

• 再：通过 Git 提交触发流水线：将代码推送到配置了 GitLab CI 的远程仓库对应分支（如 develop 、bugfix/* 、master ）后，GitLab 根据 .gitlab-ci.yml 自动创建并执行流水线，完成构建镜像、推送到私有仓库、执行部署脚本；无需在 GitLab 界面手动点击运行。

生成或说明文档时需强调上述顺序，并在「快速开始」或「开发流程」中把「本地 Docker 构建测试」放在「Git 推送触发流水线」之前。

项目仓库地址：默认为 git.tac.hillstonenet.com。克隆地址格式：https://git.tac.hillstonenet.com/&#x3C;组名>/&#x3C;项目名>.git 或 git@git.tac.hillstonenet.com:<组名>/<项目名>.git 。生成文档与示例时使用该地址。

使用「Git 提交触发流水线」前，必须先确认后端服务/项目是否已配置远程仓库：

• 执行 git remote -v 检查是否已配置 remote（如 origin ），且地址指向 git.tac.hillstonenet.com 上的项目。

• 若未配置远程仓库或 remote 不是上述地址：应提示用户先创建或关联远程仓库，例如：

• git remote add origin https://git.tac.hillstonenet.com/&#x3C;组名>/&#x3C;项目名>.git 或 SSH 形式 git@git.tac.hillstonenet.com:<组名>/<项目名>.git ；

• 若已有 origin 但地址错误：git remote set-url origin <正确地址> ；

• 说明「只有将代码推送到 git.tac.hillstonenet.com 远程仓库的 develop / bugfix / hotfix / master 分支后，流水线才会自动触发」。

• 生成项目内说明文档（如 docs/GITLAB-CICD.md ）时，在「前置配置」或「触发方式」处写明：需先确保项目已关联 git.tac.hillstonenet.com 远程仓库，再通过 git push 触发流水线；并引用或嵌入详细且可自动执行的 Git 操作说明（见 assets/git-operations.md）。

1. 确认范围

向用户确认：

• 阶段与 Job：是否采用 build + deploy；是否需要「依赖镜像」与「应用镜像」分离（多阶段 Docker）

• 分支策略：develop / bugfix / hotfix / master 的用途与触发规则

• 部署目标：必须为 dev → prod 两环境，且必须使用 K8s 部署。开发环境由 dev_deploy 执行（develop/bugfix/hotfix 触发），生产环境由 prod_deploy 执行（仅 master 触发）；脚本名为 dev_deploy.sh 、prod_deploy.sh ，在 .gitlab-ci.yml 的 deploy 阶段调用；命名空间（如 api-server ）、ConfigMap（${CI_PROJECT_NAME}-env ）、imagePullSecrets（docker-registry ）、部署模板（如 dev_deployment.yaml.tpl ）见 assets/k8s/dev_deployment.yaml.tpl 与 assets/scripts/dev_deploy.sh.example。

• 私有镜像仓库：推送地址默认为 registry.dic.hillstonenet.com，命名空间为 private（完整镜像如 registry.dic.hillstonenet.com/private/<项目名>:latest ）；若用户无特别说明，生成 .gitlab-ci.yml 与文档时使用该地址；需明确 CI 内登录方式（变量/凭证）、部署机拉取前是否需 docker login

• 依赖管理：是否使用 uv + pyproject.toml + uv.lock；依赖变更时是否单独构建「依赖镜像」以加速后续构建

2. 流水线设计要点

• build 阶段

• build_env（可选）：仅在依赖文件（如 Dockerfile 、pyproject.toml 、uv.lock ）变更时执行；使用 Dockerfile 的 --target requirement 构建依赖阶段镜像并打标签，供后续复用。

• build_project：构建最终应用镜像（--target project ）；依赖未变更时复用 build_env 的缓存，避免重复执行依赖安装。

• deploy 阶段

• push_image：给镜像打标签并推送到私有镜像仓库（registry.dic.hillstonenet.com/private/<项目名>）；CI 中需先登录该仓库（docker login registry.dic.hillstonenet.com

• 变量中的账号密码），再执行 docker push 。

• dev_deploy：在 develop / bugfix / hotfix 上执行 K8s 部署；调用 scripts/dev_deploy.sh ，切换 kubectl context 到 dev 集群，按需创建/更新 ConfigMap（${CI_PROJECT_NAME}-env ），用 envsubst 处理 dev_deployment.yaml.tpl （变量 ${CI_PROJECT_NAME} ）生成 manifest 后 kubectl apply 并 kubectl rollout restart 。模板需含 Deployment、Service、Ingress（dev 域名如 ${CI_PROJECT_NAME}.apistest.dic.hillstonenet.com ，ingressClassName: api-server）。

• prod_deploy：仅在 master 上执行 K8s 生产环境部署；调用 scripts/prod_deploy.sh ，切换 context 到 prod 集群，同样通过模板 + envsubst + kubectl apply 部署；不在此分支跑 build，使用已有镜像。

分支与 Job 的对应关系见 references/REFERENCE.md 及 assets/pipeline-overview.md。

3. Docker 多阶段构建

若采用「依赖与代码分离」：

• Python 基础镜像：Python 项目的 Dockerfile 默认使用私有镜像源中的基础镜像 docker.dic.hillstonenet.com/library/python:3.12-slim（即 FROM docker.dic.hillstonenet.com/library/python:3.12-slim ），以保证构建与运行环境一致且不依赖公网。

• requirement 阶段：在上述基础镜像上安装 uv，复制 pyproject.toml 、uv.lock 并 uv sync ；产出仅含依赖的中间镜像。CI 中 build_env 使用 --target requirement 构建并推送该镜像。

• project 阶段：在 requirement 基础上复制应用代码、设置启动命令；产出可运行的应用镜像。build_project 使用 --target project 构建。

本地等价命令示例见 assets/docker-build-commands.md。

4. 分支约定与 Git 操作

• develop：主开发分支；推送触发 build（依赖变更时先 build_env）→ build_project → push_image → dev_deploy。

• bugfix/*：从 develop 拉取；触发 build_project → push_image → dev_deploy；合并回 develop。

• hotfix/*：从 master 拉取；不触发 build，仅 push_image → dev_deploy；需保证镜像已由 develop 等构建过；合并回 master 与 develop。

• master：生产就绪；仅推送触发 prod_deploy，不跑 build。

生成文档时应包含：(1) 先：本地 Docker 构建测试的命令与说明（明确写「先本地构建并验证通过，再推送」）；(2) 再：通过 Git 提交触发流水线的说明（推送后自动触发、无需手动运行）；(3) 详细且可自动执行的 Git 操作说明：各分支场景以可直接复制执行的命令块或可执行脚本形式给出（仓库地址使用 git.tac.hillstonenet.com），包括：检查/配置远程、克隆、日常 develop 提交、bugfix 创建/推送/合并回 develop、hotfix 创建/推送/合并回 master 与 develop、develop 合并到 master 发布生产；每步对应流水线结果；(4) 若未配置远程仓库，提示先执行 git remote add origin https://git.tac.hillstonenet.com/&#x3C;组名>/&#x3C;项目名>.git （或 SSH 形式）或 git remote set-url origin ... 。可参考 assets/git-operations.md。

5. 私有镜像仓库与部署后 Docker 使用

• 私有镜像仓库：推送地址为 registry.dic.hillstonenet.com，命名空间 private。生成或校验时需包含：

• CI 内：在需要 push 的 Job（build_env、push_image 等）中，于 docker push 前执行 docker login registry.dic.hillstonenet.com ，账号密码从 GitLab CI/CD Variables 读取（如 REGISTRY_USER 、REGISTRY_PASSWORD ，设为 Masked），且不在日志中明文输出密码。

• 镜像命名：统一使用完整地址 registry.dic.hillstonenet.com/private/<项目名>:<标签> （如 registry.dic.hillstonenet.com/private/myapp:latest ），并在文档与示例中写明。

• 部署/运维侧：在需拉取镜像的机器上，先执行 docker login registry.dic.hillstonenet.com -u <用户> -p <密码> ，再 docker pull registry.dic.hillstonenet.com/private/<项目名>:latest ；文档中应说明「使用私有仓库时需先登录」及建议的凭证管理方式。

流水线完成后，镜像已推送到私有仓库。需在文档中说明：

• 拉取镜像：使用私有仓库时，先 docker login registry.dic.hillstonenet.com ，再 docker pull registry.dic.hillstonenet.com/private/<项目名>:latest 。

• docker run 示例：端口映射、环境变量（ENV、SECRET_KEY、数据库、Redis 等）、开发/生产模式（如 ENV=dev 用 Flask，ENV=prod 用 Gunicorn）。

• 可选：--env-file 、--restart unless-stopped 、常用运维命令（logs、stop、更新镜像后重建容器）。

6. 交付物清单

按需生成或更新：

• .gitlab-ci.yml：阶段、Job、only/except 或 rules（changes/refs）、依赖关系；默认 Runner tags 为 grunner （default.tags: [grunner] ），保证所有 Job 在指定 Runner 上执行。

• Dockerfile：多阶段 target（requirement、project）、与 CI Job 的对应；Python 项目基础镜像默认 docker.dic.hillstonenet.com/library/python:3.12-slim。

• 分支与流水线说明文档：强调先本地 Docker 构建测试、再 Git 推送触发流水线；说明 (1) 先本地 Docker 构建测试方式（含命令与验证通过后再推送的提示），(2) 再通过 Git 提交触发流水线（推送后自动触发）、(3) 使用流水线前需配置 git.tac.hillstonenet.com 远程仓库（若无则提示创建/关联）；阶段/Job 表、分支约定表；Git 操作说明需详细且可自动执行（各场景为可复制执行的命令块或可执行脚本，仓库地址 git.tac.hillstonenet.com），见 assets/git-operations.md。可参考项目内 docs/GITLAB-CICD.md 类文档结构。

• 部署脚本与 K8s 模板：必须提供 dev → prod 的 K8s 部署方式。scripts/dev_deploy.sh 、scripts/prod_deploy.sh 参考 assets/scripts/dev_deploy.sh.example、assets/scripts/prod_deploy.sh.example（kubectl context 切换、ConfigMap 检查/创建、envsubst + 模板生成 manifest、kubectl apply、rollout restart）；项目内需提供 k8s/dev_deployment.yaml.tpl （及可选 k8s/prod_deployment.yaml.tpl ），内容参考 assets/k8s/dev_deployment.yaml.tpl（Deployment + Service + Ingress，变量 ${CI_PROJECT_NAME} ，镜像 docker.dic.hillstonenet.com/private/${CI_PROJECT_NAME}:latest ，命名空间 api-server ）。模板路径在 Runner 上可为固定路径（如 /.flaskserver/dev_deployment.yaml.tpl ）或使用项目内 k8s/ 。

• 流水线完成后使用说明：说明 dev 与 prod 均为 K8s 部署；访问地址（dev 如 https://<项目名>.apistest.dic.hillstonenet.com ）、ConfigMap/环境变量、常用 kubectl 命令。详见 assets/k8s/k8s-deploy-usage.md。

资产与参考

• 阶段/Job 与分支对应：references/REFERENCE.md、assets/pipeline-overview.md

• 私有镜像仓库（CI 登录、镜像命名、部署侧拉取）：references/REFERENCE.md 中「私有镜像仓库」小节

• .gitlab-ci.yml 示例结构（含私有仓库登录）：assets/gitlab-ci-example.yml

• 本地 Docker 多阶段构建命令：assets/docker-build-commands.md

• Python 基础镜像（默认 FROM）：assets/dockerfile-python-base.md（docker.dic.hillstonenet.com/library/python:3.12-slim）

• K8s 部署（dev → prod，必须）：Dev 模板 assets/k8s/dev_deployment.yaml.tpl（Deployment + Service + Ingress，${CI_PROJECT_NAME} 、命名空间 api-server、镜像 docker.dic.hillstonenet.com/private/${CI_PROJECT_NAME}:latest、ConfigMap ${CI_PROJECT_NAME}-env、Ingress host ${CI_PROJECT_NAME}.apistest.dic.hillstonenet.com）；部署脚本示例 assets/scripts/dev_deploy.sh.example、assets/scripts/prod_deploy.sh.example（context 切换、ConfigMap、envsubst、kubectl apply、rollout restart）；使用说明 assets/k8s/k8s-deploy-usage.md。可选通用模板 assets/k8s/deployment-template.yaml、scripts/k8s-deploy.sh。

• Git 操作说明（详细、可自动执行，仓库 git.tac.hillstonenet.com）：assets/git-operations.md（检查/配置远程、克隆、develop/bugfix/hotfix/master 各场景命令块）

• 若项目内已有「Git 使用说明」或 AGENTS.md，生成的分支与部署说明应与之一致