Note
docker
介绍docker在ubantu下的简单使用,列出了docker常用命令。
介绍
docker是一种应用部署技术,把应用程序及其所需要的运行环境打包成一个独立的环境,这个环境也称为容器,应用程序运行在各自的容器中,这些容器之间相互隔离的,互不干扰。
- 核心作用
- 应用程序之间互不干扰。比如部署web项目,使用三个容器分别运行前端、后端、数据库,如果后端出现了内存泄漏,不会影响前端和数据库容器。
- 方便部署和管理。通常项目是在 Windows/macOS 开发,部署在linux云服务器。通过docker,可以现在 Windows/macOS 本地设置好项目上线后容器的相关配置(镜像),之后云服务器直接获取镜像,通过镜像创建并运行容器即可完成部署。后期通过docker相关的脚本(compose)可批量管理容器以实现批量管理线上项目。并且迁移项目也只需要在目标服务器获取镜像创建并运行容器。
- 与虚拟机的区别 docker容器之间都是使用同一个系统内核,而每个虚拟机都包含一个操作系统的完整内核,所以docker容器比虚拟机更轻量、启动速度更快。
运行容器的计算机被称为宿主机
docker概念图

docker部署的工作流程

镜像
镜像是容器的模板,通过镜像来生成容器。可以类比为镜像是软件安装包,容器是这个安装包安装出来的软件。
镜像仓库
docker有镜像仓库 https://hub.docker.com,用来存放镜像仓库的地方。可以上传镜像到仓库,也可以从仓库获取别人上传的镜像。docker高效部署的方式就是利用镜像仓库:在本地 Windows/macOS 制作需要上线的项目的镜像,然后发布到镜像仓库,云服务器上获取该镜像然后创建并运行容器,项目就上线了。镜像文件默认是名称为“Dockerfile”的无后缀文件。
操作镜像
命令语法约定
| 写法 | 含义 |
|---|---|
[OPTIONS] |
可选参数集合,具体参数在对应的参数表中说明 |
IMAGE |
镜像名称或镜像 ID |
IMAGE[:TAG] |
镜像名称及可选标签 |
NAME[:TAG|@DIGEST] |
镜像名称,可通过标签或摘要指定镜像版本 |
SOURCE_IMAGE、TARGET_IMAGE |
打标签时的源镜像和目标镜像名称 |
REPOSITORY |
镜像仓库名称,如 nginx 或 username/myapp |
TERM |
搜索镜像时使用的关键词 |
[SERVER] |
可选的镜像仓库地址,省略时使用 Docker Hub |
SOURCE |
文件系统归档路径、URL,或 -(从标准输入读取) |
CONTAINER |
容器名称或容器 ID |
VOLUME |
Docker 卷名称 |
NETWORK |
Docker 网络名称 |
PATH |
文件路径或目录路径 |
[COMMAND] |
可选的执行命令 |
[ARG...] |
可选的命令参数,可以有多个 |
... |
表示可以继续提供多个同类参数 |
查看镜像
查看镜像列表
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 查看所有镜像 | docker images [OPTIONS] |
docker images |
查看本地已有的镜像 |
| 查看镜像列表 | docker image ls [OPTIONS] [REPOSITORY[:TAG]] |
docker image ls nginx |
查看本地仓库名称为 nginx 的镜像 |
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
显示所有镜像,包括中间镜像 | docker images -a |
-q、--quiet |
只显示镜像 ID | docker images -q |
--digests |
显示镜像摘要 | docker images --digests |
-f、--filter |
根据条件过滤镜像 | docker images -f dangling=true |
--format |
自定义输出格式 | docker images --format "{{.Repository}}:{{.Tag}}" |
查看镜像详情
查看镜像的配置、架构、环境变量等信息。
docker image inspect [OPTIONS] IMAGE [IMAGE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--format |
只输出指定字段 | docker image inspect -f '{{.Os}}/{{.Architecture}}' nginx:alpine |
示例:
# 查看 nginx:alpine 镜像的详细信息,包括配置、架构和环境变量
docker image inspect nginx:alpine
搜索镜像
在 Docker Hub 搜索名称或描述匹配的镜像。
docker search [OPTIONS] TERM
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--filter |
根据条件过滤搜索结果 | docker search --filter is-official=true nginx |
--limit |
限制返回的结果数量 | docker search --limit 5 nginx |
--no-trunc |
不截断输出内容 | docker search --no-trunc nginx |
--format |
自定义输出格式 | docker search --format "{{.Name}}:{{.StarCount}}" nginx |
示例:
# 在 Docker Hub 搜索名称或描述中包含 nginx 的镜像
docker search nginx
构建镜像
根据当前目录的 Dockerfile 构建镜像。
docker build [OPTIONS] PATH
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-t、--tag |
指定构建结果的镜像名称和标签 | docker build -t myapp:1.0 . |
-f、--file |
指定 Dockerfile 的路径 | docker build -f Dockerfile.prod -t myapp:1.0 . |
--build-arg |
传递 Dockerfile 中声明的构建参数 | docker build --build-arg NODE_ENV=production -t myapp:1.0 . |
--no-cache |
不使用构建缓存 | docker build --no-cache -t myapp:1.0 . |
--pull |
尝试拉取更新的基础镜像 | docker build --pull -t myapp:1.0 . |
--target |
指定多阶段构建的目标阶段 | docker build --target production -t myapp:1.0 . |
--platform |
指定目标平台 | docker build --platform linux/amd64 -t myapp:1.0 . |
--progress |
指定构建进度输出模式 | docker build --progress plain -t myapp:1.0 . |
示例:
# 使用当前目录的 Dockerfile 构建镜像,并命名为 myapp:1.0
docker build -t myapp:1.0 .
# 使用 Dockerfile.prod 构建 myapp:1.0 镜像
# 传入 NODE_ENV=production 构建参数,并禁用构建缓存
docker build -f Dockerfile.prod \
--build-arg NODE_ENV=production \
--no-cache \
-t myapp:1.0 .
给镜像打标签
为已有镜像添加一个新名称或标签,供版本管理或发布使用。
docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
示例:
# 为本地 myapp:1.0 镜像添加 username/myapp:1.0 标签,供后续推送到仓库使用
docker tag myapp:1.0 username/myapp:1.0
登录镜像仓库
登录默认镜像仓库 Docker Hub,也可以指定仓库地址。
docker login [OPTIONS] [SERVER]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-u、--username |
指定登录用户名 | docker login -u username |
--password-stdin |
从标准输入读取密码或访问令牌 | cat token.txt | docker login -u username --password-stdin |
示例:
# 登录 Docker Hub
docker login
# 登录指定镜像仓库
docker login registry.example.com
拉取镜像
从镜像仓库获取指定标签的镜像。
docker pull [OPTIONS] NAME[:TAG|@DIGEST]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all-tags |
拉取指定仓库的所有标签 | docker pull -a nginx |
--platform |
指定拉取的平台 | docker pull --platform linux/amd64 nginx:alpine |
-q、--quiet |
减少输出信息 | docker pull -q nginx:alpine |
示例:
# 从 Docker Hub 拉取 nginx 镜像的 alpine 标签版本到本地
docker pull nginx:alpine
发布镜像
将指定镜像推送到有权限访问的镜像仓库。发布镜像时,镜像名称前必须带上用户名,这是官方为了区分相同名称的镜像做的规定。
docker push [OPTIONS] USERNAME/NAME[:TAG]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all-tags |
推送本地该仓库名称下的所有标签 | docker push -a username/myapp |
-q、--quiet |
减少输出信息 | docker push -q username/myapp:1.0 |
示例:
# 将本地 username/myapp:1.0 镜像推送到 Docker Hub 中有权限访问的对应仓库
docker push username/myapp:1.0
删除镜像
删除指定的本地镜像。
docker rmi [OPTIONS] IMAGE [IMAGE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
强制删除镜像 | docker rmi -f myapp:1.0 |
--no-prune |
不自动清理未标记的父镜像 | docker rmi --no-prune myapp:1.0 |
示例:
# 删除本地 myapp:1.0 镜像引用,不会删除远程仓库中的镜像
docker rmi myapp:1.0
查看构建历史
查看镜像的构建层及其历史。
docker history [OPTIONS] IMAGE
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--no-trunc |
不截断历史记录 | docker history --no-trunc myapp:1.0 |
-q、--quiet |
只显示镜像层 ID | docker history -q myapp:1.0 |
示例:
# 查看 myapp:1.0 镜像各层的构建历史
docker history myapp:1.0
导出镜像
将镜像保存到本地 tar 文件,适合离线传输。
docker image save [OPTIONS] IMAGE [IMAGE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-o、--output |
指定导出文件 | docker image save -o myapp.tar myapp:1.0 |
示例:
# 将 myapp:1.0 镜像及其标签导出为当前目录下的 myapp.tar 文件
docker image save -o myapp.tar myapp:1.0
导入镜像
从 tar 文件恢复 Docker 镜像。
docker image load [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-i、--input |
指定导入文件 | docker image load -i myapp.tar |
-q、--quiet |
抑制加载过程输出 | docker image load -q -i myapp.tar |
示例:
# 从 myapp.tar 文件恢复镜像及其标签到本地 Docker
docker image load -i myapp.tar
清理镜像
清理悬空镜像;添加 -a 时,清理所有未被现存容器引用的镜像。
docker image prune [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
清理所有未被容器引用的镜像,包括仍有标签的镜像 | docker image prune -a |
-f、--force |
不显示交互确认提示 | docker image prune -f |
--filter |
按条件过滤清理对象 | docker image prune -a --filter "until=168h" |
示例:
# 清理没有标签且未被容器引用的镜像
docker image prune
# 清理所有未被容器引用的镜像,包括仍有标签的镜像
docker image prune -a
从文件系统创建镜像
从文件系统归档创建新镜像,不等同于恢复完整的原镜像。
docker image import [OPTIONS] SOURCE [REPOSITORY[:TAG]]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-c、--change |
为导入的镜像设置受支持的 Dockerfile 指令 | docker image import -c "ENV NODE_ENV=production" rootfs.tar myapp:1.0 |
-m、--message |
添加导入说明 | docker image import -m "Import root filesystem" rootfs.tar myapp:1.0 |
--platform |
设置导入镜像的平台 | docker image import --platform linux/amd64 rootfs.tar myapp:1.0 |
示例:
# 将 rootfs.tar 中的文件系统导入为新的 myapp:1.0 镜像
docker image import rootfs.tar myapp:1.0
镜像名称和标签
镜像引用通常可以写成 [REGISTRY_HOST[:PORT]/][NAMESPACE/]REPOSITORY[:TAG]。
| 镜像引用 | 含义 |
|---|---|
nginx |
镜像名称为 nginx,未指定标签,通常默认使用 latest |
nginx:alpine |
镜像名称为 nginx,标签为 alpine |
myapp:1.0 |
本地或指定仓库中的 myapp 镜像,标签为 1.0 |
username/myapp:1.0 |
命名空间为 username 的 myapp 镜像 |
registry.example.com/team/myapp:1.0 |
从指定的私有或自建仓库引用镜像 |
容器
容器是根据镜像创建的运行实例,应用程序运行在各自容器中,各个容器之间相互隔离,互不干扰。容器拥有自己的运行配置和可写层,停止后仍可再次启动;删除容器时,其可写层也会被删除。
下文以 Linux 容器为例,常用容器名为 web,示例按各自的场景使用。命令完整说明可查阅 Docker 容器命令参考。
创建与启动容器
创建并运行容器
每次执行 docker run 都会创建一个新容器然后运行,未在本地找到所需镜像时,默认会先尝试拉取镜像。
docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-d、--detach |
在后台运行并输出容器 ID | docker run -d nginx:alpine |
-i、--interactive |
保持标准输入打开 | docker run -i alpine sh |
-t、--tty |
分配伪终端,常与 -i 组合 |
docker run -it alpine sh |
--name NAME |
指定容器名称 | docker run -d --name web nginx:alpine |
-p、--publish |
将容器端口映射到宿主机 | docker run -d -p 8080:80 nginx:alpine |
-P、--publish-all |
将镜像声明的暴露端口映射到宿主机随机端口 | docker run -d -P nginx:alpine |
-v、--volume |
挂载命名卷或宿主机目录 | docker run --rm -v app_data:/data alpine ls /data |
--mount |
通过键值形式指定挂载类型、来源和目标 | docker run --rm --mount type=volume,source=app_data,target=/data alpine ls /data |
-e、--env |
设置容器环境变量 | docker run --rm -e NODE_ENV=production alpine env |
--env-file FILE |
从指定文件读取环境变量 | docker run --rm --env-file .env alpine env |
--network NETWORK |
指定容器连接的网络 | docker run --rm --network bridge alpine ip addr |
--restart POLICY |
设置自动重启策略 | docker run -d --restart unless-stopped nginx:alpine |
--rm |
容器退出后自动删除容器及其关联的匿名卷 | docker run --rm alpine echo hello |
-w、--workdir DIR |
指定容器内的工作目录 | docker run --rm -w /app alpine pwd |
-u、--user USER |
指定运行进程的用户或 UID/GID | docker run --rm -u 1000:1000 alpine id |
--entrypoint COMMAND |
覆盖镜像默认的入口程序 | docker run --rm --entrypoint sh nginx:alpine -c 'nginx -v' |
-m、--memory LIMIT |
设置容器的内存上限 | docker run -d --memory 512m nginx:alpine |
--cpus NUMBER |
限制可使用的 CPU 总量 | docker run -d --cpus 1.5 nginx:alpine |
--read-only |
将容器根文件系统设为只读 | docker run --rm --read-only alpine ls / |
示例:
# 创建名为 web 的 Nginx 容器,在后台运行并将宿主机 8080 端口映射到容器 80 端口
# 使用 unless-stopped 重启策略,手动停止后保持停止状态
docker run -d \
--name web \
-p 8080:80 \
--restart unless-stopped \
nginx:alpine
# 创建临时交互容器并进入 sh,退出 Shell 后自动删除该容器
docker run --rm -it alpine sh
端口映射
每个docker容器都运行在独立的虚拟环境里,容器的网络与宿主机是隔离的,默认情况下Docker 使用 bridge(桥接)网络模式,无法从宿主机直接访问到docker容器的服务,宿主机只能通过容器 IP 访问容器服务。如果需要让宿主机直接访问到容器服务,需要使用端口映射。假设宿主机端口为8080,容器A默认端口为80,宿主机ip为192.168.1.100。访问 192.168.1.100:8080 无法访问到容器A,需要容器A在启动时设置端口映射 “-p 宿主机端口:容器端口” ,把宿主机端口映射到指定的容器端口,即 “-p 8080:80” ,之后在访问192.168.1.100:8080时,可以访问到容器A。
-p [HOST_IP:]HOST_PORT:CONTAINER_PORT[/PROTOCOL]
| 写法 | 含义 |
|---|---|
-p 8080:80 |
将宿主机 8080 端口映射到容器 TCP 80 端口,默认绑定宿主机所有接口 |
-p 127.0.0.1:8080:80 |
仅绑定宿主机的本地回环地址 |
-p 8080:80/udp |
将宿主机 UDP 8080 端口映射到容器 UDP 80 端口 |
-P |
将镜像声明的暴露端口映射到宿主机随机端口,可在 docker ps 中查看结果 |
EXPOSE 声明端口;通过宿主机端口访问容器服务时,还需要配置 -p 或 -P。详见 端口发布与映射。
重启策略
| 策略 | 含义 |
|---|---|
no |
不自动重启,默认策略 |
on-failure |
主进程以非零退出码结束时自动重试;Docker 服务重启本身不会触发该策略重新启动容器 |
on-failure:5 |
异常退出时最多重试 5 次 |
always |
容器停止后自动重启;手动停止后,直到手动启动容器或 Docker 服务重启才恢复运行 |
unless-stopped |
类似 always,但已停止的容器在 Docker 服务重启后仍保持停止 |
--rm 不能与自动重启策略同时使用。长期运行的服务通常保留容器,方便查看退出状态和日志;临时任务可使用 --rm 自动清理。详见 自动重启容器。
创建但不启动容器
预先保存容器配置,之后再通过 docker start 启动。大部分创建参数与 docker run 相同。
docker create [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--name NAME |
指定待创建容器的名称 | docker create --name web-pending nginx:alpine |
-p、--publish |
预先配置端口映射 | docker create -p 8081:80 nginx:alpine |
-e、--env |
配置环境变量 | docker create -e NODE_ENV=production nginx:alpine |
-v、--volume |
配置数据卷或目录挂载 | docker create -v app_data:/data nginx:alpine |
示例:
# 创建名为 web-pending 的容器,预设端口映射,此时尚未运行
docker create --name web-pending -p 8081:80 nginx:alpine
# 启动刚创建的容器,使用创建时保存的配置
docker start web-pending
启动已有容器
启动已经存在的容器,继续使用原有的容器配置和可写层。
docker start [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--attach |
连接容器的标准输出和标准错误,并转发信号 | docker start -a web |
-i、--interactive |
连接容器的标准输入 | docker start -i web |
示例:
# 启动已经存在且处于停止状态的 web 容器
docker start web
查看容器
查看容器列表
默认显示正在运行的容器,通过参数可查看其他状态或筛选结果。
docker ps [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
显示所有状态的容器 | docker ps -a |
-q、--quiet |
只显示容器 ID | docker ps -q |
-l、--latest |
显示最近创建的一个容器,包含所有状态 | docker ps -l |
-n N、--last N |
显示最近创建的 N 个容器,包含所有状态 | docker ps -n 5 |
-f、--filter |
按条件筛选容器 | docker ps -a -f status=exited |
--format |
自定义输出字段和格式 | docker ps --format "{{.Names}} {{.Status}}" |
--no-trunc |
不截断容器 ID 等输出内容 | docker ps --no-trunc |
-s、--size |
显示容器可写层大小等磁盘占用信息 | docker ps -s |
示例:
# 查看当前正在运行的容器
docker ps
# 查看全部容器,包括已经停止的容器
docker ps -a
# 只列出已退出容器的 ID,便于进一步排查
docker ps -aq -f status=exited
查看容器详情
查看容器的配置、运行状态、网络和挂载。使用容器专用的 inspect 命令可以明确查询对象类型。
docker container inspect [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--format |
只输出指定字段 | docker container inspect -f '{{.State.Status}}' web |
-s、--size |
额外计算并显示容器文件系统大小 | docker container inspect -s web |
示例:
# 查看 web 容器的完整详细信息
docker container inspect web
# 只查看 web 容器当前的运行状态
docker container inspect -f '{{.State.Status}}' web
管理运行状态
停止与重启容器
停止时,先向容器主进程发送配置的停止信号,未配置时默认使用 SIGTERM;等待超时后发送 SIGKILL。重启会在停止后重新启动同一个容器。
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 停止容器 | docker stop [OPTIONS] CONTAINER [CONTAINER...] |
docker stop web |
请求主进程正常退出 |
| 重启容器 | docker restart [OPTIONS] CONTAINER [CONTAINER...] |
docker restart web |
重新运行已有容器 |
OPTIONS:
| 适用命令 | 参数 | 作用 | 示例 |
|---|---|---|---|
stop |
-t、--timeout |
等待容器正常停止的秒数,-1 表示无限等待 |
docker stop -t 30 web |
restart |
-t、--timeout |
重启前等待容器正常停止的秒数 | docker restart -t 30 web |
stop、restart |
-s、--signal |
指定停止时发送的信号 | docker stop -s SIGTERM web |
示例:
# 请求 web 容器停止,最多等待 30 秒,超时后强制终止
docker stop -t 30 web
# 重启 web 容器,停止阶段最多等待 30 秒
docker restart -t 30 web
发送信号或强制终止容器
默认发送 SIGKILL 立即终止容器主进程;指定其他信号时,是否退出取决于信号和进程的处理方式。
docker kill [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-s、--signal |
指定发送的信号,默认是 SIGKILL |
docker kill -s SIGTERM web |
示例:
# 立即向 web 容器主进程发送 SIGKILL,强制终止容器
docker kill web
暂停与恢复容器
暂停会冻结容器中的进程,恢复后继续执行。
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 暂停容器 | docker pause CONTAINER [CONTAINER...] |
docker pause web |
暂停容器内的进程 |
| 恢复容器 | docker unpause CONTAINER [CONTAINER...] |
docker unpause web |
恢复已暂停的进程 |
示例:
# 暂停 web 容器中的进程,保留其当前执行状态
docker pause web
# 恢复 web 容器中的进程,从暂停处继续执行
docker unpause web
执行命令与查看日志
在容器内执行命令
在运行中的容器内启动一个新进程。进入 Shell 需要镜像中包含对应的 Shell;nginx:alpine 可以使用 sh。
docker exec [OPTIONS] CONTAINER COMMAND [ARG...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-i、--interactive |
保持标准输入打开 | docker exec -i web sh |
-t、--tty |
分配伪终端,常与 -i 组合 |
docker exec -it web sh |
-u、--user |
指定本次命令的执行用户 | docker exec -u root web id |
-w、--workdir |
指定本次命令的工作目录 | docker exec -w /etc/nginx web pwd |
-e、--env |
仅为本次执行的进程设置环境变量 | docker exec -e NODE_ENV=production web env |
示例:
# 在正在运行的 web 容器中打开交互式 sh
docker exec -it web sh
# 在 web 容器中检查 Nginx 配置文件的语法
docker exec web nginx -t
查看容器日志
读取容器的标准输出和标准错误日志。应用写入普通文件的日志,需要结合应用配置或容器内的文件进行查看。
docker logs [OPTIONS] CONTAINER
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--follow |
持续跟踪新产生的日志 | docker logs -f web |
-n N、--tail N |
显示最后 N 行日志 | docker logs --tail 100 web |
--since TIME |
显示指定时间之后的日志 | docker logs --since 30m web |
--until TIME |
显示指定时间之前的日志 | docker logs --until 10m web |
-t、--timestamps |
显示每条日志的时间戳 | docker logs -t web |
--details |
显示日志配置中提供的额外属性 | docker logs --details web |
示例:
# 查看 web 容器已记录的日志
docker logs web
# 先显示最后 100 行日志,再持续跟踪新日志,并显示时间戳
docker logs -f --tail 100 -t web
管理资源与进程
查看资源使用
默认持续显示运行中容器的资源使用情况,可以指定容器或只取一次统计。
docker stats [OPTIONS] [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--no-stream |
只输出一次统计结果 | docker stats --no-stream web |
--format |
自定义统计字段和输出格式 | docker stats --no-stream --format "{{.Name}} {{.CPUPerc}}" web |
-a、--all |
同时列出已停止的容器,已停止容器没有实时使用数据 | docker stats -a --no-stream |
示例:
# 实时查看所有运行中容器的 CPU、内存和 I/O 等指标
docker stats
# 只获取一次 web 容器的资源使用情况
docker stats --no-stream web
查看容器进程
查看容器内的进程。ps OPTIONS 表示传给 ps 的参数,具体支持情况取决于宿主机环境。
docker top CONTAINER [ps OPTIONS]
示例:
# 查看 web 容器中的进程列表
docker top web
# 在支持该 ps 参数的 Linux 宿主机上查看更完整的进程信息
docker top web -ef
更新资源限制与重启策略
调整支持动态更新的容器配置。端口映射、环境变量等创建时配置通常需要重新创建容器才能修改。
docker update [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--cpus NUMBER |
调整可使用的 CPU 总量 | docker update --cpus 1.5 web |
-m、--memory LIMIT |
调整内存上限 | docker update --memory 512m --memory-swap 1g web |
--memory-swap LIMIT |
设置内存与 swap 的总额度 | docker update --memory 512m --memory-swap 1g web |
--restart POLICY |
更新自动重启策略 | docker update --restart unless-stopped web |
--memory-swap 为正值时不能小于内存限制。上述示例表示内存上限为 512 MiB,内存与 swap 的总上限为 1 GiB;实际 swap 能否使用还取决于宿主机配置。
示例:
# 将 web 容器最多可使用的 CPU 总量调整为 1.5 个 CPU
docker update --cpus 1.5 web
# 将内存上限设为 512 MiB,并将内存与 swap 的总上限设为 1 GiB
docker update --memory 512m --memory-swap 1g web
# 将 web 容器的重启策略改为 unless-stopped
docker update --restart unless-stopped web
文件操作与备份
复制文件
在宿主机与容器之间复制文件或目录,容器可以处于运行或停止状态。容器路径写作 CONTAINER:/path;复制目标的父目录需要提前存在。
docker cp [OPTIONS] SRC_PATH DEST_PATH
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--archive |
尽量保留源文件的 UID/GID | docker cp -a ./nginx.conf web:/etc/nginx/nginx.conf |
-L、--follow-link |
跟随源路径中的符号链接进行复制 | docker cp -L web:/etc/nginx/nginx.conf ./nginx.conf |
示例:
# 将宿主机已有的 nginx.conf 文件复制到 web 容器中
docker cp ./nginx.conf web:/etc/nginx/nginx.conf
# 将 web 容器中的配置文件复制出来,保存为宿主机当前目录下的 nginx.conf
docker cp web:/etc/nginx/nginx.conf ./nginx.conf
查看文件系统变化
查看容器文件系统相对于创建时镜像的变化。
docker diff CONTAINER
| 标记 | 含义 |
|---|---|
A |
新增文件或目录 |
C |
修改文件或目录 |
D |
删除文件或目录 |
示例:
# 查看 web 容器文件系统中的新增、修改和删除记录
docker diff web
导出容器文件系统
将容器文件系统导出为 tar 归档,不包含挂载卷中的数据。导出结果不保留原镜像的分层历史和运行配置;恢复完整镜像应使用前文的 docker image save / docker image load。
docker export [OPTIONS] CONTAINER
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-o、--output |
指定导出的 tar 文件路径 | docker export -o web-rootfs.tar web |
示例:
# 将 web 容器的文件系统导出为当前目录下的 web-rootfs.tar 文件
docker export -o web-rootfs.tar web
重命名与删除容器
重命名容器
修改容器名称,容器 ID 保持不变。
docker rename CONTAINER NEW_NAME
示例:
# 将 web 容器重命名为 web-prod,后续通过新名称操作该容器
docker rename web web-prod
删除指定容器
默认删除已经停止的容器,使用 -f 可以强制终止并删除运行中的容器。
docker rm [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
强制终止并删除容器 | docker rm -f web |
-v、--volumes |
同时删除关联的匿名卷,保留命名卷 | docker rm -v web |
示例:
# 删除已经停止的 web 容器
docker rm web
# 强制终止并删除 web 容器,用于需要直接清理运行中容器的场景
docker rm -f web
清理已停止容器
批量删除已停止的容器,可通过条件限制清理范围。
docker container prune [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
跳过交互确认提示 | docker container prune -f |
--filter |
按创建时间、标签等条件筛选已停止的容器 | docker container prune --filter "until=24h" |
示例:
# 清理所有已停止的容器,执行前会提示确认
docker container prune
# 仅清理创建于 24 小时前、当前已停止的容器,执行前会提示确认
docker container prune --filter "until=24h"
存储
Docker 存储用于保存容器产生的数据,或将宿主机上的文件、目录提供给容器使用。直接写入容器可写层的数据会随容器删除而丢失;需要长期保存的数据通常放到数据卷或绑定挂载中。
以下示例面向 Linux 容器,使用 Bash 语法。存储机制的完整说明可查阅 Docker 存储文档。
存储方式对比
| 方式 | 数据位置与管理方式 | 生命周期 | 常见用途 |
|---|---|---|---|
| 容器可写层 | 容器自身的可写文件系统 | 停止容器后保留,删除容器后丢失 | 可随容器重新生成的文件 |
| 命名卷 Volume | 由 Docker 管理,通过指定卷名访问 | 独立于容器,普通删除容器时保留 | 数据库、应用上传文件等持久化数据 |
| 匿名卷 Volume | 由 Docker 管理,自动生成随机名称 | 普通删除容器时保留,可通过 --rm 或 docker rm -v 随容器清理 |
不需要固定卷名的独立存储 |
| 绑定挂载 Bind Mount | 直接使用宿主机指定的文件或目录 | 数据随宿主机文件保留 | 配置文件、静态资源、开发代码 |
| 临时挂载 tmpfs | 使用内存中的临时文件系统 | 容器停止或重启后内容消失 | 缓存、临时计算文件 |
命名卷与匿名卷属于同一种存储机制,区别主要在于是否显式指定名称。需要在宿主机和容器之间直接编辑同一份文件时,通常使用绑定挂载。
命令汇总
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 创建卷 | docker volume create [OPTIONS] [VOLUME] |
docker volume create mysql_data |
创建名为 mysql_data 的卷 |
| 查看卷列表 | docker volume ls [OPTIONS] |
docker volume ls |
查看 Docker 管理的数据卷 |
| 查看卷详情 | docker volume inspect [OPTIONS] VOLUME [VOLUME...] |
docker volume inspect mysql_data |
查看卷的驱动、标签和存储位置 |
| 删除卷 | docker volume rm [OPTIONS] VOLUME [VOLUME...] |
docker volume rm mysql_data |
删除没有被任何容器引用的卷 |
| 清理未使用的匿名卷 | docker volume prune [OPTIONS] |
docker volume prune |
默认清理未被容器引用的匿名卷 |
| 清理所有未使用卷 | docker volume prune [OPTIONS] |
docker volume prune -a |
同时清理未被容器引用的命名卷和匿名卷 |
操作数据卷
创建数据卷
显式创建一个数据卷,之后通过卷名挂载到容器。省略卷名时,Docker 会生成随机名称。
docker volume create [OPTIONS] [VOLUME]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-d、--driver |
指定卷驱动,默认是 local |
docker volume create -d local mysql_data |
--label |
为卷添加标签,可用于筛选和清理 | docker volume create --label env=dev app_data |
示例:
# 创建用于保存 MySQL 数据的命名卷
docker volume create mysql_data
# 创建带有 env=dev 标签的应用数据卷,便于后续按标签筛选
docker volume create --label env=dev app_data
查看数据卷
查看卷列表
列出 Docker 管理的卷,可根据是否被容器引用、标签等条件筛选。
docker volume ls [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-q、--quiet |
只显示卷名称 | docker volume ls -q |
-f、--filter |
按条件筛选卷 | docker volume ls -f dangling=true |
--format |
自定义输出格式 | docker volume ls --format "{{.Name}} {{.Driver}}" |
dangling=true 表示没有被任何容器引用;已经停止但尚未删除的容器,仍会保留对卷的引用。
示例:
# 查看当前所有数据卷
docker volume ls
# 只显示未被任何容器引用的卷名称
docker volume ls -q -f dangling=true
# 查看带有 env=dev 标签的数据卷
docker volume ls -f label=env=dev
查看卷详情
查看卷的驱动、标签、存储位置等信息。
docker volume inspect [OPTIONS] VOLUME [VOLUME...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--format |
只输出指定字段 | docker volume inspect -f '{{.Mountpoint}}' mysql_data |
示例:
# 查看 mysql_data 卷的完整信息
docker volume inspect mysql_data
# 只查看 Docker 管理的卷存储位置
docker volume inspect -f '{{.Mountpoint}}' mysql_data
Mountpoint 位于 Docker 守护进程所在的主机。Docker Desktop 中通常位于其 Linux 虚拟机内,并不是 Windows/macOS 上可直接访问的同名目录;访问卷数据时,可将卷挂载到临时容器中操作。
删除与清理数据卷
删除指定卷
删除没有被任何容器引用的卷及其数据。使用该卷的容器即使已经停止,也需要先移除对应的容器引用。
docker volume rm [OPTIONS] VOLUME [VOLUME...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
强制发起删除请求,仍不能删除被容器引用的卷 | docker volume rm -f mysql_data |
示例:
# 删除已经确认不再需要、且未被任何容器引用的 mysql_data 卷及其数据
docker volume rm mysql_data
清理未使用的数据卷
默认只清理未被容器引用的匿名卷,添加 -a 后才会同时清理命名卷。卷清理支持标签筛选,不能直接套用容器清理中的 until 条件。
docker volume prune [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
同时清理未被容器引用的命名卷 | docker volume prune -a |
-f、--force |
跳过交互确认提示 | docker volume prune -f |
--filter |
按卷标签筛选清理对象 | docker volume prune -a --filter "label=env=dev" |
示例:
# 清理未被容器引用的匿名卷,执行前会提示确认
docker volume prune
# 清理所有未被容器引用的卷,包括命名卷,执行前会提示确认
docker volume prune -a
# 仅清理带 env=dev 标签且未被容器引用的卷,包括命名卷
docker volume prune -a --filter "label=env=dev"
配置容器挂载
挂载参数写法
-v 使用冒号分隔来源、目标和选项;--mount 使用逗号分隔键值对,可以明确指定挂载类型。一个容器需要多个挂载时,重复使用对应参数。
| 占位符 | 含义 |
|---|---|
VOLUME |
Docker 数据卷名称,如 mysql_data |
HOST_PATH |
宿主机上的来源文件或目录路径 |
CONTAINER_PATH |
容器内的目标路径,使用绝对路径 |
| 参数形式 | 含义 |
|---|---|
-v VOLUME:CONTAINER_PATH |
命名卷挂载,默认可写 |
-v VOLUME:CONTAINER_PATH:ro |
命名卷只读挂载 |
-v CONTAINER_PATH |
创建并挂载匿名卷 |
-v HOST_PATH:CONTAINER_PATH |
绑定挂载宿主机文件或目录,默认可写 |
-v HOST_PATH:CONTAINER_PATH:ro |
绑定挂载,并限制容器只读访问 |
--mount type=volume,source=VOLUME,target=CONTAINER_PATH |
命名卷挂载的显式写法 |
--mount type=volume,source=VOLUME,target=CONTAINER_PATH,readonly |
命名卷只读挂载的显式写法 |
--mount type=bind,source=HOST_PATH,target=CONTAINER_PATH |
绑定挂载的显式写法 |
--mount type=bind,source=HOST_PATH,target=CONTAINER_PATH,readonly |
绑定挂载并限制容器只读访问 |
以下绑定挂载示例使用宿主机绝对路径。使用远程 Docker 服务时,来源路径属于 Docker 服务所在主机;Docker Desktop 可通过其文件共享机制使用本机路径。
挂载命名卷与匿名卷
命名卷通过名称复用;没有指定 source 的卷挂载会创建匿名卷。需要长期保存并反复使用的数据,通常显式指定卷名。
docker run [OPTIONS] --mount type=volume,source=VOLUME,target=CONTAINER_PATH IMAGE[:TAG] [COMMAND] [ARG...]
OPTIONS(以下是 --mount type=volume 的常用挂载项):
| 参数 | 作用 | 写法示例 |
|---|---|---|
source、src |
指定卷名;省略时使用匿名卷 | source=mysql_data |
target、destination、dst |
指定容器内的绝对目标路径 | target=/var/lib/mysql |
readonly、ro |
将该挂载设为只读,默认可写 | readonly |
volume-nocopy |
挂载空卷时,不复制目标目录原有文件 | volume-nocopy |
示例:
# 将 MySQL 数据目录挂载到 mysql_data 命名卷,保存数据库文件
# replace-this-password 是首次初始化使用的 root 密码占位值,使用时替换为自己的密码
docker run -d \
--name mysql \
--mount type=volume,source=mysql_data,target=/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=replace-this-password \
mysql:8.4
# 创建挂载匿名卷的临时容器,退出后自动删除容器及其关联的匿名卷
docker run --rm -it --mount type=volume,target=/data alpine sh
/var/lib/mysql 是该 MySQL 镜像的数据目录。MYSQL_ROOT_PASSWORD 用于首次初始化;卷内已有数据库时,修改此环境变量不会修改原数据库密码。详见 MySQL 官方镜像说明。
绑定挂载宿主机目录或文件
直接把宿主机上的文件或目录挂载到容器中,适用于配置文件、静态页面和开发代码。默认可写;readonly 或 :ro 限制的是容器通过该挂载写入,宿主机仍可修改源文件。
docker run [OPTIONS] --mount type=bind,source=HOST_PATH,target=CONTAINER_PATH IMAGE[:TAG] [COMMAND] [ARG...]
OPTIONS(以下是 --mount type=bind 的常用挂载项):
| 参数 | 作用 | 写法示例 |
|---|---|---|
source、src |
指定宿主机来源文件或目录 | source=/opt/app/html |
target、destination、dst |
指定容器内的绝对目标路径 | target=/usr/share/nginx/html |
readonly、ro |
限制容器只读访问该挂载 | readonly |
示例:
# 在宿主机当前目录创建静态页面目录,作为绑定挂载的来源
mkdir -p ./html
# 创建一个供 Nginx 直接提供的示例页面
printf '%s\n' '<h1>Hello Docker</h1>' > ./html/index.html
# 将宿主机 html 目录只读挂载到 Nginx 页面目录,并通过宿主机 8082 端口访问
docker run -d \
--name web-bind \
-p 8082:80 \
--mount type=bind,source="$(pwd)/html",target=/usr/share/nginx/html,readonly \
nginx:alpine
| 场景 | -v 的默认行为 |
--mount type=bind 的默认行为 |
|---|---|---|
| 来源路径不存在 | 自动创建宿主机目录,即使原本希望挂载的是文件 | 默认报错,需要先准备来源路径 |
| 挂载文件 | 来源应为已有文件;路径写错可能被自动创建成目录 | 来源应为已有文件,缺失时默认报错 |
当前版本还支持通过 bind-create-src 显式启用来源路径创建。上面的示例先创建来源目录,保持挂载目标明确。详见 绑定挂载说明。
使用临时内存挂载
tmpfs 适用于 Linux 容器的临时文件,内容在容器停止后消失。它不用于持久化数据,内存占用还会计入容器内存限制;宿主机启用 swap 时,部分内容可能进入 swap。
docker run [OPTIONS] --mount type=tmpfs,target=CONTAINER_PATH IMAGE[:TAG] [COMMAND] [ARG...]
OPTIONS(以下是 --mount type=tmpfs 的常用挂载项):
| 参数 | 作用 | 写法示例 |
|---|---|---|
target、destination、dst |
指定容器内的临时挂载目录,无需 source |
target=/cache |
tmpfs-size |
设置挂载的容量上限,单位为字节 | tmpfs-size=67108864 |
tmpfs-mode |
设置目录权限,使用八进制表示 | tmpfs-mode=1777 |
示例:
# 在容量上限为 64 MiB 的临时目录中写入并读取文件,容器退出后这些内容消失
docker run --rm \
--mount type=tmpfs,target=/cache,tmpfs-size=67108864 \
alpine sh -c 'echo temp > /cache/demo.txt && cat /cache/demo.txt'
查看容器的挂载结果
查看容器的 Mounts 字段,确认实际挂载类型、来源、目标路径和读写状态。
docker container inspect [OPTIONS] CONTAINER [CONTAINER...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--format |
仅输出挂载信息 | docker container inspect -f '{{json .Mounts}}' mysql |
示例:
# 查看 mysql 容器的挂载列表,并以 JSON 形式输出
docker container inspect -f '{{json .Mounts}}' mysql
| 字段 | 含义 |
|---|---|
Type |
挂载类型,如 volume、bind、tmpfs |
Name |
数据卷名称,通常出现在 volume 类型中 |
Source |
实际的挂载来源路径,具体形式取决于挂载类型 |
Destination |
容器内的目标路径 |
RW |
true 表示容器可写,false 表示容器只读 |
挂载后原目录的变化
| 场景 | 表现 |
|---|---|
| 新空卷挂载到容器中已有文件的目录 | 默认将原有文件复制到卷中,使用 volume-nocopy 可关闭此行为 |
| 非空卷挂载到容器目录 | 挂载内容会遮蔽容器目标目录原有的文件 |
| 绑定挂载到容器目录 | 显示宿主机来源的内容,容器目标目录原有文件被遮蔽,不会自动复制到宿主机 |
遮蔽不代表原文件已被删除。需要恢复查看镜像中的原始内容时,可以创建一个没有该挂载的新容器。
数据持久化与备份
删除容器与删除卷的区别
| 操作 | 对数据的影响 |
|---|---|
docker stop CONTAINER |
容器可写层、数据卷和绑定挂载的数据保留;tmpfs 内容消失 |
docker rm CONTAINER |
删除容器可写层,默认保留命名卷、匿名卷和绑定挂载来源 |
docker rm -v CONTAINER |
同时清理关联匿名卷,保留命名卷和绑定挂载来源 |
使用 docker run --rm ... 的容器退出 |
自动清理容器及其关联匿名卷,保留命名卷 |
docker volume rm VOLUME |
删除该卷及其数据,需要先解除全部容器引用 |
docker volume prune -a |
删除所有未被容器引用的卷,包括命名卷和匿名卷 |
持久化解决的是数据独立于容器保存的问题,仍需要单独备份重要数据。前文的 docker export 不包含挂载卷的数据,镜像的 save 也不备份数据卷。
备份数据卷
以下以已经停止写入的普通文件卷 app_data 为例,通过临时容器把卷内容归档到宿主机当前目录。数据库优先使用数据库自身的备份工具;文件级归档需要按数据库要求停止写入或正常停库,以获得一致的数据。
示例:
# 确认 app_data 卷已经存在,并核对其信息
docker volume inspect app_data
# 只读挂载待备份卷,将其中的文件归档到宿主机当前目录的 app-data.tar.gz
# 当前目录作为 /backup 挂入临时容器,生成的归档文件保留在宿主机
docker run --rm \
--mount type=volume,source=app_data,target=/data,readonly,volume-nocopy \
--mount type=bind,source="$(pwd)",target=/backup \
alpine tar -czf /backup/app-data.tar.gz -C /data .
从备份恢复到新卷
先准备一个新的空卷,再解压备份文件。示例假设当前目录中已经存在上一步生成的 app-data.tar.gz,且 app_data_restored 尚未用于其他数据。
示例:
# 创建一个用于恢复数据的新空卷
docker volume create app_data_restored
# 只读挂载宿主机备份目录,把归档中的文件恢复到新卷
docker run --rm \
--mount type=volume,source=app_data_restored,target=/data,volume-nocopy \
--mount type=bind,source="$(pwd)",target=/backup,readonly \
alpine tar -xzf /backup/app-data.tar.gz -C /data
# 通过临时容器只读查看新卷,核对恢复后的文件
docker run --rm \
--mount type=volume,source=app_data_restored,target=/data,readonly,volume-nocopy \
alpine ls -la /data
恢复后,重新创建应用容器,将原卷名替换为 app_data_restored,再按应用要求验证数据。更多卷管理与备份示例可参阅 Docker 数据卷文档。
多服务项目中如何声明和复用这些卷,见后文 Compose 的数据卷与目录挂载。
网络
Docker 网络用于容器之间的通信,也用于连接宿主机和外部网络。容器间通信使用目标容器实际监听的端口;宿主机端口发布则通过 -p 或 Compose 的 ports 配置。
以下以 Linux 容器为例,示例按场景独立使用。完整命令可参阅 Docker 网络命令参考。
网络类型对比
| 类型 | 特点 | 常见用途 |
|---|---|---|
自定义 bridge |
同一 Docker 主机内的隔离网络,支持按容器名或网络别名解析 | 单机部署多个需要互相通信的容器 |
默认 bridge |
Docker 自动创建;未指定网络时通常连接到这里,默认不提供容器名自动解析 | 简单临时容器,实际项目通常显式创建网络 |
host |
容器共享宿主机网络命名空间,没有独立容器 IP,-p 不生效 |
需要直接使用宿主机网络的特定场景 |
none |
仅保留回环接口,不连接普通容器网络 | 不需要网络访问的任务 |
overlay |
跨 Docker 主机连接容器,需要启用 Swarm 模式 | 多主机服务通信 |
host 网络适用于 Linux Docker Engine;Docker Desktop 4.34 及以后版本需要显式启用对应功能,且只支持 Linux 容器。自定义 bridge 的名称解析与默认桥接网络不同,详见 Bridge 网络说明。
命令汇总
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 查看网络列表 | docker network ls [OPTIONS] |
docker network ls |
查看 Docker 管理的网络 |
| 创建网络 | docker network create [OPTIONS] NETWORK |
docker network create app-net |
创建供容器连接的网络 |
| 查看网络详情 | docker network inspect [OPTIONS] NETWORK [NETWORK...] |
docker network inspect app-net |
查看网络配置与已连接的容器 |
| 连接已有容器 | docker network connect [OPTIONS] NETWORK CONTAINER |
docker network connect app-net web |
为已有容器增加网络连接 |
| 断开容器连接 | docker network disconnect [OPTIONS] NETWORK CONTAINER |
docker network disconnect app-net web |
移除容器在指定网络上的连接 |
| 删除指定网络 | docker network rm [OPTIONS] NETWORK [NETWORK...] |
docker network rm app-net |
删除没有容器连接的自定义网络 |
| 清理未使用网络 | docker network prune [OPTIONS] |
docker network prune |
清理未被任何容器引用的自定义网络 |
操作网络
创建网络
默认创建自定义 bridge 网络。多个容器连接到同一自定义网络后,可以使用容器名或该网络中的别名访问彼此。
docker network create [OPTIONS] NETWORK
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-d、--driver |
指定网络驱动,默认是 bridge |
docker network create -d bridge app-net |
--subnet CIDR |
指定网络使用的子网 | docker network create --subnet 172.28.0.0/16 app-net |
--gateway IP |
为指定子网设置网关地址 | docker network create --subnet 172.28.0.0/16 --gateway 172.28.0.1 app-net |
--internal |
限制该网络的外部连通能力 | docker network create --internal app-internal |
--label |
为网络设置标签,便于筛选与清理 | docker network create --label env=dev app-net |
示例:
# 创建名为 app-net 的自定义 bridge 网络,地址由 Docker 自动分配
docker network create --label env=dev app-net
# 按另一种场景创建具有指定子网和网关的网络
docker network create -d bridge \
--subnet 172.28.0.0/16 \
--gateway 172.28.0.1 \
app-net-static
自定义网段应避开宿主机、VPN 和已有 Docker 网络的网段。--internal 约束该网络的外部连通;容器同时连接多个网络时,还需要结合其他网络连接判断实际访问路径。
查看网络
查看网络列表
docker network ls [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-q、--quiet |
只显示网络 ID | docker network ls -q |
-f、--filter |
按驱动、名称、标签等条件筛选 | docker network ls -f driver=bridge |
--format |
自定义输出字段和格式 | docker network ls --format "{{.Name}} {{.Driver}}" |
--no-trunc |
显示完整网络 ID | docker network ls --no-trunc |
示例:
# 查看当前所有 Docker 网络
docker network ls
# 只查看用户创建的网络
docker network ls -f type=custom
# 查看带 env=dev 标签的网络
docker network ls -f label=env=dev
查看网络详情
查看网络的地址配置、驱动、标签及容器连接信息。
docker network inspect [OPTIONS] NETWORK [NETWORK...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--format |
只输出指定字段 | docker network inspect -f '{{json .Containers}}' app-net |
-v、--verbose |
输出额外诊断信息 | docker network inspect -v app-net |
示例:
# 查看 app-net 网络的完整配置
docker network inspect app-net
# 仅查看 app-net 网络当前记录的容器连接信息
docker network inspect -f '{{json .Containers}}' app-net
管理容器连接
连接已有容器
将已有容器连接到指定网络,一个容器可以连接多个网络。创建新容器时,也可以直接使用 docker run --network NETWORK。
docker network connect [OPTIONS] NETWORK CONTAINER
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--alias NAME |
为容器添加仅在该网络中使用的别名 | docker network connect --alias api app-net web |
--ip IP |
指定该网络中的 IPv4 地址,需要符合网络的地址配置 | docker network connect --ip 172.28.0.10 app-net-static web |
示例:
# 将已有的 web 容器连接到 app-net,并为其设置该网络内的 api 别名
docker network connect --alias api app-net web
断开容器连接
移除容器与指定网络的连接,容器在其他网络上的连接保留。普通断开操作面向运行中的容器。
docker network disconnect [OPTIONS] NETWORK CONTAINER
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
强制断开容器在指定网络上的连接 | docker network disconnect -f app-net web |
示例:
# 将运行中的 web 容器从 app-net 网络断开
docker network disconnect app-net web
删除与清理网络
删除指定网络
删除网络前,需要先断开所有已连接的容器。bridge、host、none 等内置网络不能作为普通自定义网络删除。
docker network rm [OPTIONS] NETWORK [NETWORK...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
网络不存在时不报错,不能绕过已有容器连接的限制 | docker network rm -f app-net |
示例:
# 删除已经断开全部容器连接、且不再需要的 app-net 网络
docker network rm app-net
清理未使用网络
批量删除未被任何容器引用的自定义网络,内置网络不会被清理。已经停止但尚未删除的容器,仍可能保留网络引用。
docker network prune [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
跳过交互确认提示 | docker network prune -f |
--filter |
按创建时间、标签等条件限制清理范围 | docker network prune --filter "until=24h" |
示例:
# 清理所有未被容器引用的自定义网络,执行前会提示确认
docker network prune
# 仅清理创建于 24 小时前、当前未被任何容器引用的自定义网络
docker network prune --filter "until=24h"
# 仅清理带 env=dev 标签、且未被容器引用的网络
docker network prune --filter "label=env=dev"
until=24h 按网络的创建时间筛选,并非“闲置超过 24 小时”。详见 网络清理参数。
容器通信与端口发布
| 场景 | 访问方式 | 是否需要发布宿主机端口 |
|---|---|---|
| 同一自定义 bridge 网络中的容器通信 | 容器名或网络别名,加目标容器实际监听的端口 | 不需要 |
| 宿主机或外部客户端访问容器服务 | 宿主机 IP 与发布的端口,如 127.0.0.1:8083 |
通常需要 -p |
| Compose 项目内服务通信 | Compose 服务名与容器内端口,如 db:3306 |
不需要为内部通信发布数据库端口 |
示例:
# 创建独立的演示网络
docker network create demo-net
# 在演示网络中启动 Nginx,同时把宿主机 8083 端口发布到容器 80 端口
docker run -d \
--name web-net \
--network demo-net \
-p 8083:80 \
nginx:alpine
# 在同一网络中的临时容器里,通过容器名和容器内的 80 端口访问 Nginx
docker run --rm --network demo-net alpine wget -qO- http://web-net:80
浏览器通过宿主机的 http://localhost:8083 访问;网络中的其他容器使用 http://web-net:80。容器内的 localhost 指向该容器自身,不能用来代替另一个容器的名称。应用也需要监听可被该网络访问的地址,不能仅监听其容器内的回环地址。
Compose配置项
Docker Compose 通过 YAML 格式的 compose.yaml 描述并统一管理多个服务的镜像、容器、网络和数据卷。配置文件声明服务及其所需资源,docker compose 命令负责校验配置、启动和管理项目。服务是可运行一个或多个容器的配置单元,项目则将这些服务和相关资源组织在一起。
本章先按用途介绍配置,下一章讲解Compose 命令,最后用 NestJS 与 MySQL 综合示例串起完整流程。以下小节展示独立写法或配置片段;实际使用时,将需要的字段合并到同一份 compose.yaml 中,避免重复定义同名字段。
文件结构与配置总览
services 下的每个键都是一个服务名,例如 api、db、web。服务名用于 Compose 命令和网络内的服务发现;实际容器名默认由 Compose 生成。
# 设置项目名称,便于区分不同项目的资源
name: myapp
services:
# 定义一个名为 web 的服务
web:
image: nginx:alpine
ports:
- "8080:80"
volumes:
# 将命名卷挂载到 Nginx 的静态文件目录
- web_data:/usr/share/nginx/html
# 声明供服务挂载的命名卷
volumes:
web_data:
| 顶层配置项 | 作用 | 常见写法 |
|---|---|---|
name |
设置项目名称 | name: myapp;后文的全局参数 -p可以覆盖它 |
services |
定义服务及其镜像、进程、环境变量等 | services: 下声明 api、db 等服务 |
volumes |
声明命名卷 | volumes: { db_data: {} } |
networks |
声明网络 | networks: { app_net: {} } |
configs |
声明配置文件资源,再由服务引用 | configs: { app_config: { file: ./app.conf } } |
secrets |
声明敏感文件资源,再由服务授权使用 | secrets: { db_password: { file: ./secrets/db_password.txt } } |
顶层 version 已过时,新文件可以省略;填写 version: "3.8" 不会让 Compose 切换到某个旧解析版本。具体说明见 Compose 的 version 与 name。
镜像与构建
选择运行镜像
image 指定创建容器时使用的镜像,也可以为本地构建结果指定名称和标签。
| 配置项 | 作用 | 示例 |
|---|---|---|
image |
指定镜像名称,可包含仓库、标签或摘要 | image: nginx:alpine |
pull_policy |
控制拉取镜像或构建镜像的策略 | pull_policy: missing |
platform |
指定服务运行的平台 | platform: linux/amd64 |
pull_policy 常用值:
| 值 | 含义 | 使用场景 |
|---|---|---|
always |
启动前始终尝试拉取镜像 | 希望从仓库获取指定标签的镜像 |
never |
不拉取镜像,要求本地已有镜像 | 离线环境或使用本地准备的镜像 |
missing |
通常仅在本地缺少镜像时拉取;latest 标签仍会拉取 |
优先复用本地镜像 |
build |
按服务的 build 配置构建镜像 |
使用本地源码构建服务 |
services:
web:
# 使用明确的镜像标签;alpine、latest 等标签本身仍可能更新
image: nginx:alpine
# 通常优先使用本地镜像
pull_policy: missing
省略标签通常等同于使用 latest,但 latest 只是标签名,不保证它就是版本号最新的镜像。
从 Dockerfile 构建镜像
build 可以直接写构建上下文路径,也可以写成包含多个子配置项的映射。
| 子配置项 | 作用 | 示例 |
|---|---|---|
context |
指定构建上下文;相对路径通常以项目目录为基准 | context: ./server |
dockerfile |
指定 Dockerfile,路径相对于构建上下文 | dockerfile: Dockerfile |
dockerfile_inline |
直接编写 Dockerfile 内容,不能与 dockerfile 同时使用 |
dockerfile_inline: 后接 YAML 多行文本 |
args |
向 Dockerfile 的 ARG 传入构建参数 |
args: { NODE_ENV: production } |
target |
选择 Dockerfile 已定义的某个构建阶段 | target: production |
no_cache |
构建时不使用镜像层缓存 | no_cache: true |
pull |
构建时尝试拉取 FROM 使用的镜像 |
pull: true |
platforms |
指定构建目标平台列表 | platforms: [linux/amd64, linux/arm64] |
network |
设置构建期间 RUN 指令的联网模式 |
network: none |
cache_from |
从指定位置导入构建缓存 | cache_from: ["type=local,src=.build-cache"] |
cache_to |
将构建缓存导出到指定位置 | cache_to: ["type=local,dest=.build-cache-next"] |
示例目录:
project/
├── compose.yaml
├── server/
│ ├── Dockerfile
│ ├── package.json
│ └── src/
└── web/
└── Dockerfile
示例:
services:
api:
# 为构建结果命名;发布前换成自己有权限的仓库名称
image: username/my-api:1.0
build:
# 将 server 目录作为构建上下文
context: ./server
# 实际读取 project/server/Dockerfile
dockerfile: Dockerfile
# Dockerfile 需要声明 ARG NODE_ENV 才能使用此构建参数
args:
NODE_ENV: production
# 尝试更新基础镜像;不使用层缓存需要另设 no_cache
pull: true
也可以直接写 build: ./server。args 只参与构建,不会自动成为容器运行时的环境变量;运行时变量使用 environment 或 env_file。
同时配置 image 与 build 时,由 pull_policy 决定拉取与构建行为;未指定策略时,Compose 会先尝试拉取,找不到再构建。写了 build 不代表每次启动都重新构建;后文创建并启动服务会介绍如何通过 --build 显式触发构建。
build.network 控制构建期间的联网模式,常用值为 default、none、host,与服务加入的 networks 不同。多平台构建和缓存后端也需要构建器支持,platforms 应包含显式设置的服务 platform。详细约束见 Compose 构建配置。
环境变量与变量插值
向容器传入环境变量
| 配置项或文件 | 作用 | 是否自动传入容器 |
|---|---|---|
服务 environment |
直接设置容器环境变量,支持映射或列表 | 是 |
服务 env_file |
从指定文件读取容器环境变量,支持单个文件或文件列表 | 是 |
项目 .env |
为 Compose 文件中的变量插值提供值 | 否,需要在配置中引用 |
命令行 --env-file |
指定 Compose 插值使用的变量文件,用法见全局参数 | 否,需要在配置中引用 |
build.args |
为 Dockerfile 的 ARG 提供构建参数 |
不会自动成为运行时变量 |
示例:
services:
api:
image: my-api:1.0
# 读取容器运行时的环境变量;文件需要提前准备好
env_file:
- ./app.env
- ./app.prod.env
environment:
# environment 中同名变量会覆盖 env_file 的值
NODE_ENV: production
DB_HOST: db
# 数字、布尔含义的值也写成字符串,避免 YAML 类型歧义
DB_PORT: "3306"
FEATURE_ENABLED: "true"
environment 的等价列表写法:
services:
api:
image: my-api:1.0
# 使用 KEY=VALUE 列表设置同一组运行时变量
environment:
- NODE_ENV=production
- DB_HOST=db
- DB_PORT=3306
- FEATURE_ENABLED=true
env_file 按列表顺序读取,后面的文件覆盖前面的同名值。environment 覆盖 env_file,两者都可以覆盖镜像中的 ENV。临时覆盖变量的用法放在后文创建一次性任务容器中介绍。具体优先级见 容器环境变量优先级。
为 Compose 配置插入变量
| 写法 | 作用 | 示例 |
|---|---|---|
${VAR} |
替换为变量的值 | image: my-api:${APP_VERSION} |
${VAR:-default} |
变量未设置或为空时使用默认值 | DB_HOST: "${DB_HOST:-db}" |
${VAR:?message} |
变量未设置或为空时报错 | DB_PASSWORD: "${DB_PASSWORD:?请配置 DB_PASSWORD}" |
$$VAR 或 $${VAR} |
输出字面量美元符,留给后续程序处理 | $$HOSTNAME 保留为 $HOSTNAME,可由容器内 Shell 展开 |
插值示例:
services:
api:
# APP_VERSION 可来自当前 Shell 或插值使用的 .env 文件
image: "my-api:${APP_VERSION:-1.0}"
environment:
# 必填变量缺失时,在解析配置阶段直接报错
DB_PASSWORD: "${DB_PASSWORD:?请在 .env 中配置 DB_PASSWORD}"
ports:
# WEB_PORT 未设置或为空时,使用主机 3000 端口
- "${WEB_PORT:-3000}:3000"
变量插值发生在 Compose 解析配置时;$$VAR 阻止 Compose 替换变量值,并将 $$ 转为字面量 $。下一节的 command 示例会通过 $$HOSTNAME 保留变量引用,再由容器内 Shell 展开 $HOSTNAME。完整写法见 Compose 变量插值。
进程启动与运行环境
| 配置项 | 作用 | 示例 |
|---|---|---|
command |
覆盖镜像的默认 CMD |
command: ["node", "dist/main.js"] |
entrypoint |
覆盖镜像的 ENTRYPOINT |
entrypoint: ["/app/entrypoint.sh"] |
container_name |
固定容器名称 | container_name: my-api |
working_dir |
设置容器内工作目录,覆盖镜像 WORKDIR |
working_dir: /app |
user |
设置运行用户,可写用户名或 UID:GID | user: "1000:1000" |
init |
添加初始化进程,转发信号并回收子进程 | init: true |
stdin_open |
保持标准输入打开,对应 docker run -i |
stdin_open: true |
tty |
分配伪终端,对应 docker run -t |
tty: true |
command 的字符串形式不会自动经过 Shell。需要变量展开、管道或重定向时,显式调用镜像中存在的 Shell。
services:
worker:
image: alpine:3.22
# 让 Shell 展开容器内的 HOSTNAME,随后用 exec 启动主进程
# $$ 避免 Compose 提前替换这个变量
command: ["/bin/sh", "-c", "echo 容器名称=$$HOSTNAME; exec sleep 3600"]
# 帮助转发停止信号并回收子进程
init: true
command: null 表示沿用镜像默认命令,command: [] 或 command: "" 表示清空。entrypoint 也支持这些形式;将它设置为非 null 值时,还会忽略镜像默认 CMD,需要同时检查最终执行的命令。
固定 container_name 后,Compose 无法把该服务扩容到多个容器;一般保留自动命名即可。stdin_open 和 tty 控制交互终端;后台启动的 -d 参数见后文创建并启动服务。
网络连接与端口发布
发布端口
| 配置项 | 作用 | 示例 |
|---|---|---|
ports |
将容器端口发布到主机,也就是之前说的端口映射 -p | ports: ["8080:80"] |
expose |
声明服务使用的容器端口,不发布主机端口 | expose: ["3000"] |
networks |
把服务连接到指定网络 | networks: [app_net] |
extra_hosts |
为容器添加静态主机名解析 | extra_hosts: ["host.docker.internal:host-gateway"] |
dns |
指定容器使用的 DNS 服务器 | dns: ["1.1.1.1"] |
端口的常见短格式:
| 写法 | 含义 |
|---|---|
"8080:80" |
主机 8080 端口转发到容器 80 端口,默认 TCP |
"127.0.0.1:3000:3000" |
仅通过主机回环地址发布容器 3000 端口 |
"5353:53/udp" |
主机 5353 端口转发到容器 53/UDP 端口 |
示例:
services:
web:
image: nginx:alpine
ports:
# 仅允许通过本机 127.0.0.1:8080 访问该端口
- "127.0.0.1:8080:80"
端口也支持长格式:
| 子配置项 | 作用 | 示例 |
|---|---|---|
target |
容器端口 | target: 80 |
published |
主机端口,建议写字符串 | published: "8080" |
host_ip |
绑定的主机 IP 地址 | host_ip: 127.0.0.1 |
protocol |
传输协议 | protocol: tcp |
services:
web:
image: nginx:alpine
ports:
# 与上面的 127.0.0.1:8080:80 短格式等价
- target: 80
published: "8080"
host_ip: 127.0.0.1
protocol: tcp
同一网络中的容器使用服务名和容器端口通信,例如 api 通过 db:3306 连接数据库,无须为数据库配置 ports 或 expose。服务进程需要监听容器可访问的地址,例如 0.0.0.0;仅监听容器内 127.0.0.1 时,其他容器无法访问它。
声明与使用网络
未显式配置网络时,Compose 会创建项目默认网络。需要划分连接范围时,先在顶层 networks 声明,再由服务引用。
| 顶层网络子配置项 | 作用 | 示例 |
|---|---|---|
driver |
指定网络驱动 | driver: bridge |
name |
指定实际网络名称,不自动附加项目名前缀 | name: shared-app-net |
external |
使用已存在、由项目外部管理的网络 | external: true |
internal |
创建与外部网络隔离的网络 | internal: true |
attachable |
在驱动支持时允许独立容器加入,例如可附加的 overlay 网络 | attachable: true |
labels |
为网络添加元数据 | labels: { env: dev } |
ipam |
配置 IP 地址分配 | ipam: 下设置 config |
ipam.config[].subnet |
设置子网,需避免与已有网络冲突 | subnet: 172.28.0.0/16 |
ipam.config[].gateway |
设置子网网关 | gateway: 172.28.0.1 |
示例:
services:
web:
image: nginx:alpine
networks:
# 映射写法可以为该服务设置网络别名
app_net:
aliases:
- frontend
networks:
app_net:
# 自定义本地 bridge 网络与地址范围
driver: bridge
ipam:
config:
- subnet: 172.28.0.0/16
gateway: 172.28.0.1
只需要加入网络时,服务内也可以写 networks: [app_net]。网络别名只在该网络内生效。
外部网络必须提前存在;设置 external: true 后,除 name 外不能再同时配置 driver、ipam 等创建属性。详细说明见 Compose 网络配置。
数据卷与目录挂载
服务中的 volumes 决定“把什么挂载到容器哪里”;顶层 volumes 决定“命名卷如何创建或引用”。
例如,项目 myapp 声明 db_data 时,默认创建或复用实际名为 myapp_db_data 的卷。更换项目名可能改用另一份数据卷;需要固定实际卷名时,可以设置下面的 name。
| 服务挂载写法 | 含义 |
|---|---|
db_data:/var/lib/mysql |
把命名卷挂载到容器目录 |
./config:/etc/app |
把 Compose 文件所在目录下的 config 绑定挂载到容器 |
./config:/etc/app:ro |
以只读方式绑定挂载主机目录 |
db_data:/data:ro |
以只读方式挂载命名卷 |
示例:
services:
db:
image: mysql:8.4
environment:
MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD:?请配置数据库 root 密码}"
volumes:
# 数据文件保存在命名卷中,重建容器后仍可继续使用
- db_data:/var/lib/mysql
volumes:
# 由 Compose 创建并管理的命名卷
db_data:
driver: local
labels:
app: myapp
| 顶层卷子配置项 | 作用 | 示例 |
|---|---|---|
driver |
指定卷驱动 | driver: local |
driver_opts |
向卷驱动传入参数,具体键取决于驱动 | driver_opts: { type: tmpfs, device: tmpfs } |
labels |
为卷添加元数据 | labels: { env: dev } |
external |
引用项目之外已存在的卷 | external: true |
name |
指定实际卷名,不自动附加项目名前缀 | name: shared_db_data |
只设置 name 时,卷仍由 Compose 管理。需要复用项目之外独立管理的卷时,再设置 external: true;卷必须提前存在,其创建和备份由使用者负责。
先用前文的数据卷命令准备外部卷:
# 在 Compose 项目之外创建并核对外部卷
docker volume create shared_db_data
docker volume inspect shared_db_data
再替换顶层卷声明:
# 该片段替换上面示例的顶层 volumes;服务仍引用 db_data
volumes:
db_data:
# 不创建新卷,而是查找已经存在的 shared_db_data
external: true
name: shared_db_data
设置 external: true 时,除 name 外不能同时配置 driver、labels 等创建属性。配置定义详见 Compose 数据卷配置;命名卷、匿名卷和外部卷在移除项目时的保留规则,统一见后文停止并移除项目。
自动重启与优雅停止
restart 值 |
作用 | 适用情况 |
|---|---|---|
"no" |
不自动重启,默认策略 | 临时任务或手动管理 |
always |
容器退出后重启;手动停止后暂不重启,守护进程重启后可以再次启动 | 需要长期运行的服务 |
on-failure |
仅在主进程以非零退出码退出时重启 | 出错后重试 |
on-failure:5 |
仅异常退出时重启,最多重试 5 次 | 限制错误重试次数 |
unless-stopped |
自动重启,但手动停止后在守护进程重启时仍保持停止 | 常驻服务,且希望保留手动停止状态 |
restart 与停止信号相关配置:
| 配置项 | 作用 | 示例 |
|---|---|---|
restart |
设置主进程退出后的重启策略 | restart: unless-stopped |
stop_signal |
覆盖停止信号;未配置时沿用镜像的 STOPSIGNAL,镜像也未设置时使用 SIGTERM |
stop_signal: SIGTERM |
stop_grace_period |
发送停止信号后等待的时长,超时后强制终止 | stop_grace_period: 30s |
services:
api:
image: my-api:1.0
# 异常退出后自动恢复;手动停止时保持停止
restart: unless-stopped
# 应用需要处理 SIGTERM,关闭连接并完成清理
stop_signal: SIGTERM
stop_grace_period: 30s
启动依赖与健康检查
判断服务是否健康
healthcheck 定期在容器内执行检查命令,以退出码判断服务状态。
| 子配置项 | 作用 | 示例 |
|---|---|---|
test |
设置健康检查命令 | ["CMD", "node", "/app/healthcheck.js"] |
interval |
正常检查间隔 | interval: 10s |
timeout |
单次检查超时时间 | timeout: 5s |
retries |
连续失败多少次后标记为不健康 | retries: 5 |
start_period |
启动宽限期;期间失败通常不计数,成功后进入正常计数 | start_period: 30s |
start_interval |
启动宽限期内的检查间隔 | start_interval: 2s |
disable |
禁用健康检查,包括镜像自带的检查 | disable: true |
test 形式 |
执行方式 | 示例 |
|---|---|---|
CMD |
直接执行程序及参数,不经过 Shell | ["CMD", "node", "/app/healthcheck.js"] |
CMD-SHELL |
经容器默认 Shell 执行,支持变量展开等语法 | ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/health"] |
| 字符串 | 等同于 CMD-SHELL |
test: curl -fsS http://127.0.0.1:3000/health |
NONE |
禁用健康检查 | test: ["NONE"] |
示例片段:
services:
api:
healthcheck:
# 镜像必须安装 curl,且应用需要实现该健康检查接口
test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:3000/health"]
interval: 10s
timeout: 5s
retries: 5
# 给应用留出初始化时间
start_period: 30s
start_interval: 2s
start_interval 需要 Compose 2.20.2 及以上版本,并要求 Docker Engine 25.0 及以上版本支持。
健康状态变为 unhealthy 本身不会触发单机 Docker 的自动重启策略;应用主进程退出后,才按前面的 restart 策略处理。健康状态也可作为下一节服务启动依赖的等待条件。相关定义见 健康检查 和 容器重启策略。
控制服务启动顺序
depends_on 的短格式只表达启动依赖,不等待应用完成初始化。
services:
api:
image: my-api:1.0
# 先启动 db,再启动 api;此时 db 不一定已经能接受连接
depends_on:
- db
db:
image: mysql:8.4
environment:
MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD:?请配置数据库 root 密码}"
长格式可以进一步控制等待条件:
| 子配置项 | 作用 | 示例 |
|---|---|---|
condition |
设置依赖满足条件 | condition: service_healthy |
restart |
Compose 显式更新或重启依赖后,也重启当前服务 | restart: true |
required |
是否要求依赖启动且可用,默认 true;设为 false 时缺失或不可用仅警告 |
required: false |
condition 值 |
含义 | 使用场景 |
|---|---|---|
service_started |
依赖容器已启动 | 不需要等待应用就绪 |
service_healthy |
依赖通过健康检查 | API 等待数据库可用 |
service_completed_successfully |
依赖任务成功退出 | 应用等待数据迁移任务完成 |
长格式示例片段,需与 api、db 的其他配置合并:
services:
api:
depends_on:
db:
# db 必须配置有效的 healthcheck
condition: service_healthy
# 由 Compose 显式重启或更新 db 时,连带重启 api
restart: true
depends_on.restart 不是服务的自动重启策略;依赖容器崩溃后被 Docker 自动拉起,不会因此自动重启当前服务。depends_on.restart、required 分别需要 Compose 2.17.0、2.20.0 及以上版本。
应用启动后,仍需自行处理数据库等依赖的断线并重试连接。详细定义见 Compose 启动依赖。
文件系统、权限与资源
控制文件系统和进程权限
| 配置项 | 作用 | 示例 |
|---|---|---|
read_only |
将容器根文件系统设为只读,挂载点仍按各自设置处理 | read_only: true |
tmpfs |
挂载临时内存文件系统,容器停止后内容不保留 | tmpfs: ["/tmp"] |
cap_drop |
移除 Linux capabilities | cap_drop: [ALL] |
cap_add |
按需要增加 Linux capabilities | cap_add: [NET_ADMIN] |
security_opt |
设置额外安全选项 | security_opt: ["no-new-privileges:true"] |
privileged |
开启特权模式,授予广泛的主机能力和设备访问 | privileged: true |
示例:
services:
worker:
image: alpine:3.22
# 以普通 UID/GID 运行一个演示进程
user: "1000:1000"
command: ["sleep", "3600"]
# 根文件系统只读;需要临时写入的目录单独使用 tmpfs
read_only: true
tmpfs:
- /tmp
# 移除非必需能力,阻止进程通过执行程序获得新权限
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
应用需要写入的日志、缓存、上传目录应另行配置卷或 tmpfs。privileged 适用于确有需要的特殊场景,不宜作为处理普通文件权限问题的通用方案。
限制 CPU、内存和文件句柄
单机 Compose 常用服务级配置:
| 配置项 | 作用 | 示例 |
|---|---|---|
cpus |
限制可使用的 CPU 份额,1.0 表示一个 CPU 的计算时间 |
cpus: 1.0 |
mem_limit |
设置内存硬限制 | mem_limit: 512m |
mem_reservation |
设置内存软限制,在内存争用时发挥作用 | mem_reservation: 128m |
ulimits |
设置进程资源限制,例如文件描述符数量 | ulimits: { nofile: { soft: 1024, hard: 2048 } } |
示例:
services:
api:
image: my-api:1.0
# 最多使用一个 CPU 的计算时间和 512 MiB 内存
cpus: 1.0
mem_limit: 512m
# 软限制应小于硬限制,不代表提前独占这些内存
mem_reservation: 128m
ulimits:
nofile:
# 分别设置文件描述符的软限制和硬限制
soft: 1024
hard: 2048
也可以通过 deploy.resources 声明资源限制:
| 子配置项 | 作用 | 示例 |
|---|---|---|
deploy.resources.limits.cpus |
设置 CPU 上限 | cpus: "1.0" |
deploy.resources.limits.memory |
设置内存上限 | memory: 512M |
deploy.resources.reservations.memory |
声明内存预留;具体作用取决于部署实现 | memory: 128M |
services:
api:
image: my-api:1.0
deploy:
resources:
# 设置容器可使用的资源上限
limits:
cpus: "1.0"
memory: 512M
# 当前单机 Compose 将内存预留映射为软限制
reservations:
memory: 128M
deploy 的支持范围取决于部署实现,不能笼统理解为“只有 Swarm 才生效”。当前 Docker Compose 支持上述 CPU、内存限制及内存软限制;Swarm 还会使用资源预留进行调度。若同时设置服务级与 deploy 中对应的限制,应保持一致。参见 部署资源规格 与 Docker Compose 的资源映射实现。
日志、标签与可选服务
配置日志与资源标签
| 配置项 | 作用 | 示例 |
|---|---|---|
logging.driver |
指定日志驱动 | driver: local |
logging.options |
传入驱动支持的选项,值写成字符串 | max-size: "10m"、max-file: "3" |
labels |
为服务容器添加元数据,不会自动成为环境变量 | labels: { "com.example.app": myapp } |
示例:
services:
api:
image: my-api:1.0
logging:
# local 驱动支持轮转;以下选项限制每个日志文件和保留数量
driver: local
options:
max-size: "10m"
max-file: "3"
labels:
# 标签用于标记和筛选资源
com.example.app: myapp
com.example.env: production
日志选项随驱动而变化,以上选项适用于 local 日志驱动。卷、网络也有各自的 labels,与服务容器标签分别设置。
按需启用服务
profiles 将服务加入可选配置档案,常用于调试、管理工具和辅助任务。
services:
web:
# 没有 profiles 的服务默认参与启动
image: nginx:alpine
debug:
image: busybox:1.37
command: ["sleep", "3600"]
# 普通 up 不启动此服务,启用 debug 档案后才参与
profiles:
- debug
下面只演示 profile 对服务选择的影响,命令格式和参数位置见后文选择项目与全局参数。这组命令使用本节的 web、debug 配置,按场景选择执行:
# 启动默认服务,不启动配置了 profiles 的 debug 服务
docker compose up -d
# 启用 debug 档案,启动默认服务和该档案下的服务
docker compose --profile debug up -d
# 显式点名 debug 服务时,可直接启动它及其必要依赖
docker compose up -d debug
显式点名某个服务不会自动启动同一档案内的其他服务。详见 Compose profiles。
配置文件与敏感文件
使用 configs 挂载配置文件
configs 将配置文件声明与服务使用分开,适合应用配置等非敏感内容。
| 配置项 | 作用 | 示例 |
|---|---|---|
顶层 configs.<名称>.file |
指定主机上的配置源文件 | file: ./config/app.conf |
服务 configs |
声明当前服务使用哪些配置 | configs: [app_config] |
服务引用中的 source |
指向顶层配置名称 | source: app_config |
服务引用中的 target |
指定容器内文件路径 | target: /etc/app/app.conf |
示例:
services:
api:
image: my-api:1.0
configs:
# 将已存在的主机配置文件提供给 api
- source: app_config
target: /etc/app/app.conf
configs:
app_config:
# 启动前准备好此文件;应用也需要读取容器内的目标路径
file: ./config/app.conf
短格式 configs: [app_config] 在 Linux 容器内默认挂载到 /app_config;需要固定应用路径时使用长格式的 target。详见 Compose configs。
使用 secrets 提供敏感文件
secrets 让服务按名称获取密码、令牌等文件;声明资源后,还必须在服务中授权使用。
| 配置项 | 作用 | 示例 |
|---|---|---|
顶层 secrets.<名称>.file |
指定主机上的敏感源文件 | file: ./secrets/db_password.txt |
服务 secrets |
允许该服务读取指定 secret | secrets: [db_password] |
| 默认容器路径 | Linux 容器中默认为 /run/secrets/<名称> |
/run/secrets/db_password |
应用的 *_FILE 变量 |
由应用或镜像约定,用来读取某个文件中的值 | MySQL 的 MYSQL_ROOT_PASSWORD_FILE |
示例:
services:
db:
image: mysql:8.4
environment:
# MySQL 官方镜像支持通过该变量从文件读取初始 root 密码
MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
secrets:
# 仅获得这里明确授权的敏感文件
- db_root_password
volumes:
- db_data:/var/lib/mysql
secrets:
db_root_password:
# 文件内容仅写密码;启动前创建,并妥善设置主机文件权限
file: ./secrets/db_root_password.txt
volumes:
db_data:
*_FILE 不是所有程序都自动支持的通用功能,应用需要主动读取文件。本地 Docker Compose 使用主机文件提供 secret,不等同于加密的密码保管服务;源文件不应提交到公开仓库。参见 Compose secrets 用法。
Compose 命令
配置文件准备好后,使用 docker compose 管理项目。本章先准备一个命令练习项目,再按操作目标介绍命令;完整参数可查阅 Compose 命令参考。
SERVICE 指配置中 services 下的服务名,例如 api,不要求填写实际容器名称。支持多个服务的命令通常可省略服务名,对项目中的适用服务一起操作。
准备一个示例项目
新建 compose-cli-demo 目录,在其中准备以下 Dockerfile 和 compose.yaml。本章命令统一在此目录执行;除特别说明外,均使用这里的 myapp 项目。各操作示例按场景选用,无需依次执行;删除容器后需要继续练习时,先用 up 重新创建并启动。
username/myapp:1.0 是示例镜像名,发布前替换为自己有推送权限的仓库名称。
Dockerfile:
# 为 api 镜像提供 Node.js 运行环境
FROM node:22-alpine
# 设置容器中执行命令的默认目录
WORKDIR /app
compose.yaml:
name: myapp
services:
web:
image: nginx:alpine
ports:
- "${WEB_PORT:-8084}:80"
api:
image: username/myapp:1.0
build:
context: .
command:
- node
- -e
- |
const fs = require('node:fs');
fs.appendFileSync('/data/startup.log', new Date().toISOString() + '\n');
require('node:http')
.createServer((req, res) => res.end('Hello Compose\n'))
.listen(3000, '0.0.0.0', () => console.log('API listening on 3000'));
environment:
NODE_ENV: ${NODE_ENV:-production}
volumes:
- app_data:/data
volumes:
app_data:
练习中,web 提供 Nginx 默认页面,默认访问地址为 http://localhost:8084;api 从当前目录构建并运行一个 HTTP 服务,将启动记录写入 app_data 卷。两个服务通过默认网络通信,api 不发布宿主机端口,便于后面演示多实例运行。
web 没有配置 API 反向代理,访问 Nginx 页面不会自动转发到 api;API 在项目网络内通过 api:3000 访问。
首次练习时先校验、启动,再验证服务间通信;各子命令的参数会在后续小节展开:
# 检查 compose.yaml 的结构和变量替换是否有效
docker compose config -q
# 构建 api 镜像,并在后台创建和启动项目服务
docker compose up -d --build
# 在 web 容器内通过服务名访问 api,验证项目默认网络中的服务发现
docker compose exec web wget -qO- http://api:3000
命令汇总
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 检查配置 | docker compose config [OPTIONS] [SERVICE...] |
docker compose config -q |
合并、解析并校验配置 |
| 创建并启动服务 | docker compose up [OPTIONS] [SERVICE...] |
docker compose up -d |
根据配置创建或更新服务容器并启动 |
| 启动已有服务容器 | docker compose start [OPTIONS] [SERVICE...] |
docker compose start api |
启动已经存在但已停止的服务容器 |
| 停止服务 | docker compose stop [OPTIONS] [SERVICE...] |
docker compose stop api |
停止服务并保留容器 |
| 重启服务 | docker compose restart [OPTIONS] [SERVICE...] |
docker compose restart api |
重启已有的服务容器 |
| 删除已停止容器 | docker compose rm [OPTIONS] [SERVICE...] |
docker compose rm api |
删除已经停止的服务容器 |
| 停止并移除项目 | docker compose down [OPTIONS] [SERVICES] |
docker compose down |
默认移除项目服务容器和项目管理的网络 |
| 查看服务状态 | docker compose ps [OPTIONS] [SERVICE...] |
docker compose ps |
查看项目服务容器的状态与端口 |
| 查看日志 | docker compose logs [OPTIONS] [SERVICE...] |
docker compose logs api |
查看服务容器的日志 |
| 实时查看日志 | docker compose logs [OPTIONS] [SERVICE...] |
docker compose logs -f api |
持续跟踪服务日志 |
| 查看进程 | docker compose top [SERVICES...] |
docker compose top api |
查看服务容器中的进程 |
| 进入运行中的服务容器 | docker compose exec [OPTIONS] SERVICE COMMAND [ARGS...] |
docker compose exec api sh |
在已有容器中启动新进程 |
| 运行一次性任务 | docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...] |
docker compose run --rm api node -v |
使用服务配置创建新容器执行任务 |
| 构建镜像 | docker compose build [OPTIONS] [SERVICE...] |
docker compose build api |
构建声明了 build 的服务镜像 |
| 拉取镜像 | docker compose pull [OPTIONS] [SERVICE...] |
docker compose pull web |
下载服务配置引用的镜像,不启动容器 |
| 发布镜像 | docker compose push [OPTIONS] [SERVICE...] |
docker compose push api |
推送配置中 image 指定的镜像 |
选择项目与全局参数
全局参数写在 docker compose 与子命令之间;子命令自己的参数写在子命令后面。
docker compose [GLOBAL_OPTIONS] COMMAND [OPTIONS] [ARGS...]
OPTIONS(全局参数):
| 参数 | 作用 | 示例 |
|---|---|---|
-f FILE、--file FILE |
指定配置文件,可以重复指定并依次合并 | docker compose -f compose.prod.yaml up -d |
-p NAME、--project-name NAME |
指定项目名称,区分不同项目的容器和默认资源名称 | docker compose -p myapp up -d |
--env-file FILE |
指定提供配置变量插值的环境文件 | docker compose --env-file .env.prod up -d |
--profile NAME |
启用配置中指定的服务 profile | docker compose --profile debug up -d |
--project-directory PATH |
指定项目工作目录及相对路径基准 | docker compose --project-directory /opt/myapp up -d |
--progress TYPE |
设置进度显示格式,如 auto、tty、plain、json、quiet |
docker compose --progress plain build api |
多个 -f 文件按顺序合并,后面的配置会补充或覆盖前面的配置。后续管理同一项目时,应继续使用一致的项目名和配置文件组合。示例中额外指定的配置、环境文件或 profile,需要在自己的项目中先准备好。
--env-file 替换的是配置插值使用的变量文件;它与服务级 env_file 的区别见前文环境变量与变量插值。
示例:
# 合并基础配置与已准备好的生产配置,查看最终结果
docker compose -f compose.yaml -f compose.prod.yaml config
# 使用指定的项目名启动服务,后续使用同一项目名查看状态
docker compose -p myapp up -d
# 查看刚才指定的 myapp 项目,而非其他目录或项目中的容器
docker compose -p myapp ps
操作 Compose 项目
检查配置
合并配置文件、解析变量和简写形式,检查最终使用的服务配置。
docker compose config [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-q、--quiet |
仅校验,不输出完整配置 | docker compose config -q |
--services |
只列出服务名 | docker compose config --services |
--images |
只列出引用的镜像名称 | docker compose config --images |
--environment |
查看用于配置变量插值的环境值 | docker compose config --environment |
示例:
# 校验当前项目配置,存在错误时返回非零退出码
docker compose config -q
# 列出最终配置中的所有服务名
docker compose config --services
创建与启动服务
创建并启动服务
根据配置构建、创建并启动服务。配置或镜像发生变化时,up 可以重新创建对应容器,并继续挂载原有命名卷。
docker compose up [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-d、--detach |
在后台运行服务 | docker compose up -d |
--build |
启动前构建镜像 | docker compose up -d --build api |
--no-build |
禁止构建镜像 | docker compose up -d --no-build |
--force-recreate |
即使配置和镜像没有变化,也重新创建容器 | docker compose up -d --force-recreate api |
--no-recreate |
已存在的容器不重新创建,与 --force-recreate 互斥 |
docker compose up -d --no-recreate |
--remove-orphans |
删除同一项目中当前配置未声明的服务容器 | docker compose up -d --remove-orphans |
--pull POLICY |
指定启动前拉取策略:always、missing、never |
docker compose up -d --pull always web |
--wait |
等待服务运行或健康,隐含后台模式 | docker compose up --wait |
--wait-timeout SECONDS |
设置等待运行或健康状态的超时秒数 | docker compose up --wait --wait-timeout 60 |
--scale SERVICE=NUM |
指定服务实例数量 | docker compose up -d --scale api=2 |
没有配置 healthcheck 的服务,--wait 只等待其进入运行状态。需要确认接口或数据库已经可用时,应为对应服务配置健康检查。
扩容时不要设置固定的 container_name,多个实例也不能同时占用同一个宿主机端口。示例的 api 没有这些限制,可以演示多实例运行。
示例:
# 应用配置和代码构建结果,后台启动或更新 api 服务
docker compose up -d --build api
# 等待项目服务运行或健康,最多等待 60 秒
docker compose up --wait --wait-timeout 60
# 将 api 服务调整为两个实例
docker compose up -d --scale api=2
启动已有服务容器
启动已经创建但处于停止状态的服务容器;不会创建缺失的容器,也不会应用新的服务配置。
docker compose start [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--wait |
等待服务进入运行或健康状态 | docker compose start --wait api |
--wait-timeout SECONDS |
设置等待状态变化的超时秒数 | docker compose start --wait --wait-timeout 60 api |
示例:
# 启动已经存在且已经停止的 api 服务容器
docker compose start api
停止、重启与删除服务
停止与重启服务
stop 停止服务并保留容器;restart 重新启动已有容器。修改了环境变量、挂载等配置后,应使用 up -d 应用变化。
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 停止服务 | docker compose stop [OPTIONS] [SERVICE...] |
docker compose stop api |
停止但不删除服务容器 |
| 重启服务 | docker compose restart [OPTIONS] [SERVICE...] |
docker compose restart api |
重启现有容器,不应用新的配置 |
OPTIONS:
| 适用命令 | 参数 | 作用 | 示例 |
|---|---|---|---|
stop、restart |
-t、--timeout |
设置停止阶段的等待秒数 | docker compose stop -t 30 api |
restart |
--no-deps |
不同时重启相关依赖服务 | docker compose restart --no-deps api |
示例:
# 停止 api 服务,最多等待 30 秒
docker compose stop -t 30 api
# 重启已有 api 容器,继续使用其当前配置
docker compose restart api
删除已停止的服务容器
删除停止状态的服务容器,默认会提示确认。
docker compose rm [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--force |
跳过交互确认,不代表强制终止运行中容器 | docker compose rm -f api |
-s、--stop |
删除前先停止容器 | docker compose rm -s api |
-v、--volumes |
同时删除关联匿名卷,不删除命名卷 | docker compose rm -v api |
示例:
# 删除已停止的 api 服务容器,执行前提示确认
docker compose rm api
# 先停止再删除 api 服务容器,并跳过交互确认
docker compose rm -s -f api
停止并移除项目
省略服务参数时,停止并移除项目的服务容器和项目管理的网络。默认保留数据卷;声明为 external 的网络和卷始终不由 down 删除。
docker compose down [OPTIONS] [SERVICES]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-v、--volumes |
删除配置中声明的命名卷和容器关联匿名卷,外部卷除外 | docker compose down -v |
--rmi local |
删除没有自定义标签的服务镜像 | docker compose down --rmi local |
--rmi all |
删除服务使用的镜像 | docker compose down --rmi all |
--remove-orphans |
同时删除同一项目中当前配置未声明的服务容器 | docker compose down --remove-orphans |
-t、--timeout |
设置停止容器时的等待秒数 | docker compose down -t 30 |
--rmi local 中的 local 不表示删除所有本地镜像。匿名卷虽然默认保留,后续 up 通常不会自动重新挂回原匿名卷;长期保存的数据应使用命名卷或绑定挂载。
示例:
# 停止并移除整个项目的服务容器和网络,保留命名卷中的数据
docker compose down
# 清理已经确认不再需要的项目,并删除其声明的非外部数据卷及关联匿名卷
docker compose down -v
查看服务状态与日志
查看服务容器状态
查看项目中服务容器的运行状态和端口发布情况,默认显示运行中的容器。
docker compose ps [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
同时显示已停止等其他状态的容器 | docker compose ps -a |
-q、--quiet |
只显示容器 ID | docker compose ps -q api |
--format FORMAT |
设置输出格式,如 table 或 json |
docker compose ps --format json |
--status STATUS |
按容器状态筛选 | docker compose ps -a --status exited |
--services |
只显示服务名 | docker compose ps --services |
示例:
# 查看当前项目中运行的服务容器及端口
docker compose ps
# 同时查看已经停止的服务容器
docker compose ps -a
查看服务日志
聚合一个或多个服务的标准输出和标准错误日志,省略服务名时查看项目适用服务的日志。
docker compose logs [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-f、--follow |
持续跟踪新日志 | docker compose logs -f api |
-n N、--tail N |
查看每个容器最后 N 行日志 | docker compose logs --tail 100 api |
--since TIME |
查看指定时间之后的日志 | docker compose logs --since 30m api |
--until TIME |
查看指定时间之前的日志 | docker compose logs --until 10m api |
-t、--timestamps |
显示日志时间戳 | docker compose logs -t api |
示例:
# 查看 api 服务已经记录的日志
docker compose logs api
# 先显示最后 100 行日志,再持续跟踪新日志,并显示时间戳
docker compose logs -f --tail 100 -t api
查看服务容器进程
docker compose top [SERVICES...]
示例:
# 查看 api 服务容器中的进程
docker compose top api
在服务容器中执行任务
在运行中的服务容器执行命令
exec 在已有的运行中容器里启动新进程。Compose 默认保持交互并分配 TTY,进入 Shell 通常无需再写 -it。
docker compose exec [OPTIONS] SERVICE COMMAND [ARGS...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-i、--interactive |
控制交互输入,默认开启,可设置为 false |
docker compose exec --interactive=false -T api node -v |
-T、--no-tty |
禁用伪终端,适用于脚本等场景 | docker compose exec -T api node -v |
-u、--user USER |
指定本次进程的执行用户 | docker compose exec -u root api id |
-w、--workdir PATH |
指定本次命令的工作目录 | docker compose exec -w /app api pwd |
-e、--env KEY=VALUE |
为本次执行的进程设置环境变量 | docker compose exec -e NODE_ENV=test api env |
--index INDEX |
多实例时选择指定序号的容器 | docker compose exec --index 2 api sh |
示例:
# 在正在运行的 api 服务容器中打开交互式 sh
docker compose exec api sh
# 在脚本中查询 api 容器的 Node.js 版本,关闭交互输入和伪终端
docker compose exec --interactive=false -T api node -v
创建一次性任务容器
run 使用指定服务的配置创建一个新容器,传入的命令会覆盖服务的默认命令,适用于检查环境、执行迁移或测试等一次性任务。
docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--rm |
任务结束后删除本次创建的容器 | docker compose run --rm api node -v |
--no-deps |
不自动启动依赖服务 | docker compose run --rm --no-deps api node -v |
-e、--env KEY=VALUE |
为本次任务设置环境变量 | docker compose run --rm -e NODE_ENV=test api env |
-P、--service-ports |
启用服务配置中声明的宿主机端口发布 | docker compose run --rm --service-ports web |
-p、--publish |
为任务容器单独指定宿主机端口映射 | docker compose run --rm -p 18080:3000 api |
run 默认不发布服务声明的宿主机端口。使用 --service-ports 时,需要确保对应宿主机端口没有被现有容器占用,也可以通过 -p 指定其他端口。
示例:
# 创建临时 api 容器查询 Node.js 版本,执行完毕后删除任务容器
docker compose run --rm api node -v
# 在独立任务容器中设置测试环境变量并输出其值,退出后自动删除任务容器
docker compose run --rm --no-deps -e NODE_ENV=test api node -p 'process.env.NODE_ENV'
exec 复用运行中的服务容器,run 新建任务容器;这两种操作的具体行为可查阅 exec 和 run 官方说明。
构建与发布服务镜像
构建服务镜像
只构建配置了 build 的服务,不会因此启动服务容器。示例中只有 api 配置了构建上下文,web 直接使用已有的 Nginx 镜像。
docker compose build [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--no-cache |
构建时不使用缓存 | docker compose build --no-cache api |
--pull |
尝试拉取更新的基础镜像 | docker compose build --pull api |
示例:
# 根据 api 的 build 配置构建镜像,使用其 image 字段指定的标签
docker compose build api
# 拉取更新的基础镜像,并在不使用缓存的情况下重新构建 api 镜像
docker compose build --pull --no-cache api
拉取服务镜像
下载配置引用的镜像,不创建或启动服务容器。需要根据本地 Dockerfile 构建的服务,可以通过 --ignore-buildable 跳过。
docker compose pull [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--policy POLICY |
设置拉取策略,支持 missing、always |
docker compose pull --policy always web |
--ignore-buildable |
跳过配置了 build 的服务 |
docker compose pull --ignore-buildable |
--include-deps |
同时拉取依赖服务的镜像 | docker compose pull --include-deps api |
示例:
# 拉取 web 服务配置引用的 nginx:alpine 镜像
docker compose pull web
# 使用刚拉取的镜像启动或更新 web 服务容器
docker compose up -d web
发布服务镜像
将服务 image 字段指定的镜像推送到仓库。发布前需要先完成构建或准备好本地镜像,并登录有推送权限的仓库;示例中发布 api,不向官方 Nginx 仓库推送。
docker compose push [OPTIONS] [SERVICE...]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
--include-deps |
同时发布依赖服务的镜像,相关镜像也需要有推送权限 | docker compose push --include-deps api |
-q、--quiet |
减少推送过程的输出 | docker compose push -q api |
示例:
# 将已经构建、且仓库名称已替换为自己命名空间的 api 镜像推送到仓库
docker compose push api
常见操作的区别
| 目标 | 使用方式 | 关键区别 |
|---|---|---|
| 首次部署,或应用配置、镜像的变化 | docker compose up -d,需要构建时增加 --build |
按需创建或重新创建容器 |
| 启动已有的停止状态容器 | docker compose start |
不创建缺失容器,不应用新配置 |
| 重启当前容器中的进程 | docker compose restart |
继续使用当前容器配置 |
| 暂时停止服务 | docker compose stop |
保留服务容器,后续可通过 start 恢复 |
| 移除项目容器和网络 | docker compose down |
默认保留卷,-v 会额外清理非外部卷 |
| 在已有容器中执行命令 | docker compose exec |
要求目标服务容器正在运行 |
| 按服务配置执行独立任务 | docker compose run --rm |
创建新的任务容器,结束后删除 |
Compose 综合示例:NestJS 与 MySQL
掌握配置和命令后,再将构建镜像、环境变量、端口、命名卷、健康检查和启动依赖组合到一个项目中。
本例使用独立的 nest-demo 目录和同名项目,以下命令在此目录执行。server 中需已有可构建的 NestJS 项目,Dockerfile 能启动应用,应用读取下列 DB_* 变量并监听 0.0.0.0:3000;变量名需要与实际项目代码一致。
目录结构:
nest-demo/
├── compose.yaml
├── .env
└── server/
├── Dockerfile
├── package.json
└── src/
compose.yaml:
name: nest-demo
services:
db:
image: mysql:8.4
environment:
# 使用 .env 中的值初始化数据库,缺失时直接报错
MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD:?请在 .env 中配置 MYSQL_ROOT_PASSWORD}"
MYSQL_DATABASE: app
MYSQL_USER: app_user
MYSQL_PASSWORD: "${MYSQL_PASSWORD:?请在 .env 中配置 MYSQL_PASSWORD}"
volumes:
# 数据库文件写入命名卷,重建容器后保留
- db_data:/var/lib/mysql
healthcheck:
# 使用应用账号连接指定数据库并执行查询,确认实际连接可用
# $$ 将变量留给容器内 Shell 展开
test:
- CMD-SHELL
- >-
mysql --protocol=TCP -h 127.0.0.1
-u"$$MYSQL_USER" -p"$$MYSQL_PASSWORD"
"$$MYSQL_DATABASE" -e "SELECT 1" >/dev/null
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
restart: unless-stopped
api:
# 本地构建镜像并使用固定名称
image: my-api:1.0
build:
context: ./server
dockerfile: Dockerfile
# 优先按本地源码构建,避免尝试拉取同名远程镜像
pull_policy: build
environment:
NODE_ENV: production
# 使用服务名和容器端口连接数据库
DB_HOST: db
DB_PORT: "3306"
DB_DATABASE: app
DB_USERNAME: app_user
DB_PASSWORD: "${MYSQL_PASSWORD:?请在 .env 中配置 MYSQL_PASSWORD}"
ports:
# 只在本机发布 API,访问地址为 http://127.0.0.1:3000
- "127.0.0.1:3000:3000"
depends_on:
db:
# 等待数据库查询成功后再启动 API
condition: service_healthy
restart: unless-stopped
init: true
volumes:
# 两个服务使用默认网络;数据库不需要发布主机端口
db_data:
.env:
# 换成实际密码;此文件仅用于本地示例,避免提交到仓库
MYSQL_ROOT_PASSWORD=replace-with-root-password
MYSQL_PASSWORD=replace-with-app-password
配置和 .env 准备好后,按以下顺序校验、启动并查看状态。日志命令会持续运行,查看后按 Ctrl+C 退出日志跟踪;最后需要结束练习时,再执行 down:
# 检查配置语法、插值和资源引用;-q 避免打印解析后的密码
docker compose config -q
# 构建 API 镜像并在后台启动,API 等待数据库健康检查通过
docker compose up -d --build
# 查看服务容器的运行状态和数据库健康状态
docker compose ps
# 持续查看 API 与数据库日志,排查启动和连接问题
docker compose logs -f api db
# 停止并移除项目容器和默认网络,保留数据库命名卷
docker compose down
MySQL 初始化变量只在数据目录为空时用于创建账号和数据库;修改 .env 后重建容器,不会自动修改已有数据库中的密码,需要通过数据库语句更新。关于初始化行为可参考 MySQL 官方镜像说明。
健康检查使用实际账号查询数据库。mysqladmin ping 即使遇到 Access denied 也可能返回成功,因此不能用它证明应用账号可以登录;参见 MySQL 的 ping 说明。
系统信息与清理
常用命令汇总
| 操作 | 命令 | 示例 | 说明 |
|---|---|---|---|
| 查看版本 | docker version [OPTIONS] |
docker version |
查看客户端与服务端版本 |
| 查看系统信息 | docker info [OPTIONS] |
docker info |
查看运行环境和存储驱动等信息 |
| 查看磁盘占用 | docker system df [OPTIONS] |
docker system df |
查看镜像、容器、卷和构建缓存的磁盘占用 |
| 清理无用资源 | docker system prune [OPTIONS] |
docker system prune |
清理已停止容器、未使用网络、悬空镜像和构建缓存 |
| 查看命令帮助 | docker COMMAND --help |
docker run --help |
查看指定命令的语法与参数 |
查看运行环境与占用
# 查看 Docker 客户端和服务端的版本信息
docker version
# 查看 Docker 运行环境、存储驱动等信息
docker info
# 查看各类资源的磁盘占用与可回收空间
docker system df
# 查看具体镜像、容器、卷等资源的详细占用
docker system df -v
# 查看创建并启动容器时可用的参数
docker run --help
清理未使用资源
docker system prune [OPTIONS]
OPTIONS:
| 参数 | 作用 | 示例 |
|---|---|---|
-a、--all |
扩大镜像清理范围,包含未被容器引用的非悬空镜像 | docker system prune -a |
--volumes |
额外清理未使用的匿名卷,不包括命名卷 | docker system prune --volumes |
-f、--force |
跳过确认提示 | docker system prune -f |
示例:
# 清理已停止容器、未使用网络、悬空镜像和未使用构建缓存
docker system prune
# 在默认清理范围上,额外删除未被容器引用的镜像
docker system prune -a
# 在上述范围上额外清理未使用的匿名卷,执行前确认其中没有需要保留的数据
docker system prune -a --volumes
清理会删除资源,匿名卷也可能存放业务数据。执行前检查占用并备份需要保留的数据;命名卷的清理另见存储板块。具体范围见 Docker system prune。