# 🦐 龙虾记忆同步系统 一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。 ## 📋 目录 - [项目概述](#项目概述) - [技术栈](#技术栈) - [功能特性](#功能特性) - [项目结构](#项目结构) - [快速开始](#快速开始) - [API 文档](#api-文档) - [开发指南](#开发指南) - [部署说明](#部署说明) - [开发日志](#开发日志) ## 项目概述 龙虾记忆同步系统是一个专为 OpenClaw 龙虾设计的记忆文件管理工具，支持： - 扫描龙虾记忆目录 - 检查文件差异 - 双向同步（本地 ↔ 数据库） - 版本历史追踪 - 统计信息展示 ## 技术栈 ### 后端 - Django 4.x - Django REST Framework - PostgreSQL 15 - Python 3.11 ### 前端 - React 18 - Ant Design 5.x - react-diff-viewer-continued - Axios ### 部署 - Docker - Docker Compose - Nginx ## 功能特性 - ✅ **文件树展示**：可视化展示龙虾记忆文件结构 - ✅ **差异对比**：直观对比本地文件和数据库文件 - ✅ **双向同步**：支持本地→数据库和数据库→本地同步 - ✅ **版本历史**：追踪文件的修改历史 - ✅ **统计信息**：展示文件数量、大小等统计信息 - ✅ **REST API**：完整的 RESTful API 接口 ## 项目结构 ``` lobster-memory-sync/ ├── backend/ # Django 后端 │ ├── manage.py # Django 管理脚本 │ ├── requirements.txt # Python 依赖 │ ├── Dockerfile # 后端 Docker 配置 │ ├── memory_sync/ # Django 项目配置 │ │ ├── settings.py # 项目设置 │ │ ├── urls.py # 主路由 │ │ └── wsgi.py # WSGI 配置 │ └── memory_app/ # 核心应用 │ ├── models.py # 数据模型 │ ├── serializers.py # 序列化器 │ ├── views.py # 视图 │ ├── urls.py # 应用路由 │ └── services.py # 业务逻辑 ├── frontend/ # React 前端 │ ├── package.json # Node 依赖 │ ├── Dockerfile # 前端 Docker 配置 │ ├── public/ # 静态资源 │ └── src/ # 源代码 │ ├── api/ # API 客户端 │ │ └── index.js │ ├── components/ # React 组件 │ │ ├── FileTree.js # 文件树 │ │ └── FileDiff.js # 差异对比 │ ├── App.js # 主应用 │ └── index.js # 入口文件 ├── docker-compose.yml # Docker Compose 配置 ├── README.md # 项目文档 └── DEPLOY.md # 部署文档 ``` ## 快速开始 ### 前置条件 - Docker - Docker Compose - 端口占用检查：8086（前端）、8087（后端）、5432（数据库） ### 一键启动 ```bash # 克隆项目 cd /home/node/.openclaw/workspace/daotong/lobster-memory-sync # 启动服务 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down ``` ### 访问地址 - 前端：http://localhost:8086 - 后端 API：http://localhost:8087/api/ - PostgreSQL：localhost:5432 ## API 文档 ### 扫描文件 ``` GET /api/scan/?lobster_id=daotong ``` **响应示例：** ```json { "files": [ { "name": "MEMORY.md", "path": "MEMORY.md", "type": "file", "size": 1234, "last_modified": "2026-04-05T12:00:00Z" } ] } ``` ### 检查同步状态 ``` GET /api/status/?lobster_id=daotong&file_path=MEMORY.md ``` **响应示例：** ```json { "synced": false, "has_difference": true, "difference": "+ 新增内容\n- 删除内容" } ``` ### 获取文件差异 ``` GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md ``` ### 同步到数据库 ``` POST /api/sync/db/ Content-Type: application/json { "lobster_id": "daotong", "file_path": "MEMORY.md" } ``` ### 同步到本地 ``` POST /api/sync/local/ Content-Type: application/json { "lobster_id": "daotong", "file_path": "MEMORY.md" } ``` ## 开发指南 ### 后端开发 ```bash # 进入后端容器 docker exec -it lobster-backend bash # 创建迁移 python manage.py makemigrations memory_app python manage.py migrate # 创建超级用户 python manage.py createsuperuser # 运行开发服务器 python manage.py runserver 0.0.0.0:8087 ``` ### 前端开发 ```bash # 本地开发（不使用 Docker） cd frontend npm install npm start # 构建生产版本 npm run build ``` ## 🚀 部署指南 ### 系统要求 - **操作系统**: Linux / macOS / Windows (WSL2) - **Docker**: 20.10 或更高版本 - **Docker Compose**: 2.0 或更高版本 - **内存**: 最少 2GB RAM - **磁盘**: 最少 5GB 可用空间 - **端口**: 8086（前端）、8087（后端）、5432（数据库） ### 环境准备 #### 1. 安装 Docker **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 backend # 检查端口占用 sudo netstat -tulpn | grep -E '8086|8087|5432' # 重新构建镜像 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**: 项目初始化 - 完成后端核心功能（Django + DRF + PostgreSQL） - 完成前端核心功能（React + Ant Design） - 完成部署配置（Docker Compose） - 推送到 Git 仓库：https://xjp.datalibstar.com/daotong/lobster-memory-sync.git ## 📝 License MIT ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！