Ansible部署Grafana备份工具时环境变量无法传入容器问题排查

可能的触发原因 #

• Ansible docker-compose模块配置遗漏：如果用docker_compose模块部署，要么没正确配置environment参数，要么没指定env_file，甚至把环境变量写在了services节点外面，导致容器根本读不到。
• 模板渲染失败：要是用Ansible的template模块生成docker-compose.yml，模板里的变量引用可能写错了——比如Jinja2语法错了，或者变量名和playbook里的对不上，最后生成的yml里环境变量是空的。
• 权限卡壳：Ansible运行用户没权限读取env文件，或者生成的docker-compose.yml权限太低，docker-compose加载时读不到变量配置。
• 版本不兼容：Ansible的docker_compose模块和目标主机上的docker-compose版本不匹配，有些参数在旧版本里不生效，直接被忽略了。
• 变量没传对地方：playbook里的变量定义范围不对，比如只在某个task里临时定义，结果docker-compose模块所在的task根本拿不到这些变量。

一步步排查 #

1. 先看最终生成的docker-compose.yml：到目标主机上找到这个文件，直接看services下的environment段，是不是真的有GRAFANA_URL、GRAFANA_TOKEN这些变量，值对不对。比如正常应该是：

   services:
     grafana-backup:
       image: grafana-backup-tool:latest
       environment:
         - GRAFANA_URL=http://your-grafana-ip:3000
         - GRAFANA_TOKEN=your-actual-token
   

   要是这段是空的或者值错了，那问题肯定出在模板渲染或者Ansible变量传递上。
2. 验证模板渲染结果：用ansible-playbook --check -v your-playbook.yml运行，看输出里的模板渲染内容，确认变量有没有被正确替换。如果渲染出来的还是{{ grafana_url }}这种占位符，说明变量没传对或者模板语法错了。
3. 检查docker_compose模块参数：如果是直接在模块里指定environment，别写错格式。比如：

   - name: 启动grafana备份容器
     community.docker.docker_compose:
       project_src: /opt/grafana-backup
       environment:
         GRAFANA_URL: "{{ grafana_url }}"
         GRAFANA_TOKEN: "{{ grafana_token }}"
   

   注意这里的environment是模块的参数，不是yml文件里的配置，别搞混了。
4. env_file的坑要踩一遍：如果用env文件存变量，先确认文件已经被Ansible传到目标主机了，路径对不对，内容有没有写错，权限是不是644（可读）。同时yml里要正确引用：

   services:
     grafana-backup:
       env_file: ./grafana-backup.env
   

5. 手动跑docker-compose测试：在目标主机上直接执行docker-compose up -d，然后进容器跑env看变量在不在。如果手动跑也没有变量，那就是yml文件本身的问题；如果手动跑有，那就是Ansible执行过程的问题。
6. 看Ansible的详细日志：用ansible-playbook -vvv your-playbook.yml运行，盯着docker-compose模块的执行日志，看有没有报错、警告，或者参数传递错了的地方。
7. 核对docker-compose版本：目标主机上跑docker-compose --version，然后对照Ansible的文档，看看用的docker_compose模块支不支持这个版本的参数。版本太旧的话，要么升级docker-compose，要么调整Ansible的配置。
8. 确认变量能被访问到：在docker-compose模块的task前面加个debug任务，比如：

   - name: 检查变量是否存在
     debug:
       var: grafana_url
   

   看输出里有没有正确的变量值，要是没有，就是变量作用域的问题——比如变量定义在别的play里，或者inventory里没配置对。

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