docs: 添加详细的部署指南
- 系统要求说明 - Docker 安装步骤（Ubuntu/CentOS/macOS） - 环境变量配置 - 详细安装部署流程 - 部署验证步骤 - 生产环境配置（Nginx/HTTPS/备份） - 更新部署流程 - 监控与维护命令 - 完整故障排查指南 - 卸载步骤 - 常见问题 FAQ
This commit is contained in:
道童
477
README.md
477
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**: 项目初始化
|
||||
|
||||
Reference in New Issue
Block a user