309 lines
5.3 KiB
Markdown
309 lines
5.3 KiB
Markdown
# 部署文档
|
||
|
||
## 概述
|
||
|
||
本项目支持使用 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
|
||
|