Ubuntu26.04 LTS 手把手教程｜Docker Compose V2 完整部署指南，多容器一键编排实战

前言

Ubuntu 26.04 LTS（Resolute Raccoon）正式落地后，Docker Compose V2 成为容器多服务部署标配工具。Docker Compose V2 以 CLI 插件形式集成在 Docker 内，摒弃老旧 V1 独立脚本 docker-compose，仅靠一份docker-compose.yml配置文件即可统一管理网站、数据库、缓存等多个容器，告别重复敲 docker run 命令。本文结合国内服务器网络环境，从前置准备、安装配置、语法详解、WordPress 实战、常用命令、版本区别、本土化排错 7 个维度完整教学，新手、运维均可直接抄作业。

一、部署前置条件

1. 系统：Ubuntu26.04 LTS，已完成 Docker CE 官方安装（文末附国内源快速安装命令）
2. 权限：当前普通用户加入docker用户组，免去每次输sudo执行 docker 指令

sudo usermod -aG docker $USER
newgrp docker # 立即生效权限

1. 基础：会使用 Linux 终端基础操作，掌握 nano/vim 简单编辑文件
2. 环境优化（国内必做：配置 Docker 镜像加速器，解决镜像拉取超时）

# 创建daemon.json配置国内镜像源（轩辕/1ms免费国内加速）
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://docker.xuanyuan.me","https://docker.1ms.run"]
}
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

配置后执行docker info，出现镜像地址即生效，大幅解决国内拉取 mysql、wordpress 镜像慢问题。

Compose V2 跟随 docker-compose-plugin 包安装，官方源安装 Docker 时可顺带一键安装。

Docker+Compose 一键安装（国内清华源）

# 安装依赖+添加docker清华软件源
sudo apt update && sudo apt install ca-certificates curl gnupg lsb-release -y
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 安装docker+compose插件
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y
# 验证compose安装
docker compose version

二、Docker Compose 核心语法详解（yml 配置模板，中文注释）

docker-compose.yml采用 YAML 格式，缩进必须用空格，禁止 Tab 制表符，冒号后务必带空格（新手高频报错点），整体由三大块：services（容器服务）、volumes（持久化数据卷）、networks（自定义网桥网络）组成。

# 服务列表：所有需要启动的容器配置
services:
  nginx-web: # 自定义服务名，容器间DNS可直接用这个名字互通
    image: nginx:alpine # 拉取的镜像名称
    container_name: web-nginx # 自定义容器名称
    restart: always # 重启策略：容器意外退出自动重启
    ports:
      - "8080:80" # 宿主机端口:容器内部端口
    environment: # 容器环境变量配置
      - NGINX_PORT=80
    volumes: # 数据挂载：命名卷/宿主机目录
      - html_data:/usr/share/nginx/html
    networks: # 接入自定义网桥
      - app_net

# 数据卷：容器删除数据不丢失，推荐生产使用命名卷而非宿主机绑定
volumes:
  html_data:

# 自定义网桥网络：同一网络内容器互通，隔离外部网络
networks:
  app_net:
    driver: bridge

关键知识点：同项目下容器可通过服务名直接访问，比如 db 服务，其他容器连接数据库地址直接写db:3306，无需填写 IP 地址。

三、实战项目：Docker Compose 一键部署 WordPress+MySQL8.0

本案例实现博客系统 + 数据库分离部署，数据卷持久化存储，国内服务器直接复制使用。

步骤 1：创建项目目录

mkdir ~/wp-project && cd ~/wp-project

步骤 2：编写 docker-compose.yml

nano docker-compose.yml

粘贴配置（密码自行修改，敏感密码推荐放到.env 文件，不硬编码进 yml）：

services:
  mysql-db:
    image: mysql:8.0
    container_name: wp-mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: Root@123456
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wpuser
      MYSQL_PASSWORD: Wp@654321
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - wp_net
    # 数据库健康检测：解决depends_on只等启动不等就绪的通病（国内部署高频坑）
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:latest
    container_name: wp-web
    restart: always
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: mysql-db # 直接使用上面数据库服务名通信
      WORDPRESS_DB_USER: wpuser
      WORDPRESS_DB_PASSWORD: Wp@654321
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html
    networks:
      - wp_net
    depends_on:
      mysql-db:
        condition: service_healthy # 等待数据库健康就绪再启动WP

volumes:
  db_data:
  wp_data:

networks:
  wp_net:
    driver: bridge

Ctrl+O保存回车，Ctrl+X退出 nano 编辑器。

步骤 3：后台启动整套服务

docker compose up -d

命令自动拉取镜像、创建网络、数据卷、后台启动两个容器。

步骤 4：查看运行状态 & 日志

# 查看运行容器
docker compose ps
# 实时查看日志，排错专用
docker compose logs -f

浏览器访问http://服务器IP:8080，进入 WordPress 安装界面即部署成功。

进阶优化：.env 环境变量隐藏密码（生产必备）

同目录新建.env文件，存放账号密码，yml 通过${变量名}读取，避免明文密码写在配置文件泄露：

# .env文件内容
DB_ROOT_PWD=Root@123456
DB_USER_PWD=Wp@654321

yml 内环境变量替换写法：

MYSQL_ROOT_PASSWORD: ${DB_ROOT_PWD}
MYSQL_PASSWORD: ${DB_USER_PWD}

执行docker compose config校验配置文件变量是否正常读取。

四、Docker Compose V2 高频命令速查表（中文释义）

表格

命令	功能说明	使用场景
docker compose up -d	后台创建并启动所有服务	首次部署 / 修改配置后重载
docker compose down	停止容器 + 删除容器、自定义网络（保留数据卷）	临时关停整套项目
docker compose ps	查看当前项目运行容器状态	巡检服务是否正常
docker compose logs -f	实时滚动输出容器日志	程序报错排查、启动异常定位
docker compose restart	重启已有容器，不修改配置	临时重启服务生效配置
docker compose exec 服务名 bash	进入指定容器终端	容器内部调试、数据库操作
docker compose pull	拉取最新镜像	升级容器版本
docker compose config	校验 yml 语法 + 变量解析	排查配置语法错误

⚠️ 重要区分：V2 新版空格写法 docker compose，老旧废弃 V1 是横杠docker-compose，Ubuntu26.04 禁止使用废弃 V1 命令。

五、V1（废弃）和 V2（现行）版本核心区别

1. 命令格式 V1（淘汰，Python 独立程序）：docker-compose up -d V2（Ubuntu26.04 默认，Go 原生插件）：docker compose up -d
2. 安装方式 V1 需要单独下载二进制 /pip 安装；V2 随 docker-compose-plugin 插件一同安装，集成 Docker CLI。
3. 性能：V2 启动速度更快、资源占用更低，原生适配新版 Docker 引擎特性。

六、国内 Ubuntu26.04 部署高频报错 + 本土化解决方案（原文扩充重点，国内用户专属）

1. 端口被占用（bind: address already in use）

报错：宿主机 8080 端口被 Nginx/Apache 占用

排查占用进程：sudo lsof -i :8080

方案：① 关停占用程序；② 修改 yml 端口映射"9090:80"，重新 docker compose up -d

2. WordPress 启动连不上 MySQL（数据库未初始化完成）

原因：depends_on仅控制启动顺序，不等待数据库初始化完成；

解决方案：上文 yml 添加 mysql 健康检查 + condition: service_healthy。

3. 目录挂载权限不足 Permission denied

场景：宿主机文件夹挂载到容器后读写报错

方案 1（测试）：对应服务添加privileged: true放开容器权限；

方案 2（生产规范）：修改宿主机目录权限chmod 775 目录名或统一 UID 映射。

4. 拉取镜像超时 / 连接 Docker Hub 失败

原因：国内直连官方仓库受限；

解决方案：前文已经配置国内镜像加速器，无效则替换镜像为 DaoCloud 国内镜像前缀：docker.m.daocloud.io/library/mysql:8.0。

5. YAML 语法报错：解析失败

90% 原因：缩进混用 Tab、冒号后缺少空格；用docker compose config一键校验配置文件语法错误。

七、补充 FAQ（本土化问答）

• 多个 compose 项目共存冲突吗？ 不会，Compose 默认以项目文件夹名称作为项目名，网络、卷、容器自动隔离，仅需保证宿主机端口不重复即可。
• 更新容器怎么操作？

docker compose pull #拉取最新镜像
docker compose up -d #自动重建更新的容器，不改动未更新服务

• down 和 start 区别？ docker compose down：删除容器和自定义网络；docker compose start：只启动已存在容器，不读取 yml 新配置。