PolarDB-X Docker 部署与登录实战：从拉取镜像到客户端连接

PolarDB-X Docker 部署与登录实战：从拉取镜像到客户端连接

本文将带你一步步完成 PolarDB-X 的 Docker 部署，并解决外部 IP 登录时遇到的"Access denied"权限问题，最终使用客户端工具顺利连接数据库。

背景

PolarDB-X 是阿里云推出的分布式关系型数据库，兼容 MySQL 协议。官方提供了 Docker 镜像，方便开发者快速搭建本地测试环境。本文使用的镜像版本为：

docker.io/polardbx/polardb-x:v2.4.2_5.4.19

在部署过程中，你可能会遇到这样一个典型问题：mysql 客户端在本地（127.0.0.1）可以登录，但从外部 IP（如局域网其他机器）登录时却提示 "Access denied" 。这是因为 PolarDB-X 保留了 polardbx_root 用户仅允许本地访问，我们需要创建新的管理用户来解决。

第一步：下载镜像

在终端中执行以下命令，拉取指定版本的 PolarDB-X 镜像：

docker pull polardbx/polardb-x:v2.4.2_5.4.19

如果网络状况良好，约几分钟后即可下载完成。可以通过 docker images 验证：

docker images | grep polardb-x

第二步：启动容器

使用以下命令启动一个 PolarDB-X 容器，并映射端口 8527：

docker run -d --name my-polardbx \
  -p 8527:8527 \
  polardbx/polardb-x:v2.4.2_5.4.19

参数说明：

• -d：后台运行
• --name：自定义容器名称
• -p 8527:8527：将宿主机的 8527 端口映射到容器的 8527 端口（PolarDB-X 的 MySQL 协议端口）

等待约 1-2 分钟，等待内部组件（CN、DN、GMS）完全启动。可通过 docker logs my-polardbx 查看启动日志。

第三步：使用命令行登录

本地登录（使用默认用户）

PolarDB-X 预置了 polardbx_root 用户，默认密码为 123456。在宿主机上执行：

mysql -h 127.0.0.1 -P 8527 -u polardbx_root -p123456

如果出现类似如下欢迎信息，说明登录成功：

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MySQL connection id is 59
Server version: 5.6.29 Tddl Server (ALIBABA)
...
MySQL [(none)]>

此时可以执行 show databases; 查看数据库列表。你会发现只有一个 information_schema，这是正常的，因为 PolarDB-X 没有创建示例数据库。

尝试从外部 IP 登录（会遇到权限问题）

假设你的容器宿主机 IP 为 127.0.0.1，现在从另一台机器（IP 127.0.0.1）执行：

mysql -h 127.0.0.1 -P 8527 -u polardbx_root -p123456

你可能会遇到如下错误：

ERROR 1045 (28000): Access denied for user 'polardbx_root'@'192.168.215.1' (using password: YES)

这是因为 polardbx_root 用户被系统保留，不允许从外部主机连接。直接执行 CREATE USER 'polardbx_root'@'%' 会触发错误：

ERROR 5107 (HY000): ... Can not modify polardbx_root since it is reserved for system

第四步：创建新用户以支持外部登录

我们需要创建一个新的管理员用户，并授予所有权限。

1. 使用本地方式登录（127.0.0.1）：

   mysql -h 127.0.0.1 -P 8527 -u polardbx_root -p123456

2. 在 MySQL 提示符下执行以下 SQL（将 your_password 替换为强密码）：

   -- 创建可以从任何 IP 连接的管理员用户
   CREATE USER 'admin'@'%' IDENTIFIED BY 'your_password';
   
   -- 授予所有权限
   GRANT ALL PRIVILEGES ON *.* TO 'admin'@'%' WITH GRANT OPTION;
   
   -- 刷新权限（可选）
   FLUSH PRIVILEGES;

3. 验证用户是否创建成功：

   SELECT user, host FROM mysql.user;

第五步：使用客户端工具登录

方法一：命令行客户端（外部 IP）

在外部机器（127.0.0.1）上执行：

mysql -h 127.0.0.1 -P 8527 -u admin -p

输入你设置的密码，即可成功登录。

方法二：图形化客户端（如 Navicat、DBeaver、DataGrip）

以 DBeaver 为例：

1. 新建 MySQL 连接。
2. 主机：127.0.0.1
3. 端口：8527
4. 用户名：admin
5. 密码：你设置的密码
6. 测试连接，应显示"成功"。

注意：PolarDB-X 完全兼容 MySQL 5.6/5.7 协议，因此任何支持 MySQL 的客户端都可以直接使用。

常见问题与解决方法

问题现象	可能原因	解决方案
docker: command not found	Docker 未安装	安装 Docker（参考 docs.docker.com）
容器启动后立即退出	内存不足（<12GB）	为 Docker 分配至少 12GB 内存
本地登录也失败	密码错误或容器未就绪	执行 docker logs my-polardbx 检查日志，默认密码为 123456
外部登录提示 Access denied	未创建外部用户	按照第四步创建 admin@'%' 用户
CREATE USER 报 ERROR 5107	试图修改保留用户	使用其他用户名，如 admin、dba 等
连接超时	防火墙阻止 8527 端口	开放防火墙：firewall-cmd --add-port=8527/tcp（Linux）或关闭 Windows 防火墙

总结

通过本文，你已经学会了：

• 下载 PolarDB-X Docker 镜像；
• 启动容器并映射端口；
• 使用 mysql 命令行从本地登录；
• 解决外部 IP 登录时的权限问题（创建新用户）；
• 使用图形化客户端连接 PolarDB-X。

现在，你可以在本地拥有一套完整的分布式数据库环境，用于开发、测试和学习。PolarDB-X 还支持水平扩展、分布式事务等高级特性，欢迎继续探索！

---

参考链接

• PolarDB-X 官方文档
• PolarDB-X Docker 部署指南

本文操作环境：CentOS 7.9，Docker 20.10.17，MySQL 客户端 8.0.28。如有差异请灵活调整。