feat: Enhance deployment capabilities with direct server deployment tools, email configuration, and comprehensive documentation
This commit is contained in:
ethan.chen
295
DIRECT_DEPLOY.md
Normal file
295
DIRECT_DEPLOY.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 直接部署方案（推荐）
|
||||
|
||||
## 概述
|
||||
|
||||
直接在服务器上运行 MCP 服务器（不使用 Docker），这样可以直接使用 MCP 工具进行部署，无需 SSH 连接。
|
||||
|
||||
## 优势
|
||||
|
||||
✅ **无需 SSH** - MCP 工具直接在服务器上运行
|
||||
✅ **更简单** - 不需要配置 Runner、Webhook 等
|
||||
✅ **更直接** - 在 Cursor 中直接触发部署
|
||||
✅ **更灵活** - 可以直接访问服务器文件系统
|
||||
|
||||
## 安装步骤
|
||||
|
||||
### 1. 在服务器上安装 Bun
|
||||
|
||||
```bash
|
||||
# 安装 Bun
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# 验证安装
|
||||
bun --version
|
||||
```
|
||||
|
||||
### 2. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone <your-gitea-repo-url> /opt/cloud-mcp
|
||||
cd /opt/cloud-mcp
|
||||
```
|
||||
|
||||
### 3. 安装依赖
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
### 4. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp env.template .env
|
||||
nano .env # 编辑配置
|
||||
```
|
||||
|
||||
### 5. 运行 MCP 服务器
|
||||
|
||||
#### 方式一：直接运行（测试）
|
||||
|
||||
```bash
|
||||
bun run src/index.ts
|
||||
```
|
||||
|
||||
#### 方式二：使用 PM2（推荐）
|
||||
|
||||
```bash
|
||||
# 安装 PM2
|
||||
bun add -g pm2
|
||||
|
||||
# 启动服务
|
||||
pm2 start "bun run src/index.ts" --name cloud-mcp
|
||||
|
||||
# 设置开机自启
|
||||
pm2 save
|
||||
pm2 startup
|
||||
```
|
||||
|
||||
#### 方式三：使用 systemd（生产环境）
|
||||
|
||||
创建服务文件：
|
||||
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/cloud-mcp.service > /dev/null <<EOF
|
||||
[Unit]
|
||||
Description=Cloud MCP Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
WorkingDirectory=/opt/cloud-mcp
|
||||
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
|
||||
ExecStart=/usr/local/bin/bun run src/index.ts
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# 启用并启动服务
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable cloud-mcp
|
||||
sudo systemctl start cloud-mcp
|
||||
sudo systemctl status cloud-mcp
|
||||
```
|
||||
|
||||
## 在 Cursor 中配置 MCP
|
||||
|
||||
### 1. 配置 MCP 服务器
|
||||
|
||||
编辑 Cursor 的 MCP 配置（通常在 `~/.cursor/mcp.json` 或类似位置）：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"cloud-mcp": {
|
||||
"command": "ssh",
|
||||
"args": [
|
||||
"user@your-server",
|
||||
"cd /opt/cloud-mcp && bun run src/index.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**或者**，如果 MCP 服务器已经在运行，通过 stdio 连接：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"cloud-mcp": {
|
||||
"command": "ssh",
|
||||
"args": [
|
||||
"user@your-server",
|
||||
"bun run /opt/cloud-mcp/src/index.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用部署工具
|
||||
|
||||
配置完成后，在 Cursor 中可以直接使用：
|
||||
|
||||
- `deploy_update` - 拉取最新代码并重新部署
|
||||
- `deploy_status` - 查看部署状态
|
||||
- `deploy_logs` - 查看部署日志
|
||||
|
||||
## 部署流程
|
||||
|
||||
### 自动部署（通过 MCP 工具）
|
||||
|
||||
1. **在 Cursor 中**，直接调用 `deploy_update` 工具
|
||||
2. 工具会自动：
|
||||
- 拉取最新代码
|
||||
- 更新依赖（如果需要）
|
||||
- 重启服务
|
||||
|
||||
### 手动部署
|
||||
|
||||
```bash
|
||||
cd /opt/cloud-mcp
|
||||
git pull origin main
|
||||
bun install # 如果依赖有变化
|
||||
pm2 restart cloud-mcp # 或 systemctl restart cloud-mcp
|
||||
```
|
||||
|
||||
## 部署工具说明
|
||||
|
||||
### deploy_update
|
||||
|
||||
拉取最新代码并重新部署：
|
||||
|
||||
```
|
||||
参数：
|
||||
- branch: Git 分支（默认: main）
|
||||
- rebuild: 是否强制重建（默认: false）
|
||||
```
|
||||
|
||||
### deploy_status
|
||||
|
||||
查看当前部署状态：
|
||||
- Git 状态
|
||||
- 服务运行状态
|
||||
- 是否有未提交的更改
|
||||
|
||||
### deploy_logs
|
||||
|
||||
查看部署日志：
|
||||
- 参数：lines（显示行数，默认 50）
|
||||
|
||||
## 与 Docker 方案对比
|
||||
|
||||
| 特性 | 直接运行 | Docker |
|
||||
|------|---------|--------|
|
||||
| 部署复杂度 | ⭐ 简单 | ⭐⭐ 中等 |
|
||||
| 资源占用 | 较低 | 较高 |
|
||||
| 隔离性 | 较低 | 高 |
|
||||
| MCP 工具访问 | ✅ 直接访问 | ❌ 需要 SSH |
|
||||
| 适合场景 | 个人/小项目 | 生产环境 |
|
||||
|
||||
## 迁移 from Docker
|
||||
|
||||
如果之前使用 Docker，迁移步骤：
|
||||
|
||||
```bash
|
||||
# 1. 停止 Docker 容器
|
||||
docker-compose down
|
||||
|
||||
# 2. 备份数据
|
||||
cp -r data data.backup
|
||||
|
||||
# 3. 安装 Bun（如果还没有）
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# 4. 安装依赖
|
||||
cd /opt/cloud-mcp
|
||||
bun install
|
||||
|
||||
# 5. 启动服务（选择一种方式）
|
||||
# PM2
|
||||
pm2 start "bun run src/index.ts" --name cloud-mcp
|
||||
|
||||
# 或 systemd
|
||||
sudo systemctl start cloud-mcp
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### MCP 服务器无法启动
|
||||
|
||||
```bash
|
||||
# 检查 Bun 是否安装
|
||||
bun --version
|
||||
|
||||
# 检查依赖
|
||||
bun install
|
||||
|
||||
# 查看错误
|
||||
bun run src/index.ts
|
||||
```
|
||||
|
||||
### 部署工具执行失败
|
||||
|
||||
1. **检查 Git 仓库**：
|
||||
```bash
|
||||
cd /opt/cloud-mcp
|
||||
git status
|
||||
```
|
||||
|
||||
2. **检查权限**：
|
||||
```bash
|
||||
ls -la /opt/cloud-mcp
|
||||
chmod +x deploy-gitea.sh
|
||||
```
|
||||
|
||||
3. **检查服务状态**：
|
||||
```bash
|
||||
# PM2
|
||||
pm2 status
|
||||
|
||||
# systemd
|
||||
sudo systemctl status cloud-mcp
|
||||
```
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
# PM2 日志
|
||||
pm2 logs cloud-mcp
|
||||
|
||||
# systemd 日志
|
||||
sudo journalctl -u cloud-mcp -f
|
||||
|
||||
# 部署日志
|
||||
tail -f /opt/cloud-mcp/deploy.log
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **使用非 root 用户运行**（如果可能）：
|
||||
```bash
|
||||
sudo adduser mcpuser
|
||||
sudo chown -R mcpuser:mcpuser /opt/cloud-mcp
|
||||
```
|
||||
|
||||
2. **限制文件权限**：
|
||||
```bash
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
3. **定期更新**：
|
||||
```bash
|
||||
bun update
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- 配置自动备份
|
||||
- 设置监控告警
|
||||
- 优化性能配置
|
||||
|
||||
Reference in New Issue
Block a user