CapRover 部署

概述

本技能支持仅通过自然语言指令（例如“部署 myapp”）即可将应用部署至 CapRover。它提供两种主要部署策略：

1. GitHub workflow_dispatch —— 触发已配置的 CI/CD 工作流（构建 + 部署）
2. CapRover 应用令牌 / Webhook —— 直接调用 CapRover API 执行构建与部署

配置

所有凭证均存放在技能目录下的 config.json 文件中（该文件已加入 .gitignore，不会被提交至 Git 仓库）。

config.json 格式

{
  "caprover": {
    "url": "https://captain.example.com",
    "password": "YOUR_MASTER_PASSWORD"
  },
  "github": {
    "token": "ghp_YOUR_GITHUB_PAT",
    "owner": "your-github-username"
  },
  "apps": {
    "myapp": {
      "caprover_app_name": "myapp",
      "github_repo": "your-username/myapp",
      "github_workflow": "deploy.yml",
      "default_branch": "main",
      "caprover_app_token": "OPTIONAL_PER_APP_TOKEN",
      "caprover_webhook_url": "OPTIONAL_WEBHOOK_URL_FROM_CAPROVER_DASHBOARD"
    }
  }
}

各凭证说明

部署决策流程

当用户输入 “deploy X”（可选附加 “to branch Y”）时，系统执行以下逻辑：

1. 读取 config.json
2. 根据应用名称查找匹配项（支持模糊匹配）
3. 选择部署策略：
   a. 若同时配置了 github.token、github_repo 和 github_workflow → 使用 GitHub workflow_dispatch
   b. 否则，若配置了 caprover_webhook_url → 向该 Webhook URL 发起 POST 请求
   c. 否则，若配置了 caprover_app_token → 调用 caprover CLI 执行部署
   d. 若缺少必要配置，则提示用户补充
4. 执行所选策略，并反馈结果

策略 1：GitHub Workflow Dispatch（推荐）

curl -X POST 
  -H "Authorization: Bearer $GITHUB_TOKEN" 
  -H "Accept: application/vnd.github+json" 
  https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches 
  -d '{"ref":"main"}'

检查工作流运行状态：

curl -H "Authorization: Bearer $GITHUB_TOKEN" 
  https://api.github.com/repos/OWNER/REPO/actions/runs?per_page=1

策略 2：CapRover Webhook 触发

curl -X POST "WEBHOOK_URL_FROM_CONFIG"

Webhook URL 获取路径：CapRover 控制台 → Apps → [应用名称] → Deployment 标签页 → Webhook URL

策略 3：CapRover 应用令牌（CLI 部署）

caprover deploy 
  --caproverUrl https://captain.example.com 
  --appToken "APP_TOKEN" 
  --appName "myapp" 
  --imageName "ghcr.io/owner/myapp:latest"

对话式触发指令

为新项目配置 CapRover 部署

步骤 1：选择合适的工作流模板

步骤 2：在项目中创建工作流文件

mkdir -p PROJECT/.github/workflows
cp assets/templates/deploy-image.yml PROJECT/.github/workflows/deploy.yml
# 将 __APP_NAME__ 替换为实际的 CapRover 应用名称
sed -i 's/__APP_NAME__/myapp/g' PROJECT/.github/workflows/deploy.yml

步骤 3：如需 tar 包部署，请添加 captain-definition（可选）

cp assets/templates/captain-definition.json PROJECT/captain-definition

步骤 4：配置 GitHub Secrets

在 GitHub → 仓库 → Settings → Secrets and variables → Actions 中添加以下密钥：

如使用多环境部署，请额外添加：

• CAPROVER_APP_PROD、CAPROVER_APP_TOKEN_PROD
• CAPROVER_APP_STAGING、CAPROVER_APP_TOKEN_STAGING

步骤 5：提交并推送更改

cd PROJECT
git add .github/workflows/deploy.yml captain-definition
git commit -m "ci: add CapRover deploy workflow"
git push

注意事项

• caprover CLI 可能未安装：运行 npm install -g caprover 安装
• 对于私有仓库，GitHub Token 需具备 repo 与 workflow 权限范围
• 部署触发后请务必确认成功（检查 API 返回或 GitHub Actions UI）
• 更多工作流模板请参阅 assets/templates/ 目录