cloud-mcp/DEPLOY.md

# 部署文档

## 概述

本项目支持使用 Docker 进行部署，可以通过手动脚本或 Gitea Webhook 自动部署。

## 前置要求

- Docker 和 Docker Compose 已安装
- Git 已安装
- 服务器有足够的资源（建议至少 512MB 内存）

## 快速开始

### 1. 克隆项目到服务器

```bash
git clone <your-gitea-repo-url> /path/to/cloud-mcp
cd /path/to/cloud-mcp
```

### 2. 配置环境变量

复制环境变量模板并编辑：

```bash
cp env.template .env
nano .env  # 或使用你喜欢的编辑器
```

配置必要的环境变量（NAS、服务器、路由器等）。

### 3. 创建数据目录

```bash
mkdir -p data
```

### 4. 首次部署

```bash
./deploy.sh --rebuild
```

## 部署方式

### 方式一：手动部署脚本

使用 `deploy.sh` 脚本进行手动部署：

```bash
# 基本部署（使用缓存）
./deploy.sh

# 从 Git 拉取最新代码并部署
./deploy.sh --pull

# 强制重新构建（不使用缓存）
./deploy.sh --rebuild

# 拉取代码并重新构建
./deploy.sh --pull --rebuild
```

### 方式二：Gitea Webhook 自动部署

#### 1. 配置部署脚本

编辑 `deploy-gitea.sh`，更新以下变量：

```bash
PROJECT_DIR="/path/to/cloud-mcp"  # 你的项目路径
BRANCH="main"  # 或 "master"
```

#### 2. 在 Gitea 中配置 Webhook

1. 进入仓库：**Settings** -> **Webhooks** -> **Add Webhook**
2. 配置如下：
   - **Target URL**: `http://your-server:port/gitea-webhook` (如果使用 webhook 服务器)
   - 或者直接在服务器上设置 Git Hook
3. **Content Type**: `application/json`
4. **Secret**: (可选) 设置一个密钥
5. **Events**: 选择 `Push` 事件

#### 3. 设置 Git Hook（推荐）

在服务器上设置 Git post-receive hook：

```bash
cd /path/to/cloud-mcp/.git/hooks
cat > post-receive << 'EOF'
#!/bin/bash
cd /path/to/cloud-mcp
/path/to/cloud-mcp/deploy-gitea.sh
EOF
chmod +x post-receive
```

或者使用 Gitea 的 Webhook 触发脚本：

```bash
# 安装 webhook 服务器（如 webhook）
# 然后配置 webhook 调用 deploy-gitea.sh
```

#### 4. 测试自动部署

```bash
# 在本地推送代码
git push origin main

# 在服务器上查看日志
tail -f /path/to/cloud-mcp/deploy.log
```

## Docker Compose 命令

### 基本操作

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart

# 查看状态
docker-compose ps
```

### 手动更新

```bash
# 拉取最新代码
git pull origin main

# 重新构建并启动
docker-compose build --no-cache
docker-compose up -d
```

## 部署脚本命令

`deploy-gitea.sh` 支持多种操作：

```bash
# 完整部署（默认）
./deploy-gitea.sh

# 仅拉取代码
./deploy-gitea.sh --pull-only

# 重新构建
./deploy-gitea.sh --rebuild

# 查看状态
./deploy-gitea.sh --status

# 查看日志
./deploy-gitea.sh --logs

# 停止服务
./deploy-gitea.sh --stop

# 启动服务
./deploy-gitea.sh --start

# 重启服务
./deploy-gitea.sh --restart
```

## 数据持久化

数据存储在 `./data` 目录，通过 Docker volume 挂载：

- 代码片段：`data/codeSnippets.json`
- 笔记：`data/notes.json`
- 任务：`data/tasks.json`
- 其他数据文件...

**重要**：定期备份 `data` 目录！

## 监控和维护

### 查看容器状态

```bash
docker ps --filter "name=cloud-mcp"
```

### 查看日志

```bash
# 实时日志
docker logs -f cloud-mcp

# 最近 100 行
docker logs --tail 100 cloud-mcp
```

### 进入容器

```bash
docker exec -it cloud-mcp /bin/sh
```

### 清理资源

```bash
# 清理未使用的镜像
docker image prune -f

# 清理未使用的容器和网络
docker system prune -f
```

## 故障排查

### 容器无法启动

1. 检查日志：`docker logs cloud-mcp`
2. 检查环境变量：确保 `.env` 文件配置正确
3. 检查端口冲突：确保没有其他服务占用端口
4. 检查磁盘空间：`df -h`

### 数据丢失

1. 检查 volume 挂载：`docker inspect cloud-mcp | grep Mounts`
2. 检查数据目录权限
3. 从备份恢复数据

### 自动部署不工作

1. 检查 webhook 配置
2. 检查脚本权限：`chmod +x deploy-gitea.sh`
3. 检查日志：`tail -f deploy.log`
4. 手动测试脚本：`./deploy-gitea.sh --status`

## 安全建议

1. **不要将 `.env` 文件提交到 Git**
2. 使用强密码和 SSH 密钥
3. 定期更新 Docker 镜像
4. 限制服务器访问权限
5. 使用防火墙限制端口访问
6. 定期备份数据

## 性能优化

1. **资源限制**：在 `docker-compose.yml` 中添加资源限制：

```yaml
services:
  cloud-mcp:
    # ...
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M
```

2. **日志轮转**：配置 Docker 日志驱动限制日志大小

3. **健康检查**：已包含在 `docker-compose.yml` 中

## 更新流程

### 开发流程

1. 在本地开发并测试
2. 提交代码到 Git
3. 推送到 Gitea 仓库
4. Webhook 自动触发部署（如果配置）
5. 或手动运行 `./deploy-gitea.sh`

### 回滚

如果需要回滚到之前的版本：

```bash
# 查看提交历史
git log

# 回滚到指定提交
git checkout <commit-hash>

# 重新部署
./deploy-gitea.sh --rebuild
```

## 支持

如有问题，请查看：
- 项目 README.md
- 测试文档：tests/README.md
- 日志文件：deploy.log