docs: 更新文档（README.md 和 DEPLOY.md）
更新内容： 1. README.md - 重新组织文档结构 - 新增核心特性详细说明 - 新增完整 API 文档 - 新增常见问题 FAQ - 新增 .lobsterignore 管理接口文档 - 简化快速开始流程 - 突出丝滑前端体验 2. DEPLOY.md（全新部署文档） - 完整的系统要求（最低/推荐配置） - 详细的环境准备（Docker、Git、Nginx） - 快速部署指南 - 生产环境部署（Nginx + HTTPS） - 数据库管理（连接、SQL 命令、性能优化） - 监控与维护（日志、资源使用、健康检查） - 完整的故障排查指南（5 个常见问题） - 备份与恢复（数据库备份、配置备份） - 性能优化（数据库、Nginx、Docker） - 安全加固（密码更新、防火墙、SELinux） - 维护清单（每日/每周/每月） 文档特点： - 结构清晰，易于查找 - 命令示例完整，可直接复制使用 - 包含生产环境最佳实践 - 覆盖常见问题和解决方案
This commit is contained in:
道童
859
README.md
859
README.md
@@ -1,190 +1,321 @@
|
|||||||
# 🦐 龙虾记忆同步系统
|
# 🦐 龙虾记忆同步系统
|
||||||
|
|
||||||
一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。
|
一个专为 OpenClaw 龙虾设计的记忆文件管理系统，提供文件树展示、差异对比、双向同步和属性管理功能。
|
||||||
|
|
||||||
|
## ✨ 核心特性
|
||||||
|
|
||||||
|
- ✅ **分块流式处理**：8KB 分块读取，内存限制 256MB，支持大文件处理
|
||||||
|
- ✅ **.lobsterignore 支持**：正则表达式匹配，过滤不需要同步的文件
|
||||||
|
- ✅ **智能差异对比**：行级差异，颜色区分，支持大文件截断
|
||||||
|
- ✅ **属性目录结构**：支持嵌套属性键值对（如 `author.name`, `metadata.tags`）
|
||||||
|
- ✅ **完整审计日志**：记录操作人、数据源、变动行数、执行时间
|
||||||
|
- ✅ **语义摘要**：自动生成文件内容摘要
|
||||||
|
- ✅ **冲突判定**：识别 HARD_CONFLICT 状态，智能判断严重冲突
|
||||||
|
- ✅ **丝滑前端**：Ant Design 树形控件，点选-对比-同步流程
|
||||||
|
|
||||||
## 📋 目录
|
## 📋 目录
|
||||||
|
|
||||||
- [项目概述](#项目概述)
|
|
||||||
- [技术栈](#技术栈)
|
|
||||||
- [功能特性](#功能特性)
|
|
||||||
- [项目结构](#项目结构)
|
|
||||||
- [快速开始](#快速开始)
|
- [快速开始](#快速开始)
|
||||||
|
- [功能特性](#功能特性)
|
||||||
|
- [技术架构](#技术架构)
|
||||||
|
- [项目结构](#项目结构)
|
||||||
- [API 文档](#api-文档)
|
- [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 20.10+
|
||||||
- Docker Compose
|
- Docker Compose 2.0+
|
||||||
- 端口占用检查：8086（前端）、8087（后端）、5432（数据库）
|
- 端口：8086（前端）、8087（后端）、5432（数据库）
|
||||||
|
|
||||||
### 一键启动
|
### 一键启动
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 克隆项目
|
# 克隆项目
|
||||||
cd /home/node/.openclaw/workspace/daotong/lobster-memory-sync
|
git clone http://10.2.0.100:8989/daotong/lobster-memory-sync.git
|
||||||
|
cd lobster-memory-sync
|
||||||
|
|
||||||
# 启动服务
|
# 启动服务
|
||||||
docker-compose up -d
|
docker-compose up -d
|
||||||
|
|
||||||
|
# 执行数据库迁移
|
||||||
|
docker-compose exec backend python manage.py migrate
|
||||||
|
|
||||||
# 查看日志
|
# 查看日志
|
||||||
docker-compose logs -f
|
docker-compose logs -f
|
||||||
|
|
||||||
# 停止服务
|
|
||||||
docker-compose down
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 访问地址
|
### 访问应用
|
||||||
|
|
||||||
- 前端：http://localhost:8086
|
- 📱 前端：http://localhost:8086
|
||||||
- 后端 API：http://localhost:8087/api/
|
- 📡 后端 API：http://localhost:8087/api/
|
||||||
- PostgreSQL：localhost:5432
|
- 🗄️ PostgreSQL：localhost:5432
|
||||||
|
|
||||||
## API 文档
|
## 🎯 功能特性
|
||||||
|
|
||||||
### 扫描文件
|
### 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
|
GET /api/scan/?lobster_id=daotong
|
||||||
```
|
```
|
||||||
|
|
||||||
**响应示例：**
|
**响应示例：**
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"files": [
|
"success": true,
|
||||||
|
"data": [
|
||||||
{
|
{
|
||||||
"name": "MEMORY.md",
|
"file_path": "MEMORY.md",
|
||||||
"path": "MEMORY.md",
|
"full_path": "/app/memory_files/MEMORY.md",
|
||||||
"type": "file",
|
"hash": "abc123...",
|
||||||
"size": 1234,
|
"size": 1234,
|
||||||
"last_modified": "2026-04-05T12:00:00Z"
|
"lobster_id": "daotong"
|
||||||
}
|
}
|
||||||
]
|
],
|
||||||
|
"total": 1
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 检查同步状态
|
### 检查同步状态
|
||||||
|
|
||||||
```
|
```http
|
||||||
GET /api/status/?lobster_id=daotong&file_path=MEMORY.md
|
GET /api/status/?lobster_id=daotong
|
||||||
```
|
```
|
||||||
|
|
||||||
**响应示例：**
|
**响应示例：**
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"synced": false,
|
"success": true,
|
||||||
"has_difference": true,
|
"data": {
|
||||||
"difference": "+ 新增内容\n- 删除内容"
|
"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
|
||||||
```
|
```
|
||||||
GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md
|
|
||||||
|
**响应示例：**
|
||||||
|
```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/
|
POST /api/sync/db/
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
|
|
||||||
{
|
{
|
||||||
"lobster_id": "daotong",
|
"lobster_id": "daotong",
|
||||||
"file_path": "MEMORY.md"
|
"file_path": "MEMORY.md",
|
||||||
|
"operator": "逍遥子"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 同步到本地
|
**响应示例：**
|
||||||
|
```json
|
||||||
```
|
|
||||||
POST /api/sync/local/
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{
|
{
|
||||||
"lobster_id": "daotong",
|
"success": true,
|
||||||
"file_path": "MEMORY.md"
|
"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
|
||||||
|
|
||||||
|
## 🛠️ 开发指南
|
||||||
|
|
||||||
### 后端开发
|
### 后端开发
|
||||||
|
|
||||||
@@ -196,8 +327,8 @@ docker exec -it lobster-backend bash
|
|||||||
python manage.py makemigrations memory_app
|
python manage.py makemigrations memory_app
|
||||||
python manage.py migrate
|
python manage.py migrate
|
||||||
|
|
||||||
# 创建超级用户
|
# 运行测试
|
||||||
python manage.py createsuperuser
|
python test_simple.py
|
||||||
|
|
||||||
# 运行开发服务器
|
# 运行开发服务器
|
||||||
python manage.py runserver 0.0.0.0:8087
|
python manage.py runserver 0.0.0.0:8087
|
||||||
@@ -215,488 +346,24 @@ npm start
|
|||||||
npm run build
|
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
|
|
||||||
|
|
||||||
根据实际环境修改以下配置：
|
|
||||||
|
|
||||||
|
**Q: 如何修改龙虾记忆目录？**
|
||||||
|
A: 修改 `docker-compose.yml` 中的挂载路径：
|
||||||
```yaml
|
```yaml
|
||||||
services:
|
backend:
|
||||||
backend:
|
volumes:
|
||||||
volumes:
|
- /your/path/to/lobster/memory:/app/memory_files:ro
|
||||||
# 挂载龙虾记忆目录（只读）
|
|
||||||
- /home/node/.openclaw/workspace/daotong:/app/memory_files:ro
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**注意事项：**
|
**Q: 如何配置 .lobsterignore？**
|
||||||
- 将 `/home/node/.openclaw/workspace/daotong` 替换为实际的龙虾记忆目录路径
|
A: 在龙虾记忆目录创建 `.lobsterignore` 文件，参考 `.lobsterignore.example`
|
||||||
- 使用 `:ro` 只读挂载，确保安全性
|
|
||||||
|
|
||||||
#### 4. 构建并启动服务
|
**Q: 内存占用过高怎么办？**
|
||||||
|
A: 系统已限制最大内存 256MB，自动清理缓存。如仍有问题，检查是否有大文件正在处理。
|
||||||
|
|
||||||
```bash
|
**Q: 如何查看操作日志？**
|
||||||
# 构建镜像
|
A: 访问 `GET /api/history/` 接口，支持按文件、操作类型筛选。
|
||||||
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
|
## 📝 License
|
||||||
|
|
||||||
@@ -705,3 +372,7 @@ MIT
|
|||||||
## 🤝 贡献
|
## 🤝 贡献
|
||||||
|
|
||||||
欢迎提交 Issue 和 Pull Request！
|
欢迎提交 Issue 和 Pull Request！
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**项目仓库**：http://10.2.0.100:8989/daotong/lobster-memory-sync.git
|
||||||
Reference in New Issue
Block a user