告别命令行！Docker 部署 phpMyAdmin，轻松管理 MySQL

本文基于 library/phpmyadmin:5.2.3 与 library/mariadb:10.11，Ubuntu 24.04 实测。文末附登录、首页与库表结构等界面截图。

开发机上改个表、查条慢 SQL，很多人习惯敲 mysql 客户端：换一台电脑就要重装命令行工具，还要记清主机、端口、证书路径。装 Navicat、DBeaver 等桌面客户端省事一些，但授权、版本对齐、多人共用同一套连接配置又是另一套成本；笔记本离岗、VPN 断线，库还在机房里，工具却跟人不跟服务器。

更麻烦的是合规与内网：连接串、查询历史、导出文件若落在公有云「在线库管」，审计过不了；纯命令行又难把「建库、导 SQL、看权限」教给不熟终端的同学。团队真正需要的往往是：工具也跑在自己机器上、浏览器打开就能用、数据不出内网。

phpMyAdmin 正是为此而生的免费开源 MySQL / MariaDB Web 管理界面（PHP + 浏览器）：建库建表、执行 SQL、导入导出、管理用户权限，都在网页里完成。官方 Docker 镜像已进入 Docker Hub 官方库 library/phpmyadmin（短名 phpmyadmin），由 phpmyadmin/docker 维护——一条 Compose 就能把「库 + 管理台」拉起来，适合开发测试与内网运维自托管。

上手要点：phpMyAdmin 不是数据库本身，需连上已有 MySQL/MariaDB（本文用 Compose 一并拉起 MariaDB）。登录用的是 数据库用户名/密码，镜像没有独立「默认管理员账号」。容器内 Web 端口为 80，本文映射宿主机 8080；若挂载会话目录 /sessions，宿主机目录须 chown 33:33，否则会 Permission denied（见 FAQ）。

本文按「能跟做」写完整链路：用 轩辕镜像 加速拉取 library/phpmyadmin:5.2.3（Apache 变体）与 MariaDB，docker compose up -d 启动，浏览器登录后完成浏览库表与日常操作演示。另附单容器连已有库、生产注意与 FAQ。

镜像说明见 phpmyadmin 镜像页，标签列表见 tags。官方文档：docs.phpmyadmin.net；Docker Hub：phpmyadmin。

---

一、phpMyAdmin 是什么？

phpMyAdmin 面向「要用浏览器管 MySQL / MariaDB，又不想每人装桌面客户端」的场景：它是管理端，不是数据库服务器。

核心能力一览：

典型场景：

• 开发 / 测试环境用浏览器查库改表
• 内网运维统一入口，少装几个桌面客户端
• 与 MariaDB / MySQL 容器同 Compose 一键交付「库 + 管理界面」

与 DbGate 的区别：DbGate 是多引擎通用客户端；phpMyAdmin 专攻 MySQL / MariaDB，界面与生态更聚焦这一类库。

架构（本文 Compose 主路径）：

text
浏览器 ──HTTP:8080──▶ phpmyadmin 容器(:80, Apache)
                           │
                    Compose 网络
                           │
                      MariaDB(:3306)

版本与定位：本文使用 phpmyadmin:5.2.3（默认 apache 变体，开箱即访问）。生产请固定补丁版本；勿长期依赖裸 latest。fpm / fpm-alpine 仅适合已有独立 Web 服务器的场景，不是本文跟做主路径。

---

二、环境要求

bash
docker --version
docker compose version

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

更多见 轩辕镜像使用手册。

---

三、标签怎么选

标签列表：xuanyuan.cloud/r/library/phpmyadmin/tags。

---

四、拉取镜像（轩辕镜像加速）

bash
grep -q '"docker.xuanyuan.run"' ~/.docker/config.json && echo "已登录" || echo "未登录"
# 未登录时：
# docker login docker.xuanyuan.run

bash
sudo mkdir -p /www/wwwroot/phpmyadmin/{mysql,sessions}
# 会话目录必须让容器内 PHP（Debian apache 镜像多为 uid 33 / www-data）可写
sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions
cd /www/wwwroot/phpmyadmin

docker pull docker.xuanyuan.run/library/phpmyadmin:5.2.3
docker pull docker.xuanyuan.run/library/mariadb:10.11

实测拉取输出（Ubuntu 24.04）：

text
5.2.3: Pulling from library/phpmyadmin
...
Digest: sha256:b68f318c5fd85541795ed8eb4ced28ea6908a89910871783b3e479cc6c6d1e1b
Status: Downloaded newer image for docker.xuanyuan.run/library/phpmyadmin:5.2.3
docker.xuanyuan.run/library/phpmyadmin:5.2.3

text
10.11: Pulling from library/mariadb
...
Digest: sha256:be981e4113326ada8d6004174dd09eeaefc03094037f811182a52d4f2e737350
Status: Downloaded newer image for docker.xuanyuan.run/library/mariadb:10.11
docker.xuanyuan.run/library/mariadb:10.11

短名 docker.xuanyuan.run/phpmyadmin:5.2.3 与带 library/ 前缀通常等价；本文与同目录其他官方镜像文一致，统一写 library/phpmyadmin。

---

五、快速体验：Compose 一键起 MariaDB + phpMyAdmin

主路径：同一 Compose 网络内，phpMyAdmin 通过服务名 db 连接 MariaDB。

5.1 编写 compose.yml

bash
cd /www/wwwroot/phpmyadmin

将下面内容写入 compose.yml（务必把示例密码改成强密码）：

yaml
# /www/wwwroot/phpmyadmin/compose.yml
name: phpmyadmin

services:
  db:
    image: docker.xuanyuan.run/library/mariadb:10.11
    container_name: phpmyadmin-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ChangeMe_Root_Pass
      TZ: Asia/Shanghai
    volumes:
      - ./mysql:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10

  phpmyadmin:
    image: docker.xuanyuan.run/library/phpmyadmin:5.2.3
    container_name: phpmyadmin
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      PMA_HOST: db
      PMA_PORT: 3306
      UPLOAD_LIMIT: 64M
      TZ: Asia/Shanghai
    volumes:
      - ./sessions:/sessions:rw

参数说明：

密码提醒：文中 ChangeMe_Root_Pass 仅为示例。上线前必须修改；改密后需同步更新环境变量并重建相关容器（已有数据卷时勿随意改 root 策略，以免连不上）。

会话权限（必做）：sudo mkdir 出来的 sessions 属主往往是 root，而容器内 PHP 以 uid 33 写 /sessions。未 chown 时浏览器会报 session_start(): … Permission denied / path: /sessions。创建目录后执行：sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions。

5.2 启动与验证

bash
# 若尚未改过属主，启动前再确认一次
sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions

docker compose -f /www/wwwroot/phpmyadmin/compose.yml up -d
docker compose -f /www/wwwroot/phpmyadmin/compose.yml ps

期望：phpmyadmin-db 为 healthy / Up，phpmyadmin 为 Up，端口映射 0.0.0.0:8080->80/tcp。实测示例：

text
NAME            IMAGE                                          STATUS                    PORTS
phpmyadmin      docker.xuanyuan.run/library/phpmyadmin:5.2.3   Up …                      0.0.0.0:8080->80/tcp
phpmyadmin-db   docker.xuanyuan.run/library/mariadb:10.11      Up … (healthy)            3306/tcp

bash
docker compose -f /www/wwwroot/phpmyadmin/compose.yml logs --tail 50 phpmyadmin
curl -I http://127.0.0.1:8080

日志末尾可见 Apache 就绪（Apache/2.4… PHP/8.3… configured -- resuming normal operations）。AH00558: Could not reliably determine the server's fully qualified domain name 可忽略。实测 curl -I 返回 HTTP/1.1 200 OK。

浏览器打开：

text
http://你的服务器IP:8080

若页面直接报 Error during session start / Permission denied / path: /sessions，说明 ./sessions 属主不对（见下文 FAQ §9.1），先 chown 再刷新。

登录页填写：

phpMyAdmin 没有 独立默认账号；登不上请先核对 MariaDB 侧用户名密码与网络连通。

---

六、备选：单容器连已有库

已有 MySQL / MariaDB 时，不必再起 db 服务。

6.1 固定主机（PMA_HOST）

bash
sudo mkdir -p /www/wwwroot/phpmyadmin/sessions
sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions
docker rm -f phpmyadmin 2>/dev/null || true

docker run -d \
  --name phpmyadmin \
  --restart unless-stopped \
  -p 8080:80 \
  -e PMA_HOST=你的数据库主机或IP \
  -e PMA_PORT=3306 \
  -e TZ=Asia/Shanghai \
  -v /www/wwwroot/phpmyadmin/sessions:/sessions:rw \
  docker.xuanyuan.run/library/phpmyadmin:5.2.3

注意：phpMyAdmin 容器内的 localhost / 127.0.0.1 指向自己，不是宿主机。连宿主机上的库请用宿主机局域网 IP、host.docker.internal（需 Docker 支持）或 Compose 服务名。

6.2 登录页自填任意服务器（PMA_ARBITRARY=1）

适合临时连多台库、主机每次不同：

bash
sudo mkdir -p /www/wwwroot/phpmyadmin/sessions
sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions

docker run -d \
  --name phpmyadmin \
  --restart unless-stopped \
  -p 8080:80 \
  -e PMA_ARBITRARY=1 \
  -e TZ=Asia/Shanghai \
  -v /www/wwwroot/phpmyadmin/sessions:/sessions:rw \
  docker.xuanyuan.run/library/phpmyadmin:5.2.3

打开登录页后自行填写服务器地址、用户名与密码。

官方文档仍有 --link 示例；新环境请优先使用 Compose 自定义网络 / 服务名，勿再依赖已过时的 link 方式。

---

七、浏览器登录与基础使用

会话权限正常后，按下面三步熟悉界面（与 Ubuntu 实测截图一致）。

7.1 登录页：选语言、填 root 密码

打开 http://你的服务器IP:8080。将「语言」选为 中文 - Chinese simplified；「用户名」填 root，「密码」填 Compose 里 MYSQL_ROOT_PASSWORD 的值，点「登录」。

（本文 Compose 已设 PMA_HOST=db，登录页通常不再单独填服务器；若你用了 PMA_ARBITRARY=1，才会出现服务器输入框。）

7.2 首页：确认已连上 MariaDB

登录成功进入首页。右侧「数据库服务器」应类似：

左侧列出 information_schema、mysql、performance_schema、sys 等系统库。顶部有「数据库」「SQL」「导入」「导出」「用户账户」等入口。

页底若提示「高级功能尚未完全设置」：全新部署常见提示，不影响浏览库表、执行 SQL、导入导出；需要配置存储库时再查官方文档即可。

7.3 浏览库表与新建表

在左侧点击某个库（例如系统库 mysql，或你自己新建的业务库），进入「结构」页：可见表名、行数、引擎、排序规则、大小；每行有「浏览 / 结构 / 搜索 / 插入」等操作。

页面底部「新建数据表」：填写「数据表名」、字段数，点「创建」，即可开始建表。

日常路径建议：

1. 顶部「数据库」→「创建数据库」建自己的业务库（勿改乱系统库）
2. 点进该库 →「结构」→「新建数据表」
3. 顶部「SQL」粘贴语句执行；「导入」上传 .sql（大文件见 FAQ）

---

八、生产注意

SSL 连库时可设 PMA_SSL=1（多主机用 PMA_SSLS）。细节见 官方 Docker README。

---

九、常见问题 FAQ

9.1 打开页面报 session_start(): Permission denied / path: /sessions

未改属主时，浏览器会看到红色 phpMyAdmin - Error 页，关键句为 Permission denied (13) 与 path: /sessions：

挂载了宿主机 ./sessions，但目录属主是 root，容器内 PHP（uid 33）无法读写。Ubuntu 24.04 实测修复：

bash
sudo chown -R 33:33 /www/wwwroot/phpmyadmin/sessions
docker compose -f /www/wwwroot/phpmyadmin/compose.yml restart phpmyadmin

成功时 Compose 输出类似：

text
[+] Restarting 1/1
 ✔ Container phpmyadmin  Started

刷新浏览器应出现登录页（§7.1）。临时也可去掉 volumes 里的 sessions 挂载（会话仅保存在容器可写层，重建会丢）。官方 issue 亦提示检查 volume 权限：phpmyadmin/docker#226。

9.2 登录失败 / 连不上数据库

• 确认 PMA_HOST：Compose 内用服务名（本文 db）；连宿主机库勿填容器内的 localhost
• 核对用户名密码是否与 MariaDB / MySQL 一致
• docker compose logs db / phpmyadmin 查看拒绝原因（鉴权、未就绪、防火墙）

9.3 反代后样式错乱、空白页或跳转异常

设置环境变量 PMA_ABSOLUTE_URI 为浏览器实际访问的完整前缀（含协议与尾部 /）。

9.4 导入大 SQL 失败

增大限制后重建容器，例如：

yaml
environment:
  UPLOAD_LIMIT: 256M
  MEMORY_LIMIT: 512M
  MAX_EXECUTION_TIME: 600

9.5 端口 8080 已被占用

改映射，例如 "8081:80"，并相应改访问 URL。失败后先 docker compose down 再改端口启动。

9.6 浏览器打不开，容器却在跑

确认拉的是 apache 变体（5.2.3 / *-apache）。若误用 fpm / fpm-alpine，容器内没有对外 HTTP 80 的完整 Web 服务，需另接反向代理。

9.7 公网安全吗？

能登录 phpMyAdmin 通常就能操作数据库。公网必须加防护；开发机也建议仅监听内网或 SSH 隧道。

---

十、命令速查

bash
# 目录与启动
cd /www/wwwroot/phpmyadmin
docker compose -f /www/wwwroot/phpmyadmin/compose.yml up -d
docker compose -f /www/wwwroot/phpmyadmin/compose.yml ps
docker compose -f /www/wwwroot/phpmyadmin/compose.yml logs -f phpmyadmin

# 停止 / 删除容器（数据在 ./mysql，删容器不删卷目录）
docker compose -f /www/wwwroot/phpmyadmin/compose.yml down

# 拉取
docker pull docker.xuanyuan.run/library/phpmyadmin:5.2.3
docker pull docker.xuanyuan.run/library/mariadb:10.11

# 备份数据库目录（停库或短暂停写更稳妥）
tar -czf phpmyadmin-mysql-$(date +%F).tar.gz -C /www/wwwroot/phpmyadmin mysql

---

十一、延伸阅读

• 轩辕镜像页：library/phpmyadmin
• 标签列表：tags
• Docker Hub：phpmyadmin
• 源码 / Docker 说明：github.com/phpmyadmin/docker
• 用户文档：docs.phpmyadmin.net

---

总结

• phpMyAdmin = MySQL / MariaDB 的 Web 管理界面，不是数据库本身
• 推荐标签：5.2.3（apache）；轩辕镜像坐标：docker.xuanyuan.run/library/phpmyadmin:5.2.3
• 跟做主路径：Compose 起 MariaDB + phpMyAdmin，PMA_HOST=db，访问 8080
• 登录用 数据库账号；改掉示例密码，勿裸奔公网
• 已有库用 PMA_HOST 或 PMA_ARBITRARY=1；会话挂载 /sessions 时务必 chown 33:33