多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

使用 Encore CLI 集成 CI/CD 流水线:Docker 镜像构建与自动化部署实战

使用 Encore CLI 集成 CI/CD 流水线:Docker 镜像构建与自动化部署实战 使用 Encore CLI 集成 CI/CD 流水线Docker 镜像构建与自动化部署实战【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore 提供了与任何主流 CI/CD 流水线无缝集成的 CLI 工具链其中最核心的是encore build docker命令——一条命令即可把 Encore 应用打包为可移植的 Docker 镜像从而接入 GitHub Actions、GitLab CI、Jenkins 等任意构建编排系统。本文基于 Encore 开源仓库中的 docs/go/self-host/ci-cd.md结合 CLI 与镜像构建的源码实现完整讲解 CI 环境中的 CLI 安装认证、镜像构建参数、平台差异处理与端口定制并给出一个可直接照抄的 GitHub Actions DigitalOcean 部署示例。读完本文你将能够把 Encore 应用稳定地接入自己的 CI/CD 流水线实现代码推送即自动构建、推送、部署的完整闭环。一、CI/CD 集成总体思路四个关键步骤虽然每家 CI/CD 流水线的形态各不相同但集成 Encore 遵循一个非常统一的流程安装 Encore CLI在 CI 环境中安装 Encore CLIrunner 或构建容器内构建 Docker 镜像使用encore build docker命令生成应用镜像推送镜像将镜像推送到你的容器镜像仓库Container Registry部署由你的基础设施按既定策略拉取并部署新镜像。所有主流 CI/CD 平台都能按此模式集成差异仅在于各平台调用 CLI 的具体语法如 GitHub Actions 的run步骤、GitLab CI 的script字段等。具体到 CLI 工具的接入方式可以参考你所使用平台的官方文档。二、CI 环境中的 CLI 安装与认证2.1 安装 Encore CLIEncore CLI 本身就是一个静态分发的命令行工具。在你的 CI 流水线中下载官方安装脚本并执行即可完成安装。以 GitHub Actions 为例可以通过curl拉取安装脚本后执行curl --output install.sh -L https://encore.dev/install.sh bash install.sh安装完成后可执行文件位于/home/runner/.encore/bin/encore不同平台的默认安装目录可能不同建议在安装步骤中确认实际路径并在后续步骤中统一使用该绝对路径调用。2.2 使用 Auth Key 进行非交互式认证在本地开发环境中开发者通常通过encore auth login的交互式设备授权Device Auth流程登录。但在 CI 环境中无法进行交互式浏览器授权因此 Encore 提供了Auth Key认证密钥机制用于非交互式认证。在 Encore Cloud若你的应用与其关联中从App Settings Auth Keys页面生成一个 Auth Key将其作为 CI secret 存储到你的 CI 平台中然后在构建之前执行encore auth login --auth-key${{ secrets.ENCORE_AUTH_KEY }}从源码看该机制位于 cli/cmd/encore/auth/auth.goencore auth login支持--auth-key短选项-k参数定义见 auth.go 第 76 行当--auth-key非空时CLI 调用DoLoginWithAuthKey()内部走login.WithAuthKey()流程将凭证写入本地配置文件auth.go 第 123-133 行未指定时则回退到设备授权流程。这也意味着如果你的自托管/自有基础设施部署不依赖 Encore Cloud而是完全通过本地 daemon 与 Docker 交互构建那么这一步认证可以按需省略详见下文对--push与镜像推送的说明。三、GitHub Actions 完整示例构建、推送并部署到 DigitalOcean下面这段工作流来自 ci-cd.md展示了完整的提交到main分支 → 构建镜像 → 推送镜像 → 触发部署闭环。示例中 DigitalOcean 应用被配置为每当仓库中出现latest标签的镜像被上传时自动重新部署。name: Build, Push and Deploy a Encore Docker Image to DigitalOcean on: push: branches: [ main ] permissions: contents: read packages: write jobs: build-push-deploy-image: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv4 - name: Download Encore CLI script uses: sozo-design/curlv1.0.2 with: args: --output install.sh -L https://encore.dev/install.sh - name: Install Encore CLI run: bash install.sh - name: Authenticate with Encore run: /home/runner/.encore/bin/encore auth login --auth-key${{ secrets.ENCORE_AUTH_KEY }} - name: Log in to DigitalOcean container registry run: docker login registry.digitalocean.com -u my-emailgmail.com -p ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }} - name: Build Docker image run: /home/runner/.encore/bin/encore build docker myapp - name: Tag Docker image run: docker tag myapp registry.digitalocean.com/YOUR_CONTAINER_REGISTRY_NAME/YOUR_IMAGE_REPOSITORY_NAME:latest - name: Push Docker image run: docker push registry.digitalocean.com/YOUR_CONTAINER_REGISTRY_NAME/YOUR_IMAGE_REPOSITORY_NAME:latest拆解各步骤的作用步骤说明Checkout repository拉取源码actions/checkoutv4是官方 checkout actionDownload / Install Encore CLI下载并执行官方安装脚本安装 Encore CLIAuthenticate with Encore使用ENCORE_AUTH_KEY这个 CI secret 完成非交互式登录Log in to DigitalOcean container registry使用DIGITALOCEAN_ACCESS_TOKEN登录 DigitalOcean 容器仓库此处账号替换为你自己的注册邮箱Build Docker image调用encore build docker myapp在本地 Docker daemon 中生成名为myapp的镜像IMAGE_TAG即myappTag Docker image将本地镜像打上目标仓库的latest标签Push Docker image推送到容器仓库触发 DigitalOcean 侧配置的自动重部署使用这套工作流时需要把my-emailgmail.com、YOUR_CONTAINER_REGISTRY_NAME、YOUR_IMAGE_REPOSITORY_NAME替换为你自己的实际值并在 GitHub 仓库的 Settings → Secrets 中配置ENCORE_AUTH_KEY与DIGITALOCEAN_ACCESS_TOKEN。3.1 为什么先encore build docker再用docker tag细心的读者会发现示例中先让 Encore 构建出本地镜像再用docker tag打上目标仓库标签。这是因为encore build docker默认把镜像输出到本地 Docker daemon镜像名即你传入的IMAGE_TAG而不是直接推到远端。从 cli/daemon/export/export.go 的源码可以看到未指定--push时LocalDaemonTag被设置镜像导出到本地 daemon指定--push时PushDestinationTag被设置镜像直接推送远端。因此默认模式下构建完成后用docker tagdocker push手动编排标签与推送是灵活且常见的做法。四、深入encore build docker参数与平台定制encore build docker提供了丰富的选项用于定制构建行为。以下是 ci-cd.md 中给出的三种典型用法# 构建指定的服务和网关 encore build docker --servicesservice1,service2 --gatewaysapi-gateway MY-IMAGE:TAG # 自定义基础镜像 encore build docker --basenode:18-alpine MY-IMAGE:TAG # 为特定架构构建当 CI 架构与部署目标不一致时尤其有用 encore build docker --archarm64 MY-IMAGE:TAG结合 cli/cmd/encore/build.go 的源码该命令支持的全部参数如下参数源码定义默认值说明IMAGE_TAG位置参数cobra.ExactArgs(1)必填镜像标签名作为镜像名称使用--servicesStringSlice全部仅包含指定服务多个用逗号分隔--gatewaysStringSlice全部仅包含指定网关多个用逗号分隔--baseStringscratch基础镜像Go 应用默认scratchTS 应用自动回退为node:slim--archOneofamd64目标架构仅允许amd64/arm64--osOneoflinux目标操作系统当前仅允许linux--cgoBool默认取CGO_ENABLED或应用配置是否启用 cgo--push/-pBoolfalse构建后直接推送镜像到远端仓库--configString空指定基础设施配置文件infra config路径--skip-configBoolfalse不读取也不生成基础设施配置文件几点从源码确认的重要细节基础镜像的默认值不是写死的CLI 会读取应用根目录下的应用配置文件appfile.ParseFile当检测到是 TypeScript 应用且用户未显式指定--base时自动使用node:slim作为基础镜像见 build.go 第 51-59 行Go 应用则保持scratch空镜像。架构选择应对CI 与部署目标不一致例如 CI runner 是 amd64而生产环境是 arm64 服务器通过--archarm64即可在 x86 的 CI 上产出 arm64 镜像。build命令带有eject别名encore build整体负责为部署构建你的应用docker是它的子命令从源码结构看未来还可能扩展其他输出格式。4.1 关于--push直推模式如果你的部署流水线希望跳过docker tag的中间步骤可以直接使用--push配合完整的目标仓库地址encore build docker --push registry.example.com/myorg/myapp:latest此时镜像构建完成后会直接推送到远端仓库对应PushDestinationTag逻辑推送认证依赖执行环境中已配置好的 Docker/仓库凭据。五、镜像运行时行为端口与环境变量encore build docker产出的镜像默认在 8080 端口监听你可以通过设置PORT环境变量在启动时自定义端口docker run -e PORT8081 -p 8081:8081 MY-IMAGE:TAG这条规则的实现位于 supervisor镜像内的进程管理组件源码中。镜像入口由 supervisor 进程代理它启动时会读取环境变量来决定监听端口supervisor/src/bin/supervisor-encore.rs从PORT环境变量读取端口未设置时回退到默认值8080supervisor/src/config.rs将PORT写入 supervisor 的运行时配置中供内部各服务端口分配使用。因此在容器编排平台如 Kubernetes、DigitalOcean App Platform中直接通过环境变量注入PORT即可适配平台要求的不同端口无需重新构建镜像。六、源码视角encore build docker背后发生了什么理解镜像构建的内部实现有助于排查 CI 中的构建问题。整个流程分布在两个层面6.1 CLI 层把参数翻译成 daemon 请求encore build docker的 CLI 实现cli/cmd/encore/build.go本身并不直接打镜像而是解析参数组装DockerExportParams基础镜像、本地 daemon 标签或推送目标标签解析--config为绝对路径build.go 第 121-127 行连接本地 daemon通过 gRPC 调用daemon.Export请求中携带Goos/Goarch/CgoEnabled、Services/Gateways列表以及基础设施配置路径实时流式输出构建日志cmdutil.StreamCommandOutput。6.2 daemon 层镜像如何被组装真正执行镜像构建的是 pkg/dockerbuild/dockerbuild.go 中的BuildImage函数。其核心步骤包括解析基础镜像scratch或空字符串解析为空镜像其他基础镜像通过remote.Image从远端拉取dockerbuild.go 第 135-153 行并按目标 OS/架构remote.WithPlatform拉取对应平台变体分层打包文件系统buildImageFilesystem依次组装源码层、依赖层、运行时层supervisor 二进制、配置层supervisor 配置、构建信息以及证书层CA 证书写入/etc/ssl/certs/ca-certificates.crt等多个镜像层固定时间戳保证可复现所有文件使用固定的layerEpochUnix 时间 0作为时间戳使未变化的层在不同构建之间保持相同 digestdockerbuild.go 第 32-35 行——这意味着 CI 中重复构建相同代码可以得到可复现的镜像层利于缓存与增量部署设置镜像配置写入入口点Entrypoint、工作目录、环境变量、架构与系统类型并标注encore.dev作为作者。需要 CA 证书的场景如镜像内需要访问外部 HTTPS 服务由--base基础镜像的内容与证书层共同决定使用scratch作为基础镜像时默认不包含证书这一点在定制基础镜像时需要注意。七、CI/CD 集成最佳实践小结综合文档与源码落地 Encore CI/CD 集成时建议遵循以下几点在 CI 中始终使用非交互式认证通过 Auth Keyencore auth login --auth-keyKEY代替本地设备授权Auth Key 作为 CI secret 管理详见 auth-keys 文档。固定 CLI 安装路径CI 中安装 Encore CLI 后后续步骤统一使用绝对路径如/home/runner/.encore/bin/encore调用避免 PATH 不一致导致的偶发失败。区分构建机架构与目标架构当 CI runner 架构与部署目标不同如 amd64 runner 部署到 arm64 集群时用--arch指定目标架构。按需裁剪镜像内容多服务应用可通过--services/--gateways仅打包需要的部分加快构建与拉取速度。端口交给平台注入镜像默认监听 8080通过PORT环境变量适配各平台尽量不在镜像内硬编码端口。善用推送即部署模式配合 DigitalOcean、Kubernetes 等平台的镜像更新自动重部署能力构建完成后直接推送带latest或版本标签的镜像即可触发部署无需额外部署步骤。至此你已经掌握了 Encore 应用接入 CI/CD 的完整链路安装认证 →encore build docker构建 → 镜像推送 → 平台自动部署。接下来可以进一步阅读配置基础设施与自托管总览了解镜像部署到自有基础设施时的环境变量、基础设施配置与服务发现细节。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表