1. 整件事情的思路与拆解1.1 为什么要在 Debian 上折腾 Docker 的“中国源”先把话说在前面标题里的“中国源”和“Docker”放在一起指的是两条线——一条是Debian 系统本身的 apt 软件源另一条是Docker 镜像仓库源registry mirror。这两条线看起来都是“换个下载地址”但解决的问题完全不同很多人混为一谈后面配置的时候就容易懵。Apt 软件源管的是“系统里装的软件包”比如你用apt install docker-ce时那个 docker-ce 的 deb 包就是从 apt 源里拉的。而 Docker 镜像源管的是“容器运行需要的镜像”比如docker pull mysql:8.0时镜像是从 Docker Hub 或镜像加速器拉的。简单类比apt 源解决“安装 Docker 本身”的速度问题镜像源解决“拉取容器镜像”的速度问题。两个都得配置缺一个都会卡。以我自己的经验在 Debian 上安装 Docker 最让人头疼的不是命令记不住而是网络超时和GPG 密钥报错。默认走官方源在国内环境下经常遇到Temporary failure resolving、Could not connect to deb.debian.org这类问题镜像仓库更是动不动超时。所以换源不是玄学是刚需。1.2 我的安装方案选型与适用场景Docker 官方其实提供了三种安装路径用仓库安装apt install docker-ce、下载 deb 包手动安装、以及运行一个便捷脚本get.docker.com。在 Debian 上我通常推荐第一种也就是配置 Docker 官方 apt 仓库后用 apt 安装只是把仓库地址替换成可用的镜像地址而已。为什么不推荐手动下载 deb 包因为它不解决依赖问题。Docker 的 deb 包依赖containerd.io、docker-ce-cli、docker-buildx-plugin、docker-compose-plugin等好几个包手动dpkg -i很容易被依赖顺序折磨最终还得靠apt -f install擦屁股。而走 apt 仓库的方式依赖关系由 apt 统一处理干净利落。脚本安装虽然快但有两个问题一是脚本默认从官方源拉取容易超时二是脚本会绕过 apt 的包管理记录后续卸载和升级都麻烦。所以我的结论是如果你想要一个长期稳定、能正常升级的 Docker 环境老老实实走 apt 仓库 国内镜像源。1.3 这套方案解决的核心痛点我自己踩过的坑主要有三个这套方案也主要解决这三个GPG 密钥下载失败curl -fsSL https://download.docker.com/linux/debian/gpg在国内经常直接卡死解决方法是换成国内镜像地址下载同一个密钥。apt update 404 或签名失效原因往往是你把 Debian 版本代号填错比如 Debian 12 填成了bullseye而不是bookworm导致仓库地址对不上。这个后面会专门讲。docker pull 镜像慢得没法用装上 Docker 只是第一步如果镜像仓库源不配置加速器docker pull ubuntu能拉十几分钟而这十几分钟里你只能干等。这篇文章会按“系统源 → Docker 仓库源 → 镜像仓库加速 → 验证测试 → 常见问题”这个顺序走一遍和官方文档顺序略有差异但更贴近实操中真正会遇到的情况。2. 安装前需要准备的 4 个关键细节2.1 确认 Debian 系统版本与代号这一步错后面全错在动手之前请先确认你手上的 Debian 是什么版本。这不是走形式而是因为Docker 的 apt 仓库是根据 Debian 代号codename来组织目录结构的你填错了代号apt update就会报 404 或者干脆找不到包。执行下面这条命令看一下当前系统的版本信息cat /etc/os-release输出里关注VERSION_CODENAME这一行Debian 版本代号Docker 仓库路径中的关键字段Debian 11bullseyebullseyeDebian 12bookwormbookwormDebian 13trixietrixie举个例子如果你装的是 Debian 12那 Docker 仓库地址应该是https://mirrors.xxx.com/docker-ce/linux/debian bookworm stable而不是bullseye。我见过太多人在这一步翻车明明系统是 bookworm填了 bullseye结果 apt 一直报错还以为是源本身有问题。2.2 更新系统并安装必要依赖包确认完版本后先把系统的软件包索引更新一遍并安装几个后面会用到的工具。这一步能避免很多“命令不存在”的尴尬sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release这些包各自的作用ca-certificates让系统认识常见的 HTTPS 证书避免 curl 下载时因为证书问题被拒。curl用来下载 Docker 的 GPG 密钥和仓库配置。gnupg用来导入和校验 GPG 密钥。没有它后面gpg --dearmor这步会直接失败。lsb-release用于识别发行版信息有些脚本会依赖它生成仓库地址。提示如果你的系统是精简安装可能连sudo都没有。请先用su切换到 root 用户再执行apt install -y sudo否则后面所有sudo命令都会报 “command not found”。2.3 设置主机名与网络配置的顺带检查安装 Docker 本身不强制要求设置主机名但它会影响你后面用容器时的可读性和网络配置判断。比如容器内的 hostname 会默认取系统主机名你如果拿 Docker 跑 RabbitMQ、Redis、GitLab 这类服务日志里看到的主机名就是系统主机名乱糟糟的一串localhost排查问题时很难受。顺手设置一个有意义的主机名sudo hostnamectl set-hostname debian-docker另外如果你的 Debian 是刚装好的建议先确认网络是通的至少ping mirrors.aliyun.com能通。如果 ping 不通检查/etc/resolv.conf里的 DNS 配置否则后面下载密钥和包都会卡住。这里不展开讲静态 IP 配置但记住一点服务器类用途的 Debian 最好设静态 IPDHCP 分配的地址一旦变化后续 Docker 服务、端口映射、远程连接都会受影响。2.4 如果系统里装了旧版 Docker先卸载干净Debian 官方源里自带一个旧版 Docker 包叫docker.io有些发行版还预装了podman-docker这类兼容层。如果你确定要用 Docker 官方仓库的新版建议先卸载旧版本避免命令冲突和二进制覆盖问题sudo apt remove -y docker.io docker-doc docker-compose podman-docker containerd runc卸载不会删除/var/lib/docker下的现有数据所以别担心容器数据会丢。如果只是为了测试也可以不卸载旧版但我不推荐因为docker命令可能被指向旧版二进制后面排查问题时容易精神分裂。3. 实操用中国源完成 Docker 安装全流程3.1 替换 Debian 系统 apt 源为中国镜像源这一步不是 Docker 专属但很建议先做。Debian 默认的deb.debian.org和security.debian.org在国内访问速度不稳定将系统源替换成中国镜像源能显著提升包的下载速度也让后续apt update不再频繁超时。我常用的镜像源之一是中科大源mirrors.ustc.edu.cn当然阿里云源mirrors.aliyun.com、腾讯源mirrors.tuna.tsinghua.edu.cn实际上清华源的是mirrors.tuna.tsinghua.edu.cn也都是可靠的方案。以中科大源为例替换方式如下先备份原配置sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak然后修改/etc/apt/sources.list。以 Debian 12 bookworm 为例内容大概是deb https://mirrors.ustc.edu.cn/debian bookworm main contrib non-free non-free-firmware deb https://mirrors.ustc.edu.cn/debian-security bookworm-security main contrib non-free non-free-firmware deb https://mirrors.ustc.edu.cn/debian bookworm-updates main contrib non-free non-free-firmware注意两件事Debian 12 及以上版本新增了non-free-firmware组件老版本的 sources.list 模板里没有手动写的时候别漏。debian-security的路径在部分镜像站上是/debian-security不是所有镜像站路径都一样最好先打开镜像站首页确认目录结构。保存后执行更新sudo apt update如果apt update没有报错并且能正常下载索引系统源这一步就完成了。注意不同 Debian 版本和不同镜像站的仓库路径细节不完全一致最稳妥的办法是直接去镜像站看官方帮助页。中科大源和阿里云源都有针对 Debian 的配置示例照着复制即可。3.2 下载 Docker 官方 GPG 密钥并配置国内 Docker apt 仓库系统源就绪后开始配置 Docker 官方仓库。这里的核心思路是仓库地址仍然指向 Docker 官方在镜像站上的同步副本而不是修改 Docker 的包本身。也就是说 GPG 密钥是同一个包也是官方原包只是下载位置从国外挪到了国内。新建目录并下载 GPG 密钥sudo install -m 0755 -d /etc/apt/keyrings然后从国内镜像站下载 Docker 的 GPG 密钥并转换成 apt 需要的格式curl -fsSL https://mirrors.ustc.edu.cn/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg这里解释一下--dearmor的作用Docker 官方提供的 gpg 文件是 ASCII 格式的装甲文本apt 更擅长处理二进制格式的 keyring 文件所以需要用gpg --dearmor转换。有些教程里省掉这步直接把 gpg 原样放在 keyrings 下也能用但格式不够规范后续可能出问题。接着写入 Docker apt 仓库配置echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://mirrors.ustc.edu.cn/docker-ce/linux/debian \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null不要急着复制这个命令就跑先看懂它干了什么dpkg --print-architecture自动输出系统架构比如amd64、arm64。signed-by/etc/apt/keyrings/docker.gpg告诉 apt 用刚才下载的密钥来验证这个仓库的签名。$(. /etc/os-release echo $VERSION_CODENAME)从系统信息中提取 Debian 代号自动生成正确的仓库路径。如果你不想用自动变量也可以手动写。以 Debian 12 为例等效的写法是echo deb [archamd64 signed-by/etc/apt/keyrings/docker.gpg] https://mirrors.ustc.edu.cn/docker-ce/linux/debian bookworm stable | sudo tee /etc/apt/sources.list.d/docker.list提示如果下载 GPG 密钥仍然超时可以换成阿里云镜像站的地址https://mirrors.aliyun.com/docker-ce/linux/debian/gpg。这些镜像站同步的都是同一份官方密钥校验指纹结果一致。3.3 安装 Docker 引擎核心组件仓库配置完成后再次刷新 apt 索引并安装 Docker 各组件sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里我特意把docker-buildx-plugin和docker-compose-plugin一并装上了。很多人习惯只装docker-ce后面要构建多架构镜像或使用docker compose时才发现缺插件又得补装麻烦得很。现代 Docker 已经把构建和编排能力拆成了独立插件一次性装好更省事。安装完成后Docker 服务会自动启动。验证一下sudo systemctl status docker --no-pager sudo docker versiondocker version会分别显示 Client 和 Server 的版本信息。如果 Server 部分能看到版本号说明 Docker 守护进程正常运行。如果Server部分报错了多半是服务没启动执行sudo systemctl enable --now docker再试。3.4 配置 Docker 镜像仓库加速器Registry Mirror现在 Docker 本体已经装好但如果你立刻执行docker pull nginx可能会发现下载龟速。原因很简单Docker 默认从 Docker Hub 拉取镜像而 Docker Hub 的服务器位于国外。要解决这个问题就是配置镜像加速器让 Docker 从国内镜像源拉取镜像。编辑 Docker 守护进程配置文件/etc/docker/daemon.jsonsudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] } EOF解释一下选这几个地址的理由docker.m.daocloud.ioDaoCloud 提供的公共镜像加速服务响应速度在国内算第一梯队。dockerproxy.com社区维护的 Docker Hub 反向代理作为备用。docker.mirrors.ustc.edu.cn中科大镜像站的 Docker Hub 镜像稳定但偶尔会调整可用性。注意镜像加速器只对 Docker Hub 官方镜像生效对于quay.io、gcr.io等其他仓库的镜像是不起作用的。如果你要拉取的是这些第三方仓库的镜像需要单独配置或使用代理方案这已经超出本文范围了。改完配置后重启 Dockersudo systemctl daemon-reload sudo systemctl restart docker重启后查看配置是否生效docker info | grep -A 5 Registry Mirrors如果能看到你配置的几个地址说明镜像加速器已经生效。3.5 验证安装结果并跑一个测试容器配置到这一步理论上 Docker 已经完整可用了。用几个快速验证手段确认一切正常。先拉取一个体积小、常用的测试镜像docker pull hello-world这个镜像极小几秒钟就能拉完。如果拉取速度明显比以前快说明镜像加速器生效了。然后运行它docker run --rm hello-world如果看到一段 Hello from Docker! 的说明文字说明 Docker 从拉取镜像到创建容器、运行程序的完整链路都正常。再顺手验证一下基本操作docker run -d --name nginx-test -p 8080:80 nginx curl http://localhost:8080把nginx容器跑起来后用curl访问本机 8080 端口如果返回 nginx 默认欢迎页的 HTML说明端口映射、容器网络都没问题。测试完别忘了清理docker rm -f nginx-test到这里“Debian 中国源安装 Docker”的核心流程就全部跑通了。4. 安装过程中必踩的 6 个坑与排查实录4.1 “E: Unable to locate package docker-ce”这个报错基本可以锁定两个原因一是apt update没执行成功系统还停留在旧索引二是 Docker 仓库没有正确配置或者配置里的 Debian 代号写错了。排查步骤sudo apt update apt-cache policy docker-ce如果apt-cache policy docker-ce结果为空说明 apt 根本没感知到这个包。这时候检查/etc/apt/sources.list.d/docker.list里的仓库地址重点看bookworm、bullseye这类代号字段是否和系统匹配。另外stable这个词要保留它表示使用 Docker 的稳定发布通道。4.2 GPG 密钥报错 NO_PUBKEY 或 KEYEXPIREDapt update时如果出现类似The following signatures couldnt be verified because the public key is not available说明 apt 找不到或无法读取 GPG 密钥。常见原因有两个/etc/apt/keyrings/docker.gpg的权限不对。apt 在读取 keyrings 目录下的密钥时要求文件是全局可读的执行sudo chmod ar /etc/apt/keyrings/docker.gpg解决。密钥文件路径和signed-by参数不一致。仔细核对 docker.list 里写的是不是/etc/apt/keyrings/docker.gpg不要拼错。还有一种情况你之前用旧版 Docker 官方仓库配置方式旧方案直接把密钥放在/etc/apt/keyrings或/etc/apt/trusted.gpg.d和新的signed-by指向不一致。这种情况建议把旧密钥文件删掉重新按 3.2 节的步骤走一遍。4.3 下载慢、超时curl 拉 gpg 时卡死如果你的 curl 下载 GPG 密钥一直卡住多半是网络 QoS 问题而不是命令写错。解决方法是更换镜像源地址。我在 3.2 节给的是中科大源地址如果连接不稳定可以换阿里云源curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg密钥内容完全一致校验和不会变。没必要死磕某一个地址。4.4 Docker 服务启动失败提示 “Failed to start Docker Application Container Engine”这个报错比较常见于 CentOS 场景但在 Debian 上也可能出现通常和iptables配置、网桥冲突有关。查日志sudo journalctl -u docker --no-pager -n 50日志里如果看到docker0: iptables: No chain/target/match by that name大概率是 iptables 模块未加载或规则被其他工具改动过。一个比较靠谱的恢复方法是重启系统让 Docker 重新初始化网络栈。如果重启后仍然失败检查是否装了ufw或nftablesDocker 和它们同时管理 iptables 时可能发生冲突。4.5docker info显示镜像加速器没生效配置/etc/docker/daemon.json后一定要重启 Docker 服务而且注意顺序sudo systemctl daemon-reload先执行再sudo systemctl restart docker。如果先 restart 再 daemon-reload配置有时不会正确加载。另外daemon.json是 JSON 格式语法错误会导致整个文件被忽略Docker 甚至可能拒绝启动。检查一下 JSON 格式是否合法python3 -m json.tool /etc/docker/daemon.json有输出且无报错说明 JSON 没问题。4.6 不要忽略的用户组配置与权限问题安装完成后普通用户执行docker ps会提示permission denied while trying to connect to the Docker daemon socket。这是因为 Docker 守护进程默认用 root 权限运行socket 文件/var/run/docker.sock属于 root 用户和 docker 组。把当前用户加入 docker 组sudo usermod -aG docker $USER newgrp dockernewgrp docker可以让你不用重新登录就生效。但要注意加入 docker 组等价于授予该用户 root 级别权限因为 Docker 本身可以挂载宿主机目录到容器能访问整个文件系统。个人开发机这样做没问题生产环境的服务器要谨慎分配 docker 组权限。5. 把坑提前填掉几个提高成功率的实用建议5.1 选对镜像源的策略我在系统源推荐了中科大在 Docker 仓库推荐了中科大在镜像加速器推荐了 DaoCloud你可能觉得有点乱。其实原则很简单多备选不绑定。镜像源之间偶尔会限速、调整策略、出故障你手头多几个地址哪个能用用哪个别在一棵树上吊死。尤其要注意的是Docker 镜像加速器和 Debian 系统源是不同的服务不能用同一个地址互相替代。系统源解决apt install镜像加速器解决docker pull两码事。5.2 安装前先备份出错好回滚安装前建议做两个备份一是/etc/apt/sources.list的备份前面已经做了二是 Docker 是否已经存在配置文件/etc/docker/daemon.json如果有旧内容先备份sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date %F)这样即使配置写崩了也可以快速恢复原状。5.3 网络不通时先解决网络再继续我在文章开头提过 Debian 装好后要确认网络连通性这里再强调一次。很多人在安装 Docker 时卡在 GPG 下载、apt update 超时第一反应是“换源”但实际上源头可能是宿主机 DNS 配置不对。排查一下cat /etc/resolv.conf ping -c 3 mirrors.ustc.edu.cn如果ping不通先修网络再继续安装否则换哪个源都白搭。6. 安装完成后必须做的 3 件小事6.1 设置 Docker 开机自启动Debian 下 Docker 安装后默认会启用服务但如果你的系统是手动关闭过服务或者是在容器内嵌套安装可能没设开机自启。执行一下更保险sudo systemctl enable --now docker这两条命令会设置开机自启并立即启动服务。之后再检查一下systemctl is-enabled docker输出enabled就说明没问题。6.2 验证 Docker Compose 插件可用性现在docker compose已经是日常操作容器编排的标配。验证一下插件是否安装成功docker compose version如果输出Docker Compose version v2.x.x说明一切正常。如果提示找不到命令重新执行sudo apt install -y docker-compose-plugin。6.3 用国内镜像源加速常用镜像拉取镜像加速器配置的是“默认仓库”但有些镜像仓库如k8s.gcr.io、ghcr.io并不经过加速器。如果后续需要拉取这些特殊镜像建议单独针对该镜像配置加速地址或者使用docker pull时加上完整镜像仓库路径。另外在公司网络环境下Docker 拉取镜像经常会命中公司防火墙策略。一个常见做法是设置 HTTP 代理在daemon.json里加proxy配置。这个视你的具体网络环境而定不展开讲了。7. 写到最后的一点体会这套“Debian 中国源安装 Docker”的流程我前前后后至少走过了几十遍从 Debian 10 一直到 Debian 12从 X86 到 ARM踩过的坑基本都集中在网络和仓库配置上。每次有人问我“Docker 装不上怎么办”我第一反应都是问一句你用的是哪个源其实把 Docker 装好只是第一步真正体现功力的反而是后面的细节镜像加速器配置是否合理GPG 密钥是否管理规范用户组权限是否收紧了Compose 插件是否装全了。这些细节平时看起来不起眼真到出问题时每一件都能让人抓狂半天。最后再分享一个小技巧配置完daemon.json后建议顺手把/etc/docker/目录权限收紧到 root 用户可读写防止其他用户乱改配置导致 Docker 行为异常sudo chown -R root:root /etc/docker sudo chmod -R 644 /etc/docker/daemon.json这一套流程走完你的 Debian 就有了一个源在国内、镜像加速正常、组件齐全的 Docker 环境。后面不管是跑数据库、部署站点、还是折腾开发环境都算是有了个稳当的底子。 Debian中国源安装Docker全流程：apt换源与镜像加速器配置
1. 整件事情的思路与拆解1.1 为什么要在 Debian 上折腾 Docker 的“中国源”先把话说在前面标题里的“中国源”和“Docker”放在一起指的是两条线——一条是Debian 系统本身的 apt 软件源另一条是Docker 镜像仓库源registry mirror。这两条线看起来都是“换个下载地址”但解决的问题完全不同很多人混为一谈后面配置的时候就容易懵。Apt 软件源管的是“系统里装的软件包”比如你用apt install docker-ce时那个 docker-ce 的 deb 包就是从 apt 源里拉的。而 Docker 镜像源管的是“容器运行需要的镜像”比如docker pull mysql:8.0时镜像是从 Docker Hub 或镜像加速器拉的。简单类比apt 源解决“安装 Docker 本身”的速度问题镜像源解决“拉取容器镜像”的速度问题。两个都得配置缺一个都会卡。以我自己的经验在 Debian 上安装 Docker 最让人头疼的不是命令记不住而是网络超时和GPG 密钥报错。默认走官方源在国内环境下经常遇到Temporary failure resolving、Could not connect to deb.debian.org这类问题镜像仓库更是动不动超时。所以换源不是玄学是刚需。1.2 我的安装方案选型与适用场景Docker 官方其实提供了三种安装路径用仓库安装apt install docker-ce、下载 deb 包手动安装、以及运行一个便捷脚本get.docker.com。在 Debian 上我通常推荐第一种也就是配置 Docker 官方 apt 仓库后用 apt 安装只是把仓库地址替换成可用的镜像地址而已。为什么不推荐手动下载 deb 包因为它不解决依赖问题。Docker 的 deb 包依赖containerd.io、docker-ce-cli、docker-buildx-plugin、docker-compose-plugin等好几个包手动dpkg -i很容易被依赖顺序折磨最终还得靠apt -f install擦屁股。而走 apt 仓库的方式依赖关系由 apt 统一处理干净利落。脚本安装虽然快但有两个问题一是脚本默认从官方源拉取容易超时二是脚本会绕过 apt 的包管理记录后续卸载和升级都麻烦。所以我的结论是如果你想要一个长期稳定、能正常升级的 Docker 环境老老实实走 apt 仓库 国内镜像源。1.3 这套方案解决的核心痛点我自己踩过的坑主要有三个这套方案也主要解决这三个GPG 密钥下载失败curl -fsSL https://download.docker.com/linux/debian/gpg在国内经常直接卡死解决方法是换成国内镜像地址下载同一个密钥。apt update 404 或签名失效原因往往是你把 Debian 版本代号填错比如 Debian 12 填成了bullseye而不是bookworm导致仓库地址对不上。这个后面会专门讲。docker pull 镜像慢得没法用装上 Docker 只是第一步如果镜像仓库源不配置加速器docker pull ubuntu能拉十几分钟而这十几分钟里你只能干等。这篇文章会按“系统源 → Docker 仓库源 → 镜像仓库加速 → 验证测试 → 常见问题”这个顺序走一遍和官方文档顺序略有差异但更贴近实操中真正会遇到的情况。2. 安装前需要准备的 4 个关键细节2.1 确认 Debian 系统版本与代号这一步错后面全错在动手之前请先确认你手上的 Debian 是什么版本。这不是走形式而是因为Docker 的 apt 仓库是根据 Debian 代号codename来组织目录结构的你填错了代号apt update就会报 404 或者干脆找不到包。执行下面这条命令看一下当前系统的版本信息cat /etc/os-release输出里关注VERSION_CODENAME这一行Debian 版本代号Docker 仓库路径中的关键字段Debian 11bullseyebullseyeDebian 12bookwormbookwormDebian 13trixietrixie举个例子如果你装的是 Debian 12那 Docker 仓库地址应该是https://mirrors.xxx.com/docker-ce/linux/debian bookworm stable而不是bullseye。我见过太多人在这一步翻车明明系统是 bookworm填了 bullseye结果 apt 一直报错还以为是源本身有问题。2.2 更新系统并安装必要依赖包确认完版本后先把系统的软件包索引更新一遍并安装几个后面会用到的工具。这一步能避免很多“命令不存在”的尴尬sudo apt update sudo apt install -y ca-certificates curl gnupg lsb-release这些包各自的作用ca-certificates让系统认识常见的 HTTPS 证书避免 curl 下载时因为证书问题被拒。curl用来下载 Docker 的 GPG 密钥和仓库配置。gnupg用来导入和校验 GPG 密钥。没有它后面gpg --dearmor这步会直接失败。lsb-release用于识别发行版信息有些脚本会依赖它生成仓库地址。提示如果你的系统是精简安装可能连sudo都没有。请先用su切换到 root 用户再执行apt install -y sudo否则后面所有sudo命令都会报 “command not found”。2.3 设置主机名与网络配置的顺带检查安装 Docker 本身不强制要求设置主机名但它会影响你后面用容器时的可读性和网络配置判断。比如容器内的 hostname 会默认取系统主机名你如果拿 Docker 跑 RabbitMQ、Redis、GitLab 这类服务日志里看到的主机名就是系统主机名乱糟糟的一串localhost排查问题时很难受。顺手设置一个有意义的主机名sudo hostnamectl set-hostname debian-docker另外如果你的 Debian 是刚装好的建议先确认网络是通的至少ping mirrors.aliyun.com能通。如果 ping 不通检查/etc/resolv.conf里的 DNS 配置否则后面下载密钥和包都会卡住。这里不展开讲静态 IP 配置但记住一点服务器类用途的 Debian 最好设静态 IPDHCP 分配的地址一旦变化后续 Docker 服务、端口映射、远程连接都会受影响。2.4 如果系统里装了旧版 Docker先卸载干净Debian 官方源里自带一个旧版 Docker 包叫docker.io有些发行版还预装了podman-docker这类兼容层。如果你确定要用 Docker 官方仓库的新版建议先卸载旧版本避免命令冲突和二进制覆盖问题sudo apt remove -y docker.io docker-doc docker-compose podman-docker containerd runc卸载不会删除/var/lib/docker下的现有数据所以别担心容器数据会丢。如果只是为了测试也可以不卸载旧版但我不推荐因为docker命令可能被指向旧版二进制后面排查问题时容易精神分裂。3. 实操用中国源完成 Docker 安装全流程3.1 替换 Debian 系统 apt 源为中国镜像源这一步不是 Docker 专属但很建议先做。Debian 默认的deb.debian.org和security.debian.org在国内访问速度不稳定将系统源替换成中国镜像源能显著提升包的下载速度也让后续apt update不再频繁超时。我常用的镜像源之一是中科大源mirrors.ustc.edu.cn当然阿里云源mirrors.aliyun.com、腾讯源mirrors.tuna.tsinghua.edu.cn实际上清华源的是mirrors.tuna.tsinghua.edu.cn也都是可靠的方案。以中科大源为例替换方式如下先备份原配置sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak然后修改/etc/apt/sources.list。以 Debian 12 bookworm 为例内容大概是deb https://mirrors.ustc.edu.cn/debian bookworm main contrib non-free non-free-firmware deb https://mirrors.ustc.edu.cn/debian-security bookworm-security main contrib non-free non-free-firmware deb https://mirrors.ustc.edu.cn/debian bookworm-updates main contrib non-free non-free-firmware注意两件事Debian 12 及以上版本新增了non-free-firmware组件老版本的 sources.list 模板里没有手动写的时候别漏。debian-security的路径在部分镜像站上是/debian-security不是所有镜像站路径都一样最好先打开镜像站首页确认目录结构。保存后执行更新sudo apt update如果apt update没有报错并且能正常下载索引系统源这一步就完成了。注意不同 Debian 版本和不同镜像站的仓库路径细节不完全一致最稳妥的办法是直接去镜像站看官方帮助页。中科大源和阿里云源都有针对 Debian 的配置示例照着复制即可。3.2 下载 Docker 官方 GPG 密钥并配置国内 Docker apt 仓库系统源就绪后开始配置 Docker 官方仓库。这里的核心思路是仓库地址仍然指向 Docker 官方在镜像站上的同步副本而不是修改 Docker 的包本身。也就是说 GPG 密钥是同一个包也是官方原包只是下载位置从国外挪到了国内。新建目录并下载 GPG 密钥sudo install -m 0755 -d /etc/apt/keyrings然后从国内镜像站下载 Docker 的 GPG 密钥并转换成 apt 需要的格式curl -fsSL https://mirrors.ustc.edu.cn/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg这里解释一下--dearmor的作用Docker 官方提供的 gpg 文件是 ASCII 格式的装甲文本apt 更擅长处理二进制格式的 keyring 文件所以需要用gpg --dearmor转换。有些教程里省掉这步直接把 gpg 原样放在 keyrings 下也能用但格式不够规范后续可能出问题。接着写入 Docker apt 仓库配置echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://mirrors.ustc.edu.cn/docker-ce/linux/debian \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null不要急着复制这个命令就跑先看懂它干了什么dpkg --print-architecture自动输出系统架构比如amd64、arm64。signed-by/etc/apt/keyrings/docker.gpg告诉 apt 用刚才下载的密钥来验证这个仓库的签名。$(. /etc/os-release echo $VERSION_CODENAME)从系统信息中提取 Debian 代号自动生成正确的仓库路径。如果你不想用自动变量也可以手动写。以 Debian 12 为例等效的写法是echo deb [archamd64 signed-by/etc/apt/keyrings/docker.gpg] https://mirrors.ustc.edu.cn/docker-ce/linux/debian bookworm stable | sudo tee /etc/apt/sources.list.d/docker.list提示如果下载 GPG 密钥仍然超时可以换成阿里云镜像站的地址https://mirrors.aliyun.com/docker-ce/linux/debian/gpg。这些镜像站同步的都是同一份官方密钥校验指纹结果一致。3.3 安装 Docker 引擎核心组件仓库配置完成后再次刷新 apt 索引并安装 Docker 各组件sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin这里我特意把docker-buildx-plugin和docker-compose-plugin一并装上了。很多人习惯只装docker-ce后面要构建多架构镜像或使用docker compose时才发现缺插件又得补装麻烦得很。现代 Docker 已经把构建和编排能力拆成了独立插件一次性装好更省事。安装完成后Docker 服务会自动启动。验证一下sudo systemctl status docker --no-pager sudo docker versiondocker version会分别显示 Client 和 Server 的版本信息。如果 Server 部分能看到版本号说明 Docker 守护进程正常运行。如果Server部分报错了多半是服务没启动执行sudo systemctl enable --now docker再试。3.4 配置 Docker 镜像仓库加速器Registry Mirror现在 Docker 本体已经装好但如果你立刻执行docker pull nginx可能会发现下载龟速。原因很简单Docker 默认从 Docker Hub 拉取镜像而 Docker Hub 的服务器位于国外。要解决这个问题就是配置镜像加速器让 Docker 从国内镜像源拉取镜像。编辑 Docker 守护进程配置文件/etc/docker/daemon.jsonsudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.mirrors.ustc.edu.cn ] } EOF解释一下选这几个地址的理由docker.m.daocloud.ioDaoCloud 提供的公共镜像加速服务响应速度在国内算第一梯队。dockerproxy.com社区维护的 Docker Hub 反向代理作为备用。docker.mirrors.ustc.edu.cn中科大镜像站的 Docker Hub 镜像稳定但偶尔会调整可用性。注意镜像加速器只对 Docker Hub 官方镜像生效对于quay.io、gcr.io等其他仓库的镜像是不起作用的。如果你要拉取的是这些第三方仓库的镜像需要单独配置或使用代理方案这已经超出本文范围了。改完配置后重启 Dockersudo systemctl daemon-reload sudo systemctl restart docker重启后查看配置是否生效docker info | grep -A 5 Registry Mirrors如果能看到你配置的几个地址说明镜像加速器已经生效。3.5 验证安装结果并跑一个测试容器配置到这一步理论上 Docker 已经完整可用了。用几个快速验证手段确认一切正常。先拉取一个体积小、常用的测试镜像docker pull hello-world这个镜像极小几秒钟就能拉完。如果拉取速度明显比以前快说明镜像加速器生效了。然后运行它docker run --rm hello-world如果看到一段 Hello from Docker! 的说明文字说明 Docker 从拉取镜像到创建容器、运行程序的完整链路都正常。再顺手验证一下基本操作docker run -d --name nginx-test -p 8080:80 nginx curl http://localhost:8080把nginx容器跑起来后用curl访问本机 8080 端口如果返回 nginx 默认欢迎页的 HTML说明端口映射、容器网络都没问题。测试完别忘了清理docker rm -f nginx-test到这里“Debian 中国源安装 Docker”的核心流程就全部跑通了。4. 安装过程中必踩的 6 个坑与排查实录4.1 “E: Unable to locate package docker-ce”这个报错基本可以锁定两个原因一是apt update没执行成功系统还停留在旧索引二是 Docker 仓库没有正确配置或者配置里的 Debian 代号写错了。排查步骤sudo apt update apt-cache policy docker-ce如果apt-cache policy docker-ce结果为空说明 apt 根本没感知到这个包。这时候检查/etc/apt/sources.list.d/docker.list里的仓库地址重点看bookworm、bullseye这类代号字段是否和系统匹配。另外stable这个词要保留它表示使用 Docker 的稳定发布通道。4.2 GPG 密钥报错 NO_PUBKEY 或 KEYEXPIREDapt update时如果出现类似The following signatures couldnt be verified because the public key is not available说明 apt 找不到或无法读取 GPG 密钥。常见原因有两个/etc/apt/keyrings/docker.gpg的权限不对。apt 在读取 keyrings 目录下的密钥时要求文件是全局可读的执行sudo chmod ar /etc/apt/keyrings/docker.gpg解决。密钥文件路径和signed-by参数不一致。仔细核对 docker.list 里写的是不是/etc/apt/keyrings/docker.gpg不要拼错。还有一种情况你之前用旧版 Docker 官方仓库配置方式旧方案直接把密钥放在/etc/apt/keyrings或/etc/apt/trusted.gpg.d和新的signed-by指向不一致。这种情况建议把旧密钥文件删掉重新按 3.2 节的步骤走一遍。4.3 下载慢、超时curl 拉 gpg 时卡死如果你的 curl 下载 GPG 密钥一直卡住多半是网络 QoS 问题而不是命令写错。解决方法是更换镜像源地址。我在 3.2 节给的是中科大源地址如果连接不稳定可以换阿里云源curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg密钥内容完全一致校验和不会变。没必要死磕某一个地址。4.4 Docker 服务启动失败提示 “Failed to start Docker Application Container Engine”这个报错比较常见于 CentOS 场景但在 Debian 上也可能出现通常和iptables配置、网桥冲突有关。查日志sudo journalctl -u docker --no-pager -n 50日志里如果看到docker0: iptables: No chain/target/match by that name大概率是 iptables 模块未加载或规则被其他工具改动过。一个比较靠谱的恢复方法是重启系统让 Docker 重新初始化网络栈。如果重启后仍然失败检查是否装了ufw或nftablesDocker 和它们同时管理 iptables 时可能发生冲突。4.5docker info显示镜像加速器没生效配置/etc/docker/daemon.json后一定要重启 Docker 服务而且注意顺序sudo systemctl daemon-reload先执行再sudo systemctl restart docker。如果先 restart 再 daemon-reload配置有时不会正确加载。另外daemon.json是 JSON 格式语法错误会导致整个文件被忽略Docker 甚至可能拒绝启动。检查一下 JSON 格式是否合法python3 -m json.tool /etc/docker/daemon.json有输出且无报错说明 JSON 没问题。4.6 不要忽略的用户组配置与权限问题安装完成后普通用户执行docker ps会提示permission denied while trying to connect to the Docker daemon socket。这是因为 Docker 守护进程默认用 root 权限运行socket 文件/var/run/docker.sock属于 root 用户和 docker 组。把当前用户加入 docker 组sudo usermod -aG docker $USER newgrp dockernewgrp docker可以让你不用重新登录就生效。但要注意加入 docker 组等价于授予该用户 root 级别权限因为 Docker 本身可以挂载宿主机目录到容器能访问整个文件系统。个人开发机这样做没问题生产环境的服务器要谨慎分配 docker 组权限。5. 把坑提前填掉几个提高成功率的实用建议5.1 选对镜像源的策略我在系统源推荐了中科大在 Docker 仓库推荐了中科大在镜像加速器推荐了 DaoCloud你可能觉得有点乱。其实原则很简单多备选不绑定。镜像源之间偶尔会限速、调整策略、出故障你手头多几个地址哪个能用用哪个别在一棵树上吊死。尤其要注意的是Docker 镜像加速器和 Debian 系统源是不同的服务不能用同一个地址互相替代。系统源解决apt install镜像加速器解决docker pull两码事。5.2 安装前先备份出错好回滚安装前建议做两个备份一是/etc/apt/sources.list的备份前面已经做了二是 Docker 是否已经存在配置文件/etc/docker/daemon.json如果有旧内容先备份sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date %F)这样即使配置写崩了也可以快速恢复原状。5.3 网络不通时先解决网络再继续我在文章开头提过 Debian 装好后要确认网络连通性这里再强调一次。很多人在安装 Docker 时卡在 GPG 下载、apt update 超时第一反应是“换源”但实际上源头可能是宿主机 DNS 配置不对。排查一下cat /etc/resolv.conf ping -c 3 mirrors.ustc.edu.cn如果ping不通先修网络再继续安装否则换哪个源都白搭。6. 安装完成后必须做的 3 件小事6.1 设置 Docker 开机自启动Debian 下 Docker 安装后默认会启用服务但如果你的系统是手动关闭过服务或者是在容器内嵌套安装可能没设开机自启。执行一下更保险sudo systemctl enable --now docker这两条命令会设置开机自启并立即启动服务。之后再检查一下systemctl is-enabled docker输出enabled就说明没问题。6.2 验证 Docker Compose 插件可用性现在docker compose已经是日常操作容器编排的标配。验证一下插件是否安装成功docker compose version如果输出Docker Compose version v2.x.x说明一切正常。如果提示找不到命令重新执行sudo apt install -y docker-compose-plugin。6.3 用国内镜像源加速常用镜像拉取镜像加速器配置的是“默认仓库”但有些镜像仓库如k8s.gcr.io、ghcr.io并不经过加速器。如果后续需要拉取这些特殊镜像建议单独针对该镜像配置加速地址或者使用docker pull时加上完整镜像仓库路径。另外在公司网络环境下Docker 拉取镜像经常会命中公司防火墙策略。一个常见做法是设置 HTTP 代理在daemon.json里加proxy配置。这个视你的具体网络环境而定不展开讲了。7. 写到最后的一点体会这套“Debian 中国源安装 Docker”的流程我前前后后至少走过了几十遍从 Debian 10 一直到 Debian 12从 X86 到 ARM踩过的坑基本都集中在网络和仓库配置上。每次有人问我“Docker 装不上怎么办”我第一反应都是问一句你用的是哪个源其实把 Docker 装好只是第一步真正体现功力的反而是后面的细节镜像加速器配置是否合理GPG 密钥是否管理规范用户组权限是否收紧了Compose 插件是否装全了。这些细节平时看起来不起眼真到出问题时每一件都能让人抓狂半天。最后再分享一个小技巧配置完daemon.json后建议顺手把/etc/docker/目录权限收紧到 root 用户可读写防止其他用户乱改配置导致 Docker 行为异常sudo chown -R root:root /etc/docker sudo chmod -R 644 /etc/docker/daemon.json这一套流程走完你的 Debian 就有了一个源在国内、镜像加速正常、组件齐全的 Docker 环境。后面不管是跑数据库、部署站点、还是折腾开发环境都算是有了个稳当的底子。