NAS新手必看：MariaDB实战入门与威联通套件及Docker部署全解析

December 1, 2025

在部署Docker应用时，我们经常会遇到需要配置数据库的情况。其中，MySQL / MariaDB、PostgreSQL以及一些轻量级项目使用的SQLite，是较为常见的选择。

Redis虽然在一些较新的项目中也会出现，但由于它不属于关系型数据库，本文将暂且不讨论。

根据官方文档进行一键部署通常并不困难。但当你希望多个应用共享同一个数据库，或者部署的多个应用都强依赖于数据库时，麻烦可能就随之而来了。本文旨在梳理和解决的，正是这部分在实际操作中可能遇到的挑战。

MariaDB作为MySQL的一个分支，有着其特殊性。它的特殊之处在于，在威联通（QNAP）NAS官方的App Center应用市场中，可以直接安装MariaDB的套件版本。这意味着许多用户在接触容器化应用之前，可能就已经先使用过它了。

正因如此，我打算从MariaDB开始写起，将其作为整个数据库系列文章的第一篇，希望能为新手用户提供一个清晰的入门指引。

⚠️ 重要声明：本文仅介绍基础的使用方法，目标是帮助你的项目成功连接并运行起来。文中涉及的所有部署代码均为演示目的，其可用性不作保证，请在生产环境中谨慎验证！

版本选择

在部署任何依赖数据库的应用时，首要步骤是仔细阅读该应用的官方文档。例如，下图展示了Photoview应用对数据库的支持情况，可以看到它默认推荐使用MariaDB的LTS（长期支持）版本，但并未强制要求具体的版本号，因此兼容性相对较高。

而另一个应用PhotoPrism则明确要求MariaDB版本必须大于等于10.5.12。

如果你使用的版本低于应用的要求，那么项目部署几乎注定会失败。

套件版 MariaDB

在威联通的应用商店中，通常提供两个MariaDB版本供选择：MariaDB 5 和 MariaDB 10。

两个版本的区别

MariaDB 5：这是一个相对陈旧的版本，主要目的是为了兼容一些遗留的旧应用（例如早期的内容管理系统或论坛程序）。这些旧应用可能依赖与新版本不完全匹配的数据库语法或特定功能。如果你的应用年代久远，并且官方文档明确要求使用MariaDB 5.x系列，那么你只能选择这个版本。

MariaDB 10：这是当前的主流版本，拥有更好的性能、更全面的功能以及更强的兼容性。绝大多数现代应用（如WordPress、Nextcloud、PhotoPrism等）在其官方说明中都会推荐使用MariaDB 10。因此，如果没有历史遗留应用的兼容性顾虑，直接选择MariaDB 10是明智之举。不过需要注意的是，应用商店提供的套件版本可能是v10.5.8，这已经是一个稍显落后的子版本。

如何启用套件版

首先，下载并安装 MariaDB 10 套件。其默认的端口号为 3307，我们可以根据需要进行修改。

在套件的“账户和数据库”设置界面中，“根密码”相当于超级管理员密码，建议将其重置为自己熟悉且安全的密码。“用户密码”则是指后续为各个独立数据库创建的访问账户的密码。

接着，你还需要下载安装名为 phpMyAdmin 的配套套件。通过它，我们可以使用网页界面以图形化的方式连接并管理数据库，这对于新手来说非常友好。

安装完成后，打开phpMyAdmin，会出现登录界面。用户名填写 root，密码填入上一步重置后的根密码。在服务器选项中，选择“MariaDB 10”。

登录成功后，你将进入phpMyAdmin的主管理界面。

在部署依赖MariaDB的项目之前，需要先为其创建一个专用的数据库和用户。如下图所示，点击“账户”选项卡，然后按箭头指示创建新账户。图中红框内是之前为“照片墙”应用创建的账户示例。

假设我们正在部署Emby，并且它必须绑定一个数据库才能完成初始化。

对于一般家庭用户，主要需要关注下图红框内的内容。用户名和密码通常习惯设置为与应用同名，例如 emby，当然你也可以完全自定义。主机名设置为 % 表示允许从任何主机连接，这符合大多数家庭网络的使用场景。“生成密码”功能会随机创建强密码，但个人不太喜欢使用。务必勾选「创建与用户同名的数据库并授予所有权限」选项，然后点击页面最下方的“执行”按钮。

“全局权限”部分保持默认（即不勾选任何选项），仅在数据库级别授予权限。这样做可以确保用户 emby 对系统库没有任何操作权限，只能管理其专属的数据库，更加安全。当然，如果你有特殊需求，也可以手动勾选启用如 SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX 等具体权限。

以上所有设置，在创建完成后仍然可以进行再次调整。

创建完毕后，你可以在列表中看到名为 emby 的数据库和对应的用户账户已经出现。至此，数据库端的准备工作已经完成，可以开始使用了。

部署应用并连接数据库

以上一篇部署的Photoview照片墙应用为例。

这里仅截取docker-compose配置文件中 environment 环境变量相关的部分。

- PHOTOVIEW_DATABASE_DRIVER=mysql
- PHOTOVIEW_MYSQL_URL=photoview:photoview@tcp(192.168.200.132:3307)/photoview

需要注意的是，这两项环境变量的名称由每个应用的开发者自定义，有自己的命名规范，因此务必提前查阅具体应用的使用文档。

第一项（驱动）：由于MariaDB是MySQL的分支，完全兼容MySQL的协议和客户端驱动，因此驱动部分应填写 mysql。

第二项（连接字符串）：格式为 用户名:密码@tcp(数据库服务器IP:端口)/数据库名。这意味着Photoview应用将使用用户 photoview 和密码 photoview，去连接位于你NAS上IP为 192.168.200.132、端口为 3307 的MariaDB 10服务，并最终使用名为 photoview 的数据库。将用户名、密码和数据库名设置为相同，虽然可能被视为一种“偷懒”的做法，但在个人使用场景下确实能带来极大的便利。

使用威联通的套件版MariaDB，在编写docker-compose的 yaml 配置文件时，可以省去部署数据库容器本身的步骤，配置得以精简，完成上述两项关键配置后基本就可以部署并使用了。

Docker版 MariaDB

独立部署MariaDB容器

部署MariaDB 10.6版本的示例配置如下：

services:
  mariadb:
    image: mariadb:10.6
    container_name: mariadbtest # 可自定义容器名
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=mypass  # 设置root用户的密码
    ports:
      - "3306:3306"           # 将容器内3306端口映射到宿主机3306端口，如无需外部访问可删除此行
    volumes:
      - /share/Container/mariadb:/var/lib/mysql  # 数据持久化存储目录

上方示例部署的是10.6版本，你也可以根据需求将镜像标签指定为 `mariadb:10.2` 或 `mariadb:10.5` 等有效版本。

默认情况下，MariaDB官方Docker镜像中的 root 用户要么没有密码，要么不允许直接登录。因此，必须通过环境变量 MYSQL_ROOT_PASSWORD 为其设置一个密码。

你还可以根据需要自行添加设置时区等其他环境变量，具体可参考MariaDB官方Docker镜像的文档。

请注意端口映射配置，左侧的宿主机端口是可以自定义的。

部署完成后，在容器管理界面点击该容器，然后选择“执行”命令。

这将进入容器的命令行界面。建议选择 /bin/bash 作为shell。然后输入以下命令：

# 以root身份登录MySQL，-p表示需要密码
mysql -uroot -p
# 输入之前通过环境变量设置的根密码，输入时不会显示字符，输完后按回车
# 创建名为photoview的数据库，如果不存在的话
CREATE DATABASE IF NOT EXISTS photoview;

# 创建一个用户名为‘photoview’、密码为‘photoview’的用户，并允许其从任何主机（‘%’）连接
# 单引号内的配置项，其含义与套件版中的设置是一一对应的
CREATE USER 'photoview'@'%' IDENTIFIED BY 'photoview';
# 授予该用户对photoview数据库的所有权限
GRANT ALL PRIVILEGES ON photoview.* TO 'photoview'@'%';
# 刷新权限，使设置立即生效
FLUSH PRIVILEGES;

输入 exit 命令退出root的MySQL会话。现在，我们可以使用新创建的用户账户登录刚创建的数据库，以验证创建成功。

mysql -uphotoview -pphotoview photoview

验证成功后，就可以重复上一节“套件版”中的步骤，在应用容器的环境变量中修改对应的数据库连接配置，然后启动应用容器。

与应用打包部署（一体化部署）

通常，一些应用的发布者会直接提供一个完整的 docker-compose.yml 文件，其中已经将应用本体和其依赖的数据库整合在了一起。你只需要简单修改几个变量（如密码、路径等），即可一键部署并启用整个应用栈。这就是常说的“开箱即用”。

这种方式确实非常省事。但从长远管理和资源利用的角度考虑，除非你确定后续不会再部署其他强依赖同类数据库的应用，否则不太推荐为每个应用都打包一个独立的数据库。这可能导致宿主机上运行多个相似的数据库实例，造成资源浪费。

尽管如此，这里仍提供一个Photoview应用与MariaDB数据库打包部署的示例代码，以供参考。

services:
  # 应用本体
  photoview:
    image: photoview/photoview:2
    container_name: photoview
    restart: unless-stopped
    ports:
      - "8797:80"  # 浏览器访问地址：http://你的NAS_IP:8797
    depends_on:
      mariadb:
        condition: service_healthy # 等待数据库健康检查通过后再启动应用
    environment:
      - TZ=Asia/Shanghai
      - PHOTOVIEW_DATABASE_DRIVER=mysql
      - PHOTOVIEW_MYSQL_URL=photoview:photoview@tcp(db:3306)/photoview # 注意这里使用容器名‘db’连接
      - PHOTOVIEW_LISTEN_IP=0.0.0.0
      # - MAPBOX_TOKEN=your_mapbox_token   # 可选配置
      # - PHOTOVIEW_VIDEO_HARDWARE_ACCELERATION=qsv  # 可选配置
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /share/Container/photoview:/home/photoview/media-cache
      - /share/Phone/picture:/photos:ro  # 你的照片目录

  # MariaDB 数据库
  mariadb:
    image: mariadb:10.6
    container_name: photoview-db
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=rootpassword   # 请更改为你自己的强密码
      - MYSQL_DATABASE=photoview           # 自动创建的数据库名
      - MYSQL_USER=photoview               # 自动创建的数据库用户名
      - MYSQL_PASSWORD=photoview           # 自动创建的数据库用户密码
    volumes:
      - /share/Container/photoview/mysql:/var/lib/mysql
    healthcheck: # 健康检查，确保数据库就绪后应用再启动
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

可以发现，与单独部署应用相比，上面的代码主要增加了数据库部分的定义。应用部分除了增加 depends_on 来定义容器启动顺序依赖外，几乎没有变化。healthcheck 部分用于对数据库容器进行健康检查，这是确保应用稳定启动的好实践。

应对多个应用数据库版本不兼容的情况

这是上一节情况的延伸。

假设一种场景：项目A仅支持MariaDB 10.5，而项目B仅支持MariaDB 10.6。如果你试图让它们共用同一个数据库实例，那么注定会有一个项目因为版本不兼容而报错，导致容器无法成功初始化。

对于普通用户来说，最稳妥的解决方案就是像上面演示的那样，采用“一体化部署”模式，即一个项目对应一个专属的数据库容器。这样能做到彻底的版本和环境隔离。

例如，项目A（Emby）使用MariaDB 10.5：

services:
  mariadb-emby:
    image: mariadb:10.5
    container_name: mariadb-emby
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=qnap1234
      - MYSQL_DATABASE=embyserver
      - MYSQL_USER=embyserver
      - MYSQL_PASSWORD=embyserver
    volumes:
      - /share/Container/mariadb/emby:/var/lib/mysql

项目B（Jellyfin）使用MariaDB 10.6：

  mariadb-jellyfin:
    image: mariadb:10.6
    container_name: mariadb-jellyfin
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=qnap1234
      - MYSQL_DATABASE=jellyfin
      - MYSQL_USER=jellyfin
      - MYSQL_PASSWORD=jellyfin
    volumes:
      - /share/Container/mariadb/jellyfin:/var/lib/mysql

在这种一体化部署的场景下，通常不需要将MariaDB容器的端口映射到宿主机。

因为应用容器和数据库容器之间会通过Docker网络，使用**容器名称 + 容器内部端口（默认3306）**进行通信。即使两个MariaDB容器内部都使用3306端口，由于它们在各自的容器网络命名空间中，也不会发生冲突。

只有在需要从宿主机（例如，使用本地的数据库管理工具）或家庭网络中的其他设备直接访问某个数据库时，才需要显式地映射端口，例如：

ports:
  - "3307:3306" # 将容器内3306映射到宿主机的3307端口

否则，请不要添加 ports 配置。这样处理最为简单，也能避免端口占用或配置错误的麻烦。

最后

我个人也是在自建博客之后才开始“被迫”学习使用数据库的，毕竟一点点积累起来的文章数据确实非常重要。

但对于NAS上的大多数轻量级应用，我个人的看法是：能不用数据库就尽量不用，或者优先考虑使用更轻量化的SQLite。因为除了学习成本较高之外，正如开篇提到的各种版本兼容性问题，也足以让人感到头疼。

以上就是关于在NAS上使用MariaDB的一些基础内容，希望能对你有所帮助。本文到此结束。