TgActor

Личная open-source панель для работы с Telegram-аккаунтами: импорт сессий, прокси, сценарии диалогов, мониторинг каналов и общий инбокс. Запускается на своём компьютере или сервере.

Все скриншоты в этой документации сделаны на демонстрационных данных. Они не содержат реальных сессий, переписок, номеров телефонов, паролей или ключей API.

Быстрый запуск

Нужны Git и Docker с Compose.

git clone https://github.com/ivanchik-byte/TgActor.git
cd TgActor
cp .env.example .env

В .env задайте собственный ADMIN_PASSWORD, а также значения SECRET_KEY и ENCRYPTION_KEY. Не оставляйте значения-заглушки из примера. Как создать ключи, описано в разделе Конфигурация.

docker compose up -d --build

Откройте локальную панель и введите пароль из своей конфигурации. Docker собирает frontend, запускает PostgreSQL и Redis, затем применяет миграции и поднимает API.

Что есть в панели

Раздел	Для чего нужен
Аккаунты	Импорт TData ZIP, вход по номеру телефона, переименование профилей, проверка сессий и привязка прокси.
Пулы аккаунтов	Распределение профилей между комментированием и реакциями, массовое назначение ролей.
Каналы	Мониторинг публикаций, режим первого комментария, задержки отправки и плавный вход в группы обсуждений.
Сценарии	Редактор цепочек сообщений, ответы на предыдущие шаги, вложения, роли участников и предпросмотр диалога.
Промпты	Библиотека инструкций, категории, генерация сценариев и редактирование шаблонов.
Входящие	Общий список переписок, отправка сообщений и файлов, ответы, редактирование и удаление сообщений.
История действий	Хронология, консоль и табличный просмотр событий, фильтры и экспорт CSV.

Интерфейс адаптируется под телефон и ноутбук. Есть светлая тема и три тёмных: «Графит», «Сланец» и «Бордо». Выбор сохраняется в браузере. Выпадающие списки и подтверждения удаления оформлены внутри приложения; ими можно пользоваться с клавиатуры.

Скриншоты

Сценарии диалогов

Шаги, паузы и роли редактируются в одном разделе. На ноутбуке параметры и симуляция располагаются под широким полем сообщения; на большом экране редактор использует три колонки.

Единый инбокс

Список диалогов сгруппирован по аккаунтам. Перед отправкой видно, от какого профиля ведётся переписка.

Библиотека промптов, вход и мобильная версия

Библиотека хранит инструкции для статических и динамических сценариев.

Экран входа использует пароль из локальной конфигурации.

На телефоне навигация открывается отдельной панелью, а рабочие блоки располагаются друг под другом.

Полная галерея интерфейса.

Как начать работу

1. В разделе «Аккаунты» загрузите ZIP с TData или авторизуйте профиль по номеру телефона. Если включена двухфакторная защита, укажите её пароль.
2. Добавьте прокси и привяжите их к аккаунтам. При включённом USE_PROXY неподключённые к прокси профили не участвуют в Telegram-операциях.
3. Распределите аккаунты по пулам. Комментаторы выполняют шаги сценария; пул реакций используется для реакций на сообщения.
4. Создайте сценарий вручную либо подготовьте инструкции в библиотеке промптов. Настройки ИИ находятся в разделе сценариев.
5. Добавьте каналы, выберите режим обработки и задержки. Запуск мониторинга выполняется отдельной кнопкой.
6. Проверяйте результаты в истории, а личные сообщения обрабатывайте во входящих.

Генерация поддерживает OpenAI, DeepSeek, NVIDIA NIM, OpenRouter, Gemini и совместимые API. Список моделей и доступность конкретных возможностей зависят от выбранного провайдера. Учетные данные провайдера задаются в самой панели.

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

Настройки окружения описаны в .env.example. Настоящий .env не должен попадать в Git.

Переменная	Назначение
ADMIN_PASSWORD	Пароль входа в личную панель. Обязателен.
SECRET_KEY	Ключ для подписи токенов и шифрования сессий. Обязателен; при отсутствии используется ENCRYPTION_KEY.
ENCRYPTION_KEY	Ключ сессий. Для первой установки можно задать то же значение, что у SECRET_KEY.
DATABASE_URL	Подключение SQLAlchemy к базе. Docker Compose использует PostgreSQL.
REDIS_URL	Адрес Redis для очередей и фоновой работы.
PORT	Порт панели в Docker Compose; по умолчанию 8000.
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB	Параметры контейнера PostgreSQL. Если меняете их, обновите соответствующий DATABASE_URL.

Случайный ключ можно создать через Python:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Результат запишите в конфигурацию самостоятельно. Пароль панели задайте отдельно. Значения ключей сохраняйте между перезапусками: после их замены старые Telegram-сессии могут перестать расшифровываться.

У backend также есть переменные USE_PROXY, ENABLE_CHANNEL_MONITOR, ENABLE_INBOX_LISTENER, TELEGRAM_API_ID и TELEGRAM_API_HASH. Если переопределяете их при запуске через Compose, добавьте их в environment сервиса backend: одного присутствия в .env недостаточно, чтобы передать произвольную переменную внутрь контейнера.

Файлы TData, локальные базы, содержимое data/, media/ и токены относятся к данным вашей установки. Их не нужно прикладывать к Issues или скриншотам.

Обновление и остановка

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

git pull
docker compose up -d --build

Обычная остановка сохраняет именованные тома базы и Redis:

docker compose down

Посмотреть состояние и журнал backend:

docker compose ps
docker compose logs --tail=100 backend

Разработка

Frontend: React 19, TypeScript 6, Vite 8, Tailwind CSS 4, TanStack Query, Phosphor Icons и Radix Select. Backend: Python, FastAPI, SQLAlchemy, Alembic и Hydrogram.

Для сборки frontend нужен Node.js 20.19+ либо 22.12+.

cd frontend
npm ci
npm run dev

Dev-сервер доступен на localhost:5173. Запросы /api, /media и /ws передаются локальному backend на порту 8000. Для отдельного размещения API используется VITE_API_URL; это настройка сборки Vite.

Для разработки backend нужны Python 3.11+, PostgreSQL и Redis, доступные с вашей машины. В .env укажите их адреса вместо контейнерных имён db и redis.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
set -a
. ./.env
set +a
alembic upgrade head
uvicorn main:app --host 127.0.0.1 --port 8000

Команды активации окружения и импорта .env выше предназначены для Linux и macOS. На Windows проще начать с Docker Compose, который одинаково запускается из PowerShell и терминала Linux.

Production-сборка создаётся командой npm run build в каталоге frontend. FastAPI обслуживает готовый frontend/dist, поэтому для обычного запуска отдельный сервер Node.js не нужен.

Проверки интерфейса

cd frontend
npx playwright install chromium
npm run build
npm run lint
npm test

Playwright проверяет разделы с данными, авторизацию, поиск и фильтры, смену темы, навигацию, сохранение сценария, отправку сообщения и подтверждение удаления. Проверки ширины включают экраны 360, 375, 768, 1024 и 1440 px.

HTTP и WebSocket в браузерных тестах заменены тестовыми ответами. Тесты не отправляют сообщения в Telegram и не обращаются к платным API. Они проверяют frontend и формат запросов, а не доступность внешних сервисов.

Повторно снять демонстрационные скриншоты:

CAPTURE_UI=1 npm test

Файлы появятся в frontend/test-results. Устройство дизайн-системы описано отдельно.

Ограничения

TgActor рассчитан на личную установку с одним паролем входа. Отдельных пользователей, тарифов и совместных рабочих пространств нет.

Telegram может ограничивать отдельные сессии и операции. Паузы и прокси не отменяют ограничения платформы; точная причина неудачной операции отображается в истории. Каналы без доступной группы обсуждений нельзя обрабатывать как обычную ветку комментариев.

Генерация ИИ требует настроенного провайдера и его действующего ключа. Чтение аккаунтов, ручное редактирование сценариев и работа с библиотекой не требуют генерации текста.

Участие в проекте

Ошибки и предложения можно оставлять в Issues. Для воспроизведения достаточно версии, шагов и очищенного журнала без секретов. Правила внесения изменений находятся в CONTRIBUTING.md, порядок сообщения об уязвимостях в SECURITY.md.

Лицензия: MIT.