一个服务或是一个应用程序可能会需要依赖其它的一个或多个服务才能正常运行,所以为了省下 Docker 容器得一个一个按照顺序用指令开起来的麻烦以及减少在这个过程中发生错误的概率,Docker Compose 允许把这些相关联的容器撰写在一个设置文件内,只要经过一个简单的指令就可以一同启动或是停止。

在本篇文章开始前,如果您还没设置好您的 Docker Compose 运行环境,可以参考这篇文章来设置:

请务必先阅读《Docker 的基本使用方式》再来看本篇文章。Docker Compose 现在有了不小的变化,本篇文章会尽快找时间跟进。

撰写 docker-compose.yml,并用 docker-compose 指令来创建、启动与停止容器

Docker Compose 只有一个 docker-compose.yml 设置档需要处理。我们可以添加一个目录作为 Docker 项目目录,并在这个目录下添加 docker-compose.yml 纯文字文件,并输入以下内容:

services:
  app:
    image: hello-world

docker-compose.yml 使用 YAML 格式,缩进很重要,在撰写时必须注意!

services 字段底下的每个字段都是用来创建某一种容器的设置。如上面的 docker-compose.yml 文件,app 这个服务(service)可以用来创建出基于 hello-world 映像的容器,而 app 这个名称是自订的,用来识别这是什么服务而已。通常一个服务会创建出一个容器,不过本篇文章中会说明到要如何让一个服务建出多个容器,以符合一些特定需求。

使用以下指令,可以依照 docker-compose.yml 文件中所定义的 services,将所有容器创建出来并运行。如果有容器已经创建但停止了,就会重新启动已存在的容器:

docker-compose up

以 docker-compose up 运行 hello-world

如上图,Docker Compose 会使用 hello-world 映像(如果本地端不存在这个映像就会尝试去 Docker Hub 上 pull 下来)来创建并启动容器,在屏幕上显示 Hello from Docker! 之类的消息。

Docker Compose 的映像名称也可以用冒号 : 再接上标签,如果不设置标签,预设是使用 latest 标签。

如果要指定创建出来的容器名称,可以在服务加上 container_name 字段。

services:
  app:
    image: hello-world
    container_name: hello-world

Docker Compose 也可以搭配 Dockerfile 来同时创建出映像。假设我们撰写了以下这样的 Dockerfile 文件:

FROM alpine
	 
RUN apk add --no-cache bash

CMD ["bash", "-c", "for((i=1;;i+=1)); do sleep 1 && echo \"Counter: $i\"; done"]

若要使用 Docker Compose 来创建映像,要在服务加上 build 字段,如下:

services:
  app:
    build:
      context: .

context 字段是用来设置 Docker 在创建映像时所参考的目录(build context),在这个目录底下的所有没被忽略的文件都会在创建映像的时期被传给 Docker 的守护进程处理。

此时就可以使用 docker-compose build 指令来创建映像。

以 docker-compose build 创建映像

预设的映像名称是 <项目目录名称>_<服务名称>。如果想要自订映像名称和标签,要在服务加上 image 字段。如下:

services:
  app:
    build:
      context: .
    image: counter

不过其实当服务有写 build 字段且本地端也不存在与 image 字段值(或是预设映像名称)同名的映像,docker-compose up 指令还是会先去创建映像,不必先使用 docker-compose build 指令。

我们也可以让 docker-compose up 指令在映像存在的时候去重新创建映像,只要加上 --build 参数即可。

使用 docker-compose up 指令运行这个 Docker 项目的结果如下:

以 docker-compose up 运行计数容器

此时要停止这个容器可以按下 Ctrl + c。

docker-compose up 指令可以加上 -d 参数使容器于背景运行。

若要停止这个 Docker 项目下所有运行中的容器,可以使用 docker-compose stop 指令。

若要重新启动这个 Docker 项目下所有运行中的容器,可以使用 docker-compose restart 指令。

若要删除这个 Docker 项目下所有停止中的容器,可以使用 docker-compose rm 指令。

若要停止并删除这个 Docker 项目下所有的容器,可以使用 docker-compose down 指令。

查看 Docker 项目中容器的日志

可以用 docker-compose logs 指令来查看这个 Docker 项目的容器的日志。如果想要持续监看容器的日志,还可以替 docker-compose logs 指令加上 -f 参数。

以 docker-compose logs 查看日志

之后会介绍要怎么保留 Docker 项目的日志。

改变映像预设运行的指令

继续用上面加一计数的 Docker 项目当作例子,我们可以对 docker-compose.yml 中的 app 服务加上 command 字段来修改映像的 CMD 命令所预设要运行的指令改成以下这样:

services:
  app:
    build:
      context: .
    image: counter
    command: >
      bash -c 'for((i=1;;i+=2)); do sleep 1 && echo "Counter: $$i"; done'

使用 docker-compose up 指令后,可以看到容器内输出的消息变成加二计数。第 6 行的 > 字符可以设置多行的字符串,第 7 行的 $$ 是 Docker Compose 设置档跳脱钱字号 $ 的用法。

改成加二计数的容器输出

挂载外部文件系统的目录

在服务加上 volumes 字段可以挂载 Host 的文件系统的目录到容器中。撰写方式如下:

services:
  app:
    build:
      context: .
    volumes:
      - /path/to/src1:/path/to/dest1
      - /path/to/src2:/path/to/dest2

volumes 字段的值是一个清单,要使用 - 来设置底下的项目。路径开头可以使用 ~ 字符来表示家目录。

暴露连接端口

在服务加上 ports 字段可以将 Host 的连接端口映射到容器的连接端口。撰写方式如下:

services:
  app:
    build:
      context: .
    ports:
      - "host_port1:container_port1"
      - "host_port2:container_port2"
      - "host_port_start-host_port_end:container_port_start-container_port_end"

同一个服务产生多个容器

有些服务器程序只支持单线程,好比 Node.js 的服务器程序。为了增加吞吐量,我们需要同时开好几个同样的这类服务器程序来运行才行。

以 Node.js 的服务器程序来说,虽然可以使用其内置的 Cluster 功能,利用 pm2 这个 Node.js 程序的进程管理器就可以很容易做成 Cluster 架构,让多个进程跑同一支应用程序,共同监听一样的连接端口。但是在 Docker 环境下,还是会建议一个容器只运行一个进程,如此便不能使用 Node.js 的 Cluster 架构。

Docker Compose 可以水平扩充(scale)某个服务,用法很简单,只要在使用 docker-compose up 指令加上 --scale 参数,后面再接上 服务名称=实体数量 就可以了。例如以下指令,可以让 app 服务建出数量等同于电脑逻辑内核数量的容器。

docker-compose up --scale app=$(nproc)

不过如果这个服务有暴露连接端口的话,也要让 Host 端的连接端口数量成倍成长才行,不然会产生连接端口重复使用的错误。例如原本将连接端口 3000 暴露出来的服务,docker-compose.yml 文件可以做如下的修改:

services:
  app:
    build:
      context: .
    ports:
      - "3000-3063:3000"

如此一来,若在运行 docker-compose up 指令时加上 --scale app=8 参数,就会创建出 8 个容器,并用 Host 的连接端口 3000~3007 分别映射到这 8 个容器的连接端口 3000。此处由于 docker-compose.yml 文件的 Host 连接端口范围是设置为 3000-3063,因此这个 app 服务最多只能用 --scale 参数设置产生 64 个容器。

有了多个容器以及多个连接端口,我们就可以利用 Nginx 等负载平衡服务器来部署我们的服务器程序了!有关 Nginx 的用法可以参考这篇文章:

变量

在服务加上 environment 字段可以设置环境变量。撰写方式如下:

services:
  app:
    build:
      context: .
    environment:
      VARIABLE1: value1
      VARIABLE2: value2

docker-compose.yml 文件本身也可以使用变量。可以在 Docker 项目根目录下添加 .env 文件,然后将 docker-compose.yml 文件本身会用到的变量写进这个文件里。格式如下:

VARIABLE1=value1
VARIABLE2=value2

若要在 docker-compose.yml 文件中套用 .env 文件所设置的变量,可以在那个要使用变量值的地方置入 $变量名称 或是 ${变量名称}。例如:

services:
  app:
    build:
      context: .
    image: hello-world:${TAG}

如果 Docker Compose 的设置档不命名为 docker-compose.yml,或是 .env 不命名为 .env 也是可以的。docker-compose 指令可以用 -f 参数来设置 Docker Compose 的设置档的路径;用 --env-file 参数来设置 .env 文件的路径。

不过笔者习惯不在 Docker Compose 的设置档中使用 .env 文件的变量,因为这样 Docker Compose 要读取两个文件,用起来显得很混乱。笔者比较习惯在不同的阶段使用不同的 docker-compose.yml 文件,把用于 Production 环境的 Docker Compose 设置档命名为 docker-compose.prod.yml;用于 Development 环境的 Docker Compose 设置档命名为 docker-compose.yml。

单一的 YAML 文件其实有类似变量的写法,可以多加利用,语法如下:

foo: &myanchor
  key1: val1
  key2: val2

bar: *myanchor

& 用来对某个字段设置锚点(anchor),* 用来引用某个锚点指定的字段内容。

再看看以下写法:

foo: &myanchor
  key1: val1
  key2: val2

bar:
  <<: *myanchor
  key2: val2-new
  key3: val3

<< 搭配 * 可以用来合并字段。例如以上的 bar 字段底下会有 key1、key2、key3 字段,且因为 bar 自己有写 key2,所以从 foo 合并进来的 key2 会被覆写掉。

在 Docker Compose 的设置档要使用这样的语法,要注意锚点所在的字段名称必须要对于 Docker Compose 来说是有效的。若想要使用我们自订的字段名称,要以 x- 开头才可以。这种写法笔者经常会用在服务的 environment 字段上,用来定义多个服务共有的环境变量,例如:

x-env-suite-1: &vars
  VAR: Hello!

services:
  app1:
    image: alpine
    environment: *vars
    command: sh -c "echo $$VAR"
  app2:
    image: alpine
    environment:
      <<: *vars
    command: sh -c "echo $$VAR"

docker-compose up 的运行结果如下图:

两个容器输出环境变量的结果

透过网络界面让不同容器进行沟通

这个小节会以 TypeScript 编程语言制作的一个简单的需要连接数据库的 HTTP 服务器程序来当作例子。如果您不太熟悉 TypeScript 编程语言,有兴趣了解更多的话,可以参考《TypeScript 学习之路》系列文章。

首先添加一个目录,并将终端机工作目录移动到这个新目录下,接着在这个目录下添加一个 app.ts 文件,文件内容如下:

import { createServer } from "http";

import { MongoClient } from "mongodb";

const PORT = process.env.PORT ?? 3000;
const MONGODB_URI = process.env.MONGODB_URI ?? "mongodb://localhost:27017/db_counter";

async function main() {
    const client = new MongoClient(MONGODB_URI);

    await client.connect();

    const db = client.db();
    const counter = db.collection<{
        _id: string,
        sequenceNumber: number
    }>("counter");

    // eslint-disable-next-line @typescript-eslint/no-misused-promises
    const server = createServer(async (_req, res) => {
        const result = await counter.findOneAndUpdate({ _id: "counter" }, { $inc: { sequenceNumber: 1 } }, { upsert: true, returnDocument: "after" });

        if (result) {
            res.writeHead(200, { "Content-Type": "text/plain" });
            res.write(`Counter: ${result.sequenceNumber}`);
        } else {
            res.writeHead(500);
        }

        res.end();
    });

    server.listen(PORT, () => {
        console.log(`HTTP server started at http://localhost:${PORT}`);
    });
}

main().catch((err) => {
    console.error(err);
});

也可以写个 README.md。

DB Counter Server
=================

## How to Build & Run?

```bash
docker-compose up -d
```

Then visit `http://localhost:3000`.

一般来说 Node.js 程序项目都要有 package.json 文件,但在这篇文章中的重点不是 Node.js 或是 TypeScript,所以把 package.json 放在 Docker 环境中创建。

再来要添加 .dockerignore 文件,如下:

*

!/app.ts
# !/src
# !/tests
# !/*.json

然后撰写 Dockerfile 文件,内容如下:

FROM node:slim AS builder

WORKDIR /build

RUN chown node:node /build

COPY --chown=node:node . .

USER node

RUN npm init -y && npm i mongodb && npm i -D typescript @types/node && npx tsc --init # Create a typescript project

RUN npm i && npx tsc && npm ci # Build project and create node_modules in the release mode 


FROM node:alpine

EXPOSE 3000

WORKDIR /app

RUN chown node:node /app

COPY --chown=node:node --from=builder /build/app.js /app/
COPY --chown=node:node --from=builder /build/node_modules /app/node_modules/

USER node

CMD ["node", "app.js"]

然后撰写 docker-compose.yml 文件,内容如下:

services:
  mongo:
    image: mongo
    volumes:
      - ~/docker/hello-db/mongo/db:/data/db
      - ~/docker/hello-db/mongo/configdb:/data/configdb
    networks:
      - db-counter-net

  app:
    build:
      context: .
    image: db-counter
    environment:
      MONGODB_URI: mongodb://mongo.db-counter-net:27017/db_counter
    ports:
      - "3000:3000"
    networks:
      - db-counter-net
    command: sh -c "sleep 3; node app.js"

networks:
  db-counter-net:
    name: db-counter-net

上面的 docker-compose.yml 文件,先看到 mongo 服务,这个服务会启动 MongoDB,MongoDB 是一种 NoSQL 数据库。之所以将外部文件系统目录分别挂载到 /data/db 和 /data/configdb 路径的目的是要让 MongoDB 的数据能够保存在外部的文件系统中,这样在容器删除后依然可以保留 MongoDB 的数据。

再来看第 22 行的 networks 字段,这个字段可以用来定义上面的服务启动前要创建或是要链接的 Docker 网络界面。name 字段可以设置 Docker 网络界面的名称。如果不要创建 Docker 网络界面,而是沿用已经创建好的 Docker 网络界面的话,可以在网络界面的字段下(与 name 同层)添加 external 字段,并设置字段值为 true。第 7 行和第 18 行是服务下的 networks 字段,可以设置该服务的容器创建后要使用的网络界面。

在 Docker 环境中,可以利用 <容器ID或名称>.<网络界面名称> 作为主机名称来对应容器。使用 Docker Compose 时,则可以用服务名称来替代其中的容器名称。所以设置 MONGODB_URI 环境变量为 mongodb://mongo.db-counter-net:27017/db_counter,可以让 app 服务的 HTTP 服务器程序连接到 mongo 服务的 MongoDB。

第 20 行覆写了映像预设要运行的指令,在运行 HTTP 服务器之前先运行 sleep 指令是为了要等待一段时间,让 MongoDB 能够在 HTTP 服务器启动之前被启动,这样 HTTP 服务器才能够顺利连接上数据库。

服务/容器的相依关系(先后运行顺序)

承上面的需要连接数据库的 HTTP 服务器程序,我们其实还可以在服务加上 depends_on 字段来设置服务的相依性。如下:

services:
  mongo:
    image: mongo
    volumes:
      - ~/docker/hello-db/mongo/db:/data/db
      - ~/docker/hello-db/mongo/configdb:/data/configdb
    networks:
      - db-counter-net

  app:
    build:
      context: .
    image: db-counter
    environment:
      MONGODB_URI: mongodb://mongo.db-counter-net:27017/db_counter
    ports:
      - "3000:3000"
    networks:
      - db-counter-net
    depends_on:
      - mongo

networks:
  db-counter-net:
    name: db-counter-net

这样虽然可以确保 app 服务的容器在 mongo 服务的容器启动后才会启动,但无法保证 app 服务的容器会在 mongo 服务的容器中的 MongoDB 数据库启动之后才启动。

为了确保容器中的服务的运行顺序,可以加入 Wait Service 工具。

将 Dockerfile 文件修改如下:

FROM rust:slim AS wait-service-builder

WORKDIR /build

RUN apt update && apt install -y make musl-tools musl-dev \
    && rustup target add x86_64-unknown-linux-musl \
    && cargo search --limit 0

RUN cargo install --target x86_64-unknown-linux-musl wait-service --features json \
    && cp ${CARGO_HOME}/bin/wait-service /build


FROM node:slim AS builder

WORKDIR /build

RUN chown node:node /build

COPY --chown=node:node . .

USER node

RUN npm init -y && npm i mongodb && npm i -D typescript @types/node && npx tsc --init -t ES6 # Create a typescript project

RUN npm i && npx tsc && npm ci # Build project and create node_modules in the release mode 


FROM node:alpine

EXPOSE 3000

WORKDIR /app

RUN chown node:node /app

COPY --chown=node:node --from=wait-service-builder /build/wait-service /app/
COPY --chown=node:node --from=builder /build/app.js /app/
COPY --chown=node:node --from=builder /build/node_modules /app/node_modules/

USER node

CMD ["node", "app.js"]

以上的 Dockerfile 文件,第 1 行到第 11 行用来编译可在 Alpine Linux 环境运行的 wait-service 指令工具,为一个独立的阶段。第 36 行将 wait-service 可执行文件拷贝进运行阶段的映像中。

wait-service 的编译方式会与它之后会在哪个运行环境运行有关,需自行调整。

再来要修改 docker-compose.yml 设置档中 app 服务的 command 字段,要透过 wait-service 指令工具来运行我们的这个基于 Node.js 的 HTTP 服务器。

services:
  mongo:
    image: mongo
    volumes:
      - ~/docker/hello-db/mongo/db:/data/db
      - ~/docker/hello-db/mongo/configdb:/data/configdb
    networks:
      - db-counter-net

  app:
    build:
      context: .
    image: db-counter
    environment:
      MONGODB_URI: mongodb://mongo.db-counter-net:27017/db_counter
    ports:
      - "3000:3000"
    networks:
      - db-counter-net
    depends_on:
      - mongo
    command: ["./wait-service", "--tcp", "mongo.db-counter-net:27017", "--", "node", "app.js"]

networks:
  db-counter-net:
    name: db-counter-net

以上的 docker-compose.yml 文件,第 22 行让容器在启动后去运行 wait-service,在确认 mongo.db-counter-net:27017 能够连得上之后才会去运行 node app.js 指令。

有关于 Wait Service 的用法可以参考这篇文章:

将容器的日志输出到 syslog

为了方便管理运行在 Docker 环境的服务所产生出来的日志,笔者习惯将这些日志丢给 Linux 发行版内置的 syslog(准确来说是 rsyslog)处理。

在改变 Docker 容器的日志输出方式之前,有一些前置工作要做。

首先创建 /etc/rsyslog.d/10-docker.conf 文件,文件内容如下:

$FileCreateMode 0644

template(name="DockerLogFileName" type="list") {
    constant(value="/var/log/docker/")
    property(name="syslogtag" securepath="replace" regex.expression="docker/\\([^/:]*\\)[^/]*/.*" regex.submatch="1")
    constant(value="/containers.log")
}

if ($syslogtag startswith "docker/") then {
    $EscapeControlCharactersOnReceive off
    /var/log/docker/combined.log

    if (re_match($syslogtag, "docker/[^/:]*[^/]*/.*")) then {
        ?DockerLogFileName
    }

    stop
}

$FileCreateMode 0600

以上设置档可以让进入 syslog 且标签是以 docker/ 为开头的日志,被保存到 /var/log/docker 目录下。这个目录下的 combined.log 文件会存放所有的日志,也会有子目录分别存放日志,稍后再提。

运行以下指令检查 rsyslog 的设置档是否正确:

sudo rsyslogd -N1

运行以下指令重启 rsyslog 以套用设置:

sudo systemctl restart rsyslog

接着创建 /etc/logrotate.d/docker 文件,文件内容如下:

/var/log/docker/*.log {
  daily
  dateext
  missingok
  rotate 180
  compress
  delaycompress
  notifempty
  copytruncate
} 
  
/var/log/docker/*/*.log {
  daily
  dateext
  missingok
  rotate 180
  compress
  delaycompress
  notifempty
  copytruncate
}

以上设置档的创建是为了避免时间久了 syslog 的日志会太大而占用过多的硬盘空间,所以透过 Linux 发行版内置的 logrotate 来做日志轮替和压缩。以上设置档将备份频率设为每天(daily),会保存最多 180 天(rotate 180)的日志。

最后修改 Docker Compose 设置文件中的服务,用如下的方式加入 logging 字段就可以把其所创建出来的容器所产生的日志交给 syslog 处理了!

services:
  mongo:
    image: mongo
    volumes:
      - ~/docker/hello-db/mongo/db:/data/db
      - ~/docker/hello-db/mongo/configdb:/data/configdb
    networks:
      - db-counter-net

  app:
    build:
      context: .
    image: db-counter
    environment:
      MONGODB_URI: mongodb://mongo.db-counter-net:27017/db_counter
    ports:
      - "3000:3000"
    networks:
      - db-counter-net
    depends_on:
      - mongo
    command: ["./wait-service", "--tcp", "mongo.db-counter-net:27017", "--", "node", "app.js"]
    logging:
      driver: "syslog"
      options:
        tag: "docker/{{.ImageName}}/{{.Name}}/{{.ID}}"

networks:
  db-counter-net:
    name: db-counter-net

/var/log/docker 目录下的子目录是依照日志标签的第一个斜线 / 和第二个斜线中间的字符串来命名,也就是会让相同映像名称的日志放在同一个文件。

透过 journalctl 指令可以查看存进 syslog 的日志。用法如下:

journalctl -t <日志标签> --output cat

在终端机输入指令的时候,<日志标签> 的部份不需要自行记忆,先输入 docker/,然后按两次 TAB,终端机就会出现之后的提示。

如果要持续监看日志,可以替 journalctl 指令加上 -f 参数。

以 journalctl 查看容器的日志

开机后自动启动 Docker Compose 服务

在服务加上 restart 字段可以设置容器的重启策略。可用的字段值和 docker run 指令的 --restart 参数一样,例如:

services:
  app:
    restart: always
    build:
      context: .

指定不同的 Docker Compose 项目名称

Docker Compose 预设会使用 Docker 项目的目录名称作为项目名称,如果不小心让不同的 Docker 项目的映像名称重复或是容器名称有冲突的话,可以在使用 docker-compose 指令时加上 -p 参数来指定项目名称。