# Vector 恢复备份 API 用户指南

## 📖 概述

Vector恢复备份API提供了完整的pgvector表数据恢复功能，包括备份文件列表查询和数据恢复操作。这套API与现有的备份API形成完整的数据管理解决方案。

## 🔧 前置条件

1. **服务运行**: 确保统一API服务正在运行
   ```bash
   python unified_api.py
   ```

2. **数据库连接**: 确保pgvector数据库连接正常

3. **备份文件**: 确保存在可用的备份文件（通过备份API创建）

## 📋 API 1: 备份文件列表查询

### 基本信息
- **端点**: `GET /api/v0/data_pipeline/vector/restore/list`
- **功能**: 扫描并列出所有可用的vector表备份文件
- **返回**: 结构化的备份文件列表信息

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `global_only` | boolean | 否 | false | 仅查询全局备份（`training_data/vector_bak/`目录） |
| `task_id` | string | 否 | - | 查询指定任务的备份文件 |

### 参数说明

#### 1. 查询所有备份文件（默认）
```bash
curl "http://localhost:8084/api/v0/data_pipeline/vector/restore/list"
```

#### 2. 仅查询全局备份
```bash
curl "http://localhost:8084/api/v0/data_pipeline/vector/restore/list?global_only=true"
```

#### 3. 查询特定任务的备份
```bash
curl "http://localhost:8084/api/v0/data_pipeline/vector/restore/list?task_id=task_20250721_213627"
```

### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {
    "response": "成功扫描到 6 个备份位置，共 6 个备份集",
    "backup_locations": [
      {
        "type": "global",
        "relative_path": "./data_pipeline/training_data/vector_bak",
        "backups": [
          {
            "timestamp": "20250722_010318",
            "collection_file": "langchain_pg_collection_20250722_010318.csv",
            "embedding_file": "langchain_pg_embedding_20250722_010318.csv",
            "collection_size": "209 B",
            "embedding_size": "819 KB",
            "backup_date": "2025-07-22 01:03:18",
            "has_log": true,
            "log_file": "vector_backup_log.txt"
          }
        ]
      },
      {
        "type": "task",
        "task_id": "task_20250721_213627",
        "relative_path": "./data_pipeline/training_data/task_20250721_213627/vector_bak",
        "backups": [
          {
            "timestamp": "20250721_215758",
            "collection_file": "langchain_pg_collection_20250721_215758.csv",
            "embedding_file": "langchain_pg_embedding_20250721_215758.csv",
            "collection_size": "209 B",
            "embedding_size": "764 KB",
            "backup_date": "2025-07-21 21:57:58",
            "has_log": true,
            "log_file": "vector_backup_log.txt"
          }
        ]
      }
    ],
    "summary": {
      "total_locations": 6,
      "total_backup_sets": 6,
      "global_backups": 1,
      "task_backups": 5,
      "scan_time": "2025-07-22T11:28:25.156158"
    },
    "timestamp": "2025-07-22T11:28:25.156158"
  }
}
```

### 响应字段说明

#### backup_locations 数组
- **type**: 备份类型（`global` 或 `task`）
- **task_id**: 任务ID（仅task类型有此字段）
- **relative_path**: 相对路径（Unix风格）
- **backups**: 该位置下的备份集数组

#### backups 数组中的备份信息
- **timestamp**: 备份时间戳（格式：YYYYMMDD_HHMMSS）
- **collection_file**: collection表备份文件名
- **embedding_file**: embedding表备份文件名
- **collection_size**: collection文件大小（可读格式）
- **embedding_size**: embedding文件大小（可读格式）
- **backup_date**: 备份日期（可读格式）
- **has_log**: 是否有备份日志文件
- **log_file**: 日志文件名

#### summary 汇总信息
- **total_locations**: 扫描到的备份位置总数
- **total_backup_sets**: 备份集总数
- **global_backups**: 全局备份数量
- **task_backups**: 任务备份数量
- **scan_time**: 扫描时间戳

## 🔄 API 2: 备份数据恢复

### 基本信息
- **端点**: `POST /api/v0/data_pipeline/vector/restore`
- **功能**: 从备份文件恢复vector表数据到PostgreSQL数据库
- **支持**: 全量恢复、部分表恢复、数据清空等选项

### 请求参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `backup_path` | string | ✅ | - | 备份文件目录路径（相对路径） |
| `timestamp` | string | ✅ | - | 备份时间戳（YYYYMMDD_HHMMSS格式） |
| `tables` | array | 否 | null | 要恢复的表名列表，空则恢复所有表 |
| `db_connection` | string | 否 | null | 自定义PostgreSQL连接字符串 |
| `truncate_before_restore` | boolean | 否 | false | 恢复前是否清空目标表 |

### 参数详细说明

#### backup_path（必填）
- **格式**: 相对路径，Unix风格斜杠
- **示例**: `"./data_pipeline/training_data/vector_bak"`
- **示例**: `"./data_pipeline/training_data/task_20250721_213627/vector_bak"`

#### timestamp（必填）
- **格式**: `YYYYMMDD_HHMMSS`
- **示例**: `"20250721_215758"`
- **说明**: 必须与备份文件名中的时间戳匹配

#### tables（可选）
- **格式**: 字符串数组
- **可选值**: `["langchain_pg_collection"]`, `["langchain_pg_embedding"]`, `["langchain_pg_collection", "langchain_pg_embedding"]`
- **默认**: `null`（恢复所有表）

#### db_connection（可选）
- **格式**: PostgreSQL连接字符串
- **示例**: `"postgresql://user:password@host:port/database"`
- **默认**: 使用配置文件中的连接信息

#### truncate_before_restore（可选）
- **类型**: 布尔值
- **默认**: `false`
- **说明**: 
  - `true`: 恢复前清空目标表（推荐用于生产环境）
  - `false`: 直接追加数据（可能导致主键冲突）

### 使用示例

#### 1. 基本恢复（推荐）
```bash
curl -X POST http://localhost:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/task_20250721_213627/vector_bak",
    "timestamp": "20250721_215758",
    "truncate_before_restore": true
  }'
```

#### 2. 仅恢复embedding表
```bash
curl -X POST http://localhost:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/vector_bak",
    "timestamp": "20250722_010318",
    "tables": ["langchain_pg_embedding"],
    "truncate_before_restore": false
  }'
```

#### 3. 使用自定义数据库连接
```bash
curl -X POST http://localhost:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/vector_bak",
    "timestamp": "20250722_010318",
    "db_connection": "postgresql://user:password@localhost:5432/target_db",
    "truncate_before_restore": true
  }'
```

### 响应格式

#### 成功响应
```json
{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {
    "response": "Vector表恢复完成",
    "restore_performed": true,
    "truncate_performed": true,
    "backup_info": {
      "backup_path": "./data_pipeline/training_data/task_20250721_213627/vector_bak",
      "timestamp": "20250721_215758",
      "backup_date": "2025-07-21 21:57:58"
    },
    "truncate_results": {
      "langchain_pg_collection": {
        "success": true,
        "rows_before": 4,
        "rows_after": 0,
        "duration": 0.025
      },
      "langchain_pg_embedding": {
        "success": true,
        "rows_before": 58,
        "rows_after": 0,
        "duration": 0.063
      }
    },
    "restore_results": {
      "langchain_pg_collection": {
        "success": true,
        "source_file": "langchain_pg_collection_20250721_215758.csv",
        "rows_restored": 4,
        "file_size": "209 B",
        "duration": 0.145
      },
      "langchain_pg_embedding": {
        "success": true,
        "source_file": "langchain_pg_embedding_20250721_215758.csv",
        "rows_restored": 58,
        "file_size": "764 KB",
        "duration": 0.678
      }
    },
    "errors": [],
    "duration": 0.911,
    "timestamp": "2025-07-22T10:35:20+08:00"
  }
}
```

### 响应字段说明

#### 顶层字段
- **restore_performed**: 是否执行了恢复操作
- **truncate_performed**: 是否执行了清空操作
- **backup_info**: 备份信息
- **truncate_results**: 清空操作结果
- **restore_results**: 恢复操作结果
- **errors**: 错误信息数组
- **duration**: 总耗时（秒）

#### truncate_results 字段
- **success**: 清空是否成功
- **rows_before**: 清空前的行数
- **rows_after**: 清空后的行数
- **duration**: 清空耗时（秒）

#### restore_results 字段
- **success**: 恢复是否成功
- **source_file**: 源CSV文件名
- **rows_restored**: 恢复的行数
- **file_size**: 文件大小（可读格式）
- **duration**: 恢复耗时（秒）
- **error**: 错误信息（仅失败时出现）

## ⚠️ 错误处理

### 常见错误类型

#### 1. 参数错误（400）
```json
{
  "code": 400,
  "success": false,
  "message": "请求参数错误",
  "data": {
    "response": "缺少必需参数: backup_path, timestamp",
    "error_type": "MISSING_REQUIRED_PARAMS",
    "missing_params": ["backup_path", "timestamp"],
    "timestamp": "2025-07-22T10:35:20+08:00"
  }
}
```

#### 2. 文件未找到（404）
```json
{
  "code": 404,
  "success": false,
  "message": "资源未找到",
  "data": {
    "response": "备份目录不存在: ./data_pipeline/training_data/nonexistent",
    "error_type": "RESOURCE_NOT_FOUND",
    "timestamp": "2025-07-22T10:35:20+08:00"
  }
}
```

#### 3. 数据库错误（500）
```json
{
  "code": 500,
  "success": false,
  "message": "系统内部错误",
  "data": {
    "response": "数据库连接失败，请稍后重试",
    "error_type": "DATABASE_ERROR",
    "timestamp": "2025-07-22T10:35:20+08:00"
  }
}
```

## 🎯 使用场景

### 1. 数据迁移
```bash
# 步骤1: 在源环境列出备份
curl "http://source-server:8084/api/v0/data_pipeline/vector/restore/list"

# 步骤2: 复制备份文件到目标环境（手动操作）
# scp source:/path/to/backups/* target:/path/to/backups/

# 步骤3: 在目标环境恢复数据
curl -X POST http://target-server:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/vector_bak",
    "timestamp": "20250722_010318",
    "truncate_before_restore": true
  }'
```

### 2. 数据回滚
```bash
# 步骤1: 查找回滚点
curl "http://localhost:8084/api/v0/data_pipeline/vector/restore/list?task_id=task_20250721_213627"

# 步骤2: 恢复到指定时间点
curl -X POST http://localhost:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/task_20250721_213627/vector_bak",
    "timestamp": "20250721_215758",
    "truncate_before_restore": true
  }'
```

### 3. 部分数据恢复
```bash
# 仅恢复embedding表，不影响collection表
curl -X POST http://localhost:8084/api/v0/data_pipeline/vector/restore \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "./data_pipeline/training_data/vector_bak",
    "timestamp": "20250722_010318",
    "tables": ["langchain_pg_embedding"],
    "truncate_before_restore": false
  }'
```

## 💡 最佳实践

### 1. 恢复前准备
- ✅ 确认目标数据库连接正常
- ✅ 如果是重要数据，建议先创建当前数据的备份
- ✅ 确认备份文件的完整性（collection和embedding文件都存在）
- ✅ 检查目标数据库的存储空间

### 2. 参数选择建议
- **生产环境**: 建议使用 `truncate_before_restore: true` 确保数据干净
- **测试环境**: 可以使用 `truncate_before_restore: false` 进行数据叠加测试
- **部分恢复**: 仅在明确知道影响范围时使用 `tables` 参数
- **跨环境**: 使用 `db_connection` 参数指定目标数据库

### 3. 监控和验证
- 📊 关注恢复操作的 `duration` 字段，了解性能表现
- 🔍 检查 `errors` 数组，确保没有恢复失败的表
- ✅ 验证 `rows_restored` 与预期的数据量一致
- 📝 查看备份日志文件了解备份时的状态

### 4. 故障排除
- 🔧 如果恢复失败，检查错误信息中的具体原因
- 🔐 确认数据库连接配置和权限设置
- 📁 验证备份文件的格式和完整性
- 🌐 检查网络连接和防火墙设置

## 📊 性能参考

根据测试，恢复性能参考：

| 数据量级 | Collection表 | Embedding表 | 总耗时 | 说明 |
|----------|-------------|-------------|--------|------|
| 小量数据（< 100行） | < 0.1s | < 0.7s | < 1s | 开发测试环境 |
| 中等数据（< 10K行） | < 0.5s | < 3s | < 4s | 小型生产环境 |
| 大量数据（< 100K行） | < 2s | < 15s | < 20s | 中型生产环境 |
| 超大数据（> 100K行） | < 10s | < 60s | < 80s | 大型生产环境 |

*注：实际性能取决于数据库配置、硬件性能和网络状况*

## 🔗 相关API

- **备份API**: `POST /api/v0/data_pipeline/vector/backup` - 创建vector表备份
- **健康检查**: `GET /health` - 检查API服务状态
- **训练数据API**: `/api/v0/training_data/*` - 训练数据管理

## 📞 技术支持

如果遇到问题，请检查：

1. **API服务状态**: 访问 `http://localhost:8084/health`
2. **数据库连接**: 检查连接字符串和权限
3. **文件权限**: 确保API有读取备份文件的权限
4. **日志文件**: 查看 `logs/app.log` 了解详细错误信息

---

**文档版本**: v1.0  
**最后更新**: 2025-07-22  
**适用版本**: unified_api.py v1.0+ 