# OCNGX 备份和恢复方案

## 概述

OCNGX（OpenCode + Nginx）备份和恢复方案支持在同一个版本的不同 HuggingFace Space 之间进行无缝迁移。该方案确保数据完整性、配置一致性和服务连续性。

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                     OCNGX System                          │
├─────────────────────────────────────────────────────────────┤
│  Frontend (Nginx:7860) │ Backend (OpenCode:3000)           │
├─────────────────────────────────────────────────────────────┤
│  配置文件                    │ 用户数据                      │
│  - opencode.json            │ - projects/                   │
│  - nginx/配置              │ - sessions/                   │
│  - AGENT.md                 │ - config/                     │
│  - 启动脚本                 │ - cache/                      │
├─────────────────────────────────────────────────────────────┤
│  运行时数据                   │ 日志                         │
│  - 进程状态                 │ - nginx日志                   │
│  - 网络连接                 │ - opencode日志                │
└─────────────────────────────────────────────────────────────┘
```

## 备份内容

### 1. 核心配置文件
- `opencode.json` - OpenCode 主配置
- `AGENT.md` - 系统代理配置
- `docker-start.sh` - 容器启动脚本
- `Dockerfile` - 容器构建文件
- `nginx/` - Nginx 配置目录
- `cron-jobs/` - 定时任务配置

### 2. OpenCode 数据
- `~/.opencode/projects/` - 项目数据
- `~/.opencode/sessions/` - 会话数据
- `~/.opencode/config/` - 用户配置
- `~/.opencode/cache/` - 缓存数据
- `~/.opencode/logs/` - 运行日志

### 3. 运行时状态
- 当前运行的进程信息
- 网络连接状态
- 最近的系统日志

### 4. 元数据
- 备份时间戳
- 环境信息
- 系统版本信息
- 磁盘使用情况

## 使用指南

### 1. 快速开始

#### 创建备份
```bash
# 执行完整备份
./backup-scripts/backup.sh

# 查看备份文件
ls -la /var/backups/ocngx/
```

#### 恢复系统
```bash
# 恢复到新环境
./backup-scripts/restore.sh /path/to/backup.tar.gz

# 强制覆盖现有配置
./backup-scripts/restore.sh --force backup.tar.gz

# 跳过配置文件恢复
./backup-scripts/restore.sh --skip-config backup.tar.gz
```

### 2. 部署到新环境

#### 自动配置部署环境
```bash
# 自动检测并配置当前环境
source deploy-config.sh
configure_for_deployment

# 验证配置
verify_configuration
```

#### 手动部署到 HuggingFace Spaces
```bash
# 1. 克隆项目到新 Space
git clone <项目地址> .
cd <项目目录>

# 2. 配置环境变量
export SPACE_ID="your-space-name"
export ADMIN_USERNAME="your-admin-user"
export ADMIN_PASSWORD="your-admin-password"

# 3. 自动配置
source deploy-config.sh
configure_for_deployment

# 4. 恢复数据（如果有备份）
./backup-scripts/restore.sh backup.tar.gz

# 5. 启动服务
docker-compose up -d
```

### 3. 使用 Docker Compose

#### 启动完整服务
```bash
# 使用默认配置启动
docker-compose up -d

# 使用自定义环境变量
OPENCODE_PUBLIC_URL=https://your-space.hf.space \
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f ocngx
```

#### 配置外部备份存储
```bash
# 创建 .env 文件
cat >> .env << EOF
BACKUP_S3_BUCKET=your-backup-bucket
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
EOF

# 启动包含备份服务的完整系统
docker-compose up -d
```

## 迁移流程

### 从 Source Space 到 Target Space

```bash
# 1. 在 Source Space 创建备份
ssh source-space
./backup-scripts/backup.sh

# 2. 下载备份文件
scp user@source-space:/var/backups/ocngx/latest.tar.gz ./

# 3. 在 Target Space 准备环境
git clone <项目仓库> target-space
cd target-space
export SPACE_ID="target-space-name"

# 4. 配置新环境
source deploy-config.sh
configure_for_deployment

# 5. 恢复数据
./backup-scripts/restore.sh latest.tar.gz

# 6. 启动服务
docker-compose up -d

# 7. 验证迁移
curl https://target-space.hf.space/health
```

## 备份策略

### 自动备份
- **频率**: 每日凌晨 2:00
- **保留**: 最近 10 个备份
- **压缩**: gzip 压缩
- **校验**: SHA256 校验和

### 手动备份
```bash
# 立即备份
./backup-scripts/backup.sh

# 指定备份目录
BACKUP_DIR=/custom/backup/path ./backup-scripts/backup.sh
```

### 外部存储集成
支持自动上传到 S3 存储：
```bash
# 配置 S3 环境变量
export BACKUP_S3_BUCKET="my-backup-bucket"
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# 备份时自动上传
./backup-scripts/backup.sh
```

## 故障恢复

### 恢复损坏的配置
```bash
# 恢复最近的备份
./backup-scripts/restore.sh --force /var/backups/ocngx/latest.tar.gz

# 重启服务
docker-compose restart ocngx
```

### 数据库损坏恢复
```bash
# 只恢复数据，跳过配置
./backup-scripts/restore.sh --skip-config backup.tar.gz

# 手动恢复特定数据
tar -xzf backup.tar.gz '*/opencode_data/*' -C /
```

### 回滚到之前版本
```bash
# 查看可用备份
ls -la /var/backups/ocngx/

# 恢复到指定版本
./backup-scripts/restore.sh /var/backups/ocngx/ocngx_backup_20240101_120000.tar.gz
```

## 监控和维护

### 健康检查
```bash
# 检查服务状态
curl http://localhost:7860/health

# 检查 OpenCode 状态
curl http://localhost:3000/global/health

# 检查备份状态
./backup-scripts/backup.sh --dry-run
```

### 日志监控
```bash
# Nginx 日志
tail -f logs/nginx/access.log
tail -f logs/nginx/error.log

# OpenCode 日志
tail -f ~/.opencode/logs/opencode.log

# 备份日志
tail -f logs/backup.log
```

### 磁盘空间管理
```bash
# 查看备份占用空间
du -sh /var/backups/ocngx/

# 清理旧备份
find /var/backups/ocngx -name "*.tar.gz" -mtime +30 -delete

# 查看系统磁盘使用
df -h
```

## 安全考虑

### 敏感数据处理
- 备份中不包含密码明文
- 环境变量中的敏感信息会被过滤
- 建议使用外部密钥管理服务

### 访问控制
```bash
# 设置备份文件权限
chmod 600 /var/backups/ocngx/*.tar.gz

# 限制恢复脚本执行权限
chmod 700 backup-scripts/restore.sh
```

### 网络安全
- 备份传输使用加密通道
- S3 上传使用服务器端加密
- 定期轮换访问密钥

## 故障排除

### 常见问题

#### 1. 备份失败
```bash
# 检查磁盘空间
df -h

# 检查文件权限
ls -la /var/backups/

# 查看详细错误
./backup-scripts/backup.sh --debug
```

#### 2. 恢复失败
```bash
# 验证备份文件完整性
sha256sum -c backup.tar.gz.sha256

# 检查目标环境
./backup-scripts/restore.sh --dry-run backup.tar.gz

# 强制恢复
./backup-scripts/restore.sh --force backup.tar.gz
```

#### 3. 服务启动失败
```bash
# 检查配置文件
docker-compose config

# 查看容器日志
docker-compose logs ocngx

# 重新构建容器
docker-compose up -d --build
```

## 最佳实践

### 1. 定期测试恢复
```bash
# 每月测试一次恢复流程
./backup-scripts/backup.sh
./backup-scripts/restore.sh --test /var/backups/ocngx/latest.tar.gz
```

### 2. 版本控制
```bash
# 记录每次重要变更
git tag -a "v1.0.0-backup" -m "Backup before migration"
```

### 3. 文档更新
- 记录每次迁移过程
- 更新配置变更
- 维护故障处理文档

## 技术支持

如遇到问题，请提供以下信息：
1. 错误日志
2. 系统环境信息
3. 备份文件元数据
4. 具体操作步骤

联系支持：创建 Issue 并附上相关日志文件。