From 2c6903ce947d83210ac9c98aa0b19749a9fee7dd Mon Sep 17 00:00:00 2001 From: Misha Date: Thu, 27 Nov 2025 21:58:36 +0200 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?/=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 521 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..bdda96a --- /dev/null +++ b/README.md @@ -0,0 +1,521 @@ +# 🛡️ Discord Anti-Nuke Бот + +Полнофункциональный Discord бот для защиты сервера от краша, спама и вредоносных ботов. Бот автоматически отслеживает подозрительную активность, применяет наказания и восстанавливает удалённые элементы. + +--- + +## 📋 Содержание + +1. [Описание](#описание) +2. [Функционал](#функционал) +3. [Установка](#установка) +4. [Настройка](#настройка) +5. [Запуск](#запуск) +6. [Модули](#модули) +7. [Команды](#команды) +8. [База данных](#база-данных) +9. [Логирование](#логирование) +10. [Запуск на Pterodactyl](#запуск-на-pterodactyl) +11. [Решение проблем](#решение-проблем) + +--- + +## 📖 Описание + +Discord Anti-Nuke бот — это комплексная система защиты сервера, которая: + +- ✅ Автоматически защищает от массового удаления каналов и ролей +- ✅ Предотвращает добавление вредоносных ботов +- ✅ Блокирует спам и злоупотребление упоминаниями +- ✅ Отслеживает изменения названия и иконки сервера +- ✅ Восстанавливает удалённые элементы автоматически +- ✅ Ведёт подробные логи всех событий +- ✅ Применяет наказания нарушителям + +--- + +## 🎯 Функционал + +### Защита от краша сервера (Anti-Nuke) + +- **Массовое удаление каналов**: Отслеживает количество удалённых каналов за период времени +- **Массовое удаление ролей**: Контролирует удаление ролей +- **Массовое создание каналов/ролей**: Предотвращает создание большого количества элементов +- **Изменение сервера**: Защищает от изменения названия и иконки сервера +- **Выдача админских прав**: Отслеживает массовую выдачу административных прав + +### Защита от ботов (Anti-Bot) + +- Автоматическая проверка всех добавляемых ботов +- Сравнение с белым списком разрешённых ботов +- Бан неразрешённых ботов и пригласивших их пользователей + +### Защита от спама (Anti-Spam) + +- Контроль частоты сообщений +- Защита от злоупотребления упоминаниями (@everyone, @here) +- Автоматический мут или бан спамеров + +### Автоматическое восстановление + +- Сохранение данных каналов и ролей перед удалением +- Автоматическое восстановление удалённых элементов +- Сохранение всех разрешений и настроек + +--- + +## 🚀 Установка + +### Требования + +- Node.js 18+ +- MySQL или MariaDB +- Discord Bot Token + +### Шаги установки + +1. **Клонирование или загрузка проекта** + +```bash +cd /path/to/project +``` + +2. **Установка зависимостей** + +```bash +npm install +``` + +3. **Настройка конфигурации** + +Скопируйте файл `src/config/config.example.yml` в `src/config/config.yml`: + +```bash +cp src/config/config.example.yml src/config/config.yml +``` + +Отредактируйте `src/config/config.yml` и заполните все необходимые параметры (см. раздел [Настройка](#настройка)). + +4. **Сборка проекта** + +```bash +npm run build +``` + +--- + +## ⚙️ Настройка + +### 1. Получение Discord Bot Token + +1. Перейдите на [Discord Developer Portal](https://discord.com/developers/applications) +2. Создайте новое приложение или выберите существующее +3. Перейдите в раздел "Bot" +4. Нажмите "Reset Token" и скопируйте токен +5. Включите следующие привилегии: + - **SERVER MEMBERS INTENT** (Privileged Gateway Intents) + - **MESSAGE CONTENT INTENT** (Privileged Gateway Intents) +6. В разделе "OAuth2" → "URL Generator": + - Выберите scope: `bot`, `applications.commands` + - Выберите permissions: `Administrator` (или минимальные: Ban Members, Manage Channels, Manage Roles, Manage Server, View Audit Log) + - Скопируйте URL и откройте в браузере для добавления бота на сервер + +### 2. Получение ID сервера + +1. Включите режим разработчика в Discord (Настройки → Расширенные → Режим разработчика) +2. Правый клик по серверу → "Копировать ID сервера" + +### 3. Настройка базы данных + +Создайте базу данных MySQL/MariaDB: + +```sql +CREATE DATABASE antinuke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +Или используйте существующую базу данных. Бот автоматически создаст необходимые таблицы при первом запуске. + +### 4. Редактирование config.yml + +Откройте `src/config/config.yml` и заполните: + +```yaml +bot: + token: "ВАШ_ТОКЕН_БОТА" + guild_id: "ID_ВАШЕГО_СЕРВЕРА" + prefix: "!" + log_channel_id: "ID_КАНАЛА_ДЛЯ_ЛОГОВ" # Необязательно + +database: + type: "mysql" + host: "localhost" + port: 3306 + user: "root" + password: "ваш_пароль" + name: "antinuke" + +limits: + max_channel_creates: 3 + max_role_deletes: 2 + max_channel_deletes: 2 + max_role_creates: 5 + max_spam_messages: 5 + max_mentions: 3 + window_seconds: 10 + spam_window_seconds: 3 + +whitelist: + admins: + - "ID_ДОВЕРЕННОГО_АДМИНА_1" + - "ID_ДОВЕРЕННОГО_АДМИНА_2" + bots: + - "ID_РАЗРЕШЁННОГО_БОТА_1" + +punishment: + ban_user: true + ban_bot: true + ban_inviter: true + restore_changes: true + mute_on_spam: true + mute_duration_minutes: 10 +``` + +### 5. Настройка белого списка + +Добавьте ID доверенных администраторов и разрешённых ботов в секцию `whitelist` конфигурации. Эти пользователи и боты не будут забанены системой защиты. + +--- + +## 🏃 Запуск + +### Режим разработки + +```bash +npm run dev +``` + +### Продакшн режим + +```bash +npm run build +npm start +``` + +### Использование PM2 (рекомендуется) + +```bash +npm install -g pm2 +npm run build +pm2 start dist/index.js --name antinuke-bot +pm2 save +pm2 startup +``` + +--- + +## 🔧 Модули + +### Core модули + +#### `logger.ts` +Система логирования на основе Winston. Поддерживает логирование в консоль и файл с ротацией. + +#### `database.ts` +Модуль работы с MySQL/MariaDB. Обеспечивает подключение, создание таблиц и операции с данными. + +#### `configLoader.ts` +Загрузка и валидация конфигурации из YAML файла. + +### Модули защиты + +#### `antiNuke.ts` +Основной модуль защиты от краша сервера. Отслеживает массовые операции через Audit Log и сравнивает с лимитами. + +#### `antiBot.ts` +Проверяет всех добавляемых ботов и сравнивает с белым списком. + +#### `antiSpam.ts` +Контролирует частоту сообщений и упоминаний, применяет наказания за спам. + +#### `autoRestore.ts` +Сохраняет данные каналов и ролей перед удалением и восстанавливает их при необходимости. + +#### `punishment.ts` +Выполняет наказания: бан, кик, мут. Отправляет сообщения в лог-канал. + +#### `whitelist.ts` +Управление белым списком администраторов и ботов. + +--- + +## 💬 Команды + +Все команды доступны через Slash Commands (/) в Discord. + +### `/whitelist add user_id: type:` +Добавляет пользователя или бота в белый список. + +**Пример:** +``` +/whitelist add user_id:123456789012345678 type:admin +``` + +### `/whitelist remove user_id: type:` +Удаляет пользователя или бота из белого списка. + +### `/whitelist list` +Показывает текущий белый список. + +### `/antinuke status` +Отображает статус системы защиты, текущие лимиты и настройки. + +### `/antinuke test` +Проверяет работу системы защиты. + +### `/config reload` +Перезагружает конфигурацию из файла `config.yml` без перезапуска бота. + +--- + +## 🗄️ База данных + +### Структура таблиц + +#### `events_log` +Хранит все события, отслеживаемые ботом. + +| Поле | Тип | Описание | +|------|-----|----------| +| id | VARCHAR(36) | UUID события | +| user_id | VARCHAR(20) | ID пользователя | +| action | VARCHAR(100) | Тип действия | +| details | TEXT | Детали события | +| timestamp | DATETIME | Время события | + +#### `restored_items` +Хранит данные для восстановления каналов и ролей. + +| Поле | Тип | Описание | +|------|-----|----------| +| id | INT | ID записи | +| type | ENUM | Тип: channel или role | +| old_data | JSON | Данные элемента | +| restored_at | DATETIME | Время восстановления | + +#### `punishments` +Лог всех применённых наказаний. + +| Поле | Тип | Описание | +|------|-----|----------| +| id | INT | ID записи | +| user_id | VARCHAR(20) | ID пользователя | +| reason | TEXT | Причина наказания | +| punishment_type | VARCHAR(50) | Тип наказания | +| timestamp | DATETIME | Время наказания | + +--- + +## 📝 Логирование + +Бот ведёт логи в двух местах: + +1. **Консоль**: Все события выводятся в консоль с цветовой кодировкой +2. **Файл**: Логи сохраняются в файл (настраивается в `config.yml`) + +### Уровни логирования + +- `error`: Критические ошибки +- `warn`: Предупреждения +- `info`: Информационные сообщения +- `debug`: Отладочная информация + +### Настройка логирования + +В `config.yml`: + +```yaml +logging: + enabled: true + file_path: "./logs/bot.log" + level: "info" + max_file_size: "10m" + max_files: 5 +``` + +--- + +## 🐳 Запуск на Pterodactyl + +### 1. Создание яйца (Egg) + +Если у вас есть доступ к панели Pterodactyl, создайте новое яйцо для Node.js приложения. + +### 2. Настройка сервера + +1. Создайте новый сервер в Pterodactyl +2. Выберите яйцо Node.js +3. Установите следующие переменные окружения (если нужно): + - `NODE_VERSION`: `18` или выше + +### 3. Установка зависимостей + +В консоли сервера выполните: + +```bash +npm install +``` + +### 4. Настройка конфигурации + +Отредактируйте `src/config/config.yml` через файловый менеджер или через консоль: + +```bash +nano src/config/config.yml +``` + +### 5. Сборка и запуск + +```bash +npm run build +npm start +``` + +### 6. Автозапуск + +Pterodactyl автоматически перезапустит бота при перезагрузке сервера, если процесс завершится. + +### Альтернатива: использование PM2 + +Если хотите использовать PM2 на Pterodactyl: + +1. Установите PM2 в консоли сервера: +```bash +npm install -g pm2 +``` + +2. Создайте файл `ecosystem.config.js`: +```javascript +module.exports = { + apps: [{ + name: 'antinuke-bot', + script: 'dist/index.js', + instances: 1, + autorestart: true, + watch: false, + max_memory_restart: '500M', + }] +}; +``` + +3. Запустите через PM2: +```bash +npm run build +pm2 start ecosystem.config.js +pm2 save +``` + +--- + +## 🔍 Решение проблем + +### Бот не запускается + +**Проблема**: Ошибка при запуске бота + +**Решения**: +1. Проверьте правильность токена в `config.yml` +2. Убедитесь, что бот добавлен на сервер с необходимыми правами +3. Проверьте подключение к базе данных +4. Убедитесь, что Node.js версии 18+ + +### Ошибки подключения к БД + +**Проблема**: `Error: connect ECONNREFUSED` + +**Решения**: +1. Проверьте, что MySQL/MariaDB запущен +2. Проверьте правильность хоста, порта, пользователя и пароля +3. Убедитесь, что база данных существует +4. Проверьте права доступа пользователя БД + +### Бот не реагирует на события + +**Проблема**: Бот онлайн, но не обрабатывает события + +**Решения**: +1. Проверьте, что `guild_id` в конфиге соответствует ID сервера +2. Убедитесь, что бот имеет необходимые права на сервере +3. Проверьте, что включены необходимые Intents в Discord Developer Portal +4. Проверьте логи на наличие ошибок + +### Команды не работают + +**Проблема**: Slash Commands не отображаются или не работают + +**Решения**: +1. Подождите несколько минут после запуска (команды регистрируются асинхронно) +2. Проверьте права бота (нужны права на использование Slash Commands) +3. Убедитесь, что бот имеет права Administrator или необходимые минимальные права +4. Попробуйте перезапустить бота + +### Бот банит легитимных пользователей + +**Проблема**: Бот банит администраторов или разрешённых ботов + +**Решения**: +1. Добавьте ID администраторов в `whitelist.admins` в конфиге +2. Добавьте ID разрешённых ботов в `whitelist.bots` +3. Перезагрузите конфигурацию командой `/config reload` или перезапустите бота + +### Восстановление не работает + +**Проблема**: Удалённые каналы/роли не восстанавливаются + +**Решения**: +1. Убедитесь, что `punishment.restore_changes: true` в конфиге +2. Проверьте права бота (нужны права на создание каналов и ролей) +3. Проверьте логи на наличие ошибок восстановления +4. Убедитесь, что данные сохраняются в БД (проверьте таблицу `restored_items`) + +### Высокое использование памяти + +**Проблема**: Бот потребляет много памяти + +**Решения**: +1. Уменьшите `max_files` в настройках логирования +2. Уменьшите `max_file_size` для логов +3. Используйте PM2 с ограничением памяти +4. Регулярно очищайте старые записи из БД + +--- + +## 📞 Поддержка + +Если у вас возникли проблемы, не описанные в этом руководстве: + +1. Проверьте логи бота в файле или консоли +2. Проверьте логи базы данных +3. Убедитесь, что все зависимости установлены: `npm install` +4. Проверьте версию Node.js: `node --version` (должна быть 18+) + +--- + +## 📄 Лицензия + +MIT License + +--- + +## 🙏 Благодарности + +Бот создан с использованием: +- [discord.js](https://discord.js.org/) - Discord API библиотека +- [mysql2](https://github.com/sidorares/node-mysql2) - MySQL драйвер +- [winston](https://github.com/winstonjs/winston) - Система логирования +- [js-yaml](https://github.com/nodeca/js-yaml) - Парсер YAML + +--- + +**Версия**: 1.0.0 +**Последнее обновление**: 2024 +