快速参考

• 由……维护： （注：原文中“Maintained by:”后面应该会有具体的维护者信息，若有完整内容，翻译会更加准确。这里仅根据给定的部分进行了翻译。）
  MariaDB 基金会，MariaDB 有限公司，以及我们社区的贡献

• 哪里可以获得帮助：
  数据库管理员（Stack Exchange），MariaDB 知识库（在此提问）。

还可查看 MariaDB 知识库中“获取 MariaDB 帮助”的文章。

支持的标签及各自的 Dockerfile 链接

• 11.6.1-ubi9-rc, 11.6-ubi9-rc, 11.6.1-ubi-rc, 11.6-ubi-rc

• 11.6.1-noble-rc, 11.6-noble-rc, 11.6.1-rc, 11.6-rc

• 11.5.2-ubi9, 11.5-ubi9, 11-ubi9, 11.5.2-ubi, 11.5-ubi, 11-ubi

• 11.5.2-noble, 11.5-noble, 11-noble, noble, 11.5.2, 11.5, 11, latest

• 11.4.3-ubi9, 11.4-ubi9, lts-ubi9, 11.4.3-ubi, 11.4-ubi, lts-ubi

• 11.4.3-noble, 11.4-noble, lts-noble, 11.4.3, 11.4, lts

• 11.2.5-jammy, 11.2-jammy, 11.2.5, 11.2

• 11.1.6-jammy, 11.1-jammy, 11.1.6, 11.1

• 10.11.9-ubi9, 10.11-ubi9, 10-ubi9, 10.11.9-ubi, 10.11-ubi, 10-ubi

• 10.11.9-jammy, 10.11-jammy, 10-jammy, 10.11.9, 10.11, 10

• 10.6.19-ubi9, 10.6-ubi9, 10.6.19-ubi, 10.6-ubi

• 10.6.19-focal, 10.6-focal, 10.6.19, 10.6

• 10.5.26-focal, 10.5-focal, 10.5.26, 10.5

快速参考（续）

• 在哪里提交问题：
  问题可在 https://jira.mariadb.org/ 上的“MDEV”项目和“Docker”组件下提交，或在 GitHub 上提交。

• 支持的架构：（更多信息）
  amd64, arm64v8, ppc64le, s390x

• 已发布的图像伪影细节：
  repo-info repo 的 repos/mariadb/ 目录（历史记录）
  （图像元数据、传输大小等）

• 图像更新：
  官方图像仓库的 library/mariadb 标签
  官方图像存储库的 library/mariadb 文件（历史记录）

• 此描述的来源：
  文档库的 mariadb/ 目录（历史记录）

什么是 MariaDB？

MariaDB 服务器是全球最受欢迎的数据库服务器之一。它由 MySQL 的原始开发者创建，并保证保持开源。著名的用户包括维基百科、星展银行（DBS Bank）和 ServiceNow。

其目的还在于保持与 MySQL 的高度兼容性，确保库二进制等效性以及与 MySQL API 和命令的精确匹配。MariaDB 开发人员继续开发新功能并提高性能，以更好地为其用户服务。

如何使用此图像

mariadb 有许多标签，值得注意的是 latest ，作为最新的稳定版本，以及 lts ，作为上一个长期支持版本发布。

运行容器

开始使用最小配置

使用此映像所需的环境变量涉及设置根用户密码：

$ docker run --detach --name some-mariadb --env MARIADB_ROOT_PASSWORD=my-secret-pw  mariadb:latest

或：

$ docker run --detach --name some-mariadb --env MARIADB_ALLOW_EMPTY_ROOT_PASSWORD=1  mariadb:latest

或：

$ docker run --detach --name some-mariadb --env MARIADB_RANDOM_ROOT_PASSWORD=1  mariadb:latest

...在那里容器日志将包含生成的根密码。

...通过 docker-compose 或 docker stack deploy

示例 docker-compose.yml 用于 mariadb ：

# Use root/example as user/password credentials
version: '3.1'

services:

  db:
    image: mariadb
    restart: always
    environment:
      MARIADB_ROOT_PASSWORD: example

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080

运行 docker stack deploy -c stack.yml mariadb （或 docker-compose -f stack.yml up ），等待其完全初始化，然后访问 http://swarm-ip:8080 、 http://localhost:8080 或 http://host-ip:8080 （视情况而定）。

使用用户、密码和数据库启动一个 mariadb 服务器实例

使用用户、密码和数据库启动 MariaDB 实例：

$ docker run --detach --name some-mariadb --env MARIADB_USER=example-user --env MARIADB_PASSWORD=my_cool_secret --env MARIADB_DATABASE=exmple-database --env MARIADB_ROOT_PASSWORD=my-secret-pw  mariadb:latest

在网络中启动一个 mariadb 服务器实例

当应用程序与 MariaDB 进行通信时，MariaDB 需要在与应用程序相同的网络中启动：

$ docker network create some-network 
$ docker run --detach --network some-network --name some-mariadb --env MARIADB_USER=example-user --env MARIADB_PASSWORD=my_cool_secret --env MARIADB_ROOT_PASSWORD=my-secret-pw  mariadb:latest
$ docker run --detach --network some-network --name some-application --env APP_DB_HOST=some-mariadb  --env APP_DB_USER=example-user --env APP_DB_PASSWD=my_cool_secret some-application

... 其中 some-network 是新创建的网络（不同于作为默认网络的 bridge ）， some-mariadb 是您想为容器指定的名称， my-secret-pw 是要为 MariaDB 根用户设置的密码。查看上面的列表，以找到符合您需求和环境的相关标签。 some-application 然后环境变量 APP_DB_HOST 、 APP_DB_USER 和 APP_DB_PASSWD 是应用程序针对其数据库连接的配置。

从 MariaDB 命令行客户端连接到 MariaDB

以下命令会启动另一个 mariadb 容器实例，并针对您原始的 mariadb 容器运行 mariadb 命令行客户端，使您能够针对您的数据库实例执行 SQL 语句：

$ docker run -it --network some-network --rm mariadb mariadb -hsome-mariadb -uexample-user -p

... 其中 some-mariadb 是您原始的 mariadb 容器（连接到 some-network Docker 网络）的名称。

此图像也可用作非 Docker 或远程实例的客户端：

$ docker run -it --rm mariadb mariadb --host <server container IP> --user example-user --password --database test

这将为您提供一个标准的 MariaDB 提示符。您可以通过以下方式进行测试：

MariaDB [(none)]> \s
--------------
client/mariadb  Ver 15.1 Distrib 10.6.16-MariaDB, for Linux (x86_64) using  EditLine wrapper

Connection id:      20
Current database:   test
Current user:       example-user@bark
SSL:            Not in use
Current pager:      stdout
Using outfile:      ''
Using delimiter:    ;
Server:         MariaDB
Server version:     10.6.16-MariaDB Source distribution
Protocol version:   10
Connection:     192.168.178.73 via TCP/IP
Server characterset:    latin1
Db     characterset:    latin1
Client characterset:    utf8mb3
Conn.  characterset:    utf8mb3
TCP port:       3306
Uptime:         6 min 4 sec

Threads: 1  Questions: 32  Slow queries: 0  Opens: 20  Open tables: 13  Queries per second avg: 0.087
--------------

...这将为您提供版本和连接信息。然后，您可以使用 exit 离开 MariaDB 命令行客户端和客户端容器。

有关 MariaDB 命令行客户端的更多信息可在 MariaDB 知识库：MariaDB 命令行客户端中找到。

容器外壳访问

docker exec 命令允许您在正在运行的容器内运行命令。以下命令行将在您的 mariadb 容器内为您提供一个 bash shell：

$ docker exec -it some-mariadb bash

MariaDB 备份

由于 MariaDB-Backup 与服务器版本高度耦合，在明确版本的 mariadb 容器中使用 mariadb-backup 可能会很有用：

$ docker run --volume /backup-volume:/backup --rm mariadb:10.6.15 mariadb-backup --help

容器查看 MariaDB 日志

该日志可通过 Docker 的容器日志获取：

$ docker logs some-mariadb

使用自定义的 MariaDB 配置文件

自定义配置文件应以 .cnf 结尾，并以只读方式挂载到 /etc/mysql/conf.d 目录。这些文件应包含您的应用程序/环境所需的、对 MariaDB 工作负载的最小更改。MariaDB 配置文件将有一个 [mariadb] 组，其后是每个设置服务器系统变量或选项前缀变量的 variable = value 设置。

mariadb 图像配置包含具有针对容器的两个自定义更改的 Ubuntu MariaDB 变量：

[host-cache-size=0](https://mariadb.com/kb/en/server-system-variables/#host_cache_size)
[skip-name-resolve](https://mariadb.com/kb/en/server-system-variables/#skip_name_resolve)

这些会禁用 user@hostname 用户的身份验证。要重新启用 skip-name-resolve ，将 disable-skip-name-resolve 用作变量或参数。启用后， host-cache-size 对于连接到 mariadb 的容器数量应该是足够的。

要查看您的 mariadb 容器的最终配置：

$ docker run --name some-mariadb -v /my/custom:/etc/mysql/conf.d --rm mariadb:latest my_print_defaults --mysqld

没有 cnf 文件的配置

许多配置选项可以作为标志传递给 mariadbd 。这将使您能够灵活地自定义容器，而无需 cnf 文件。例如，如果您想在 3808 端口上运行，只需运行以下命令：

$ docker run --name some-mariadb -e MARIADB_ROOT_PASSWORD=my-secret-pw -d mariadb:latest --port 3808

如果您想查看可用选项的完整列表，只需运行：

$ docker run -it --rm mariadb:latest --verbose --help

环境变量

当您启动 mariadb 图像时，可以通过在 docker run 命令行上传递一个或多个环境变量来调整 MariaDB 实例的初始化。请注意，如果您使用已经包含数据库的数据目录启动容器，则除 MARIADB_AUTO_UPGRADE 之外的所有变量都将不起作用。也就是说，在容器启动时，任何预先存在的数据库都将始终保持不变。

MARIADB_RANDOM_ROOT_PASSWORD 、 MARIADB_ROOT_PASSWORD_HASH 、 MARIADB_ROOT_PASSWORD 或 MARIADB_ALLOW_EMPTY_ROOT_PASSWORD （或包括 *_FILE 在内的等效项）中的一个是必需的。其他环境变量是可选的。

存在一长串环境变量，完整列表记录在 MariaDB 的知识库中：MariaDB 服务器 Docker 官方映像环境变量。

MARIADB_AUTO_UPGRADE

当设置此环境变量时，如果需要，将运行 mariadb-upgrade，以便对 MariaDB 系统表进行任何必要的更改，以启用新功能。这可能会妨碍一些降级选项。除非设置环境变量 MARIADB_DISABLE_UPGRADE_BACKUP ，否则将在数据目录的顶级位置创建系统表的备份，作为 system_mysql_backup_*.sql.zst ，以便在需要时协助降级。

秘密

作为通过环境变量传递敏感信息的替代方法，可将 _FILE 附加到先前列出的环境变量上，从而使初始化脚本从容器中存在的文件加载这些变量的值。特别是，这可用于从存储在 /run/secrets/<secret_name> 文件中的 Docker 机密中加载密码。例如：

$ docker run --name some-mysql -e MARIADB_ROOT_PASSWORD_FILE=/run/secrets/mariadb-root -d mariadb:latest

正在初始化数据库内容

当容器首次启动时，将使用指定名称创建一个新数据库，并使用提供的配置变量进行初始化。此外，它将执行在 /docker-entrypoint-initdb.d 中找到的扩展名为 .sh 、 .sql 、 .sql.gz 、 .sql.xz 和 .sql.zst 的文件。文件将按字母顺序执行。没有文件执行权限的 .sh 文件将被引用而不是执行。您可以通过将 SQL 转储挂载到该目录并提供具有贡献数据的自定义映像来轻松填充您的 mariadb 服务。默认情况下，SQL 文件将导入到由 MARIADB_DATABASE 变量指定的数据库中。

注意事项

数据存储于何处

重要提示：在 Docker 容器中运行的应用程序所使用的数据有几种存储方式。我们鼓励 mariadb 镜像的用户熟悉可用的选项，包括：

• 使用容器管理器的命名卷，通过利用其自身内部的卷管理将数据库文件写入主机系统的磁盘来管理数据库数据的存储。这是默认设置，对用户来说简便且相当透明。缺点是，对于直接在主机系统（即在容器之外）上运行的工具和应用程序，可能难以找到这些文件。
• 在主机系统（容器外部）上创建一个数据目录，并将其挂载到容器内部可见的目录。这样可以将数据库文件放置在主机系统上的已知位置，并且便于主机系统上的工具和应用程序访问这些文件。缺点是用户需要确保该目录存在，并且例如主机系统上的目录权限和其他安全机制已正确设置。

Docker 文档是了解不同存储选项和变体的良好起点，并且有多个博客和论坛帖子在该领域进行讨论并提供建议。在这里，我们将仅为上述后一种选项展示基本过程：

1. 在您的主机系统的合适卷上创建一个数据目录，例如 /my/own/datadir 。

2. 像这样启动您的 mariadb 容器：

   $ docker run --name some-mariadb -v /my/own/datadir:/var/lib/mysql:Z -e MARIADB_ROOT_PASSWORD=my-secret-pw -d mariadb:latest
   

命令的 -v /my/own/datadir:/var/lib/mysql:Z 部分将底层主机系统中的 /my/own/datadir 目录作为 /var/lib/mysql 挂载到容器内部，默认情况下 MariaDB 会将其数据文件写入此处。

在 MariaDB 初始化完成之前没有连接

如果容器启动时没有初始化数据库，那么将创建一个默认数据库。虽然这是预期的行为，但这意味着在初始化完成之前，它不会接受传入的连接。这可能会在使用自动化工具（例如 docker-compose ，它会同时启动多个容器）时引起问题。

健康/活性/就绪性检查

查看“官方图像”常见问题解答，了解为何没有默认的 HEALTHCHECK 指令。然而，您可以使用 healthcheck.sh 脚本从（非详尽的）测试列表中进行选择，以检查您认为的健康/活性/就绪情况。请参考 MariaDB 知识库：使用 Healthcheck.sh，了解如何使用它以及提供了哪些确切的测试。

针对现有数据库的使用情况

如果您使用已包含数据库（特别是 mysql 子目录）的数据目录启动 mariadb 容器实例，则不需要也不会检查控制初始化的环境变量，并且不会更改任何预先存在的数据库。唯一的例外是非默认的 MARIADB_AUTO_UPGRADE 环境变量，它可能会导致 mysql_upgrade / mariadb-upgrade 运行，这可能会更改系统表。

备份与恢复

在容器中，备份和恢复数据库也很重要。关于如何进行此操作的文档可以在 MariaDB 知识库：容器备份和恢复中找到。

常见问题 / 如何重置根用户和普通用户密码

此内容记录在 MariaDB 知识库：Docker 官方映像的常见问题解答中。

如何安装 MariaDB 插件

这在 MariaDB 知识库中有记录：向 Docker 官方镜像添加插件。

相关图像

• MariaDB MaxScale
• MariaDB 列存储

编写文件示例

使用此 mariadb 的示例撰写文件位于 https://github.com/MariaDB/mariadb-docker 中的 /examples 文件夹中。

许可证

查看此映像中所包含软件的许可证信息。

与所有 Docker 镜像一样，这些镜像可能还包含其他可能受其他许可证约束的软件（例如来自基础发行版的 Bash 等，以及所包含的主要软件的任何直接或间接依赖项）。

一些能够自动检测到的额外许可信息可能会在 repo-info 存储库的 mariadb/ 目录中找到。

对于任何预构建图像的使用，图像用户有责任确保对此图像的任何使用都符合其中包含的所有软件的任何相关许可。