Skip to content

Rokami/synology-drive-restore

BranchesTags

Repository files navigation

Synology Drive Batch Restore

English | 中文

English

Overview

A command-line tool to batch restore files from Synology Drive's recycle bin based on deletion time. Perfect for recovering files after accidental bulk deletions.

Features

  • 🕐 Time-based filtering: Restore only files deleted after a specific timestamp
  • 📦 Batch processing: Handles thousands of files efficiently (100 files per batch)
  • 🔄 Async task monitoring: Track restoration progress in real-time
  • 🔒 Secure authentication: Uses Synology's official API with cookie-based auth
  • 📊 Progress tracking: Clear visual feedback during operation

Requirements

  • Python 3.6+
  • curl command-line tool
  • Synology NAS with Drive installed
  • Admin or user account with Drive access

Installation

git clone https://github.com/yourusername/synology-drive-restore.git
cd synology-drive-restore
chmod +x restore.py monitor.py

Usage

1. Configure credentials

Create a config.json file:

{
  "base_url": "https://your-nas-ip:5001",
  "username": "your-username",
  "password": "your-password",
  "cutoff_timestamp": 1738224000
}

To calculate timestamp:

python3 -c "from datetime import datetime; print(int(datetime(2026, 1, 30, 15, 0, 0).timestamp()))"

2. Run restoration

./restore.py

This will:

  1. Login to your Synology NAS
  2. Scan recycle bin for files deleted after the cutoff time
  3. Submit batch restore tasks
  4. Display progress

3. Monitor progress (optional)

./monitor.py

Monitors all submitted tasks and shows real-time progress.

Configuration Options

Field Description Example
base_url Your NAS URL (with port) https://192.168.1.100:5001
username Synology account username admin
password Account password your-password
cutoff_timestamp Unix timestamp (files deleted after this time will be restored) 1738224000
batch_size Files per batch (optional, default: 100) 100

Security Notes

⚠️ Important:

  • Never commit config.json with real credentials to version control
  • Use a dedicated account with minimal permissions if possible
  • Consider using environment variables for sensitive data
  • The tool uses HTTPS but disables SSL verification (use at your own risk)

How It Works

  1. Authentication: Logs in via Synology's Web API
  2. Scanning: Fetches recycle bin items in batches (1000 per request)
  3. Filtering: Keeps only files deleted after the specified timestamp
  4. Restoration: Submits async restore tasks (100 files per task)
  5. Monitoring: Polls task status until completion

API Endpoints Used

  • SYNO.API.Auth - Authentication
  • SYNO.SynologyDrive.Trash - List recycle bin items
  • SYNO.SynologyDrive.Revisions - Restore files
  • SYNO.SynologyDrive.Tasks - Monitor task status

Troubleshooting

Login fails:

  • Check URL, username, and password
  • Ensure account has Drive access
  • Verify NAS is accessible

No files found:

  • Verify timestamp is correct (use Unix epoch time)
  • Check if files are actually in recycle bin
  • Ensure you're using the correct Drive path (/mydrive)

Tasks stuck:

  • Large files take longer to restore
  • Check NAS system resources
  • Monitor via DSM web interface

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

License

MIT License - see LICENSE file for details.

Disclaimer

This tool is provided as-is. Always backup important data before performing bulk operations. The author is not responsible for any data loss.

中文

概述

一个命令行工具，用于根据删除时间批量恢复 Synology Drive 回收站中的文件。非常适合在意外批量删除后恢复文件。

功能特性

  • 🕐 基于时间过滤：仅恢复指定时间戳之后删除的文件
  • 📦 批量处理：高效处理数千个文件（每批100个）
  • 🔄 异步任务监控：实时跟踪恢复进度
  • 🔒 安全认证：使用群晖官方 API 和基于 Cookie 的认证
  • 📊 进度跟踪：操作过程中提供清晰的视觉反馈

系统要求

  • Python 3.6+
  • curl 命令行工具
  • 安装了 Drive 的群晖 NAS
  • 具有 Drive 访问权限的管理员或用户账户

安装

git clone https://github.com/yourusername/synology-drive-restore.git
cd synology-drive-restore
chmod +x restore.py monitor.py

使用方法

1. 配置凭据

创建 config.json 文件：

{
  "base_url": "https://你的NAS地址:5001",
  "username": "你的用户名",
  "password": "你的密码",
  "cutoff_timestamp": 1738224000
}

计算时间戳：

python3 -c "from datetime import datetime; print(int(datetime(2026, 1, 30, 15, 0, 0).timestamp()))"

2. 运行恢复

./restore.py

这将：

  1. 登录到你的群晖 NAS
  2. 扫描回收站中截止时间后删除的文件
  3. 提交批量恢复任务
  4. 显示进度

3. 监控进度（可选）

./monitor.py

监控所有已提交的任务并显示实时进度。

配置选项

字段 说明 示例
base_url NAS 地址（含端口） https://192.168.1.100:5001
username 群晖账户用户名 admin
password 账户密码 your-password
cutoff_timestamp Unix 时间戳（此时间后删除的文件将被恢复） 1738224000
batch_size 每批文件数（可选，默认：100） 100

安全注意事项

⚠️ 重要：

  • 切勿将包含真实凭据的 config.json 提交到版本控制
  • 如果可能，使用具有最小权限的专用账户
  • 考虑使用环境变量存储敏感数据
  • 该工具使用 HTTPS 但禁用了 SSL 验证（使用风险自负）

工作原理

  1. 认证：通过群晖 Web API 登录
  2. 扫描：批量获取回收站项目（每次请求1000个）
  3. 过滤：仅保留指定时间戳之后删除的文件
  4. 恢复：提交异步恢复任务（每个任务100个文件）
  5. 监控：轮询任务状态直到完成

使用的 API 端点

  • SYNO.API.Auth - 认证
  • SYNO.SynologyDrive.Trash - 列出回收站项目
  • SYNO.SynologyDrive.Revisions - 恢复文件
  • SYNO.SynologyDrive.Tasks - 监控任务状态

故障排除

登录失败：

  • 检查 URL、用户名和密码
  • 确保账户具有 Drive 访问权限
  • 验证 NAS 可访问

未找到文件：

  • 验证时间戳是否正确（使用 Unix 纪元时间）
  • 检查文件是否确实在回收站中
  • 确保使用正确的 Drive 路径（/mydrive）

任务卡住：

  • 大文件恢复需要更长时间
  • 检查 NAS 系统资源
  • 通过 DSM Web 界面监控

贡献

欢迎贡献！请：

  1. Fork 仓库
  2. 创建功能分支
  3. 提交 Pull Request

许可证

MIT 许可证 - 详见 LICENSE 文件。

免责声明

此工具按原样提供。在执行批量操作之前，请始终备份重要数据。作者不对任何数据丢失负责。

About

Batch restore files from Synology Drive recycle bin based on deletion time

Topics

python automation synology batch-processing synology-nas nas data-recovery cli-tool synology-drive backup-restore

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 - Initial Release Latest
Jan 30, 2026

Packages

 
 
 

Contributors

Languages