diff --git a/DEPLOY.md b/DEPLOY.md index fb96496..f74f440 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -1,107 +1,1100 @@ -# Lobster Memory Sync +# 🚀 龙虾记忆同步系统 - 部署文档 -## 部署指南 +完整的部署指南,涵盖从开发环境到生产环境的所有步骤。 -### 前置条件 +## 📋 目录 -- Docker -- Docker Compose +- [系统要求](#系统要求) +- [环境准备](#环境准备) +- [快速部署](#快速部署) +- [生产环境部署](#生产环境部署) +- [数据库管理](#数据库管理) +- [监控与维护](#监控与维护) +- [故障排查](#故障排查) +- [备份与恢复](#备份与恢复) +- [性能优化](#性能优化) +- [安全加固](#安全加固) -### 快速启动 +--- + +## 💻 系统要求 + +### 最低配置 + +| 项目 | 要求 | +|------|------| +| 操作系统 | Linux / macOS / Windows (WSL2) | +| CPU | 2 核 | +| 内存 | 2GB RAM | +| 磁盘 | 5GB 可用空间 | +| 网络 | 稳定的网络连接 | + +### 推荐配置 + +| 项目 | 要求 | +|------|------| +| 操作系统 | Ubuntu 22.04 LTS / CentOS 8+ | +| CPU | 4 核 | +| 内存 | 4GB RAM | +| 磁盘 | 20GB SSD | +| 网络 | 千兆网络 | + +### 端口要求 + +| 端口 | 服务 | 说明 | +|------|------|------| +| 8086 | 前端 | React 应用 | +| 8087 | 后端 API | Django REST API | +| 5432 | PostgreSQL | 数据库 | +| 443 | HTTPS | Nginx(生产环境) | + +--- + +## 🔧 环境准备 + +### 1. 安装 Docker + +#### Ubuntu / Debian -1. **克隆项目** ```bash -cd /home/node/.openclaw/workspace/daotong/lobster-memory-sync +# 更新包索引 +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 ``` -2. **启动服务** +#### 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 +``` + +### 3. 安装 Git + +```bash +# Ubuntu / Debian +sudo apt-get install -y git + +# CentOS / RHEL +sudo yum install -y git + +# macOS +brew install git +``` + +### 4. 安装 Nginx(生产环境) + +```bash +# Ubuntu / Debian +sudo apt-get install -y nginx + +# CentOS / RHEL +sudo yum install -y nginx +``` + +--- + +## 🚀 快速部署 + +### 1. 克隆项目 + +```bash +# 克隆仓库 +git clone http://10.2.0.100:8989/daotong/lobster-memory-sync.git +cd lobster-memory-sync +``` + +### 2. 配置环境变量 + +创建 `.env` 文件: + +```bash +# 数据库配置 +DB_NAME=lobster_memory +DB_USER=postgres +DB_PASSWORD=your_secure_password_here +DB_HOST=postgres +DB_PORT=5432 + +# 龙虾记忆目录路径 +LOBSTER_MEMORY_BASE=/home/node/.openclaw/workspace/daotong + +# 前端配置 +REACT_APP_API_URL=http://localhost:8087/api + +# 端口配置 +FRONTEND_PORT=8086 +BACKEND_PORT=8087 +POSTGRES_PORT=5432 + +# Docker 配置 +COMPOSE_PROJECT_NAME=lobster-memory-sync +``` + +**重要提示:** +- 修改 `DB_PASSWORD` 为强密码 +- 修改 `LOBSTER_MEMORY_BASE` 为实际的龙虾记忆目录路径 +- 生产环境建议使用 `REACT_APP_API_URL=https://yourdomain.com/api` + +### 3. 修改 docker-compose.yml + +编辑 `docker-compose.yml`: + +```yaml +version: '3.8' + +services: + postgres: + image: postgres:15-alpine + container_name: lobster-postgres + environment: + POSTGRES_DB: ${DB_NAME} + POSTGRES_USER: ${DB_USER} + POSTGRES_PASSWORD: ${DB_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "${POSTGRES_PORT:-5432}:5432" + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"] + interval: 10s + timeout: 5s + retries: 5 + + backend: + build: + context: ./backend + dockerfile: Dockerfile + container_name: lobster-backend + environment: + DB_HOST: ${DB_HOST} + DB_NAME: ${DB_NAME} + DB_USER: ${DB_USER} + DB_PASSWORD: ${DB_PASSWORD} + DB_PORT: ${DB_PORT} + LOBSTER_MEMORY_BASE: ${LOBSTER_MEMORY_BASE} + DJANGO_SETTINGS_MODULE: memory_sync.settings + volumes: + # 挂载龙虾记忆目录(只读) + - ${LOBSTER_MEMORY_BASE}:/app/memory_files:ro + # 代码热重载(开发用) + - ./backend:/app + ports: + - "${BACKEND_PORT:-8087}:8087" + depends_on: + postgres: + condition: service_healthy + command: > + sh -c " + python manage.py migrate && + python manage.py runserver 0.0.0.0:8087 + " + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8087/api/"] + interval: 30s + timeout: 10s + retries: 3 + + frontend: + build: + context: ./frontend + dockerfile: Dockerfile + container_name: lobster-frontend + ports: + - "${FRONTEND_PORT:-8086}:80" + environment: + - REACT_APP_API_URL=${REACT_APP_API_URL} + depends_on: + - backend + +volumes: + postgres_data: +``` + +### 4. 构建并启动服务 + +```bash +# 构建镜像 +docker-compose build + +# 启动所有服务(后台运行) docker-compose up -d -``` -3. **访问应用** -- 前端:http://localhost:8086 -- 后端 API:http://localhost:8087/api/ -- PostgreSQL:localhost:5432 +# 查看服务状态 +docker-compose ps -### 开发模式 - -#### 后端开发 -```bash -# 进入后端容器 -docker exec -it lobster-backend bash - -# 创建迁移 -python manage.py makemigrations memory_app -python manage.py migrate - -# 创建超级用户 -python manage.py createsuperuser -``` - -#### 前端开发 -```bash -# 本地开发(不使用 Docker) -cd frontend -npm install -npm start -``` - -### API 接口文档 - -#### 扫描文件 -``` -GET /api/scan/?lobster_id=daotong -``` - -#### 检查同步状态 -``` -GET /api/status/?lobster_id=daotong -``` - -#### 获取文件差异 -``` -GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md -``` - -#### 同步到数据库 -``` -POST /api/sync/db/ -{ - "lobster_id": "daotong", - "file_path": "MEMORY.md" -} -``` - -#### 同步到本地 -``` -POST /api/sync/local/ -{ - "lobster_id": "daotong", - "file_path": "MEMORY.md" -} -``` - -### 故障排查 - -#### 查看日志 -```bash +# 查看日志 docker-compose logs -f ``` -#### 重启服务 -```bash -docker-compose restart +**预期输出:** +``` +NAME STATUS +lobster-postgres Up (healthy) +lobster-backend Up (healthy) +lobster-frontend Up ``` -#### 清理数据 +### 5. 初始化数据库 + ```bash -docker-compose down -v +# 等待数据库启动 +sleep 10 + +# 执行数据库迁移 +docker-compose exec backend python manage.py migrate + +# 创建超级用户(可选) +docker-compose exec backend python manage.py createsuperuser + +# 验证迁移 +docker-compose exec backend python manage.py showmigrations memory_app +``` + +**预期输出:** +``` +[X] 0001_initial +[X] 0002_add_summary_and_audit_fields +[X] 0003_add_file_attribute +``` + +### 6. 验证部署 + +#### 检查服务状态 + +```bash +# 查看所有容器状态 +docker-compose ps + +# 查看容器资源使用 +docker stats +``` + +#### 测试后端 API + +```bash +# 测试 API 健康检查 +curl http://localhost:8087/api/ + +# 测试文件扫描 +curl "http://localhost:8087/api/scan/?lobster_id=daotong" + +# 测试同步状态 +curl "http://localhost:8087/api/status/?lobster_id=daotong" +``` + +#### 访问前端 + +打开浏览器访问: +- http://localhost:8086 + +**预期效果:** +- ✅ 能够看到文件树展示 +- ✅ 能够点击文件查看差异对比 +- ✅ 能够执行同步操作 +- ✅ 能够查看操作历史 + +--- + +## 🏭 生产环境部署 + +### 1. 使用环境变量文件 + +创建 `.env.production` 文件: + +```bash +# 生产环境配置 +DB_NAME=lobster_memory_prod +DB_USER=postgres +DB_PASSWORD=<强密码,至少 32 位> +DB_HOST=postgres +DB_PORT=5432 + +# 龙虾记忆目录 +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 + +# Docker 配置 +COMPOSE_PROJECT_NAME=lobster-memory-sync-prod +``` + +### 2. 配置 Nginx 反向代理 + +创建 Nginx 配置文件 `/etc/nginx/sites-available/lobster-memory-sync`: + +```nginx +# 上游服务器配置 +upstream lobster_backend { + server localhost:8087; + keepalive 32; +} + +upstream lobster_frontend { + server localhost:8086; + keepalive 32; +} + +# HTTP 重定向到 HTTPS +server { + listen 80; + listen [::]:80; + server_name yourdomain.com; + + # Let's Encrypt 验证 + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + # 重定向到 HTTPS + location / { + return 301 https://$server_name$request_uri; + } +} + +# HTTPS 配置 +server { + listen 443 ssl http2; + 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 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384'; + ssl_prefer_server_ciphers off; + + # HSTS + add_header Strict-Transport-Security "max-age=63072000" always; + + # 安全头部 + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + + # 日志 + access_log /var/log/nginx/lobster-memory-access.log; + error_log /var/log/nginx/lobster-memory-error.log; + + # 前端静态资源 + location / { + proxy_pass http://lobster_frontend; + 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; + + # 缓存配置 + expires 1h; + add_header Cache-Control "public, immutable"; + } + + # 后端 API + location /api/ { + proxy_pass http://lobster_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; + + # 超时配置 + proxy_connect_timeout 60s; + proxy_send_timeout 60s; + proxy_read_timeout 60s; + + # 禁用缓存 + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + + # WebSocket 支持(如果需要) + location /ws/ { + proxy_pass http://lobster_backend/ws/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } +} +``` + +启用配置: + +```bash +# 创建符号链接 +sudo ln -s /etc/nginx/sites-available/lobster-memory-sync /etc/nginx/sites-enabled/ + +# 测试配置 +sudo nginx -t + +# 重启 Nginx +sudo systemctl restart nginx +``` + +### 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 + +# 添加自动续期任务 +sudo crontab -e +``` + +添加以下行: + +``` +0 0 * * * certbot renew --quiet --post-hook "systemctl reload nginx" +``` + +### 4. 配置防火墙 + +```bash +# Ubuntu (UFW) +sudo ufw allow 80/tcp +sudo ufw allow 443/tcp +sudo ufw enable + +# CentOS (firewalld) +sudo firewall-cmd --permanent --add-service=http +sudo firewall-cmd --permanent --add-service=https +sudo firewall-cmd --reload +``` + +### 5. 配置数据库备份 + +创建备份脚本 `/usr/local/bin/lobster-backup.sh`: + +```bash +#!/bin/bash + +# 配置 +BACKUP_DIR="/var/backups/lobster-memory" +COMPOSE_FILE="/opt/lobster-memory-sync/docker-compose.yml" +DB_NAME="lobster_memory_prod" +DB_USER="postgres" +RETENTION_DAYS=30 + +# 创建备份目录 +mkdir -p $BACKUP_DIR + +# 生成备份文件名 +DATE=$(date +%Y%m%d_%H%M%S) +BACKUP_FILE="$BACKUP_DIR/lobster_memory_$DATE.sql.gz" + +# 执行备份 +docker-compose -f $COMPOSE_FILE exec -T postgres pg_dump -U $DB_USER $DB_NAME | gzip > $BACKUP_FILE + +# 检查备份是否成功 +if [ $? -eq 0 ]; then + echo "Backup completed: $BACKUP_FILE" + + # 删除旧备份 + find $BACKUP_DIR -name "lobster_memory_*.sql.gz" -mtime +$RETENTION_DAYS -delete + + # 记录日志 + logger "Lobster Memory backup completed: $BACKUP_FILE" +else + echo "Backup failed!" + logger "Lobster Memory backup failed!" + exit 1 +fi +``` + +添加执行权限: + +```bash +sudo chmod +x /usr/local/bin/lobster-backup.sh +``` + +添加定时任务: + +```bash +sudo crontab -e +``` + +添加以下行: + +``` +# 每天凌晨 2 点执行备份 +0 2 * * * /usr/local/bin/lobster-backup.sh >> /var/log/lobster-backup.log 2>&1 +``` + +### 6. 配置日志轮转 + +创建日志轮转配置 `/etc/logrotate.d/lobster-memory`: + +``` +/var/log/nginx/lobster-memory-*.log { + daily + rotate 30 + compress + delaycompress + missingok + notifempty + create 644 www-data www-data + sharedscripts + postrotate + systemctl reload nginx > /dev/null 2>&1 || true + endscript +} + +/var/log/lobster-backup.log { + weekly + rotate 12 + compress + missingok + notifempty + create 644 root root +} +``` + +--- + +## 🗄️ 数据库管理 + +### 连接数据库 + +```bash +# 进入数据库容器 +docker-compose exec postgres psql -U postgres -d lobster_memory + +# 或使用主机连接 +psql -h localhost -U postgres -d lobster_memory +``` + +### 常用 SQL 命令 + +```sql +-- 查看所有表 +\dt + +-- 查看表结构 +\d lobster_memory + +-- 查看索引 +\d lobster_memory + +-- 查看同步历史 +SELECT * FROM sync_history ORDER BY created_at DESC LIMIT 10; + +-- 查看文件属性 +SELECT * FROM file_attribute WHERE lobster_id = 'daotong'; + +-- 统计文件数量 +SELECT COUNT(*) FROM lobster_memory WHERE lobster_id = 'daotong'; + +-- 查看冲突文件 +SELECT file_path, status, version FROM lobster_memory WHERE status IN ('conflict', 'hard_conflict'); +``` + +### 数据库性能优化 + +```sql +-- 创建索引 +CREATE INDEX idx_lobster_memory_lobster_updated ON lobster_memory(lobster_id, updated_at); +CREATE INDEX idx_sync_history_lobster_updated ON sync_history(lobster_id, created_at); + +-- 分析表 +ANALYZE lobster_memory; +ANALYZE sync_history; +ANALYZE file_attribute; + +-- 清理死元组 +VACUUM FULL lobster_memory; +``` + +--- + +## 📊 监控与维护 + +### 查看服务日志 + +```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 + +# 查看特定时间范围的日志 +docker-compose logs --since=2024-01-01T00:00:00 backend +``` + +### 查看资源使用 + +```bash +# 查看容器资源使用情况 +docker stats + +# 查看磁盘使用 +docker system df + +# 清理未使用的资源 +docker system prune -a + +# 查看容器详细信息 +docker inspect lobster-backend +``` + +### 健康检查 + +```bash +# 检查后端 API +curl -f http://localhost:8087/api/ || echo "Backend is down" + +# 检查前端 +curl -f http://localhost:8086/ || echo "Frontend is down" + +# 检查数据库 +docker-compose exec postgres pg_isready -U postgres +``` + +### 自动化监控脚本 + +创建监控脚本 `/usr/local/bin/lobster-monitor.sh`: + +```bash +#!/bin/bash + +# 配置 +WEBHOOK_URL="https://your-webhook-url.com" +COMPOSE_FILE="/opt/lobster-memory-sync/docker-compose.yml" + +# 检查服务状态 +check_service() { + local service=$1 + local url=$2 + + if ! curl -f -s -o /dev/null "$url"; then + echo "Service $service is down!" + + # 发送告警 + curl -X POST "$WEBHOOK_URL" \ + -H "Content-Type: application/json" \ + -d "{\"text\": \"🚨 Service $service is down!\"}" + + # 重启服务 + docker-compose -f $COMPOSE_FILE restart $service + + # 记录日志 + logger "Restarted service: $service" + fi +} + +# 检查各个服务 +check_service "backend" "http://localhost:8087/api/" +check_service "frontend" "http://localhost:8086/" +``` + +添加定时任务: + +```bash +sudo crontab -e +``` + +添加以下行: + +``` +# 每 5 分钟检查一次服务状态 +*/5 * * * * /usr/local/bin/lobster-monitor.sh +``` + +--- + +## 🔍 故障排查 + +### 问题 1:容器启动失败 + +**症状:** +```bash +docker-compose ps +# NAME STATUS +# lobster-postgres Exit 1 +# lobster-backend Exit 1 +``` + +**排查步骤:** + +1. 查看容器日志 +```bash +docker-compose logs postgres +docker-compose logs backend +``` + +2. 检查端口占用 +```bash +sudo netstat -tulpn | grep -E '8086|8087|5432' +``` + +3. 检查磁盘空间 +```bash +df -h +``` + +4. 重新构建镜像 +```bash +docker-compose build --no-cache docker-compose up -d ``` -### 技术栈 +### 问题 2:数据库连接失败 -- **后端**: Django + Django REST Framework + PostgreSQL -- **前端**: React + Ant Design + react-diff-viewer-continued -- **部署**: Docker + Docker Compose \ No newline at end of file +**症状:** +``` +django.db.utils.OperationalError: could not connect to server +``` + +**排查步骤:** + +1. 检查数据库容器状态 +```bash +docker-compose ps postgres +``` + +2. 查看数据库日志 +```bash +docker-compose logs postgres +``` + +3. 测试数据库连接 +```bash +docker-compose exec postgres psql -U postgres -d lobster_memory -c "SELECT version();" +``` + +4. 检查环境变量 +```bash +docker-compose exec backend env | grep DB_ +``` + +### 问题 3:前端无法访问后端 API + +**症状:** +``` +Network Error +``` + +**排查步骤:** + +1. 检查后端服务状态 +```bash +curl http://localhost:8087/api/ +``` + +2. 检查前端配置 +```bash +docker-compose logs frontend +``` + +3. 验证环境变量 +```bash +docker-compose exec frontend env | grep REACT_APP_API_URL +``` + +4. 检查网络连接 +```bash +docker-compose exec frontend curl http://backend:8087/api/ +``` + +### 问题 4:文件扫描失败 + +**症状:** +``` +Error reading /app/memory_files/file.txt: Permission denied +``` + +**排查步骤:** + +1. 检查龙虾记忆目录挂载 +```bash +docker-compose exec backend ls -la /app/memory_files +``` + +2. 检查目录权限 +```bash +ls -ld /home/node/.openclaw/workspace/daotong +``` + +3. 修复权限 +```bash +chmod -R 755 /home/node/.openclaw/workspace/daotong +``` + +4. 重新挂载 +```bash +docker-compose down +docker-compose up -d +``` + +### 问题 5:内存占用过高 + +**症状:** +``` +Memory usage exceeds 256MB +``` + +**排查步骤:** + +1. 查看容器资源使用 +```bash +docker stats +``` + +2. 检查大文件 +```bash +find /home/node/.openclaw/workspace/daotong -type f -size +50M +``` + +3. 添加到 .lobsterignore +```bash +echo "*.log" >> /home/node/.openclaw/workspace/daotong/.lobsterignore +``` + +4. 重启服务 +```bash +docker-compose restart backend +``` + +--- + +## 💾 备份与恢复 + +### 备份数据库 + +```bash +# 手动备份 +docker-compose exec postgres pg_dump -U postgres lobster_memory > backup.sql + +# 压缩备份 +docker-compose exec postgres pg_dump -U postgres lobster_memory | gzip > backup.sql.gz + +# 备份到远程 +docker-compose exec postgres pg_dump -U postgres lobster_memory | gzip | ssh user@remote "cat > /backup/lobster_memory_$(date +%Y%m%d).sql.gz" +``` + +### 恢复数据库 + +```bash +# 从本地恢复 +docker-compose exec -T postgres psql -U postgres lobster_memory < backup.sql + +# 从压缩文件恢复 +gunzip < backup.sql.gz | docker-compose exec -T postgres psql -U postgres lobster_memory + +# 从远程恢复 +ssh user@remote "cat /backup/lobster_memory_20240101.sql.gz" | gunzip | docker-compose exec -T postgres psql -U postgres lobster_memory +``` + +### 备份配置文件 + +```bash +# 备份配置文件 +tar -czf lobster-config-$(date +%Y%m%d).tar.gz \ + .env \ + docker-compose.yml \ + .lobsterignore \ + nginx.conf +``` + +--- + +## ⚡ 性能优化 + +### 1. 数据库优化 + +```sql +-- 调整 PostgreSQL 配置 +ALTER SYSTEM SET shared_buffers = '256MB'; +ALTER SYSTEM SET effective_cache_size = '1GB'; +ALTER SYSTEM SET maintenance_work_mem = '64MB'; +ALTER SYSTEM SET work_mem = '16MB'; + +-- 重启数据库生效 +docker-compose restart postgres +``` + +### 2. Nginx 优化 + +```nginx +# 启用 gzip 压缩 +gzip on; +gzip_vary on; +gzip_min_length 1024; +gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json; + +# 启用缓存 +location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { + expires 30d; + add_header Cache-Control "public, immutable"; +} +``` + +### 3. Docker 优化 + +```yaml +# docker-compose.yml +services: + backend: + # 限制内存使用 + deploy: + resources: + limits: + cpus: '2' + memory: 512M + reservations: + cpus: '0.5' + memory: 256M +``` + +--- + +## 🔒 安全加固 + +### 1. 更新默认密码 + +```bash +# 修改数据库密码 +docker-compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'your-strong-password';" + +# 更新 .env 文件 +sed -i 's/DB_PASSWORD=.*/DB_PASSWORD=your-strong-password/' .env +``` + +### 2. 配置防火墙 + +```bash +# 只允许特定 IP 访问数据库 +sudo ufw allow from 192.168.1.0/24 to any port 5432 +``` + +### 3. 启用 SELinux(CentOS) + +```bash +# 检查 SELinux 状态 +sestatus + +# 启用 SELinux +sudo setenforce 1 +``` + +### 4. 定期更新 + +```bash +# 更新 Docker 镜像 +docker-compose pull +docker-compose up -d + +# 更新系统包 +sudo apt-get update && sudo apt-get upgrade -y +``` + +--- + +## 📝 维护清单 + +### 每日 + +- [ ] 检查服务状态 +- [ ] 查看错误日志 +- [ ] 验证备份完成 + +### 每周 + +- [ ] 清理旧日志 +- [ ] 检查磁盘空间 +- [ ] 更新系统补丁 + +### 每月 + +- [ ] 检查备份完整性 +- [ ] 性能评估 +- [ ] 安全审计 + +--- + +## 🆘 获取帮助 + +遇到问题? + +1. 查看日志:`docker-compose logs -f` +2. 查看文档:[README.md](README.md) +3. 提交 Issue:http://10.2.0.100:8989/daotong/lobster-memory-sync/issues + +--- + +**文档版本**: v1.0.0 +**最后更新**: 2026-04-05 +**维护者**: 道童 \ No newline at end of file diff --git a/README.md b/README.md index 338eb1a..87ce78d 100644 --- a/README.md +++ b/README.md @@ -1,190 +1,321 @@ # 🦐 龙虾记忆同步系统 -一个用于同步和管理龙虾记忆文件的前后端分离系统,提供文件树展示、差异对比和双向同步功能。 +一个专为 OpenClaw 龙虾设计的记忆文件管理系统,提供文件树展示、差异对比、双向同步和属性管理功能。 + +## ✨ 核心特性 + +- ✅ **分块流式处理**:8KB 分块读取,内存限制 256MB,支持大文件处理 +- ✅ **.lobsterignore 支持**:正则表达式匹配,过滤不需要同步的文件 +- ✅ **智能差异对比**:行级差异,颜色区分,支持大文件截断 +- ✅ **属性目录结构**:支持嵌套属性键值对(如 `author.name`, `metadata.tags`) +- ✅ **完整审计日志**:记录操作人、数据源、变动行数、执行时间 +- ✅ **语义摘要**:自动生成文件内容摘要 +- ✅ **冲突判定**:识别 HARD_CONFLICT 状态,智能判断严重冲突 +- ✅ **丝滑前端**:Ant Design 树形控件,点选-对比-同步流程 ## 📋 目录 -- [项目概述](#项目概述) -- [技术栈](#技术栈) -- [功能特性](#功能特性) -- [项目结构](#项目结构) - [快速开始](#快速开始) +- [功能特性](#功能特性) +- [技术架构](#技术架构) +- [项目结构](#项目结构) - [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(数据库) +- Docker 20.10+ +- Docker Compose 2.0+ +- 端口:8086(前端)、8087(后端)、5432(数据库) ### 一键启动 ```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 exec backend python manage.py migrate + # 查看日志 docker-compose logs -f - -# 停止服务 -docker-compose down ``` -### 访问地址 +### 访问应用 -- 前端:http://localhost:8086 -- 后端 API:http://localhost:8087/api/ -- PostgreSQL:localhost:5432 +- 📱 前端:http://localhost:8086 +- 📡 后端 API:http://localhost:8087/api/ +- 🗄️ 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 ``` **响应示例:** ```json { - "files": [ + "success": true, + "data": [ { - "name": "MEMORY.md", - "path": "MEMORY.md", - "type": "file", + "file_path": "MEMORY.md", + "full_path": "/app/memory_files/MEMORY.md", + "hash": "abc123...", "size": 1234, - "last_modified": "2026-04-05T12:00:00Z" + "lobster_id": "daotong" } - ] + ], + "total": 1 } ``` ### 检查同步状态 -``` -GET /api/status/?lobster_id=daotong&file_path=MEMORY.md +```http +GET /api/status/?lobster_id=daotong ``` **响应示例:** ```json { - "synced": false, - "has_difference": true, - "difference": "+ 新增内容\n- 删除内容" + "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 ``` -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/ Content-Type: application/json { "lobster_id": "daotong", - "file_path": "MEMORY.md" + "file_path": "MEMORY.md", + "operator": "逍遥子" } ``` -### 同步到本地 - -``` -POST /api/sync/local/ -Content-Type: application/json - +**响应示例:** +```json { - "lobster_id": "daotong", - "file_path": "MEMORY.md" + "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 + +## 🛠️ 开发指南 ### 后端开发 @@ -196,8 +327,8 @@ docker exec -it lobster-backend bash python manage.py makemigrations memory_app python manage.py migrate -# 创建超级用户 -python manage.py createsuperuser +# 运行测试 +python test_simple.py # 运行开发服务器 python manage.py runserver 0.0.0.0:8087 @@ -215,488 +346,24 @@ 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 - -根据实际环境修改以下配置: +## ❓ 常见问题 +**Q: 如何修改龙虾记忆目录?** +A: 修改 `docker-compose.yml` 中的挂载路径: ```yaml -services: - backend: - volumes: - # 挂载龙虾记忆目录(只读) - - /home/node/.openclaw/workspace/daotong:/app/memory_files:ro +backend: + volumes: + - /your/path/to/lobster/memory:/app/memory_files:ro ``` -**注意事项:** -- 将 `/home/node/.openclaw/workspace/daotong` 替换为实际的龙虾记忆目录路径 -- 使用 `:ro` 只读挂载,确保安全性 +**Q: 如何配置 .lobsterignore?** +A: 在龙虾记忆目录创建 `.lobsterignore` 文件,参考 `.lobsterignore.example` -#### 4. 构建并启动服务 +**Q: 内存占用过高怎么办?** +A: 系统已限制最大内存 256MB,自动清理缓存。如仍有问题,检查是否有大文件正在处理。 -```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 +**Q: 如何查看操作日志?** +A: 访问 `GET /api/history/` 接口,支持按文件、操作类型筛选。 ## 📝 License @@ -704,4 +371,8 @@ MIT ## 🤝 贡献 -欢迎提交 Issue 和 Pull Request! \ No newline at end of file +欢迎提交 Issue 和 Pull Request! + +--- + +**项目仓库**:http://10.2.0.100:8989/daotong/lobster-memory-sync.git \ No newline at end of file