🚀 在 Ubuntu 上部署 Docker，是搭建开发、测试和轻量化生产环境的常见选择。本文围绕“能装好、能跑通、能排错”三个目标，梳理 Docker Engine 的安装流程、基础验证、日常配置和常见问题处理，适合新手按步骤操作，也适合运维人员快速查漏补缺。
一、部署前准备：先确认环境
在安装 Docker 之前，建议先确认 Ubuntu 版本、系统架构和旧包状态。Docker 官方文档说明，Ubuntu 安装 Docker Engine 时应使用受支持的 64 位 Ubuntu 版本，并注意不同架构的兼容性，具体支持列表以 Docker Ubuntu 安装文档 为准。
- 查看系统版本：cat /etc/os-release
- 查看系统架构：uname -m
- 查看内核信息：uname -r
- 检查旧 Docker：docker --version
- 检查服务状态：systemctl status docker
如果系统曾经安装过 docker.io、docker-compose、containerd 或 runc 等包，建议先清理冲突包。官方文档也提醒，发行版自带的 Docker 包可能与 Docker 官方仓库的软件包产生冲突，因此正式安装前应先移除旧包，但镜像、容器、卷和网络数据不会因为卸载软件包而自动删除。
二、推荐安装方式：使用 Docker 官方 APT 仓库
🧩 在 Ubuntu 上安装 Docker，比较稳妥的方式是添加 Docker 官方 APT 仓库后再安装 Docker Engine、CLI、containerd、Buildx 和 Compose 插件。这种方式便于后续通过 apt 升级和维护，也更适合长期使用。
1. 卸载可能冲突的旧包
可以先执行以下命令清理旧包：
sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc
如果提示某些包未安装，通常不影响继续操作。若你希望保留原有镜像和容器，不要手动删除 /var/lib/docker；如果确实要全新部署，再考虑备份后清理该目录。
2. 安装依赖并添加密钥
执行：
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL 来源链接 -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
这里的 keyrings 目录用于保存 Docker 仓库签名密钥，目的是让 apt 在安装软件包时能够验证来源，降低安装到非可信包的风险。
3. 添加 Docker 软件源
执行：
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] 来源链接 $(. /etc/os-release && echo ${UBUNTU_CODENAME:-$VERSION_CODENAME}) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
如果 apt update 报错，优先检查系统代号是否识别正确、网络是否能访问 Docker 仓库，以及 /etc/apt/keyrings/docker.asc 是否存在。
4. 安装 Docker Engine
执行：
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
安装完成后，使用下面的命令验证：
sudo docker run hello-world
如果能看到测试容器成功运行并退出，说明 Docker Engine 基本可用。hello-world 镜像会从镜像仓库拉取并启动一个临时容器，适合作为安装后的第一步验证。
三、安装后的常用配置
1. 允许普通用户运行 Docker
默认情况下，Docker daemon 通过 Unix socket 工作，通常需要 root 权限或 sudo 才能访问。Docker 官方的 Linux 安装后步骤说明，可以把用户加入 docker 组以减少每次输入 sudo 的麻烦，但也明确提醒 docker 组具备较高权限，配置前应理解安全影响，参考 Docker Linux 安装后步骤。
执行：
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world
如果仍然提示权限不足，建议退出当前 SSH 会话后重新登录；虚拟机环境中，必要时重启系统。
2. 设置开机自启
多数 Ubuntu 环境使用 systemd 管理服务。可以执行：
sudo systemctl enable docker
sudo systemctl enable containerd
sudo systemctl start docker
查看服务状态：
systemctl status docker
3. 验证 Compose 插件
新版 Docker 通常使用 Compose 插件，命令形式为：
docker compose version
注意它与旧版 docker-compose 命令不同。如果脚本或教程仍写着 docker-compose，可以根据实际安装情况调整为 docker compose。
四、常见问题排查 🔧
问题 1：Cannot connect to the Docker daemon
这个错误通常表示 Docker 服务未启动、当前用户无权限，或 socket 无法访问。处理顺序建议如下：
- 检查服务：sudo systemctl status docker
- 启动服务：sudo systemctl start docker
- 查看日志：journalctl -u docker --no-pager -n 100
- 若普通用户执行失败，确认是否已加入 docker 组。
问题 2：permission denied while trying to connect
如果 sudo docker 可以运行，而 docker 直接运行失败，通常是用户权限问题。执行 sudo usermod -aG docker $USER 后，需要重新登录。如果之前用 sudo 运行过 Docker CLI，还可能导致 ~/.docker 目录权限异常，可执行：
sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
sudo chmod g+rwx "$HOME/.docker" -R
问题 3：镜像拉取很慢或超时
镜像拉取慢一般与网络环境、DNS、代理或镜像仓库访问质量有关。排查时可以先测试网络连通性，再检查 /etc/docker/daemon.json 是否配置了正确的 registry mirrors。修改配置后执行：
sudo systemctl daemon-reload
sudo systemctl restart docker
建议不要随意使用来源不明的镜像加速地址，生产环境尤其要关注镜像可信度、更新及时性和供应链安全。
问题 4：端口映射后无法访问服务
先确认容器是否运行：docker ps；再检查端口映射是否正确，例如 8080:80 表示宿主机 8080 转发到容器 80。还要检查应用是否监听 0.0.0.0，而不是只监听 127.0.0.1。Docker 官方文档也提示，使用 ufw 或 firewalld 管理防火墙时，Docker 暴露端口可能绕过部分防火墙规则，因此需要结合 DOCKER-USER 链和 iptables 规则进行控制。
问题 5：磁盘空间被镜像和日志占满
Docker 使用时间久了，未使用镜像、停止容器、构建缓存和日志都可能占用空间。可以先查看：
docker system df
谨慎清理：
docker container prune
docker image prune
docker volume prune
docker builder prune
执行 prune 前要确认没有误删仍需保留的容器、镜像或数据卷。尤其是 volume，可能保存数据库、上传文件等关键数据。
五、实用建议：让环境更稳定
- 固定部署流程：把安装命令、daemon.json、Compose 文件纳入文档或仓库，避免多人维护时环境不一致。
- 控制权限：不要把无关用户加入 docker 组，生产环境建议最小权限原则。
- 关注日志：定期查看 docker logs、journalctl 和应用日志，提前发现异常。
- 做好备份：容器可以重建，但数据卷里的业务数据必须单独备份。
- 区分环境：开发机可以追求方便，生产环境应更重视版本、权限、网络和镜像来源。
总结
✅ Ubuntu 部署 Docker 的核心思路并不复杂：先清理冲突包，再添加官方 APT 仓库，安装 Docker Engine 和 Compose 插件，最后完成权限、开机自启和运行验证。遇到问题时，不要盲目重装，应优先从服务状态、用户权限、网络访问、端口映射和磁盘空间几个方向排查。只要流程规范、配置可追踪、数据有备份，Docker 就能成为 Ubuntu 环境中高效、稳定的容器化基础设施。
