5eb24ed3e2
更新内容： 1. README.md - 重新组织文档结构 - 新增核心特性详细说明 - 新增完整 API 文档 - 新增常见问题 FAQ - 新增 .lobsterignore 管理接口文档 - 简化快速开始流程 - 突出丝滑前端体验 2. DEPLOY.md（全新部署文档） - 完整的系统要求（最低/推荐配置） - 详细的环境准备（Docker、Git、Nginx） - 快速部署指南 - 生产环境部署（Nginx + HTTPS） - 数据库管理（连接、SQL 命令、性能优化） - 监控与维护（日志、资源使用、健康检查） - 完整的故障排查指南（5 个常见问题） - 备份与恢复（数据库备份、配置备份） - 性能优化（数据库、Nginx、Docker） - 安全加固（密码更新、防火墙、SELinux） - 维护清单（每日/每周/每月） 文档特点： - 结构清晰，易于查找 - 命令示例完整，可直接复制使用 - 包含生产环境最佳实践 - 覆盖常见问题和解决方案
378 lines
9.6 KiB
Markdown
378 lines
9.6 KiB
Markdown
# 🦐 龙虾记忆同步系统
|
||
|
||
一个专为 OpenClaw 龙虾设计的记忆文件管理系统，提供文件树展示、差异对比、双向同步和属性管理功能。
|
||
|
||
## ✨ 核心特性
|
||
|
||
- ✅ **分块流式处理**：8KB 分块读取，内存限制 256MB，支持大文件处理
|
||
- ✅ **.lobsterignore 支持**：正则表达式匹配，过滤不需要同步的文件
|
||
- ✅ **智能差异对比**：行级差异，颜色区分，支持大文件截断
|
||
- ✅ **属性目录结构**：支持嵌套属性键值对（如 `author.name`, `metadata.tags`）
|
||
- ✅ **完整审计日志**：记录操作人、数据源、变动行数、执行时间
|
||
- ✅ **语义摘要**：自动生成文件内容摘要
|
||
- ✅ **冲突判定**：识别 HARD_CONFLICT 状态，智能判断严重冲突
|
||
- ✅ **丝滑前端**：Ant Design 树形控件，点选-对比-同步流程
|
||
|
||
## 📋 目录
|
||
|
||
- [快速开始](#快速开始)
|
||
- [功能特性](#功能特性)
|
||
- [技术架构](#技术架构)
|
||
- [项目结构](#项目结构)
|
||
- [API 文档](#api-文档)
|
||
- [部署指南](#部署指南)
|
||
- [开发指南](#开发指南)
|
||
- [常见问题](#常见问题)
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Docker 20.10+
|
||
- Docker Compose 2.0+
|
||
- 端口：8086（前端）、8087（后端）、5432（数据库）
|
||
|
||
### 一键启动
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone http://10.2.0.100:8989/daotong/lobster-memory-sync.git
|
||
cd lobster-memory-sync
|
||
|
||
# 启动服务
|
||
docker-compose up -d
|
||
|
||
# 执行数据库迁移
|
||
docker-compose exec backend python manage.py migrate
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
```
|
||
|
||
### 访问应用
|
||
|
||
- 📱 前端：http://localhost:8086
|
||
- 📡 后端 API：http://localhost:8087/api/
|
||
- 🗄️ PostgreSQL：localhost:5432
|
||
|
||
## 🎯 功能特性
|
||
|
||
### 1. 分块流式处理
|
||
- **ChunkedReadStream**：8KB 分块读取，避免大文件内存问题
|
||
- **内存限制**：最大 256MB 缓存，自动清理
|
||
- **流式哈希**：无需加载完整内容即可计算哈希
|
||
- **智能对比**：大文件只对比头尾，中间部分计算哈希
|
||
|
||
### 2. .lobsterignore 支持
|
||
- **正则表达式**：`re:.*\.log$` 匹配日志文件
|
||
- **通配符**：`*.pyc`, `node_modules/` 匹配目录和文件
|
||
- **默认规则**：自动过滤 `.git`, `__pycache__`, `.DS_Store` 等
|
||
|
||
### 3. 属性目录结构
|
||
- **嵌套属性**：使用点号分隔的键名（`author.name`, `metadata.tags`）
|
||
- **类型支持**：string, integer, float, boolean, json
|
||
- **分类管理**：支持属性分类和元数据
|
||
- **索引优化**：快速查询属性
|
||
|
||
### 4. 审计日志
|
||
- **完整记录**：操作人、操作时间、数据源、变动行数
|
||
- **变更追踪**：属性变更记录
|
||
- **执行时间**：精确到毫秒
|
||
- **历史查询**：支持按文件、操作类型查询
|
||
|
||
### 5. 冲突判定
|
||
- **7 种状态**：consistent, local_newer, db_newer, conflict, hard_conflict, local_only, db_only
|
||
- **HARD_CONFLICT**：版本 > 1 且 1 小时内更新
|
||
- **智能判断**：基于版本号和时间戳
|
||
|
||
### 6. 丝滑前端
|
||
- **Ant Design**：现代化 UI 组件库
|
||
- **文件树**：直观的树形控件，状态标签
|
||
- **差异对比**：绿色（新增）、红色（删除），行级差异
|
||
- **一键同步**：同步到本地 / 同步到数据库
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 后端
|
||
- **框架**：Django 4.x + Django REST Framework
|
||
- **数据库**：PostgreSQL 15
|
||
- **内存管理**：ChunkedReadStream（256MB 限制）
|
||
- **Python**：3.11
|
||
|
||
### 前端
|
||
- **框架**：React 18
|
||
- **UI 库**：Ant Design 5.x
|
||
- **差异对比**：diff + react-syntax-highlighter
|
||
- **HTTP 客户端**：Axios
|
||
|
||
### 部署
|
||
- **容器**：Docker + Docker Compose
|
||
- **反向代理**：Nginx
|
||
- **SSL**：Let's Encrypt
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
lobster-memory-sync/
|
||
├── backend/ # Django 后端
|
||
│ ├── memory_app/
|
||
│ │ ├── chunked_stream.py # 流式读取器（内存限制 256MB）
|
||
│ │ ├── models.py # 数据模型（LobsterMemory, FileAttribute, SyncHistory）
|
||
│ │ ├── services.py # 业务逻辑
|
||
│ │ ├── views.py # API 视图
|
||
│ │ ├── serializers.py # 序列化器
|
||
│ │ └── migrations/ # 数据库迁移
|
||
│ │ ├── 0001_initial.py
|
||
│ │ ├── 0002_add_summary_and_audit_fields.py
|
||
│ │ └── 0003_add_file_attribute.py
|
||
│ ├── memory_sync/
|
||
│ │ ├── settings.py # Django 配置
|
||
│ │ ├── urls.py # 主路由
|
||
│ │ └── wsgi.py # WSGI 配置
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ ├── Dockerfile # 后端 Docker 配置
|
||
│ ├── manage.py # Django 管理脚本
|
||
│ └── test_simple.py # 功能测试脚本
|
||
├── frontend/ # React 前端
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ │ ├── FileTree.js # 文件树组件
|
||
│ │ │ └── FileDiff.js # 差异对比组件
|
||
│ │ ├── api/
|
||
│ │ │ └── index.js # API 客户端
|
||
│ │ ├── App.js # 主应用
|
||
│ │ └── index.js # 入口文件
|
||
│ ├── package.json # Node 依赖
|
||
│ └── Dockerfile # 前端 Docker 配置
|
||
├── docker-compose.yml # Docker Compose 配置
|
||
├── .lobsterignore.example # .lobsterignore 示例
|
||
├── README.md # 项目文档
|
||
├── DEPLOY.md # 详细部署文档
|
||
├── CHANGELOG.md # 变更日志
|
||
└── .gitignore # Git 忽略规则
|
||
```
|
||
|
||
## 📡 API 文档
|
||
|
||
### 文件扫描
|
||
|
||
```http
|
||
GET /api/scan/?lobster_id=daotong
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"file_path": "MEMORY.md",
|
||
"full_path": "/app/memory_files/MEMORY.md",
|
||
"hash": "abc123...",
|
||
"size": 1234,
|
||
"lobster_id": "daotong"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### 检查同步状态
|
||
|
||
```http
|
||
GET /api/status/?lobster_id=daotong
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"consistent": [],
|
||
"local_newer": [],
|
||
"db_newer": [],
|
||
"conflict": [],
|
||
"hard_conflict": [],
|
||
"local_only": [{"file_path": "MEMORY.md", "status": "local_only", "hash": "abc123"}],
|
||
"db_only": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取文件差异
|
||
|
||
```http
|
||
GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md&chunked=true
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"file_path": "MEMORY.md",
|
||
"lobster_id": "daotong",
|
||
"local_content": "本地内容",
|
||
"db_content": "数据库内容",
|
||
"local_hash": "abc123",
|
||
"db_hash": "def456",
|
||
"status": "conflict",
|
||
"diff": {
|
||
"local_lines": ["line1", "line2"],
|
||
"db_lines": ["line1", "line3"],
|
||
"has_diff": true,
|
||
"is_truncated": false,
|
||
"lines_changed": 1
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 同步到数据库
|
||
|
||
```http
|
||
POST /api/sync/db/
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"lobster_id": "daotong",
|
||
"file_path": "MEMORY.md",
|
||
"operator": "逍遥子"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "已同步到数据库",
|
||
"data": {
|
||
"id": 1,
|
||
"lobster_id": "daotong",
|
||
"file_path": "MEMORY.md",
|
||
"content": "...",
|
||
"hash": "abc123",
|
||
"status": "consistent",
|
||
"version": 1,
|
||
"size": 1234,
|
||
"summary": "文件摘要",
|
||
"created_at": "2026-04-05T12:00:00Z",
|
||
"updated_at": "2026-04-05T12:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取操作历史
|
||
|
||
```http
|
||
GET /api/history/?lobster_id=daotong&limit=10
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"lobster_id": "daotong",
|
||
"file_path": "MEMORY.md",
|
||
"action": "sync_to_db",
|
||
"status": "success",
|
||
"source": "local",
|
||
"old_version": null,
|
||
"new_version": 1,
|
||
"lines_changed": 10,
|
||
"operator": "逍遥子",
|
||
"execution_time": 0.123,
|
||
"created_at": "2026-04-05T12:00:00Z"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
### .lobsterignore 管理
|
||
|
||
```http
|
||
# 获取忽略规则
|
||
GET /api/ignore/patterns/
|
||
|
||
# 重新加载忽略规则
|
||
POST /api/ignore/reload/
|
||
```
|
||
|
||
## 📘 详细部署指南
|
||
|
||
详细的部署文档请查看 [DEPLOY.md](DEPLOY.md)，包含：
|
||
- 系统要求
|
||
- Docker 安装
|
||
- 环境配置
|
||
- 数据库迁移
|
||
- 生产环境部署（Nginx + HTTPS）
|
||
- 数据库备份
|
||
- 监控与维护
|
||
- 故障排查
|
||
- 常见问题 FAQ
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
# 进入后端容器
|
||
docker exec -it lobster-backend bash
|
||
|
||
# 创建迁移
|
||
python manage.py makemigrations memory_app
|
||
python manage.py migrate
|
||
|
||
# 运行测试
|
||
python test_simple.py
|
||
|
||
# 运行开发服务器
|
||
python manage.py runserver 0.0.0.0:8087
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
# 本地开发（不使用 Docker）
|
||
cd frontend
|
||
npm install
|
||
npm start
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
**Q: 如何修改龙虾记忆目录？**
|
||
A: 修改 `docker-compose.yml` 中的挂载路径：
|
||
```yaml
|
||
backend:
|
||
volumes:
|
||
- /your/path/to/lobster/memory:/app/memory_files:ro
|
||
```
|
||
|
||
**Q: 如何配置 .lobsterignore？**
|
||
A: 在龙虾记忆目录创建 `.lobsterignore` 文件，参考 `.lobsterignore.example`
|
||
|
||
**Q: 内存占用过高怎么办？**
|
||
A: 系统已限制最大内存 256MB，自动清理缓存。如仍有问题，检查是否有大文件正在处理。
|
||
|
||
**Q: 如何查看操作日志？**
|
||
A: 访问 `GET /api/history/` 接口，支持按文件、操作类型筛选。
|
||
|
||
## 📝 License
|
||
|
||
MIT
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
**项目仓库**：http://10.2.0.100:8989/daotong/lobster-memory-sync.git |