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. 安装依赖

# 创建虚拟环境
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:

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

Linux (Ubuntu/Debian):

# 添加微软仓库
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 文件，配置数据库连接：

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

4. 配置Redis

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

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

5. 数据库迁移

cd src
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser

6. 启动服务

启动Django开发服务器

cd src
python manage.py runserver

启动Celery Worker

cd src
celery -A project worker -l info

启动Celery Beat (定时任务)

cd src
celery -A project beat -l info

启动Flower (监控界面，可选)

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示例:

{
    "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示例:

{
    "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特殊配置:

{
    "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"
    }
}

字段映射配置示例

{
    "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接口

测试数据库连接

POST /sync/databases/{db_id}/test/

获取表字段信息

GET /sync/databases/{db_id}/columns/?table_name=table_name

启动同步任务

POST /sync/tasks/start/
Content-Type: application/json

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

获取任务状态

GET /sync/api/task/{task_id}/status/

获取统计信息

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: 重试失败任务

定时任务配置

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: [项目地址]