README

介绍 🌟

Light Hook Deploy 是一个旨在简化使用webhook进行自动部署的微服务。此服务并非旨在取代像 Jenkins、CodeDeploy、Azure Pipelines 或其他CI/CD方法等综合性工具。相反，它为需要自动部署但不需要更复杂或资源密集型工具的环境提供了一个 轻量级、易于配置 的解决方案。

🎯 为什么选择Light Hook Deploy？

无需复杂的配置或多个依赖项即可轻松设置。
与版本控制系统无缝集成，实现顺畅的部署。
轻量级且避免使用不必要的工具过载环境。

📋 目录

描述
功能
入门
部署方法
CLI参考
下一步
CLI脚本概述
致谢

描述

Light Hook Deploy 允许通过服务如 GitHub、GitLab 和 Bitbucket 的webhook进行 自动化部署。通过利用基于webhook的策略，此微服务可无缝集成到您的存储库中，并在特定事件发生时（例如向特定分支推送更改）触发部署脚本。

与需要更复杂配置和多个依赖项的 Jenkins 或 Azure Pipelines 不同，Light Hook Deploy 设计为

🛠️ 轻量级 和 易于使用。
🚀 只需几个步骤即可设置项目和部署脚本。
💡 适用于不需要大型CI/CD生态系统的环境。

功能

⚡ 简单设置 - 快速配置部署，无需复杂配置。
🔗 与GitHub、GitLab和Bitbucket存储库无缝集成。
🚀 专为需要可靠自动化的小型和中等规模项目设计。
💡 适用于精简环境 - 完美适用于不支持更重工具的服务器。
🌐 最小依赖项 - 保持系统清洁且易于维护。

入门

📋 前提条件

在开始之前，请确保您的服务器已设置以下内容

PHP 8.2 或更高版本。
Composer：请确保已安装Composer以管理PHP依赖项。
SSH访问 以运行部署脚本。
Git服务器 或在 GitHub、GitLab 或 Bitbucket 上的帐户。
shell_exec 已启用：程序使用 shell_exec 来执行脚本，因此您的PHP配置必须启用此功能。确保在 php.ini 文件中未禁用 shell_exec。

⚙️ 安装

要安装Light Hook Deploy，请使用Composer运行以下命令

composer create-project pipestream/light-hook-deploy

接下来，将 .env.example 文件复制到 .env 以设置环境配置

cp .env.example .env

该 .env 文件包含以下配置设置

# Display Slim Errors
DISPLAY_ERROR_DETAILS=true
LOG_ERRORS=true
LOG_ERROR_DETAILS=true

# -------- Request attempts per IP --------
# Redis Configuration for Rate Limiting
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# Rate Limit Configuration (to manage request attempts and prevent brute force attacks)
ENABLE_RATE_LIMIT=false # Enable it if you have Redis configured
MAX_ATTEMPTS_PER_DEPLOY=100
RATE_LIMIT_DEPLOY_MINUTES=60
# -----------------------------------------

# Max execution time
MAX_EXECUTION_TIME=600

重要说明：MAX_EXECUTION_TIME 变量对于确保脚本有足够的执行时间以避免 502网关超时 错误至关重要。建议在 Apache 或 Nginx（如果使用Nginx作为反向代理，则两者都要）中扩展超时设置。

此外，还提供了Redis配置，可用于阻止尝试通过试错（暴力破解）执行部署的IP地址。要启用Redis进行速率限制，请在您的.env文件中设置以下变量

ENABLE_RATE_LIMIT=true # Enable it if you have Redis configured
MAX_ATTEMPTS_PER_DEPLOY=100 # Maximum deploy attempts allowed per hour
RATE_LIMIT_DEPLOY_MINUTES=60 # Time frame in minutes for rate limiting

在此配置中，每小时最多可以进行100次部署尝试。

环境设置完成后，需要将cli文件夹的权限设置为755，以便允许使用命令行系统

chmod 755 cli

安装完成后，导航到cli文件夹，并运行./lhd-install.sh脚本，将用户名作为参数传递。该用户将用于从./deployments/scripts/目录执行部署脚本。

cd cli
./lhd-install.sh <username>

👤 用户配置

lhd-install.sh脚本在运行时需要传递一个<username>参数。您可以使用现有用户，或者如果需要，脚本将引导您创建一个新的用户。所选用户将被配置为具有执行部署脚本所需的所有权限。

您可以将用户设置为类似www-data（通常用于Web服务），或者选择不同的用户以保持部署任务独立。
脚本将授予所选用户以下权限
- Web服务执行：用户将具有www-data权限，通过Web运行服务。
- Sudo执行：Sudo权限将限制在deployments目录下的scripts文件夹中的脚本。
用户将在/etc/passwd中进行配置，以便允许Bash执行，这是运行部署脚本所必需的。这确保了用户在部署过程中有适当的shell访问权限来执行命令。

🌐 Web服务器配置

确保您的Web服务器（Apache或Nginx）配置为指向公共目录，其中包含index.php文件。这对于应用程序的正确运行是必要的。

DocumentRoot /path-to-your-project/public

确保您的Apache或Nginx配置文件已更新，以便从该目录提供服务。

部署方法

基于Webhook的部署 ⚡

此方法利用来自GitHub、GitLab或Bitbucket等服务的Webhook。该服务可以配置为监听您的存储库Webhook部分中指定的任何事件，例如

🚀 推送
🔀 合并
📩 请求拉取
⚙️ 您配置的任何其他自定义事件。

当这些事件被触发时，Light Hook Deploy将执行为项目配置的部署脚本。

🔒 您可以使用令牌来保护Webhook，以确保只有经过验证的请求才能触发部署。

📚 更多关于基于Webhook的部署信息

通过端点手动部署 🔐

或者，您可以通过向特定的部署端点发送请求来部署您的项目。此方法需要您提供项目名称和密码以授权部署。

当持续集成由同一个存储库或跨不同服务器和工具处理，并且需要直接与项目连接进行部署时，特别推荐此方法。例如，如果您使用

🔧 Bitbucket Pipelines
⚙️ GitHub Actions
🔄 GitLab CI/CD

或如果您有其他配置了持续集成的服务器，此方法确保部署可以在项目所在的具体主机上处理。

✅ 此选项在您的CI/CD设置需要直接与部署主机交互时是理想的，提供更多关于何时以及如何触发部署的控制。

📚 更多关于通过端点手动部署的信息

下一步

📜 要有效地配置部署和脚本，请继续阅读以下文档

配置部署和脚本：本节将指导您设置您的钩子、定义部署脚本，并确保您的集成与版本控制系统顺畅工作。这是充分利用 Light Hook Deploy 和确保无缝自动化部署的必要条件。
响应处理和状态码：在这里，您将了解如何处理响应以及部署端点返回的各种状态码。这些知识对于故障排除和优化您的部署过程至关重要。

通过遵循以下步骤，您将确保自动化部署的强大设置和有效管理部署生命周期的清晰理解。

CLI脚本概述

📜 要更好地了解 cli 目录中 CLI 脚本的功能，请参考以下文档

CLI 脚本概述：本节涵盖了 CLI 脚本的目的和功能，例如 lhd-add-deployment-structure.sh、lhd-add-secret-token.sh 等。这些脚本有助于配置部署、管理访问密钥和处理部署结构。通过熟悉这些脚本，您将能够通过命令行高效地管理您的部署。

👥 致谢

特别感谢以下为此项目作出贡献的参与者

pipestream / light-hook-deploy

维护者

详细信息