bruvtools 🚀

bruvtools 🚀

你的私有应用平台 —— 在任何地方部署微服务，使用任何语言，只需一个 CLI

使用相同的简单命令，将 Node.js、Go、Python、Java、PHP、Ruby 或任何可容器化的应用部署到 CapRover、AWS、GCP 或 Kubernetes。零厂商锁定。

🎯 bruvtools 是什么？

bruvtools 可将任何云服务器变成你的私有应用平台——就像拥有自己的 Heroku、Vercel 或 Railway。结合 CapRover，你将获得：

特性	说明
✅ 推送即可部署	执行 bruvtools deploy my-app，应用即刻上线
✅ 自动 SSL 证书	自动启用 HTTPS
✅ 支持任何语言	Node.js、Python、Go、Java、PHP、Ruby、Docker
✅ 零停机部署	内置滚动更新
✅ 自动扩缩容	按需扩展或缩减应用
✅ 私有且安全	你自己的服务器，你自己的规则
✅ 经济实惠	每月 $5，而其他平台每月 $25+

🚀 快速开始：5 分钟搭建你的私有平台

第 1 步：创建 CapRover 服务（2 分钟）

最简单的入门方式是使用 DigitalOcean 的 CapRover 一键部署：

你将获得：

• ✅ 每月 $5 的服务器，已预装 CapRover
• ✅ $100 免费额度，供 DigitalOcean 新用户使用（免费 2 个月！）
• ✅ 自动配置 Docker 和防火墙
• ✅ 几分钟内即可部署

**其他安装方式：**按照 CapRover 入门指南，在任何云服务商上手动安装。

第 2 步：安装 bruvtools（30 秒）

npm install -g bruvtools
bruvtools --version  # Should show: 0.2.16

第 3 步：配置并部署（2 分钟）

# Clone and test the working example
git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools/examples/hello-world

# Setup bruvtools (one time)
bruvtools init
# This creates:
# - bruvtools.yml (configuration: machine names, domains, projects)
# - .env (secrets: passwords, API keys)
# ⚠️  IMPORTANT: Never commit bruvtools.yml or .env to version control!

# Deploy with smart auto-creation and collision detection
bruvtools deploy my-app
# ✅ Checks if app exists
# ✅ Auto-creates app if needed  
# ✅ Handles name collisions (my-app-1, my-app-2, etc.)
# ✅ Deploys with clear step-by-step progress
# ✅ Your app is live with HTTPS!

**🎯 就这么简单！**你的私有应用平台已准备就绪。应用现已通过 https://my-app.yourdomain.com 上线，并自动启用 SSL。

🔌 MCP 集成（Cursor.com）——革命性的开发体验

借助 Model Context Protocol（MCP）支持，你将获得革命性的开发体验——无需离开编辑器，即可直接从 Cursor.com 部署：

特性	说明
📋 列出所有应用	在 IDE 中查看你的完整基础设施
📊 实时拉取日志	无需切换窗口即可调试
🚀 借助 AI 部署	只需向 Claude 询问：“将此部署到生产环境”
📈 实时监控状态	在编辑器中查看应用健康状况、指标和扩缩容情况
🔄 即时回滚	“回滚到上一版本”——完成！
🎯 智能建议	AI 根据你的代码推荐优化方案

🤯 实际体验：

You: "Deploy this Node.js app to my-api-v2"
Claude: ✅ Deploying to CapRover...
        ✅ App created with collision detection  
        ✅ Building Docker image...
        ✅ Live at https://my-api-v2.yourdomain.com
        ✅ SSL certificate auto-configured
        
You: "Show me the logs"
Claude: [Real-time logs streaming in your editor]

You: "Scale this to 3 replicas"  
Claude: ✅ Scaled to 3 replicas, load balanced automatically

这就是开发的未来——你的 AI 编程搭档能够真正部署和管理基础设施。无需切换上下文，无需单独的终端，也无需部署仪表板。只需编写代码、提出请求，应用即可上线。

请参阅下文，查看 Claude 在成功完成设置后的实际回复示例。

🔌 Cursor.com 的 MCP 设置（5 分钟）

选项 1：自动设置（推荐）

要以最简单的方式完成设置，请在 bruvtools 仓库中运行自动化脚本：

# Clone the repository to get the setup script
git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools

# Run the automated MCP setup
chmod +x setup-mcp.sh
./setup-mcp.sh

# Follow the prompts for global or project-specific installation

注意：必须在 bruvtools 仓库目录中运行设置脚本，因为它会使用随附的 mcp-server.js 文件。

选项 2：手动设置

第 1 步：安装 bruvtools MCP 服务

# Install bruvtools globally (if not already installed)
npm install -g bruvtools

# Verify MCP server is available
bruvtools --version  # Should show: 0.2.16

第 2 步：配置 Cursor.com MCP 设置

1. 打开 Cursor.com 设置：

   • 按 Cmd/Ctrl + , 打开设置
   • 搜索“MCP”，或前往 Extensions → Model Context Protocol

2. 添加 bruvtools MCP 服务：

   {
     "mcpServers": {
       "bruvtools": {
         "command": "bruvtools",
         "args": ["mcp"],
         "env": {
           "CAPROVER_PASSWORD": "your-caprover-password",
           "CAPROVER_DOMAIN": "your-domain.com",
           "CAPROVER_MACHINE": "your-machine-name"
         }
       }
     }
   }
   

3. 备选方案：使用本地配置： 如果项目中有 bruvtools.yml 和 .env 文件：

   {
     "mcpServers": {
       "bruvtools": {
         "command": "bruvtools",
         "args": ["mcp"],
         "cwd": "${workspaceFolder}"
       }
     }
   }
   

第 3 步：重启 Cursor.com 并测试集成

在 Cursor.com 中打开任意项目，然后尝试在 Claude 中运行以下命令：

You: "List all my deployed apps"
Claude: [Shows your CapRover apps with URLs and status]

You: "Deploy this project as my-new-app"
Claude: [Deploys your current project to CapRover]

🎯 成功设置后，你将看到：

Claude 通过 MCP 集成展示已部署服务的示例

🎯 增强的开发者体验（v0.2.16）

✅ 部署后健康状况验证

bruvtools deploy my-app
# ✅ Step 1: Creating app...
# ✅ Step 2: Packaging...  
# ✅ Step 3: Deploying...
# ✅ Step 4: Enabling SSL...
# 🔍 Step 5: Verifying deployment health...
#    ✅ Instance count: 1
#    ✅ App is responding correctly!
# 🎉 Deployment completed successfully!

🔧 自动修复常见问题

• 实例数量 = 0：自动扩展到 1 个实例
• 端口不匹配：检测 server.js 与 Dockerfile 之间的端口冲突
• SSL 问题：为证书问题提供清晰的指导
• 容器崩溃：显示调试步骤和常见解决方案

🔐 智能环境变量处理

🚨 大型环境变量检测与自动拆分 ⚠️ 实验性功能

bruvtools 可以检测环境变量是否超过平台限制，并提供智能解决方案（目前为实验性功能）：

bruvtools init
# 🔍 Analyzing environment variables...
# ⚠️  Large environment variable detected: JWT_TOKEN (1083 characters)
# 💡 CapRover has ~1000 character limits on environment variables

🔄 手动令牌重构 ✅ 可用

你可以使用以下模式手动实现拆分环境变量：

// Universal function (manually add to your project)
function getEnvVar(varName) {
  // First try to get the variable directly
  if (process.env[varName]) {
    return process.env[varName];
  }
  
  // If not found, try to reconstruct from split parts
  let reconstructed = '';
  let partIndex = 1;
  
  while (true) {
    const partName = `${varName}_${partIndex}`;
    const part = process.env[partName];
    
    if (part) {
      reconstructed += part;
      partIndex++;
    } else {
      break;
    }
  }
  
  return reconstructed || undefined;
}

// Use in your app
const JWT_TOKEN = getEnvVar('JWT_TOKEN'); // Works with both single and split tokens!

🔧 配置文件

bruvtools 将配置与机密信息清晰分离：

📄 bruvtools.yml — 配置（非机密信息）

default_provider: caprover
providers:
  caprover: 
    machine: your-caprover-machine-name
    domain: your-domain.com
projects:
  my-app:
    provider: caprover
    port: 80

🔐 .env — 仅存放机密信息

# CapRover Authentication
CAPROVER_PASSWORD=your-caprover-password

# Optional: App secrets
DATABASE_URL=postgresql://user:pass@host:port/db
API_KEY=your-api-key

⚠️ 安全性：这两个文件都会自动添加到 .gitignore，绝不能提交到版本控制系统。

🏗️ CapRover 设置详情

前提条件

• 域名（每年 $2）— 用于通配符 DNS（*.yourdomain.com）
• 具有公网 IP 的服务器（每月 $5）— DigitalOcean、Vultr、Linode 等
• 已安装 Docker — 一键部署中已包含

DNS 配置

在 DNS 中设置通配符 A 记录：

• 类型：A 记录
• 主机：*.captain（或 *.apps、*.dev 等）
• 指向：服务器的 IP 地址
• TTL：300（或默认值）

服务器要求

• 最低配置：1GB RAM、1 个 CPU 核心
• 推荐配置：构建较大型应用时使用 2GB RAM
• 操作系统：Ubuntu 22.04+（已测试并推荐）
• Docker：25.x+ 版本（一键部署时自动安装）

📋 常用命令

# Interactive setup (one time)
bruvtools init

# View all deployed apps/services
bruvtools services     # Show all deployed apps with URLs
bruvtools apps         # Same as services (alias)
bruvtools deployed     # Same as services (alias)  
bruvtools dashboard    # Same as services (alias)

# Deploy and manage apps
bruvtools deploy <app-name>    # Deploy with smart auto-creation
bruvtools create <app-name>    # Create app manually (optional)
bruvtools status <app-name>    # Check app status
bruvtools logs <app-name>      # View app logs
bruvtools scale <app> <count>  # Scale app replicas
bruvtools test <app-name>      # Test app connectivity

🚀 高级功能

智能冲突检测

bruvtools deploy my-app
# ✅ App "my-app" created and deployed

bruvtools deploy my-app  
# ⚠️  App "my-app" already exists, using "my-app-1" instead
# ✅ App "my-app-1" created and deployed

多环境部署

# Deploy to different environments
bruvtools deploy my-app-dev     # Development
bruvtools deploy my-app-staging # Staging  
bruvtools deploy my-app-prod    # Production

🔧 支持的语言

语言	自动检测	状态
Node.js	package.json	✅ 已全面测试
Go	go.mod	✅ 已就绪
Python	requirements.txt	✅ 已就绪
Java	pom.xml, build.gradle	✅ 已就绪
PHP	composer.json	✅ 已就绪
Ruby	Gemfile	✅ 已就绪
任意语言	Dockerfile	✅ 已就绪

🌐 在线示例

• Hello World：https://hello-world.your-domain.com
• CNPJ Enricher：https://cnpj-enricher.your-domain.com
• Kommo Integration：https://kommo-contacts-api.your-domain.com
• ABEC Med API：https://abecmed-api-legacy.your-domain.com

API 调用示例：

# Get Brazilian company information by CNPJ (tax ID)
curl "https://cnpj-enricher.your-domain.com/ficha?cnpj=11222333000181"

# Search patient by CPF (with API key)
curl -X GET "https://abecmed-api-legacy.your-domain.com/patient-search?cpf=024.804.267-00" \
  -H "X-API-KEY: your-api-key"

# Test Kommo integration
curl "https://kommo-contacts-api.your-domain.com/healthcheck"

📁 示例项目

仓库在 examples/ 目录中包含可直接部署的示例：

🚀 Hello World（examples/hello-world）

简单的 Node.js Web 服务 — 非常适合测试 bruvtools 设置。

cd bruvtools/examples/hello-world
bruvtools deploy hello-world

💼 CNPJ Enricher（examples/cnpj-enricher）

使用外部数据源的巴西公司信息 API。

cd bruvtools/examples/cnpj-enricher
bruvtools deploy cnpj-enricher

📞 Kommo Contacts API（examples/kommo-contacts-api）

用于 Kommo（AmoCRM）的 CRM 集成微服务，提供联系人管理功能。

cd bruvtools/examples/kommo-contacts-api
bruvtools deploy kommo-contacts-api

🏥 ABEC Med API Legacy (examples/abecmed-api-legacy)

集成 Google Sheets 的医疗患者搜索微服务。

功能：

• 按 CPF 或手机号码搜索患者
• Google Service Account 身份验证
• 巴西电话号码标准化
• API 密钥身份验证
• 全面的日志记录

# Setup Google Service Account key first
ls examples/abecmed-api-legacy/keys/abecmed-368dfd6bae7c.json

# Deploy the service
cd bruvtools/examples/abecmed-api-legacy
bruvtools deploy abecmed-api-legacy

# Test the API
curl -X GET "https://abecmed-api-legacy.your-domain.com/patient-search?cpf=024.804.267-00" \
  -H "X-API-KEY: adcd2e35-787d-4dd2-ba8c-76085a99d2a4"

🎯 每个示例都包含：

• ✅ 完整源代码
• ✅ 用于部署的 Dockerfile
• ✅ 适用于 CapRover 的 captain-definition
• ✅ 包含依赖项的 package.json
• ✅ 附带 API 文档的详细 README
• ✅ 环境变量配置

🔧 快速部署任意示例：

git clone https://github.com/fcavalcantirj/bruvtools.git
cd bruvtools/examples/[example-name]
bruvtools deploy [app-name]

💰 成本对比

平台	月费用	功能
bruvtools + CapRover	$5	应用数量不限、SSL、扩展、自己的服务器
Heroku	$25+	应用数量有限、SSL 需额外付费、共享资源
Vercel Pro	$20+	函数数量有限、带宽限制
Railway	$20+	使用量有限、共享基础设施
AWS/GCP	$50+	设置复杂、隐藏费用

💡 使用 DigitalOcean 的 $100 额度，可免费使用 20 个月！

🛠️ 故障排除

常见问题

问题	解决方案
“未找到 CapRover CLI”	运行 npm install -g caprover 并重启终端
“不允许使用此应用名称”	仅使用小写字母和连字符（例如，my-app-name）
“身份验证失败”	检查 .env 文件中的 CAPROVER_PASSWORD 是否正确
显示默认 CapRover 页面	等待 2-3 分钟，直至部署完成

⚠️ 环境变量注意事项与限制

🚨 大型环境变量（>1000 个字符）

问题：CapRover 和许多云平台对环境变量大小有严格限制：

• CapRover：每个环境变量约 1000 个字符
• Heroku：所有环境变量总计 32KB
• AWS Lambda：所有环境变量总计 4KB
• Docker：没有硬性限制，但值非常大时性能会下降

常见原因：

• 🔑 JWT 令牌：通常超过 1000 个字符（尤其是包含大量声明时）
• 🔐 私钥：RSA/ECDSA 密钥可能超过 1600 个字符
• 📄 JSON 配置：大型配置对象
• 🌐 Base64 编码数据：图像、证书或二进制数据

✅ 大型环境变量的解决方案

1. 手动拆分 ✅ 可用（推荐方案）

   # Split a 1083-character JWT token manually
   export JWT_TOKEN_1="first_part_here"
   export JWT_TOKEN_2="second_part_here"
   export JWT_TOKEN_3="third_part_here"
   
   # Add getEnvVar() function to your code (manual implementation)
   # Use getEnvVar('JWT_TOKEN') to reconstruct automatically
   

2. 替代方案 ✅ 可用

   # Option 1: Store in files (for very large data)
   echo "large_private_key_content" > /app/private.key
   # Then read in your app: fs.readFileSync('/app/private.key', 'utf8')
   
   # Option 2: Use external secret management
   # - AWS Secrets Manager
   # - HashiCorp Vault  
   # - Azure Key Vault
   # - Google Secret Manager
   

✅ 最佳实践

1. 不要将密钥提交到 git

   # Always in .gitignore:
   .env
   .env.local
   .env.production
   bruvtools.yml
   

2. 根据数据类型使用合适的存储方式

   • 短密钥（<500 个字符）：环境变量 ✅
   • 长令牌（500-2000 个字符）：拆分到多个环境变量 ✅
   • 超长数据（>2000 个字符）：文件或密钥管理 ✅
   • 二进制数据：使用文件，切勿使用环境变量 ❌

3. 测试还原结果

   // Always test that your tokens work after reconstruction
   const token = getEnvVar('JWT_TOKEN');
   console.log(`Token length: ${token ? token.length : 0} characters`);
   if (!token || token.length < 100) {
     throw new Error('JWT token reconstruction failed!');
   }
   

📋 各平台限制

平台	单个变量限制	总限制	备注
CapRover	约 1000 个字符	无总限制	硬性限制，失败时不显示错误
Heroku	32KB	总计 32KB	包含变量名
AWS Lambda	单个变量无上限	总计 4KB	限制非常严格
Docker	无硬性限制	取决于内存	会影响性能
Kubernetes	1MB	无总限制	在 etcd 中以 Base64 编码存储

🪟 Windows PowerShell 支持

✅ “完全”支持！ bruvtools 可在 Windows PowerShell 上“无缝”运行。嗯，理应如此 °¿°

# 1. Install both tools
npm install -g bruvtools caprover

# 2. Verify installation
bruvtools --version  # Should show: 0.2.16
caprover --version   # Should show: 2.x.x

# 3. Deploy normally (same as Mac/Linux)
bruvtools init
bruvtools deploy my-app

---

要求：Node.js 16+ • 许可证：MIT • 版本：0.2.16

🤝 贡献

欢迎贡献！这是一个严肃的开源项目，致力于让部署变得简单可靠。

1. Fork 此仓库
2. 创建功能分支
3. 彻底测试你的更改
4. 提交 pull request

📞 支持

• 问题：GitHub Issues
• 文档：GitHub Wiki
• 电子邮件：[email protected]

---

由 bruvtools 团队倾心打造 • 永不放弃！ 🚀