feat: 龙虾记忆同步系统完整版本
功能特性: - 文件树展示 - 差异对比 - 双向同步（本地 <-> 数据库） - 版本历史追踪 - 统计信息展示 核心补丁: 1. 分块读取与流式传输（防止大文件内存飙升） 2. .lobsterignore 机制（排除临时文件） 3. 操作溯源（Audit Log，记录同步历史） 技术栈: - 后端: Django + DRF + PostgreSQL - 前端: React + Ant Design - 部署: Docker + Docker Compose 项目已完整部署，可直接使用 docker-compose up -d 启动
This commit is contained in:
道童
707
README.md
Normal file
707
README.md
Normal file
@@ -0,0 +1,707 @@
|
||||
# 🦐 龙虾记忆同步系统
|
||||
|
||||
一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [项目概述](#项目概述)
|
||||
- [技术栈](#技术栈)
|
||||
- [功能特性](#功能特性)
|
||||
- [项目结构](#项目结构)
|
||||
- [快速开始](#快速开始)
|
||||
- [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！
|
||||
Reference in New Issue
Block a user