Databasus备份解密脚本使用说明

Databasus（Mysql或MariaDB）备份解密脚本使用说明

一、脚本功能

脚本下载链接: https://pan.baidu.com/s/1daBXThAelmtQ7YcrLGdz4g?pwd=fdds 提取码: fdds

decrypt_backup.py 用于解密 Databasus 生成的加密备份文件，并自动用 zstd 解压，最终得到可直接还原的 .sql 文件。

处理流程：

加密备份文件 + metadata + master key
        │
        ├─ 校验文件头 (PGRSUS01)
        ├─ 用 PBKDF2 派生密钥 (master_key + backupId, salt, 100000 次迭代)
        ├─ 按 1MB 分块用 AES-GCM 解密
        ├─ 输出 decrypted_<备份名>.zst
        └─ zstd 解压 → decrypted_<备份名>.sql（并删除中间 .zst）

注：脚本中 master_key 已改为从环境变量读取，不再硬编码在源码里。

---

二、前置条件

1. Python 版本

Python 3.7 及以上。

2. 安装 Python 依赖

pip install pycryptodome

（只用到 Crypto 模块，包名是 pycryptodome，不是 pycrypto。）

3. 安装 zstd 命令行工具

脚本会调用系统 zstd 命令，需确保它在 PATH 中：

# Debian / Ubuntu
sudo apt-get install zstd

# RHEL / CentOS / Rocky
sudo yum install zstd
# 或
sudo dnf install zstd

# macOS
brew install zstd

# Windows（推荐用 choco 或 scoop）
choco install zstd
# 或
scoop install zstd

验证：

zstd --version

4. 需要的三个输入

输入	说明
加密备份文件	例如 mysql-...-d12ae790-...（没有扩展名也可能）
metadata 文件	与备份同名的 .metadata 文件（JSON），含 backupId、encryptionSalt、encryptionIV 等
master key	来自 ./databasus-data/secret.key，通过环境变量传入

---

三、设置环境变量

环境变量名：DATABASUS_MASTER_KEY

Linux / macOS

export DATABASUS_MASTER_KEY='你的主密钥内容'

Windows PowerShell

$env:DATABASUS_MASTER_KEY = "你的主密钥内容"

Windows CMD

set DATABASUS_MASTER_KEY=你的主密钥内容

⚠️ 提示：

• 直接 export 会把密钥写进 shell 历史，生产环境建议改用 read -s 交互输入，或使用密钥管理系统（Vault、KMS 等）。
• 切勿把密钥写进脚本、配置文件或提交到 Git。
• 如果密钥中含空格/特殊字符，务必用引号包起来。

---

四、运行

export DATABASUS_MASTER_KEY='你的主密钥'
python decrypt_backup.py ./xxx ./xxx.metadata

成功输出示例

Successfully decrypted 37 chunks to ./decrypted_mysql-...-d12ae790-....zst
*** zstd command line interface 64-bits v1.5.5, by Yann Collet ***
./decrypted_mysql-...-d12ae790-....zst : 16777216 bytes

最终得到：

./decrypted_mysql-...-d12ae790-....sql

中间产物 decrypted_*.zst 会在解压成功后自动删除。

---

五、常见错误与排查

报错	原因	解决
Error: environment variable DATABASUS_MASTER_KEY is not set	没设置或拼错环境变量名	检查 echo $DATABASUS_MASTER_KEY（Windows：echo $env:DATABASUS_MASTER_KEY）
Error: Backup file not found	备份文件路径不对	检查相对/绝对路径，注意文件名很长、没有扩展名
Error: Metadata file not found	metadata 路径不对	确认 .metadata 文件与备份同目录
Error: Backup is not encrypted (encryption status: ...)	metadata 中 encryption 不为 ENCRYPTED	说明此备份未加密，直接 zstd -d 解压即可，无需本脚本
Invalid magic bytes: expected b'PGRSUS01', got ...	传入了错误的文件（如已经解压过或不是 Databasus 加密备份）	确认输入的是原始加密备份
MAC check failed（会打印 Failed at chunk N）	①master key 错误；②备份损坏；③metadata 与备份不匹配	逐一核对密钥、备份完整性、metadata 是否配套；不要混用不同备份的 metadata
subprocess.CalledProcessError: ... zstd ... / FileNotFoundError: zstd	未安装 zstd 或不在 PATH	按第二节安装并验证
ModuleNotFoundError: No module named 'Crypto'	未安装依赖	pip install pycryptodome

发生 MAC check failed 时，脚本会自动删除已生成的不完整 decrypted_*.zst，不会污染目录。

---

六、安全建议

1. 密钥只经环境变量传递，不要硬编码、不要写进脚本、不要提交仓库。
2. metadata 与备份必须配套，不同备份的 backupId/salt/IV 不同，混用必然 MAC 校验失败。
3. 解密得到的是明文 SQL，包含业务数据，请保存在受限目录并控制权限（如 chmod 600），用完后及时清理。
4. 在生产机执行前，建议先在测试环境用一份小备份验证流程。
5. 记录并保管好 secret.key 原文件，这是唯一的解密凭证——丢失后无法恢复。