Files Node Bot

A professional private NAS management bot for Telegram.

Manage your NAS files and directories directly from Telegram with a powerful, interactive interface.

---

✨ Features

• 📥 Interactive Upload: Send any file and browse folders to select exactly where to save it.
• 📂 Folder Manager: Create (/mkdir) or move directories to trash via a guided UI.
• 🔎 Smart Search: Recursive filename search across the entire NAS (all folders, not just categories) with /find or the 🔎 Find button, including pagination.
• 📑 File Browser: Browse NAS categories with pagination, file size display, and last-modified timestamps.
• 🗑️ Safe Deletion: Files and folders are moved to .trash/ — never permanently deleted immediately.
• ⏱️ Rate Limiting: Built-in cooldown on heavy operations (save, delete) to protect the NAS.
• 📊 Storage Health: Real-time disk usage monitoring with visual progress bars.
• 🚀 Local API Support: Handles large files (up to 2GB) using a Local Bot API Server.
• 🛡️ Private & Secure: Multi-user authorization support via whitelist.

---

🔧 Stack

	Tool
Language	Python 3.12+
Framework	aiogram v3.x
Logic	Asyncio (Asynchronous I/O)
Filesystem	Pathlib & Shutil
API Server	telegram-bot-api (Local)

---

📁 Project Structure

files-node-bot/
├── main.py              # Entry point, router registration, and startup
├── config.py            # Professional config validation & environment loading
├── requirements.txt     # Project dependencies
├── handlers/            # UI & Logic Handlers
│   ├── commands.py      # Basic commands (/start, /space)
│   ├── files.py         # Advanced upload & folder selection logic
│   ├── search.py        # Browsing, pagination, /find, and file options
│   └── folders.py       # Interactive Folder Manager (Create/Delete wizard)
└── utils/               # Internal Utilities
    └── storage.py       # Disk usage, sanitization, and filesystem helpers

---

🚀 Setup

1. Environment Variables

Create a .env file in the root directory:

BOT_TOKEN=your_telegram_bot_token
ALLOWED_USER_ID=12345678,987654321  # Comma-separated list of authorized IDs
NAS_PATH=/mnt/nas                   # Absolute path to your NAS root
LOCAL_API_SERVER_URL=http://localhost:8081

2. Install Dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Local Bot API Server (Optional)

To support files larger than 50MB (up to 2GB), run a local Telegram Bot API server:

./telegram-bot-api --api-id=YOUR_ID --api-hash=YOUR_HASH --local

4. Run the Bot

python main.py

5. Run as systemd Service

To ensure the bot runs automatically on boot and restarts if it crashes:

Create /etc/systemd/system/files-bot.service:

[Unit]
Description=Files Node Telegram Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/your/files-node-bot
ExecStart=/path/to/your/files-node-bot/venv/bin/python3 main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# Reload, enable and start
sudo systemctl daemon-reload
sudo systemctl enable files-bot.service
sudo systemctl start files-bot.service

# View live logs
sudo journalctl -u files-bot.service -f

---

🎛️ Interface

The bot uses a persistent Reply Keyboard — no need to type commands.

[ 🔍 Browse ]  [ 🔎 Find  ]
[ 📂 Folders ]  [ 📊 Storage ]

Button	Action
🔍 Browse	Open NAS category browser
🔎 Find	Search files by name across entire NAS
📂 Folders	Open Folder Manager (create / delete)
📊 Storage	Check disk usage and free space

📥 Send any file directly to the chat to trigger the upload flow.

---

💬 Commands

Command	Description
/start	Show welcome message and persistent menu
/search	Browse NAS categories and files with pagination
/find [name]	Recursive filename search across entire NAS (all folders)
/mkdir	Open interactive Folder Manager (Create / Move to Trash)
/space	Check NAS storage status and health

---

📂 Category Mapping

The bot automatically suggests folders based on file extensions:

Category	Extensions
Documents	.pdf, .docx, .xlsx, .txt, .pptx, .md
Media	.png, .jpg, .mp4, .mov, .gif, .mp3, .wav
Data	.csv, .json, .sql, .xml, .yaml
Scripts	.py, .sh, .js, .ts, .go, .cpp
Archives	.zip, .tar, .gz, .7z, .rar

---

🗑️ Trash & Recovery

Deleted files and folders are never permanently removed immediately. They are moved to a .trash/ directory inside NAS_PATH with a Unix timestamp prefix:

/mnt/nas/.trash/
├── 1711900000_report.pdf
└── 1711900050_old-project/

To recover a file, simply move it back to its original location manually via SSH or a file manager.

Note: The .trash/ folder is not auto-purged. Clean it up manually when needed.

---

🛠️ Troubleshooting

Bad Request: can't parse entities

The bot uses HTML parse mode for stability. If you see this error, ensure that any manual code changes correctly escape HTML tags (<, >, &). Filenames and paths are automatically handled.

Files not saving to NAS

Check that the user running the bot has write permissions for the NAS_PATH directory. You can verify this by running touch /path/to/nas/test_file.

Large files failing to upload

Standard Telegram bots are limited to 50MB. To handle larger files, you must use a Local Bot API Server and ensure LOCAL_API_SERVER_URL is correctly set in your .env.

---

📄 License

MIT