From 31665ca31262f44c08886e52c69aae1fc88c5e6c Mon Sep 17 00:00:00 2001 From: Misha Date: Thu, 27 Nov 2025 22:00:48 +0200 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 704 ++++++++++++++---------------------------------------- 1 file changed, 183 insertions(+), 521 deletions(-) diff --git a/README.md b/README.md index bdda96a..393eb6b 100644 --- a/README.md +++ b/README.md @@ -1,521 +1,183 @@ -# 🛡️ 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 - +# 🛡️ Discord Anti-Nuke Бот + +Полнофункциональный Discord бот для защиты сервера от краша, спама и вредоносных ботов. Бот автоматически отслеживает подозрительную активность, применяет наказания и восстанавливает удалённые элементы. + +## 📖 Описание + +- ✅ Автоматически защищает от массового удаления каналов и ролей +- ✅ Предотвращает добавление вредоносных ботов +- ✅ Блокирует спам и злоупотребление упоминаниями +- ✅ Отслеживает изменения названия и иконки сервера +- ✅ Восстанавливает удалённые элементы автоматически +- ✅ Ведёт подробные логи всех событий +- ✅ Применяет наказания нарушителям + +--- + +## 🎯 Функционал + +### Защита от краша сервера (Anti-Nuke) + +- **Массовое удаление каналов**: Отслеживает количество удалённых каналов за период времени +- **Массовое удаление ролей**: Контролирует удаление ролей +- **Массовое создание каналов/ролей**: Предотвращает создание большого количества элементов +- **Изменение сервера**: Защищает от изменения названия и иконки сервера +- **Выдача админских прав**: Отслеживает массовую выдачу административных прав + +### Защита от ботов (Anti-Bot) + +- Автоматическая проверка всех добавляемых ботов +- Сравнение с белым списком разрешённых ботов +- Бан неразрешённых ботов и пригласивших их пользователей + +### Защита от спама (Anti-Spam) + +- Контроль частоты сообщений +- Защита от злоупотребления упоминаниями (@everyone, @here) +- Автоматический мут или бан спамеров + +### Автоматическое восстановление + +- Сохранение данных каналов и ролей перед удалением +- Автоматическое восстановление удалённых элементов +- Сохранение всех разрешений и настроек + +--- + +## ⚙️ Настройка + +### 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` конфигурации. Эти пользователи и боты не будут забанены системой защиты. + +--- + +## 💬 Команды + +Все команды доступны через 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` без перезапуска бота. + +--- + +## 📝 Логирование + +Бот ведёт логи в двух местах: + +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 +```