feat: Add deployment scripts, Docker configuration, and documentation for Cloud MCP project
This commit is contained in:
ethan.chen
308
DEPLOY.md
Normal file
308
DEPLOY.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# 部署文档
|
||||
|
||||
## 概述
|
||||
|
||||
本项目支持使用 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
|
||||
|
||||
Reference in New Issue
Block a user