From d9420b6cc629d9ab9c99bdf89686ef081b29dedb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=81=93=E7=AB=A5?= <daotong@openclaw.ai>
Date: Sun, 5 Apr 2026 12:15:48 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E8=AF=A6=E7=BB=86?=
 =?UTF-8?q?=E7=9A=84=E9=83=A8=E7=BD=B2=E6=8C=87=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 系统要求说明
- Docker 安装步骤（Ubuntu/CentOS/macOS）
- 环境变量配置
- 详细安装部署流程
- 部署验证步骤
- 生产环境配置（Nginx/HTTPS/备份）
- 更新部署流程
- 监控与维护命令
- 完整故障排查指南
- 卸载步骤
- 常见问题 FAQ
---
 README.md | 477 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 463 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 0f3e2fb..338eb1a 100644
--- a/README.md
+++ b/README.md
@@ -215,32 +215,481 @@ npm start
 npm run build
 ```
 
-## 部署说明
+## 🚀 部署指南
 
-详细部署文档请参考 [DEPLOY.md](DEPLOY.md)
+### 系统要求
 
-### 生产环境部署
+- **操作系统**: Linux / macOS / Windows (WSL2)
+- **Docker**: 20.10 或更高版本
+- **Docker Compose**: 2.0 或更高版本
+- **内存**: 最少 2GB RAM
+- **磁盘**: 最少 5GB 可用空间
+- **端口**: 8086（前端）、8087（后端）、5432（数据库）
 
-1. 修改 `docker-compose.yml` 中的环境变量
-2. 配置 Nginx 反向代理
-3. 启用 HTTPS
-4. 配置数据库备份
+### 环境准备
+
+#### 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
+
+根据实际环境修改以下配置：
+
+```yaml
+services:
+  backend:
+    volumes:
+      # 挂载龙虾记忆目录（只读）
+      - /home/node/.openclaw/workspace/daotong:/app/memory_files:ro
+```
+
+**注意事项：**
+- 将 `/home/node/.openclaw/workspace/daotong` 替换为实际的龙虾记忆目录路径
+- 使用 `:ro` 只读挂载，确保安全性
+
+#### 4. 构建并启动服务
+
+```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 -f backend
-docker-compose logs -f frontend
+# 查看容器日志
+docker-compose logs backend
 
-# 重启服务
-docker-compose restart
+# 检查端口占用
+sudo netstat -tulpn | grep -E '8086|8087|5432'
 
-# 清理数据
-docker-compose down -v
+# 重新构建镜像
+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**: 项目初始化