MacBook 2025 M4 笔记本 Docker 本地微服务环境完整部署指南#

本指南旨在为基于 Apple Silicon M4 架构的 MacBook 提供一套轻量、稳定、易于调试的本地微服务底座（包含 MySQL、Redis、Nacos 与 RocketMQ）。配置已针对 Mac 本地资源占用和 IDEA 宿主机直连调试进行了优化。

第一步：构建最佳目录结构#

为了避免 Docker 挂载数据卷时出现路径混乱或无权限（Permission Denied）的问题，我们需要预先在宿主机上创建好标准的工作空间和数据挂载目录。

请打开 Mac 终端，复制并一次性执行以下完整脚本，它将为您建立 ~/mac-dev-env 工作主目录以及所有依赖的子文件夹：

1
# 1. 创建并进入你的本地微服务环境主工作目录
2
mkdir -p ~/mac-dev-env
3
cd ~/mac-dev-env
4

5
# 2. 在当前目录下，创建 MySQL、Redis 的数据挂载目录，以及 RocketMQ 的配置目录
6
mkdir -p ./data/mysql
7
mkdir -p ./data/redis
8
mkdir -p ./rocketmq
9

10
# 3. 创建 Nacos 的数据与日志挂载目录（用于持久化，避免 docker compose down 后丢配置）
11
mkdir -p ./data/nacos/data
12
mkdir -p ./data/nacos/logs
13

14
# 4. 创建 RocketMQ 特殊的绝对路径数据目录（存放日志和持久化存储）
15
mkdir -p ~/docker-data/rocketmq/{logs,store}

执行完毕后，您的核心工作目录已就绪，且 Nacos/RocketMQ 所需的数据挂载目录也已创建完成。

第二步：配置环境变量文件（推荐）#

为了让编排文件更易维护，同时避免启动时出现环境变量缺失提示，建议在工作根目录创建 .env 文件统一管理变量。

请在 ~/mac-dev-env 下创建文件 .env，并写入以下内容：

1
cd ~/mac-dev-env
2

3
cat > .env <<'EOF'
4
MYSQL_ROOT_PASSWORD=lsdfsdf!@#
5
TZ=Asia/Shanghai
6
EOF

第三步：配置 RocketMQ（本地直连优化版）#

为了让宿主机（您的 Mac）上运行的 IDEA 能够直连 RocketMQ 容器收发消息，我们需要一份定制化的 Broker 配置。

请创建文件 ~/mac-dev-env/rocketmq/broker.conf，并将以下完整配置粘贴进去：

1
brokerClusterName = DefaultCluster
2
brokerName = broker-a
3
brokerId = 0
4

5
deleteWhen = 04
6
fileReservedTime = 48
7
brokerRole = ASYNC_MASTER
8
flushDiskType = ASYNC_FLUSH
9

10
# ---- 开发环境优化 ----
11
autoCreateTopicEnable = true
12
autoCreateSubscriptionGroup = true
13

14
# 容器内 namesrv 地址（容器里不能写 127.0.0.1）
15
namesrvAddr = rocketmq-namesrv:9876
16

17
# 减少内存映射文件大小
18
mapedFileSizeCommitLog = 268435456
19
mapedFileSizeConsumeQueue = 2097152
20

21
# 数据目录（映射到宿主机 ${HOME}/docker-data/rocketmq/store）
22
storePathRootDir=/home/rocketmq/store
23
storePathCommitLog=/home/rocketmq/store/commitlog
24
storePathConsumeQueue=/home/rocketmq/store/consumequeue
25
storePathIndex=/home/rocketmq/store/index
26
storeCheckpoint=/home/rocketmq/store/checkpoint
27
abortFile=/home/rocketmq/store/abort
28

29
# 宿主机 IDEA 跑客户端：broker 宣告 127.0.0.1 最稳
30
brokerIP1=127.0.0.1

第四步：配置 Docker Compose 核心编排文件#

请在工作根目录下创建文件 ~/mac-dev-env/docker-compose.yml，并将以下完整内容粘贴进去：

1
services:
2
  mysql:
3
    image: mysql:8.4
4
    container_name: dev-mysql
5
    restart: unless-stopped
6
    environment:
7
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
8
      MYSQL_ROOT_HOST: '%'
9
      MYSQL_DATABASE: micro_platform
10
      TZ: ${TZ}
11
    command:
12
      [
13
        "mysqld",
14
        "--character-set-server=utf8mb4",
15
        "--collation-server=utf8mb4_general_ci",
16
        "--default-time-zone=+08:00",
17
        "--innodb-buffer-pool-size=256M",
18
        "--max-connections=200"
19
      ]
20
    ports:
21
      - "127.0.0.1:3306:3306"
22
    volumes:
23
      - ./data/mysql:/var/lib/mysql
24
    healthcheck:
25
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p\"${MYSQL_ROOT_PASSWORD}\" --silent"]
26
      interval: 10s
27
      timeout: 5s
28
      retries: 10
29
    networks:
30
      - devnet
31

32
  redis:
33
    image: redis:7.4-alpine
34
    container_name: dev-redis
35
    restart: unless-stopped
36
    command: ["redis-server", "--save", "60", "1", "--loglevel", "warning"]
37
    ports:
38
      - "127.0.0.1:6379:6379"
39
    volumes:
40
      - ./data/redis:/data
41
    healthcheck:
42
      test: ["CMD", "redis-cli", "ping"]
43
      interval: 10s
44
      timeout: 3s
45
      retries: 10
46
    networks:
47
      - devnet
48

49
  nacos:
50
    image: nacos/nacos-server:v2.4.3-slim
51
    container_name: dev-nacos
52
    restart: unless-stopped
53
    environment:
54
      MODE: standalone
55
      NACOS_AUTH_ENABLE: "false"
56
      JVM_XMS: "256m"
57
      JVM_XMX: "256m"
58
      JVM_XMN: "128m"
59
      PREFER_HOST_MODE: hostname
60
    ports:
61
      - "127.0.0.1:8848:8848"
62
      - "127.0.0.1:9848:9848"
63
      - "127.0.0.1:9849:9849"
64
    volumes:
65
      - ./data/nacos/data:/home/nacos/data
66
      - ./data/nacos/logs:/home/nacos/logs
67
    networks:
68
      - devnet
69

70
  rocketmq-namesrv:
71
    image: apache/rocketmq:5.3.4
72
    container_name: dev-rmq-namesrv
73
    restart: unless-stopped
74
    command: ["sh", "mqnamesrv"]
75
    environment:
76
      JAVA_OPT_EXT: "-Xms256m -Xmx256m -Xmn128m -XX:MaxDirectMemorySize=128m"
77
    ports:
78
      - "127.0.0.1:9876:9876"
79
    volumes:
80
      - ${HOME}/docker-data/rocketmq/logs:/home/rocketmq/logs
81
    networks:
82
      - devnet
83

84
  rocketmq-broker:
85
    image: apache/rocketmq:5.3.4
86
    container_name: dev-rmq-broker
87
    restart: unless-stopped
88
    depends_on:
89
      - rocketmq-namesrv
90
    command: ["sh", "mqbroker", "-c", "/home/rocketmq/rocketmq-5.3.4/conf/broker.conf"]
91
    environment:
92
      NAMESRV_ADDR: "rocketmq-namesrv:9876"
93
      JAVA_OPT_EXT: "-Xms512m -Xmx512m -Xmn256m -XX:MaxDirectMemorySize=256m"
94
    ports:
95
      - "127.0.0.1:10909:10909"
96
      - "127.0.0.1:10911:10911"
97
      - "127.0.0.1:10912:10912"
98
    volumes:
99
      - ./rocketmq/broker.conf:/home/rocketmq/rocketmq-5.3.4/conf/broker.conf
100
      - ${HOME}/docker-data/rocketmq/logs:/home/rocketmq/logs
101
      - ${HOME}/docker-data/rocketmq/store:/home/rocketmq/store
102
    networks:
103
      - devnet
104

105
networks:
106
  devnet:
107
    driver: bridge

说明： MySQL 限制 buffer pool，Nacos 单机免鉴权并做数据持久化，RocketMQ 使用宿主机绝对路径持久化 store/logs。

第五步：镜像拉取与一键启动#

请确保终端路径处于 ~/mac-dev-env，并且 Docker Desktop 已启动。

建议按以下顺序启动（先拉镜像、再启动容器）：

1
cd ~/mac-dev-env
2

3
docker compose down
4
docker compose pull
5
docker compose up -d
6
docker compose ps

第六步：Docker Desktop 常用设置（拉取镜像失败时必看）#

在网络环境不稳定、存在代理/VPN、或镜像拉取频繁中断时，可能出现拉取层文件失败的情况。遇到此类问题时，建议检查 Docker Desktop 的通用设置项，完成后重启 Docker Desktop 再重新执行 docker compose pull。

另外建议在拉取失败时先单独拉取一个轻量镜像用于验证网络链路：

1
docker pull redis:7.4-alpine

第七步：IDEA / 宿主机直连关键地址#

服务	地址	备注
MySQL	`127.0.0.1:3306`	用户 `root`，密码 `lsdfsdf!@#`
Redis	`127.0.0.1:6379`	无密码
Nacos 控制台	`http://127.0.0.1:8848/nacos`	免鉴权
RocketMQ NameServer	`127.0.0.1:9876`	—
RocketMQ Broker	`127.0.0.1:10911`	由 `brokerIP1=127.0.0.1` 决定

第八步：常用排查命令#

当服务启动异常或端口不可用时，可使用以下命令快速定位：

1
cd ~/mac-dev-env
2

3
# ---------------------------
4
# 1) 查看服务状态（推荐）
5
# ---------------------------
6
docker compose ps
7

8
# ---------------------------
9
# 2) 查看日志（推荐）
10
# ---------------------------
11
# 看某个服务日志（推荐：定位单点问题最清晰）
12
docker compose logs -f --tail=200 mysql
13
docker compose logs -f --tail=200 redis
14
docker compose logs -f --tail=200 nacos
15
docker compose logs -f --tail=200 rocketmq-namesrv
16
docker compose logs -f --tail=200 rocketmq-broker
17

18
# 看全部服务日志（推荐：不确定是哪个服务时）
19
docker compose logs -f --tail=200
20

21
# ---------------------------
22
# 3) 启动 / 停止 / 重启（编排级别）
23
# ---------------------------
24

25
# 启动（推荐：日常启动）
26
docker compose up -d
27

28
# 停止（推荐：临时停一下，后续还要继续用）
29
docker compose stop
30

31
# 重启全部服务（推荐：配置没变，只是服务状态不对/想快速恢复）
32
docker compose restart
33

34
# 重启单个服务（推荐：只影响一个组件）
35
# 示例：只重启 mysql
36
docker compose restart mysql
37

38
# 停止并移除容器（推荐：你改了 docker-compose.yml 或挂载配置，需要“重建容器”）
39
# 注意：不带 -v 不会删除你挂载到宿主机的数据目录
40
docker compose down
41
docker compose up -d
42

43
# ---------------------------
44
# 4) Docker Desktop 启动 / 重启（macOS）
45
# ---------------------------
46

47
# 启动 Docker Desktop（推荐：Docker 没开时）
48
open -a Docker
49

50
# 重启 Docker Desktop（推荐：遇到 pull EOF、网络异常、Docker 引擎卡住等）
51
osascript -e 'quit app "Docker"'
52
open -a Docker
53

54
# 关闭 Docker Desktop（不推荐常用；相当于停止 Docker 引擎）
55
osascript -e 'quit app "Docker"'
56

57
# ---------------------------
58
# 5) 进入容器排查（推荐：需要看容器内文件/配置/进程时）
59
# ---------------------------
60
docker exec -it dev-mysql bash
61
docker exec -it dev-redis sh
62
docker exec -it dev-nacos sh
63
docker exec -it dev-rmq-broker sh