跳到主要内容
版本：4.x

发布配置

介绍​

配置指定应用在某环境下如何执行发布，发布支持两种方式 常规发布 和 自定义发布。

选择发布方式

常规发布​

由 Spug 负责应用代码的拉取、构建、打包、传输和版本切换，同时提供了各个阶段可自定义的钩子脚本。适合大部分基于 Git 仓库的应用发布场景。

说明

常规发布参考了开源项目 瓦力 的一些设计思路，在此感谢。 如果你使用过 瓦力 的发布，可以直接迁移至常规发布。

基本配置​

基本配置

  • 发布环境：为哪个环境创建的发布配置，例如：测试环境 / 生产环境等，可以建立多个环境实现同一应用在不同环境里配置不同的发布流程。
  • 目标主机：该发布配置作用于哪些主机，可以选择一个或多个，新建发布申请时可以从中再挑选本次发布的主机。
  • Git仓库地址：该应用的 Git 仓库地址。私有仓库请点击旁边的 私有仓库？，可以选择 密钥 认证（把 Spug 的公钥添加到代码平台的部署公钥中，使用 ssh 协议地址）或 账户密码 认证（使用 http/https 协议地址）。
  • 发布模式：并行 表示每台主机相互独立同时发布；串行 表示一台完成后再发布下一台，期间出现异常则终止后续发布。
  • 发布审核：开启后发布申请需要具有审核权限的用户审核通过后才能发布。
  • 消息通知：发布结果通知，支持 钉钉、飞书、企业微信 群机器人以及自定义 Webhook，填写对应的机器人地址即可。

构建配置​

构建配置

  • 文件过滤：可选 包含 或 排除，填写相对于项目根目录的文件路径（每行一条），打包时仅包含 / 排除匹配到的文件或目录，例如排除 .git、node_modules。
  • 代码检出前执行：在运行 Spug 的服务器（或容器）上执行，当前目录为仓库源代码目录，请避免在此修改已跟踪的文件，防止在检出代码时失败。
  • 代码检出后执行：在运行 Spug 的服务器（或容器）上执行，当前目录为检出后待发布的源代码目录，大多数情况下在此进行编译构建操作，例如 npm run build、mvn package。

发布配置​

发布配置

  • 部署路径：应用最终在目标主机上的路径，为了数据安全请确保该目录不存在，Spug 会自动创建并接管该目录（以软链接的形式指向当前版本），可以使用全局变量，例如 /www/$SPUG_APP_KEY。
  • 存储路径：目标主机上用于存储应用历史版本的目录，例如 /data/repos/$SPUG_APP_KEY。
  • 版本数量：保留的历史版本数量，早于指定数量的构建记录及历史版本会被自动删除以释放磁盘空间，同时也决定了可回滚的版本范围。
  • 应用发布前执行：在发布的目标主机上运行，当前目录为目标主机上待发布的源代码目录，此时还未进行文件变更，可进行一些发布前置操作。
  • 应用发布后执行：在发布的目标主机上运行，当前目录为已发布的应用目录，可以在发布后进行重启服务等操作。
提示

发布流程​

  1. 构建阶段（服务端）：拉取 Git 仓库 → 执行 代码检出前执行 → 检出指定分支 / Tag / 提交 → 执行 代码检出后执行 → 按文件过滤规则打包，产物记录到 构建仓库；
  2. 发布阶段（目标主机）：清理超出版本数量的历史版本 → 把构建产物传输到存储路径 → 执行 应用发布前执行 → 切换部署路径的软链接到新版本 → 执行 应用发布后执行。

同一个构建产物可以用于多次发布（例如先发测试主机再发生产主机），发布申请中选择 构建仓库 中的版本即可跳过构建阶段。

自定义发布​

该发布模式下 Spug 仅负责按顺序依次执行记录的动作，不关心代码来自哪里，适合发布流程特殊、或者产物来自外部 CI 系统的场景。

自定义发布

配置项​

  • 发布环境 / 目标主机 / 发布模式 / 发布审核 / 消息通知：含义与常规发布相同。
  • 本地执行动作：可以添加多个执行动作，执行对象为部署运维平台的服务器，会优先按顺序执行本地动作。
  • 目标主机执行动作：可以添加多个执行动作，执行对象为发布的目标主机，按顺序依次执行。目标主机动作有两种类型：执行命令 与 数据传输。

数据传输​

数据传输动作用于把文件从部署 Spug 的容器或主机传输至目标主机：

  • 数据来源 数据来源可以选择以下两种
    • 本地路径：位于部署 spug 的容器或主机上，路径可以是文件或目录，请输入绝对路径。
    • 发布时上传：在创建发布申请时上传数据。
  • 过滤规则 仅在数据来源选择本地路径时有效，可以设置 包含 和 排除 两种规则，内容为基于本地路径的相对路径，多个路径使用英文逗号分割，当传输对象为文件时过滤规则将会被忽略。
  • 目标路径 如果数据来源为发布时上传，则目标路径必须为一个文件路径（例如：/tmp/upload.tar.gz），如果数据来源为本地路径则请保持目标路径与本地路径的类型一致，如本地路径为文件则目标路径也必须为文件，可参考以下例子

当数据来源为发布时上传，需要注意以下事项：

注意
  1. 目标路径既可以是文件路径（例如 /data/upload.jar），也可以是目标主机上已存在的目录，后者会按上传文件的原始文件名写入该目录；大部分情况下还需要其他后续动作去处理上传的文件。
  2. 目标为文件路径且不存在时，Spug 会自动创建其上级目录（如上例中的 /data）。
  3. 每次执行该数据传输动作时将会覆盖已存在的文件。

下面以 Spug 开源项目的源代码作为例子来说明当数据来源为本地路径时几种典型情况，假设源代码位于 /data/spug 目录下。

  • 本地路径：/data/spug，目标路径：/www/spug，文件过滤：关闭

    说明

    将会把部署 Spug 的容器或主机上的 /data/spug 目录完整传输至目标主机的 /www/spug 目录，特别注意，如果目标主机的 /www/spug 已存在，将会先执行删除操作。

  • 本地路径：/data/spug，目标路径：/www/spug，文件过滤：包含 spug_api,spug_web/dist

    说明

    仅把 /data/spug 目录下的 spug_api 和 spug_web/dist 传输至目标主机，传输完成后目录主机的 /www/spug 中仅包含上述两个目录，文件 过滤中的 排除 用法与 包含 类似，但只传输除了指定路径以外的其他文件。

  • 本地路径：/data/spug/README.md，目标路径：/www/spug/README.md, 文件过滤：包含 spug_api

    说明

    仅把 README.md 传输至目标主机，因为传输对象为文件，所以文件过滤规则将会被忽略。

  • 本地路径：/data/spug/README.md, 目标路径：/www/spug，文件过滤：关闭

    说明

    传输 README.md 至目标主机，删除并替换 /www/spug，特别注意，传输完成后目标主机的 /www/spug 将变更为一个文件，内容为 README.md 文件的内容。这个是一个反例，如果你要传输的是文件，请保持目标路径也是一个完整的文件路径。

  • 本地路径：/data/spug, 目标路径：/www/spug/README.md，文件过滤：关闭

    说明

    将传输整个 /data/spug 目录至目标主机并将其命名为 README.md，特别注意，传输完成后目标主机的 /www/spug/README.md 将变更为一个目录。 这个是一个反面例子，如果你要传输的是目录，请保持目标路径也是一个完整的目录路径。

全局变量​

  • SPUG_APP_NAME 发布应用的名称
  • SPUG_APP_KEY 发布应用的标识符
  • SPUG_APP_ID 发布应用的 ID
  • SPUG_REQUEST_ID 发布申请单 ID
  • SPUG_REQUEST_NAME 发布申请单的名称
  • SPUG_VERSION 发布申请版本
  • SPUG_BUILD_VERSION 发布申请内部版本号
  • SPUG_ENV_ID 发布环境 ID
  • SPUG_ENV_KEY 发布环境的标识符
  • SPUG_DEPLOY_ID 发布配置 ID
  • SPUG_DEPLOY_TYPE 发布类型（"1" 为正常发布，"2" 为回滚，"3" 为 Webhook 触发的自动发布）
  • SPUG_API_TOKEN 访问配置中心获取配置的 API_TOKEN
  • SPUG_HOST_ID 当前执行主机的 ID（仅在主机执行阶段有效）
  • SPUG_HOST_NAME 当前执行主机的 IP / 域名（仅在主机执行阶段有效）

常规发布变量

  • SPUG_REPOS_DIR 源码存储目录，常规发布与自定义发布都会注入（$SPUG_REPOS_DIR/$SPUG_DEPLOY_ID 即为本次发布应用的源码目录）
  • SPUG_BUILD_ID 本次发布使用的构建记录 ID
  • SPUG_DST_DIR 常规发布目标主机部署路径
  • SPUG_GIT_BRANCH 本次发布选择的 Git 分支（常规发布基于分支时有效）
  • SPUG_GIT_COMMIT_ID 本次发布选择的 Git Commit ID（常规发布基于分支时有效）
  • SPUG_GIT_TAG 本次发布的 Git Tag（常规发布基于 Tag 时有效）

自定义发布变量

  • SPUG_RELEASE 新建自定义发布申请填写的 SPUG_RELEASE 值（自定义发布有效）

    提示

    SPUG_RELEASE 会自动按空格分隔解析为多个环境变量，例如 abc 123 def，会对应有4个变量：

    SPUG_RELEASE = abc 123 def
    SPUG_RELEASE_1 = abc
    SPUG_RELEASE_2 = 123
    SPUG_RELEASE_3 = def

配置中心变量

该应用在发布环境下的配置（含依赖的应用与服务的配置）会以 _SPUG_ 加大写 Key 的形式注入，例如配置 api_order_db_host 对应环境变量 _SPUG_API_ORDER_DB_HOST，详见 配置中心 API。

跨阶段传递变量与动态更新配置​

在服务端阶段（代码检出前 / 后执行 或自定义发布的本地动作）脚本中导出的两类特殊环境变量会被 Spug 捕获：

  • SPUG_GEV_*：以 SPUG_GEV_ 为前缀的变量会传递到后续的目标主机执行阶段，可用于把构建阶段计算出的值（例如镜像版本号）带到主机脚本中：

    # 代码检出后执行
    export SPUG_GEV_IMAGE_TAG=$(git rev-parse --short HEAD)
    # 应用发布后执行
    echo "部署镜像版本 $SPUG_GEV_IMAGE_TAG"

  • SPUG_SET：按 应用/服务标识符:环境标识符:变量名=变量值 的格式导出，可以在发布过程中动态创建或更新配置中心的配置，变更会记录在配置的历史记录中：

    export SPUG_SET="api_order:prod:release_version=$SPUG_VERSION"