Ubuntu 18.04/20.04 安装 Docker 完整指南：源配置、故障排查与避坑

上个月帮 A 同学处理一台 Ubuntu 20.04 的生产服务器准备在上面装 Docker。他照着网上搜到的一篇教程一路复制粘贴结果在apt update这里直接翻车404 报错刷满屏幕跟着又来了一串NO_PUBKEY的 GPG 错误。我把那篇教程翻出来看问题非常明显——仓库地址写的是老镜像源、系统代号对不上、密钥管理方式还是几年前的apt-key老路子。在 Ubuntu 22.04 以下版本上安装 Docker表面上是几条命令的事实际拆开看涉及的东西远比想象中多。18.04、20.04 这两代 LTS 到今天依然有大量存量服务器很多机器跑着核心业务不到万不得已是不会动系统级的。Docker 又是一个需要和内核、systemd、iptables 深度配合的组件哪一个环节没对上安装后就是一串莫名其妙的坑。这篇文章我不打算只贴一份命令清单。我会把安装前要摸清的底细、官方源的正确配置方式、apt 源失效的完整排查链路、旧系统上最常见的三大故障以及装完之后的权限、自启、镜像加速、离线部署、卸载升级这些事按照我在真实服务器上操作的顺序一五一十地摊开写。1. 为什么单独写“22.04 以下版本”这套安装指南和官方文档差在哪1.1 存量旧服务器多升级没那么轻松很多运维同学手里都压着几台 Ubuntu 18.04 或 20.04 的机器数据库、内部系统、老业务代码都跑在上面。系统标准支持结束后业务依然稳如泰山谁也不敢贸然do-release-upgrade。这种环境下Docker 作为新的运行时组件被塞进旧系统是再常见不过的需求。问题是网上绝大多数 Docker 安装教程默认你用的是最新 LTS。官方文档写得再清楚也不会替你想清楚“我的 18.04 该怎么办”“我的 20.04 能不能直接用这条命令”。这两个版本的内核、systemd、cgroup 默认配置都不一样直接复制最新教程的命令翻车概率非常高。1.2 自带源里的 docker.io 和官方 docker-ce 完全是两回事Ubuntu 自带源里其实有一个叫docker.io的包很多新手图省事直接apt install docker.io。装完发现能用但版本落后很多而且不带docker compose插件不带 buildx后续想要 Docker Compose v2 语法还得另配。对生产环境来说这基本是条死路。Docker 官方提供的docker-ce仓库则会持续跟进新版本包含docker-ce-cli、containerd.io、docker-buildx-plugin、docker-compose-plugin这一整套。我要讲的就是这条官方路线而不是 Ubuntu 自带的“阉割版”。1.3 教程失效的根源GPG 密钥与仓库配置方式早已换代旧教程里最常见的写法是这样curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository deb [archamd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable这套写法放在 Ubuntu 16.04、18.04 时代没问题但现在的apt已经明确弃用apt-key。新的推荐做法是把密钥单独存到/etc/apt/keyrings/docker.gpg然后在仓库配置里用signed-by指定它。这样某个仓库的密钥只验证该仓库不会因为一把全局密钥泄露导致所有源都不安全。另外一个隐蔽的坑是部分第三方镜像站只同步了新版本系统的仓库比如只同步 jammy不同步 focal、bionic。你配好源以后apt update直接 404。这也是我为什么在 1.3 里反复强调优先用官方源地址别去抄网上的“加速源”。2. 安装前先把你系统的底细摸清楚版本、内核、残留一个都不能漏2.1 版本、内核、架构一条一条确认我每到一个新环境动手装 Docker 之前一定会先跑下面四条命令cat /etc/os-release lsb_release -a uname -r dpkg --print-architecture为什么要这么干因为后面的仓库地址里$(lsb_release -cs)直接决定 apt 会去哪个目录找包。20.04 输出的是focal18.04 输出的是bionic。如果这条命令因为某些精简系统没装lsb-release而报错你至少要能从/etc/os-release里认出版本代号。内核版本决定存储驱动能不能用overlay2。Docker 官方要求内核 3.10 以上但我的经验是至少 4.0 以上才稳。20.04 默认内核 5.418.04 默认 4.15基本都满足。但是如果你的机器是云主机老模板内核被裁剪过后面overlay模块找不到就会出幺蛾子。架构信息同样重要。绝大多数服务器是 x86_64也就是amdp --print-architecture会输出amd64。如果是 ARM 机器后面的仓库配置里arch字段就要写成arm64。这一步错了apt update一样会报错。2.2 清掉历史残留避免新旧组件打架很多机器不是“全新安装”以前可能装过docker.io或者某个脚本安装的旧版 Docker。不清理干净后面安装docker-ce时会出现包冲突尤其是containerd和runc这两个底层组件。建议先执行一遍sudo apt remove docker docker-engine docker.io containerd runc这一步会移除旧包但默认不会删/var/lib/docker里的镜像、容器和数据卷。所以如果你只是想换个新版本 Docker这套操作是安全的如果你打算彻底重来那装完新版本之后再考虑单独清理数据目录。2.3 基础依赖四件套缺一个后面都会出幺蛾子sudo apt update sudo apt install ca-certificates curl gnupg lsb-release这四个包各管一段ca-certificates保证下载 https 资源时能完成证书校验内网镜像环境尤其容易缺它curl负责拉 GPG 密钥gnupg负责把密钥处理成 apt 认识的.gpg文件lsb-release提供lsb_release命令。我的习惯是提前把这四个包装好别等到配仓库时才发现缺东西。特别是极简模板连ca-certificates都可能没装curl访问 https 直接报证书错误查起来很费劲。3. 官方 apt 仓库安装全流程以及仓库失效的完整排查链路3.1 官方仓库的逐步配置命令先把密钥目录建好再拉取 GPG 密钥转成 apt 能识别的格式sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg然后写入源列表。这里我建议直接把架构和系统代号写进配置避免依赖环境变量出问题echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list如果lsb_release -cs输出异常就直接手动写死20.04 写focal18.04 写bionic。比如echo deb [archamd64 signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu focal stable | sudo tee /etc/apt/sources.list.d/docker.list接着更新源并安装sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin如果你的机器之前装过奇怪的 containerd有极小概率遇到“containerd.io 与某些包冲突”的情况先apt remove containerd再装一般能解决。3.2 apt update 报 404 的完整排查链路这是旧系统上最常出现的翻车点。报错长这样The repository https://download.docker.com/linux/ubuntu focal Release does not have a Release file.拿到这个报错不要急着换源。我一般按下面这条路走cat /etc/apt/sources.list.d/docker.list确认仓库 URL 和系统代号写对了。lsb_release -cs确认当前系统代号到底是focal还是bionic。手动探测仓库是否真的存在比如curl -I https://download.docker.com/linux/ubuntu/dists/focal/stable/Release如果返回 200说明源没问题那问题大概率出在公司内网的 apt 缓存或者代理镜像上需要检查代理配置。如果返回 404说明这个源根本没有这个发行版的目录。第三步对于“判断这是谁的锅”非常管用。很多教程里的镜像站只同步了 jammy没有同步 focal你按教程配完一定 404。遇到这种情况我的建议是直接切回官方源。还有一个高频 GPG 报错The following signatures couldnt be verified because the public key is not available: NO_PUBKEY ...处理思路也很直接重新下载 key 并生成/etc/apt/keyrings/docker.gpg然后确认 deb 配置里的signed-by路径和实际文件路径一致。可以用gpg --show-keys /etc/apt/keyrings/docker.gpg查看密钥指纹和官方文档列出的指纹对一下确保不是下载到了残缺文件。3.3 装完后的第一眼自检安装完成先别急着跑容器做一次快速自检systemctl status docker然后docker version docker info重点看Server Version是否正常、Storage Driver是不是overlay2、Cgroup Driver是systemd还是cgroupfs。如果docker version的 Client 正常但 Server 部分报错说明 dockerd 没起来需要去查日志。这一眼扫完基本能判断安装是否成功了一大半。4. 旧版本系统上最常踩的三个坑我把排查过程完整走一遍4.1 内核模块缺失overlay 与 br_netfilter症状很典型dockerd 能启动但创建容器时报错日志里出现error creating overlay mount或者容器启动到一半就退出了。原因在旧内核的模块没有自动加载。Ubuntu 18.04 的老内核尤其常见。先确认lsmod | grep overlay lsmod | grep br_netfilter如果输出为空就手动加载sudo modprobe overlay sudo modprobe br_netfilter但手动加载是一次性的重启就没了。我习惯顺手把模块写进/etc/modules-load.d/docker.confoverlay br_netfilter创建文件后可以用sudo systemctl restart systemd-modules-load验证是否生效。与此同时桥接网络转发相关的内核参数也顺手开一下。新建/etc/sysctl.d/99-docker.confnet.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1然后sudo sysctl --system让它生效。这一步做完后面容器网络的很多怪问题都能少一半。4.2 cgroup 驱动不一致dockerd 起不来另一种常见症状是我在云主机和某些学校机房服务器上碰到过的dockerd直接启动失败日志里写着failed to start daemon: Devices cgroup isnt mounted这个报错和系统当前的 cgroup 模式直接相关。老系统默认是 cgroup v1但一些虚拟化模板或者后来升级过 systemd 的环境挂载状态是残缺的。排查命令mount | grep cgroup ls /sys/fs/cgroup如果/sys/fs/cgroup下根本没有devices目录说明 v1 挂载不完整。我的建议是先让 Docker 和 systemd 保持同一个驱动。在/etc/docker/daemon.json里写{ exec-opts: [native.cgroupdriversystemd] }然后重启 Dockersystemctl restart docker docker info | grep -i cgroup看到Cgroup Driver: systemd就说明对上了。还有一种情况是系统内核默认走了 cgroup v2而你的 systemd 版本对 v2 支持不完整表现为各种奇怪的容器内资源限制失效。Ubuntu 20.04 的 systemd 是 245对 v2 支持还行18.04 的 systemd 是 237对 cgroup v2 支持不完整。遇到这种老系统可以在 GRUB 内核参数里强制回退 v1systemd.unified_cgroup_hierarchy0改完/etc/default/grub后执行sudo update-grub重启生效。这套操作对老系统非常见效。4.3 容器起得来但网络不通iptables 拦了哪一层症状是容器能创建、能进入但ping不通外网容器之间网络也可能不通。先查内核转发cat /proc/sys/net/ipv4/ip_forward输出是 0 就说明没开转发。临时开启sudo sysctl -w net.ipv4.ip_forward1然后在/etc/sysctl.d/99-docker.conf里持久化写入net.ipv4.ip_forward 1。接着看 iptables 的 NAT 规则sudo iptables -L -n -t nat | grep docker如果没有任何 docker 相关的链多半是 Docker 启动时没能接管 iptables或者 ufw 的 FORWARD 默认策略把容器流量拦了。可以用sudo ufw status看防火墙状态。这里我要特别提醒一句不要因为网络不通就把iptables: false写进 daemon.json。那是给专业网络环境做旁路接管用的普通用户开了以后只会更乱。正确做法是把 FORWARD 策略放行或者给 ufw 配置一条针对 Docker 网段的放行规则。5. 官方脚本与离线 deb 包两条备用安装路线怎么选5.1 官方脚本快是快但生产环境别赌Docker 官方给了一个一键安装脚本命令简单到离谱curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh这个脚本会自动检测系统、配源、装依赖、装最新版 Docker。开发机、临时实验环境用它可以省很多时间。但生产服务器我不推荐这么做。脚本内容随版本更新会变你今天拉下来的脚本和三个月前可能完全不同它默认安装的是当前最新版本版本策略不可控而且脚本在安装过程中会自己改源如果你公司内网要求走指定镜像源脚本反而会打乱你的环境。5.2 离线 deb 包隔离网络下的唯一选择有些服务器在等保环境、内网机房完全连不上外网。这时候唯一靠谱的路子就是离线 deb 安装。预先在有网的机器上把包下载好。在已经配好 Docker 官方源的环境执行apt download docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin把生成的.deb文件拷贝到离线机器后sudo dpkg -i *.deb如果报依赖缺失用sudo apt -f install修一下或者缺哪个包就再下载哪个包一起拷过去。这种方式的优点是完全可控版本、依赖、时间点都能锁定缺点是需要手动维护依赖链稍微繁琐。5.3 三条路线的对比表安装方式网络要求版本可控性依赖处理生产环境推荐度官方 apt 仓库需要能访问官方源或内网镜像高可锁定到具体版本apt 自动处理推荐官方脚本需要能访问外网低默认最新版脚本自动处理不推荐离线 deb 包完全离线可用高需手动解决依赖隔离网络下推荐6. 装完别急着跑容器权限组、开机自启、镜像加速和安全底子一次补齐6.1 把用户加进 docker 组但先搞清楚它的权限代价安装完成后如果你不想每条命令都敲sudo可以把当前用户加进 docker 组sudo usermod -aG docker $USER改完必须重新登录会话或者执行newgrp docker临时刷新。很多时候用户加完组发现还是要输 sudo就是因为没重新登录。但这里我要泼一盆冷水docker 组的权限等价于 root 权限。能操作 Docker 的用户可以挂载宿主机目录、运行特权容器基本等于控制了整台机器。多人共用服务器时不要随手把所有人都加进 docker 组。运维团队建议单独建一个专用账号只给这个账号授权。6.2 开机自启别等重启以后才发现没起来大部分使用官方 apt 仓库安装的机器Docker 和 containerd 的服务已经配置了开机自启。但用脚本安装或者老环境升级上来的有可能没注册。手动确认一遍最稳妥sudo systemctl enable docker sudo systemctl enable containerd sudo systemctl start docker如果你克隆过虚拟机模板也建议检查一下模板里是不是把服务 disable 了否则每克隆一台机器都要手动启一次 Docker很耽误事。6.3 daemon.json 一次配好数据目录、日志轮转、镜像加速装完之后我第一件事通常不是跑容器而是写/etc/docker/daemon.json。一个常用的基础配置如下{ registry-mirrors: [https://mirror.example.com], data-root: /data/docker, log-driver: json-file, log-opts: { max-size: 50m, max-file: 3 }, exec-opts: [native.cgroupdriversystemd] }这里的registry-mirrors是镜像加速地址。很多云服务商都提供免费的公共加速地址一般在你自己的云平台控制台或者镜像站页面里能找到。注意不要照抄别人配置文件里的地址别人能用的不一定对你有用。加速地址失效时删除该字段即可不影响容器运行只是拉镜像变慢。>sudo systemctl restart docker docker info | grep -i docker root dir\|logging driver\|cgroup看到输出和配置一致才算生效。6.4 顺手完成安全基线检查有几个基础安全项我每次装机都会顺手过一遍不要随便给容器加--privileged除非确定业务必须。不要修改/etc/docker目录的权限这个目录里存放着证书和关键配置。Docker 默认不监听 TCP 端口。如果你需要远程管理 API别直接暴露 2375/2376 端口到公网优先考虑走 SSH 隧道或内网受控网络。7. 验证安装、卸载与升级把退路留好7.1 安装结果自检组合拳配置完成后按顺序跑三组验证docker version docker info docker run --rm hello-worlddocker version确认 Client 和 Server 都正常响应docker info再核对一次存储驱动、cgroup 驱动、镜像加速是否生效hello-world则验证了从拉取镜像、创建容器到运行退出全链路都通。如果hello-world拉取镜像超时先回头检查registry-mirrors是否写对、docker info里能不能看到镜像加速地址。网络隔离环境里拉不到镜像就先用脚本或离线包预置几个必要镜像再测试运行。7.2 卸载要卸得干净哪些该删哪些别手滑如果哪一天 Docker 服务彻底不想要了完整的卸载流程是这样的sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin然后清理残留目录sudo rm -rf /etc/docker /var/lib/docker /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list强烈提醒一句/var/lib/docker是镜像、容器、数据卷的存放地点。如果里面还有任何需要保留的容器或数据卷先备份再动手删。7.3 升级 Docker 和跨版本升级系统顺序不能乱日常升级 Docker 很简单sudo apt update sudo apt install --only-upgrade docker-ce docker-ce-cli containerd.io软件升级默认不会动/var/lib/docker所以正常情况下镜像和数据卷都还在。但为了稳妥升级前至少把重要的镜像清单docker images存一份关键数据卷用docker run --volumes-from的方式打包备份。如果你准备把系统从 20.04 升级到 22.04那就更要注意了升级前确认当前 Docker 版本对目标系统有新版本兼容升级前对数据盘做快照升级后用docker info立刻检查 cgroup 驱动、存储驱动有没有变化。跨版本升级系统以后容器网络最容易出问题到时候回到第 4 章把 iptables 和内核转发检查一遍就够了。最后说点个人体会。在旧版 Ubuntu 上装 Docker问题十有八九不出在 Docker 本身而是你对系统底子了解多少内核模块加载了吗cgroup 是几iptables 让不让转发。把这几件事先搞明白再回去看那些安装教程你会发现它们其实简单得很。另外一个小技巧遇到任何装完起不来的怪问题先执行journalctl -u docker -n 50看日志这比在搜索引擎里把所有报错复制一遍快得多。日志里那行真正的原因往往就在最底部。