openclaw-memory/README.md

# 🦐 龙虾记忆同步系统

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

## 📋 目录

- [项目概述](#项目概述)
- [技术栈](#技术栈)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [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！