lobster-memory-sync/README.md

🦐 龙虾记忆同步系统

一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。

📋 目录

• 项目概述
• 技术栈
• 功能特性
• 项目结构
• 快速开始
• 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（数据库）

一键启动

# 克隆项目
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

响应示例：

{
  "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

响应示例：

{
  "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"
}

开发指南

后端开发

# 进入后端容器
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

前端开发

# 本地开发（不使用 Docker）
cd frontend
npm install
npm start

# 构建生产版本
npm run build

部署说明

详细部署文档请参考 DEPLOY.md

生产环境部署

1. 修改 docker-compose.yml 中的环境变量
2. 配置 Nginx 反向代理
3. 启用 HTTPS
4. 配置数据库备份

故障排查

# 查看日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 重启服务
docker-compose restart

# 清理数据
docker-compose down -v
docker-compose up -d

开发日志

• 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！