Telegram-бот для управления отпусками и выходными днями

Эта статья - полноценное руководство по развёртыванию нашего Telegram-бота “LL weekend bot” на VPS/выделенном сервере. Ниже - что умеет бот, какие задачи закрывает в команде, пошаговая установка под Ubuntu/Debian, автозапуск через systemd, обновления с перезапуском, бэкапы и типичные ошибки. В конце вы сможете скачать архив с ботом. Время установки зависит от сервера и настройки доступа.

Кому нужен бот для управления отпусками?

Команды любого размера постоянно сталкиваются с рутиной: заявки на отпуск, согласование, кто когда отсутствует, ограничения по пересечениям, лимиты по дням, CSV-выгрузки для бухгалтерии и т. д. Бот автоматизирует всё это прямо в Telegram, без внешних платных сервисов и лишних интеграций.

Ключевые выгоды:

• Своя база: SQLite хранится на вашем сервере, сообщения проходят через Telegram API. Хостинг и администрирование оплачиваются отдельно.
• Прозрачность: статусы заявок, история, напоминания, выгрузки.
• Ускорение процессов: админы утверждают/отклоняют в один клик, сотрудники подают заявки за секунды.
• Изоляция по командам: каждый workspace - отдельная команда с собственными типами отпусков, политиками и лимитами.
• Лёгкая поддержка: Python + python-telegram-bot, без сложных брокеров и монструозных стэков.

Функционал бота: краткий обзор

Роли и команды

• Роли: админские (CEO, OWNER, TIMLID, TECH) и пользовательские (BAER, DESIGNER, FARMER, MANAGER, BUHGALTER).
• Членство назначает администратор команды по проверенному числовому Telegram ID. Название команды и username не дают доступ.

Заявки на отпуска

• Быстрые диапазоны (например, 7/14 дней от ближайшего понедельника) или ручной выбор дат через встроенный календарь.
• Комментарий сотрудника к заявке (опционально).
• Проверки: запрещённые даты, пересечения с учётом политики, лимит дней за раз и лимит за год.
• Статусы: На рассмотрении → Подтверждена/Отклонена.

Админка

• Добавление/удаление сотрудников, назначение ролей.
• Управление типами отпусков (название, описание, лимит дней/год).
• Настройка политики пересечений: разрешить всем / запретить всем / запретить одинаковым ролям.
• Запреты дат (дни/диапазоны) с примечаниями, список актуальных запретов.
• Лимиты: дней в год и за один отпуск.
• Список сотрудников и остатки по годовым лимитам.
• Заявки на рассмотрении: утверждение/отклонение в один клик + комментарий.
• Экспорт CSV за год - для бухгалтерии/аналитики.
• Лёгкая анализ-сводка по месяцам и ролям.

Напоминания

• Автоматические напоминания сотрудникам за 3 дня и за 1 день до начала отпуска.

Требования к серверу

• ОС: Ubuntu 22.04/24.04 LTS (подойдёт любой Debian/Ubuntu).
• Ресурсы: 1 vCPU, 512-1024 МБ RAM, 5+ ГБ диска.
• ПО: Python 3.10+ (желательно 3.11/3.12), systemd.
• Доступ: SSH и открытый исходящий HTTPS (бот общается с Telegram API).
• Вариант хостинга по партнёрской ссылке: adminvps (актуальные условия и действие промокода BoostClicks проверьте у провайдера)

Версия от 31 октября 2026: исправлены вход в чужую команду по названию, привязка по username и проверки решений по заявкам. Офлайн-регрессии используют временную SQLite и подставной Bot без сетевых запросов. Настоящий polling в Telegram не проверялся; перед рабочим подключением пройдите тестовую заявку на своей установке.

Что внутри архива

В корне проекта будут файлы:

• telegram_vacation_bot.py - основной код бота.
• requirements.txt - зависимости Python.
• config.py - тонкие настройки (если нужны).
• .env.example - шаблон окружения. Свою .env создайте рядом с исходниками и не публикуйте.

В обновлённом ZIP исходники лежат в корне, без вложенной папки. В поставке есть .env.example, README и офлайн-тесты; рабочей базы и .env с токеном нет. Скопируйте пример в .env и задайте токен своего бота.

config.py читает TELEGRAM_TOKEN из окружения. Вручную экспортируйте свой .env перед запуском; systemd загружает его через обязательный EnvironmentFile. Не дублируйте токен в Python-коде.

Пример .env:

TELEGRAM_TOKEN=ВСТАВЬТЕ_ТОКЕН_BOTFATHER
VACATION_BOT_DB=/home/bot/app/vacation_bot.db
VACATION_BOOTSTRAP_ADMIN_IDS=ВАШ_ЧИСЛОВОЙ_TELEGRAM_ID

Если параметр VACATION_BOT_DB не указать, бот создаст БД vacation_bot.db в текущей папке.

Установка бота: пошагово

1) Подготовить сервер и пользователя

# Обновления
sudo apt update && sudo apt -y upgrade

# Установить Python и pip
sudo apt -y install python3 python3-venv python3-pip unzip sqlite3

# Создать системного пользователя (без shell) или обычного:
sudo useradd -m -d /home/bot -s /bin/bash bot
sudo passwd bot  # задайте пароль или используйте SSH-ключи

# Дать права на каталог приложения
sudo mkdir -p /home/bot/app
sudo chown -R bot:bot /home/bot

2) Залить архив и развернуть

С локального ПК (Windows PowerShell):

scp .\telegram-vacation-bot.zip bot@IP_СЕРВЕРА:/home/bot/

На сервере:

sudo -u bot -H bash -lc '
cd /home/bot
unzip telegram-vacation-bot.zip -d app
cd app
ls -la
'

Скопируйте и отредактируйте .env:

sudo -u bot -H bash -lc '
cd /home/bot/app
cp .env.example .env
chmod 600 .env
nano .env
'

3) Виртуальное окружение и зависимости

sudo -u bot -H bash -lc '
cd /home/bot/app
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip

# requirements уже закрепляет PTB 20.0 с extras job-queue
pip install -r requirements.txt
'

4) Пробный запуск из консоли

Не меняйте закреплённые версии выборочно: PTB 20.0 использует APScheduler 3.9, которому нужен pkg_resources. В setuptools 82 этот модуль удалён; requirements сохраняет проверенную совместимую версию 81. После установки проверьте python -m unittest discover -s tests -v: тест сборки приложения проверяет наличие JobQueue без сети.

sudo -u bot -H bash -lc '
cd /home/bot/app
source venv/bin/activate
set -a
. ./.env
set +a
python config.py
python telegram_vacation_bot.py
'

Если бот стартовал (в логе что-то вроде Application started), остановите Ctrl+C.

Автозапуск через systemd (бот всегда онлайн)

Создайте юнит:

sudo tee /etc/systemd/system/telegram-vacation-bot.service > /dev/null <<'EOF'
[Unit]
Description=Telegram Vacation Bot
After=network-online.target
Wants=network-online.target

[Service]
User=bot
WorkingDirectory=/home/bot/app
Environment="PYTHONUNBUFFERED=1"
EnvironmentFile=/home/bot/app/.env
ExecStart=/home/bot/app/venv/bin/python /home/bot/app/telegram_vacation_bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Запустить и включить автозапуск:

sudo systemctl daemon-reload
sudo systemctl enable --now telegram-vacation-bot
sudo systemctl status telegram-vacation-bot

Открыть логи:

journalctl -u telegram-vacation-bot -f -n 200

Если видите предупреждение вида JobQueue не инициализирован, убедитесь, что установлен пакет
python-telegram-bot[job-queue] и перезапустите сервис:

sudo systemctl restart telegram-vacation-bot

Первичная настройка бота

1. Если свой ID неизвестен, запустите своего бота с пустым VACATION_BOOTSTRAP_ADMIN_IDS и отправьте /whoami в личном чате. Остановите процесс, впишите полученный свой числовой ID в .env и запустите заново. Пустой список не даёт никому создать команду.
2. Настроенный владелец выполняет /start и вводит новое название. Он получает OWNER; присвоить существующую команду по названию нельзя.
3. Создайте типы отпусков, лимиты и политику пересечений.
4. Сотрудник сначала открывает бота и передаёт свой ID из /whoami администратору по проверенному каналу. Администратор выполняет /setrole TELEGRAM_ID ROLE или выбирает «Добавить сотрудника», вводит числовой ID и назначает роль. Сотрудник повторяет /start.
5. Проверьте тестовую заявку: сотрудник видит свою команду, её администратор принимает решение, а посторонний не получает список и не может обработать заявку. Бот работает только в личных чатах.

Как обновлять Telegram-бота с коротким перезапуском

Обновление существующей установки: сначала остановите единственный процесс и сделайте снимок SQLite, как показано ниже. Отдельно сохраните .env вне папки приложения с правами 600. Новый ZIP распакуйте в отдельный пустой каталог, прочитайте README и сравните файлы:

sudo systemctl stop telegram-vacation-bot
sudo -u bot -H bash -lc '
mkdir -p /home/bot/release-2026-10-31
unzip /home/bot/telegram-vacation-bot.zip -d /home/bot/release-2026-10-31
ls -la /home/bot/release-2026-10-31
'

После бэкапа и проверки замените только исходники telegram_vacation_bot.py, config.py и requirements.txt, затем установите закреплённые зависимости в прежний venv. Рабочие .env и БД не перезаписывайте. В старой версии они могли лежать внутри вложенной папки telegram-vacation-bot/: сверьте фактический путь с unit. Проверьте старые роли и team_id до возобновления доступа, затем запустите сервис. Автоматической миграции старой Default Team в новые команды здесь нет.

Бэкапы базы (SQLite)

База по умолчанию: /home/bot/app/vacation_bot.db (или путь из .env).

Снимок через SQLite .backup, а не копирование открытого файла: так учитываются изменения в WAL. Ниже указан путь по умолчанию; если в .env другой путь, замените его в обеих командах. После копирования проверьте восстановление на отдельной базе и ограничьте доступ к бэкапам.

sudo -u bot -H bash -lc '
mkdir -p /home/bot/backups
sqlite3 -readonly /home/bot/app/vacation_bot.db ".timeout 5000" ".backup /home/bot/backups/vacation_bot.db.$(date +%F_%H-%M-%S).bak"
ls -lh /home/bot/backups/
'

Автобэкап через cron (ежедневно в 02:15 по часовому поясу сервера; сначала создайте каталог /home/bot/backups от пользователя bot):

sudo -u bot crontab -e
# добавьте строку:
15 2 * * * /usr/bin/sqlite3 -readonly /home/bot/app/vacation_bot.db ".timeout 5000" ".backup /home/bot/backups/vacation_bot.db.$(date +\%F_\%H-\%M-\%S).bak"

Безопасность и надёжность

• Храните токен бота только в .env и не коммитьте его в публичные репозитории.
• Права на каталог:

sudo chown -R bot:bot /home/bot
chmod 600 /home/bot/app/.env

UFW/Firewall: вход по SSH, остальное - по необходимости:

sudo apt -y install ufw
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Старая установка: перед обновлением проверьте Telegram ID, роли и команды на копии базы. Исправление не удаляет ранее выданные злоумышленникам роли автоматически. Старые username-плейсхолдеры не получают аккаунт по совпадению имени; данные Default Team требуют отдельной осознанной миграции.

Частые ошибки и решения

1) JobQueue не инициализирован
Не установлены extras. Решение:

source /home/bot/app/venv/bin/activate
pip install -r /home/bot/app/requirements.txt
sudo systemctl restart telegram-vacation-bot

2) Message is not modified в логах
Это warning от Telegram, когда вы пытаетесь «редактировать» сообщение тем же текстом/клавиатурой. В боте уже предусмотрено безопасное подавление этой ошибки - можно игнорировать.

3) Forbidden: bot was blocked by the user
Пользователь заблокировал бота - нормальная ситуация при рассылке уведомлений. Это не авария.

4) database is locked
Если возникнет под нагрузкой:
- убедитесь, что бота не запускают дважды;
- проверьте диск и права;
- проверьте длительность транзакций и закрытие соединений. Переход на PostgreSQL потребует отдельной доработки и проверки кода.

5) Не запускается сервис после обновления
Проверьте права и пути:

sudo -u bot -H bash -lc 'ls -la /home/bot/app'
sudo systemctl status telegram-vacation-bot
journalctl -u telegram-vacation-bot -n 200 --no-pager

Почему именно этот бот

• Простая архитектура: Python + python-telegram-bot + aiosqlite.
• Гибкая админка: всё конфигурируется в чате - без отдельных кабинетов.
• Сильные проверки: запреты дат, пересечения, лимиты в год/за раз.
• Экспорт и аналитика: CSV для бухгалтерии; сводки по месяцам и ролям.
• Скорость внедрения: один файл сервиса в systemd, и он уже «живёт» на сервере.

FAQ

Как перенести бота на другой сервер?
Остановите единственный процесс, сделайте снимок SQLite через .backup и сохраните .env с ограниченным доступом. Перенесите исходники и снимок, пересоздайте venv из requirements.txt, проверьте пути и только затем запустите сервис на новом сервере.

Можно ли развернуть на Docker?
Да, но готового Dockerfile в ZIP нет. Передайте настройки контейнеру через env_file или environment; простое монтирование .env не экспортирует переменные. Базу храните в отдельном volume. Эта версия проверена офлайн, не как готовый Docker-образ.

Как сменить токен?
Замените TELEGRAM_TOKEN в .env и перезапустите telegram-vacation-bot. В ручной консоли заново экспортируйте .env. Токен не нужно менять в Python-коде.

Кто может создать команду и выдать роль администратора?
Новую команду создаёт только числовой Telegram ID из VACATION_BOOTSTRAP_ADMIN_IDS; её создатель получает OWNER. В существующей команде роли назначает её действующий администратор. Самостоятельно войти по названию и выбрать себе CEO нельзя.

Как добавить сотрудника без доверия к username?
Сотрудник открывает бота и передаёт свой числовой ID из /whoami администратору по проверенному каналу. Администратор использует /setrole TELEGRAM_ID ROLE или кнопку добавления с тем же ID. Совпадение или смена username членство не создаёт.

Что мы имеем

А имеем мы пошаговую схему: от чистого сервера до настроенного образца Telegram-бота для отпусков с админкой, политиками пересечений, напоминаниями и экспортом. Такой подход снимает хаос в календарях и табличках, ускоряет согласование и делает процесс предсказуемым.

Скачайте архив ниже, разверните на своём сервере по инструкции.

Ну а кому лень заниматься установкой и настройкой, вы можете просто заюзать уже установленного бота для планирования отпусков и выходных дней в компании: https://t.me/LLweekend_bot