Docker stack deploy部署时如何向YAML配置文件传递环境变量

Docker Stack 原生支持和 Docker Compose 完全一致的环境变量替换逻辑，不需要手动修改YAML文件，也不需要引入复杂的第三方工具，以下是可直接落地的实现方式：

方案1：原生环境变量替换（零依赖，生产环境首选） #

你只需要提前修改一次live-deploy.yaml，把硬编码的镜像版本号换成变量占位符即可，后续部署完全不需要再改文件。

1. 修改live-deploy.yaml中的镜像配置，将固定版本号替换为变量：

# 原来的硬编码写法
# image: myregistry/myimage:v1.0.0
# 修改为变量占位符
image: myregistry/myimage:${IMAGE_TAG}

2. 在执行docker stack deploy命令前，将GitLab CI生成的CI_COMMIT_TAG注入当前执行环境的环境变量即可，Docker会自动完成占位符替换，不需要额外处理。

GitLab CI 对应部署阶段的脚本参考：

deploy_job:
  stage: deploy
  script:
    # 原有构建、推镜像逻辑保持不变
    - docker build --no-cache --platform linux/amd64 -t myregistry/myimage:$CI_COMMIT_TAG -f docker/php-backend/Dockerfile .
    - docker push myregistry/myimage:$CI_COMMIT_TAG
    # 将部署模板文件传到Swarm管理节点
    - scp live-deploy.yaml deploy-user@swarm-manager-ip:/opt/myapp/
    # 远程执行部署时，在远程命令上下文注入版本变量即可
    - ssh deploy-user@swarm-manager-ip "cd /opt/myapp && export IMAGE_TAG=$CI_COMMIT_TAG && sudo docker stack deploy --with-registry-auth -c live-deploy.yaml my-stack-name"

注意：如果是通过SSH远程执行部署命令，必须在远程执行的shell上下文里注入环境变量，本地GitLab Runner里导出的变量不会自动同步到远程服务器。

方案2：envsubst预渲染配置（适合多变量复杂场景） #

如果部署文件里有多个需要动态替换的字段，或者需要提前校验替换后的配置是否正确，可以用系统自带的envsubst工具（属于gettext组件，绝大多数Linux发行版默认预装）先把配置渲染成最终版本，再执行部署。
操作示例：

# 注入版本变量
export IMAGE_TAG=$CI_COMMIT_TAG
# 渲染配置文件，生成最终可用的部署yaml
envsubst < live-deploy.yaml > live-deploy-final.yaml
# 可选：打印渲染后的配置做校验，避免变量缺失
# cat live-deploy-final.yaml
# 用渲染后的文件执行部署
sudo docker stack deploy --with-registry-auth -c live-deploy-final.yaml my-stack-name

这个方案的优势是替换逻辑透明，你可以随时检查渲染后的文件内容，避免变量替换错误导致部署异常。

避坑说明 #

• 不要在CI流程里做自动修改YAML文件并提交回Git仓库的操作，这种做法会产生大量无意义的提交记录，污染版本历史，多人协作时还容易引发配置冲突。
• 不建议生产环境用latest标签配合强制拉取的方式部署，这种方式无法追溯部署版本，出问题后无法快速回滚到指定历史版本，稳定性风险极高。

小技巧：如果需要回滚到历史版本，只需要在执行部署命令时把IMAGE_TAG赋值为对应历史版本号即可，不需要改动任何配置文件。

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