1. 项目概述为什么用 Ansible 自动化部署 Docker 到 Ubuntu 18.04 是运维效率的分水岭Ansible、Docker、Ubuntu 18.04 这三个词凑在一起不是偶然而是过去五年里无数中小团队在技术选型十字路口反复权衡后落下的真实脚印。我第一次在客户现场看到运维同事手动敲完 23 行apt-get install、curl -fsSL、usermod -aG docker、systemctl enable、docker run hello-world全流程耗时 7 分 42 秒中间还因网络抖动重试了两次 apt 更新——那一刻我就知道这套操作必须进 playbook。这不是炫技是止损。Ubuntu 18.04 虽已进入 ESM扩展安全维护阶段但大量生产环境中的 CI/CD 构建节点、边缘计算网关、遗留测试集群仍在稳定运行它而 Docker 作为容器化事实标准其安装过程表面简单实则暗藏三类典型风险一是系统源配置不一致导致apt-transport-https缺失引发后续失败二是 GPG 密钥导入失败却无明确报错使apt-key add看似成功实则无效三是dockerd启动后未验证是否真正监听/var/run/docker.sock导致后续docker info命令静默失败。Ansible 的价值正在于把这三类“看似能跑、实则埋雷”的状态全部收束进可审计、可回滚、可批量执行的声明式逻辑里。它不替代你理解 Docker而是把你对 Docker 安装路径的每一次经验沉淀变成下次新服务器上线时自动复现的确定性动作。适合谁不是只给 DevOps 工程师看的——如果你是刚接手公司旧测试环境的 Python 开发需要快速在三台 Ubuntu 18.04 虚拟机上搭起本地镜像构建环境如果你是高校实验室管理员要为 15 个学生账号统一预装 Docker 并加入docker用户组甚至如果你只是 WSL2 下想摆脱sudo apt-get install docker.io那个老旧版本的束缚这个 playbook 都能直接抄作业。核心就一条让“安装 Docker”这件事从一次性的、依赖记忆的手工操作变成一个带版本号、带校验、带日志的可交付制品。2. 整体设计与思路拆解为什么不用 shell 脚本而选 Ansible四个不可妥协的技术动因2.1 拒绝“一锅炖”式 shell 脚本幂等性不是可选项是生存线很多人第一反应是写个.sh脚本apt update apt install docker-ce ...。我试过也维护过——直到某天凌晨三点接到告警说某台机器dockerd进程异常退出登录一看脚本被重复执行了 4 次/etc/docker/daemon.json被覆盖了三次最后一次写入的{}导致守护进程无法启动。Shell 脚本天然缺乏状态感知能力。而 Ansible 的apt、copy、service模块每个动作都内置幂等性判断apt模块会先查包是否已安装且版本匹配copy模块默认比对文件内容哈希service模块只在服务状态非预期时才触发启停。这意味着你可以放心地对同一台机器反复运行ansible-playbook docker-setup.yml -i inventory.ini它只会做“必要之事”不会因误操作引发雪崩。这不是功能差异是运维哲学的分野shell 脚本是“我命令你执行”Ansible 是“我声明你应处于什么状态”。2.2 Ubuntu 18.04 的特殊性官方源 vs Docker 官方源版本控制的生死抉择Ubuntu 18.04 官方仓库里的docker.io包版本长期卡在 18.09.x而 Docker 社区版CE早已迭代至 20.10。关键区别在哪docker.io缺少docker buildx插件支持无法构建多平台镜像其dockerd默认不启用containerd作为运行时导致后续集成 Kubernetes CRI 时出现兼容问题。因此本方案强制使用 Docker 官方 APT 源而非apt install docker.io。这带来两个硬性要求第一必须确保apt-transport-https和ca-certificates已预装否则apt-add-repository会静默失败第二Docker 官方 GPG 密钥必须通过apt_key模块安全导入而非curl | sudo apt-key add -这种已被弃用且存在安全风险的操作。Ansible 的模块化设计让这两个前置条件成为 playbook 中清晰、独立、可单独调试的步骤而不是 shell 脚本里一行容易被注释掉的apt-get install -y apt-transport-https ca-certificates。2.3 安全基线的刚性嵌入非 root 用户也能安全使用 Docker 的底层逻辑Docker 守护进程默认以 root 权限运行若普通用户需执行docker run传统做法是sudo usermod -aG docker $USER。但这存在两个隐患一是该命令需重启用户会话才能生效自动化中难以可靠触发二是若目标用户不存在usermod会报错中断。本方案采用 Ansible 的user模块配合group模块双重保障先确保docker组存在再将指定用户如ubuntu或deploy加入该组并设置append: yes避免覆盖已有组成员。更重要的是我们额外注入一条~/.bashrc配置export DOCKER_HOSTunix:///var/run/docker.sock。这并非必需但它让非 root 用户在不加sudo的前提下通过 Unix socket 直接与dockerd通信规避了sudo权限提升带来的审计盲区。这条配置由lineinfile模块精准插入仅当行不存在时才添加完美符合幂等原则。2.4 可观测性与故障定位为什么ignore_errors: no是默认而failed_when是必填项Ansible 默认会在任何任务失败时立即中止整个 playbook。这看似严苛实则是精准排障的前提。比如apt模块安装docker-ce-cli失败若忽略错误继续执行dockerd启动最终docker info必然报错但你根本不知道根因是 CLI 工具缺失还是守护进程未启动。因此本方案所有关键任务均显式声明ignore_errors: no虽为默认但显式写出是专业习惯并在涉及外部命令验证的任务如docker version中使用failed_when精确控制失败阈值。例如docker version返回非零码时Ansible 默认视为失败但若返回码为 1 且 stdout 包含Client:字样说明客户端已就绪而服务端未启动——这属于预期中的中间态不应中止流程。这种粒度的错误处理是 shell 脚本用|| echo failed根本无法实现的。3. 核心细节解析与实操要点从 playbook 结构到每个参数的深意3.1 playbook 文件结构为什么vars、handlers、roles不是摆设一个健壮的docker-setup.yml不是线性脚本而是分层架构--- - name: Install and configure Docker on Ubuntu 18.04 hosts: ubuntu1804_nodes become: true vars: docker_apt_repo: deb [archamd64] https://download.docker.com/linux/ubuntu bionic stable docker_gpg_key_url: https://download.docker.com/linux/ubuntu/gpg docker_users: - ubuntu - deploy pre_tasks: - name: Ensure required system packages are installed apt: name: {{ item }} state: present loop: - apt-transport-https - ca-certificates - curl - gnupg-agent - software-properties-common tasks: # ... 主安装任务 ... handlers: - name: Restart docker daemon service: name: docker state: restarted post_tasks: - name: Verify Docker installation command: docker version register: docker_version_result changed_when: false failed_when: Client: not in docker_version_result.stdout or Server: not in docker_version_result.stdoutvars区域定义了所有可配置变量这是复用性的基石。docker_apt_repo明确指向bionicUbuntu 18.04 代号避免因lsb_release -sc命令在某些精简镜像中不可用而导致源地址错误。docker_users是一个列表支持为多个用户批量授权而非硬编码单个用户名。pre_tasks确保所有依赖包在主流程前就位这是防止apt-key因缺少gnupg-agent而卡住的关键。handlers将服务重启解耦为事件驱动只有当docker-ce包实际更新或配置文件变更时才会触发Restart docker daemon避免无谓的守护进程震荡。post_tasks中的docker version验证用changed_when: false明确告知 Ansible 此任务永不标记为“已更改”仅用于检查failed_when则用字符串匹配精准捕获成功状态比单纯依赖返回码更可靠。3.2 GPG 密钥导入为什么apt_key模块比curl | apt-key add安全十倍过去常见的curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -存在两大硬伤第一apt-key add会将密钥无差别导入到/etc/apt/trusted.gpg这是一个全局信任库一旦该密钥未来被吊销所有依赖它的源都会失效第二curl下载过程无校验中间人攻击可替换密钥内容。Ansible 的apt_key模块彻底规避此风险- name: Add Dockers official GPG key apt_key: url: {{ docker_gpg_key_url }} state: present keyring: /usr/share/keyrings/docker-archive-keyring.gpg关键在keyring参数。它指定密钥存入/usr/share/keyrings/docker-archive-keyring.gpg这个专用密钥环随后在apt_repository模块中引用- name: Add Docker APT repository apt_repository: repo: {{ docker_apt_repo }} state: present filename: docker-ce-stable keyring: /usr/share/keyrings/docker-archive-keyring.gpg这样apt仅在解析docker-ce-stable.list源时才加载该专用密钥环实现密钥作用域最小化。这是 Debian/Ubuntu 官方推荐的安全实践也是apt-key命令自 2021 年起被标记为 deprecated 的根本原因。3.3 Docker Daemon 配置daemon.json的黄金三参数与陷阱/etc/docker/daemon.json是dockerd的心脏配置文件。新手常犯的错误是直接copy一个完整 JSON 文件却忽略了 Ubuntu 18.04 的 systemd 限制。本方案采用lineinfile模块逐行注入确保安全- name: Configure Docker daemon to use systemd as cgroup driver lineinfile: path: /etc/docker/daemon.json line: exec-opts: [native.cgroupdriversystemd], create: yes backup: yes insertbefore: EOF - name: Set default logging driver to json-file lineinfile: path: /etc/docker/daemon.json line: log-driver: json-file, create: yes backup: yes insertbefore: EOF - name: Configure default log options lineinfile: path: /etc/docker/daemon.json line: log-opts: {max-size: 10m, max-file: 3} create: yes backup: yes insertbefore: EOF为什么是这三个参数native.cgroupdriversystemd是 Ubuntu 18.04 的刚需。因为其内核和 systemd 版本较老若dockerd使用默认的cgroupfs驱动与systemd管理的 cgroup 层级冲突会导致容器启动后立即退出docker ps -a显示Exited (1)。log-driver和log-opts则解决磁盘爆满问题默认的journald驱动会将日志塞进systemd-journald而journald在 Ubuntu 18.04 上默认不限制大小一台持续构建的 CI 机器三天就能吃光 20GB 系统盘。json-file配合max-size/max-file实现日志轮转这是生产环境的底线配置。提示lineinfile的create: yes确保文件不存在时自动创建backup: yes在每次修改前生成.bak备份这是 Ansible 最朴实的容灾机制。3.4 用户组授权user模块的append: yes如何避免“组成员被清空”的灾难usermod -aG docker ubuntu中的-aappend至关重要。若省略-ausermod -G docker ubuntu会将用户ubuntu的附属组重置为仅docker导致其丢失sudo、adm等关键组权限SSH 登录后连sudo ls都被拒绝。Ansible 的user模块默认行为就是append: no即覆盖模式这恰恰是危险的。因此我们必须显式声明- name: Add users to docker group user: name: {{ item }} groups: docker append: yes loop: {{ docker_users }} when: item is definedappend: yes确保只向用户现有组列表中追加docker绝不删除其他组。when: item is defined是防御性编程防止docker_users列表中出现空值导致任务失败。这个细节是无数次线上事故后总结出的血泪经验。4. 实操过程与核心环节实现从零开始搭建可复用的部署流水线4.1 环境准备三步建立最小可行 Ansible 控制节点无需复杂环境一台干净的 Ubuntu 18.04 或 macOS 即可作为控制节点。三步到位安装 Ansiblepip3 install ansible2.9.27。选择 2.9.x 是关键——Ubuntu 18.04 的 Python 3.6.9 与 Ansible 2.10 的依赖存在兼容性问题ansible 2.9.27是最后一个官方支持 Python 3.6 的稳定版且对 Ubuntu 18.04 的apt模块适配最成熟。配置 SSH 免密登录在控制节点生成密钥ssh-keygen -t rsa -b 4096将公钥id_rsa.pub复制到目标机ssh-copy-id -i ~/.ssh/id_rsa.pub ubuntutarget-ip。务必验证ssh ubuntutarget-ip能无密码登录这是 Ansible 执行的基础。创建最小 inventory新建inventory.ini[ubuntu1804_nodes] web01 ansible_host192.168.1.101 ansible_userubuntu db01 ansible_host192.168.1.102 ansible_userubuntu此文件定义了目标主机列表、IP 地址和登录用户。ansible_host和ansible_user是标准变量Ansible 会自动识别。注意若目标机是 WSL2其 IP 地址每次重启可能变化。此时应改用ansible_hostlocalhost并在ssh_config中配置Host localhost段指定Port和IdentityFile确保连接稳定性。4.2 编写并执行 playbook逐行解析docker-setup.yml的实战意义完整docker-setup.yml如下已整合前述所有要点--- - name: Install and configure Docker on Ubuntu 18.04 hosts: ubuntu1804_nodes become: true vars: docker_apt_repo: deb [archamd64] https://download.docker.com/linux/ubuntu bionic stable docker_gpg_key_url: https://download.docker.com/linux/ubuntu/gpg docker_users: - ubuntu - deploy pre_tasks: - name: Ensure required system packages are installed apt: name: {{ item }} state: present loop: - apt-transport-https - ca-certificates - curl - gnupg-agent - software-properties-common tags: setup_deps tasks: - name: Add Dockers official GPG key apt_key: url: {{ docker_gpg_key_url }} state: present keyring: /usr/share/keyrings/docker-archive-keyring.gpg tags: gpg_key - name: Add Docker APT repository apt_repository: repo: {{ docker_apt_repo }} state: present filename: docker-ce-stable keyring: /usr/share/keyrings/docker-archive-keyring.gpg tags: apt_repo - name: Update apt cache after adding Docker repo apt: update_cache: yes tags: update_cache - name: Install Docker CE, CLI, and containerd apt: name: - docker-ce5:20.10.21~3-0~ubuntu-bionic - docker-ce-cli5:20.10.21~3-0~ubuntu-bionic - containerd.io1.6.24-1 state: present allow_unauthenticated: no tags: install_docker - name: Configure Docker daemon to use systemd as cgroup driver lineinfile: path: /etc/docker/daemon.json line: exec-opts: [native.cgroupdriversystemd], create: yes backup: yes insertbefore: EOF notify: Restart docker daemon tags: daemon_config - name: Set default logging driver to json-file lineinfile: path: /etc/docker/daemon.json line: log-driver: json-file, create: yes backup: yes insertbefore: EOF notify: Restart docker daemon tags: daemon_config - name: Configure default log options lineinfile: path: /etc/docker/daemon.json line: log-opts: {max-size: 10m, max-file: 3} create: yes backup: yes insertbefore: EOF notify: Restart docker daemon tags: daemon_config - name: Ensure docker group exists group: name: docker state: present tags: group_setup - name: Add users to docker group user: name: {{ item }} groups: docker append: yes loop: {{ docker_users }} when: item is defined tags: user_setup - name: Ensure docker service is enabled and started service: name: docker state: started enabled: yes tags: service_control handlers: - name: Restart docker daemon service: name: docker state: restarted post_tasks: - name: Verify Docker client and server versions command: docker version register: docker_version_result changed_when: false failed_when: Client: not in docker_version_result.stdout or Server: not in docker_version_result.stdout tags: verify_install - name: Verify Docker can run a test container command: docker run --rm hello-world register: hello_world_result changed_when: false failed_when: Hello from Docker! not in hello_world_result.stdout tags: verify_runtime执行命令ansible-playbook -i inventory.ini docker-setup.yml --tags setup_deps,gpg_key,apt_repo,install_docker,daemon_config,group_setup,user_setup,service_control,verify_install,verify_runtime。--tags参数允许你按需执行特定阶段例如首次调试时可先只跑--tags setup_deps,gpg_key确认基础依赖和密钥导入无误再逐步放开后续标签这是高效排障的核心技巧。4.3 版本锁定与回滚如何用apt模块精确控制 Docker 版本Docker 官方源中docker-ce包名格式为docker-ceepoch:upstream_version~debian_revision。Ubuntu 18.04 的bionic仓库中5:20.10.21~3-0~ubuntu-bionic是经过充分验证的稳定版本。apt模块通过name参数精确匹配此完整包名确保安装的一定是该版本而非apt install docker-ce可能拉取的最新不稳定版。若需回滚只需修改name值为旧版本号如5:20.10.16~3-0~ubuntu-bionic再次运行 playbookapt模块会自动执行降级操作。这种版本锁定能力是pip install docker5.0.0在 Python 生态中的对应物是生产环境可追溯性的基石。4.4 验证与日志docker version和docker run hello-world的深层含义post_tasks中的两个验证任务远不止“跑通就行”docker version的failed_when检查Client:和Server:字样是因为docker version输出格式为Client: Docker Engine - Community Version: 20.10.21 ... Server: Docker Engine - Community Engine: Version: 20.10.21若Server:部分缺失说明dockerd守护进程未启动或崩溃Client工具再新也无用。docker run --rm hello-world的failed_when检查Hello from Docker!字样是因为该镜像的入口点是一个 Shell 脚本其标准输出严格固定为该字符串。若此处失败常见原因有三dockerd未监听 socketnetstat -ltnp | grep :2375、/var/run/docker.sock权限不足ls -l /var/run/docker.sock应显示srw-rw---- 1 root docker、或 SELinux/AppArmor 限制Ubuntu 18.04 默认禁用可忽略。这些信息都直接体现在hello_world_result的stdout和stderr中Ansible 会原样输出为排障提供第一手证据。5. 常见问题与排查技巧实录那些 Ansible 报错背后的真实世界5.1 “Failed to connect to the host via ssh”SSH 连接失败的七种可能与速查表现象可能原因排查命令解决方案Permission denied (publickey)公钥未正确复制到目标机~/.ssh/authorized_keysssh -v ubuntutarget-ip查看详细认证过程重新执行ssh-copy-id或手动将公钥内容追加到目标机~/.ssh/authorized_keysConnection timed out目标机防火墙阻止 22 端口或网络不通ping target-iptelnet target-ip 22在目标机执行sudo ufw allow OpenSSH或检查网络路由No route to host目标机未开机或 IP 地址错误arp -agrep target-ipHost key verification failed目标机重装系统后 SSH 主机密钥变更ssh-keygen -R target-ip清除本地known_hosts中旧记录Could not resolve hostnameinventory 中ansible_host是域名但 DNS 解析失败nslookup target-hostname在 inventory 中直接使用 IP 地址或配置本地/etc/hostsConnection refused目标机 SSH 服务未运行ssh -o ConnectTimeout5 ubuntutarget-ip在目标机执行sudo systemctl status ssh若为inactive则sudo systemctl start sshAuthentication failed目标机用户密码已修改但ssh-copy-id未更新ssh -o PubkeyAuthenticationno ubuntutarget-ip临时启用密码登录重新执行ssh-copy-id实操心得永远先用ssh命令手动验证连接再运行 Ansible。Ansible 的报错信息往往不如原生命令清晰。5.2 “The task includes an option with an undefined variable”变量未定义的根源与修复此错误通常出现在docker_users变量为空或未定义时。例如在inventory.ini中忘记定义docker_users变量或在 playbook 中误写为docker_user少了个s。Ansible 的变量解析是动态的{{ docker_users }}在渲染时若找不到该变量就会抛出此异常。修复方法有二一是在vars区域为docker_users设置默认值docker_users: [ubuntu]二是在inventory.ini中为特定主机组定义变量[ubuntu1804_nodes:vars] docker_users [ubuntu, ci]这样所有属于ubuntu1804_nodes组的主机都会继承此变量。这是 Ansible 变量作用域inventory playbook role的典型应用。5.3 “apt module is not found”Ansible 2.9.x 下apt模块缺失的真相在极简 Ubuntu 18.04 镜像如ubuntu:18.04Docker 镜像中apt模块可能因缺少python3-apt包而无法加载。Ansible 报错module (apt) is missing。解决方案是在pre_tasks中增加一个raw模块任务绕过 Python 环境直接执行 shell 命令- name: Install python3-apt for apt module raw: apt-get update apt-get install -y python3-apt args: executable: /bin/bash when: ansible_facts[distribution] Ubuntu and ansible_facts[distribution_version] 18.04raw模块不依赖目标机的 Python 环境直接调用/bin/bash是解决此类“鸡生蛋”问题的终极手段。5.4 “dockerd: error while loading shared libraries: libseccomp.so.2”Ubuntu 18.04 的libseccomp兼容性陷阱这是 Ubuntu 18.04 用户安装新版 Docker 时最经典的坑。Docker 20.10 依赖libseccomp2 2.3.0而 Ubuntu 18.04 官方源中libseccomp2版本仅为2.3.3-4ubuntu0.18.04.1看似满足实则因 ABI 兼容性问题导致dockerd启动失败。journalctl -u docker日志中会出现error while loading shared libraries: libseccomp.so.2。解决方案是手动升级libseccomp2- name: Upgrade libseccomp2 to fix dockerd startup apt: name: libseccomp2 state: latest deb: https://archive.ubuntu.com/ubuntu/pool/main/libs/libseccomp/libseccomp2_2.5.4-1ubuntu1~18.04.1_amd64.deb when: ansible_facts[distribution] Ubuntu and ansible_facts[distribution_version] 18.04此任务通过deb参数直接安装来自 Ubuntu 官方 archive 的更新版.deb包绕过apt源同步延迟一劳永逸解决此兼容性问题。这是针对 Ubuntu 18.04 的专属补丁其他版本无需此步骤。5.5 “Failed to set up non-admin sandbox” 类错误的澄清这不是 Ansible 或 Docker 的问题网络热词中频繁出现的could not set up non-admin sandbox、could not set up agent sandbox等错误与本方案完全无关。这些错误源自 Windows 平台的特定软件如某些浏览器沙箱、企业级安全代理、或旧版 Visual Studio 安装程序它们试图在非管理员权限下创建隔离环境失败。Ubuntu 18.04 是 Linux 系统没有 Windows 的 UAC用户账户控制和 sandbox 机制。若你在 Ubuntu 环境中看到类似报错大概率是误将 Windows 错误日志粘贴到了 Linux 论坛或是混淆了不同平台的术语。请专注排查dockerd日志journalctl -u docker -n 50和apt安装输出这才是 Linux 世界的真相。6. 进阶扩展与生产就绪从单机部署到集群管理的平滑演进6.1 从docker-ce到docker-compose一键补齐容器编排能力Docker 安装完成后docker-compose是下一个刚需。它不再需要pip install docker-compose该方式在 Python 3.6 下易出错而是直接下载官方二进制- name: Download and install docker-compose get_url: url: https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-linux-x86_64 dest: /usr/local/bin/docker-compose mode: 0755 checksum: sha256:5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e5a5e - name: Create docker-compose symlink file: src: /usr/local/bin/docker-compose dest: /usr/bin/docker-compose state: linkchecksum参数是关键它确保下载的二进制文件未被篡改。get_url模块会自动校验 SHA256 值不匹配则任务失败这是安全交付的最后防线。6.2 镜像加速为 Docker 配置国内镜像源告别pull超时国内用户常因docker pull缓慢而放弃。在daemon.json中添加registry-mirrors即可- name: Configure Docker registry mirrors lineinfile: path: /etc/docker/daemon.json line: registry-mirrors: [https://your-mirror.mirror.aliyuncs.com], create: yes backup: yes insertbefore: EOF notify: Restart docker daemon将your-mirror替换为阿里云、腾讯云或中科大的镜像地址如https://mirrors.aliyun.com/docker-ce。注意registry-mirrors是数组若需配置多个需用blockinfile模块整体写入 JSON 数组而非lineinfile逐行添加否则 JSON 格式会损坏。6.3 安全加固禁用dockerd的 TCP Socket只保留 Unix Socketdockerd默认只监听 Unix Socket/var/run/docker.sock这是安全的。但若有人误配置DOCKER_OPTS-H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock就会暴露 TCP 端口导致未授权访问。本方案在daemon.json中不配置hosts字段确保dockerd仅绑定 Unix Socket。若需远程管理应使用 SSH 隧道ssh -L 2375:/var/run/docker.sock userhost这是零信任架构下的最佳实践。6.4 持续集成将 playbook 集成到 GitHub Actions实现代码即部署创建.github/workflows/docker-deploy.ymlname: Deploy Docker to Ubuntu 18.04 on: push: branches: [main] paths: [docker-setup.yml, inventory.ini] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.6 - name: Install Ansible run: pip install ansible2.9.27 - name: Run Docker Setup Playbook run: ansible-playbook -i inventory.ini docker-setup.yml env: ANSIBLE_HOST_KEY_CHECKING