如何基于Docker与GitLab在创建合并请求时搭建预览环境？

实现步骤 #

• 编写Docker镜像构建配置
  • 在项目根目录创建Dockerfile，根据项目类型（前端/后端）定义基础镜像、依赖安装、代码拷贝、启动命令。比如前端用nginx:alpine托管静态文件，后端用python:3.11-slim运行服务。
  • 配套创建.dockerignore文件，排除node_modules、.git、日志文件等不必要内容，缩小镜像体积。
• 配置GitLab CI/CD流水线
  • 项目根目录新建.gitlab-ci.yml，定义MR触发的流水线阶段：
    • build阶段：构建Docker镜像，用$CI_COMMIT_REF_SLUG-$CI_PIPELINE_ID作为镜像标签，保证每个MR的镜像唯一。
    • deploy阶段：把镜像部署到内部Docker宿主机或轻量K8s集群，用mr-$CI_MERGE_REQUEST_IID作为环境标识（比如容器名、子域名前缀），确保每个MR环境独立。
    • 部署时要么给每个容器分配唯一端口（比如30000 + $CI_MERGE_REQUEST_IID），要么用Nginx反向代理，通过子域名（如mr-123.preview.example.com）路由到对应容器。
• 生成预览链接并同步到MR
  • 在deploy阶段末尾加脚本生成预览链接，格式根据部署方式定，比如http://preview.example.com/mr-$CI_MERGE_REQUEST_IID或http://192.168.1.100:30123。
  • 用GitLab内置的$CI_JOB_TOKEN调用API，把链接评论到对应MR里，示例命令：

    curl --request POST --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" \
    "https://your-gitlab-domain/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
    --data "body=预览环境已就绪：http://preview.example.com/mr-$CI_MERGE_REQUEST_IID"
    

• 配置自动清理机制
  • 在.gitlab-ci.yml里加cleanup阶段，当MR关闭或合并时自动清理对应的容器和镜像，避免资源浪费：

    cleanup:
      stage: cleanup
      script:
        - docker stop mr-$CI_MERGE_REQUEST_IID || true
        - docker rm mr-$CI_MERGE_REQUEST_IID || true
        - docker rmi $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-$CI_PIPELINE_ID || true
      only:
        - merge_requests
      when: on_success
      rules:
        - if: $CI_MERGE_REQUEST_STATE == 'closed' || $CI_MERGE_REQUEST_STATE == 'merged'
    

常见问题及解决方法 #

• 端口冲突：多个MR同时部署时端口重复。解决：用MR的IID作为端口偏移量，或者直接用反向代理+子域名的方式，彻底避免端口暴露问题。
• 资源过载：大量MR运行导致宿主机CPU/内存不足。解决：启动容器时用--memory 512m、--cpus 0.5限制资源，或者加定时任务清理超过7天未活动的预览环境。
• 访问限制：内网无法访问预览环境，或外部访问存在安全风险。解决：部署到公司内部可访问的服务器，如需外部访问则在反向代理层加Basic Auth身份验证，只允许内部人员访问。
• 镜像构建失败：依赖下载慢或Dockerfile语法错误。解决：在GitLab CI里配置Docker层缓存，提前在本地测试Dockerfile的构建流程，确保能正常生成镜像。
• 权限不足：CI Runner没有Docker宿主机的操作权限。解决：把GitLab Runner用户加入docker用户组，或者使用Docker in Docker模式（注意启用DinD时的安全配置）。
• 环境不一致：预览环境和生产环境行为差异大。解决：复用生产环境的Dockerfile和环境变量配置，尽量保持基础镜像、依赖版本一致。

内容的提问来源于stack exchange，提问作者David49