Skip to content

L1ghtsitte/human

BranchesTags

Repository files navigation

HUMAN Discord Bot + Web Panel

Полноценный стек для Discord-бота:

  • bot (discord.py) с slash-командами, модерацией, автоматизациями и интеграциями.
  • api (FastAPI) для веб-панели и защищенного доступа.
  • frontend (React + Vite) для управления сервером через браузер.
  • postgres + redis.
  • новая система внешних плагинов из GitHub Release через раздел Плагины в панели.

1) Архитектура

Discord -> bot (discord.py)
              |
              v
           postgres <-> api (FastAPI) <-> frontend (React)
              ^
              |
           redis cache

api <-> bot management API (enable/disable/reload plugin)
api <-> /plugins volume (download/install plugin package)
bot <-> /plugins volume (runtime load plugin)

2) Что уже реализовано

  • Базовые cogs: админ-функции, модерация, опросы, welcome/events, voice, feeds.
  • Вход в веб-панель через одноразовый код /site.
  • Панель управления сервером, участниками, модерацией, опросами, статистикой, настройками.
  • Plugin Marketplace Runtime:
    • установка плагина из GitHub release-архива (.zip / .tar.gz),
    • статусы плагина (enabled, disabled, error),
    • включение/выключение/перезагрузка/удаление без ручного редактирования кода,
    • авто-подгрузка включенных плагинов после рестарта бота.

3) Структура репозитория

api/         FastAPI backend
bot/         Discord bot + built-in cogs + plugin runtime
db/          SQL schema + migrations
frontend/    React web panel
plugins/     Каталог установленных внешних плагинов (runtime)

4) Быстрый запуск (рекомендуется: Docker Compose)

Требования:

  • Docker 24+
  • Docker Compose v2+

Шаги:

  1. Скопируйте .env.example в .env.
  2. Заполните все обязательные переменные (см. раздел ниже).
  3. Запустите:
docker compose up -d --build

Проверка:

  • API health: http://localhost:8000/health
  • Frontend: http://localhost:3000

Остановка:

docker compose down

5) Установка без Docker

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y python3 python3-venv python3-pip nodejs npm postgresql redis-server
  1. API:
cd api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000
  1. Bot:
cd bot
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py
  1. Frontend:
cd frontend
npm install
npm run build
npm run dev

Windows (PowerShell)

  1. Установите: Python 3.11+, Node.js 20+, PostgreSQL, Redis.
  2. API:
cd api
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000
  1. Bot:
cd bot
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py
  1. Frontend:
cd frontend
cmd /c npm install
cmd /c npm run dev

macOS

brew install python node postgresql redis

Дальше шаги те же, что для Linux.

6) Полная конфигурация .env

Минимум для старта:

DISCORD_TOKEN=
SERVER_ID=
DATABASE_URL=postgresql://discord_bot:secure_password@postgres:5432/discord_bot_db
REDIS_URL=redis://redis:6379/0
API_SECRET_KEY=
BOT_MANAGEMENT_TOKEN=

Подробно по ключам:

Discord / Bot

  • DISCORD_TOKEN - токен бота из Discord Developer Portal.
  • BOT_PREFIX - префикс текстовых команд (для slash не обязателен).
  • SERVER_ID - ID сервера для мгновенного sync slash-команд.
  • WELCOME_CHANNEL_ID, BOOST_CHANNEL_ID, TRIGGER_VOICE_CHANNEL_ID, DYNAMIC_VOICE_CATEGORY_ID - ID каналов/категорий.
  • TELEGRAM_FORWARD_CHANNEL_ID, YOUTUBE_FORWARD_CHANNEL_ID - default каналы для пересылки.

DB

  • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB - параметры Postgres.
  • DATABASE_URL - строка подключения для API и бота.

API / Auth

  • API_HOST, API_PORT - адрес API.
  • API_SECRET_KEY - секрет JWT (обязательно заменить).
  • API_ADMIN_USER, API_ADMIN_PASSWORD - legacy параметры (можно оставить).

Web

  • WEB_PANEL_URL - публичный URL панели (используется в сообщениях бота).
  • VITE_API_URL (в контейнере frontend) - URL API, обычно /api через reverse proxy.

Интеграции

  • TELEGRAM_API_TOKEN, TELEGRAM_CHANNELS, TELEGRAM_CHECK_INTERVAL
  • YOUTUBE_API_KEY, YOUTUBE_CHANNELS, YOUTUBE_CHECK_INTERVAL

Плагины (новое)

  • PLUGINS_DIR - общий путь к установленным плагинам (/plugins в Docker).
  • BOT_MANAGEMENT_URL - URL внутреннего управления ботом (для API), по умолчанию http://bot:8091.
  • BOT_MANAGEMENT_HOST / BOT_MANAGEMENT_PORT - на чем бот поднимает внутренний plugin API.
  • BOT_MANAGEMENT_TOKEN - общий токен API<->бот (обязательно длинный случайный).

Runtime

  • ENVIRONMENT - production или development.
  • DEBUG - true/false.

7) Базовые slash-команды бота

Администрирование и utility

  • /site, /stats, /afk, /ping, /panel, /serverrules, /serverinfo
  • /userinfo, /userinfox, /avatar
  • /setup, /templates, /welcomepreset, /setwelcome, /setwelcomevariants
  • /setchannelcfg, /setsetting, /permissions, /setfeedstyle
  • /announce, /language, /time, /roll, /choose, /remind, /botinfo, /help

Модерация

  • /warn, /masswarn, /warnings, /modlog
  • /kick, /ban, /unban
  • /purge, /clear, /slowmode, /slowmodepreset, /lock, /unlock
  • /timeout, /untimeout, /nick, /roleadd, /roleremove, /note, /clearwarns

Опросы

  • /poll

8) Работа с плагинами через веб-панель

  1. Откройте раздел Плагины.
  2. Вставьте Release Asset URL (например, https://github.com/org/repo/releases/download/v1.0.0/plugin.zip).
  3. Нажмите Установить плагин.
  4. Управляйте кнопками:
    • Enable
    • Disable
    • Reload
    • Delete

Статусы:

  • enabled - загружен в runtime.
  • disabled - установлен, но не активен.
  • error - ошибка загрузки/инициализации (см. last_error).

9) Формат плагина

Архив релиза должен содержать plugin.json:

{
  "slug": "coin-flip",
  "name": "Coin Flip",
  "version": "1.0.0",
  "description": "Slash команда /coin",
  "entrypoint": "coin_plugin.py"
}

Требования:

  • slug: a-z, 0-9, _, -.
  • entrypoint: путь к .py внутри архива.
  • entrypoint должен экспортировать setup(bot).
  • Для корректного выключения рекомендуется teardown(bot).

10) Деплой на VPS (production)

  1. Клонируйте репозиторий на сервер.
  2. Создайте .env.
  3. Запустите:
docker compose up -d --build
  1. Настройте reverse proxy (nginx) для:
  • frontend:3000
  • api:8000
  1. Добавьте TLS (Let's Encrypt).
  2. Проверьте health endpoints.

11) Публикация на GitHub без мусора

Перед push:

  • убедитесь, что .env не попал в git,
  • не коммитьте node_modules, __pycache__, временные архивы,
  • оставьте в plugins/ только .gitkeep.

Проверка:

git status
git add .
git commit -m "feat: plugin system and web plugin manager"
git push origin main

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

  • Никогда не публикуйте .env.
  • Сразу меняйте API_SECRET_KEY и BOT_MANAGEMENT_TOKEN.
  • Устанавливайте плагины только из проверенных GitHub релизов.
  • Для чувствительных плагинов делайте ревью кода перед установкой.

13) Диагностика

  • Проверка сервиса:
    • docker compose logs -f api
    • docker compose logs -f bot
    • docker compose logs -f frontend
  • Проверка plugin runtime:
    • если статус error, смотрите last_error в панели и логи бота.

Если нужен enterprise-режим (подпись релизов, allowlist репозиториев, sandbox для плагинов), это можно надстроить отдельным security-слоем в следующей итерации.

About

human-discord-bot

Topics

admin web moderation dicsord-bot human-discord-bot

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages