1Бот-сторож: спам і збої

Бот, у якого багато користувачів, рано чи пізно зустрічає двох неприємних гостей. Перший — спам: хтось засипає бота сотнею повідомлень за хвилину (з цікавості, з нудьги або щоб зламати). Другий — збій: служба впала, сайт не відкривається, бот завис, а ти дізнаєшся про це від однокласників через три дні. Сьогодні в тебе з’являться обидва захисти.

До кінця заняття в тебе буде:

• файл guard.py («охоронець» — він стереже бота від спаму): якщо хтось пише надто часто, повторює те саме чи вживає заборонені слова, бот спершу чемно просить зачекати, а потім на 10 хвилин замовкає. Покарання записується в таблицю blocked у базі;
• власника охоронець не блокує ніколи, а людину блокує за номером чату, а не за іменем;
• команди власника /status (скільки працює бот, скільки заблоковано, останні помилки), /blocked і /unblock;
• окрема програма watch.py («сторож» — він стереже сайт і самого бота від збоїв) і таймер, які щохвилини перевіряють сайт та самого бота й пишуть тобі в Telegram, коли щось упало і коли знову запрацювало, — але не частіше ніж один раз на подію;
• власна аварія: ти сам зупиниш службу й побачиш сповіщення.

Показати можна буде: імітацію спаму, де бот замовкає (python3 spam.py), повідомлення «🔴 … впало» і «🟢 … знову працює» і відповідь на /status.

Якщо в тебе немає TelegramНічого не втрачено. Спам імітує програма spam.py, команди власника перевіряє try_bot.py --id …, а сповіщення сторожа, якщо немає куди писати, потрапляють у журнал ~/logs/club-watch.log з позначкою [без Telegram]. Живе повідомлення в Telegram лише підтверджує викладач.

Спам — це небажані повідомлення, які надсилають масово й швидко. Для бота це три різні ситуації, і кожну можна впізнати за цифрами:

• надто часто — понад 5 повідомлень за хвилину від однієї людини. Людина, яка друкує руками, стільки не пише; а програма — легко;
• одне й те саме — три однакові повідомлення підряд;
• заборонені слова — реклама «казино», «заробіток без вкладень» тощо. Список слів — просто кортеж BAD_WORDS у guard.py (кортеж — це список, який не змінюють під час роботи), і його можна доповнювати.

Є тонкість: охоронець не має ображати звичайних людей. Друг, який розсердився й надіслав шість повідомлень, — не спамер. Тому покарання йде сходинками: перше порушення — лише чемне «зачекай хвилину», і це повідомлення бот не обробляє; наступне порушення — мовчання без жодної відповіді (щоб спамер не отримував «нагороди» у вигляді відповідей); третє порушення за хвилину — тимчасове мовчання на 10 хвилин. Не назавжди: помилитися може кожен, а вічний бан без права на помилку — несправедливий.

Чому «ліміт на хвилину», а не «ліміт на весь день»? Бо цікавить швидкість. Стільки ж повідомлень за день — нормальна розмова, за хвилину — атака.

Кнопки під повідомленнями бота (заняття 10) теж можна «засипати» натисканнями, і кожне натискання — це запис у базу. Тому охоронець рахує й їх, але щедріше: до 20 натискань за хвилину (CLICK_LIMIT), бо кнопки — звичайна частина розмови.

Це спрощена схемаСправжні захисти складніші. Наш охоронець, наприклад, вважає повтором навіть п’ять разів «ок» поспіль. Для навчання цього досить: головне — зрозуміти ідею «лічильник у пам’яті плюс покарання в базі».

Охоронцю потрібно пам’ятати двоє різних речей, і зберігаються вони по-різному.

Лічильники повідомлень («цей chat_id писав о 14:01:05, 14:01:06, 14:01:06…») потрібні лише на хвилину-дві. Їх тримаємо в оперативній пам’яті програми — у словнику _recent: для кожного chat_id — черга останніх повідомлень з часом (тип deque, «двостороння черга»: старе легко викидати спереду, нове додавати ззаду). Якщо бот перезапуститься, лічильники обнуляться — і це нормально.

Покарання («замовкни до 14:11») має жити довше й не зникати від перезапуску бота. Інакше спамеру достатньо дочекатися, поки ти оновиш бота, — і він знову на волі. Тому мовчання записуємо в базу, в таблицю blocked:

CREATE TABLE IF NOT EXISTS blocked(
  chat_id INTEGER PRIMARY KEY,   -- кого мовчимо (один рядок на людину)
  until   INTEGER NOT NULL,      -- до якої миті, у секундах
  reason  TEXT NOT NULL,         -- чому: fast, repeat чи word
  created TEXT NOT NULL          -- коли записали
)

Рядок додається командою INSERT OR REPLACE («додай, а якщо такий chat_id вже є — заміни»). Коли строк минув, охоронець сам видаляє рядок (DELETE). Час записуємо числом — «секунди від 1 січня 1970» (так робить time.time()), бо числа легко порівнювати: until > clock() означає «ще мовчимо».

І остання деталь: охоронець бере час не прямо з time.time(), а через clock — спершу це просто time.time під іншим іменем. Це маленька хитрість для перевірок. Щоб довести, що блокування закінчується через 10 хвилин, не треба чекати 10 хвилин: перевірка підміняє clock на «годинник», який можна перемотати. У програмуванні так роблять часто, і ти бачитимеш це в тестах на занятті 12.

Блокувати можна лише за chat_id — тим самим числом, яким ми визначали власника на занятті 07. Ім’я та нік змінює собі кожен за секунду. Якби ми блокували за іменем «Спамер», то по-перше, спамер змінив би ім’я й продовжив; по-друге, тисячі цілком чемних людей, що теж звуться «Саша», потрапили б під удар. Номер чату видає Telegram, і підробити його не вдасться.

Власника не блокуємо ніколи. Це перший рядок у guard.check: якщо chat_id збігається з номером власника (перший у ADMIN_IDS) — пропускаємо без розмов. Уяви, що ти тестуєш бота й надсилаєш двадцять команд поспіль, а власний захист заблокував тебе самого. Саме тому для власника ще й існують /unblock і /blocked: якщо охоронець помилково заблокував гарну людину, ти її розблокуєш однією командою.

Досі ми дізнавалися про поломки так: бот не відповідає — отже, щось не так. Це найгірший спосіб: ти дізнаєшся останнім. Краще, щоб про збій тобі сказала програма-сторож. Для цього їй потрібно вміти перевіряти, чи все гаразд. Такі перевірки бувають двох видів.

1. Постукати в сайт. Відкрити сторінку сайту й подивитися, що повернув сервер. Відповідь 200 означає «усе гаразд» (ти вже бачив коди відповідей на занятті 06). Сторож робить HTTP-запит до http://127.0.0.1/u/<логін>/. Ця сторінка — звичайні файли з ~/www, їх роздає nginx (програма, що приймає запити з інтернету), і окремої програми для цього не потрібно. Якщо сторінки немає, nginx віддає код 403 або 404. Запам’ятай, він знадобиться в кроках 8 і 11.

Бот не відкриває порту, тому «постукати» в нього не вийде. Його перевіряють по-іншому (друга перевірка).

2. Перевірити, чи не завис бот. Тут команда systemctl --user is-active club-bot не допоможе: служба може бути «активна», а бот усередині застряг — наприклад, назавжди чекає відповіді від Telegram. Пам’ятаєш last_poll у файлі ~/data/bot_state.json? Бот записує туди час кожної відповіді, яку отримав від Telegram, тож якщо цей час давніший за дві хвилини, бот не працює, хоч би що показував is-active. Таку перевірку називають перевіркою «живості».

Висновок, який варто запам’ятати: стежити треба за результатом (чи відповідає сайт, чи рухається бот), а не за тим, що «процес існує».

Чому сторожа не можна вбудувати в самого бота? Бо коли бот упав, він уже нічого не скаже: мертвий сторож нікого не попередить. Тому watch.py — окрема програма, яку будить таймер systemd щохвилини (так само, як morning.py на занятті 09). Бот може лежати, а сторож усе одно прокинеться, подивиться і напише.

Але сторож, який пише щохвилини «сайт лежить, сайт лежить, сайт лежить…», за годину набридне, і ти його вимкнеш. Тоді він марний. Тому дві умови:

• Один раз на подію. Перше повідомлення — «🔴 впало». Далі тиша, поки не зміниться стан. Потім одне повідомлення — «🟢 знову працює». Щоб пам’ятати, що вже повідомлено, сторож (він щоразу запускається наново й «забуває» все) записує стан у файл ~/data/watch_state.json: для кожної перевірки — скільки разів поспіль вона провалилася (fails) і чи вже сповіщено (alerted). Ідея знайома: стан живе у файлі, а не в пам’яті програми (заняття 09, поле last).
• Не панікувати через одну невдачу. Службу можна перезапустити — і кілька секунд вона не відповідає. Якщо сторож писав би про кожну секундну мовчанку, він кричав би даремно (хибна тривога). Тому сторож пише лише після FAILS = 2 невдач поспіль — приблизно через дві хвилини. Саме тому kill -9 з заняття 08 (служба впала, але сама піднялася за пару секунд) жодного сповіщення не викличе: це і є правильна поведінка.

Є ще одна дрібниця: повідомлення позначається «надісланим» лише тоді, коли Telegram справді його прийняв. Якщо інтернет зник, сторож спробує ще раз за хвилину.

Школа вимикає службу вночіТвоя служба працює лише в години занять і ввечері. Поза цим часом школа її зупиняє, і сторож напише «🔴 впало», а потім «🟢 знову працює», коли службу ввімкнуть. Це не збій, а розклад, але сторож цього не знає й сповістить про «аварію». Щоб не отримувати повідомлень уночі, після заняття можна зупинити таймер: systemctl --user stop club-watch.timer. Після перезавантаження сервера таймер знову запуститься сам.

Коли ти за кермом, тобі потрібна не вся механіка автомобіля, а кілька приладів на панелі: швидкість, пальне, лампочки несправностей. Для бота такою «панеллю» буде команда /status — вона працює лише для власника:

📊 Стан бота
Бот працює: 2 год 14 хв
Останнє опитування Telegram: 12 с тому
Заблоковано зараз: 1
Останні помилки у журналі:
• 2026-10-25T14:03:11 помилка обробки: KeyError('name')

«Бот працює: 2 год 14 хв» — це аптайм (від англ. up — «вгору», «працює»): скільки часу програма працює без перезапуску. Якщо вчора було 20 годин, а сьогодні 3 хвилини — бот перезапускався, і варто з’ясувати чому. Останні помилки /status бере з журналу ~/logs/club-bot.log: охоронець переглядає кінець файлу й вибирає рядки зі словами «помилка», «Traceback», «не вдалося». Власний журнал, який ти ще з заняття 02 читаєш руками, тепер приходить у Telegram сам.

Якщо ти запускаєш /status через try_bot.py, аптайм буде «0 с»: програма try_bot.py щойно стартувала. Справжній аптайм видно лише у відповіді живого бота в Telegram.

Кожне питання оцінюється відразу в браузері — це лишається так само. Ця кнопка лише надсилає підсумок учителю, щоб відповіді не зникли разом із закритою вкладкою.

Список критеріїв і що саме вони означають — у таблиці вище, «Що перевіряє автоматика». Тут — та сама перевірка, але прямо зараз, без очікування на найближчий прохід за розкладом.

1. Подивись, що сторож записав за ніч. Завтра вранці виконай tail -n 20 ~/logs/club-watch.log і cat ~/data/watch_state.json. Школа вимикає служби груп уночі, тож, якщо таймер не зупиняли, там буде «🔴» і «🟢». Запиши в README, о котрій годині це сталося і скільки часу минуло між ними. Не хочеш нічних повідомлень — systemctl --user stop club-watch.timer.
2. Четверта перевірка. Додай у watch.py перевірку вільного місця на диску: новий пункт у функції look(). Угорі файлу, до інших import, додай import shutil, а look() зроби такою (два перші пункти вже є, не забудь кому після ("bot", …)):

   def look():
       free = shutil.disk_usage(str(HOME)).free // 10**9      # вільно, ГБ
       return [("site", "Сайт", *probe_url(SITE)),
               ("bot", "Бот", *probe_bot()),
               ("disk", "Диск", free >= 1, f"вільно {free} ГБ")]

   Перевір: python3 watch.py --dry має показати рядок «Диск». Більше нічого міняти не треба: подумай, чому run() сам підхопить нову перевірку.
3. Придумай обхід — і не користуйся ним. Як би спамер міг обійти твого охоронця (підказка: що, якщо писати раз на 13 секунд і по-різному?). Запиши ідею в README одним реченням і поясни, чому охоронець усе одно потрібен.
4. Підготуйся пояснити. Чому блокують за chat_id, а не за іменем; навіщо блокування записано в таблицю, а не лише в пам’ять; чому сторож пише один раз на подію; чому служба може бути active, а бот — ні. На початку заняття 12 викладач спитає щось одне з цього.
5. Збережи. git add -A, git commit -m "Заняття 11: домашня робота", git push origin main і git push github main.

32Бот не стартує або не відповідає після вставок

Подивись журнал: tail -n 30 ~/logs/club-bot.log. Найчастіше причина в одному з трьох:

• ModuleNotFoundError: No module named 'guard' — немає файлу ~/app/guard.py (крок 2);
• SyntaxError чи IndentationError після вставок — зсунуто відступ або забуто двокрапку; порівняй: diff ~/app/bot.py /opt/club/kurs/11/bot.py;
• бот працює, але /status відповідає «Не знаю такої команди» — вставка 3 стоїть після загального if text.startswith("/"); її треба перед ним;
• перевірка L11.1 пише, що кнопки не під охороною, — вставка 4 не зроблена або стоїть поза гілкою callback_query.

33L11.1: спамера не зупинили

• python3 spam.py показує лише ✔ — у handle_update немає виклику guard.check(...) (вставка 2) або він стоїть після обробки команд. Охоронець має бути першим;
• бот мовчить, але перевірка пише «немає запису в blocked» — не змінюй функцію ban() у guard.py; оригінал: /opt/club/kurs/11/guard.py;
• заборонене слово проходить — перевір, що BAD_WORDS — це кортеж рядків з комами, не один великий рядок, і що слово написано малими літерами.

34L11.2: звичайну людину заблоковано

Найчастіше причина — змінений LIMIT. Якщо ти поставив 1–2, людина, що пише раз на 20 секунд, швидко потрапить під обмеження; поверни LIMIT = 5, WINDOW = 60, REPEAT = 3. Друга причина — блокування за іменем замість chat_id: у guard.py ключем скрізь має бути chat_id.

35L11.3: власника заблоковано

Перший рядок у guard.check має пропускати власника: if chat_id is None or (owner and str(chat_id) == str(owner)): return True, None. У bot.py третім аргументом має йти OWNER: guard.check(chat_id, text, OWNER). Якщо на кроці 1 було 0 замість 1 — у .env немає OWNER_CHAT_ID; власник тоді не відомий, і охоронець блокує всіх.

36L11.4: блокування не закінчується

• У banned_until() порівнюй until з clock(), а не з time.time(): перевірка підміняє саме clock;
• рядок із таблиці має видалятися, коли строк вийшов (DELETE FROM blocked …);
• BAN_SEC менше 60 — перевірка цього не пропустить; за завданням — 600.

37L11.5: /status

• відповідь без «Заблоковано зараз: N» — не змінюй функцію status() у guard.py або поверни оригінал;
• помилок немає у відповіді — рядок у журналі має містити слово «помилка», «Traceback» або «не вдалося»; журнал — ~/logs/club-bot.log (його можна підмінити змінною CLUB_BOT_LOG);
• чужому номеру показує стан — перевірка власника стоїть після guard.command(text), а має бути перед ним.

38L11.6 або L11.7: сторож

• немає ~/app/watch.py — cp /opt/club/kurs/11/watch.py ~/app/;
• у виводі --dry немає слів «Сайт», «Бот» або знаків ✅ ❌ — ти змінив main(); поверни оригінал;
• --dry створює watch_state.json — у гілці --dry не має бути виклику run() чи save();
• сторож пише більше одного разу — не прибирай прапорець alerted і умову and not st["alerted"] у run();
• сторож пише вже після першої невдачі — FAILS має бути не менше 2, інакше будь-який перезапуск служби поверне хибну тривогу;
• не пише про відновлення — перевір, що після «🟢» прапорець alerted знову стає False.

39L11.8: таймер сторожа

• Unit club-watch.timer not found — файли не скопійовано в ~/.config/systemd/user/ або забуто daemon-reload;
• немає timers.target.wants/club-watch.timer — не виконано systemctl --user enable --now club-watch.timer. Зупинка таймера (stop) перевірку не ламає, а вимкнення (disable) — ламає;
• у club-watch.timer має бути рядок OnCalendar=minutely (або OnUnitActiveSec=).