一台全新的 Ubuntu 24.04.2 LTS（amd64），从零安装 Docker 官方版本，过程中踩了两个网络坑：安装包下载只有 3 KB/s，镜像拉取被直接拒绝。这篇把完整过程、报错原文和处理办法都记下来。
一、先确认环境
. /etc/os-release; echo "$PRETTY_NAME $(dpkg --print-architecture)"
Ubuntu 24.04.2 LTS amd64
检查是否已装过 Docker：
dpkg -l | grep -E '^ii\s+(docker|containerd)'
command -v docker
两条都没有输出，说明是干净系统，可以开始。
二、为什么用官方仓库，而不是 apt install docker.io
Ubuntu 源里的 docker.io 也能用，但版本通常落后，且 docker compose、buildx 这些插件要么没有、要么要给 apt 再装一遍第三方包。Docker 官方维护的 APT 仓库版本新、组件齐（docker-ce、docker-ce-cli、containerd.io、buildx、compose 插件），后续还能 apt upgrade 跟着升级。
所以本次走官方仓库。
三、添加官方 GPG 密钥和软件源
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
然后写入源。新版 Ubuntu（24.04）推荐 deb822 格式，比老的 sources.list 单行写法更清晰：
. /etc/os-release
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: ${VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
生成的文件长这样：
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: noble
Components: stable
Architectures: amd64
Signed-By: /etc/apt/keyrings/docker.asc
sudo apt update 能正常拉到 stable InRelease 就说明源配好了。
四、坑一：安装包下载只有 3 KB/s
按官方文档执行：
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
apt 解析依赖没问题，但卡在了下载阶段：
Get:1 https://download.docker.com/linux/ubuntu noble/stable amd64 containerd.io amd64 2.4.2 [23.3 MB]
进度几乎不动。实测同一台机器：
-
download.docker.com→ 约 3 KB/s，20 秒只下到 65 KB - 阿里云 Docker CE 镜像 → 1~4 MB/s
containerd.io 一个包 23 MB，按 3 KB/s 要下两个多小时，只能换路子。
做法：先从国内镜像下 deb，再用 dpkg 装
注意一点：软件源仍然保留官方地址（以后 apt upgrade 还是走官方），只是这一次安装的包从国内镜像拿，版本完全一致。
先查出版本和文件名：
apt-cache show docker-ce | grep -E '^(Version|Filename|Size)'
再逐个下载（版本号按你 apt-cache 看到的填）：
BASE=https://mirrors.aliyun.com/docker-ce/linux/ubuntu
sudo apt install -y ca-certificates
curl -fLO $BASE/dists/noble/pool/stable/amd64/containerd.io_2.4.2-3~ubuntu.24.04~noble_amd64.deb
curl -fLO $BASE/dists/noble/pool/stable/amd64/docker-ce-cli_29.9.2-1~ubuntu.24.04~noble_amd64.deb
curl -fLO $BASE/dists/noble/pool/stable/amd64/docker-ce_29.9.2-1~ubuntu.24.04~noble_amd64.deb
curl -fLO $BASE/dists/noble/pool/stable/amd64/docker-ce-rootless-extras_29.9.2-1~ubuntu.24.04~noble_amd64.deb
curl -fLO $BASE/dists/noble/pool/stable/amd64/docker-buildx-plugin_0.38.1-1~ubuntu.24.04~noble_amd64.deb
curl -fLO $BASE/dists/noble/pool/stable/amd64/docker-compose-plugin_5.6.1-1~ubuntu.24.04~noble_amd64.deb
一定要校验哈希
从镜像站拿包，就要自己核对完整性。镜像站提供同版本的 Packages 索引，里面有 SHA256：
curl -s $BASE/dists/noble/stable/binary-amd64/Packages | grep -A2 '^Package: docker-ce$'
sha256sum docker-ce_29.9.2-1~ubuntu.24.04~noble_amd64.deb
本次六个包的 SHA256 与索引全部一致，可以放心安装。
装包：
sudo dpkg -i containerd.io_*.deb docker-ce-cli_*.deb docker-ce_*.deb \
docker-ce-rootless-extras_*.deb docker-buildx-plugin_*.deb docker-compose-plugin_*.deb
dpkg 报依赖错误时补一句 sudo apt-get -f install -y 即可。
安装过程中会自动创建两个 systemd 服务并设置开机自启：
Created symlink /etc/systemd/system/multi-user.target.wants/containerd.service
Created symlink /etc/systemd/system/multi-user.target.wants/docker.service
Created symlink /etc/systemd/system/sockets.target.wants/docker.socket
五、验证安装与服务
docker --version
docker compose version
docker buildx version
systemctl is-active docker containerd
本次输出：
Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1
github.com/docker/buildx v0.38.1
active
active
再看守护进程状态：
sudo docker info --format 'Server={{.ServerVersion}} Driver={{.Driver}} Cgroup={{.CgroupDriver}}'
Server=29.9.2 Driver=overlayfs Cgroup=systemd
到这里 Engine 本身的安装就算完成了。
六、坑二：hello-world 拉不下来
真正跑一个容器才算验证：
sudo docker run --rm hello-world
结果直接失败：
Unable to find image 'hello-world:latest' locally
docker: Error response from daemon: failed to resolve reference "docker.io/library/hello-world:latest":
failed to do request: Head "https://registry-1.docker.io/v2/library/hello-world/manifests/latest":
dial tcp 199.59.148.202:443: connect: connection refused
connection refused 说明不是 Docker 的问题，是国内网络访问 Docker Hub 不通。
做法：给守护进程配镜像加速
编辑 /etc/docker/daemon.json（文件不存在就新建）：
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://docker.1panel.live",
"https://dockerproxy.net"
]
}
写完后重启服务：
sudo systemctl restart docker
sudo docker info | grep -A3 'Registry Mirrors'
再跑一次：
sudo docker run --rm hello-world
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
镜像拉取、容器创建、运行、输出全部正常。
提醒：第三方镜像地址会失效或变化，配多个是为了一个挂了还有备选。企业环境建议自建 Harbor 或使用云厂商的容器镜像服务。
七、免 sudo（可选，注意安全）
现在普通用户执行 docker ps 会提示：
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
把用户加入 docker 组即可免 sudo：
sudo usermod -aG docker $USER
重新登录后生效（不是 source，要退出会话）。
要清楚这意味着什么：docker 组的成员可以通过挂载宿主目录等方式拿到 root 权限，本质上等价于 root。只有在你信任这台机器上的这个账号时才加。不想加就一直用 sudo docker，或者用 rootless 模式（docker-ce-rootless-extras 已经装了，执行 dockerd-rootless-setuptool.sh install 配置）。
八、常用检查命令
docker version # 客户端 + 服务端版本
docker info # 引擎详情、存储驱动、镜像加速
docker ps -a # 容器列表
docker images # 本地镜像
docker system df # 磁盘占用
docker system prune -a # 清理无用镜像/容器（谨慎）
九、卸载
sudo apt purge -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
sudo rm -rf /var/lib/docker /var/lib/containerd
sudo rm -f /etc/apt/sources.list.d/docker.sources /etc/apt/keyrings/docker.asc
小结
整件事拆开看就四步：加官方源、装包、起服务、跑容器验证。真正的麻烦都在网络上：
# 1. 官方源（保留，用于后续升级）
sudo apt update
# 2. 包下载慢 → 国内镜像下 deb，校验 SHA256 后 dpkg 安装
sudo dpkg -i *.deb
# 3. 服务与版本
systemctl is-active docker && docker --version
# 4. 镜像拉不动 → 配 registry-mirrors
sudo systemctl restart docker && sudo docker run --rm hello-world
Docker 本身几乎不会出问题，卡住你的九成是"包下不下来"和"镜像拉不下来"这两件事。想清楚这两条链路，剩下的都是例行操作。
