Docker Compose 编排实战:从命令详解到 Redis Cluster 三主三从部署

🐳 一个正常上线的项目,很少只有一个容器。应用一个、数据库一个、缓存一个、前面还压着反向代理------它们要一起存在、按顺序启动、彼此能按名字访问。手敲 docker run 拼这些东西,命令长到没法复现,换台机器就崩。

这篇从 Compose 的定位讲起,把常用命令和 docker-compose.yml 的指令过一遍,最后用一份真实的编排文件,在一台机器上拉起 3 主 3 从的 Redis Cluster 并验证读写。

全文命令统一使用 docker compose(Docker CLI 插件形式)。示例目录统一放在 ~/docker/ 下,实验机 IP 为 192.168.2.132,环境为 Ubuntu 22.04 + Docker 24 + Compose 插件。


🐳 一、Compose 解决了什么问题

📌 1.1 它是什么

Docker Compose 是 Docker 官方提供的容器编排工具 ,负责把「多个容器组成的一个应用 」快速跑起来。项目源码在 github.com/docker/compose,早期从 Fig 演化而来,思路和 OpenStack 的 Heat 属于同一类。

它给自己的定位很明确:多容器应用的定义与运行。「多容器」这三个字,就是它和 Dockerfile 的分界线。

📌 1.2 单容器思路的边界

Dockerfile 能回答的问题是:一个镜像长什么样。基础镜像是什么、装什么依赖、跑什么命令,写得清清楚楚。

但它回答不了另一类问题:

  • 这个应用还依赖 Redis,Redis 容器谁起?
  • 应用要先等数据库就绪,顺序怎么保证?
  • 应用连数据库,地址写什么?容器 IP 每次重建都变。
  • 端口、数据目录、配置文件、环境变量,怎么一次性描述完?

这些如果全靠 docker run 手拼,你会得到一串带 --network、-v、-e、--link 的长命令,而且只存在于你的终端历史里,没有任何可版本化的东西。

Compose 的做法是把这些写成一份 docker-compose.yml,把一组容器声明成一个「项目」,然后一条命令全起来。

📌 1.3 两个必须分清的概念

概念 含义 直观理解
服务(service) 一个应用的容器定义,背后可以是多个跑同一镜像的实例 一类「角色」,比如 web 角色可以站 3 个实例
项目(project) 由一组关联服务组成的完整业务单元,写在 yml 里 一部「戏」,角色都在剧本里

由此推出三条结论:

  • 层级是 项目 → 服务 → 容器实例,三层不要糊在一起;
  • Compose 的默认操作对象是项目,命令不带服务名就作用于整个项目;
  • Compose 本身是 Python 写的外壳 ,真正干活是调 Docker 的 API。所以只要平台上有可用的 Docker API,Compose 就能在上面编排。

📌 1.4 一条命令背后的完整链路

复制代码
docker compose up
   │
   ├─ 读取 docker-compose.yml,做变量替换与语法校验
   ├─ 为项目创建(或复用)一张自定义网络
   ├─ 对带 build 的服务构建镜像
   ├─ 按 depends_on 顺序创建容器
   ├─ 挂载 volumes、注入 environment、套用 ulimits/sysctls
   └─ 启动容器,把日志汇总到当前终端

理解了这条链路,后面所有命令都只是在这个链路上「打断点」。

🧠 核心要点 :Dockerfile 管「一个镜像怎么造 」,Compose 管「一组容器怎么协作跑」。前者是构建期,后者是运行期编排。


🐳 二、安装与工程结构

📌 2.1 安装

macOS / Windows :装 Docker Desktop 即可,docker compose 随 Docker 一起提供,开箱可用。

Linux:Compose 以 Docker CLI 插件形式提供,装插件包即可。

bash 复制代码
# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y docker-compose-plugin

如果发行版的仓库版本偏旧,也可以从 GitHub Release 直接取二进制,放进 CLI 插件目录(让 Docker 能把它识别为 compose 子命令):

bash 复制代码
# 下载对应架构的插件二进制
sudo curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \
  -o /usr/local/lib/docker/cli-plugins/docker-compose

# 赋予执行权限
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

📌 2.2 验证

bash 复制代码
docker compose version

能打印出版本号就说明可用。再确认它确实是以插件形式挂到 Docker CLI 上的:

bash 复制代码
docker compose --help | head -5

能看到 Usage: docker compose [OPTIONS] COMMAND 就说明装好了。

📌 2.3 一个 Compose 项目的目录长什么样

本文第一个示例的目录结构:

text 复制代码
likeboard/
├── app.py                 # 应用代码
├── requirements.txt       # 依赖清单
├── Dockerfile             # 镜像构建文件
└── docker-compose.yml     # 编排文件(名字是约定,不是随便起)

四个要点:

  • 文件名是约定 :默认就叫 docker-compose.yml,放在项目根目录,docker compose up 会自动找它;
  • build 的路径是相对的 :相对 docker-compose.yml 所在目录,所以文件放哪儿很关键;
  • 不要提交的东西 :.env 里如果有密码,加进 .gitignore;
  • 一个项目一个目录 :Compose 默认拿目录名当项目名 ,容器、网络、卷都会带上这个前缀(本文示例是 likeboard-)。

💡 项目名可以改:docker compose -p myapp up -d,或者设环境变量 COMPOSE_PROJECT_NAME=myapp。同一台机器跑多套环境时很有用。


🐳 三、跑通第一个多容器项目

📌 3.1 项目说明

做一个极简的「点赞板」服务:

  • web :Python + Flask 提供三个接口,POST /api/like 点赞、GET /api/count 查总数、GET /healthz 健康检查;
  • redis:存点赞数,开启 AOF 持久化;
  • 两者通过 Compose 的自定义网络互通,web 里用服务名连 Redis,不写 IP。

为什么不用 localhost?因为 web 和 redis 是两个容器、两个网络命名空间,各自有独立的 127.0.0.1。Compose 会为项目建一张网,并把服务名注册成 DNS 记录 ,所以 host="redis" 能直接解析到 redis 容器。

📌 3.2 应用代码 app.py

python 复制代码
import os
import time

import redis
from flask import Flask, jsonify

app = Flask(__name__)

# 从环境变量取连接信息,未设置时给出默认值。
# 注意 host 默认值就是服务名 "redis" ------ Compose 会把它解析成容器 IP。
REDIS_HOST = os.getenv("REDIS_HOST", "redis")
REDIS_PORT = int(os.getenv("REDIS_PORT", "6379"))
COUNTER_KEY = os.getenv("COUNTER_KEY", "likeboard:likes")

_client = None


def get_client() -> "redis.Redis":
    """惰性建立 Redis 连接,并做有限次重试。

    容器之间没有「同时启动」这回事:web 起来时 redis 可能还在初始化,
    第一次 ping 会失败。这里退避重试若干次,避免进程直接退出。
    """
    global _client
    if _client is not None:
        return _client

    last_error = None
    for attempt in range(1, 11):
        try:
            client = redis.Redis(
                host=REDIS_HOST,
                port=REDIS_PORT,
                decode_responses=True,
                socket_connect_timeout=2,
                socket_timeout=2,
            )
            client.ping()
            _client = client
            return _client
        except redis.exceptions.RedisError as exc:
            last_error = exc
            app.logger.warning("redis 未就绪(第 %s 次):%s", attempt, exc)
            time.sleep(0.5)

    raise RuntimeError(f"无法连接 redis {REDIS_HOST}:{REDIS_PORT}") from last_error


@app.get("/")
def index():
    return (
        "<h1>LikeBoard</h1>"
        "<p>POST /api/like 点赞,GET /api/count 查看总数</p>"
    )


@app.post("/api/like")
def like():
    total = get_client().incr(COUNTER_KEY)
    return jsonify(likes=total)


@app.get("/api/count")
def count():
    value = get_client().get(COUNTER_KEY)
    return jsonify(likes=int(value) if value else 0)


@app.get("/healthz")
def healthz():
    """供容器健康检查使用:能 ping 通 Redis 才算健康。"""
    try:
        get_client().ping()
        return jsonify(status="ok"), 200
    except (redis.exceptions.RedisError, RuntimeError):
        return jsonify(status="down"), 503


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=int(os.getenv("APP_PORT", "8080")))

三处值得单独说:

  1. host="redis" 是服务名,不是域名也不是 IP。容器重建后 IP 会变,服务名不会。
  2. 重试是必须的 。depends_on 只保证启动顺序,不保证 Redis 已经能收命令,所以连接要自己兜底。
  3. /healthz 是给 healthcheck 用的。健康检查不能只看端口通不通,要真做一次业务探活。

📌 3.3 依赖清单 requirements.txt

text 复制代码
flask==3.0.3
redis==5.0.8

锁版本,别用浮动版本------否则半年后构建出来的镜像和今天不一样,排查问题时很痛苦。

📌 3.4 镜像构建 Dockerfile

dockerfile 复制代码
FROM python:3.11-slim

# 不生成 .pyc、日志不缓冲,容器里这两个开关几乎是标配
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    APP_PORT=8080

WORKDIR /app

# 先只拷依赖清单,利用镜像层缓存:
# 只要 requirements.txt 没变,这一层就能命中,不必重装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 再拷业务代码,改代码不会让上面那层失效
COPY app.py .

EXPOSE 8080

CMD ["python", "app.py"]

各行的作用:

指令 作用
FROM python:3.11-slim 底座选 slim 版本,体积比完整版小很多
ENV PYTHONDONTWRITEBYTECODE=1 不写 .pyc,减少容器内垃圾文件
ENV PYTHONUNBUFFERED=1 标准输出不缓冲,docker compose logs 能实时看到日志
WORKDIR /app 工作目录,后面相对路径都基于它
COPY requirements.txt . + RUN pip install 依赖单独成层,便于缓存复用
COPY app.py . 业务代码单独一层
EXPOSE 8080 声明端口(仅是文档性质 ,真正映射靠 yml 的 ports)
CMD ["python", "app.py"] 容器默认启动命令,可被 yml 的 command 覆盖

⚠️ EXPOSE 不发布端口 。它只是元信息,告诉读镜像的人「这个服务监听 8080」。要让宿主机访问,必须写 ports。这是新手最常见的误解之一。

📌 3.5 编排文件 docker-compose.yml

yaml 复制代码
services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: likeboard-web:1.0
    container_name: likeboard-web
    restart: unless-stopped
    environment:
      REDIS_HOST: redis          # 服务名,靠 Compose 内置 DNS 解析
      REDIS_PORT: "6379"         # 端口用字符串,避免 YAML 类型推断问题
      COUNTER_KEY: likeboard:likes
    ports:
      - "8080:8080"              # 宿主机:容器
    depends_on:
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c",
             "import urllib.request;urllib.request.urlopen('http://127.0.0.1:8080/healthz')"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 15s
    networks:
      - likeboard-net
    logging:
      driver: json-file
      options:
        max-size: "20m"
        max-file: "3"

  redis:
    image: redis:7-alpine
    container_name: likeboard-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - likeboard-net

volumes:
  redis-data:

networks:
  likeboard-net:
    driver: bridge

几个关键设计:

写法 为什么这么写
build + image 构建出来的镜像同时打上 likeboard-web:1.0 标签,便于推仓库
depends_on.condition: service_healthy 等 redis 健康再起 web,不只是「先启动」
healthcheck 用真实业务接口探活,比 nc -z 端口探测可靠
volumes: redis-data:/data 命名卷,Redis 的 AOF 保存在里面,容器删了数据还在
自定义 networks 把两个服务圈进同一张网,服务名才可解析
logging.options 限制日志体积,防止磁盘被写满

⚠️ depends_on 的两种形态别混 :短语法 depends_on: [redis] 只管启动顺序 ;带 condition: service_healthy 的长语法才会等健康。前者等你踩坑,后者才是你想要的。

📌 3.6 启动与验证

bash 复制代码
cd ~/docker/likeboard

# 首次启动会构建镜像,所以别急着加 -d 看不见输出
docker compose up -d --build

--build 表示强制重建镜像 ,改了 app.py 或 Dockerfile 时用它,避免跑到旧镜像。

看容器状态:

bash 复制代码
docker compose ps
text 复制代码
NAME              IMAGE               COMMAND                  SERVICE   STATUS                    PORTS
likeboard-redis   redis:7-alpine      "docker-entrypoint.s..."   redis     Up 2 minutes (healthy)    6379/tcp
likeboard-web     likeboard-web:1.0   "python app.py"          web       Up 1 minute (healthy)     0.0.0.0:8080->8080/tcp

两个容器的 STATUS 都带 (healthy),说明健康检查通过、web 已经能连上 Redis。

接口验证:

bash 复制代码
# 点赞两次
curl -X POST http://192.168.2.132:8080/api/like
curl -X POST http://192.168.2.132:8080/api/like

# 查总数
curl http://192.168.2.132:8080/api/count

# 健康检查
curl -i http://192.168.2.132:8080/healthz
text 复制代码
{"likes":1}
{"likes":2}
{"likes":2}
HTTP/1.1 200 OK
Content-Type: application/json
{"status":"ok"}

📌 3.7 几个日常观测动作

bash 复制代码
# 跟踪日志(-f 持续输出,Ctrl-C 只退出日志跟踪,不会停容器)
docker compose logs -f web

# 只看最近 50 行
docker compose logs --tail=50 redis

# 进容器排查
docker compose exec web sh

# 看 web 到 redis 的连通性(在 web 容器里执行)
docker compose exec web python -c "import socket;print(socket.gethostbyname('redis'))"

# 验证数据持久化:重启 web 不影响计数
docker compose restart web && curl http://192.168.2.132:8080/api/count

最后一条能验证「计数存在 Redis 里」------重启 web 后 likes 依然是 2。

🧠 核心要点 :up 一次完成 构建镜像 → 建网络 → 创建容器 → 启动并汇总日志。docker compose logs -f 里的 -f 只跟踪日志,不会停容器 ;只有前台 up 时的 Ctrl-C 才会停容器。


🐳 四、命令手册

📌 4.1 作用对象与语法

大部分命令的操作对象有三级:项目 / 服务 / 容器 。不指定时默认是项目,也就是项目里所有服务都会被执行一遍。

bash 复制代码
# 基本语法
docker compose [-f=<arg>...] [options] [COMMAND] [ARGS...]

# 查某个子命令的用法
docker compose [COMMAND] --help
docker compose help [COMMAND]

📌 4.2 全局选项

选项 作用
-f, --file FILE 指定编排文件,默认 docker-compose.yml;可写多次,多份文件按顺序合并
-p, --project-name NAME 指定项目名,默认取所在目录名
--env-file FILE 指定环境变量文件,默认 .env
--profile NAME 启用某组 profile 下的服务(按需启动可选服务)
--verbose 输出更详细的调试信息
--dry-run 只打印将要执行的操作,不真正执行(排查改动很实用)

📌 4.3 命令速查表

命令 作用 最常用法
up 构建 + 创建 + 启动整个项目 docker compose up -d
down 停止并删除容器、网络 docker compose down -v
ps 列出项目内容器 docker compose ps
logs 查看服务日志 docker compose logs -f web
exec 在运行中的容器里执行命令 docker compose exec web sh
run 用服务配置临时跑一条命令 docker compose run --rm web python -V
build 构建或重建镜像 docker compose build --no-cache
pull 拉取服务依赖的镜像 docker compose pull
push 推送镜像到仓库 docker compose push
restart 重启服务 docker compose restart web
stop / start 停止 / 启动(不删容器) docker compose stop
rm 删除已停止的容器 docker compose rm -v
kill 发信号强杀 docker compose kill -s SIGINT
pause / unpause 挂起 / 恢复 docker compose pause web
port 查端口映射 docker compose port web 8080
top 看容器内进程 docker compose top
images 列出涉及的镜像 docker compose images
config 校验并输出最终配置 docker compose config
version 打印版本 docker compose version
ls 列出本机所有 Compose 项目 docker compose ls
cp 容器与宿主机之间拷文件 docker compose cp web:/app/x.log .

📌 4.4 常用命令详解

🔹 up

docker compose up [options] [SERVICE...]

把「构建镜像 → 创建/重建服务 → 启动服务 → 接上关联容器」一次做完,日常启动项目基本只用它。

行为要点:

  • 默认前台 运行,所有容器日志混在一起输出,Ctrl-C 会停掉全部容器;
  • -d 转后台,生产环境用这个;
  • 容器已存在 时,默认会停旧容器、按最新 yml 重建(命名卷保留),保证配置是最新的;
  • 只想补启动、不想重建,用 --no-recreate;想无条件重建,用 --force-recreate(两者互斥);
  • 只想重部署某个服务,用 --no-deps -d <服务名>,不牵连它依赖的服务。
选项 作用
-d, --detach 后台运行
--build 启动前先构建镜像
--force-recreate 强制重建容器
--no-recreate 容器已存在则不重建
--no-deps 不启动依赖的服务
--no-build 缺镜像也不构建
--remove-orphans 删掉 yml 里已不存在的服务的旧容器
--scale SERVICE=NUM 指定某服务的实例数
-t, --timeout 停止超时,默认 10 秒

🧠 三种重建策略记这一句:默认=变了就重建;--no-recreate=只补启动;--force-recreate=无条件重建。

🔹 down

docker compose down [options]

停止并删除 up 创建的容器,同时移除项目网络。

选项 作用
-v, --volumes 连命名卷一起删(宿主机目录挂载不受影响)
--rmi local 删除本机构建的镜像
--remove-orphans 清理孤立容器
-t, --timeout 停止超时
bash 复制代码
# 彻底清场,重来一遍
docker compose down -v --rmi local
🔹 ps

docker compose ps [options] [SERVICE...]

列出项目内容器。-a 包含已停止的,-q 只输出 ID。

bash 复制代码
docker compose ps
docker compose ps -q          # 交给别的命令用,比如 docker stats
🔹 logs

docker compose logs [options] [SERVICE...]

查看服务输出,默认给不同服务不同颜色 (--no-color 可关)。

选项 作用
-f, --follow 持续跟踪
--tail=N 只显示最后 N 行
-t, --timestamps 显示时间戳
--since / --until 按时间范围过滤
bash 复制代码
docker compose logs -f --tail=100 web
🔹 exec

docker compose exec [options] SERVICE COMMAND

在运行中的容器里执行命令,最常用于进容器排查。

bash 复制代码
docker compose exec web sh
docker compose exec redis redis-cli
docker compose exec -T web python -c "print('ok')"   # -T 不分配 tty,适合脚本

💡 exec 要求容器正在运行 ;容器已停止要用 run。

🔹 run

docker compose run [options] SERVICE [COMMAND] [ARGS...]

用服务的配置临时起一个新容器跑一条命令,跑完即走。

bash 复制代码
# 跑一次性任务,跑完自动删容器
docker compose run --rm web python -c "print('hello')"

# 不启动依赖服务
docker compose run --rm --no-deps web python -c "print('standalone')"

两个关键差别:命令会覆盖服务原本的启动命令 ;默认不创建端口映射 (避免和运行中的服务抢端口,需要时加 --service-ports)。

选项 作用
--rm 跑完删容器
-d 后台运行
--name 指定容器名
--no-deps 不启动依赖
-e KEY=VAL 设环境变量
--entrypoint 覆盖入口点
--service-ports 套用服务的端口映射
-T 不分配 tty
🔹 build

docker compose build [options] [SERVICE...]

构建或重建服务镜像。

选项 作用
--no-cache 不用缓存,全量重建
--pull 先拉最新底座镜像
--build-arg KEY=VAL 传构建参数
--parallel 并行构建多个服务
🔹 config

docker compose config

校验编排文件语法,并输出变量替换后的最终配置。格式错了会直接指出位置。

bash 复制代码
docker compose config
docker compose config --services      # 只看服务名列表
docker compose config --quiet         # 只校验,成功则无输出,适合 CI

💡 排查缩进错、变量没替换上,这是最快的命令------不用等 up 报错再翻日志。

🔹 restart / stop / start
bash 复制代码
docker compose restart web     # 重启,配置改动不会生效(不会重建容器)
docker compose stop            # 停容器,不删
docker compose start           # 把停了的再启动

⚠️ restart 只重启进程,不重新读取 yml 。改了 environment、ports 这类创建期参数,必须 up -d 让容器重建。

🔹 rm / kill / pause
bash 复制代码
docker compose rm -v           # 删已停止的容器,-v 连卷一起删
docker compose kill -s SIGINT  # 发指定信号(默认 SIGKILL)
docker compose pause web       # 挂起(进程冻结)
docker compose unpause web     # 恢复
🔹 port / top / images / ls
bash 复制代码
docker compose port web 8080   # 查容器 8080 映射到宿主机哪个端口
docker compose top             # 各容器内运行的进程
docker compose images          # 涉及的镜像及大小
docker compose ls              # 本机所有 Compose 项目及状态
🔹 scale(现在统一用 up --scale)

scale 子命令已不再推荐,统一写进 up:

bash 复制代码
# 起 3 个 web 实例
docker compose up -d --scale web=3

两条硬规则:

  1. 服务一旦写了 container_name,就无法扩缩容 ------Docker 不允许同名容器。要扩就把 container_name 删掉,让 Compose 自动命名(项目-服务-序号);
  2. 扩了实例就不能固定端口映射 。3 个 web 都抢宿主机的 8080 会冲突,正确做法是让前面加一层反向代理(nginx),或者只 expose 不 ports。
🔹 version
bash 复制代码
docker compose version

📌 4.5 三个命令的关系

你的目的 该用哪个 结果
改完代码,想让新代码生效 docker compose up -d --build 重建镜像 + 重建容器
只重启进程(比如内存泄漏) docker compose restart web 容器不变,进程重启
清场重来 docker compose down -v 容器、网络、卷全删

🐳 五、docker-compose.yml 指令详解

📌 5.1 几条总规则

  • 默认文件名 docker-compose.yml,内容是 YAML ,缩进用空格、不用 Tab;
  • 每个服务必须至少有 image 或 build,否则不知道镜像从哪来;
  • 用了 build,Dockerfile 里的 CMD、EXPOSE、VOLUME、ENV 会被自动继承,yml 里不用抄一遍;
  • 大多数指令都能和 docker run 的某个参数对上号,学过 docker run 就等于学了一半。

💡 「自动继承」要补一句:yml 里写了 command,它会盖掉 Dockerfile 的 CMD。继承 ≠ 不可覆盖。

下面按功能分组,比按字母顺序背有效。

📌 5.2 构建与镜像

🔹 build

指定 Dockerfile 所在目录(绝对路径或相对 yml 的路径),Compose 据此构建镜像并使用。

yaml 复制代码
services:
  web:
    build:
      context: .                    # 构建上下文目录
      dockerfile: Dockerfile        # 文件名,默认就是 Dockerfile
      args:                         # 构建参数,对应 Dockerfile 里的 ARG
        APP_ENV: prod
      cache_from:                   # 指定可复用的缓存镜像
        - likeboard-web:0.9
      target: runtime               # 多阶段构建时只构建到某个阶段

最简写法 build: ./api,只给路径。

⚠️ 构建上下文 = 整个目录会被打包发给 Docker daemon 。把 node_modules、.git、target/ 这种大目录放进上下文,构建会明显变慢,务必写 .dockerignore。

🔹 image

指定镜像名或镜像 ID,本地没有就自动拉取。

yaml 复制代码
services:
  cache:
    image: redis:7-alpine           # 名字:标签
  db:
    image: postgres:16              # 带仓库路径也可以 mysql:8.0
  legacy:
    image: a4bc65fd                 # 直接用镜像 ID(不推荐,可读性差)

build 和 image 同时出现时,image 相当于给构建出来的镜像打标签,方便推仓库。

📌 5.3 启动控制与生命周期

🔹 command

覆盖容器启动命令(会盖掉 Dockerfile 的 CMD)。

yaml 复制代码
services:
  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "512mb"]

⚠️ 列表写法更安全 。字符串写法 command: redis-server --appendonly yes 会走 shell 解析,引号和变量容易被吃掉。

🔹 entrypoint

覆盖入口点。和 command 的关系是:entrypoint 是「主程序」,command 是「参数」。

yaml 复制代码
services:
  api:
    entrypoint: ["/app/entrypoint.sh"]
    command: ["--mode", "server"]
🔹 container_name

指定容器名。不写时按 项目-服务-序号 自动生成。

yaml 复制代码
services:
  web:
    container_name: likeboard-web

⚠️ 写了它就不能 --scale (重名冲突),而且多个项目共存时容易撞名字。除非脚本里要按名字 exec,一般建议不写。

🔹 restart

退出后的重启策略。

yaml 复制代码
services:
  web:
    restart: unless-stopped
取值 含义
no 不重启(默认)
always 总是重启
on-failure[:N] 非 0 退出才重启,可限次数
unless-stopped 总是重启,除非被手动 stop(生产推荐)

💡 生产选 unless-stopped 而不是 always:手动 docker compose stop 之后,always 会在 Docker 重启时又把它拉起来,运维会很困惑。

🔹 stop_signal

自定义停止信号,默认 SIGTERM。

yaml 复制代码
services:
  nginx:
    stop_signal: SIGQUIT      # nginx 优雅退出用 SIGQUIT
🔹 healthcheck

用命令判断容器是否健康。

yaml 复制代码
services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/healthz"]
      interval: 10s         # 多久查一次
      timeout: 3s           # 单次超时
      retries: 3            # 连续失败几次判为 unhealthy
      start_period: 20s     # 启动宽限期,这期间的失败不计入 retries
字段 说明
test ["CMD", ...] 直接执行;["CMD-SHELL", "..."] 走 shell(可用 &&、变量)
interval 检查间隔
timeout 单次检查超时
retries 连续失败阈值
start_period 启动宽限,避免慢启动服务被误判

💡 start_period 非常关键 。Java、Python 服务启动动辄二三十秒,不设宽限期会一直被判 unhealthy,depends_on: condition: service_healthy 就永远等不到。

🔹 depends_on

解决启动顺序。

yaml 复制代码
services:
  web:
    depends_on:
      redis:
        condition: service_healthy     # 等 redis 健康
      mysql:
        condition: service_started     # 只等它启动
condition 含义
service_started 容器起来了就走(约等于短语法)
service_healthy 等对方健康检查通过
service_completed_successfully 等对方执行完并成功退出(适合一次性初始化任务)

⚠️ 短语法 depends_on: [redis] 只保证启动顺序,不保证对端可用 。要真正等就绪,必须用长语法 + healthcheck;没有健康检查可用时,就在代码里做重试(3.2 节的 get_client() 就是干这个的)。

🔹 stdin_open / tty
yaml 复制代码
services:
  shell:
    stdin_open: true      # 等于 docker run -i
    tty: true             # 等于 docker run -t

主要用于调试型容器,等价于 docker run -it。

📌 5.4 网络

🔹 ports

端口映射,两种写法:宿主端口:容器端口,或只写容器端口(宿主机随机分配)。

yaml 复制代码
services:
  web:
    ports:
      - "8080:8080"                 # 宿主:容器
      - "9090:9090/tcp"             # 指定协议
      - "127.0.0.1:8081:8080"       # 只绑本机回环,不对外
      - "3000"                      # 只写容器端口,宿主随机

⚠️ 端口一律加引号 。YAML 会把 xx:yy 当成六十进制数字 解析,22:22、8080:8080 这类写成裸数字可能得到意外的值。- "8080:8080" 的引号不是排版习惯,是语法必需。

🔹 expose

只对同一网络内的服务开放端口,不映射到宿主机。

yaml 复制代码
services:
  api:
    expose:
      - "8080"
指令 谁能访问
ports 宿主机 + 同网络服务
expose 仅同网络服务
🔹 networks

把服务接入自定义网络。

yaml 复制代码
services:
  web:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true        # 内部网络,不能访问外网

💡 internal: true 是隔离利器 :数据库只挂 backend,这个网段没有出口,容器被攻破也连不出去。

🔹 network_mode

直接套用某种网络模式,取值同 docker run --network。

yaml 复制代码
services:
  monitor:
    network_mode: "host"          # 共享宿主机网络栈
  debug:
    network_mode: "service:web"   # 复用另一个服务的网络命名空间
取值 含义
bridge 默认桥接
host 共享宿主机网络栈(第六章 Redis Cluster 必须用)
none 无网络
service:<name> 复用指定服务的网络
container:<name/id> 复用指定容器网络
yaml 复制代码
services:
  web:
    dns:
      - 223.5.5.5
      - 8.8.8.8
    dns_search:
      - example.com
    extra_hosts:
      - "api.internal:192.168.2.10"    # 写进容器 /etc/hosts

extra_hosts 等价于 docker run --add-host,适合「不想动 DNS,只想让容器里某个域名指向固定 IP」的场景。

yaml 复制代码
services:
  web:
    links:
      - redis
    external_links:
      - legacy-db:mysql

links 是早期桥接网络时代的补丁,现在自定义网络 + 服务名 DNS 已经把它覆盖了,新项目不要用。external_links 用于连接 yml 之外的容器,同样不推荐。

📌 5.5 存储

🔹 volumes

三种写法,用途完全不同:

yaml 复制代码
services:
  db:
    volumes:
      - mysql-data:/var/lib/mysql              # ① 命名卷(Docker 管理)
      - ./conf/my.cnf:/etc/mysql/my.cnf:ro     # ② 绑定挂载(宿主目录,只读)
      - /tmp                         # ③ 匿名卷
volumes:
  mysql-data:                                  # 声明命名卷
类型 写法 数据在哪 适合
命名卷 name:/容器路径 Docker 管理区(/var/lib/docker/volumes) 数据库、中间件数据,性能好、可备份
绑定挂载 ./dir:/容器路径 你自己指定的宿主目录 配置文件、代码热更新
匿名卷 /容器路径 Docker 随机命名 临时数据,容器删了就没了

💡 数据库数据一定用命名卷,不要用绑定挂载。绑定挂载在 Mac/Windows 上跨文件系统性能很差,而且权限问题一堆。

🔹 tmpfs

挂内存文件系统,容器停就没了,适合临时缓存、敏感文件。

yaml 复制代码
services:
  web:
    tmpfs:
      - /tmp:size=64m,mode=1777
🔹 secrets / configs

secrets 存敏感数据,容器内以文件 形式出现(/run/secrets/<名字>),不会出现在 docker inspect 的环境变量里。

yaml 复制代码
services:
  mysql:
    environment:
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/mysql_root_pwd
    secrets:
      - mysql_root_pwd

secrets:
  mysql_root_pwd:
    file: ./secrets/mysql_root_pwd.txt    # 从文件读
  external_token:
    external: true                        # 引用已存在的 secret

configs 同理,但只在 Swarm 模式下可用,单机 Compose 用不上。

📌 5.6 环境变量

🔹 environment

字典或数组两种写法:

yaml 复制代码
services:
  web:
    environment:
      APP_ENV: prod              # 字典
      TZ: Asia/Shanghai
      DEBUG_FLAG: "false"        # 布尔词必须加引号
    # environment:
    #   - APP_ENV=prod           # 数组等价写法
    #   - TZ=Asia/Shanghai

⚠️ YAML 布尔陷阱 :值里出现 true/false、yes/no、on/off 这类词,一定加引号,否则会被解析成布尔值而不是字符串。完整清单:

y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF

只写键不写值时,会从宿主机取同名变量:

yaml 复制代码
    environment:
      AWS_SECRET_KEY:          # 留空 = 取宿主机环境变量
🔹 env_file

从文件批量读环境变量。

yaml 复制代码
services:
  web:
    env_file:
      - ./.env
      - ./env/web.env

.env:

text 复制代码
# 以 # 开头是注释
APP_ENV=prod
APP_PORT=8080

规则:变量名与 environment 冲突时,environment 优先 ;文件里每行一条 KEY=VALUE。

🔹 变量替换 ${}

编排文件里可以直接引用宿主环境变量 和 .env 文件:

yaml 复制代码
services:
  web:
    image: likeboard-web:${TAG:-latest}
    ports:
      - "${HOST_PORT:-8080}:8080"
bash 复制代码
# 指定标签启动
TAG=1.2.0 docker compose up -d
语法 含义
${VAR} 取变量,缺失则空
${VAR:-default} 缺失或空时用默认值
${VAR-default} 仅缺失时用默认值
${VAR:?err} 缺失则报错退出(关键变量防漏配)

优先级从高到低 :命令行前缀赋值 → shell 环境变量 → .env 文件 → yml 里的默认值。另外 environment 一定压过 env_file。

📌 5.7 资源、权限与内核参数

🔹 cap_add / cap_drop

增删内核能力。默认容器只保留有限能力,需要额外权限时按需加,不要直接 privileged。

yaml 复制代码
services:
  web:
    cap_add:
      - NET_ADMIN
    cap_drop:
      - ALL
🔹 cgroup_parent

指定父 cgroup,继承其资源限制。

yaml 复制代码
services:
  worker:
    cgroup_parent: workers.slice
🔹 ulimits

限制进程数、文件句柄数等。

yaml 复制代码
services:
  web:
    ulimits:
      nproc: 65535
      nofile:
        soft: 20000        # 应用可自行调高,但不得超过 hard
        hard: 40000        # 只有 root 能提高

💡 高并发服务(nginx、Redis、网关)的 nofile 不调,很容易出现 Too many open files。

🔹 sysctls

改容器内核参数。

yaml 复制代码
services:
  api:
    sysctls:
      net.core.somaxconn: 4096
      net.ipv4.tcp_syncookies: 0

⚠️ 并非所有 sysctl 都允许在容器内改,net.* 是允许的;kernel.* 这类通常需要 privileged 或直接在宿主设置。

🔹 devices / pid / security_opt / privileged / read_only
yaml 复制代码
services:
  iot:
    devices:
      - "/dev/ttyUSB0:/dev/ttyUSB0"     # 设备映射
    pid: "host"                          # 共享宿主 PID 命名空间
    security_opt:
      - label:user:app                   # SELinux 标签
      - no-new-privileges:true
    read_only: true                      # root 文件系统只读
    # privileged: true                   # 全权限,能不用就不用
🔹 deploy(仅 Swarm)
yaml 复制代码
services:
  web:
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: "0.50"
          memory: 512M

单机 docker compose 会忽略 deploy 段 ,资源限制要用 cpus/mem_limit(旧)或 deploy.resources(部分场景生效)。这是最容易踩的坑之一。

📌 5.8 日志与元数据

🔹 logging
yaml 复制代码
services:
  web:
    logging:
      driver: json-file
      options:
        max-size: "50m"       # 单文件上限
        max-file: "5"         # 最多保留几个

三种驱动:json-file(默认)、syslog、none。syslog 可以再配 syslog-address: "tcp://192.168.2.20:514"。

💡 max-size + max-file 是生产必配。不限制的话,一个话痨服务能在几天内把磁盘写满。

🔹 labels

给容器打元数据,便于筛选、归属管理。

yaml 复制代码
services:
  web:
    labels:
      com.example.owner: platform
      com.example.env: prod
      com.example.version: "1.0.0"
bash 复制代码
# 按标签筛选容器
docker ps --filter "label=com.example.env=prod"

📌 5.9 其余指令速查

指令 作用 示例
hostname 容器主机名 hostname: web-01
domainname 搜索域 domainname: example.com
user 运行用户 user: "1000:1000"
working_dir 工作目录 working_dir: /app
mac_address MAC 地址 mac_address: "02:42:ac:11:00:02"
shm_size /dev/shm 大小 shm_size: 256m
ipc IPC 命名空间 ipc: "host"
init 用 tini 做 PID 1,处理信号与僵尸进程 init: true
platform 指定架构 platform: linux/amd64
profiles 按需启用的服务分组 profiles: ["debug"]

💡 init: true 很值 :应用没正确转发 SIGTERM 时,加它能让容器「优雅停止」而不是等 10 秒被强杀。

📌 5.10 一份接近生产形态的参考模板

把上面的指令组合起来,看一份能直接改成自己项目用的完整文件:

yaml 复制代码
# 公共环境变量锚点,避免重复
x-common-env: &common-env
  TZ: Asia/Shanghai
  LANG: C.UTF-8

services:
  gateway:
    image: nginx:1.27-alpine
    container_name: demo-gateway
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/certs:/etc/nginx/certs:ro
      - ./logs/nginx:/var/log/nginx
    depends_on:
      api:
        condition: service_healthy
    networks:
      - frontend
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      args:
        APP_ENV: prod
    image: demo-api:1.2.0
    container_name: demo-api
    restart: unless-stopped
    env_file:
      - ./.env
    environment:
      <<: *common-env
      DB_HOST: mysql
      CACHE_HOST: redis
      JAVA_OPTS: "-Xms512m -Xmx1024m"
    expose:
      - "8080"
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1:8080/healthz || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 40s
    volumes:
      - ./config:/app/config:ro
    networks:
      - frontend
      - backend

  mysql:
    image: mysql:8.0
    container_name: demo-mysql
    restart: unless-stopped
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    environment:
      MYSQL_ROOT_PASSWORD_FILE: /run/secrets/mysql_root_pwd
      MYSQL_DATABASE: demo
    secrets:
      - mysql_root_pwd
    volumes:
      - mysql-data:/var/lib/mysql
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping --silent"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
    networks:
      - backend

  redis:
    image: redis:7-alpine
    container_name: demo-redis
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "512mb", "--maxmemory-policy", "allkeys-lru"]
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true          # 数据层不出网

volumes:
  mysql-data:
  redis-data:

secrets:
  mysql_root_pwd:
    file: ./secrets/mysql_root_pwd.txt

这份模板里每处设计都能对上前面讲的指令:

设计 对应指令 解决什么
nginx 只暴露 80/443,api 用 expose ports vs expose 应用不直接对外,减少暴露面
数据层只在 backend 且 internal: true networks 数据库无法访问外网
全部服务有 restart restart 进程崩溃能自愈
start_period: 40s healthcheck 慢启动服务不被误判
depends_on.condition: service_healthy depends_on 真的等到能服务才启动上层
密码走 secrets 文件 secrets 不出现在 inspect 和日志里
日志限 50m×5 logging 磁盘不会被写满
x-common-env 锚点 + <<: 合并 YAML 锚点 公共变量只写一次

🐳 六、实战:Compose 部署 Redis Cluster

📌 6.1 为什么必须用 host 网络

Redis 官方文档里有一条硬性要求:想让 Redis Cluster 和 Docker 共存,容器必须使用 host 网络模式。原因是这句话:

Redis Cluster 不支持 NAT 环境,也不支持 IP 地址或 TCP 端口被重映射的环境。

Docker 默认用端口映射 :容器里的进程以为自己监听在 A 端口,对外暴露的却是 B 端口。而集群要靠总线上互相通告地址 ,客户端拿到 MOVED 之后还要按通告的地址直连目标节点。一旦端口被映射改过:节点通告出去的地址别人连不上,客户端拿到的重定向地址也是错的,集群要么建不起来,要么状态一直异常。

host 模式 (network_mode: "host")让容器共享宿主机网络栈 ,不虚拟网卡、不单独分配 IP,直接使用宿主机的 IP 和端口。这样节点通告的地址就是真实可达的地址,问题从根上消失。

🧠 核心要点 :Cluster 靠 Gossip 通告 + 槽位重定向工作,地址必须是「别人真能连上的地址」。端口映射会让通告地址失真,所以必须 host 网络。

📌 6.2 环境与规划

单机模拟集群,192.168.2.132,6 个实例:

角色 服务端口 总线端口 说明
主节点 6371 / 6372 / 6373 16371 / 16372 / 16373 分走 16384 个槽
从节点 6374 / 6375 / 6376 16374 / 16375 / 16376 各复制一个主节点

为什么从 6371 开始而不是 6379 ?因为总线端口是 服务端口 + 10000,选 6371~6376 正好得到 16371~16376,不会和已有服务撞车。

目录规划:

text 复制代码
~/docker/redis-cluster/
├── redis-cluster.tmpl          # 配置模板
├── 6371/conf/redis.conf        # 由模板生成
├── 6371/data/                  # AOF、nodes.conf
├── 6372/conf/redis.conf
├── 6372/data/
├── ...
└── 6376/data/

docker-compose.yml 放在这个目录的上一级 ~/docker/ 下,路径更好写。

📌 6.3 五步总览

  1. 写配置模板 (一份带 ${PORT} 占位的 redis-cluster.tmpl);
  2. 批量生成 6 份 redis.conf(envsubst 循环);
  3. 写 docker-compose.yml(6 个服务,host 网络);
  4. 启动 6 个容器;
  5. 用 redis-cli --cluster create 组集群。

📌 6.4 配置模板

bash 复制代码
mkdir -p ~/docker/redis-cluster
cd ~/docker/redis-cluster
vim redis-cluster.tmpl
text 复制代码
# 服务端口与总线端口由模板变量注入
port ${PORT}
requirepass LJredis1234
masterauth LJredis1234
protected-mode no
daemonize no
appendonly yes
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 15000
cluster-announce-ip 192.168.2.132
cluster-announce-port ${PORT}
cluster-announce-bus-port 1${PORT}

逐项解释:

配置项 作用
port ${PORT} 节点监听端口,由环境变量注入
requirepass 客户端访问密码
masterauth 从节点连主节点时用的密码,必须与 requirepass 一致
protected-mode no 关闭保护模式,允许非同机访问(有密码兜底)
daemonize no 必须 no:容器里 PID 1 必须前台运行
appendonly yes 开启 AOF,重启不丢数据
cluster-enabled yes 开启集群模式
cluster-config-file 集群拓扑文件(记录所有节点与槽分配)
cluster-node-timeout 15000 节点失联判定超时,15 秒
cluster-announce-ip 对外通告的 IP,填宿主机 IP
cluster-announce-port 对外通告的服务端口
cluster-announce-bus-port 对外通告的总线端口,1${PORT} 即端口前加 1

两个关键点展开说:

为什么 daemonize 必须是 no :容器要求 PID 1 前台运行。设成 yes,Redis 会 fork 到后台、主进程退出,容器会立刻退出。这是容器化的铁律。

为什么 masterauth 要和 requirepass 相同 :主从复制时从节点要主动连主节点,主节点要求认证。从节点没有密码就会 NOAUTH,主从同步直接失败,集群也只能看到 master_link_status:down。

📌 6.5 两个端口的分工

每个集群节点都要开两个 TCP 端口:

端口 用途
服务端口(如 6371) 给客户端用的正常 Redis 端口
总线端口(服务端口 +10000,如 16371) 集群总线,节点间用二进制协议通信

总线端口负责:故障检测、配置更新、故障转移授权。

两条纪律:

  1. 客户端不要连总线端口,一律连服务端口;
  2. 防火墙两个端口都要放开,否则节点之间通不了,集群直接瘫。

🧠 核心要点 :总线端口 = 服务端口 + 10000 。模板里 cluster-announce-bus-port 1${PORT} 就是在端口前加 1,6371 → 16371。

📌 6.6 批量生成 6 份配置

bash 复制代码
cd ~/docker/redis-cluster

for port in $(seq 6371 6376); do \
  mkdir -p ${port}/conf ${port}/data \
  && PORT=${port} envsubst < redis-cluster.tmpl > ${port}/conf/redis.conf; \
done

一条循环完成三件事:建目录 → 替换 ${PORT} 生成配置 → 建数据目录。6 份配置一次生成,避免手改出错。

检查结果:

bash 复制代码
tree -L 3 ~/docker/redis-cluster
text 复制代码
/home/LJ/docker/redis-cluster
├── 6371
│   ├── conf
│   │   └── redis.conf
│   └── data
├── 6372
│   ├── conf
│   │   └── redis.conf
│   └── data
├── 6373
│   ├── conf
│   │   └── redis.conf
│   └── data
├── 6374
│   ├── conf
│   │   └── redis.conf
│   └── data
├── 6375
│   ├── conf
│   │   └── redis.conf
│   └── data
├── 6376
│   ├── conf
│   │   └── redis.conf
│   └── data
└── redis-cluster.tmpl

抽查一份,确认变量被替换了:

bash 复制代码
cat ~/docker/redis-cluster/6371/conf/redis.conf
text 复制代码
port 6371
requirepass LJredis1234
masterauth LJredis1234
protected-mode no
daemonize no
appendonly yes
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 15000
cluster-announce-ip 192.168.2.132
cluster-announce-port 6371
cluster-announce-bus-port 16371

其余 5 份只有端口相关的三行不同:

节点 port / announce-port announce-bus-port
6371 6371 16371
6372 6372 16372
6373 6373 16373
6374 6374 16374
6375 6375 16375
6376 6376 16376

💡 模板 + envsubst 的收益就在这里:只有端口在变,其余配置收敛在一处,改一个参数 6 个节点同时生效。

📌 6.7 编排文件

在 ~/docker/ 下创建 docker-compose.yml:

yaml 复制代码
services:
  redis-6371:
    image: redis:7-alpine
    container_name: redis-6371
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6371/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6371/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

  redis-6372:
    image: redis:7-alpine
    container_name: redis-6372
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6372/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6372/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

  redis-6373:
    image: redis:7-alpine
    container_name: redis-6373
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6373/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6373/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

  redis-6374:
    image: redis:7-alpine
    container_name: redis-6374
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6374/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6374/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

  redis-6375:
    image: redis:7-alpine
    container_name: redis-6375
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6375/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6375/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

  redis-6376:
    image: redis:7-alpine
    container_name: redis-6376
    restart: always
    network_mode: "host"
    volumes:
      - /home/LJ/docker/redis-cluster/6376/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6376/data:/data
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

每个键的作用:

键 作用
image: redis:7-alpine 官方镜像,本地没有会自动拉
container_name 固定名字,方便 docker exec
restart: always 挂了自动拉起
network_mode: "host" 关键,见 6.1
第一个 volumes 配置文件挂进去,只读 (:ro)
第二个 volumes 数据目录挂出去,AOF 和 nodes.conf 落在这里
command 用我们生成的配置启动,会覆盖镜像默认命令

两个挂载都是命门:

  1. 不挂配置 :容器用镜像默认配置(6379、cluster-enabled no),集群根本建不起来;
  2. 不挂数据 :容器删了 AOF 和 nodes.conf 一起没,数据丢失、拓扑重置。

⚠️ 这份文件里没有 ports 。host 模式下容器直接占用宿主机端口,6371 就是宿主机的 6371,再写端口映射会冲突。不是漏写,是不该写。
💡 6 个服务高度重复,用 YAML 锚点可以压缩成一半:

yaml 复制代码
x-redis-base: &redis-base
  image: redis:7-alpine
  restart: always
  network_mode: "host"
  command: ["redis-server", "/usr/local/etc/redis/redis.conf"]

services:
  redis-6371:
    <<: *redis-base
    container_name: redis-6371
    volumes:
      - /home/LJ/docker/redis-cluster/6371/conf/redis.conf:/usr/local/etc/redis/redis.conf:ro
      - /home/LJ/docker/redis-cluster/6371/data:/data

但新手建议先写全,出问题时逐字段对照更直观。

📌 6.8 启动

bash 复制代码
cd ~/docker
docker compose up -d
text 复制代码
[+] Running 6/6
 ✔ Container redis-6376  Started
 ✔ Container redis-6374  Started
 ✔ Container redis-6372  Started
 ✔ Container redis-6371  Started
 ✔ Container redis-6373  Started
 ✔ Container redis-6375  Started

逐个确认状态:

bash 复制代码
docker compose ps
text 复制代码
NAME         IMAGE            COMMAND                  SERVICE      STATUS         PORTS
redis-6371   redis:7-alpine   "docker-entrypoint.s..."   redis-6371   Up 8 seconds
redis-6372   redis:7-alpine   "docker-entrypoint.s..."   redis-6372   Up 8 seconds
redis-6373   redis:7-alpine   "docker-entrypoint.s..."   redis-6373   Up 8 seconds
redis-6374   redis:7-alpine   "docker-entrypoint.s..."   redis-6374   Up 8 seconds
redis-6375   redis:7-alpine   "docker-entrypoint.s..."   redis-6375   Up 8 seconds
redis-6376   redis:7-alpine   "docker-entrypoint.s..."   redis-6376   Up 8 seconds

看日志确认集群模式已开:

bash 复制代码
docker compose logs redis-6371
text 复制代码
redis-6371  | 1:C 18 Nov 2026 20:11:03.412 # oO0OoO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0OoO0Oo
redis-6371  | 1:C 18 Nov 2026 20:11:03.412 # Redis version=7.2.5, bits=64, commit=00000000, modified=0, pid=1, just started
redis-6371  | 1:C 18 Nov 2026 20:11:03.412 # Configuration loaded
redis-6371  | 1:M 18 Nov 2026 20:11:03.413 * Running mode=cluster, port=6371.
redis-6371  | 1:M 18 Nov 2026 20:11:03.413 # Server initialized
redis-6371  | 1:M 18 Nov 2026 20:11:03.413 * Ready to accept connections

三行关键信息:

  1. Running mode=cluster, port=6371 ------ cluster-enabled yes 生效了,是集群模式不是单机模式;
  2. 没看到 No cluster configuration found ------ 说明 data/ 里已有 nodes.conf(首次启动才会有那条提示,属于正常现象);
  3. Ready to accept connections ------ 端口已监听。

如果宿主机 somaxconn 偏小,还会看到一条 warn:

text 复制代码
# WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.

不影响搭建,但生产要调大:

bash 复制代码
# 临时生效
sudo sysctl -w net.core.somaxconn=4096
# 永久生效
echo "net.core.somaxconn = 4096" | sudo tee -a /etc/sysctl.conf

同理还有 vm.overcommit_memory = 1,避免低内存时后台 RDB 保存失败。

📌 6.9 创建集群

进任意一个节点:

bash 复制代码
docker exec -it redis-6371 bash
cd /usr/local/bin/

💡 进 /usr/local/bin/ 是因为 redis-cli、redis-server 都装在这个目录,进去之后直接用命令名,不用写全路径。

组集群:

bash 复制代码
redis-cli -a LJredis1234 --cluster create \
  192.168.2.132:6371 192.168.2.132:6372 192.168.2.132:6373 \
  192.168.2.132:6374 192.168.2.132:6375 192.168.2.132:6376 \
  --cluster-replicas 1

会先打印分配方案让你确认,必须手输 yes:

text 复制代码
>>> Performing hash slots allocation on 6 nodes...
Master[0] -> Slots 0 - 5460
Master[1] -> Slots 5461 - 10922
Master[2] -> Slots 10923 - 16383
Adding replica 192.168.2.132:6374 to 192.168.2.132:6371
Adding replica 192.168.2.132:6375 to 192.168.2.132:6372
Adding replica 192.168.2.132:6376 to 192.168.2.132:6373
>>> Trying to optimize slaves allocation for anti-affinity
[WARNING] Some slaves are in the same host as their master
M: 6f3a9c1d8b7e4250a1c9f6d2e8b04c73a1d5e920 192.168.2.132:6371
   slots:[0-5460] (5461 slots) master
M: 2b7d4e8f1a3c5906d7e2b8f4a6c10d95e3f7b2a8 192.168.2.132:6372
   slots:[5461-10922] (5462 slots) master
M: 9c1e5a7b3d2f4806a9c4e7b1d5f82a30c6e9b4d7 192.168.2.132:6373
   slots:[10923-16383] (5461 slots) master
S: 4d8b2f6a1c9e7305b2d8a4f6c1e95b37a0d2c8f4 192.168.2.132:6374
   replicates 2b7d4e8f1a3c5906d7e2b8f4a6c10d95e3f7b2a8
S: 7a3c9e1b5d4f8206c1e7a3b9d5f24c68e0b1d7a3 192.168.2.132:6375
   replicates 9c1e5a7b3d2f4806a9c4e7b1d5f82a30c6e9b4d7
S: 1e6b9d3a7c2f5804d6b1e8a5c3f97d20b4e7c1a9 192.168.2.132:6376
   replicates 6f3a9c1d8b7e4250a1c9f6d2e8b04c73a1d5e920
Can I set the above configuration? (type 'yes' to accept): yes
>>> Nodes configuration updated
>>> Assign a different config epoch to each node
>>> Sending CLUSTER MEET messages to join the cluster
Waiting for the cluster to join
..
>>> Performing Cluster Check (using node 192.168.2.132:6371)
[OK] All nodes agree about slots configuration.
>>> Check for open slots...
>>> Check slots coverage...
[OK] All 16384 slots covered.

怎么读这段输出:

输出片段 含义
Performing hash slots allocation on 6 nodes... 开始分配哈希槽
Master[0] -> Slots 0 - 5460 等三行 16384 个槽三等分:5461 + 5462 + 5461
Adding replica ...:6374 to ...:6371 给每个主节点挂一个从节点
[WARNING] Some slaves are in the same host as their master 单机搭建的必然警告:主从同机,无物理容灾
M: / S: M=Master,S=Slave
slots:[0-5460] (5461 slots) master 负责的槽区间与角色
slots: (0 slots) slave + replicates <id> 从节点不分槽,只复制指定主节点
type 'yes' to accept 必须输 yes ,输 y 不认
Sending CLUSTER MEET messages 节点互相握手成集群
Waiting for the cluster to join + .. 等状态收敛
All nodes agree about slots configuration 所有节点对槽分配达成一致
All 16384 slots covered 16384 个槽全覆盖,集群可用

验收只看最后两行 :All nodes agree about slots configuration 和 All 16384 slots covered。

🧠 --cluster create 干的五件事 :分槽 (16384 平均给 3 个 master)→ 配从 (--cluster-replicas 1 决定每主 1 从)→ 定 epoch (每节点不同 config epoch,故障转移比新旧用)→ MEET (总线上互相握手)→ check(检查槽覆盖)。

📌 6.10 集群形态

6 个节点、3 主 3 从:

  • 三个主节点分走全部槽,负责处理客户端请求;
  • 三个从节点复制对应主节点,主节点故障时顶上。

节点间关系可以画成三层:

text 复制代码
      客户端(读写)                客户端(只读)
           │                            │
           ▼                            ▼
      ┌─────────┐                 ┌─────────┐
      │ Master  │◀─── 复制 ───────│  Slave  │
      │  6371   │                 │  6376   │
      └────┬────┘                 └─────────┘
           │ 集群总线(Gossip:故障检测 / 配置更新 / 故障转移授权)
           ▼
      ┌─────────┐   ┌─────────┐
      │ Master  │   │ Master  │
      │  6372   │   │  6373   │
      └────┬────┘   └────┬────┘
           │             │
      ┌─────────┐   ┌─────────┐
      │ Slave   │   │ Slave   │
      │  6374   │   │  6375   │
      └─────────┘   └─────────┘

读写走 master,读请求可以分流到 slave;master 挂了,slave 通过总线上的投票拿到授权后升主。

📌 6.11 查看状态与验证读写

🔹 整体体检
bash 复制代码
redis-cli -a LJredis1234 --cluster check 192.168.2.132:6375

连任一节点,输出整个集群的槽分配与节点健康状况。看到 [OK] All 16384 slots covered 就说明健康。

🔹 集群信息与节点信息
bash 复制代码
# 连集群某节点(-c = cluster 模式,自动跟随重定向)
redis-cli -c -a LJredis1234 -h 192.168.2.132 -p 6376

在交互里执行:

text 复制代码
192.168.2.132:6376> CLUSTER INFO
cluster_enabled:1
cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384
cluster_known_nodes:6
cluster_size:3
cluster_current_epoch:6
cluster_my_epoch:1

192.168.2.132:6376> CLUSTER NODES
6f3a9c1d... 192.168.2.132:6371@16371 master - 0 1731930063412 1 connected 0-5460
2b7d4e8f... 192.168.2.132:6372@16372 master - 0 1731930063000 2 connected 5461-10922
9c1e5a7b... 192.168.2.132:6373@16373 master - 0 1731930062900 3 connected 10923-16383
4d8b2f6a... 192.168.2.132:6374@16374 slave 2b7d4e8f... 0 1731930063000 2 connected
7a3c9e1b... 192.168.2.132:6375@16375 slave 9c1e5a7b... 0 1731930063412 3 connected
1e6b9d3a... 192.168.2.132:6376@16376 myself,slave 6f3a9c1d... 0 1731930062000 1 connected
字段 含义
cluster_state:ok 集群状态正常(有槽未覆盖会变成 fail)
cluster_slots_assigned:16384 已分配槽数,等于 16384 才算完整
cluster_size:3 主节点数量(3)
@16371 总线端口,写在节点地址后面
connected 0-5460 该节点负责的槽区间,connected 表示链路正常
myself 当前连的这个节点
master / slave 角色
🔹 验证分片:两个 key 落到不同节点
text 复制代码
192.168.2.132:6376> set likeboard 1
-> Redirected to slot [905] located at 192.168.2.132:6371
OK

192.168.2.132:6371> set site demo
-> Redirected to slot [9421] located at 192.168.2.132:6372
OK

192.168.2.132:6372> get site
"demo"

192.168.2.132:6372> get likeboard
-> Redirected to slot [905] located at 192.168.2.132:6371
"1"

这段把分片讲透了:

  1. 客户端连的是 6376(一个从节点);
  2. likeboard 哈希到 slot 905 ,归 6371 ,于是返回 MOVED;
  3. 因为带了 -c ,客户端自动改连 6371 并重发 ,拿到 OK;
  4. site 哈希到 slot 9421 ,归 6372,又被重定向到 6372;
  5. 在 6372 上 get likeboard,仍然会被指回 6371 ------路由表在客户端,节点只负责指路。

可以用 CLUSTER KEYSLOT 自己核对槽号:

text 复制代码
192.168.2.132:6372> CLUSTER KEYSLOT likeboard
(integer) 905
192.168.2.132:6372> CLUSTER KEYSLOT site
(integer) 9421

💡 -c 就是「自动跟随 MOVED」 。不加 -c,你只会看到 (error) MOVED 905 192.168.2.132:6371,得自己换节点重连。

📌 6.12 清理与重建

bash 复制代码
cd ~/docker

# 停容器(保留数据)
docker compose stop

# 停并删容器,保留 data 目录里的 AOF 与 nodes.conf
docker compose down

# 连数据一起清,彻底重来
docker compose down -v
sudo rm -rf ~/docker/redis-cluster/637*/data/* ~/docker/redis-cluster/637*/conf/redis.conf

⚠️ 只想重建集群、不想丢数据 :不要删 data/nodes.conf。删了它,节点身份重置,--cluster create 会当成全新节点重来,原来的数据虽然还在 AOF 里,但槽映射和节点 ID 全变了,需要重新 meet 与 reshard,风险很高。


🐳 七、总结

📌 7.1 要点回顾

层面 要点
定位 官方编排工具,管「多容器应用的定义与运行」,前身 Fig,思路类似 OpenStack Heat
三层结构 项目(业务单元)→ 服务(一类容器)→ 容器实例(可多份);默认按项目管理
实现 Python 外壳,真正干活靠调 Docker API
配置文件 默认 docker-compose.yml,YAML,缩进用空格;每个服务必须有 image 或 build
继承规则 用 build 时 Dockerfile 的 CMD/EXPOSE/VOLUME/ENV 自动生效,但 yml 的 command 能覆盖 CMD
三个坑 ports 必须加引号(YAML 六十进制);depends_on 短语法不等就绪;container_name 一写就不能扩缩容
五个常用 up -d --build 起、ps 看、logs -f 追、exec 进、down -v 清
变量优先级 命令行 > shell 环境 > .env > yml 默认值;environment 压过 env_file
生产必配 restart: unless-stopped、logging 限 max-size/max-file、healthcheck + start_period、数据用命名卷
Redis Cluster 必须 network_mode: "host";总线端口 = 服务端口 +10000;两个端口都要放行

📌 7.2 上手核对清单

  • 编排文件里每个服务都有 image 或 build
  • 端口全部加了引号
  • 数据目录用的是命名卷,不是绑定挂载
  • 关键服务有 healthcheck,慢启动的配了 start_period
  • depends_on 用的是 condition: service_healthy(或代码里有重试)
  • 有 restart 策略,日志有 max-size/max-file
  • 密码走 secrets 或 env_file,没有硬编码在 yml 里
  • 需要扩缩容的服务没有写 container_name
  • Redis/MySQL 这类有状态服务,volume 挂到了 /data 或 /var/lib/mysql
  • 集群场景确认用了 host 网络 ,且防火墙放行了两个端口

🐳 八、常见面试题

📌 Q1:Compose 是什么?它补上了 Dockerfile 的哪个短板?

答 :Compose 是 Docker 官方提供的编排工具 ,负责「多个容器组成的一个应用」的定义与运行,前身是 Fig,思路上和 OpenStack 的 Heat 类似。

Dockerfile 的边界是一个容器 :它能描述一个镜像怎么构建出来,但描述不了几个容器怎么一起活 。真实项目往往是应用 + 数据库 + 缓存 + 反向代理,全靠 docker run 手拼,网络、挂载、顺序、环境变量会滚成一坨,且不可复现。

Compose 把这一组容器写成一份 docker-compose.yml,声明成一个「项目」,一条 up 全部起来。它本身是 Python 写的,底层调用 Docker API,所以只要有可用 Docker API 的平台都能用。


📌 Q2:服务(service)和项目(project)怎么区分?

答:

  • 服务 是一个应用的容器定义 ,背后可以是一个或多个跑同一镜像的实例------它是「角色」,不是某个具体容器;
  • 项目 是一组关联服务组成的完整业务单元,写在编排文件里。

三者是递进关系:项目 → 服务 → 容器实例 。Compose 默认按项目管理,命令不带服务名时作用于项目下所有服务。


📌 Q3:docker compose up 具体做了什么?容器已存在会怎么处理?

答 :up 按顺序完成 构建镜像 → 创建/重建服务 → 启动服务 → 接上关联容器,并顺带创建项目网络。

容器已存在时有三种策略:

  • 默认 :停旧容器、按最新 yml 重建(命名卷保留),保证配置最新;
  • --no-recreate :只把停止的容器补启动,运行中的不动;
  • --force-recreate :无条件重建,与上者互斥。

只想重部署某个服务,用 up --no-deps -d <服务名>,不牵连它依赖的服务 。另外默认是前台 运行、日志合并输出,Ctrl-C 会停掉全部;-d 转后台,生产用这个。


📌 Q4:depends_on 能保证依赖服务「启动完成」吗?

答 :短语法不能 。depends_on: [redis] 只解决启动顺序 ,不保证对端已经就绪能服务。容器起来了,里面的进程可能还在初始化。

要真正等到就绪,两条路:

  1. 配置层 :给被依赖服务加 healthcheck,依赖方用长语法 depends_on: {redis: {condition: service_healthy}},Compose 会等健康才启动;
  2. 代码层:在应用里做连接重试(有限次退避),这是最稳的兜底。

另外 start_period 很重要:慢启动服务不设宽限期会一直被判 unhealthy,service_healthy 就永远等不到。


📌 Q5:Compose 里 ports 为什么要加引号?

答 :因为 YAML 会把 xx:yy 这种形式解析成六十进制数字 (base-60),裸写 8080:8080、22:22 可能得到意料之外的值。

所以端口一律写成字符串:- "8080:8080"、- "49100:22"。这不是编码风格问题,是 YAML 的类型推断问题。

顺带区分:ports 会映射到宿主机 ,宿主和同网络服务都能访问;expose 只对同网络内的服务开放,不映射到宿主机。


📌 Q6:EXPOSE 和 ports 有什么区别?

答 :EXPOSE 写在 Dockerfile 里,只是元信息 ------告诉读镜像的人「这个服务监听 8080」,不发布任何端口,宿主机访问不到。

真正发布端口要在 yml 的 ports (或 docker run -p)里写映射。两者关系是:EXPOSE 是文档性质的声明,ports 是实际生效的映射。

同网络内的其他容器可以通过服务名 + 容器端口 直接访问,这一步甚至不需要 EXPOSE------EXPOSE 只影响 docker run -P 的自动映射和镜像可读性。


📌 Q7:为什么在 Docker 里部署 Redis Cluster 必须用 host 网络?

答 :因为 Redis Cluster 不支持 NAT,也不支持 IP/端口被重映射的环境。

Docker 默认的端口映射 会让「程序以为自己监听的端口」和「对外暴露的端口」不一致。而集群靠总线上的 Gossip 通告地址 ,客户端还要按 MOVED 给的地址直连目标节点 。一旦端口被 remap:节点通告的地址别人连不上,客户端拿到的重定向地址也是错的,集群要么建不起来,要么一直异常。

host 模式 (network_mode: "host")让容器共享宿主机网络栈,不虚拟网卡、不单独分配 IP,直接用宿主机 IP 和端口,通告地址变成真实可达的,问题从根上消失。


📌 Q8:集群节点的两个端口分别干什么?防火墙为什么要开两个?

答 :每个节点开两个 TCP 端口:

  1. 服务端口(如 6371):给客户端用的正常 Redis 端口;
  2. 总线端口 (服务端口 +10000 ,如 16371):集群总线 ,节点之间用二进制协议 通信,负责故障检测、配置更新、故障转移授权。

客户端不要连总线端口 ,只连服务端口;但防火墙两个都要放开,否则节点之间通不了,集群直接瘫。


📌 Q9:--cluster-replicas 1 什么意思?16384 个槽怎么分?

答 :--cluster-replicas 1 表示每个主节点配 1 个副本 。6 个节点就自然形成 3 主 3 从。

redis-cli --cluster create 依次做五件事:

  1. 分槽 :16384 平均给 3 个 master ------ 0-5460(5461)、5461-10922(5462)、10923-16383(5461),合计 16384;
  2. 配从 :按 --cluster-replicas 1 给每个 master 挂一个 replica;
  3. 定 epoch:给每个节点分配不同的 config epoch,故障转移时比新旧用;
  4. MEET:通过集群总线让节点互相握手;
  5. 校验 :cluster check 检查槽覆盖,输出 All nodes agree about slots configuration 和 All 16384 slots covered 才算成功。

三个主节点分走全部槽、处理客户端请求;从节点在主挂掉后顶替。


📌 Q10:集群里 set 一个 key 为什么会被「重定向」?

答 :因为集群是分片 的------每个 key 哈希到 16384 个槽之一,槽分布在不同 master 上,当前连的节点不一定管这个槽。

实测现象:

text 复制代码
192.168.2.132:6376> set likeboard 1
-> Redirected to slot [905] located at 192.168.2.132:6371
OK

客户端连的是 6376,但 likeboard 属于 slot 905 ,归 6371 管,于是返回 MOVED 重定向 指路。因为 redis-cli 带了 -c ,会自动改连目标节点重发,所以最终拿到 OK;不加 -c 就直接看到 (error) MOVED 905 192.168.2.132:6371。

这也说明:路由表缓存在客户端,节点只负责指路 ,所以集群客户端必须支持 MOVED / ASK 重定向。用 CLUSTER KEYSLOT likeboard 可以自己核对槽号。


📌 收尾 :这两块知识真正的价值,不在敲过多少命令,而在把因果链接上------Compose 用服务名做 DNS 解决容器互通,用 healthcheck + depends_on 解决启动顺序,用命名卷 解决数据持久化;Redis Cluster 用 host 网络 解决地址通告,用模板 + envsubst 解决配置重复,用 --cluster create + 16384 槽解决数据分片。这条链能讲顺,基本就不是背出来的了。

相关推荐
xbzb21 小时前
Kubernetes 节点删除后还有残留?drain、reset 与集群销毁重建全流程
容器·kubernetes·kubectl·集群·reset·drain
AI开源软件1 天前
Kubernetes 网络实战:打通 Pod、Service 与集群外任务调度器的双向调用
docker·nacos·kubernetes·xxl-job·calico·微服务部署·ruoyi office
csdn_aspnet1 天前
Docker 啟動MySQL Server連上MySQL Workbench
mysql·docker·容器
月夏1 天前
我把全栈项目塞进已有 nginx 的服务器,卡我最久的是三个斜杠
nginx·react.js·docker
瑞克-桑切斯2 天前
Kubernetes 1.28 保姆级新手学习教程
运维·学习·docker·云原生·容器·kubernetes
对象存储与RustFS2 天前
对象锁遇上版本化:删掉的对象还在,真删的又删不掉
后端·docker·云原生
遇雪长安2 天前
wslc 来了:Docker Desktop 还要留着吗?
运维·docker·容器
csdn_aspnet2 天前
【Docker 攻略】MySQL 安裝篇
运维·mysql·docker·容器
艺杯羹2 天前
ufw 已 active,Docker 端口却仍对外开放的复盘
运维·docker·容器