GitLab CI + Docker 流水线

按「build → deploy」两阶段、分支触发规则与 Docker 多阶段构建，生成或维护 .gitlab-ci.yml、分支使用说明及部署脚本。部署方式固定为 dev → prod，且必须使用 Kubernetes（K8s）部署。生成或校验时必须遵循私有镜像源参考，尤其是 Python 相关：Docker 基础镜像使用 docker.dic.hillstonenet.com/library/python:*，pip/uv 安装依赖须使用约定镜像源（详见 assets/dockerfile-python-base.md）。文档与说明中的 Docker 命令、Git 命令均为可直接执行的命令：用户或 Agent 可将这些命令复制到终端直接运行，无需改写。在 .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 提交触发流水线。

1. 先：本地 Docker 构建与测试（必须优先执行）：在项目根目录执行多阶段构建（见 assets/docker-build-commands.md），本地验证镜像能否正常构建与运行，并可本地 docker run 做接口或功能验证；无需推送代码。Docker 命令可直接在终端执行（复制即用）。在确认本地构建与运行无误后，再执行步骤 2，避免有问题的提交触发流水线、占用 Runner 与部署环境。
2. 再：通过 Git 提交触发流水线：将代码推送到配置了 GitLab CI 的远程仓库对应分支（如 develop、bugfix/*、master）后，GitLab 根据 .gitlab-ci.yml 自动创建并执行流水线，完成构建镜像、推送到私有仓库、执行部署脚本；无需在 GitLab 界面手动点击运行。Git 命令（如 git remote、git push、git checkout 等）可直接在终端执行，生成说明时应给出可复制执行的完整命令。

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