ailine/REMOTE_SERVICES_MIGRATION.md

# 远程服务配置迁移指南

## 📋 变更概述

从 **2026-04-15** 起，项目已将 PostgreSQL 和 Qdrant 服务迁移到远程服务器（`115.190.121.151`），本地开发环境不再需要运行这些服务的容器。

## 🌐 远程服务地址

| 服务 | 远程地址 | 端口 | 说明 |
|------|---------|------|------|
| **PostgreSQL** | `115.190.121.151` | `5432` | LangGraph 状态持久化 |
| **Qdrant** | `115.190.121.151` | `6333` | Mem0 向量数据库 |

## 🔧 已修改的配置文件

### 1. `.env` - 本地开发配置
```bash
# 之前（本地容器）
QDRANT_URL=http://localhost:6333
DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable

# 现在（远程服务器）
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:mysecretpassword@115.190.121.151:5432/langgraph_db?sslmode=disable
```

### 2. `.env.docker` - Docker Compose 配置
```bash
# 之前（Docker 内部网络）
QDRANT_URL=http://qdrant:6333
DB_URI=postgresql://postgres:mysecretpassword@postgres:5432/langgraph_db?sslmode=disable

# 现在（远程服务器）
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:mysecretpassword@115.190.121.151:5432/langgraph_db?sslmode=disable
```

### 3. `docker/docker-compose.yml` - Docker Compose 编排
```yaml
# ❌ 已移除的服务
# postgres:
#   image: postgres:16
#   ...

# qdrant:
#   image: qdrant/qdrant:latest
#   ...

# ✅ backend 服务配置更新
backend:
  environment:
    - DB_URI=postgresql://postgres:mysecretpassword@115.190.121.151:5432/langgraph_db?sslmode=disable
    - QDRANT_URL=http://115.190.121.151:6333
  # ⭐ 移除了 depends_on (postgres, qdrant)
```

## 🚀 使用方式

### 本地开发（直接运行 Python）
```bash
# 1. 确保 .env 文件已更新（已完成）
cat .env | grep -E "(QDRANT_URL|DB_URI)"

# 2. 启动后端服务
python app/backend.py

# 3. 启动前端服务
cd frontend && streamlit run app.py
```

### Docker Compose 部署
```bash
# 1. 确保 .env.docker 文件已更新（已完成）
cp .env.docker .env

# 2. 启动服务（仅 backend 和 frontend）
cd docker
docker compose up -d

# 3. 查看日志
docker compose logs -f backend
```

## ⚠️ 注意事项

### 1. 网络连接
- 确保本地机器可以访问 `115.190.121.151` 的 `5432` 和 `6333` 端口
- 测试连接：
  ```bash
  # 测试 PostgreSQL
  psql -h 115.190.121.151 -U postgres -d langgraph_db
  
  # 测试 Qdrant
  curl http://115.190.121.151:6333/collections
  ```

### 2. 防火墙配置
如果无法连接，检查远程服务器的防火墙规则：
```bash
# 在远程服务器上执行
sudo ufw allow 5432/tcp
sudo ufw allow 6333/tcp
sudo ufw reload
```

### 3. 数据持久化
- PostgreSQL 数据存储在远程服务器的 `~/docker_volumes/postgres_data`
- Qdrant 数据存储在远程服务器的 `~/docker_volumes/qdrant_storage`
- **无需在本地维护数据卷**

### 4. 备份与恢复
如需备份远程数据库：
```bash
# 备份 PostgreSQL
pg_dump -h 115.190.121.151 -U postgres langgraph_db > backup_$(date +%Y%m%d).sql

# 备份 Qdrant（通过 API 导出集合）
curl http://115.190.121.151:6333/collections/mem0_user_memories/snapshot > snapshot.zip
```

## 🔄 回滚到本地容器（可选）

如果需要使用本地容器进行测试，可以：

1. **修改 `.env` 文件**：
   ```bash
   QDRANT_URL=http://localhost:6333
   DB_URI=postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db?sslmode=disable
   ```

2. **启动本地容器**：
   ```bash
   docker run -d --name qdrant_server -p 6333:6333 qdrant/qdrant
   docker run -d --name ai-postgres -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=langgraph_db -p 5432:5432 postgres:16
   ```

3. **初始化数据库表**：
   ```bash
   python scripts/init_db.py
   ```

## 📊 架构对比

### 之前（本地容器）
```
┌─────────────┐     ┌──────────┐     ┌──────────┐
│  Frontend   │────▶│ Backend  │────▶│ Postgres │ (localhost:5432)
│  :8501      │     │  :8001   │     └──────────┘
└─────────────┘     └──────────┘     ┌──────────┐
                                      │  Qdrant  │ (localhost:6333)
                                      └──────────┘
```

### 现在（远程服务）
```
┌─────────────┐     ┌──────────┐     ┌──────────────────┐
│  Frontend   │────▶│ Backend  │────▶│ Remote Services  │
│  :8501      │     │  :8001   │     │                  │
└─────────────┘     └──────────┘     │ • Postgres       │
                                     │   (115.190.121.151:5432)
                                     │ • Qdrant         │
                                     │   (115.190.121.151:6333)
                                     └──────────────────┘
```

## ✅ 验证清单

- [x] `.env` 文件已更新为远程地址
- [x] `.env.docker` 文件已更新为远程地址
- [x] `.env.example` 模板已更新
- [x] `docker-compose.yml` 已移除 postgres 和 qdrant 服务
- [x] 远程服务器上的服务正常运行
- [ ] 本地可以连接到远程 PostgreSQL
- [ ] 本地可以连接到远程 Qdrant
- [ ] 应用功能测试通过

---

**最后更新**: 2026-04-15  
**维护者**: AI Agent Team