Windows 下 Docker 部署 TiDB 伪集群技术指导

一、前置条件

• 操作系统：Windows 10/11（推荐使用 WSL2 后端）
• 内存要求：物理内存 ≥ 16GB，建议为 Docker 分配 ≥ 8GB 内存
• 依赖软件：Docker Desktop for Windows（已安装并启用 WSL2）

二、Docker Desktop 安装与配置

2.1 安装 Docker Desktop

• 从 Docker 官网 下载并安装 Docker Desktop for Windows。
• 安装时勾选Use WSL 2 instead of Hyper-V，完成后启动 Docker Desktop。

2.2 调整 Docker 内存分配（关键步骤）

• 打开 Docker Desktop → 点击右上角设置图标 → Resources → Memory。
• 将内存调整为 8GB（16GB 物理内存完全足够），点击 Apply & Restart 重启 Docker。

2.3 配置 WSL2 内存上限（可选）

• 在用户目录（C:\Users\你的用户名）下创建 .wslconfig 文件，写入以下内容：

[wsl2]
memory=8GB
processors=4
swap=4GB

• 重启 WSL2：

wsl --shutdown

• 重新启动 Docker Desktop。

三、编写 docker-compose.yml 配置文件

3.1 创建工作目录

mkdir -Path ~/Desktop/tidb-docker
cd ~/Desktop/tidb-docker

3.2 编写优化后的配置文件

创建 docker-compose.yml 文件，内容如下：

services:
  # PD（集群调度与元数据管理）
  pd:
    image: pingcap/pd:v7.5.0
    container_name: tidb-pd
    ports:
      - "2379:2379"
    volumes:
      - ./pd-data:/data
      - ./pd-log:/log
    command:
      - --name=pd
      - --data-dir=/data
      - --log-file=/log/pd.log
      - --client-urls=http://0.0.0.0:2379
      - --peer-urls=http://0.0.0.0:2380
      - --initial-cluster=pd=http://pd:2380
      - --advertise-client-urls=http://pd:2379
      - --advertise-peer-urls=http://pd:2380
    deploy:
      resources:
        limits:
          memory: 512M
    restart: always

  # TiKV（分布式存储引擎）
  tikv:
    image: pingcap/tikv:v7.5.0
    container_name: tidb-tikv
    ports:
      - "20160:20160"
    volumes:
      - ./tikv-data:/data
      - ./tikv-log:/log
    command:
      - --addr=0.0.0.0:20160
      - --advertise-addr=tikv:20160
      - --data-dir=/data
      - --log-file=/log/tikv.log
      - --pd=http://pd:2379
    depends_on:
      - pd
    deploy:
      resources:
        limits:
          memory: 2G
    restart: always

  # TiDB（SQL 服务层）
  tidb:
    image: pingcap/tidb:v7.5.0
    container_name: tidb-server
    ports:
      - "4000:4000"
      - "10080:10080"
    volumes:
      - ./tidb-log:/log
    command:
      - --store=tikv
      - --path=pd:2379
      - --log-file=/log/tidb.log
      - --advertise-address=tidb
    depends_on:
      - pd
      - tikv
    deploy:
      resources:
        limits:
          memory: 1G
    restart: always

  # TiDB Dashboard（可视化管理）
  tidb-dashboard:
    image: pingcap/tidb-dashboard:v7.5.0
    container_name: tidb-dashboard
    ports:
      - "23790:23790"
    command:
      - --pd=http://pd:2379
    depends_on:
      - pd
    restart: always

四、启动 TiDB 伪集群

在 tidb-docker 目录下执行以下命令：

# 清理旧容器
docker compose down

# 后台启动集群
docker compose up -d

# 检查容器状态
docker compose ps

• 若所有容器状态为 Up，则集群启动成功。

五、验证 TiDB 集群连接

5.1 获取 WSL2 IP 地址

(wsl -- ip -4 addr show eth0) | Select-String -Pattern 'inet\s+(\d+\.\d+\.\d+\.\d+)' | ForEach-Object { $_.Matches.Groups[1].Value }

5.2 使用 MySQL 客户端连接

# 替换为实际的 WSL2 IP 和 MySQL 客户端路径
D:\mysql-8.0.39-winx64\bin\mysql -h 127.0.0.1 -P 4000 -u root

5.3 执行测试 SQL

SELECT VERSION();
CREATE DATABASE test_db;
USE test_db;
CREATE TABLE test_table (id INT PRIMARY KEY, name VARCHAR(20));
INSERT INTO test_table VALUES (1, 'tidb-docker');
SELECT * FROM test_table;

5.4 可视化工具连接

• 工具：Navicat、DBeaver、MySQL Workbench
• 连接信息：
  • 地址：127.0.0.1 或 WSL2 IP
  • 端口：4000
  • 用户名：root
  • 密码：空

六、常见问题排查

6.1 TiDB 容器反复重启（Restarting）

• 原因：Docker 内存不足或 TiKV 无限制占用内存
• 解决：
  • 确认 Docker 内存分配 ≥ 8GB
  • 检查 TiKV 内存限制配置（2G）
  • 查看日志：

docker compose logs tidb

6.2 连接超时（ERROR 2003）

• 原因：PD 地址配置错误或容器间网络异常
• 解决：
  • 确认 PD 的 --advertise-client-urls 为 http://pd:2379
  • 检查 PD 容器状态：docker compose ps pd
  • 使用 WSL2 IP 替代 127.0.0.1 连接

6.3 端口被占用

• 原因：宿主机程序占用 4000/2379 等端口
• 解决：修改 docker-compose.yml 中的端口映射（如 4001:4000），重启集群

七、核心总结

• Docker 部署 TiDB 伪集群的核心是足够的内存分配和正确的 PD 地址配置
• 16GB 物理内存需为 Docker 分配 ≥ 8GB，同时限制 TiKV 内存 ≤ 2GB
• 容器间通信依赖 PD 的 advertise-client-urls 配置为 http://pd:2379
• 验证集群的关键是通过 MySQL 客户端/可视化工具成功连接并执行 SQL