netresearch/kite

又一款构建和部署工具 - 受TYPO3.Surf启发

维护者

详细信息

github.com/netresearch/kite

主页

源代码

问题

安装: 334

依赖: 0

建议者: 0

安全: 0

星标: 5

关注者: 14

分支: 0

开放问题: 0

1.8.0 2021-06-01 14:08 UTC

Requires

MIT 13118999014278812e0a1f6db0d13e06bba29db5

  • Christian Opitz <christian.opitz.woop@netresearch.de>

This package is auto-updated.

Last update: 2024-08-29 04:14:26 UTC

README

Kite

Kite: 让你的项目翱翔

http://img.shields.io/travis/netresearch/kite.svg?style=flat-square https://img.shields.io/packagist/v/netresearch/kite.svg?style=flat-square https://img.shields.io/scrutinizer/g/netresearch/kite.svg?style=flat-square

Kite 是一个构建和自动化工具，受 TYPO3.Surf 启发，用 PHP 编写并使用 PHP 进行配置。它是...

  • 易于使用
    • Kite 随带多个预配置的任务、工作流程和预设 - 只需使用预设即可完成任务。
    • 任务和工作流程在命令行上可用，每个任务都有 --help 帮助。
  • 灵活
    • 配置可以完全通过数组完成，将任务组合在一起，或者通过具有所有任务作为方法的类工作流程完成。
    • 在任何地方都可以轻松重用任务、工作流程和任务 - 新任务可以由它们中的任何一个组成。
    • 变量系统提供类似 JavaScript 的变量继承：子任务可以访问父任务的变量，但也可以设置自己的变量。
    • 任务和工作流程可以公开变量作为命令行选项和参数。
    • 通过使用 Symfony 表达式语言，在执行过程中实现高级逻辑
  • 基于节点
    • 可能无限数量的远程目标
    • 节点可以全局设置或仅针对特定（子）任务设置
    • 远程任务在所有当前节点上运行
  • 安全
    • 可以通过 --dry-run 预览所有操作（但需要配置要包含的任务）
    • 可以使用 kite log 查看先前任务的完整调试输出

内容

附录

安装

您可以选择全局安装 kite（推荐）或按项目安装

先决条件

本地

  • PHP 5.4+（对于 composer 安装，应用程序可以具有更低版本）
  • Linux shell（Windows 可能会工作，但未经测试）
  • SSH/SCP 已安装（用于在节点上工作）
  • git 已安装（如果使用 git 任务）
  • composer 已安装（如果使用 composer 任务）

远程

  • PHP
  • SSH 访问

全局安装

composer global require "netresearch/kite"
~/.composer/vendor/bin/kite -V

按项目安装

cd /var/www/project
composer require "netresearch/kite"
vendor/bin/kite -V

配置

概念

  • 任务
    • 最小的、预定义的步骤
    • 有关 kite 随带的任务参考，请参阅 任务参考
  • 工作流程
    • 一种特殊的任务，允许在类中组合其子任务
    • 顶级工作流程可以公开命令行参数和选项
    • 有关 kite 随带的工作流程参考，请参阅 工作流程参考
  • 任务
    • 最高级别的任务
    • 作为命令行上的命令可用
    • 在数组中定义的任务和/或工作流程的集合（任意深度）
    • 可配置的命令行参数和选项
  • 预设
    • 配置预设（包括例如常见任务）
  • 配置文件（typo3conf/Kite.php，app/etc/kite.php，kite.php）
    • 定义任务；可以加载和覆盖预设

变量

所有配置的任务都是自动运行的，这引入了需要变量系统，允许您从动态配置中读取或更改它。Kite 提供了一种基本的语法，可以在字符串（所有任务、节点等）中访问这些变量。

选项字符串内部大括号内的每个字符串都作为 Symfony 表达式语言 表达式来评估 - 例如。

<?php
$this['messages'] = (object) ['default' => 'Hello world'];
$this['jobs']['echo'] = [
    'description' => 'Output the default message from (\{config["messages"].default\})',
    'task' => [
        'type' => 'output',
        'message' => '{config["messages"].default}'
    ]
];

如您所见，通过引号括号，您可以避免评估表达式。请参阅 Symfony 表达式语言语法 以获取有关如何使用表达式的帮助。

变量作用域

变量作用域与 JavaScript 中的非常相似。这意味着您可以从当前作用域中访问父作用域中的所有变量，除非您在当前作用域中有同名的变量。为了消除歧义，您可以使用特殊的变量 this 和 parent。

任务或工作流程选项 总是与任务的作用域绑定

这意味着，它们必须显式地设置给任务或工作流程，并且不能从父任务（如作业或工作流程）中读取。然而，这些任务的子任务可以在没有前缀的情况下访问这些选项，如果没有具有相同名称的选项或使用 parent 前缀。

全局变量

除了当前任务和父任务的选项外，还有一些全局变量可用

  • job
    • 当前作业对象（\Netresearch\Kite\Job 的实例）
  • kite
    • 包含有关 kite 包（path 和相对 dir）的一些信息的对象
  • config
    • 配置数组对象（如配置文件中所示）
  • composer
    • 提供键 packages 和 rootPackage 的 Composer 服务对象

特殊变量

  • this
    • 通过使用 this，您可以强制变量只在本作用域内查找，而不是在父作用域中查找
    • 。
  • parent
    • 指向父对象

可用函数

Kite 附带了以下 表达式语言函数

  • isset(variable) 和 empty(variable)
    • 行为与它们的 PHP 相当。仅适用于变量对象，例如
    • tasks、nodes、workflows 或 jobs 以及它们的对象（例如，不是配置数组）
  • get(variableName, variableValue) 和 set(variableName, variableValue)
    • 获取或设置变量（例如 set('job.owner', node.user)）
  • answer(question)
    • 让（命令行）用户回答一个问题并返回结果
  • answer(question)
    • 让（命令行）用户回答一个确认问题并返回结果
  • select(question, options)
    • 让（命令行）用户从选项数组中选择
  • 任何 PHP 函数
    • 允许您以您在 PHP 中习惯的方式调用 PHP 函数 - 例如 str_replace('\\\\', '/', config['somePath'])（注意四个反斜杠，这是将单个转义反斜杠传递给表达式语言所必需的）

Kite 配置文件

您需要一个名为 "Kite.php" 的文件来设置配置（部署位置）。对于 TYPO3 项目，它应该放在这里：typo3conf/Kite.php，对于 Magento app/etc/kite.php，对于其他所有应用程序只是 kite.php。一个基本示例可以是

<?php
// Example for a project without a staging environment

// This loads configuration with common jobs
$this->loadPreset('common');

// This configuration is loaded on execution of deploy or rollout job
$this['stages']['staging']['node'] = array(
    'host' => 'set host here',
    'deployPath' => 'set path on host here',
    'webUrl' => 'set url here',
    'php' => 'php56',
);

// no staging is available
unset($this['stages']['production']);

?>

任务

作业必须在配置中的 jobs 键中进行配置。它们可以包含一个 task、一个 tasks 的数组或一个 workflow（始终只有一个）。

<?php
// Job, running a single task
$this['jobs']['echo'] = [
    'description' => 'Output a message',
    'arguments' => [
        'message' => [
            'type' => 'string',
            'required' => true,
            'label' => 'The message to output'
        ]
    ],
    'task' => [
        'type' => 'output',
        'message' => '{job.message}'
    ]
];

// Job, running a workflow
$this['jobs']['diagnose'] = [
    'description' => 'Show status of packages',
    'workflow' => 'Netresearch\Kite\Workflow\Composer\Diagnose'
    // can written as follows also:
    // 'workflow' => 'composer-diagnose'
];

节点

当您在一个作业、工作流或任务上设置名为 node 或 nodes 的键时，其值将被映射到节点模型的聚合。这些模型具有以下默认配置

<?php
array(
    'user' => '',
    'pass' => '',
    'port' => '',
    'url' => '{(this.user ? this.user ~ "@" : "") ~ this.host}', // SCP/SSH URL
    'sshOptions' => ' -A{this.port ? " -p " ~ this.port : ""}{this.pass ? " -o PubkeyAuthentication=no" : ""}',
    'scpOptions' => '{this.port ? " -P " ~ this.port : ""}{this.pass ? " -o PubkeyAuthentication=no" : ""}',
    'php' => 'php', // PHP executable
    'webRoot' => '{this.deployPath}/current',
    // No default values, required to be set:
    // 'webUrl' => 'http://example.com',
    // 'host' => 'example.com',
    // 'deployPath' => '/var/www'
);

开发包

默认的 kite 作业 checkout 和 merge 仅对白名单中的开发包有效。由于 deploy 和 rollout 使用这些作业，它们也遵循这种行为。

您可以通过以下三种方式将包添加到白名单：按包名、按 git 远程 URL 或按包路径。如果没有指定任何一项，则所有 git 包都将被视为开发包。您可以在您的 Kite 配置文件 中更改白名单

<?php
// The following whitelist types are available (evaluated by OR)
// ... for the package names
$this['composer']['whitelistNames'] = 'netresearch/.*';
// ... for the git remote urls
$this['composer']['whitelistRemotes'] = 'git@github.com:netresearch/.*';
// ... for the package paths
$this['composer']['whitelistPaths'] = 'vendor/netresearch/.*';

默认配置如下

<?php
$this['composer']['whitelistNames'] = $this['composer']['whitelistPaths'] = null;
$this['composer']['whitelistRemotes'] = '{preg_quote(preg_replace("#/[^/]+$#s", "", composer.rootPackage.remote), "#")}/.+';

这意味着只有与应用程序远程共享最后一个 / 之前部分的包才会被视为开发包（例如，如果您的应用程序 git 远程为 https://github.com/netresearch/kite.git，则只有远程类似 https://github.com/netresearch/* 的包将匹配）。

部署配置

阶段

如您在 Kite 配置文件 中的示例所见，存在一个名为 stages 的顶级配置元素。它们由 common 预设设置，仅用于每个键的配置（例如，默认情况下为 staging 和 production）。它们由基于 stage-select 工作流的工作流评估，该工作流从命令行或选择问题中获取要使用的阶段。选择了一个阶段后，所有其值都设置到相应的任务（例如 deploy）。

阶段没有特殊含义，也不会以特殊方式处理 - 它们仅与基于阶段的任务（common 预设中的 deploy 和 rollout，以及 typo3 预设中的 ccr）一起使用，因为这些任务就是这样配置的。

部署

deployment 工作流将您的应用程序部署到恰好一个阶段（而 rollout 则为每个选定的阶段运行 deployment 工作流）。因此，它执行以下步骤

  1. 运行 kite composer diagnose 以确保您的应用程序处于定义的状态（没有任何未提交、未推送、未拉取，lock 文件最新等）

  2. 使用您为阶段提供的参数运行 composer checkout

    1. branch - 检出的分支。在 common 预设中，它们配置如下

      <?php
$this['stages'] = [
    'staging' => [
        'branch' => '{replace("/", "-", composer.rootPackage.name)}-staging',
        'merge' => true,
        'createBranch' => '{config["composer"]["whitelistNames"] || config["composer"]["whitelistRemotes"] || config["composer"]["whitelistPaths"]}'
        // add nodes or node in your config
    ],
    'production' => [
        'branch' => 'master',
        // add nodes or node in your config
    ]
];

    2. merge - 是否将当前检出的分支合并到要检出的分支

    3. createBranch - 如果不存在，是否创建分支。默认情况下，对于 staging 阶段，当开发包被白名单化（默认情况下是这样）时，此设置设置为 true。

    4. rsync - 调用的 rsync 任务的配置（例如，使用 excludes 选项）

  3. 在每个 node 上从当前发布创建一个新版本

  4. 在每个 node 上将当前本地状态同步到新发布目录

  5. 符号链接共享目录和文件（共享意味着在发布之间共享） - 共享目录和文件预计位于 {deployPath}/shared。它们可以在 typo3 预设中配置

    <?php
$this->merge(
    $this['jobs']['deploy']['task'],
    [
        'shared' => [
            'dirs' => ['fileadmin', 'uploads', 'typo3temp']
        ]
    ]
);

    以下是一个示例，说明如何为不同的 stage 设置不同的共享目录

    <?php
$this->merge(
    $this['stages'],
    [
        'staging' => [
            'shared' => [
                'dirs' => ['shared_dir_1', 'shared_dir_2'],
                'files' => ['file1', 'file2']
            ]
        ],
        'production' => [
            'shared' => [
                'dirs' => '{config["stages"]["staging"]["shared"]["dirs"]}',
                'file' => 'file'
            ]
        ]
    ]
);

  6. 将上一个发布指针（{deploypath}/previous）切换到当前发布。

  7. 将当前发布指针（{deploypath}/current）切换到新发布。

  8. 如果有，调用 onReady 任务。

    <?php
$this->merge(
    $this['jobs']['deploy']['task'],
    [
        'onReady' => [
            'type' => 'shell',
            'command' => 'mail',
            'optArg' => ['s' => 'Deployed to {stage}', 'user@example.com']
        ],
    ]
);

    再次证明每个 stages 都可以覆盖部署工作流中的任何选项

    <?php
$this->merge(
    $this['stages']['production'],
    [
        'onReady' => [
            'type' => 'shell',
            'command' => 'mail',
            'optArg' => ['s' => '[IMPORTANT] Deployed to {stage}', 'user@example.com']
        ],
    ]
);

当您使用回滚（--rollback 或 -r）选项调用 deployment 或 rollout 作业时

  1. 将下一个发布指针（{deploypath}/next）切换到当前发布
  2. 将当前发布指针（{deploypath}/current）切换到上一个发布
  3. 如果有，调用 onReady 任务。

当您使用回滚（--activate 或 -a）选项调用 deployment 或 rollout 任务时，它会调用部署的最后三个步骤（切换符号链接，并调用 onReady）。

使用

如上所述，所有任务都可作为 kite 子命令（kite job-name）使用。您可以通过运行以下命令来列出所有可用命令：

kite [list]

通过运行

kite help command
#or
kite command --help

您可以查看特定任务/命令的帮助信息。

常见命令

  • kite [help [command]]
    • 显示所有可用命令（任务）列表或显示指定命令的帮助信息
  • kite --workflow=<工作流名称或类>
    • 运行工作流类，无需将其包含在任务中
  • kite --workflow=<工作流名称或类> --help
    • 显示工作流的文档（PHP 类文档）、参数和选项
  • kite log [-l]
    • 显示最后（默认）、特定的（使用形如 ^2 的尖号来显示第 2 个最少日志或使用从 kite log -l 获取的时间戳）或所有可用日志记录的列表

常见任务

  • update [分支]
    • 如果提供，检出 分支
    • 运行 git pull，然后运行 composer update
  • kite checkout [--merge] 分支
    • 遍历所有 开发包，并在其中检出分支（如果可用）
    • 在包上检出分支后，遍历所有需要它的 开发包，并将版本约束更新到该分支
    • 当传递 --merge 时，当前检出的分支将合并到要检出的分支中
    • 当传递 -c 时，如果不存在，将在所有 开发包 中创建分支（您可以使用 -p 选项将操作限制到某些包）
  • kite merge [--squash] [--message="消息"] 分支
    • 遍历所有 composer 包，并将分支合并到当前检出的分支中
  • kite package-foreach [--git] 命令
    • 为每个 composer 包运行命令（可选：仅对 --git 包运行）
  • kite cc, kite ccr [阶段]
    • 在本地（cc）或特定阶段的所有节点上清除缓存（目前仅限于包含在 TYPO3 预设中的特定阶段）

开发工作流程

默认的 kite 任务旨在简化基于 composer 的应用程序的开发，这在处理跨多个包的工作分支时通常会变得相当复杂。kite 可以为您做什么，就是管理 开发包 中的分支以及对其的依赖关系。

以下列出了您在功能（可能源自主题分支）或错误修复分支上进行开发时使用的 kite 命令，您将合并到 master 中，一旦它们的更改经过审查和测试。

  1. 确保应用程序在 master 上且是最新的

    kite update master

  2. 在您想要的包中创建功能分支

    这将创建包 vendor/branch 中的 FEATURE 分支，以及所有已安装的依赖包，并在 dev-FEATURE 中要求它们（因为您的应用程序直接或间接需要该包，所以它也将检出 FEATURE 分支）。

    kite checkout -c -p vendor/package FEATURE

  3. 开发

    cd vendor/package
echo '<?php phpinfo(); ?>' > i.php
git add i.php
git commit -m 'Added php info'
git push
cd ../..

  4. （在另一个现有分支上工作）

    kite checkout ANOTHER_FEATURE

  5. 将 FEATURE 分支部署到预发布环境

    kite checkout FEATURE
kite deploy staging

  1. （在另一个现有分支上工作）

    kite checkout ANOTHER_FEATURE

  2. FEATURE 已审查，合并到 master 并删除它

    kite checkout master
kite merge --delete FEATURE

  3. 将 master（现在包括 FEATURE）从预发布环境部署到生产环境

    kite rollout production

部署任务

  • kite deploy [阶段]
    • 运行给定或所选阶段的节点上的部署
  • kite rollout [阶段]
    • 为每个阶段的所有节点运行部署，直到（包括）给定阶段

使用公钥认证

为了防止在部署过程中多次输入您的密码，您应该在服务器上设置您的公钥。通常位于此处： "~/.ssh/authorized_keys"。

故障排除

执行的所有任务及其输出都将记录到您家目录中的日志文件中。这包括例如在本地和远程shell上运行的每个命令、它们的输出、调试信息等等。基本上，它包含了您通过添加-vvv到您的kite命令所能得到的输出。

当作业失败并且您想确切知道出了什么问题时，只需运行kite log。