前阵子做数据库迁移预研不想在云上反复建实例就在本地用 Docker 部署了一套 PolarDB-X一个下午把训练营里拆表、全局二级索引、分布式事务的动手实验全跑了一遍。整个过程踩了几个不小的坑今天从头到尾复盘一次给准备做 PolarDB-X 本地部署的同学当参考。这套流程不依赖云账号不产生按量计费只要电脑能跑 Docker 就能复现。如果你是正在参加 PolarDB 训练营的学员或是想在没有云资源的情况下体验分布式数据库的后端工程师这篇文章基本可以帮你把“本地部署 PolarDB-X”这个环节一次走通。我会把环境准备、部署步骤、首次连接、功能验证和故障排查串成一条完整链路并附上实战中容易忽略的细节。1. 为什么要把一套分布式数据库跑在本地PolarDB-X 是阿里云 PolarDB 分布式版的开源实现对外兼容 MySQL 协议和大部分 SQL 语法。它和你电脑上的单机 MySQL 有本质区别一个标准集群里有计算节点CN、数据节点DN、全局元数据服务GMS和变更捕获服务CDC。CN 负责接收 SQL、生成分布式执行计划DN 负责实际落盘存储GMS 维护全局元数据和事务状态CDC 负责捕获 binlog 供下游消费。这种架构让它可以做到水平扩展、分布式事务、全局二级索引和透明分片。但在训练营或日常学习中很多人面临同一个问题想用分布式数据库得先有云上实例。申请云资源要等审批、要盯着计费、要维护白名单这对一个只想验证 SQL 行为或跑通实验的人来说太重了。本地部署刚好把门槛拉低到“一台笔记本 Docker”。具体能解决什么问题我总结了三点学习验证训练营里的拆分键选择、全局二级索引、广播表等实验不需要真实集群也能做本地实例足以复现核心行为。开发联调后端程序直接连本地 3306 端口像使用 MySQL 一样调试 SQL不用频繁改连接串。迁移预研评估业务迁移到分布式数据库的可行性时先本地跑一版真实环境比看文档猜行为高效得多。这里顺便说一句本地部署 PolarDB-X 的思路和最近很火的“本地部署大模型”其实是同一类诉求把原本依赖平台侧的资源拉到个人电脑上换来即时性、可控性和低成本。差别只是 PolarDB-X 拉起来的是一个数据库服务而不是一个推理服务。但也要说清楚边界本地单机容器只是功能级验证环境不代表真实集群的性能。CN、DN、GMS 都跑在同一台机器上网络开销、磁盘 IO 和真实多节点集群完全不同。所以本地部署适合做“这个功能是否支持、这个 SQL 行为是否符合预期”这类验证不适合出性能压测报告。2. 部署前必须完成的三项检查资源、端口、镜像2.1 硬件基线两台机器的真实体感我在一台 8 核 16G 的 Linux 工作站和一台 4 核 8G 的 MacBook Pro 上都跑过。结论是CPU 2 核勉强能启动4 核比较舒服内存建议至少 8GDocker Desktop 要给到 5G 以上磁盘预留 20G 可用空间比较稳因为镜像加数据卷大概要占 8~10G。如果你电脑上已经跑着其他服务比如本地装了 Ollama、Dify 之类的容器注意叠加内存占用。我一度在同时运行三个容器组的情况下拉起 PolarDB-X结果引擎节点反复重启后来才发现是内存不够。2.2 端口冲突排查别让本地 MySQL 抢了 3306PolarDB-X 兼容 MySQL 协议默认连接端口就是 3306。本地如果已经装了 MySQL、Redis 或其他服务占用 3306部署后会出现端口映射失败。启动前先检查端口占用lsof -i :3306 # 或者 netstat -an | grep 3306如果 3306 被占最简单的办法是修改 compose 文件里的端口映射比如把宿主机端口改成 33061容器内端口保持 3306 不变。表里面的默认端口参考如下具体以你拉取的 compose 文件为准端口对应服务用途3306polardbx-sqlCNMySQL 协议连接入口8080GMS / 管理面元数据与运维接口8081CDC 相关变更订阅管理9090调试接口一般不对公网开放2.3 镜像与客户端准备减少启动等待时间PolarDB-X 本地部署需要拉取几个镜像体积加起来有几 GB。第一次执行docker compose up -d时拉镜像的时间可能比初始化时间还长。建议先手动拉取避免启动过程在超时边缘反复横跳docker pull polardbx/polardb-x:latest docker pull polardbx/polardbx-engine:latest如果你之前跑本地大模型工具时已经配置过 Docker 镜像加速这里同样生效没配置过的话多等一会儿也能拉完但网络不稳定时容易出现中断。客户端方面宿主机装一个 MySQL 客户端最省事。macOS 可以用brew install mysql-clientLinux 用系统包管理器装mysql-client或mariadb-client。没有也没关系后面会讲用容器内客户端连接的替代方案。3. 拉起实例Docker Compose 全流程实操3.1 获取官方 QuickStart 模板PolarDB-X 开源社区维护了一个部署项目里面包含了通过 Docker Compose 快速拉起单机实例的模板。先把它克隆下来git clone https://github.com/polardb/polardbx-operator.git cd polardbx-operator/quickstart进入quickstart目录后你会看到一个docker-compose.yml文件。这个文件就是整套部署的核心它替你编排好了 CN、DN、GMS 等组件的启动顺序和依赖关系。3.2 先看懂 compose 里的组件角色第一次看到 compose 文件里定义了四五个服务可能会有点慌。其实不需要每个都深究你只需要抓住两类角色第一类是polardbx-engine对应 DN 数据节点。它负责真实的数据存储基于兼容 MySQL 的存储引擎实现底层和 InnoDB 打交道。第二类是polardbx-sql对应 CN 计算节点。你通过 MySQL 协议连接的就是它SQL 解析、优化、执行计划分发都在这里完成。GMS 的元数据能力在 QuickStart 单机模式下通常合并到 CN 进程中CDC 服务如果有独立容器则是负责 binlog 捕获的组件。理解这些角色的意义在于排查问题的时候能定位到日志。比如连接失败大概率要去看polardbx-sql的日志数据写入报错重点看polardbx-engine的日志。不要一上来就docker logs 全容器名挨个翻先想清楚是哪个组件出了问题。3.3 启动、等待与确认就绪在quickstart目录下执行docker compose up -d启动后查看容器状态docker compose ps刚启动时部分服务可能还在初始化状态会从starting慢慢变成Up。几秒内变成Up不代表可以连了CN 节点需要完成元数据初始化和分片映射构建这个过程通常需要 1 到 3 分钟。判断是否初始化完成看日志比看状态更可靠docker compose logs -f polardbx-sql当日志中出现类似ready、successfully、password is这类关键词时说明 CN 已经对外提供服务了。如果你看到容器反复重启多半是资源不足或者端口冲突不要反复up -d先把上一套环境清干净docker compose down -v docker compose up -ddown -v会连数据卷一起删掉相当于彻底重置环境。排障阶段这是最有效的重置手段损失就是之前写入的实验数据全部清空。4. 第一次连接从日志里挖出初始密码4.1 初始账号密码的两种来源PolarDB-X 本地实例默认账号通常是polardbx_root。密码的获取方式有两种一种是在 compose 文件的environment段落里显式配置了比如POLARDBX_PASSWORD这样的环境变量另一种是系统随机生成然后打印到容器日志里。我先说通用做法把 CN 容器日志里所有跟密码相关的行捞出来。docker compose logs polardbx-sql | grep -i password如果日志里有一行类似Root password: xxxxxx或者random password: xxxxxx那就是你需要的初始密码。如果你在启动前手动改了 compose 文件设置了自定义密码环境变量那就直接用你设置的值没必要再去翻日志。4.2 连接命令与常见报错拿到密码后用 MySQL 客户端连接mysql -h127.0.0.1 -P3306 -upolardbx_root -p输入密码后就进入了 MySQL 命令行。建议先执行一句确认版本SELECT VERSION();看到版本号里包含类似TDDL或PolarDB-X的标识说明连接的是 CN 节点而不是本机残留的某个 MySQL 服务。宿主机没有 MySQL 客户端时可以直接进 CN 容器执行docker exec -it polardbx-sql容器名 mysql -h127.0.0.1 -P3306 -upolardbx_root -p连接失败的高频原因有三个。第一宿主机端口映射没生效确认你连的端口和 compose 里ports段一致。第二密码包含$、!等特殊字符在命令行里需要转义最省事的方式是用环境变量传密码MYSQL_PWDxxxx mysql -h127.0.0.1 -P3306 -upolardbx_root。第三host 写成了localhost某些客户端会走 unix socket从而连不到 TCP 端口这里必须明确写127.0.0.1。5. 部署成功只是开始拆表、GSI 和事务验证5.1 建一个带拆分键的逻辑表PolarDB-X 里你创建的数据库是“逻辑库”它可能对应底层多个物理分片。我们建一个业务库然后创建一张按用户维度拆分的订单表CREATE DATABASE app_db DEFAULT CHARACTER SET utf8mb4; USE app_db; CREATE TABLE t_order ( id BIGINT NOT NULL AUTO_INCREMENT, user_id BIGINT NOT NULL, order_no VARCHAR(64) NOT NULL, amount DECIMAL(12,2) NOT NULL, PRIMARY KEY (id, user_id) ) ENGINE InnoDB DEFAULT CHARSET utf8mb4 PARTITION BY HASH(user_id) PARTITIONS 4;这里的关键是最后一行PARTITION BY HASH(user_id) PARTITIONS 4。意思是根据user_id做哈希把数据分散到 4 个分片里。PARTITIONS 4的数字可以根据实际场景调整如果未来数据量增长还可以通过扩分片来扩容。这里有个容易踩的坑拆分键必须包含在主键中或者作为主键的一部分。我第一次建表时用PRIMARY KEY (id)结果报错原因很简单——分布式表的主键需要能定位到具体分片如果主键只有id而拆分键是user_id系统无法根据主键快速计算出数据在哪个分片。把主键改成(id, user_id)后问题就解决了。如果有一些字典类的小表不想拆成多份可以使用广播表CREATE TABLE t_dict ( dict_code VARCHAR(32) NOT NULL, dict_value VARCHAR(128), PRIMARY KEY (dict_code) ) BROADCAST;广播表会在每个分片上都复制一份完整数据适合配置类、字典类的小表这样在 JOIN 时可以避免跨分片数据传输。5.2 用 EXPLAIN 观察数据路由和执行计划建完表后插入几条测试数据INSERT INTO t_order (id, user_id, order_no, amount) VALUES (1, 101, 20250101001, 99.00), (2, 102, 20250101002, 199.00), (3, 201, 20250101003, 299.00);然后分别用两种方式查询观察执行计划的差异EXPLAIN SELECT * FROM t_order WHERE user_id 101; EXPLAIN SELECT * FROM t_order WHERE order_no 20250101001;第一条查询带了拆分键user_id系统可以通过哈希计算直接定位到具体分片执行计划会显示命中单个分片。第二条查询只带order_no不带拆分键CN 无法确定数据在哪个分片只能把请求发给所有分片也就是全分片扫描。这个对比非常直观地解释了为什么分布式数据库要求业务 SQL 尽量带拆分键。很多慢查询问题本质上都是“看似走了索引实际扫了全部分片”。5.3 全局二级索引给非拆分键查询提速既然order_no查询会全分片扫能不能给它也建一个索引在单机 MySQL 里建普通索引就行但在 PolarDB-X 里不行。因为索引如果和主表一样只存在某个分片那用索引去查同样不知道去哪个分片找。这时候需要的是全局二级索引GSI。它本质上是另一张分布式的索引表索引列作为新的拆分键独立分片CREATE GLOBAL INDEX idx_order_no ON t_order(order_no) PARTITION BY HASH(order_no) PARTITIONS 4;再次执行之前的 EXPLAINEXPLAIN SELECT * FROM t_order WHERE order_no 20250101001;这次执行计划会走 GSI 的分片先根据order_no哈希找到对应索引分片再回表取完整数据。训练营课程里常说的“用 GSI 解决非拆分键查询”就是这个原理。GSI 的同步是异步的写主表后索引更新有一点延迟。本地实验时感觉不明显但在高并发写入场景下需要在一致性和性能之间做取舍。5.4 分布式事务的快速验证PolarDB-X 支持分布式事务这也是落地场景中最受关注的能力。用一个简单的账户转账来验证CREATE TABLE t_account ( account_id BIGINT NOT NULL, balance DECIMAL(12,2) NOT NULL, PRIMARY KEY (account_id) ) PARTITION BY HASH(account_id) PARTITIONS 4; INSERT INTO t_account VALUES (1, 1000.00), (2, 1000.00); START TRANSACTION; UPDATE t_account SET balance balance - 100 WHERE account_id 1; UPDATE t_account SET balance balance 100 WHERE account_id 2; COMMIT;如果account_id1和account_id2哈希到了不同分片这条事务就是真正的跨分片分布式事务。CN 在这里承担协调者角色需要协调两个 DN 分片完成提交。本地实验观察到的结果和单机 MySQL 很相似都是一句 COMMIT 结束但背后多了一层协调逻辑。要注意的是单机部署无法验证真正的故障恢复行为比如网络分区、节点宕机时的事务状态如何处理。这类场景需要多机集群才能模拟本地部署只适合验证基本功能。6. 本地实例的日常维护与高频故障排查6.1 生命周期管理起停、重置与清理日常开发中不需要一直开着整套实例。资源紧张时可以先停掉docker compose stop下次要用再启动docker compose start如果想把数据彻底清掉恢复到刚部署的状态docker compose down -v-v参数会删除数据卷这一点要特别注意。数据卷里存的是 DN 节点的物理数据和 GMS 的元数据删了就真的没了。想保留数据做长期开发就不要随便加-v。容器日志会持续增长本地实验阶段倒不用太在意但如果长时间跑着建议给 Docker 的 log 配置加个大小限制比如在daemon.json里设置max-size100m避免日志文件把磁盘塞满。6.2 四个高频问题的排查链路我在实际操作中遇到过几类问题整理成排查思路供参考。第一类是连接不上 3306。先docker compose ps看端口映射是否正常再确认宿主机端口有没有被其他进程占用。很多时候是本地 MySQL 还在跑把宿主机映射端口改掉就能解决。第二类是容器反复重启。先看日志里有没有内存分配失败或磁盘不足的报错。Docker Desktop 的默认内存配额经常不够用把它调到 6G 或更高然后重启 Docker问题通常会消失。第三类是密码明明在日志里找到了却一直提示认证失败。检查一下 compose 文件里有没有配置环境变量密码如果配置了日志里打印的随机密码就是无效的要用配置的密码。第四类是 M1/M2 芯片的 Mac 上启动失败。PolarDB-X 官方镜像以 x86_64 为主Apple Silicon 上需要依赖模拟层运行建议开启 Docker Desktop 的 Rosetta 模拟选项再试。如果不行最省事的方案是换一台 x86 的 Linux 机器跑这套环境。还有一个排查顺序的问题不要一上来就怀疑镜像有问题。先看宿主机资源再看容器状态最后看对应组件日志按这个链路排查效率最高。我自己现在每次部署完都会顺手做三件事记下当前版本的初始密码把 3306 的映射端口写进项目的 README再把建库、拆表、GSI、事务验证的 SQL 存成一个脚本。这样下次重置环境后一条命令就能把功能验证跑完。本地部署 PolarDB-X 的价值不在于“跑起来”这个动作而在于跑起来之后你能反复实验、随意改动、再快速重置这种低成本试错的机会才是训练营和日常学习中真正珍贵的东西。 PolarDB-X 本地部署实战：用 Docker 跑通分布式数据库全流程
前阵子做数据库迁移预研不想在云上反复建实例就在本地用 Docker 部署了一套 PolarDB-X一个下午把训练营里拆表、全局二级索引、分布式事务的动手实验全跑了一遍。整个过程踩了几个不小的坑今天从头到尾复盘一次给准备做 PolarDB-X 本地部署的同学当参考。这套流程不依赖云账号不产生按量计费只要电脑能跑 Docker 就能复现。如果你是正在参加 PolarDB 训练营的学员或是想在没有云资源的情况下体验分布式数据库的后端工程师这篇文章基本可以帮你把“本地部署 PolarDB-X”这个环节一次走通。我会把环境准备、部署步骤、首次连接、功能验证和故障排查串成一条完整链路并附上实战中容易忽略的细节。1. 为什么要把一套分布式数据库跑在本地PolarDB-X 是阿里云 PolarDB 分布式版的开源实现对外兼容 MySQL 协议和大部分 SQL 语法。它和你电脑上的单机 MySQL 有本质区别一个标准集群里有计算节点CN、数据节点DN、全局元数据服务GMS和变更捕获服务CDC。CN 负责接收 SQL、生成分布式执行计划DN 负责实际落盘存储GMS 维护全局元数据和事务状态CDC 负责捕获 binlog 供下游消费。这种架构让它可以做到水平扩展、分布式事务、全局二级索引和透明分片。但在训练营或日常学习中很多人面临同一个问题想用分布式数据库得先有云上实例。申请云资源要等审批、要盯着计费、要维护白名单这对一个只想验证 SQL 行为或跑通实验的人来说太重了。本地部署刚好把门槛拉低到“一台笔记本 Docker”。具体能解决什么问题我总结了三点学习验证训练营里的拆分键选择、全局二级索引、广播表等实验不需要真实集群也能做本地实例足以复现核心行为。开发联调后端程序直接连本地 3306 端口像使用 MySQL 一样调试 SQL不用频繁改连接串。迁移预研评估业务迁移到分布式数据库的可行性时先本地跑一版真实环境比看文档猜行为高效得多。这里顺便说一句本地部署 PolarDB-X 的思路和最近很火的“本地部署大模型”其实是同一类诉求把原本依赖平台侧的资源拉到个人电脑上换来即时性、可控性和低成本。差别只是 PolarDB-X 拉起来的是一个数据库服务而不是一个推理服务。但也要说清楚边界本地单机容器只是功能级验证环境不代表真实集群的性能。CN、DN、GMS 都跑在同一台机器上网络开销、磁盘 IO 和真实多节点集群完全不同。所以本地部署适合做“这个功能是否支持、这个 SQL 行为是否符合预期”这类验证不适合出性能压测报告。2. 部署前必须完成的三项检查资源、端口、镜像2.1 硬件基线两台机器的真实体感我在一台 8 核 16G 的 Linux 工作站和一台 4 核 8G 的 MacBook Pro 上都跑过。结论是CPU 2 核勉强能启动4 核比较舒服内存建议至少 8GDocker Desktop 要给到 5G 以上磁盘预留 20G 可用空间比较稳因为镜像加数据卷大概要占 8~10G。如果你电脑上已经跑着其他服务比如本地装了 Ollama、Dify 之类的容器注意叠加内存占用。我一度在同时运行三个容器组的情况下拉起 PolarDB-X结果引擎节点反复重启后来才发现是内存不够。2.2 端口冲突排查别让本地 MySQL 抢了 3306PolarDB-X 兼容 MySQL 协议默认连接端口就是 3306。本地如果已经装了 MySQL、Redis 或其他服务占用 3306部署后会出现端口映射失败。启动前先检查端口占用lsof -i :3306 # 或者 netstat -an | grep 3306如果 3306 被占最简单的办法是修改 compose 文件里的端口映射比如把宿主机端口改成 33061容器内端口保持 3306 不变。表里面的默认端口参考如下具体以你拉取的 compose 文件为准端口对应服务用途3306polardbx-sqlCNMySQL 协议连接入口8080GMS / 管理面元数据与运维接口8081CDC 相关变更订阅管理9090调试接口一般不对公网开放2.3 镜像与客户端准备减少启动等待时间PolarDB-X 本地部署需要拉取几个镜像体积加起来有几 GB。第一次执行docker compose up -d时拉镜像的时间可能比初始化时间还长。建议先手动拉取避免启动过程在超时边缘反复横跳docker pull polardbx/polardb-x:latest docker pull polardbx/polardbx-engine:latest如果你之前跑本地大模型工具时已经配置过 Docker 镜像加速这里同样生效没配置过的话多等一会儿也能拉完但网络不稳定时容易出现中断。客户端方面宿主机装一个 MySQL 客户端最省事。macOS 可以用brew install mysql-clientLinux 用系统包管理器装mysql-client或mariadb-client。没有也没关系后面会讲用容器内客户端连接的替代方案。3. 拉起实例Docker Compose 全流程实操3.1 获取官方 QuickStart 模板PolarDB-X 开源社区维护了一个部署项目里面包含了通过 Docker Compose 快速拉起单机实例的模板。先把它克隆下来git clone https://github.com/polardb/polardbx-operator.git cd polardbx-operator/quickstart进入quickstart目录后你会看到一个docker-compose.yml文件。这个文件就是整套部署的核心它替你编排好了 CN、DN、GMS 等组件的启动顺序和依赖关系。3.2 先看懂 compose 里的组件角色第一次看到 compose 文件里定义了四五个服务可能会有点慌。其实不需要每个都深究你只需要抓住两类角色第一类是polardbx-engine对应 DN 数据节点。它负责真实的数据存储基于兼容 MySQL 的存储引擎实现底层和 InnoDB 打交道。第二类是polardbx-sql对应 CN 计算节点。你通过 MySQL 协议连接的就是它SQL 解析、优化、执行计划分发都在这里完成。GMS 的元数据能力在 QuickStart 单机模式下通常合并到 CN 进程中CDC 服务如果有独立容器则是负责 binlog 捕获的组件。理解这些角色的意义在于排查问题的时候能定位到日志。比如连接失败大概率要去看polardbx-sql的日志数据写入报错重点看polardbx-engine的日志。不要一上来就docker logs 全容器名挨个翻先想清楚是哪个组件出了问题。3.3 启动、等待与确认就绪在quickstart目录下执行docker compose up -d启动后查看容器状态docker compose ps刚启动时部分服务可能还在初始化状态会从starting慢慢变成Up。几秒内变成Up不代表可以连了CN 节点需要完成元数据初始化和分片映射构建这个过程通常需要 1 到 3 分钟。判断是否初始化完成看日志比看状态更可靠docker compose logs -f polardbx-sql当日志中出现类似ready、successfully、password is这类关键词时说明 CN 已经对外提供服务了。如果你看到容器反复重启多半是资源不足或者端口冲突不要反复up -d先把上一套环境清干净docker compose down -v docker compose up -ddown -v会连数据卷一起删掉相当于彻底重置环境。排障阶段这是最有效的重置手段损失就是之前写入的实验数据全部清空。4. 第一次连接从日志里挖出初始密码4.1 初始账号密码的两种来源PolarDB-X 本地实例默认账号通常是polardbx_root。密码的获取方式有两种一种是在 compose 文件的environment段落里显式配置了比如POLARDBX_PASSWORD这样的环境变量另一种是系统随机生成然后打印到容器日志里。我先说通用做法把 CN 容器日志里所有跟密码相关的行捞出来。docker compose logs polardbx-sql | grep -i password如果日志里有一行类似Root password: xxxxxx或者random password: xxxxxx那就是你需要的初始密码。如果你在启动前手动改了 compose 文件设置了自定义密码环境变量那就直接用你设置的值没必要再去翻日志。4.2 连接命令与常见报错拿到密码后用 MySQL 客户端连接mysql -h127.0.0.1 -P3306 -upolardbx_root -p输入密码后就进入了 MySQL 命令行。建议先执行一句确认版本SELECT VERSION();看到版本号里包含类似TDDL或PolarDB-X的标识说明连接的是 CN 节点而不是本机残留的某个 MySQL 服务。宿主机没有 MySQL 客户端时可以直接进 CN 容器执行docker exec -it polardbx-sql容器名 mysql -h127.0.0.1 -P3306 -upolardbx_root -p连接失败的高频原因有三个。第一宿主机端口映射没生效确认你连的端口和 compose 里ports段一致。第二密码包含$、!等特殊字符在命令行里需要转义最省事的方式是用环境变量传密码MYSQL_PWDxxxx mysql -h127.0.0.1 -P3306 -upolardbx_root。第三host 写成了localhost某些客户端会走 unix socket从而连不到 TCP 端口这里必须明确写127.0.0.1。5. 部署成功只是开始拆表、GSI 和事务验证5.1 建一个带拆分键的逻辑表PolarDB-X 里你创建的数据库是“逻辑库”它可能对应底层多个物理分片。我们建一个业务库然后创建一张按用户维度拆分的订单表CREATE DATABASE app_db DEFAULT CHARACTER SET utf8mb4; USE app_db; CREATE TABLE t_order ( id BIGINT NOT NULL AUTO_INCREMENT, user_id BIGINT NOT NULL, order_no VARCHAR(64) NOT NULL, amount DECIMAL(12,2) NOT NULL, PRIMARY KEY (id, user_id) ) ENGINE InnoDB DEFAULT CHARSET utf8mb4 PARTITION BY HASH(user_id) PARTITIONS 4;这里的关键是最后一行PARTITION BY HASH(user_id) PARTITIONS 4。意思是根据user_id做哈希把数据分散到 4 个分片里。PARTITIONS 4的数字可以根据实际场景调整如果未来数据量增长还可以通过扩分片来扩容。这里有个容易踩的坑拆分键必须包含在主键中或者作为主键的一部分。我第一次建表时用PRIMARY KEY (id)结果报错原因很简单——分布式表的主键需要能定位到具体分片如果主键只有id而拆分键是user_id系统无法根据主键快速计算出数据在哪个分片。把主键改成(id, user_id)后问题就解决了。如果有一些字典类的小表不想拆成多份可以使用广播表CREATE TABLE t_dict ( dict_code VARCHAR(32) NOT NULL, dict_value VARCHAR(128), PRIMARY KEY (dict_code) ) BROADCAST;广播表会在每个分片上都复制一份完整数据适合配置类、字典类的小表这样在 JOIN 时可以避免跨分片数据传输。5.2 用 EXPLAIN 观察数据路由和执行计划建完表后插入几条测试数据INSERT INTO t_order (id, user_id, order_no, amount) VALUES (1, 101, 20250101001, 99.00), (2, 102, 20250101002, 199.00), (3, 201, 20250101003, 299.00);然后分别用两种方式查询观察执行计划的差异EXPLAIN SELECT * FROM t_order WHERE user_id 101; EXPLAIN SELECT * FROM t_order WHERE order_no 20250101001;第一条查询带了拆分键user_id系统可以通过哈希计算直接定位到具体分片执行计划会显示命中单个分片。第二条查询只带order_no不带拆分键CN 无法确定数据在哪个分片只能把请求发给所有分片也就是全分片扫描。这个对比非常直观地解释了为什么分布式数据库要求业务 SQL 尽量带拆分键。很多慢查询问题本质上都是“看似走了索引实际扫了全部分片”。5.3 全局二级索引给非拆分键查询提速既然order_no查询会全分片扫能不能给它也建一个索引在单机 MySQL 里建普通索引就行但在 PolarDB-X 里不行。因为索引如果和主表一样只存在某个分片那用索引去查同样不知道去哪个分片找。这时候需要的是全局二级索引GSI。它本质上是另一张分布式的索引表索引列作为新的拆分键独立分片CREATE GLOBAL INDEX idx_order_no ON t_order(order_no) PARTITION BY HASH(order_no) PARTITIONS 4;再次执行之前的 EXPLAINEXPLAIN SELECT * FROM t_order WHERE order_no 20250101001;这次执行计划会走 GSI 的分片先根据order_no哈希找到对应索引分片再回表取完整数据。训练营课程里常说的“用 GSI 解决非拆分键查询”就是这个原理。GSI 的同步是异步的写主表后索引更新有一点延迟。本地实验时感觉不明显但在高并发写入场景下需要在一致性和性能之间做取舍。5.4 分布式事务的快速验证PolarDB-X 支持分布式事务这也是落地场景中最受关注的能力。用一个简单的账户转账来验证CREATE TABLE t_account ( account_id BIGINT NOT NULL, balance DECIMAL(12,2) NOT NULL, PRIMARY KEY (account_id) ) PARTITION BY HASH(account_id) PARTITIONS 4; INSERT INTO t_account VALUES (1, 1000.00), (2, 1000.00); START TRANSACTION; UPDATE t_account SET balance balance - 100 WHERE account_id 1; UPDATE t_account SET balance balance 100 WHERE account_id 2; COMMIT;如果account_id1和account_id2哈希到了不同分片这条事务就是真正的跨分片分布式事务。CN 在这里承担协调者角色需要协调两个 DN 分片完成提交。本地实验观察到的结果和单机 MySQL 很相似都是一句 COMMIT 结束但背后多了一层协调逻辑。要注意的是单机部署无法验证真正的故障恢复行为比如网络分区、节点宕机时的事务状态如何处理。这类场景需要多机集群才能模拟本地部署只适合验证基本功能。6. 本地实例的日常维护与高频故障排查6.1 生命周期管理起停、重置与清理日常开发中不需要一直开着整套实例。资源紧张时可以先停掉docker compose stop下次要用再启动docker compose start如果想把数据彻底清掉恢复到刚部署的状态docker compose down -v-v参数会删除数据卷这一点要特别注意。数据卷里存的是 DN 节点的物理数据和 GMS 的元数据删了就真的没了。想保留数据做长期开发就不要随便加-v。容器日志会持续增长本地实验阶段倒不用太在意但如果长时间跑着建议给 Docker 的 log 配置加个大小限制比如在daemon.json里设置max-size100m避免日志文件把磁盘塞满。6.2 四个高频问题的排查链路我在实际操作中遇到过几类问题整理成排查思路供参考。第一类是连接不上 3306。先docker compose ps看端口映射是否正常再确认宿主机端口有没有被其他进程占用。很多时候是本地 MySQL 还在跑把宿主机映射端口改掉就能解决。第二类是容器反复重启。先看日志里有没有内存分配失败或磁盘不足的报错。Docker Desktop 的默认内存配额经常不够用把它调到 6G 或更高然后重启 Docker问题通常会消失。第三类是密码明明在日志里找到了却一直提示认证失败。检查一下 compose 文件里有没有配置环境变量密码如果配置了日志里打印的随机密码就是无效的要用配置的密码。第四类是 M1/M2 芯片的 Mac 上启动失败。PolarDB-X 官方镜像以 x86_64 为主Apple Silicon 上需要依赖模拟层运行建议开启 Docker Desktop 的 Rosetta 模拟选项再试。如果不行最省事的方案是换一台 x86 的 Linux 机器跑这套环境。还有一个排查顺序的问题不要一上来就怀疑镜像有问题。先看宿主机资源再看容器状态最后看对应组件日志按这个链路排查效率最高。我自己现在每次部署完都会顺手做三件事记下当前版本的初始密码把 3306 的映射端口写进项目的 README再把建库、拆表、GSI、事务验证的 SQL 存成一个脚本。这样下次重置环境后一条命令就能把功能验证跑完。本地部署 PolarDB-X 的价值不在于“跑起来”这个动作而在于跑起来之后你能反复实验、随意改动、再快速重置这种低成本试错的机会才是训练营和日常学习中真正珍贵的东西。