Skip to content

README-RU.md

Latest commit

 

History

History
230 lines (156 loc) · 10.3 KB

README-RU.md

File metadata and controls

230 lines (156 loc) · 10.3 KB

Radian

Radian

Продакшн-готовый Telegram-бот для управления объектным хранилищем Cloudflare R2

Загружайте, организовывайте и управляйте файлами прямо из Telegram без веб-интерфейса.

Обзор

Radian безопасный, полнофункциональный Telegram-бот, предоставляющий полные возможности управления объектным хранилищем через интуитивный чат-интерфейс. Создан для продакшн-окружений с комплексными средствами безопасности, поддержкой нескольких бакетов и корпоративной надёжностью.

Возможности

Операции с файлами

  • Загрузка Отправляйте любые файлы, фото, видео, аудио или документы в ваш R2-бакет
  • Произвольные имена Переименовывайте файлы перед загрузкой (расширения сохраняются автоматически)
  • Ссылки для копирования Автоматически генерируемые markdown-ссылки после каждой загрузки
  • Просмотр Список всех файлов с размером и датой изменения
  • Просмотр Генерация подписанных или кастомных URL для любого файла
  • Метаданные Просмотр полной информации о файле (размер, MIME-тип, ETag, временные метки)
  • Переименование Переименование файла на месте (атомарная операция копирования-удаления)
  • Перемещение Бесшовный перенос файлов между бакетами
  • Поиск Поиск по подстроке без учёта регистра

Массовые операции

  • Удаление одного Удаление файла с подтверждением
  • Массовое удаление Интерфейс множественного выбора для удаления с параллельной обработкой
  • Очистка бакета Полная очистка бакета с пагинацией (работает с большими бакетами)

Аналитика

  • Статистика по бакетам Количество файлов, общий размер, средний размер, топ-5 largest файлов
  • Глобальный обзор Агрегированная статистика по всем настроенным бакетам

Конфигурация

  • Бакет по умолчанию Пропуск экрана выбора для часто используемых бакетов
  • Несколько бакетов Неограниченная конфигурация бакетов с inline-выбором
  • Управление сессиями Отмена любой операции и мгновенная очистка состояния
  • Меню команд Все команды зарегистрированы в нативном меню Telegram

Безопасность

  • Контроль доступа Аутентификация на основе белого списка
  • Санитизация путей Защита от атак обхода директорий
  • Ограничения размера Принудительные ограничения загрузки
  • TTL сессии Автоматическая очистка устаревших сессий (10 минут)
  • Валидация бакетов Проверка белого списка при каждом callback
  • Валидация при запуске Бот отказывается запускаться с неполной конфигурацией

Расширенные функции

  • Постоянные сессии Сессии сохраняются на диск и переживают перезапуск процесса
  • Ограничение частоты Ограничение запросов на пользователя предотвращает злоупотребление API
  • Аудит логирование Полный журнал аудита всех действий пользователей с ежедневной ротацией
  • Параллельная обработка Массовые операции выполняются параллельно для оптимальной производительности

Требования

  • Bun runtime
  • Аккаунт Cloudflare с включённым R2
  • Токен Telegram-бота от @BotFather

Установка

1. Клонирование и установка

git clone https://github.com/pimatis/radian.git
cd radian
bun install

2. Конфигурация окружения

cp .env.example .env

Отредактируйте .env с вашими данными:

TELEGRAM_BOT_TOKEN=ваш_токен_бота
CF_ACCOUNT_ID=ваш_id_аккаунта_cloudflare
CF_ACCESS_KEY_ID=ваш_r2_access_key
CF_SECRET_ACCESS_KEY=ваш_r2_secret_key
CF_BUCKET_NAMES=мой-бакет,другой-бакет
ALLOWED_TELEGRAM_USER_IDS=123456789

Как найти ваш Telegram ID: Напишите @userinfobot

Создание R2 API-ключей: Cloudflare Dashboard → R2 → Manage R2 API Tokens → Create API Token (требуются права Object Read & Write)

3. Запуск

bun start

Режим разработки с автоперезагрузкой:

bun dev

Расширенная конфигурация

Кастомные домены

Настройка публичных доменов для URL бакетов:

CF_BUCKET_DOMAINS=мой-бакет=https://files.example.com,другой-бакет=https://media.example.com

При настройке все сгенерированные ссылки используют публичные URL вместо временных подписанных URL.

Хранение сессий

Сессии по умолчанию сохраняются в ./data/sessions/. Вы можете настроить расположение хранилища:

SESSIONS_DIR=/path/to/custom/sessions

Сессии переживают перезапуск процесса и автоматически очищаются после истечения 10-минутного TTL.

Ограничение частоты

Предотвратите злоупотребление API с помощью ограничения запросов на пользователя:

RATE_LIMIT_WINDOW_MS=60000        # Временное окно в миллисекундах (по умолчанию: 1 минута)
RATE_LIMIT_MAX_REQUESTS=30        # Максимум запросов за окно (по умолчанию: 30)

Аудит логирование

Все действия пользователей логируются для соответствия требованиям и мониторинга безопасности:

AUDIT_ENABLED=true                # Включить/отключить аудит логирование (по умолчанию: true)
AUDIT_LOGS_DIR=./data/audit       # Директория для аудит логов

Логи ротируются ежедневно в формате: audit-ГГГГ-ММ-ДД.log. Каждая запись включает:

  • ID пользователя и имя пользователя
  • Выполненное действие (загрузка, удаление, переименование и т.д.)
  • Целевой бакет и ключ файла
  • Метку времени и статус

Размер файла и срок действия URL

MAX_FILE_SIZE_BYTES=52428800      # Максимальный размер загрузки (по умолчанию: 50MB)
PRESIGNED_URL_EXPIRY=3600         # Срок действия подписанного URL в секундах (по умолчанию: 1 час)

Продакшн развёртывание

Управление процессами

Используйте PM2 или аналогичный менеджер процессов для продакшна:

# Установите PM2 глобально
npm install -g pm2

# Запустите с PM2
pm2 start index.ts --name radian --interpreter bun

# Включите автоматический перезапуск при сбое
pm2 startup
pm2 save

Docker развёртывание

FROM oven/bun:latest
WORKDIR /app
COPY . .
RUN bun install
CMD ["bun", "start"]

Соберите и запустите:

docker build -t radian .
docker run -d --env-file .env -v ./data:/app/data radian

Сохранение данных

Бот хранит три типа данных в директории ./data/:

  • sessions/ - Активные сессии пользователей (переживают перезапуски)
  • ratelimits/ - Отслеживание ограничений частоты
  • audit/ - Ежедневные аудит логи

Важно: Смонтируйте постоянный том для директории ./data при использовании Docker или облачных развёртываний, чтобы сохранить сессии и логи между перезапусками.

Лицензия

MIT License. См. файл LICENSE.