Files

- 系统要求说明
- Docker 安装步骤（Ubuntu/CentOS/macOS）
- 环境变量配置
- 详细安装部署流程
- 部署验证步骤
- 生产环境配置（Nginx/HTTPS/备份）
- 更新部署流程
- 监控与维护命令
- 完整故障排查指南
- 卸载步骤
- 常见问题 FAQ

2026-04-05 12:15:48 +00:00

14 KiB

Raw Permalink Blame History

🦐 龙虾记忆同步系统

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

📋 目录

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

🚀 部署指南

系统要求

操作系统: Linux / macOS / Windows (WSL2)
Docker: 20.10 或更高版本
Docker Compose: 2.0 或更高版本
内存: 最少 2GB RAM
磁盘: 最少 5GB 可用空间
端口: 8086（前端）、8087（后端）、5432（数据库）

环境准备

1. 安装 Docker

Ubuntu / Debian:

# 更新包索引
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:

# 安装依赖
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:

# 使用 Homebrew 安装
brew install --cask docker

# 启动 Docker Desktop
open -a Docker

2. 配置 Docker 用户组（可选）

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 重新登录或运行
newgrp docker

# 验证
docker ps

安装部署

1. 克隆项目

# 克隆仓库
git clone https://xjp.datalibstar.com/daotong/lobster-memory-sync.git
cd lobster-memory-sync

2. 配置环境变量

创建 .env 文件（可选，用于覆盖默认配置）：

# 数据库配置
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

根据实际环境修改以下配置：

services:
  backend:
    volumes:
      # 挂载龙虾记忆目录（只读）
      - /home/node/.openclaw/workspace/daotong:/app/memory_files:ro

注意事项：

将 /home/node/.openclaw/workspace/daotong 替换为实际的龙虾记忆目录路径
使用 :ro 只读挂载，确保安全性

4. 构建并启动服务

# 构建镜像
docker-compose build

# 启动所有服务（后台运行）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

5. 初始化数据库

# 等待数据库启动
sleep 10

# 执行数据库迁移
docker-compose exec backend python manage.py migrate

# 创建超级用户（可选）
docker-compose exec backend python manage.py createsuperuser

验证部署

1. 检查服务状态

# 查看所有容器状态
docker-compose ps

# 预期输出：
# NAME                    STATUS
# lobster-postgres        Up
# lobster-backend         Up
# lobster-frontend        Up

2. 测试后端 API

# 测试 API 健康检查
curl http://localhost:8087/api/

# 测试文件扫描
curl "http://localhost:8087/api/scan/?lobster_id=daotong"

3. 访问前端

打开浏览器访问：

http://localhost:8086

预期效果：

能够看到文件树展示
能够点击文件查看差异对比
能够执行同步操作

生产环境配置

1. 使用环境变量文件

创建 .env.production 文件：

# 生产环境配置
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：

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 证书：

# 安装 certbot
sudo apt-get install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d yourdomain.com

# 自动续期
sudo certbot renew --dry-run

4. 配置数据库备份

创建备份脚本 backup.sh：

#!/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"

添加定时任务：

# 编辑 crontab
crontab -e

# 每天凌晨 2 点执行备份
0 2 * * * /path/to/backup.sh

更新部署

1. 拉取最新代码

git pull origin master

2. 重新构建镜像

docker-compose build

3. 重启服务

docker-compose up -d

4. 执行数据库迁移（如有）

docker-compose exec backend python manage.py migrate

监控与维护

查看服务日志

# 查看所有服务日志
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

查看资源使用

# 查看容器资源使用情况
docker stats

# 查看磁盘使用
docker system df

# 清理未使用的资源
docker system prune -a

数据库维护

# 进入数据库容器
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：容器启动失败

# 查看容器日志
docker-compose logs backend

# 检查端口占用
sudo netstat -tulpn | grep -E '8086|8087|5432'

# 重新构建镜像
docker-compose build --no-cache
docker-compose up -d

问题 2：数据库连接失败

# 检查数据库容器状态
docker-compose ps postgres

# 查看数据库日志
docker-compose logs postgres

# 测试数据库连接
docker-compose exec postgres psql -U postgres -d lobster_memory -c "SELECT version();"

问题 3：前端无法访问后端 API

# 检查后端服务状态
curl http://localhost:8087/api/

# 检查前端配置
docker-compose logs frontend

# 验证环境变量
docker-compose exec frontend env | grep REACT_APP_API_URL

问题 4：文件扫描失败

# 检查龙虾记忆目录挂载
docker-compose exec backend ls -la /app/memory_files

# 检查目录权限
ls -ld /home/node/.openclaw/workspace/daotong

# 重新挂载
docker-compose down
docker-compose up -d

卸载

# 停止并删除容器
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 中修改对应的端口映射，例如：

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！

14 KiB Raw Permalink Blame History Unescape Escape