cloud-mcp/DEPLOY.md

部署文档

概述

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

前置要求

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

快速开始

1. 克隆项目到服务器

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

2. 配置环境变量

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

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

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

3. 创建数据目录

mkdir -p data

4. 首次部署

./deploy.sh --rebuild

部署方式

方式一：手动部署脚本

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

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

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

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

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

方式二：Gitea Webhook 自动部署

1. 配置部署脚本

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

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：

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 触发脚本：

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

4. 测试自动部署

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

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

Docker Compose 命令

基本操作

# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 查看日志
docker-compose logs -f

# 重启服务
docker-compose restart

# 查看状态
docker-compose ps

手动更新

# 拉取最新代码
git pull origin main

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

部署脚本命令

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

# 完整部署（默认）
./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 目录！

监控和维护

查看容器状态

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

查看日志

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

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

进入容器

docker exec -it cloud-mcp /bin/sh

清理资源

# 清理未使用的镜像
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 中添加资源限制：

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

回滚

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

# 查看提交历史
git log

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

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

支持

如有问题，请查看：

• 项目 README.md
• 测试文档：tests/README.md
• 日志文件：deploy.log