🐳 一个正常上线的项目,很少只有一个容器。应用一个、数据库一个、缓存一个、前面还压着反向代理------它们要一起存在、按顺序启动、彼此能按名字访问。手敲
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")))
三处值得单独说:
host="redis"是服务名,不是域名也不是 IP。容器重建后 IP 会变,服务名不会。- 重试是必须的 。
depends_on只保证启动顺序,不保证 Redis 已经能收命令,所以连接要自己兜底。 /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
两条硬规则:
- 服务一旦写了
container_name,就无法扩缩容 ------Docker 不允许同名容器。要扩就把container_name删掉,让 Compose 自动命名(项目-服务-序号); - 扩了实例就不能固定端口映射 。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> |
复用指定容器网络 |
🔹 dns / dns_search / extra_hosts
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」的场景。
🔹 links / external_links(不推荐)
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 五步总览
- 写配置模板 (一份带
${PORT}占位的redis-cluster.tmpl); - 批量生成 6 份
redis.conf(envsubst循环); - 写
docker-compose.yml(6 个服务,host 网络); - 启动 6 个容器;
- 用
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) | 集群总线,节点间用二进制协议通信 |
总线端口负责:故障检测、配置更新、故障转移授权。
两条纪律:
- 客户端不要连总线端口,一律连服务端口;
- 防火墙两个端口都要放开,否则节点之间通不了,集群直接瘫。
🧠 核心要点 :总线端口 = 服务端口 + 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 |
用我们生成的配置启动,会覆盖镜像默认命令 |
两个挂载都是命门:
- 不挂配置 :容器用镜像默认配置(6379、
cluster-enabled no),集群根本建不起来; - 不挂数据 :容器删了 AOF 和
nodes.conf一起没,数据丢失、拓扑重置。
⚠️ 这份文件里没有
ports。host 模式下容器直接占用宿主机端口,6371 就是宿主机的 6371,再写端口映射会冲突。不是漏写,是不该写。
💡 6 个服务高度重复,用 YAML 锚点可以压缩成一半:
yamlx-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
三行关键信息:
Running mode=cluster, port=6371------cluster-enabled yes生效了,是集群模式不是单机模式;- 没看到
No cluster configuration found------ 说明data/里已有nodes.conf(首次启动才会有那条提示,属于正常现象); 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"
这段把分片讲透了:
- 客户端连的是 6376(一个从节点);
likeboard哈希到 slot 905 ,归 6371 ,于是返回MOVED;- 因为带了
-c,客户端自动改连 6371 并重发 ,拿到OK; site哈希到 slot 9421 ,归 6372,又被重定向到 6372;- 在 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] 只解决启动顺序 ,不保证对端已经就绪能服务。容器起来了,里面的进程可能还在初始化。
要真正等到就绪,两条路:
- 配置层 :给被依赖服务加
healthcheck,依赖方用长语法depends_on: {redis: {condition: service_healthy}},Compose 会等健康才启动; - 代码层:在应用里做连接重试(有限次退避),这是最稳的兜底。
另外 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 端口:
- 服务端口(如 6371):给客户端用的正常 Redis 端口;
- 总线端口 (服务端口 +10000 ,如 16371):集群总线 ,节点之间用二进制协议 通信,负责故障检测、配置更新、故障转移授权。
客户端不要连总线端口 ,只连服务端口;但防火墙两个都要放开,否则节点之间通不了,集群直接瘫。
📌 Q9:--cluster-replicas 1 什么意思?16384 个槽怎么分?
答 :--cluster-replicas 1 表示每个主节点配 1 个副本 。6 个节点就自然形成 3 主 3 从。
redis-cli --cluster create 依次做五件事:
- 分槽 :16384 平均给 3 个 master ------
0-5460(5461)、5461-10922(5462)、10923-16383(5461),合计 16384; - 配从 :按
--cluster-replicas 1给每个 master 挂一个 replica; - 定 epoch:给每个节点分配不同的 config epoch,故障转移时比新旧用;
- MEET:通过集群总线让节点互相握手;
- 校验 :
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 槽解决数据分片。这条链能讲顺,基本就不是背出来的了。