本文记录在 Ubuntu / Debian 系统中手动安装 Docker 的完整流程，适合拿来存档或后续部署时直接参考。
适用系统：
- Debian 11 / 12 / 13
- Ubuntu 22.04 / 24.04
注意：Ubuntu 和 Debian 的 Docker 官方仓库地址不同，不能混用。
一、卸载旧版本（避免冲突）
如果系统中已经安装过旧版 Docker，建议先卸载。
Debian
apt remove docker.io docker-compose podman-docker containerd runc -y
Ubuntu
apt remove docker.io docker-compose docker-compose-v2 podman-docker containerd runc -y
二、更新系统软件包
apt update
apt upgrade -y
三、安装必要依赖
apt install -y ca-certificates curl
四、添加 Docker 官方 GPG key
这一步 Debian 和 Ubuntu 通用。
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
五、添加 Docker 官方仓库
这里开始需要区分系统。
1）Debian 添加仓库
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/debian \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| tee /etc/apt/sources.list.d/docker.list > /dev/null
2）Ubuntu 添加仓库
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" \
| tee /etc/apt/sources.list.d/docker.list > /dev/null
然后更新软件包索引：
apt update
六、安装 Docker Engine 与 Compose 插件
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
七、验证是否安装成功
查看 Docker 版本：
docker --version
查看 Docker Compose 插件版本：
docker compose version
运行测试容器：
docker run hello-world
如果输出中包含：
Hello from Docker!
说明 Docker 已安装成功。
八、设置 Docker 开机自启
systemctl enable docker
查看服务状态：
systemctl status docker
九、配置当前用户免 sudo（可选）
如果你不是使用 root 用户操作，可以把当前用户加入 docker 用户组。
usermod -aG docker 你的用户名
执行后重新登录终端，或者执行：
newgrp docker
这样后续执行 docker 命令时就不需要再加 sudo 了。
十、建议优化：配置镜像加速
如果拉取镜像速度较慢，可以配置镜像加速。
先创建 Docker 配置目录：
mkdir -p /etc/docker
编辑配置文件：
vim /etc/docker/daemon.json
写入如下内容：
{
"registry-mirrors": [
"https://dockerproxy.com",
"https://mirror.ccs.tencentyun.com"
]
}
保存后重启 Docker：
systemctl restart docker
十一、查看 Docker 服务日志
如果 Docker 启动失败，或者排查运行问题，可以查看服务日志：
journalctl -u docker -n 100 --no-pager
十二、常见问题
1. Ubuntu 不要误配成 Debian 源
这是一个非常常见的错误。
错误示例：
https://download.docker.com/linux/debian noble
这里的 noble 是 Ubuntu 24.04 的版本代号，不属于 Debian。
如果你是 Ubuntu，正确地址应该是：
https://download.docker.com/linux/ubuntu noble
2. 安装时出现 connection reset 或 TLS 握手失败
例如：
curl: (35) Recv failure: Connection reset by peer
Could not handshake: Error in the pull function
这类问题常见原因有：
- IPv6 网络不稳定
- 双网卡路由异常
- 机房或运营商到 Docker CDN 的链路质量较差
可以先尝试强制使用 IPv4：
curl -4fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
apt -o Acquire::ForceIPv4=true update
如果这样就恢复正常，通常说明问题不在 Docker 命令本身，而在 IPv6 或网络链路。
总结
Docker 在 Ubuntu / Debian 上安装并不复杂，关键就是两点：
- 系统类型要分清楚，Ubuntu 和 Debian 源不能混用
- 如果拉取失败，优先排查网络，尤其是 IPv6 和双网卡路由问题
这样配置好之后，后续无论是安装单个容器，还是部署 docker compose 项目，都会方便很多。