部署 ​

概述 ​

部署是指将您的代码从源代码控制提供商下载到您的服务器上的过程，以便世界可以访问。Forge 会跟踪最近的 10 次部署，以便您可以查看部署的内容、部署时间、部署所需时间，以及查看您的 部署脚本 的输出。

环境 ​

某些应用程序，例如使用 Laravel 框架创建的应用程序，可能需要一个 .env 文件来配置数据库和缓存等设置。您可以在 Forge 网站的管理面板中创建和编辑您的环境文件。

环境圈权限 ​

您可以使用 site:manage-environment 权限授予圈子成员查看和编辑网站环境文件（或 WordPress 配置）的权限。如果没有此权限，Forge 不会 将环境文件的内容显示给圈子成员。

加密环境文件 ​

Forge 支持 Laravel 的 加密环境文件，而无需您在部署脚本中包含您的加密密钥。

要利用此功能，请将您的加密密钥添加到您网站管理面板的“环境加密密钥”部分。添加后，Forge 会在部署期间将该值注入到 LARAVEL_ENV_ENCRYPTION_KEY 环境变量中，允许您将 env:decrypt Artisan 命令添加到您的部署脚本中，而无需显式设置 --key 选项。

php artisan env:decrypt --force

快速部署 ​

Forge 的“快速部署”功能允许您在将代码推送到源代码控制提供商时轻松部署您的项目。当您将代码推送到您配置的快速部署分支时，Forge 会从源代码控制中拉取您的最新代码并运行您应用程序的配置部署脚本。

您可以在您网站管理面板的“应用程序”选项卡中点击“启用快速部署”按钮来启用 Forge 的快速部署功能。

对于使用 自定义源代码控制提供商 的网站，您需要手动设置一个 部署触发器，以便在您将代码推送到源代码提供商时部署您的代码。点击您网站管理面板的“应用程序”选项卡中的“管理快速部署”按钮以获取说明。

部署脚本 ​

当您的项目部署到服务器时，执行的命令由您网站的部署脚本决定。当然，您可以在 Forge UI 中直接编辑此部署脚本。默认情况下，您网站的部署脚本将

• 导航到网站目录
• 执行 git pull 命令
• 安装应用程序的 Composer 依赖项
• 执行 php artisan migrate 命令（如果您的应用程序包含 artisan 文件）

您可以通过选中部署脚本面板下方的“将 .env 变量提供给部署脚本”复选框，使您的 .env 变量可供部署脚本使用。启用后，Forge 会自动将您网站的 .env 文件中的变量注入到部署脚本中，允许您像访问任何正常的 Bash 变量一样访问它们

echo "${APP_NAME} is deploying..."

PHP 版本 ​

如果您在服务器上安装了 多个版本的 PHP，则可能需要更新您的部署脚本以使用正确的 PHP 版本。

默认情况下，php 将始终指向 CLI 上使用的活动 PHP 版本。如果您需要使用其他版本的 PHP，则必须使用 phpx.x（其中 x.x 反映了使用版本，例如 php8.1）在调用 PHP 命令时。

新创建网站的部署脚本使用 $FORGE_PHP 环境变量。此环境变量将始终包含为网站配置的当前 PHP 二进制文件，因此在使用此变量并切换网站的 PHP 版本时，无需对部署脚本进行任何其他更改。

环境变量 ​

Forge 会在运行时自动将以下环境变量注入到您的部署脚本中

您可以像使用其他 Bash 变量一样使用这些变量。

if [[ $FORGE_MANUAL_DEPLOY -eq 1 ]]; then
    echo "This deploy was triggered manually."
fi

例如，您可能希望在提交消息包含“wip”时阻止部署。

if [[ $FORGE_DEPLOY_MESSAGE =~ "wip" ]]; then
    echo "WORK IN PROGRESS, DO NOT CONTINUE."
    exit 1
fi

从 CI 部署 ​

到目前为止，我们已经讨论了从 Forge UI 或使用 Forge 的“快速部署”功能部署 Forge 站点。但是，您也可以从您选择的 CI 平台部署它们。

要从 CI 平台执行 Forge 部署，您可以使用部署触发器或 Forge CLI。

使用部署触发器 ​

您可以通过指示您的 CI 平台向您站点详细信息中显示的“部署触发器 URL”发出 GET 或 POST 请求来随时执行部署。

虽然您可以随时刷新站点令牌，但您需要在刷新令牌后更新使用此 URL 的任何服务。

可以通过传递给部署触发器 URL 的查询参数将其他数据传递到您的部署脚本。例如，当传递以下查询参数 ?token=abc1234&env=staging 时，Forge 会自动注入一个自定义的 FORGE_VAR_ENV 变量，该变量将评估为 "staging"。

您可以使用 4 个保留参数在触发部署时传递 Forge 信息。

• forge_deploy_branch: 包含提交的代码分支。Forge 仅在分支与站点当前部署的分支匹配时才会触发部署。
• forge_deploy_commit: 提交的哈希值。这将在“部署”表中可见，并在您的部署脚本中作为 FORGE_DEPLOY_COMMIT 环境变量提供。
• forge_deploy_author: 提交的作者。这将在“部署”表中可见，并在您的部署脚本中作为 FORGE_DEPLOY_AUTHOR 环境变量提供。
• forge_deploy_message: 提交信息。这将在您的部署脚本中作为 FORGE_DEPLOY_MESSAGE 环境变量提供。

使用 Forge CLI ​

如果您想访问部署输出或执行其他部署操作（例如重启服务），可以使用 Forge CLI。

安装 Forge CLI 后，您可以在 CI 平台的部署管道中执行 forge deploy 命令。

为了从您的 CI 平台向 Forge 进行身份验证，您需要在 CI 构建环境中添加 FORGE_API_TOKEN 环境变量。您可以在 Forge API 设置仪表板 中生成 API 令牌。此外，您的 CI 平台需要对您的服务器进行 SSH 访问。

GitHub Actions 示例 ​

如果您的站点使用 GitHub Actions 作为其 CI 平台，以下指南将帮助您配置 Forge 部署，以便在有人将提交推送到 main 分支时自动部署您的应用程序。

1. 首先，将 FORGE_API_TOKEN 环境变量添加到您的“GitHub > 项目设置 > 秘密”设置中，以便 GitHub 在运行操作时可以向 Forge 进行身份验证。

2. 接下来，将 SSH_PRIVATE_KEY 环境变量添加到您的“GitHub > 项目设置 > 秘密”设置中，以便 GitHub 可以对您的站点的服务器进行 SSH 访问。

3. 然后，在 your-project/.github/workflows 目录中创建一个 deploy.yml 文件。该文件应包含以下内容

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup SSH
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.1
          tools: composer:v2
          coverage: none
      - name: Require Forge CLI
        run: composer global require laravel/forge-cli
      - name: Deploy Site
        run: |
          forge server:switch your-server-name
          forge deploy your-site-name.com
        env:
          FORGE_API_TOKEN: ${{ secrets.FORGE_API_TOKEN }}

4. 最后，您可以编辑deploy.yml文件以满足您网站的部署需求，因为它可能需要不同的 PHP 版本或像npm这样的库。完成后，将deploy.yml文件提交并推送到main分支，以便 GitHub Actions 运行第一个部署作业。

使用 Chipper CI 的示例 ​

如果您的网站使用 Chipper CI 作为其 CI 平台，则可以使用以下配置在推送到main分支时部署您的 Forge 网站。

1. 首先，将FORGE_API_TOKEN环境变量添加到您的“项目 > 项目设置 > 密钥”设置中，以便 Chipper 可以与 Forge 进行身份验证。

2. 接下来，将SSH_PRIVATE_KEY环境变量添加到您的“项目 > 项目设置 > 密钥”设置中，以便 Chipper 可以访问您网站服务器的 SSH。

3. 然后，编辑您的.chipperci.yml文件。该文件将类似于以下内容

version: 1

environment:
  php: 8.1
  node: 14

on:
  push:
    branches:
      - main

# Add the following 2 pipeline steps to your Chipper CI pipeline:
pipeline:  
  - name: Configure Forge
    cmd: |
      echo $SSH_PRIVATE_KEY > ~/.ssh/id_forge
      chmod 0600 ~/.ssh/id_forge
      composer global require laravel/forge-cli
    
  - name: Deploy
    cmd: |
      forge server:switch your-server-name
      forge deploy your-site-name.com

4. 当然，您可以进一步调整.chipperci.yml文件以满足您的需求。完成后，提交并推送到main分支，以便 Chipper CI 可以部署您的网站。

部署分支 ​

您可以通过更新部署分支设置来更改部署到您网站的分支。更新分支后，您需要点击立即部署以手动触发新分支的全新部署。

Git 远程 ​

从网站的应用管理仪表板更新 Git 远程将更新您服务器上的 Git 远程 URL；但是，网站不会在该过程中被删除或变得不可用。更新的 Git 远程必须包含与当前安装的存储库相同的存储库/Git 历史记录。

您不应该使用此功能将完全不同的项目安装到网站上。如果您想安装完全不同的项目，您应该使用应用仪表板中的“卸载存储库”按钮完全卸载现有存储库。

部署通知 ​

您可以在网站管理仪表盘的**通知**选项卡中启用网站的部署通知。Forge 支持多种通知渠道

• 电子邮件
• Slack
• Telegram
• Microsoft Teams
• Discord

Slack ​

要启用 Slack 通知，首先输入您要发送消息的频道名称，然后点击**启用 Slack 通知**。您将被重定向到 Slack 应用程序授权页面，您需要点击**允许**。

如果您想修改 Forge 消息的频道，您应该先禁用 Slack 通知，然后重新启用网站的通知。

Telegram ​

要启用 Telegram 通知，请打开 Telegram 并创建一个或选择一个您希望 Forge 发送部署通知的群聊。接下来，您应该通过搜索用户laravel_forge_telegram_bot将 Laravel Forge 机器人添加到聊天中。最后，复制 Forge 在 Telegram 部署通知部分提供的/start命令，并将其粘贴到聊天中。

如果您想更改 Forge 消息的群组，您应该禁用 Telegram 通知，然后按照上述步骤再次激活通知。

Microsoft Teams ​

要启用 Microsoft Teams 通知，您首先需要在您选择的 Teams 频道中创建一个新的**传入 Webhook** 连接器。一旦 Teams 生成了一个 Webhook，您需要将 URL 复制到**Webhook URL** 字段中，然后点击**启用 Microsoft Teams 通知**。Forge 现在将为成功和失败的部署通知配置的频道。

如果您想更改 Webhook URL，您首先需要禁用 Microsoft Teams 通知，然后重新启用通知。

Discord ​

要启用 Discord 通知，您首先需要在您的 Discord 服务器上创建一个新的 **传入 Webhook** 集成。Discord 生成 Webhook 后，您需要将 URL 复制到 **Webhook URL** 字段中，然后点击 **启用 Discord 通知**。Forge 现在将为成功和失败的部署通知配置的频道。

如果您想更改 Webhook URL，您首先需要禁用 Discord 通知，然后重新启用通知。

Webhooks ​

Forge 也可以在每次部署后向任意 URL 发送 HTTP POST 请求。请求的有效负载将包含服务器 ID、站点 ID、部署状态以及相关的提交信息。

{
  "status": "success",
  "server": {
    "id": 123,
    "name": "my-awesome-server"
  },
  "site": {
    "id": 456,
    "name": "my-awesome-site.dev"
  },
  "commit_hash": "382b0f5185773fa0f67a8ed8056c7759",
  "commit_url": "https://github.com/johndoe/my-awesome-site/commit/382b0f5185773fa0f67a8ed8056c7759",
  "commit_author": "John Doe",
  "commit_message": "deploying!"
}

圈子权限 ​

您可以通过授予 site:manage-deploys 权限来授予圈子成员管理部署脚本、管理维护模式和部署站点的权限。