数据导入导出

Claude Code Hub 提供完整的数据导入导出功能，支持数据库备份恢复、价格表同步和批量数据操作。该系统采用分布式锁、事务保护和全面验证等企业级安全机制，确保数据操作的完整性。

数据库备份导出

导出接口

端点：GET /api/admin/database/export?excludeLogs=true

系统使用 pg_dump 创建 PostgreSQL 自定义格式（压缩）备份。

文件命名规则：

backup_2025-01-29T10-30-00.dump
backup_2025-01-29T10-30-00_no-logs.dump  // 排除日志时

导出特性

• 流式响应：支持大型数据库的流式传输
• 日志排除：可选择排除 message_request 表数据，保留表结构
• 分布式锁：Redis 分布式锁防止并发操作，锁超时 5 分钟

数据库备份导入

导入接口

端点：POST /api/admin/database/import

导入模式

合并模式 (cleanFirst=false)：

• 导入数据不清空现有数据
• 适用于增量恢复

覆盖模式 (cleanFirst=true)：

• 使用 --clean --if-exists --no-owner 参数
• 先删除现有对象再创建
• 适用于完整恢复

进度反馈

导入过程通过 Server-Sent Events (SSE) 实时推送进度：

interface ImportProgressEvent {
  type: "progress" | "complete" | "error";
  message: string;
  exitCode?: number;
}

错误处理

系统智能分类恢复错误：

可忽略错误（不影响导入成功）：

• 对象已存在
• 重复主键
• 重复键值
• 角色不存在

致命错误（导致导入失败）：

• 连接失败
• 认证失败
• 权限拒绝
• 数据库不存在
• 内存不足
• 磁盘已满

价格表导入

支持格式

系统自动检测格式：先尝试 JSON 解析，失败后尝试 TOML 解析。

导入方式

1. 手动上传：通过 Web UI 上传价格表文件
2. 手动同步：管理员触发从云端同步
3. 自动同步：后台服务定期同步云端价格表

冲突处理

• 默认保留手动设置的价格
• 可通过 overwriteManual 参数指定覆盖特定手动价格
• 系统追踪价格来源（litellm 或 manual）

批量操作

供应商批量操作

最大批量：500 个供应商

用户批量操作

最大批量：500 个用户

可更新字段：

• note：备注
• tags：标签
• rpm：每分钟请求限制
• dailyQuota：每日配额
• limit5hUsd：5小时消费限额
• limitWeeklyUsd：周消费限额
• limitMonthlyUsd：月消费限额

密钥批量操作

最大批量：500 个密钥

可更新字段：

• providerGroup：供应商分组
• limit5hUsd：5小时消费限额
• limitDailyUsd：日消费限额
• limitWeeklyUsd：周消费限额
• limitMonthlyUsd：月消费限额
• canLoginWebUi：是否允许登录 Web UI
• isEnabled：是否启用

并发控制

分布式锁

系统使用 Redis 分布式锁防止并发备份操作：

锁策略：

1. 优先使用 Redis 分布式锁（支持多实例部署）
2. Redis 不可用时降级为内存锁（单实例安全）
3. 使用 Lua 脚本确保原子性 SET NX PX 操作

并发冲突响应

当其他管理员正在执行备份操作时，返回 HTTP 409：

{
  "error": "其他管理员正在执行备份操作，请稍后重试",
  "details": "为确保数据一致性，同一时间只能执行一个备份操作"
}

临时文件管理

系统自动管理导入过程中的临时文件：

请求取消处理：

• 用户关闭浏览器时触发清理
• 自动删除临时文件
• 释放分布式锁

环境配置

数据库连接

# PostgreSQL 连接字符串
DSN=postgresql://user:password@host:port/database

解析后的配置：

最佳实践

备份策略

1. 定期备份：建议每日执行完整备份
2. 日志分离：生产环境建议使用 excludeLogs=true 减小备份体积
3. 异地存储：将备份文件存储到独立存储系统

恢复策略

1. 测试恢复：定期在测试环境验证备份可恢复性
2. 合并优先：非必要情况下使用合并模式，避免数据丢失
3. 监控进度：通过 SSE 事件监控恢复进度

批量操作

1. 分批执行：超过 500 条记录时分批处理
2. 事务保护：批量操作自动使用事务，失败时完整回滚
3. 验证优先：操作前验证数据完整性约束

相关文档

• 系统设置 - 了解系统配置选项
• 用户管理 - 了解用户和密钥管理
• 供应商管理 - 了解供应商配置