https://github.com/caomeiyouren/auto-backup-database

服务器数据库自动备份方案，支持本地备份和异地备份
https://github.com/caomeiyouren/auto-backup-database

backup database mongodb mysql postgresql sqlite typescript

Last synced: 3 months ago
JSON representation

服务器数据库自动备份方案，支持本地备份和异地备份

Host: GitHub
URL: https://github.com/caomeiyouren/auto-backup-database
Owner: CaoMeiYouRen
License: mit
Created: 2026-02-24T15:41:10.000Z (4 months ago)
Default Branch: master
Last Pushed: 2026-03-26T07:22:02.000Z (3 months ago)
Last Synced: 2026-03-27T02:34:26.888Z (3 months ago)
Topics: backup, database, mongodb, mysql, postgresql, sqlite, typescript
Language: TypeScript
Homepage:
Size: 549 KB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

README

auto-backup-database

Version

> 服务器数据库自动备份方案，支持本地备份和异地备份（OSS/S3）

## 功能特性

- **多数据库支持**: SQLite、MongoDB、PostgreSQL、MySQL
- **Glob 匹配**: 支持 Glob 语法批量匹配数据库文件
- **压缩加密**: 自动压缩备份文件，支持可选的密码加密
- **本地 + 远程存储**: 同时支持本地备份和 OSS/S3 远程备份
- **生命周期管理**: 按天数和总大小自动清理旧备份
- **定时调度**: 基于 Cron 表达式的定时任务调度
- **消息通知**: 支持多种推送渠道（微信、钉钉、飞书等）

## 依赖要求

- Node.js >= 20
- tar（用于压缩）
- openssl（用于加密，可选）
- MongoDB Database Tools（仅在启用 MongoDB 备份时需要；Docker 镜像内已预装，宿主机部署需自行安装并确保 `mongodump` 可执行）
- MySQL Client Tools（仅在启用 MySQL 备份时需要；Docker 镜像内已预装，宿主机部署需自行安装并确保 `mysqldump` 可执行）
- PostgreSQL Client Tools（仅在启用 PostgreSQL 备份时需要；Docker 镜像内已预装，宿主机部署需自行安装并确保 `pg_dump` 可执行）

## 安装

```bash
# 使用 pnpm
pnpm install

# 使用 npm
npm install
```

## 配置

### 1. 创建配置文件 `config.yml`

```yaml
oss:
region: "${OSS_REGION}"
accessKeyId: "${OSS_ACCESS_KEY_ID}"
accessKeySecret: "${OSS_ACCESS_KEY_SECRET}"
bucket: "${OSS_BUCKET}"
endpoint: "${OSS_ENDPOINT}"

security:
backupPassword: "${BACKUP_PASSWORD}"

projects:
- name: my-app-db
dbType: sqlite
dbPath: "/data/apps/my-app/*.db" # 支持 Glob 语法
backupSchedule: "0 2 * * *" # 每天凌晨 2 点
compress:
enabled: true
password: true # 使用环境变量中的 BACKUP_PASSWORD 加密
retention:
local:
days: 7
maxSize: 2GB
remote:
days: 30
maxSize: 10GB
options:
localEnabled: true
remoteEnabled: true

- name: mongo-prod
dbType: mongodb
connection:
uri: "${MONGODB_URI}"
database: "${MONGODB_DATABASE:-app}"
dumpOptions:
archive: true
authenticationDatabase: "${MONGODB_AUTH_DB:-admin}"
extraArgs: []
backupSchedule: "0 3 * * *"
compress:
enabled: true
password: true
retention:
local:
days: 7
maxSize: 5GB
remote:
days: 30
maxSize: 20GB
options:
localEnabled: true
remoteEnabled: true

- name: mysql-prod
dbType: mysql
connection:
uri: "${MYSQL_URI}"
database: "${MYSQL_DATABASE:-app}"
dumpOptions:
singleTransaction: true
quick: true
routines: true
events: true
extraArgs: []
backupSchedule: "0 3 * * *"
compress:
enabled: true
password: true
retention:
local:
days: 7
maxSize: 5GB
remote:
days: 30
maxSize: 20GB
options:
localEnabled: true
remoteEnabled: true

- name: postgres-prod
dbType: postgresql
connection:
uri: "${POSTGRESQL_URI}"
database: "${POSTGRESQL_DATABASE:-app}"
dumpOptions:
format: custom
compression: 0
noOwner: true
extraArgs: []
backupSchedule: "0 4 * * *"
compress:
enabled: true
password: true
retention:
local:
days: 7
maxSize: 5GB
remote:
days: 30
maxSize: 20GB
options:
localEnabled: true
remoteEnabled: true

# 通知配置（可选）
notify:
enabled: true
type: Dingtalk # 支持多种推送方式，详见 push-all-in-one
config:
DINGTALK_ACCESS_TOKEN: "${DINGTALK_ACCESS_TOKEN}"
DINGTALK_SECRET: "${DINGTALK_SECRET}"
```

### 2. 创建环境变量文件 `.env`

```env
# OSS 配置（支持阿里云 OSS、腾讯云 COS、AWS S3 等）
OSS_REGION=oss-cn-hangzhou
OSS_ACCESS_KEY_ID=your-access-key-id
OSS_ACCESS_KEY_SECRET=your-access-key-secret
OSS_BUCKET=your-bucket-name
OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com

# 备份加密密码（可选）
BACKUP_PASSWORD=your-secure-password

# MongoDB（可选）
MONGODB_URI=mongodb://username:password@127.0.0.1:27017/app?authSource=admin
MONGODB_DATABASE=app
MONGODB_AUTH_DB=admin

# MySQL（可选）
MYSQL_URI=mysql://root:password@127.0.0.1:3306
MYSQL_DATABASE=app

# PostgreSQL（可选）
POSTGRESQL_URI=postgresql://postgres:password@127.0.0.1:5432
POSTGRESQL_DATABASE=app

# 通知配置（可选）
DINGTALK_ACCESS_TOKEN=your-token
DINGTALK_SECRET=your-secret
```

### 3. MongoDB 备份说明

MongoDB 备份计划基于官方 `mongodump` 工具实现：

- Docker 部署时，镜像内预装 MongoDB Database Tools，无需额外安装。
- 非 Docker 部署时，需要自行安装 MongoDB Database Tools，并确保 `mongodump --version` 可以直接执行。
- 配置文件中的敏感值统一通过占位符从 `.env` 注入，避免在 `config.yml` 与 `.env` 之间维护两套配置结构。

### 4. MySQL 备份说明

MySQL 备份基于官方 `mysqldump` 工具实现：

- Docker 部署时，镜像内预装 `mariadb-client` 与 `mariadb-connector-c`，默认优先调用 `mysqldump`，仅在缺失时回退到 `mariadb-dump`。
- 非 Docker 部署时，需要自行安装 MySQL Client Tools，并确保 `mysqldump --version` 可以直接执行。
- 当前实现默认输出单个 `.sql` 逻辑备份文件，并复用现有压缩、加密、本地存储和远程上传流程。
- 单项目支持 3 种目标模式：单数据库、显式多数据库和 `dumpOptions.allDatabases`；若配置 `dumpOptions.tables`，则只能用于单数据库场景。
- 推荐在 InnoDB 场景下启用 `dumpOptions.singleTransaction: true` 与 `dumpOptions.quick: true`，减少锁表影响并改善大表导出行为。
- `connection.uri` 中仅会转换少量已知兼容的查询参数，如 `ssl-mode`、`tls`、`tls-version`、`ssl-ca`、`ssl-cert`、`ssl-key`、`charset`；其他应用层 DSN 参数会被忽略。如需显式传递 CLI 参数，请使用 `dumpOptions.extraArgs`。
- 如果 MySQL 8 实例使用默认的 `caching_sha2_password` 认证方式，Docker/Alpine 环境必须确保安装了 `mariadb-connector-c`，否则会报缺少 `caching_sha2_password.so` 插件的连接错误。
- 若 TiDB Cloud 返回 `usage quota being exhausted`，说明实例配额已耗尽，属于服务端限制，需提升额度或等待恢复后再重试。

### 5. PostgreSQL 备份说明

PostgreSQL 备份基于官方 `pg_dump` 工具实现：

- Docker 部署时，镜像内预装 PostgreSQL Client Tools，无需额外安装。
- 非 Docker 部署时，需要自行安装 PostgreSQL Client Tools，并确保 `pg_dump --version` 可以直接执行。
- 默认使用单文件 `custom` 格式导出，便于后续通过 `pg_restore` 做选择性恢复。
- 当项目级 `compress.enabled` 开启时，默认关闭 `pg_dump` 内置压缩，避免重复压缩；若显式设置 `dumpOptions.compression > 0`，将被视为配置冲突。
- PostgreSQL 备份必须提供数据库名，可以放在 `connection.uri` 中，也可以通过 `connection.database` 单独指定。

## 使用

### 命令行

```bash
# 启动调度器（默认模式）
pnpm run start

# 单次执行所有项目备份
pnpm run start -- -m once

# 单次执行指定项目备份
pnpm run start -- -m once -p my-app-db

# 指定配置文件
pnpm run start -- -c /path/to/config.yml -e /path/to/.env
```

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-c, --config ` | 配置文件路径 | `config.yml` |
| `-e, --env ` | 环境变量文件路径 | `.env` |
| `-o, --output ` | 本地备份目录 | `./backups` |
| `-m, --mode ` | 运行模式: `once` 或 `schedule` | `schedule` |
| `-p, --project ` | 指定项目名称（单次模式） | - |
| `-h, --help` | 显示帮助信息 | - |

## Docker 部署

### 使用 docker-compose

```bash
# 构建并启动
docker-compose up -d

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

### 手动构建

```bash
# 构建镜像
docker build -t auto-backup-database .

# 运行容器
docker run -d \
--name auto-backup-database \
-v $(pwd)/config:/app/config:ro \
-v $(pwd)/backups:/app/backups \
-v /path/to/databases:/app/data:ro \
auto-backup-database
```

## 开发

```bash
# 开发模式
pnpm run dev

# 构建
pnpm run build

# 代码检查
pnpm run lint

# 运行测试
pnpm run test

# 提交代码
pnpm run commit
```

## 项目结构

```
src/
├── cli.ts # CLI 入口
├── index.ts # 模块导出
├── config/
│ └── loader.ts # 配置加载器
├── providers/
│ ├── database.ts # 数据库提供者抽象类
│ ├── mongodb.ts # MongoDB 提供者
│ ├── mysql.ts # MySQL 提供者
│ ├── postgresql.ts # PostgreSQL 提供者
│ └── sqlite.ts # SQLite 提供者
├── services/
│ ├── backup.ts # 备份服务
│ └── scheduler.ts # 调度服务
├── storage/
│ ├── local.ts # 本地存储
│ └── oss.ts # OSS 存储
├── notify/
│ └── index.ts # 通知服务
├── types/
│ └── config.ts # 配置类型定义
└── utils/
├── compress.ts # 压缩工具
└── encrypt.ts # 加密工具
```

## 作者

**CaoMeiYouRen**

* GitHub: [@CaoMeiYouRen](https://github.com/CaoMeiYouRen)

## 贡献

欢迎贡献、提问或提出新功能！请查看 [issues page](https://github.com/CaoMeiYouRen/auto-backup-database/issues) 或 [contributing guide](https://github.com/CaoMeiYouRen/auto-backup-database/blob/master/CONTRIBUTING.md)。

## 支持

如果觉得这个项目有用的话请给一颗⭐️，非常感谢

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=CaoMeiYouRen/auto-backup-database&type=Date)](https://star-history.com/#CaoMeiYouRen/auto-backup-database&Date)

## License

***
_This README was generated with ❤️ by [cmyr-template-cli](https://github.com/CaoMeiYouRen/cmyr-template-cli)_

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/caomeiyouren/auto-backup-database

Awesome Lists containing this project

README

auto-backup-database