在 Deis 上使用 Dockerfile 部署应用:从准备、推送构建到水平扩展的完整指南
在 Deis 上使用 Dockerfile 部署应用:从准备、推送构建到水平扩展的完整指南
Dockerfile 是 Deis 三种应用构建方式(Heroku Buildpacks、Dockerfile、Docker Image)中最灵活的一种,它允许你基于任意基础镜像精确定义应用的运行环境。本文将围绕 Deis 官方文档中「Using Dockerfiles」一节展开,完整讲解 Dockerfile 应用的准入要求、通过 git push 触发构建部署的完整流程,并结合仓库中 builder 构建脚本 与 controller 构建模型 的源码实现,揭示构建、发布与容器调度的底层原理。读完本文,你将掌握如何在 Deis 上用 Dockerfile 应用完成「创建应用 → 推送代码 → 自动构建 → 访问服务 → 扩容」的完整闭环。
Dockerfile 在 Deis 三种构建方式中的定位
在 deploy-application.rst 中,Deis 明确支持三种应用构建方式:
- Heroku Buildpacks:适合遵循 Heroku 最佳实践或从 Heroku 迁移的应用;
- Dockerfile:在自选基础 OS 上定义可移植执行环境,是本文的主角;
- Docker Image:从公共或私有镜像仓库按位(bit-for-bit)复制镜像部署,保证开发、CI 与生产环境运行完全相同的镜像。
Dockerfile 的价值在于:一条 Dockerfile 通过一系列指令(FROM、RUN、ENV、ADD、CMD、EXPOSE 等)自动化地编排「构建 Docker 镜像」的每一步,让你对应用运行时环境拥有完全的控制权。Deis 会检测仓库根目录是否存在 Dockerfile 文件来决定走哪条构建路径。
准备工作:克隆示例应用
如果你还没有现成的 Dockerfile 应用,可以克隆 Deis 官方示例应用 helloworld 来体验完整的 Dockerfile 工作流:
$ git clone https://github.com/deis/helloworld.git
$ cd helloworld
该示例应用在 Dockerfile 中演示了安装 Go 工具链、编译应用、设置环境变量并暴露 HTTP 端口的典型写法,非常适合作为首次体验 Deis Dockerfile 部署的起点。
Dockerfile 的准入要求
要在 Deis 上成功部署 Dockerfile 应用,应用必须满足以下四条要求:
| 要求 | 说明 |
|---|---|
| Dockerfile 必须只 EXPOSE 一个端口 | 暴露多个端口会触发 issue 1156 所记录的问题,导致部署失败 |
| 该端口必须监听 HTTP 连接 | 暴露的端口用于对外提供 HTTP 服务,Deis 路由器会依据此端口转发请求 |
| 必须指定默认 CMD 来运行容器 | 没有 CMD 指令,容器启动后没有可执行入口,无法对外提供服务 |
| 镜像内应包含 bash | Deis 在启动容器时依赖 bash 执行启动命令,缺失会导致容器无法正常拉起 |
原文档特别以 note 形式提醒:暴露多个端口的 Dockerfile 将命中 issue 1156,因此编写 Dockerfile 时务必只保留一个 HTTP 监听端口。
从源码看,这条「单端口」约束背后是 Deis 路由模型的直接结果:Deis 控制器为每个应用生成 http://<app-name>.<domain> 的访问地址(见 views.py 中 BuildHookViewSet 的响应构造),路由层只面向单一 HTTP 端口做七层转发。应用若要横向扩展,还必须遵循十二要素方法论(deploy-application.rst),将状态存储到外部服务中,而不是本地文件系统。
创建应用:deis create
登录 Deis 控制器后(deis login http://deis.example.com),在应用目录下使用 deis create 创建应用:
$ deis create
Creating application... done, created folksy-offshoot
Git remote deis added
deis create 会做两件事:
- 在控制器上创建一个应用记录(包含初始 Config 和版本为 1 的初始 Release,见 models.py 中 App.create);
- 在本地 Git 仓库中自动添加名为
deis的远程仓库,指向ssh://git@<cluster-domain>:2222/<app-name>.git。
创建完成后,应用即获得形如 folksy-offshoot.local3.deisapp.com 的默认域名。
推送部署:git push deis master
在应用目录执行:
$ git push deis master
这是 Dockerfile 工作流的核心环节。完整输出如下(节选自原文档示例):
Counting objects: 13, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (13/13), done.
Writing objects: 100% (13/13), 1.99 KiB | 0 bytes/s, done.
Total 13 (delta 2), reused 0 (delta 0)
-----> Building Docker image
Uploading context 4.096 kB
Uploading context
Step 0 : FROM deis/base:latest
---> 60024338bc63
Step 1 : RUN wget -O /tmp/go1.2.1.linux-amd64.tar.gz -q https://go.googlecode.com/files/go1.2.1.linux-amd64.tar.gz
---> Using cache
---> cf9ef8c5caa7
Step 2 : RUN tar -C /usr/local -xzf /tmp/go1.2.1.linux-amd64.tar.gz
---> Using cache
---> 515b1faf3bd8
Step 3 : RUN mkdir -p /go
---> Using cache
---> ebf4927a00e9
Step 4 : ENV GOPATH /go
---> Using cache
---> c6a276eded37
Step 5 : ENV PATH /usr/local/go/bin:/go/bin:$PATH
---> Using cache
---> 2ba6f6c9f108
Step 6 : ADD . /go/src/github.com/deis/helloworld
---> 94ab7f4b977b
Removing intermediate container 171b7d9fdb34
Step 7 : RUN cd /go/src/github.com/deis/helloworld && go install -v .
---> Running in 0c8fbb2d2812
github.com/deis/helloworld
---> 13b5af931393
Removing intermediate container 0c8fbb2d2812
Step 8 : ENV PORT 80
---> Running in 9b07da36a272
---> 2dce83167874
Removing intermediate container 9b07da36a272
Step 9 : CMD ["/go/bin/helloworld"]
---> Running in f7b215199940
---> b1e55ce5195a
Removing intermediate container f7b215199940
Step 10 : EXPOSE 80
---> Running in 7eb8ec45dcb0
---> ea1a8cc93ca3
Removing intermediate container 7eb8ec45dcb0
Successfully built ea1a8cc93ca3
-----> Pushing image to private registry
Launching... done, v2
-----> folksy-offshoot deployed to Deis
http://folksy-offshoot.local3.deisapp.com
To learn more, use `deis help` or visit http://deis.io
To ssh://git@local3.deisapp.com:2222/folksy-offshoot.git
* [new branch] master -> master
构建成功后,用 curl 验证服务:
$ curl -s http://folksy-offshoot.local3.deisapp.com
Welcome to Deis!
See the documentation at http://docs.deis.io/ for more information.
推送背后的构建链路:从 SSH 接收到镜像发布
git push deis master 并非简单的 Git 推送,它背后是一条完整的「Git → 构建 → 发布」链路。结合仓库源码可以还原整个过程:
-
SSH 接收与鉴权:Builder 服务通过 SSH 对外监听(默认地址
0.0.0.0:2223,见 builder.go),先走pubkeyAuth路由校验开发者 SSH 公钥,再经 sshGitReceive 路由 将会话交给git.Receive,最终以git-shell -c 'git-receive-pack ...'方式接收代码(见 git/git.go 的 Receive 实现)。 -
pre-receive 钩子触发构建:每次推送都会触发仓库的 pre-receive 钩子(模板见 git.go 中的 PrereceiveHookTpl),钩子调用
/home/git/builder脚本(由 confd 渲染,配置见 conf.d/builder.toml)。该脚本由builder/rootfs/etc/confd/templates/builder定义,是 Dockerfile 构建流程的核心。 -
检出代码并检测 Dockerfile:脚本通过
git archive $GIT_SHA | tar -xmC $TMP_DIR将提交快照检出到临时目录,随后if <a href="https://link.gitcode.com/i/17c1073c45cda538e614d18841a83ccb" target="_blank"> -f Dockerfile ]检测仓库根目录是否存在 Dockerfile,以此设置USING_DOCKERFILE=true(见 [builder 模板脚本)。若没有 Dockerfile,则走 slugbuilder/slugrunner 的 Heroku 构建路径。 -
注入环境变量并构建镜像:脚本向 Dockerfile 追加
ENV GIT_SHA $GIT_SHA注入构建标识,然后执行docker build -t $TMP_IMAGE .构建镜像,镜像名形如<registry-host>:<port>/<app-name>:git-<short-sha>,构建完成后docker push到私有镜像仓库(builder 脚本)。 -
回传构建钩子:脚本调用 generate-buildhook.go 生成
BuildHookJSON(包含sha、receive_user、receive_repo、image、procfile、dockerfile六个字段,结构定义见 builder/types.go),再通过 publish-release-controller.go 回调控制器/v1/hooks/build接口。 -
控制器创建 Build 与 Release:控制器 BuildHookViewSet 校验
receive_user对该应用的权限后创建 Build 记录,Build.create基于最新 Release 生成新 Release 并触发app.deploy部署(models.py 中 Build.create)。返回的响应包含新版本号和访问域名。 -
确定默认进程类型:控制器在部署时依据 models.py 的判断逻辑 决定容器结构——若 Dockerfile 存在但没有 Procfile,则自动假定 Dockerfile 工作流,将
cmd进程类型默认扩容到 1(源码注释明确写出 "if a dockerfile exists without a procfile, assume docker workflow")。这正是原文档所述「由于检测到 Dockerfile 应用,cmd进程类型在首次部署时自动扩展为 1」的底层实现。
关于 procfile 与 dockerfile 的协同
Deis 的 Build 模型(models.py Build 类)同时保存 procfile 和 dockerfile 两个字段。若应用同时提供 Procfile(如 worker: node worker.js),Deis 也会按其中的进程类型创建对应容器(见 test_build.py 中的测试用例)。Procfile 在 Dockerfile 工作流中是可选增强项:没有它时 Deis 会按 cmd 类型处理,有它时则能显式定义多种进程类型。
扩容:deis scale cmd=3
Dockerfile 应用没有 Procfile 时统一使用 cmd 进程类型。执行以下命令将 cmd 进程扩展到 3 个:
$ deis scale cmd=3
deis scale 客户端将参数按 type=num 格式解析(不匹配会提示 '%s' does not match the pattern 'type=num', ex: web=2,见 client/cmd/ps.go 的 PsScale 实现),随后调用控制器 ps API。扩展某个进程类型会直接改变运行该进程的容器数量(Deis 术语中称为 Container,见 docs/understanding_deis/concepts.rst)。
需要特别说明两点:
- 横向扩展的前提是无状态:与十二要素要求一致,若应用把状态写入本地文件系统(例如 WordPress、Drupal 这类 CMS),则无法通过
deis scale安全地水平扩展(deploy-application.rst); - 容器启动方式差异:控制器调度容器时,对 Dockerfile 应用(无 procfile 或基于镜像发布)使用
bash -c '<command>'方式启动,而对 Heroku slug 应用使用 slugrunner 的/runner/init start <type>入口(models.py 的 _get_command 实现),因此镜像内必须包含 bash——这正是准入要求第 4 条的根本原因。
排查与注意事项
- 多端口问题:Dockerfile 若
EXPOSE多个端口,将命中 issue 1156,务必只暴露一个 HTTP 端口; - 默认 CMD 缺失:没有
CMD指令的镜像无法被 Deis 正常启动,请在 Dockerfile 末尾明确指定; - bash 依赖:Deis 以
bash -c方式执行启动命令,基础镜像应尽量基于包含 bash 的发行版(如 Deis 官方示例使用的deis/base); - 首次部署默认 cmd=1:这是 Deis 对 Dockerfile 工作流的自动假定,可通过
deis scale cmd=N随时调整副本数。
总结
在 Deis 上使用 Dockerfile 部署应用的完整路径为:准备满足四项要求的 Dockerfile 应用 → deis create 创建应用 → git push deis master 推送构建 → 访问 http://<app>.deisapp.com 验证 → deis scale cmd=N 横向扩展。与 Buildpacks 和 Docker Image 两种方式相比,Dockerfile 让你完全掌控运行环境,代价是需要自己保证单 HTTP 端口、默认 CMD 和 bash 依赖这三项约束。掌握推送背后的「SSH 接收 → pre-receive 钩子 → docker build/push → 控制器 Build/Release → 调度部署」链路,将帮助你在遇到构建或启动问题时快速定位故障环节。