docs: 完善项目 README 文档
- 添加项目概述和详细说明 - 完善技术栈介绍 - 添加功能特性列表 - 添加项目结构图 - 添加快速开始指南 - 完善 API 文档 - 添加开发指南 - 添加部署说明
This commit is contained in:
道童
256
README.md
256
README.md
@@ -1,22 +1,258 @@
|
|||||||
# 🦐 龙虾记忆同步系统
|
# 🦐 龙虾记忆同步系统
|
||||||
|
|
||||||
|
一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。
|
||||||
|
|
||||||
|
## 📋 目录
|
||||||
|
|
||||||
|
- [项目概述](#项目概述)
|
||||||
|
- [技术栈](#技术栈)
|
||||||
|
- [功能特性](#功能特性)
|
||||||
|
- [项目结构](#项目结构)
|
||||||
|
- [快速开始](#快速开始)
|
||||||
|
- [API 文档](#api-文档)
|
||||||
|
- [开发指南](#开发指南)
|
||||||
|
- [部署说明](#部署说明)
|
||||||
|
- [开发日志](#开发日志)
|
||||||
|
|
||||||
## 项目概述
|
## 项目概述
|
||||||
|
|
||||||
一个用于同步和管理龙虾记忆文件的前后端分离系统。
|
龙虾记忆同步系统是一个专为 OpenClaw 龙虾设计的记忆文件管理工具，支持：
|
||||||
|
- 扫描龙虾记忆目录
|
||||||
|
- 检查文件差异
|
||||||
|
- 双向同步（本地 ↔ 数据库）
|
||||||
|
- 版本历史追踪
|
||||||
|
- 统计信息展示
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
|
|
||||||
- **后端**: Django + Django REST Framework + PostgreSQL
|
### 后端
|
||||||
- **前端**: React + Ant Design
|
- Django 4.x
|
||||||
- **版本控制**: Git
|
- 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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 部署说明
|
||||||
|
|
||||||
|
详细部署文档请参考 [DEPLOY.md](DEPLOY.md)
|
||||||
|
|
||||||
|
### 生产环境部署
|
||||||
|
|
||||||
|
1. 修改 `docker-compose.yml` 中的环境变量
|
||||||
|
2. 配置 Nginx 反向代理
|
||||||
|
3. 启用 HTTPS
|
||||||
|
4. 配置数据库备份
|
||||||
|
|
||||||
|
### 故障排查
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 查看日志
|
||||||
|
docker-compose logs -f backend
|
||||||
|
docker-compose logs -f frontend
|
||||||
|
|
||||||
|
# 重启服务
|
||||||
|
docker-compose restart
|
||||||
|
|
||||||
|
# 清理数据
|
||||||
|
docker-compose down -v
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
## 开发日志
|
## 开发日志
|
||||||
|
|
||||||
- 2026-04-05: 项目初始化
|
- **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