docs: 添加详细的部署指南

- 系统要求说明 - Docker 安装步骤（Ubuntu/CentOS/macOS） - 环境变量配置 - 详细安装部署流程 - 部署验证步骤 - 生产环境配置（Nginx/HTTPS/备份） - 更新部署流程 - 监控与维护命令 - 完整故障排查指南 - 卸载步骤 - 常见问题 FAQ
2026-04-05 12:15:48 +00:00
parent 7cd91c90d7
commit d9420b6cc6
1 changed files with 463 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -215,32 +215,481 @@ npm start
 npm run build
 ```
-## 部署说明
+## 🚀 部署指南
-详细部署文档请参考 [DEPLOY.md](DEPLOY.md)
+### 系统要求
-### 生产环境部署
+- **操作系统**: Linux / macOS / Windows (WSL2)
 - **Docker**: 20.10 或更高版本
 - **Docker Compose**: 2.0 或更高版本
 - **内存**: 最少 2GB RAM
 - **磁盘**: 最少 5GB 可用空间
 - **端口**: 8086（前端）、8087（后端）、5432（数据库）
-1. 修改 `docker-compose.yml` 中的环境变量
+### 环境准备
-2. 配置 Nginx 反向代理
+
-3. 启用 HTTPS
+#### 1. 安装 Docker
-4. 配置数据库备份
+
 **Ubuntu / Debian:**
 ```bash
 # 更新包索引
 sudo apt-get update
 # 安装依赖
 sudo apt-get install -y ca-certificates curl gnupg lsb-release
 # 添加 Docker 官方 GPG key
 sudo mkdir -p /etc/apt/keyrings
 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
 # 添加 Docker 仓库
 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 # 安装 Docker
 sudo apt-get update
 sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
 # 验证安装
 docker --version
 docker compose version
 ```
 **CentOS / RHEL:**
 ```bash
 # 安装依赖
 sudo yum install -y yum-utils device-mapper-persistent-data lvm2
 # 添加 Docker 仓库
 sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
 # 安装 Docker
 sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
 # 启动 Docker
 sudo systemctl start docker
 sudo systemctl enable docker
 ```
 **macOS:**
 ```bash
 # 使用 Homebrew 安装
 brew install --cask docker
 # 启动 Docker Desktop
 open -a Docker
 ```
 #### 2. 配置 Docker 用户组（可选）
 ```bash
 # 将当前用户添加到 docker 组
 sudo usermod -aG docker $USER
 # 重新登录或运行
 newgrp docker
 # 验证
 docker ps
 ```
 ### 安装部署
 #### 1. 克隆项目
 ```bash
 # 克隆仓库
 git clone https://xjp.datalibstar.com/daotong/lobster-memory-sync.git
 cd lobster-memory-sync
 ```
 #### 2. 配置环境变量
 创建 `.env` 文件（可选，用于覆盖默认配置）：
 ```bash
 # 数据库配置
 DB_NAME=lobster_memory
 DB_USER=postgres
 DB_PASSWORD=your_secure_password
 # 龙虾记忆目录路径
 LOBSTER_MEMORY_BASE=/path/to/lobster/memory
 # 前端配置
 REACT_APP_API_URL=http://localhost:8087/api
 # 端口配置
 FRONTEND_PORT=8086
 BACKEND_PORT=8087
 POSTGRES_PORT=5432
 ```
 #### 3. 修改 docker-compose.yml
 根据实际环境修改以下配置：
 ```yaml
 services:
  backend:
    volumes:
      # 挂载龙虾记忆目录（只读）
      - /home/node/.openclaw/workspace/daotong:/app/memory_files:ro
 ```
 **注意事项：**
 - 将 `/home/node/.openclaw/workspace/daotong` 替换为实际的龙虾记忆目录路径
 - 使用 `:ro` 只读挂载，确保安全性
 #### 4. 构建并启动服务
 ```bash
 # 构建镜像
 docker-compose build
 # 启动所有服务（后台运行）
 docker-compose up -d
 # 查看服务状态
 docker-compose ps
 # 查看日志
 docker-compose logs -f
 ```
 #### 5. 初始化数据库
 ```bash
 # 等待数据库启动
 sleep 10
 # 执行数据库迁移
 docker-compose exec backend python manage.py migrate
 # 创建超级用户（可选）
 docker-compose exec backend python manage.py createsuperuser
 ```
 ### 验证部署
 #### 1. 检查服务状态
 ```bash
 # 查看所有容器状态
 docker-compose ps
 # 预期输出：
 # NAME                    STATUS
 # lobster-postgres        Up
 # lobster-backend         Up
 # lobster-frontend        Up
 ```
 #### 2. 测试后端 API
 ```bash
 # 测试 API 健康检查
 curl http://localhost:8087/api/
 # 测试文件扫描
 curl "http://localhost:8087/api/scan/?lobster_id=daotong"
 ```
 #### 3. 访问前端
 打开浏览器访问：
 - http://localhost:8086
 **预期效果：**
 - 能够看到文件树展示
 - 能够点击文件查看差异对比
 - 能够执行同步操作
 ### 生产环境配置
 #### 1. 使用环境变量文件
 创建 `.env.production` 文件：
 ```bash
 # 生产环境配置
 DB_NAME=lobster_memory_prod
 DB_USER=postgres
 DB_PASSWORD=<强密码>
 DB_HOST=postgres
 # 龙虾记忆目录
 LOBSTER_MEMORY_BASE=/var/lib/lobster/memory
 # 前端 API 地址
 REACT_APP_API_URL=https://api.yourdomain.com/api
 # 端口配置
 FRONTEND_PORT=8086
 BACKEND_PORT=8087
 POSTGRES_PORT=5432
 ```
 #### 2. 配置 Nginx 反向代理
 创建 `nginx.conf`：
 ```nginx
 upstream backend {
    server localhost:8087;
 }
 upstream frontend {
    server localhost:8086;
 }
 server {
    listen 80;
    server_name yourdomain.com;
    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
 }
 server {
    listen 443 ssl http2;
    server_name yourdomain.com;
    # SSL 证书配置
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    # 前端静态资源
    location / {
        proxy_pass http://frontend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    # 后端 API
    location /api/ {
        proxy_pass http://backend/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 #### 3. 启用 HTTPS
 使用 Let's Encrypt 获取免费 SSL 证书：
 ```bash
 # 安装 certbot
 sudo apt-get install certbot python3-certbot-nginx
 # 获取证书
 sudo certbot --nginx -d yourdomain.com
 # 自动续期
 sudo certbot renew --dry-run
 ```
 #### 4. 配置数据库备份
 创建备份脚本 `backup.sh`：
 ```bash
 #!/bin/bash
 BACKUP_DIR="/var/backups/lobster-memory"
 DATE=$(date +%Y%m%d_%H%M%S)
 BACKUP_FILE="$BACKUP_DIR/backup_$DATE.sql"
 # 创建备份目录
 mkdir -p $BACKUP_DIR
 # 执行备份
 docker-compose exec -T postgres pg_dump -U postgres lobster_memory > $BACKUP_FILE
 # 压缩备份
 gzip $BACKUP_FILE
 # 删除 7 天前的备份
 find $BACKUP_DIR -name "backup_*.sql.gz" -mtime +7 -delete
 echo "Backup completed: ${BACKUP_FILE}.gz"
 ```
 添加定时任务：
 ```bash
 # 编辑 crontab
 crontab -e
 # 每天凌晨 2 点执行备份
 0 2 * * * /path/to/backup.sh
 ```
 ### 更新部署
 #### 1. 拉取最新代码
 ```bash
 git pull origin master
 ```
 #### 2. 重新构建镜像
 ```bash
 docker-compose build
 ```
 #### 3. 重启服务
 ```bash
 docker-compose up -d
 ```
 #### 4. 执行数据库迁移（如有）
 ```bash
 docker-compose exec backend python manage.py migrate
 ```
 ### 监控与维护
 #### 查看服务日志
 ```bash
 # 查看所有服务日志
 docker-compose logs -f
 # 查看特定服务日志
 docker-compose logs -f backend
 docker-compose logs -f frontend
 docker-compose logs -f postgres
 # 查看最近 100 行日志
 docker-compose logs --tail=100 backend
 ```
 #### 查看资源使用
 ```bash
 # 查看容器资源使用情况
 docker stats
 # 查看磁盘使用
 docker system df
 # 清理未使用的资源
 docker system prune -a
 ```
 #### 数据库维护
 ```bash
 # 进入数据库容器
 docker-compose exec postgres psql -U postgres -d lobster_memory
 # 备份数据库
 docker-compose exec postgres pg_dump -U postgres lobster_memory > backup.sql
 # 恢复数据库
 docker-compose exec -T postgres psql -U postgres lobster_memory < backup.sql
 ```
 ### 故障排查
 #### 问题 1：容器启动失败
 ```bash
-# 查看日志
+# 查看容器日志
-docker-compose logs -f backend
+docker-compose logs backend
 docker-compose logs -f frontend
-# 重启服务
+# 检查端口占用
-docker-compose restart
+sudo netstat -tulpn | grep -E '8086|8087|5432'
-# 清理数据
+# 重新构建镜像
-docker-compose down -v
+docker-compose build --no-cache
 docker-compose up -d
 ```
 #### 问题 2：数据库连接失败
 ```bash
 # 检查数据库容器状态
 docker-compose ps postgres
 # 查看数据库日志
 docker-compose logs postgres
 # 测试数据库连接
 docker-compose exec postgres psql -U postgres -d lobster_memory -c "SELECT version();"
 ```
 #### 问题 3：前端无法访问后端 API
 ```bash
 # 检查后端服务状态
 curl http://localhost:8087/api/
 # 检查前端配置
 docker-compose logs frontend
 # 验证环境变量
 docker-compose exec frontend env | grep REACT_APP_API_URL
 ```
 #### 问题 4：文件扫描失败
 ```bash
 # 检查龙虾记忆目录挂载
 docker-compose exec backend ls -la /app/memory_files
 # 检查目录权限
 ls -ld /home/node/.openclaw/workspace/daotong
 # 重新挂载
 docker-compose down
 docker-compose up -d
 ```
 ### 卸载
 ```bash
 # 停止并删除容器
 docker-compose down
 # 删除数据卷
 docker-compose down -v
 # 删除镜像
 docker rmi lobster-memory-sync-backend lobster-memory-sync-frontend
 # 删除项目目录
 cd ..
 rm -rf lobster-memory-sync
 ```
 ### 常见问题 (FAQ)
 **Q: 如何修改默认端口？**
 A: 在 `docker-compose.yml` 中修改对应的端口映射，例如：
 ```yaml
 frontend:
  ports:
    - "9086:80"  # 将 8086 改为 9086
 ```
 **Q: 如何使用外部数据库？**
 A: 修改 `docker-compose.yml` 中的 `backend` 服务配置，移除 `postgres` 服务并设置 `DB_HOST` 环境变量。
 **Q: 如何扩展存储空间？**
 A: 修改 `docker-compose.yml` 中的 `postgres_data` 卷配置，或使用外部存储卷。
 **Q: 如何配置多实例部署？**
 A: 使用 Docker Swarm 或 Kubernetes 进行集群部署，配置负载均衡器分发请求。
 ## 开发日志
 - **2026-04-05**: 项目初始化