MariaDB 教程 / 用 Docker Compose 创建持久化本地实验环境

Docker Compose 可以在一份 YAML 文件中定义 MariaDB 容器、连接端口与持久数据卷,便于建立独立学习环境。删除容器与删除数据卷的后果不同;应明确连接路径并实际查询保存的记录,不能把容器重建当作数据已经验证保留。

界定学习环境并检查 Docker 前提

Docker 在容器中运行业务进程,Compose 描述服务的运行配置。本例在电脑的 127.0.0.1:3307 提供数据库连接,容器内部 MariaDB 仍使用 3306,因此可与已占用本机 3306 的数据库并存。可结合本地与远程连接路径排查和独立备份的范围理解端口与数据保存。

按 Docker Compose 官方安装说明准备 Docker Desktop,或在适用平台准备 Engine 与 Compose 插件。Windows 使用 Linux 容器。先启动引擎,在终端确认下面两个命令可用,再进行数据库配置:

docker version
docker compose version

配置使用 mariadb:11.8 镜像系列。这个标签可能随补丁更新指向新的镜像;需要精确重现时记录经过批准的补丁标签或摘要。YAML 能被解析不等于镜像已经启动,启动、健康检查和数据卷保留都需要在实际 Docker 环境分别确认。

创建项目目录与两个独立密码文件

  1. 新建 mariadb-appops 文件夹,并在该目录打开终端。不要在无关 Compose 项目里运行本篇命令。
  2. 建立 secrets 子目录,分别创建 root-password.txt 与 app-password.txt。每个 UTF-8 文本文件只保存一个非空练习密码,两个密码不同,不写说明文字。
  3. 把下一节完整配置保存为 compose.yaml,并建立包含以下两行的 .gitignore。限制密码文件访问,避免提交到版本库。
secrets/
.env

Compose secrets 将文件提供给被指定的服务,并不把宿主机源文件变成加密密码库。需要同时保护文件和 Docker 操作权限。Compose secrets 文档说明了文件挂载与 Linux 容器条件。

理解完整的 Compose 配置

name: mariadb-appops
services:
  db:
    image: mariadb:11.8
    ports:
      - "127.0.0.1:3307:3306"
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/root_password
      MARIADB_DATABASE: appops_lab
      MARIADB_USER: app_user
      MARIADB_PASSWORD_FILE: /run/secrets/app_password
    secrets:
      - root_password
      - app_password
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
secrets:
  root_password:
    file: ./secrets/root-password.txt
  app_password:
    file: ./secrets/app-password.txt
volumes:
  db_data:

电脑上的客户端使用 127.0.0.1:3307,同一 Compose 网络中的其他服务使用 db:3306。在容器内,127.0.0.1 指向该容器自身,不能把它与宿主机回环地址混用。发布地址绑定到宿主机回环接口,限制本例数据库端口的外部暴露范围。

命名卷 db_data 挂载到 /var/lib/mysql 保存数据目录。密码通过 _FILE 变量读取指定 secrets 文件。根据官方镜像初始化变量说明,数据库、用户和密码创建作用于新的数据目录;已有初始化数据卷时,修改密码文件不会自动修改存储在数据库里的账户密码。

官方 healthcheck.sh 检查脚本可检查连接与 InnoDB 初始化。容器进程处于 running 不代表数据库已准备好处理练习 SQL,因此配置还定义了健康检查间隔、超时与初始化等待期。

启动服务并查询一条真实记录

在项目目录终端依次执行:

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=80 db

第一条检查 Compose 配置。确认服务最终成为 healthy;若未就绪,查看初始化日志。密码文件不存在时修正路径,端口被占用时选择可用宿主机端口并同步修改客户端连接,不要通过删卷代替排查。

docker compose exec db mariadb --default-character-set=utf8mb4 -u app_user -p appops_lab

在提示处输入 app-password.txt 中的密码。进入 MariaDB 客户端后执行以下完整 SQL,预期返回一条记录。建表仅用于首次运行;如已存在 docker_notes,先检查表和数据,不要直接重做初始化。

USE appops_lab;
CREATE TABLE docker_notes (
  note_id INT NOT NULL PRIMARY KEY,
  note_text VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO docker_notes VALUES (1, 'volume survives container replacement');
SELECT note_id, note_text FROM docker_notes;

预期 note_id 为 1,note_text 为原样的 volume survives container replacement。该英文字符串只是固定验证值,意为“数据卷在容器替换后保留”,需要通过后续重建试验确认,不能把这行文字本身当作持久化证明。

若宿主机安装了 MariaDB 客户端,可用下面的终端命令通过发布端口访问同一服务器。误用 3306 可能连接到另一台本地实例:

mariadb --protocol=tcp --host=127.0.0.1 --port=3307 --default-character-set=utf8mb4 -u app_user -p appops_lab

保留数据卷后替换容器,并再次查询

docker compose down
docker compose up -d

对于本配置,普通 down 会删除容器与项目网络,但保留命名数据卷。重新 up 后等健康检查通过,再用同一路径连接并执行 SELECT * FROM docker_notes;,应仍能读取编号 1 的原始字符串。只有重新查询到记录,才能确认当前项目确实挂载了预期数据。

docker compose down --volumes 还会删除声明的命名卷,可能丢失数据库内容,不能把它当作普通重启命令。只有确认这个项目的练习数据可丢弃时才考虑该操作。Compose down 官方参考列出了删除范围。

数据卷不是备份;重要内容仍需要单独保存与恢复验证。也不要以为换了文件夹后就一定使用另一份数据,本例显式固定项目名,应核对项目、端口与实际挂载卷。

先定位连接错误,再决定是否重新初始化

症状 检查项目
无法连接 Docker 引擎 Desktop 或 Engine 是否运行,Docker context 是否正确
发布端口被占用 宿主机 3307 是否空闲,改动后客户端是否同步更新
Access denied 实际初始化时的账户与密码,数据卷是否早已存在
容器运行但 SQL 不可用 健康状态、初始化日志、网络内 db 与宿主机地址的区别
重建后数据不符 项目名 mariadb-appops、工作目录、端口与挂载卷

不要把删除卷作为排错第一步。先确认实际连接的服务器与数据目录,再判断需要修正配置、恢复正确连接路径,还是在保留必要备份后有意重新初始化。