# db27z

**Repository Path**: fengleer/db27z

## Basic Information

- **Project Name**: db27z
- **Description**: db27z - Modern MySQL Database Backup & Restore Solution
A high-performance, reliable MySQL database backup and restore tool written in Go.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# db27z - 现代化数据库备份与还原工具

[**English**](README_EN.md) | 中文

[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go)](https://golang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0--alpha-orange.svg)](https://github.com/db27z/db27z)

## 📋 项目简介

db27z 是一个现代化、高效、可扩展的数据库备份与还原解决方案，支持 MySQL 数据库的全量备份和快速还原，具有实时进度监控、高压缩比、跨平台支持等特性。

**✨ 核心特性：双工具架构**

- **db27z** - 数据库备份工具
- **7z2db** - 数据库还原工具

## ✨ 主要特性

### 备份功能 (db27z)

- ✅ 支持 MySQL 数据库的全量备份
- ✅ 完整备份表结构、数据等所有内容
- ✅ 实时进度监控和 ETA 计算
- ✅ 使用 Zip 压缩算法，节省存储空间
- ✅ 跨平台支持（Windows、Linux、macOS）
- ✅ 灵活的配置管理（命令行、环境变量、配置文件）

### 还原功能 (7z2db)

- ✅ 多种还原模式（删除重建、跳过已存在、合并模式）
- ✅ 灵活的还原选项（仅结构、仅数据、指定表）
- ✅ 高级错误处理（错误容忍、阈值控制）
- ✅ 性能优化（批处理、外键控制）
- ✅ 还原验证（行数对比、抽样检查）
- ✅ 模拟运行模式（dry-run）

## 🛠️ 技术栈

- **语言**: Go 1.21+
- **数据库驱动**: go-sql-driver/mysql
- **CLI 框架**: cobra
- **配置管理**: viper
- **压缩格式**: ZIP (archive/zip)

## 📁 项目结构

```
db27z/
├── cmd/                      # 命令行入口
│   ├── backup/               # 备份命令 (db27z)
│   └── restore/              # 还原命令 (7z2db)
│
├── pkg/                      # 核心代码包
│   ├── adapter/              # 数据库适配器
│   ├── backup/               # 备份引擎
│   ├── config/               # 配置管理
│   ├── monitor/              # 进度监控
│   ├── restore/              # 还原引擎
│   └── storage/              # 存储引擎
│
├── internal/                 # 内部库
│   └── workerpool/           # 工作池
│
├── docs/                     # 📖 文档目录
│   ├── getting-started/      # 入门文档
│   ├── user-guide/           # 用户指南
│   ├── architecture/         # 架构文档
│   ├── development/          # 开发文档
│   ├── tools/                # 工具文档
│   ├── spec/                 # 技术规格
│   └── proposals/            # 提案
│
├── examples/                 # 💡 使用示例
│   ├── backup/               # 备份示例脚本
│   ├── restore/              # 还原示例脚本
│   └── config/               # 配置示例
│
├── tests/                    # 🧪 测试文件
│   ├── integration/          # 集成测试
│   ├── unit/                 # 单元测试
│   ├── fixtures/             # 测试数据
│   └── results/              # 测试结果
│
├── scripts/                  # 🔧 辅助脚本
│   └── tools/                # 开发工具
│
├── configs/                  # ⚙️ 配置模板
│   └── config.yaml.example
│
├── .github/                  # GitHub 配置
│   ├── ISSUE_TEMPLATE/       # Issue 模板
│   └── PULL_REQUEST_TEMPLATE.md
│
├── bin/                      # 编译后的二进制文件
├── LICENSE                   # MIT 许可证
├── CONTRIBUTING.md           # 贡献指南
├── CHANGELOG.md              # 变更日志
├── README.md                 # 本文件
├── Makefile                  # 构建脚本
├── go.mod
└── go.sum
```

## 🚀 快速开始

### 安装

#### 从源码编译

```bash
# 克隆仓库
git clone https://github.com/db27z/db27z.git
cd db27z

# 下载依赖
go mod tidy

# 编译备份工具
go build -o bin/db27z ./cmd/backup

# 编译还原工具
go build -o bin/7z2db ./cmd/restore

# 可选：安装到 PATH
sudo cp bin/db27z /usr/local/bin/
sudo cp bin/7z2db /usr/local/bin/
```

### 配置文件

创建配置文件（从示例复制）:

```bash
# 复制示例配置
cp configs/config.yaml.example config.yaml

# 编辑配置文件
vim config.yaml
```

或创建 `config.yaml`:

```yaml
# 数据库配置
database:
  host: localhost
  port: 3306
  username: root
  password: ""
  charset: utf8mb4
  timeout: 30

# 备份配置
backup:
  output_dir: ./backups
  compression_level: 5
  threads: 4

# 还原配置
restore:
  mode: drop
  skip_errors: false
  max_errors: 100
  batch_size: 1000
  disable_foreign_keys: false

# 日志配置
logging:
  level: info
  format: console
```

## 📦 备份数据库 (db27z)

### 基本用法

```bash
# 备份数据库
./bin/db27z backup \
  -H localhost \
  -P 3306 \
  -u root \
  -p password \
  -d mydb \
  -o ./backups
```

### 使用环境变量

```bash
export DATABASE_HOST=localhost
export DATABASE_PORT=3306
export DATABASE_USER=root
export DATABASE_PASSWORD=password
export DATABASE_NAME=mydb

./bin/db27z backup -d mydb -o ./backups
```

### 命令行选项

| 参数 | 说明 | 必需 | 默认值 |
|------|------|------|--------|
| `-H, --host` | 数据库主机 | 否 | localhost |
| `-P, --port` | 端口 | 否 | 3306 |
| `-u, --user` | 用户名 | 否 | root |
| `-p, --password` | 密码 | 否 | - |
| `-d, --database` | 数据库名 | **是** | - |
| `-o, --output` | 输出目录 | 否 | ./backups |
| `-c, --config` | 配置文件路径 | 否 | - |

### 备份输出示例

```
🚀 Starting full backup for database: prodct-vue3-admin
📡 Connecting to 127.0.0.1:3306...
✓ Connected successfully
📊 Retrieving table metadata...
✓ Found 51 tables
📝 Exporting database schema...
✓ Schema exported
💾 Exporting table data...
[████████████████████████████████████████] 100.0% (560559/560559) ETA: 00:00:00
✓ Data export completed
🗜️  Compressing backup...
============================================================
✓ Backup completed successfully!
  Database:    prodct-vue3-admin
  Tables:      51
  Total Rows:  560559
  File:        ./backups/prodct-vue3-admin_full_20260129_210038.zip
  Size:        36.00 MB
  Duration:    12s
============================================================
```

## 🔄 还原数据库 (7z2db)

### 基本用法

```bash
# 还原数据库（删除并重建）
./bin/7z2db \
  -i ./backups/mydb_full_20260129.zip \
  -d mydb_restored \
  -H localhost \
  -P 3306 \
  -u root \
  -p password
```

### 还原模式

#### 1. 删除重建模式（默认）

```bash
# 如果数据库存在，先删除再重建
./bin/7z2db -i backup.zip -d mydb --mode drop
```

#### 2. 跳过模式

```bash
# 如果数据库已存在，则跳过
./bin/7z2db -i backup.zip -d mydb --mode skip
```

#### 3. 合并模式

```bash
# 合并到现有数据库（不删除现有表）
./bin/7z2db -i backup.zip -d mydb --mode merge
```

### 灵活的还原选项

#### 仅还原结构

```bash
./bin/7z2db -i backup.zip -d mydb --schema-only
```

#### 仅还原数据

```bash
./bin/7z2db -i backup.zip -d mydb --data-only
```

#### 还原指定表

```bash
./bin/7z2db -i backup.zip -d mydb --tables users,orders,products
```

#### 模拟运行（不实际执行）

```bash
./bin/7z2db -i backup.zip -d mydb --dry-run
```

### 高级选项

#### 错误容忍

```bash
# 遇到错误继续执行，最多允许 500 个错误
./bin/7z2db -i backup.zip -d mydb --skip-errors --max-errors 500
```

#### 性能优化

```bash
# 使用更大的批处理大小，禁用外键检查
./bin/7z2db -i backup.zip -d mydb --batch-size 5000 --disable-fk
```

#### 还原后验证

```bash
# 还原后进行验证（10% 抽样）
./bin/7z2db -i backup.zip -d mydb --verify --sample-ratio 0.1
```

### 命令行选项

| 参数 | 说明 | 必需 | 默认值 |
|------|------|------|--------|
| `-i, --input` | 输入备份文件 | **是** | - |
| `-d, --database` | 目标数据库名 | **是** | - |
| `--mode` | 数据库处理模式 | 否 | drop |
| `--schema-only` | 仅还原结构 | 否 | false |
| `--data-only` | 仅还原数据 | 否 | false |
| `--tables` | 指定表（逗号分隔） | 否 | - |
| `--skip-errors` | 遇到错误继续 | 否 | false |
| `--max-errors` | 最大错误数 | 否 | 100 |
| `--batch-size` | 批处理大小 | 否 | 1000 |
| `--disable-fk` | 禁用外键检查 | 否 | false |
| `--verify` | 还原后验证 | 否 | false |
| `--dry-run` | 模拟运行 | 否 | false |

### 还原输出示例

```
🚀 Starting database restore
📁 Input file: backups/prodct-vue3-admin_full_20260129.zip
🎯 Target database: test_restore
🔧 Mode: drop

📦 Opening archive file...
✓ Archive opened and validated

📡 Connecting to database server at localhost:3306...
✓ Connected successfully

🗑️  Dropping existing database: test_restore
🔨 Creating database: test_restore

📝 Restoring database schema...
[████████████████████████░░░░░░] 80.0% (41/51) ETA: 00:00:05
✓ Schema restored (51 tables)

💾 Restoring table data...
[████████████████████████████] 100.0% (51/51) ETA: 00:00:00
✓ Data restored (560559 rows)

========================================
           Restore Report
========================================
  Status:      ✅ Completed successfully
  Duration:    2m15s

  Tables:
    Total:     51
    Restored:  51
    Skipped:   0

  Rows:
    Restored:  560559

  Errors:      0
========================================
```

## 📊 备份文件结构

备份文件采用 ZIP 格式，包含以下内容：

```
prodct-vue3-admin_full_20260129_210038.zip
├── schema.sql           # 数据库结构（CREATE TABLE 语句）
├── metadata.json        # 备份元数据（可选）
└── data/                # 数据文件目录
    ├── auth_group.sql
    ├── auth_permission.sql
    ├── cp_system_users.sql
    └── ...              # 每个表一个文件
```

每个数据文件包含 INSERT 语句：

```sql
INSERT INTO `cp_system_users` (`id`, `username`, `email`) VALUES (1,'admin','admin@example.com');
INSERT INTO `cp_system_users` (`id`, `username`, `email`) VALUES (2,'user','user@example.com');
```

## 🎯 使用场景

### 场景 1：日常备份

```bash
# 每日备份脚本
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
./bin/db27z backup -d production -o /backup/daily --config /etc/db27z/config.yaml
# 保留最近 7 天的备份
find /backup/daily -name "*.zip" -mtime +7 -delete
```

### 场景 2：数据库迁移

```bash
# 1. 在源服务器备份
./bin/db27z backup -d source_db -o ./migrate

# 2. 传输到目标服务器
scp ./migrate/source_db_full_*.zip user@target-server:/tmp/

# 3. 在目标服务器还原
./bin/7z2db -i /tmp/source_db_full_*.zip -d source_db --mode drop
```

### 场景 3：开发环境同步

```bash
# 从生产环境备份
./bin/db27z backup -d production -o ./sync

# 还原到开发环境
./bin/7z2db -i ./sync/production_full_*.zip -d development --mode drop
```

### 场景 4：灾难恢复

```bash
# 1. 验证备份文件完整性
unzip -t backup.zip

# 2. 模拟还原（不实际执行）
./bin/7z2db -i backup.zip -d test_restore --dry-run

# 3. 实际还原
./bin/7z2db -i backup.zip -d production --mode drop --verify
```

### 场景 5：选择性还原

```bash
# 仅还原用户相关表
./bin/7z2db -i backup.zip -d dev_db \
  --tables users,user_profiles,user_permissions \
  --mode merge
```

## 🔧 验证与测试

### 验证备份文件

```bash
# 查看备份内容
unzip -l backup.zip

# 检查 schema
unzip -p backup.zip schema.sql | head -50

# 测试归档读取
go run test_archive.go
```

### 验证还原结果

```bash
# 比较表数量
mysql -u root -p -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='mydb'"

# 比较行数
mysql -u root -p -e "SELECT table_name, table_rows FROM information_schema.tables WHERE table_schema='mydb'"
```

## ⚡ 性能指标

### 备份性能 (db27z)

- **备份速度**: ≥ 50MB/s（取决于硬件）
- **压缩比**: 约 70-90%
- **内存占用**: ≤ 512MB
- **并发支持**: 支持多线程处理

### 还原性能 (7z2db)

- **还原速度**: ≥ 10,000 rows/sec
- **内存占用**: ≤ 512MB
- **进度更新**: ≤ 1 秒延迟
- **批处理优化**: 可配置批次大小

## 🌍 环境变量支持

### 备份工具 (db27z)

- `DATABASE_HOST`: 数据库主机
- `DATABASE_PORT`: 数据库端口
- `DATABASE_USER`: 数据库用户名
- `DATABASE_PASSWORD`: 数据库密码
- `DATABASE_NAME`: 数据库名称

### 还原工具 (7z2db)

- `DATABASE_HOST`: 数据库主机
- `DATABASE_PORT`: 数据库端口
- `DATABASE_USER`: 数据库用户名
- `DATABASE_PASSWORD`: 数据库密码

## 📝 配置优先级

配置读取优先级（从高到低）：

1. 命令行参数
2. 环境变量
3. 配置文件
4. 默认值

## 🗺️ 路线图

### v1.0.0-alpha (当前版本)
- ✅ MySQL 全量备份
- ✅ 完整还原功能
- ✅ 实时进度监控
- ✅ ZIP 压缩
- ✅ 命令行接口
- ✅ 多种还原模式

### v1.1.0 (计划中)
- [ ] 增量备份（基于 Binlog）
- [ ] 备份加密
- [ ] 云存储支持（S3、OSS、COS）
- [ ] 定时任务支持
- [ ] Webhook 通知

### v2.0.0 (未来)
- [ ] PostgreSQL 支持
- [ ] Web UI 管理界面
- [ ] 分布式备份
- [ ] 备份版本管理
- [ ] 自动化测试套件

## ❓ 故障排除

### 备份问题

#### 连接失败

```
❌ Backup failed: failed to connect: connection refused
```

**解决方案**：
1. 检查 MySQL 服务是否运行
2. 验证主机和端口配置
3. 检查防火墙设置

#### 权限不足

```
❌ Backup failed: Access denied for user
```

**解决方案**：
```sql
GRANT SELECT ON *.* TO 'backup_user'@'localhost';
FLUSH PRIVILEGES;
```

### 还原问题

#### 数据库已存在

```
❌ database mydb already exists (use --mode drop to overwrite)
```

**解决方案**：
- 使用 `--mode drop` 覆盖现有数据库
- 或使用 `--mode merge` 合并到现有数据库
- 或选择不同的数据库名

#### 归档文件无效

```
❌ invalid archive: missing required file: schema.sql
```

**解决方案**：
1. 验证备份文件完整性：`unzip -t backup.zip`
2. 确认文件是由 db27z 创建的
3. 检查文件是否损坏

## 📚 文档

### 📖 文档导航

- [📘 快速入门](docs/getting-started/quickstart.md) - 5 分钟上手指南
- [📕 用户指南](docs/user-guide/) - 完整的使用文档
  - [备份指南](docs/user-guide/backup-guide.md) - 备份操作和策略
  - [还原指南](docs/user-guide/restore-guide.md) - 还原操作和模式
  - [配置参考](docs/user-guide/configuration.md) - 配置文件详解
  - [故障排除](docs/user-guide/troubleshooting.md) - 常见问题解决
- [📗 架构文档](docs/architecture/overview.md) - 系统架构与技术设计
- [📙 开发文档](docs/development/) - 测试和实现细节
- [📔 工具文档](docs/tools/7z2db.md) - 7z2db 还原工具说明
- [📓 技术规格](docs/spec/) - 详细的技术规格
- [📝 贡献指南](CONTRIBUTING.md) - 如何贡献代码
- [📋 变更日志](CHANGELOG.md) - 版本更新记录

### 🎯 快速链接

| 需求 | 文档 |
|------|------|
| 第一次使用 | [快速入门](docs/getting-started/quickstart.md) |
| 设置配置 | [配置参考](docs/user-guide/configuration.md) |
| 执行备份 | [备份指南](docs/user-guide/backup-guide.md) |
| 执行还原 | [还原指南](docs/user-guide/restore-guide.md) |
| 自动化备份 | [备份策略](docs/user-guide/backup-guide.md#备份策略) |
| 解决问题 | [故障排除](docs/user-guide/troubleshooting.md) |
| 了解架构 | [架构文档](docs/architecture/overview.md) |
| 贡献代码 | [贡献指南](CONTRIBUTING.md) |

### 💡 使用示例

查看 [examples/](examples/) 目录获取实用脚本：
- [基本备份示例](examples/backup/basic-backup.sh)
- [定时备份示例](examples/backup/scheduled-backup.sh)
- [基本还原示例](examples/restore/basic-restore.sh)
- [选择性还原示例](examples/restore/selective-restore.sh)
- [配置文件示例](examples/config/)

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

### 如何贡献

1. 阅读 [贡献指南](CONTRIBUTING.md)
2. Fork 本仓库
3. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
4. 提交更改 (`git commit -m 'feat: add some AmazingFeature'`)
5. 推送到分支 (`git push origin feature/AmazingFeature`)
6. 开启 Pull Request

### 贡献类型

- 🐛 报告 Bug
- 💡 提出新功能
- 📝 改进文档
- 🔧 提交代码
- ✅ 审查 Pull Request

查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解更多详情。

## 📄 许可证

MIT License

## 📧 联系方式

- **Issues**: [GitHub Issues](https://github.com/db27z/db27z/issues)
- **Discussions**: [GitHub Discussions](https://github.com/db27z/db27z/discussions)

---

**注意**: 这是 v1.0.0-alpha 版本，功能仍在开发中。建议在生产环境使用前进行充分测试。