Docker 部署完整流程教程

环境：阿里云轻量应用服务器，Ubuntu 24.04
本文档整理 Docker 从零安装，到日常部署任意开源项目的通用流程，
以及实际操作中踩过的坑和排查方法，供以后新增项目时参考复用。

一、核心概念先搞清楚

Docker（容器引擎，全局只装一次）
  ↓
Docker Compose（批量管理容器的插件工具，全局只装一次）
  ↓
每个项目自己的 docker-compose.yml（配置清单，每个项目各自一份）
  ↓
docker compose up -d（照着清单拉镜像+启动容器）

关键理解：

Docker 引擎和 Compose 插件，服务器上只需要装一次，所有项目共用
每个项目的 docker-compose.yml 各自独立，放在各自的文件夹里，互不干扰
容器内部监听的端口是软件自己写死的，不能通过配置文件修改；能改的只有"宿主机对外暴露哪个端口"

二、安装 Docker

第一步：更新软件源

apt update
# 刷新一遍软件源里"有哪些包、最新版本是什么"的清单，不会真的安装/更新任何东西

第二步：安装 Docker

📝 注释：官方一键安装脚本 curl -fsSL https://get.docker.com | sh 在国内网络环境下大概率会失败
（报错类似 Recv failure: Connection reset by peer），因为该脚本需要连接境外站点。
不需要纠结这条路，直接用下面的国内方案，这是最终验证成功、稳定可用的方法。

apt install docker.io -y
# 从 Ubuntu 官方软件源安装 Docker
# docker.io 是 Ubuntu 仓库里 Docker 的包名，走国内源，速度快、稳定
# -y 表示遇到确认提示自动选"是"

systemctl start docker
# 启动 Docker 服务

systemctl enable docker
# 设置 Docker 开机自动启动，避免服务器重启后要手动再启动一次

docker --version
# 查看版本号，确认安装成功

第三步：安装 Docker Compose 插件

apt install docker-compose-v2 -y
# 安装批量管理多容器的插件工具

docker compose version
# 查看版本号，确认安装成功

📝 注释：docker compose 是批量管理多个容器的工具，可以用一份配置文件（docker-compose.yml）
描述"要跑几个容器、用什么镜像、怎么互相连接"，执行一条命令就能把所有容器一次性拉起来，
避免手动逐个 docker run 的繁琐操作。

第四步：配置国内镜像加速（强烈建议，避免后续拉镜像超时）

📝 注释：不配置这一步，之后执行 docker compose up -d 拉取镜像时，
大概率会报错 failed to resolve reference ... dial tcp ... i/o timeout，
原因同样是国内直连境外镜像仓库 Docker Hub 超时。

mkdir -p /etc/docker
# 创建 Docker 的配置文件目录（已存在则不报错）

cat > /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://docker.1panel.live"
  ]
}
EOF
# 写入配置文件，告诉 Docker："以后拉取镜像时，优先走这几个国内加速地址"
# 这几个地址如果某天失效了，可以搜索"docker镜像加速"换成其他可用地址重试

systemctl daemon-reload
# 让系统重新读取服务配置（因为 Docker 的配置变了）

systemctl restart docker
# 重启 Docker 服务，让镜像加速配置正式生效

三、部署任意一个新项目的通用流程

以后不管部署什么开源软件（论坛、下载工具、笔记应用等），都是这四步套路：

第一步：新建专属文件夹

mkdir -p /opt/项目名
cd /opt/项目名

📝 注释：/opt 目录是 Linux 里约定俗成、专门用来存放"额外安装的第三方软件项目"的地方，
每个项目一个独立文件夹，方便管理、互不干扰。

第二步：写 docker-compose.yml 配置清单

cat > docker-compose.yml << 'EOF'
services:
  服务名:
    image: 镜像名:版本号
    # 去项目官方文档查这个软件对应的 Docker 镜像名称

    restart: always
    # 容器异常退出或服务器重启后自动重新启动

    ports:
      - "宿主机端口:容器内部端口"
      # 宿主机端口自己定，注意别跟其他项目冲突
      # 容器内部端口是软件自己写死的，需要查官方文档，不能随便改

    volumes:
      - 数据卷名:容器内的数据存放路径
      # 把容器里的重要数据（用户上传的文件、数据库等）映射到宿主机保存
      # 这样即使容器被删除重建，数据也不会丢失

    environment:
      - 环境变量名=值
      # 一些软件的账号密码、初始配置，通过这种方式传进去

volumes:
  数据卷名:
  # 声明上面用到的数据卷，Docker 会自动创建对应的存储空间
EOF

第三步：启动

docker compose up -d
# 根据配置文件，拉取镜像并启动容器
# 如果本地没有对应镜像会自动下载；-d 表示在后台运行，不占用当前终端

docker compose ps
# 查看容器运行状态，确认是 Up（运行中）

第四步：防火墙放行端口（如果需要对外访问）

阿里云控制台 → 服务器详情页 →「防火墙」→「添加规则」，放行你在 ports 里设置的宿主机端口。

四、常用日常管理命令

docker compose ps
# 查看当前目录下项目的容器运行状态

docker compose logs 服务名 --tail 50
# 查看某个服务最近50行日志，排查问题时用

docker compose restart 服务名
# 仅修改了配置文件内容后，重启使其生效

docker compose up -d --force-recreate
# 强制重新创建容器，用于配置改了但 restart 没生效的情况
# （遇到过这种情况：改了端口映射，重启后没变化，用这条命令强制重建才生效）

docker compose down
# 停止并删除容器（数据卷不会被删除，重新 up -d 数据还在）

docker exec -it 容器名 bash
# 进入正在运行的容器内部，执行内部命令时用
# 有些软件要求用特定用户身份执行内部命令，格式如：
# docker exec -it 容器名 su 用户名 -s /bin/bash -c "具体命令"

五、实际踩过的坑与排查方法

坑一：改了端口配置，重启后不生效

现象：改完 docker-compose.yml 里的 ports，执行 docker compose up -d，但用 docker compose ps 或 docker compose port 检查，发现还是老端口，甚至端口列为空。

解决：

docker compose up -d --force-recreate
# 强制重新创建容器，确保新配置真正生效

坑二：容器内部端口和外部端口混淆，导致改端口后连不上

现象：把 ports: "8080:8080" 这样两边都改成新端口，结果容器状态显示 unhealthy，浏览器访问拒绝连接。

原因：容器内部监听的端口是软件自己写死的（比如 Halo 固定监听 8090，Nextcloud 内部固定用 80），只能改冒号左边（宿主机端口），右边必须保持软件原本的端口。

正确写法示例（把 Halo 外部访问端口改成 8080，但内部仍是8090）：

ports:
  - "8080:8090"

排查方法：

docker compose ps
# 观察 PORTS 这一列，如果显示类似 "8090/tcp"（没有 0.0.0.0: 前缀）单独列出，
# 说明这就是容器内部实际监听、但没有被正确映射到外部的端口

docker compose logs 服务名 --tail 50
# 查看容器日志，确认内部程序具体监听在哪个端口

坑三：vi 编辑文件时异常中断，再次打开报 swap file 冲突

现象：

E325: ATTENTION
Found a swap file by the name ".xxx.yml.swp"

原因：上次编辑时连接意外断开（比如服务器重启、网络波动），vi 没能正常清理临时缓存文件。

解决：出现选项提示时，按 D（Delete it），删除这个残留的临时文件，正常打开真正的配置文件（不影响已保存在磁盘上的原文件内容）。

坑四：Nextcloud 修改端口后，浏览器提示"通过不被信任的域名访问"

原因：Nextcloud 出于安全考虑，会记录"初始化设置时使用的访问地址"，换端口/换域名访问时，新地址不在信任名单里会被拒绝。

解决：进入容器内部，把新地址加入信任名单：

docker exec -it nextcloud-app-1 su www-data -s /bin/bash -c "php occ config:system:set trusted_domains 1 --value=新的IP或域名:端口"

⚠️ 这条命令必须在普通命令行下执行，不要在 vi 编辑器里粘贴（曾经误操作把这条命令粘贴进了配置文件里，导致文件内容错乱，需要用 :q! 强制退出不保存来恢复）。

坑五：cat 粘贴长文本（带中文注释）到配置文件，内容错位粘连

现象：用 cat > 文件名 << 'EOF' ... EOF 一次性粘贴大段带中文注释的配置内容时，个别行末尾的内容跟下一行开头粘连在一起，格式错乱。