laraveladmin / backup
Database and file backups for Hyperf: spatie/laravel-backup feature set, coroutine-safe streaming and verifiable archives.
Requires
- php: >=8.2
- ext-json: *
- ext-openssl: *
- ext-pdo: *
- ext-zip: *
- ext-zlib: *
- hyperf/async-queue: ~3.2.0
- hyperf/command: ~3.2.0
- hyperf/config: ~3.2.0
- hyperf/contract: ~3.2.0
- hyperf/db-connection: ~3.2.0
- hyperf/di: ~3.2.0
- hyperf/event: ~3.2.0
- hyperf/filesystem: ~3.2.0
- hyperf/guzzle: ~3.2.0
- hyperf/logger: ~3.2.0
- hyperf/redis: ~3.2.0
- hyperf/support: ~3.2.0
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
- ext-pdo_mysql: MySQL / MariaDB dumps.
- ext-sodium: Streaming AEAD encryption (recommended); AES-256-CBC+HMAC is used when missing.
Provides
None
Conflicts
None
Replaces
None
README
Hyperf 数据库与文件备份包:对齐 spatie/laravel-backup 的使用习惯,并按 Swoole 常驻内存 / 协程模型重写关键链路(全链路流式、无状态、专属队列、分布式锁、逐文件校验)。
语言:简体中文 | English
状态:
v1.0.7(2026-11-18 发布):P0–P2 已实现并通过验收(103 测试 / 312 断言)。设计文档(唯一事实源):宿主仓库docs/待完成需求/42-数据库与文件备份扩展包-修订版.md。
目录
- 1. 它能做什么
- 2. 环境要求
- 3. 安装
- 4. 快速开始
- 5. 配置
- 6. 命令参考
- 7. 归档结构与校验
- 8. 加密与密码轮换
- 9. 目标盘与上传
- 10. 锁、队列与调度
- 11. 事件与通知
- 12. 运行记录
- 13. 性能、内存与失败策略
- 14. 测试
- 15. 排障
- 16. 与 spatie/laravel-backup 的差异
- 17. 非目标
- License
1. 它能做什么
| 能力 | 说明 |
|---|---|
| 数据库备份 | mysqldump / mariadb-dump 客户端导出(单事务、可选 routines/triggers/events、表级 include/exclude);客户端不可用时可用 PDO 兜底(逐表流式) |
| 文件备份 | 默认关闭(默认只备份数据库);配置 source.files.include 后才流式扫描,支持 glob 排除、符号链接策略、不可读目录策略、relative_path 归档内路径 |
| 归档 | ZIP(Zip64)+ manifest.json(schema v1)+ files.index.jsonl(逐文件 sha256),SQL 先 gzip 且 zip 内 STORE 避免二次压缩 |
| 加密 | 默认 XChaCha20-Poly1305(libsodium secretstream,Argon2id);无 sodium 时 AES-256-CBC + HMAC 兜底;生产强制 |
| 多目标盘 | 任意 Hyperf / Flysystem 盘,逐盘上传、size/sha256 回验、.part-{runId} 原子改名、失败盘可补传 |
| 校验 | backup:verify:解密 → CHECKCONS → manifest → DB dump sha256 → index 逐行重算文件 sha256 |
| 恢复 | 默认只解压到 staging;写生产必须 --in-place --force --confirm(生产另需环境开关),默认恢复前快照 |
| 清理 | 5 档保留(全量窗口 / 日 / 周 / 月 / 年)+ 容量上限 + --dry-run,永不删最后一份已校验归档 |
| 监控 | 数量 / 最新年龄 / 容量(支持多监控组 + 自定义 HealthCheckInterface),--json 供后台消费 |
| 编排 | file / Redis 分布式锁、tries 重试、内存上限守卫、可选运行记录表、PSR-14 事件、webhook / 邮件 / 站内信通知 |
2. 环境要求
- PHP
>= 8.2;Hyperf~3.2 - 必需扩展:
ext-json、ext-openssl、ext-pdo、ext-zip、ext-zlib - 推荐:
ext-sodium(首选加密算法)、ext-pdo_mysql、hyperf/redis(多节点锁 / 队列) - 数据库:MySQL 8 / MariaDB(P0 范围);
mysqldump或mariadb-dump客户端需在 PATH 中
3. 安装
3.1 从 Packagist(发布后)
composer require laraveladmin/backup:^1.0
3.2 本地开发副本(宿主仓库内)
"repositories": [
{ "type": "path", "url": "../packages/backup", "options": { "symlink": true } }
]
composer update laraveladmin/backup
3.3 初始化
# 1) 发布配置 + 创建临时目录 + 打印配置校验结果(幂等)
php bin/hyperf.php backup:install
# 2) 发布迁移(可选:仅在需要 backup_runs 运行记录时)
php bin/hyperf.php vendor:publish laraveladmin/backup
php bin/hyperf.php migrate:all
3.4 准备私有备份盘
在 config/autoload/file.php 的 storage 下新增(不能用 local 盘、public/ 下的目录或带 public_url 的公开盘):
'backups' => [
'driver' => \Hyperf\Filesystem\Adapter\LocalAdapterFactory::class,
'root' => BASE_PATH . '/storage/backups', // 不在 public 下、无 public_url
],
生产建议再配一个私有对象存储盘(OSS / S3 / MinIO / COS / 七牛),作为异地主份。
4. 快速开始
# 全量备份(数据库 + 文件 → 所有目标盘)
php bin/hyperf.php backup:run
# 查看各盘归档
php bin/hyperf.php backup:list
# 全量校验最新归档(manifest + DB dump sha256 + 逐文件 sha256)
php bin/hyperf.php backup:verify --backup=storage/backups/app-2026-11-17-09-50-31.zip
# 恢复演练:只解压到 staging(不动生产)
php bin/hyperf.php backup:restore --backup=storage/backups/app-2026-11-17-09-50-31.zip
典型输出:
备份完成:app-2026-11-17-09-50-31.zip(19.78 MB, success)
- backups: ok
5. 配置
配置唯一来源:config/autoload/backup.php(backup:install / vendor:publish 生成)。根键与 spatie 对齐,项目扩展集中在 hyperf 块。
5.1 环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
APP_NAME | app | 归档名主体({name}-{Y-m-d-H-i-s}.zip) |
BACKUP_ARCHIVE_PASSWORD | 空 | 归档密码(生产必填,≥ 32 位随机) |
BACKUP_ARCHIVE_PASSWORD_PREVIOUS | 空 | 历史密码(逗号分隔,轮换期解密用) |
BACKUP_DB_DUMP_DRIVER | auto | auto / binary / pdo |
BACKUP_NOTIFICATIONS_MAIL | 空 | 通知邮件收件人(逗号分隔) |
BACKUP_WEBHOOK_URL | 空 | 通知 webhook 地址 |
BACKUP_WEBHOOK_SECRET | 空 | webhook HMAC 签名密钥 |
APP_ENV | production | 决定 hyperf.encryption.require_password 默认值与恢复环境开关判断 |
MAIL_FROM_ADDRESS / MAIL_FROM_NAME | 项目默认 | 通知邮件发件人 |
5.2 关键配置项
// 源:数据库连接名(databases.<name>)+ 文件根
'source' => [
'driver' => 'auto',
'databases' => ['default'],
'files' => [
'include' => [], // 默认只备份数据库;需要备份上传文件时填目录,如 [BASE_PATH . '/public/uploads']
'exclude' => [BASE_PATH . '/public/uploads/tmp', '*.log'],
'follow_links' => false,
'ignore_unreadable_directories' => true,
'relative_path' => BASE_PATH, // 归档内路径基准
],
],
// 目标盘(必填,至少一个私有盘)
'destination' => [
'disks' => ['backups'],
'filename_prefix' => '',
'compression_method' => 'deflate', // deflate | bzip2 | store
'compression_level' => 6,
'continue_on_failure' => true, // true: 至少一盘成功即 success
],
'temporary_directory' => BASE_PATH . '/runtime/backup',
'verify_backup' => true, // 归档后 CHECKCONS + 非空
'tries' => 1, // 可重试异常的重试次数(配置校验 / 锁冲突不重试)
'retry_delay' => 10, // 重试间隔(秒)
// 清理:5 档保留 + 容量 + 最新/已校验保护
'cleanup' => ['default_strategy' => [
'keep_all_backups_for_days' => 7,
'keep_daily_backups_for_days' => 16,
'keep_weekly_backups_for_weeks' => 8,
'keep_monthly_backups_for_months' => 4,
'keep_yearly_backups_for_years' => 2,
'delete_oldest_backups_when_using_more_megabytes_than' => 5000,
'protect_last_verified' => true,
]],
// 数据库 dump 细节(客户端参数 / 表级过滤 / TLS)
'hyperf' => [
'source' => [
'binary' => 'mysqldump',
// include/exclude 支持通配符(* / ?,如 'logs_*' 排除所有日志分表)
'include_tables' => [],
'exclude_tables' => [],
'strip_definer' => true,
'include_routines' => false,
'include_triggers' => false,
'include_events' => false,
'extra_options' => [],
'tls' => ['mode' => 'preferred'], // disabled | preferred | required | verify
],
'limits' => [
'max_memory_mb' => 128, // 超过即中止本次运行(失败优先)
'timeout' => 3600,
'max_files' => 200000,
'max_file_size' => '4G',
'max_bytes' => '200G',
'max_uncompressed_bytes' => '400G',
'max_compression_ratio' => 100,
'min_free_bytes' => '2G',
'disk_factor' => 1.5,
],
'archive_filename_format' => 'Y-m-d-H-i-s', // 归档名时间格式(PHP date);非法字符会自动替换为 '-'
'locks' => ['driver' => 'file', 'ttl' => 3600, 'path' => ''], // 留空 = 跟随临时目录(runtime/backup/locks);多节点改 redis
'queue' => ['connection' => 'backup', 'channel' => 'backup', 'handle_timeout' => 7200],
'runs' => ['enabled' => true, 'table' => 'backup_runs', 'retain_days' => 30],
'restore' => ['web_enabled' => false],
],
归档内 dump 文件名:
db-dumps/<connection>-<timestamp>.sql[.gz],timestamp取database_dump_file_timestamp_format(默认Y-m-d_H-i-s,非法字符同样替换为-;空格式=不带时间戳)。
归档文件名:
[{destination.filename_prefix}]{backup.name}-{timestamp}.zip,timestamp取hyperf.archive_filename_format(默认Y-m-d-H-i-s,也可用BACKUP_ARCHIVE_FILENAME_FORMAT覆盖)。 格式里的:、空格等非法字符会先替换为-,因此Y-m-d H:i:s与默认结果相同 (HyperfAdmin-2026-11-18-11-31-16.zip);要可区分请用Ymd_His(HyperfAdmin-20261118_113116.zip) 或Y-m-d_H-i-s。
上线前必做:
destination.disks指向私有盘;生产设置BACKUP_ARCHIVE_PASSWORD;APP_ENV=production时配置校验会拒绝明文归档与--no-encryption。
6. 命令参考
所有命令通过 php bin/hyperf.php <command> 执行;退出码见 6.9。
6.1 backup:install
发布配置、创建临时目录、打印配置校验结果(幂等,可重复执行)。
php bin/hyperf.php backup:install
6.2 backup:run
运行一次备份:锁 → 配置校验 → dump → 文件扫描 → 归档 → 加密 → 上传 → 运行记录 → 事件。
php bin/hyperf.php backup:run # 全量(库 + 文件)
php bin/hyperf.php backup:run --only-db # 只备份数据库
php bin/hyperf.php backup:run --only-files # 只备份文件
php bin/hyperf.php backup:run --only-to-disk=oss_backup
php bin/hyperf.php backup:run --filename=pre-deploy # 自定义归档名主体(不含扩展名)
php bin/hyperf.php backup:run --verify-upload # 上传后强制 sha256 回验
php bin/hyperf.php backup:run --no-compress # 不压缩(排障)
php bin/hyperf.php backup:run --disable-notifications
php bin/hyperf.php backup:run --force # 忽略互斥锁(排障,可能并发产出两份归档)
| 选项 | 说明 |
|---|---|
--only-db | 只备份数据库(跳过文件扫描) |
--only-files | 只备份文件(跳过 dump) |
--only-to-disk=<disk> | 本次只写指定目标盘 |
--filename=<subject> | 自定义文件名主体;禁止 /、\、..、控制字符,长度 ≤ 120 |
--verify-upload | 上传后强制 sha256 回验(默认按 verify_upload 配置) |
--no-compress | 关闭 SQL gzip 与 zip 压缩(体积换时间,仅排障) |
--disable-notifications | 本次不发通知(事件仍派发) |
--no-encryption | 本次不加密;生产环境直接失败,仅限非生产联调 |
--force | 忽略互斥锁(排障用) |
6.3 backup:list
列出各目标盘上的归档(只匹配本包命名模式)。
php bin/hyperf.php backup:list
php bin/hyperf.php backup:list --disk=oss_backup
php bin/hyperf.php backup:list --json
| 选项 | 说明 |
|---|---|
--disk=<disk> | 只看指定盘 |
--json | JSON 输出(供后台 / 脚本消费) |
6.4 backup:verify
全量校验归档:解密(.enc)→ ZipArchive::CHECKCONS → manifest.json → DB dump sha256 → files.index.jsonl 逐行重算逐文件 sha256 与大小,并校验 index 行数与 manifest.files.count 一致。
php bin/hyperf.php backup:verify --backup=storage/backups/app-2026-11-17-09-50-31.zip
php bin/hyperf.php backup:verify --disk=backups --backup=app-2026-11-17-09-50-31.zip.enc
php bin/hyperf.php backup:verify --backup=... --sample=100 # 抽样 100 个文件(index 完整性仍全量校验)
| 选项 | 说明 |
|---|---|
--backup=<path> | 本地路径;配合 --disk 时为盘内相对路径,必填 |
--disk=<disk> | 从指定盘读取(会先回读到临时文件) |
--sample=<n> | 抽样文件数;0(默认)= 全量 |
6.5 backup:restore
恢复。默认只解压到 staging,不写生产。
# 默认:解压到 staging(runtime/backup/restore/时间戳)
php bin/hyperf.php backup:restore --backup=storage/backups/app-2026-11-17-09-50-31.zip
# 只挑 DB / 文件
php bin/hyperf.php backup:restore --backup=... --only-db
php bin/hyperf.php backup:restore --backup=... --only-files
# 只挑 files/ 下某些路径
php bin/hyperf.php backup:restore --backup=... --only-paths=public/uploads/images,public/uploads/docs
# 写生产(三件套;生产另需 BACKUP_RESTORE_ALLOW=1)
BACKUP_RESTORE_ALLOW=1 php bin/hyperf.php backup:restore \
--backup=storage/backups/app-2026-11-17-09-50-31.zip \
--in-place --force --confirm=app-2026-11-17-09-50-31.zip
# 只恢复部分表(先恢复到临时库再抽表,需 mysqldump 客户端)
BACKUP_RESTORE_ALLOW=1 php bin/hyperf.php backup:restore \
--backup=... --in-place --force --confirm=... --only-db --only-tables=users,roles --database=target_db
| 选项 | 说明 |
|---|---|
--backup=<path> | 归档路径;配合 --disk 时为盘内路径,必填 |
--disk=<disk> | 从指定盘读取 |
--staging=<dir> | staging 目录(默认 runtime/backup/restore/<时间戳>) |
--only-db / --only-files | 只处理数据库 / 只处理文件 |
--only-paths=<a,b> | 只恢复 files/ 下匹配前缀的路径 |
--only-tables=<a,b> | 只恢复指定表(需 --database,走临时库 {db}_restore_scratch,结束自动 DROP) |
--in-place | 写生产(必须同时 --force --confirm,且默认恢复前快照) |
--force | 确认覆盖目标 |
--confirm=<filename> | 输入归档文件名(不可逆操作二次确认) |
--database=<name> | 目标库名(in-place 导库时) |
--backup-before-restore | 恢复前先做一次快照(默认开) |
--no-backup-before-restore | 跳过恢复前快照(危险,需确认已有可恢复备份) |
恢复后动作:重启 server / 队列 worker;按需 search:reindex、重建图片派生缓存;确认 AUTO_INCREMENT(可能回退属预期)。
6.6 backup:clean
按保留策略清理旧归档(只删本包命名模式,且永不删最后一份已校验归档)。
php bin/hyperf.php backup:clean --dry-run # 只打印将删除的文件
php bin/hyperf.php backup:clean # 真正删除
php bin/hyperf.php backup:clean --only-to-disk=oss_backup
| 选项 | 说明 |
|---|---|
--dry-run | 只打印计划,不删除 |
--only-to-disk=<disk> | 只清理指定盘(本地与云端互相独立) |
6.7 backup:monitor
备份健康检查:最小份数 / 最新备份最大年龄 / 最大容量;支持 monitor_backups 多组与自定义 HealthCheckInterface。
php bin/hyperf.php backup:monitor
php bin/hyperf.php backup:monitor --json
| 选项 | 说明 |
|---|---|
--json | JSON 输出(供后台 / 监控系统消费) |
不健康时退出码 1,并派发 UnhealthyBackupWasFound 事件。
6.8 backup:upload
把已存在的归档补传到目标盘,不重新 dump。
php bin/hyperf.php backup:upload --backup=storage/backups/app-2026-11-17-09-50-31.zip
php bin/hyperf.php backup:upload --backup=app-2026-11-17-09-50-31.zip --from-disk=backups --disk=oss_backup
php bin/hyperf.php backup:upload --backup=... --verify
| 选项 | 说明 |
|---|---|
--backup=<path> | 本地归档路径;配合 --from-disk 时为盘内路径,必填 |
--from-disk=<disk> | 从该盘读取归档再补传 |
--disk=<disk> | 只传到指定盘 |
--verify | 强制 sha256 回验 |
6.9 退出码
| 退出码 | 含义 |
|---|---|
0 | 成功;锁被占用导致的 skipped 也是 0(避免 crontab / 发布脚本误报,运行记录里仍为 skipped) |
1 | 备份 / 校验 / 恢复失败 |
2 | 配置或参数错误(含生产环境拒绝 --no-encryption、缺 --in-place 三件套等) |
7. 归档结构与校验
app-2026-11-17-09-50-31.zip[.enc]
├── manifest.json # schema v1:app / runtime / dumps / files / encryption / checksums / notes
├── files.index.jsonl # 逐行:{"path","size","sha256","mtime","mode"}
├── db-dumps/
│ └── db-dumps-default-2026-11-17-09-50-31.sql.gz
└── files/
└── public/uploads/images/... # 相对 relative_path 的路径
manifest.checksums只包含db-dumps/*与files.index.jsonl的 sha256;逐文件 sha 只在files.index.jsonl(10 万文件也不膨胀)。manifest.json最后写入,保证 index / dump 校验和已知。- 恢复与校验都会校验 ZIP 条目安全:拒绝绝对路径、
..、盘符、空字节、超长段、重复条目、符号链接条目。 - 归档路径只存相对路径,不写宿主机绝对路径。
8. 加密与密码轮换
encryption:default(sodium 可用则 XChaCha20-Poly1305,否则 AES-256-CBC+HMAC)/aes256/none(仅非生产)。- 加密失败、sodium/AES 均不可用、写
.enc失败 → 整次 failed,绝不回退明文。 - 密码:
BACKUP_ARCHIVE_PASSWORD(≥ 32 位随机、双人保管);只存环境变量 / 密钥管理,绝不写 manifest、日志、通知。 - 轮换:新密码写入
BACKUP_ARCHIVE_PASSWORD,旧密码加入BACKUP_ARCHIVE_PASSWORD_PREVIOUS(默认「当前 → 历史」顺序尝试解密),旧归档删完后移除旧密码。 - 密码丢失 = 不可恢复,没有后门。
9. 目标盘与上传
- 目标盘来自
filesystems.disks(backup.destination.disks),校验会拒绝:名为local的盘、root 在public/下、带public_url的盘。 hyperf.destination.path_prefix(默认空)与path_prefixes.<disk>可按盘覆盖前缀。- 上传:
{final}.part-{runId}写入 → 回验 →move到最终名;不支持 move 的盘退化为「直写最终名 + 失败删除」。 - 回验模式:
hyperf.destination.verify_upload:size(默认,比较 fileSize)/sha256(回读全量)/none;--verify-upload强制 sha256。 - 多盘语义:
continue_on_failure=true时至少一盘成功即success;逐盘结果写backup_runs.meta.disks[];失败盘可backup:upload补传。 - 本地与云端状态独立:
backup:clean只清理目标盘自己的文件。
10. 锁、队列与调度
10.1 互斥锁
- 单机默认
hyperf.locks.driver=file(flock,进程退出自动释放);多节点改redis(SET NX PX+ Lua 值匹配续期 / 释放)。 - 锁被占用:本次运行记录为
skipped,backup:run退出码0(不误报失败),不会产生第二份归档。 --force忽略锁,仅排障用。
10.2 队列 job
包内提供 LaravelAdmin\Backup\Job\RunBackupJob、VerifyBackupJob(maxAttempts=1,失败靠下次调度)。宿主侧建议使用独立队列通道:
// config/autoload/async_queue.php
'backup' => [
'driver' => RedisDriver::class,
'redis' => ['pool' => 'default'],
'channel' => '{backup}',
'queue' => 'backup',
'handle_timeout' => 7200, // 必须大于最大运行时长,避免租约过期重投
'processes' => 1,
'concurrent' => ['limit' => 1],
'max_messages' => 0,
],
// app/Process/BackupQueueConsumer.php
#[Process]
class BackupQueueConsumer extends ConsumerProcess
{
protected string $pool = 'backup'; // 注意:ConsumerProcess 用 $pool,不是 $channel
}
10.3 调度(宿主 crontab,包不硬编码)
| name | rule(Asia/Shanghai) | 说明 |
|---|---|---|
backup-run | 10 2 * * * | 投递 RunBackupJob 到 backup 队列 |
backup-clean | 20 3 * * 0 | 直接执行清理 |
backup-monitor | 40 4 * * * | 健康检查(状态翻转才通知) |
backup-verify | 10 5 * * 1 | 校验最新归档(走队列) |
11. 事件与通知
事件(PSR-14,LaravelAdmin\Backup\Event\*):BackupWasSuccessful、BackupHasFailed、BackupRunSkipped、UnhealthyBackupWasFound、RestoreWasSuccessful、RestoreHasFailed。
通知按 backup.notifications.notifications[事件类] = [渠道] 分发;渠道实现通过 backup.notifications.notifiers.<channel> 注入:
'notifiers' => [
'inapp' => \App\Service\Backup\BackupInAppNotifier::class,
'mail' => \App\Service\Backup\BackupMailNotifier::class,
],
'notifications' => [
\LaravelAdmin\Backup\Event\BackupHasFailed::class => ['mail', 'inapp'],
\LaravelAdmin\Backup\Event\UnhealthyBackupWasFound::class => ['mail', 'inapp'],
],
- 内置渠道:
log(默认兜底)、webhook(JSON +X-Backup-Signature: sha256=...,走 Hyperf Guzzle)。 - 收件人优先级:
notifiable.emails>mail.to/BACKUP_NOTIFICATIONS_MAIL。 - 通知失败只记日志,不改变备份结果;
--disable-notifications跳过;log_channel=null关闭日志渠道。
12. 运行记录
hyperf.runs.enabled=true(默认)时写 backup_runs 表(迁移见 migrations/):
| 字段 | 说明 |
|---|---|
run_id | 幂等键(YmdHis-随机) |
type / trigger / triggered_by | backup / restore / verify / upload;schedule / manual / cli;操作人 ID |
mode / status | db / files / both;running / success / failed / skipped |
filename / size / sha256 | 归档信息 |
disks | 逐盘上传结果 JSON |
error | 失败原因(中文原文,CLI / 日志 / 排查用) |
error_code / error_params | 失败原因代码与参数(v1.0.7+,管理端按 code 做多语言渲染;config_invalid 携带结构化 failures) |
meta | 文件数、dump 数、memory_peak_bytes 等 |
started_at / finished_at / verified_at / duration_ms | 时间与耗时 |
资源快照写 meta(v1.0.6+):cpu_time_ms(CPU 时间)、memory_peak_bytes(进程峰值内存)、server_memory_before/after、temp_bytes(临时目录峰值)、disk_free_before/after(各目标盘剩余)、archive_ratio(原始/归档压缩比)。
宿主后台可基于该表与 backup:list --json 提供 /admin/backups 页面(本仓库已完成:标准资源控制器 + CrudTable 列表,筛选 / 排序 / 三端)。
12.1 基础模型(Hyperf ORM)
包内提供 LaravelAdmin\Backup\Model\BackupRun(对应 backup_runs,含枚举常量、fillable / casts、enumValues()、latestSuccess()),可直接读,也可由应用继承定制:
namespace App\Model;
use App\Model\Traits\BaseModel; // 宿主通用 CRUD / 筛选能力
use Hyperf\ModelCache\Cacheable;
use Hyperf\ModelCache\CacheableInterface;
use LaravelAdmin\Backup\Model\BackupRun as BaseBackupRun;
class BackupRun extends BaseBackupRun implements CacheableInterface
{
use BaseModel;
use Cacheable;
}
- 包只提供基础结构(表 / 字段 / 枚举),不依赖宿主
App\*; - 应用侧用上面的方式继承后即可获得
optionsWhere、缓存等宿主能力; - 写入仍由
PdoRunStore负责(不依赖 ORM),模型主要用于读取、管理端 CRUD 与外部集成。
13. 性能、内存与失败策略
原则:宁可备份失败,也不要把生产进程拖死。
- 全链路流式:
mysqldump | gzip、逐文件扫描、ZipArchive::addFile、加密 1 MB 分块、上传 / 下载 stream、DB 导入gzip -dc | mysql、backup:verify用getStream()逐行读 index。 hyperf.limits.max_memory_mb(默认 128):运行中memory_get_peak_usage(true)超限即抛异常中止本次运行(检查点覆盖 dump / 扫描 / 归档 / 校验 / 恢复)。- PDO 兜底 dump 使用 MySQL unbuffered 游标,避免整表结果集进 PHP 内存。
- 归档后可选
verify_backup(CHECKCONS + 非空);ZIP bomb 防护:条目数、单文件大小、解压总量、压缩比。 - 实测基线(170 MiB 库 / 40 万行):PDO 兜底 dump 峰值 ≈ 12 MB;全量备份 PHP 峰值 ≈ 28 MB;归档 ≈ 19.8 MB。
14. 测试
# 包内(随包发布,不依赖宿主业务表)
docker compose exec -T server sh -lc 'cd /opt/www/packages/backup && vendor/bin/phpunit'
# 或:vendor/bin/pest vendor/laraveladmin/backup/tests
当前 101 tests / 290 assertions(配置、dump、扫描、归档、加密、上传、锁、编排、校验、恢复、健康检查、重试、通知、内存守卫)。宿主侧真实备份 / 队列 / 后台 API 的集成测试建议放 server/test/Feature/Backup/。
15. 排障
| 现象 | 排查 |
|---|---|
目标盘不存在 / 盘在 public 下 | 检查 file.storage.<disk> 与 backup.destination.disks;私有盘不能带 public_url |
mysqldump 输出异常小 | 客户端连接失败被 gzip 管道掩盖;看 runtime/backup-*/mysqldump-*.err;MariaDB 15.x 自签证书需 skip-ssl(包内按客户端 flavor 自动加) |
| 上传回验失败 | size 模式先看对象大小;网络类可重试;认证错误不重试,用 backup:upload --disk= 补传 |
| 锁被占用(退出码 0 + skipped) | 上一次运行未结束;确认无进程后可调小 hyperf.locks.ttl 或 --force(不推荐) |
| 校验失败 | 看 backup:verify 分类:清单缺失 / 文件缺失 / hash 不一致 / 解密失败;可能是归档被截断 |
| 恢复被拒绝 | 需 --in-place --force --confirm=<归档名>;生产另需 BACKUP_RESTORE_ALLOW=1 |
内存峰值超过上限 | 调大 hyperf.limits.max_memory_mb 或缩小备份范围;这是保护机制,不是 bug |
生产 --no-encryption 被拒 | 设计如此:生产强制加密,仅非生产可明文 |
16. 与 spatie/laravel-backup 的差异
- 加密:流式 AEAD(不是 ZipCrypto);生产强制,失败不回退明文。
- 完整性:新增
manifest.json+files.index.jsonl+ 逐文件 sha256 +backup:verify。 - 运维:运行记录表、PSR-14 事件、清理保护(最后一份已校验永不删)、分布式锁、独立队列通道、内存守卫。
- 恢复:默认 staging;写生产三件套 + 生产环境开关 + 恢复前快照。
- 不做:对象存储内容搬运(与 spatie 一致);ZipCrypto 兼容;Redis / ES 备份。
17. 非目标
- 不搬运对象存储内容(云上文件仍在桶内,建议开版本控制 / 跨区复制)。
- 不备份 Redis / ES(可重建)。
- 不做增量 / 去重 / 硬链接池、binlog PITR、Object Lock(P3 评估)。
- P0 仅 MySQL / MariaDB;PostgreSQL / SQLite / Mongo 为后续增强。
License
MIT © 2026 laraveladmin