django-sync-db 1.0.0
Production-ready Django database synchronization with streaming processing, data deduplication, and multi-database support
License: MIT
Requires Python: >=3.8
Keywords: async, database, django, migration, synchronization

# Django数据库同步系统

一个生产就绪的Django数据库同步应用，支持流式处理、数据去重、多数据库类型和完整的错误恢复机制。

## 版本信息

### v1.0.0 (2025-12-02) - 重大版本更新

**🎉 生产就绪版本发布**

#### 重大改进：
- **🔧 架构重构**: 解决了7个关键设计缺陷，从"硬伤"版本升级为生产就绪版本
- **🚀 流式处理**: 实现内存优化的流式查询，支持大数据量同步不溢出
- **🔄 数据去重**: 使用`update_or_create()`自动去重，避免重复数据
- **🔒 线程安全**: 乐观锁机制确保并发环境下的数据一致性
- **⚡ 断点续传**: 支持任务中断后从断点恢复，提高同步可靠性
- **📊 模型统一**: 合并冗余的`SyncTask`和`DailySyncTask`模型
- **🛡️ 错误恢复**: 增强的错误处理和自动重试机制

#### 技术特性：
- **多数据库支持**: MySQL、PostgreSQL、MongoDB、SQLite、Microsoft SQL Server (2008+)
- **灵活的字段映射**: 可配置外部字段到本地字段的映射关系
- **自定义SQL支持**: 支持复杂查询和统计数据的同步
- **异步任务队列**: 基于Celery的可靠任务执行
- **详细日志记录**: 记录每次同步的详细状态和执行信息
- **Admin后台管理**: 完整的Django Admin管理界面，带详细帮助信息

## 功能特性

### 核心功能
- **多数据库支持**: MySQL、PostgreSQL、MongoDB、SQLite、Microsoft SQL Server (2008+)
- **灵活的字段映射**: 可配置外部字段到本地字段的映射关系
- **SQL筛选**: 支持自定义SQL条件筛选数据
- **异步任务队列**: 基于Celery的可靠任务执行
- **详细日志记录**: 记录每次同步的详细状态和执行信息
- **Admin后台管理**: 完整的Django Admin管理界面
- **Web管理界面**: 现代化的Bootstrap界面

### 高级功能
- **每日任务拆分**: 自动将大时间范围的同步任务拆分为每日任务
- **任务重试机制**: 支持失败任务的自动重试
- **实时进度监控**: 实时显示同步任务进度
- **统计报表**: 提供任务执行统计和成功率分析
- **连接测试**: 支持数据库连接和表映射配置测试

## 系统架构

```
Django同步系统
├── 外部数据库连接层
│   ├── MySQL连接器
│   ├── PostgreSQL连接器
│   ├── MongoDB连接器
│   └── SQLite连接器
├── 数据映射层
│   ├── 字段映射配置
│   ├── SQL条件筛选
│   └── 数据转换
├── 任务调度层
│   ├── Celery任务队列
│   ├── 每日任务拆分
│   └── 重试机制
└── 监控管理层
    ├── Admin后台
    ├── Web界面
    ├── 日志系统
    └── 统计报表
```

## 安装部署

### 1. 环境要求
- Python 3.8+
- Redis (用于Celery消息队列)
- 数据库 (SQLite/MySQL/PostgreSQL)

### 2. 安装依赖
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 2.1. MSSQL支持 (可选)
如果需要连接Microsoft SQL Server，请确保安装了ODBC驱动：

**Windows:**
```bash
# 下载并安装 Microsoft ODBC Driver for SQL Server
# https://docs.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server
```

**Linux (Ubuntu/Debian):**
```bash
# 添加微软仓库
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
sudo apt-add-repository "$(curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list)"
sudo apt-get update

# 安装ODBC驱动
sudo apt-get install -y unixodbc-dev
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql17
```

### 3. 配置数据库
编辑 `src/project/settings.py` 文件，配置数据库连接：

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}
```

### 4. 配置Redis
确保Redis服务运行，并更新settings.py中的Celery配置：

```python
CELERY_BROKER_URL = 'redis://localhost:6379/0'
CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'
```

### 5. 数据库迁移
```bash
cd src
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
```

### 6. 启动服务

#### 启动Django开发服务器
```bash
cd src
python manage.py runserver
```

#### 启动Celery Worker
```bash
cd src
celery -A project worker -l info
```

#### 启动Celery Beat (定时任务)
```bash
cd src
celery -A project beat -l info
```

#### 启动Flower (监控界面，可选)
```bash
cd src
celery -A project flower
```

## 使用指南

### 1. 配置外部数据库
1. 访问Admin后台: http://localhost:8000/admin/
2. 进入"外部数据库"管理页面
3. 添加数据库连接配置：
   - 数据库名称
   - 数据库类型 (MySQL/PostgreSQL/MongoDB/SQLite)
   - 连接信息 (主机、端口、用户名、密码等)

### 2. 创建表映射
1. 进入"表映射"管理页面
2. 创建新的映射配置：
   - 选择外部数据库
   - 输入外部表名
   - 输入本地模型名
   - 配置字段映射 (JSON格式: {"外部字段": "本地字段"})
   - 设置筛选SQL条件 (可选)

### 3. 启动同步任务
#### 方式一: 通过Web界面
1. 访问同步任务页面
2. 点击"启动同步"
3. 设置时间范围
4. 选择是否创建每日任务

#### 方式二: 通过Admin后台
1. 进入表映射管理
2. 选择要同步的表
3. 执行"启动选中表同步"操作

### 4. 监控任务执行
- **仪表板**: 查看总体统计信息
- **任务列表**: 查看所有同步任务状态
- **任务详情**: 查看具体任务的执行日志和进度
- **同步日志**: 查看详细的执行日志

## 配置示例

### 外部数据库配置示例

**MySQL示例:**
```json
{
    "name": "生产数据库",
    "db_type": "mysql",
    "host": "192.168.1.100",
    "port": 3306,
    "database_name": "production",
    "username": "sync_user",
    "password": "password123",
    "extra_params": {
        "charset": "utf8mb4",
        "connect_timeout": 30
    }
}
```

**MSSQL示例:**
```json
{
    "name": "MSSQL数据库",
    "db_type": "mssql",
    "host": "192.168.1.100",
    "port": 1433,
    "database_name": "production",
    "username": "sa",
    "password": "password123",
    "extra_params": {
        "driver": "ODBC Driver 17 for SQL Server",
        "timeout": 30,
        "encrypt": "no",
        "connection_timeout": 30
    }
}
```

**MSSQL 2008特殊配置:**
```json
{
    "name": "MSSQL 2008数据库",
    "db_type": "mssql",
    "host": "192.168.1.100",
    "port": 1433,
    "database_name": "production",
    "username": "sa",
    "password": "password123",
    "extra_params": {
        "driver": "SQL Server Native Client 10.0",
        "timeout": 30,
        "encrypt": "no"
    }
}
```

### 字段映射配置示例
```json
{
    "external_table": "orders",
    "local_model": "Order",
    "field_mapping": {
        "order_id": "id",
        "order_no": "order_number",
        "create_time": "created_at",
        "update_time": "updated_at",
        "customer_name": "customer.name",
        "total_amount": "amount"
    },
    "filter_sql": "status = 'completed' AND create_time >= '2024-01-01'"
}
```

## API接口

### 测试数据库连接
```http
POST /sync/databases/{db_id}/test/
```

### 获取表字段信息
```http
GET /sync/databases/{db_id}/columns/?table_name=table_name
```

### 启动同步任务
```http
POST /sync/tasks/start/
Content-Type: application/json

{
    "mapping_id": 1,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}
```

### 获取任务状态
```http
GET /sync/api/task/{task_id}/status/
```

### 获取统计信息
```http
GET /sync/api/statistics/
```

## 任务队列管理

### Celery任务类型
1. **test_connection**: 测试数据库连接
2. **start_sync_task**: 启动同步任务
3. **create_daily_sync_tasks**: 创建每日同步任务
4. **execute_daily_sync**: 执行每日同步任务
5. **cleanup_old_logs**: 清理旧日志
6. **retry_failed_daily_tasks**: 重试失败任务

### 定时任务配置
```python
CELERY_BEAT_SCHEDULE = {
    'daily-cleanup': {
        'task': 'django_sync_db.tasks.schedule_daily_cleanup',
        'schedule': 60.0 * 60.0 * 24.0,  # 每天执行一次
    },
    'daily-retry': {
        'task': 'django_sync_db.tasks.schedule_daily_retry',
        'schedule': 60.0 * 60.0 * 2.0,  # 每2小时执行一次
    },
}
```

## 日志管理

### 日志级别
- **INFO**: 一般信息
- **WARNING**: 警告信息
- **ERROR**: 错误信息
- **DEBUG**: 调试信息

### 日志存储
- 数据库存储: 通过SyncLog模型
- 文件存储: 配置在`logs/django_sync_db.log`

## 性能优化

### 建议配置
1. **批量处理**: 默认每批处理1000条记录
2. **并发控制**: Celery worker并发数根据服务器配置调整
3. **内存管理**: 大数据量同步建议分时段执行
4. **索引优化**: 确保外部表查询字段有适当索引

### 监控指标
- 任务执行时间
- 成功率
- 错误率
- 数据处理量

## 故障排除

### 常见问题
1. **连接失败**: 检查网络连接和数据库权限
2. **字段映射错误**: 验证字段名和类型匹配
3. **任务卡住**: 检查Celery worker状态
4. **内存不足**: 调整批量处理大小
5. **MSSQL连接问题**: 
   - 确保安装了正确的ODBC驱动
   - 检查SQL Server Browser服务是否运行
   - 验证防火墙设置（1433端口）
   - 对于MSSQL 2008，使用"SQL Server Native Client 10.0"驱动

### 调试方法
1. 查看Django日志: `logs/django_sync_db.log`
2. 查看Celery日志: 启动时添加`-l debug`
3. 使用Flower监控任务状态
4. 检查数据库连接和权限

## 安全考虑

1. **密码安全**: 数据库密码加密存储
2. **网络访问**: 限制数据库访问IP
3. **权限控制**: 最小权限原则
4. **日志脱敏**: 避免敏感信息记录到日志

## 扩展开发

### 添加新数据库类型
1. 在`services.py`中添加连接逻辑
2. 更新模型中的DB_TYPE_CHOICES
3. 添加相应的查询和字段获取方法

### 自定义任务处理
1. 继承DataSyncService类
2. 重写数据转换方法
3. 添加自定义验证逻辑

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 联系方式

如有问题，请通过以下方式联系：
- 邮箱: 276069869@qq.com
- GitHub: [项目地址]