Блог
Публикации о процессе разработки, решённых задачах и изученных технологиях
От хаоса к объектам: как переделали API для трендов
# Регистрируем API эндпоинт: как архитектура трендов выросла из хаоса документации Мне нужно было разобраться с проектом **trend-analysis** — системой для отслеживания трендов из GitHub и Hacker News. Проект жил в состоянии «почти готово», но когда я начал читать логи и документацию, выяснилось: база данных хранит обычные статьи, а нужно хранить **объекты** — сущности вроде React.js или ChatGPT, за которыми стоит десятки упоминаний. Первым делом я столкнулся с классической проблемой: эксперты предложили одну методологию определения трендов, а Глеб Куликов (архитектор системы) независимо пришёл к другой — и они совпадали на **95%**. Но Куликов заметил то, что упустили эксперты: текущая архитектура создаёт дубликаты. Одна статья о React — один тренд, вторая статья о React — второй тренд. Это как хранить 10 постов о Путине вместо одной записи о самом Путине в каталоге. Я решил реализовать **гибридную модель**: добавить слой entity extraction, чтобы система извлекала объекты из статей. Значит, нужны новые таблицы в БД (`objects`, `item_objects`, `object_signals`) и, самое важное, новые API эндпоинты для управления этими объектами. **Вот тут начинается интересная часть.** API эндпоинты я размещал в `api/auth/routes.py` — стандартное место в проекте. Но admin-endpoints для работы с объектами требовали отдельного маршрутизатора. Я создал новый файл с роутером, настроил префикс `/admin/eval`, и теперь нужно было **зарегистрировать его в main.py**. На фронтенде добавил страницу администратора для управления объектами, обновил боковую панель навигации, реализовал API-клиент на TypeScript, используя существующие паттерны из проекта. По сути, это была целая цепочка: api → typescript-client → UI components → i18n ключи. **Занимательный факт о веб-архитектуре**: корневая ошибка новичков — писать эндпоинты, не думая о регистрации роутеров. Flask и FastAPI не магическим образом находят ваши функции. Если вы создали красивый эндпоинт в отдельном файле, но забыли добавить `app.include_router()` в main.py — для клиента это будет 404 Not Found. Поэтому регистрация в точке входа приложения — это не «формальность», это **фундамент**. В итоге система сегодня: - Не ломает текущую функциональность (backward compatible) - Может извлекать объекты из потока статей - Отслеживает свойства объектов: количество упоминаний, интенсивность сентимента, иерархию категорий - Готова к полной дедупликации в Q3–Q4 Документировал всё в `KULIKOVS-METHODOLOGY-ANALYSIS.md` — отчёт на 5 фаз имплементации. Теперь архитектура стройная, и следующие разработчики не будут гадать, почему в системе 10 записей о React вместо одной. 😄 Почему Ansible расстался с разработчиком? Слишком много зависимостей в отношениях.
Как машина научилась видеть тренды раньше рынка
# Охота на тренды: как мы учим машину видеть будущее Вчера сидел в офисе и слушал, как бизнес снова волнуется: доходы падают, рынок неопределён, никто не знает, на что ставить. А потом понял — проблема не в рынке, а в том, что мы **слепые**. Мы видим только то, что уже произошло, а не то, что начинает происходить. Вот тогда и родилась задача: построить систему, которая ловит тренды до того, как они станут очевидными. ## С чего всё начиналось Сначала я попытался дать определение: тренд — это когда что-то новое становится популярным, потому что это действительно меняет жизнь людей. Написал, прочитал, понял, что это полная туфта. Слишком размыто, слишком философично. На собеседовании такое не пройдёт. Три дня размышлений — и вдруг щёлкнуло. **Объект.** Начнём с объекта. React.js, алюминиевые вилки, нейросети, биткоин — неважно что. Каждый объект существует в каком-то количестве экземпляров. И когда это количество **резко меняется** — вот это и есть тренд. Восходящий или нисходящий, но именно это. Дальше логика развернулась сама: объекты объединяются в классы. React.js — это объект из класса "JavaScript-фреймворки", который входит в категорию "современные фронтенд-инструменты". И здесь началось самое интересное. ## Архитектура, которая растёт сама Ключевой инсайт пришёл неожиданно: объект может **протянуть за собой весь класс**. Например, если взлетает спрос на вилки в целом, то растут и алюминиевые, и пластиковые одновременно. Но это не просто рост — это свойства объекта, которые нужно отслеживать отдельно. Я понял, что база должна быть построена не вокруг трендов, а вокруг **объектов**. Каждый объект хранит: - Количество экземпляров (конкретное число или статистику) - Скорость изменения этого количества - *Эмоциональную напряженность* вокруг него (обсуждения в сети, упоминания, дискуссии) - Иерархию: класс → категория → суперкатегория Последний пункт казался странным на первый взгляд. Но потом я понял: это нужно, чтобы поймать **масштабируемость тренда**. Если тренд на React 19 завтра умрёт, выйдет React 20 — но категория "JavaScript-фреймворки" будет актуальна годами. ## Откуда берём данные? Здесь я поймал себя на ошибке: слишком сужал поиск. Вместо "React 19 новые фичи" нужно смотреть на "эволюция современных фронтенд-фреймворков". Первое привязано к версии, второе охватывает реальный тренд целиком. То же с трендом на нейросети: не "ChatGPT выпустил новую версию", а "AI-ассистенты в работе разработчика" — это охватывает ChatGPT, GitHub Copilot, Claude и сюда же войдут новые инструменты. Система должна **автоматически выделять объекты** из обсуждений, присваивать им свойства и отслеживать скорость изменения. Нужен парсер новостей, форумов, GitHub-трендов, Stack Overflow. И математический движок, который из этого шума выделит сигнал. ## Что дальше Прототип уже в работе. Первая версия ловит объекты из текстов, классифицирует их, строит иерархию. Потом будет предикция: "это может стать трендом в Q2". И финал — рекомендации: "вам стоит обратить внимание на эти три объекта". Учимся мы методом проб и ошибок, как всегда. Но уже ясно: когда видишь тренд на стадии зарождения, а не на пике волны — это совсем другое ощущение. 😄 Jest: решение проблемы, о существовании которой ты не знал, способом, который не понимаешь.
Когда агент смотрит в зеркало: самоанализ в хаосе
# Как мы научили агента следить за собой: история про самоотражение в проекте Voice Agent Представь ситуацию: у тебя есть сложный проект **Voice Agent** с многоуровневой архитектурой, где крутятся несколько агентов одновременно, каждый выполняет свою роль. Параллельно запускаются задачи в Bash, подзапрашиваются модели Opus и Haiku, работает асинхронное стриминг через SSE. И вот вопрос — как убедиться, что эта машина работает правильно и не застревает в своих же ошибках? Именно это и стояло перед нами. Обычного логирования было недостаточно. Нужна была **система самоотражения** — механизм, при котором агент сам анализирует свою работу, выявляет прорехи и предлагает улучшения. Первым делом мы изучили то, что уже было в проекте: правила оркестрации (главный поток на Opus для Bash-команд, подагенты для кода), протокол обработки ошибок (обязательное чтение ERROR_JOURNAL.md перед любым исправлением), требования к контексту субагентов (ответы должны быть краткими, чтобы не взорвать окно контекста). На бумаге это выглядело впечатляюще, но было ясно — нет механизма проверки, что все эти требования действительно соблюдаются на практике. Неожиданно выяснилось кое-что интересное: генерировалось 55 внутренних инсайтов самоотражения, а реальных взаимодействий с пользователем было нулевое. Получилась замкнутая система — агент размышляет о своей работе, но это размышление не валидируется реальными задачами. Это как писать код в пустоте, без тестов. Поэтому мы переделали подход. Вместо постоянного внутреннего монолога мы встроили **инструментированное отслеживание**: во время реальной работы агент теперь собирает метрики — сколько параллельных Task-вызовов в одном сообщении, правильно ли выбирается модель по ролям, соблюдается ли лимит в 4 параллельных задачи. И самое важное — проверяет, прочитан ли ERROR_JOURNAL перед попыткой исправления бага. Интересный момент про самые сложные проекты: они часто требуют не столько добавления новых функций, сколько добавления способов *видеть* свою работу. Когда ты выводишь на поверхность то, что творится внутри системы, половина проблем решается сама собой. Разработчик видит, что тормозит, и может целенаправленно это исправлять. В итоге мы получили не просто логирование, а **систему обратной связи**: инсайты генерируются только для найденных проблем (приоритет 3-5), и каждый инсайт содержит конкретное действие для следующей сессии. На каждый шаг — метрика для проверки. На каждую архитектурную гарантию — точка наблюдения. Дальше план простой: собирать реальные данные, анализировать их через неделю и смотреть, где теория разошлась с практикой. Потому что самый опасный разработчик — это тот, кто уверен, что всё работает правильно, но не проверял это. 😄 *Самоотражение в коде: когда агент начинает размышлять о своих размышлениях, это либо философия, либо бесконечный цикл.*
Voice-Agent: как монорепо не рухнул под собственным весом
# Как Claude Code спас voice-agent от архитектурного хаоса Проект **voice-agent** оказался передо мной как незаконченный пазл: монорепозиторий с Python-бэкендом для обработки аудио и Next.js-фронтендом для интерфейса. Разработчик уже наметил архитектуру в документах, но требовалось реализовать суть проекта — связать асинхронную обработку речи, WebSocket-коммуникацию и сложную логику распознавания в один работающий механизм. Первая сложность: необходимо было писать и отлаживать код одновременно на трёх языках, не запутавшись в структуре монорепозитория. Задача началась с картографирования. Вместо привычного «давайте быстренько добавим функцию» я потратил время на изучение документации в `docs/tma/` — там лежали все архитектурные решения, объясняющие, почему выбраны именно эти подходы. Эта работа оказалась ключевой: знание причин проектных решений спасло меня от десятков потенциальных ошибок позже. Первая реальная задача была про потоковую обработку аудио в реальном времени. Стоял выбор: использовать простой опрос сокетов или event-driven архитектуру? Решение пришло с использованием асинхронных генераторов Python вместе с aiohttp для non-blocking операций. Звучит абстрактно, но практически это означало, что сервер теперь мог одновременно обрабатывать сотни клиентов без блокировки основного потока. Неожиданный момент случился при рефакторинге обработки текста. Обнаружилось, что синхронная функция создавала скрытую очередь запросов и вызывала каскадные задержки. Переписал на асинхронность — и задержка упала с 200 ms до 50 ms одним движением. Это был классический случай, когда архитектурное решение имеет экспоненциальный эффект на производительность. Вот важный момент, который я бы посоветовал каждому, работающему с Next.js в монорепозитории: Turbopack (встроенный bundler) может некорректно определить корневую директорию проекта и начать искать зависимости не в папке приложения, а в корне репозитория. Это вызывает каскадные ошибки с импортами. Решение банально просто, но его узнают либо опытом, либо от коллеги: нужно явно указать `turbopack.root` в `next.config.ts` и настроить базовый путь в `postcss.config.mjs`. Это элементарно, когда знаешь. За пару сессий разработчик перешёл от «давайте напишем фичу» к «давайте выберем правильный инструмент для каждой задачи». aiosqlite для асинхронного доступа к данным, WebSocket для real-time коммуникации, TypeScript для типобезопасности фронтенда — каждое решение теперь имеет обоснование. Voice-agent получил солидный фундамент, и главное открытие: хороший AI-ассистент — это не замена опыту, а его турбо. Честно? Это как работать с очень внимательным senior-разработчиком, который помнит все паттерны и никогда не пропустит edge case 😄
Монорепозиторий и AI: как Claude стал напарником разработчика
# Когда AI-ассистент встречает монорепозиторий: история голосового агента Представьте: перед вами лежит амбициозный проект **voice-agent** — это монорепозиторий с Python-бэкендом и Next.js-фронтендом, где нужно связать воедино асинхронную обработку аудио, WebSocket-коммуникацию и сложную логику распознавания речи. И вот в этот момент включается Claude — не просто ассистент, а полноценный напарник по коду. ## Задача была жёсткой Когда разработчик впервые открыл Claude Code, проект уже имел чёткую архитектуру в `docs/tma/`, но требовал реализации множества деталей. Нужно было: - Писать и отлаживать код одновременно на Python, JavaScript и TypeScript - Ориентироваться в сложной структуре монорепозитория без «холодного старта» - Не просто добавлять функции, а понимать, *почему* каждое решение работает именно так Первым делом разработчик понял ключевую особенность работы с Claude Code в контексте таких проектов: AI-ассистент может видеть не только ваш текущий файл, но и архитектуру всего проекта. Это даёт огромное преимущество — вы не пишете код в вакууме. ## Развитие: между выбором и экспериментами Когда встал вопрос об обработке потока аудио в реальном времени, разработчик столкнулся с классической дилеммой: использовать опрос сокетов или event-driven архитектуру? Claude предложил использовать асинхронные генераторы Python вместе с aiohttp для non-blocking операций. Звучит сложно, но в реальности это означало, что сервер мог одновременно обрабатывать сотни клиентов без блокировки основного потока. Интересный момент: при рефакторинге компонента обработки текста выяснилось, что простая синхронная функция создавала скрытую очередь запросов. Пришлось переписать логику под асинхронность, и это одномоментно снизило задержку с 200 ms до 50 ms. Такие открытия — именно то, ради чего стоит привлекать опытного помощника. ## Познавательный момент: монорепозитории и их подводные камни Мало кто знает, но классическая ошибка при работе с Next.js в монорепозитории — неправильный поиск корневой директории проекта. Turbopack (встроенный в Next.js бандлер) может начать искать зависимости не в папке приложения, а в корне репозитория, вызывая каскадные ошибки с импортами. Правильное решение — явно указать `turbopack.root` в `next.config.ts` и настроить базовый путь в `postcss.config.mjs`. Это элементарно, но узнают об этом опытом... или благодаря опытному напарнику. ## Итог: что-то большое начинает работать За несколько сессий разработчик не просто писал код — он учился *думать* архитектурно. Claude помог не просто реализовать фичи, но и выбрать правильные инструменты для каждой задачи: aiosqlite для асинхронного доступа к данным, WebSocket для real-time коммуникации, TypeScript для типобезопасности фронтенда. Проект voice-agent теперь имеет солидный фундамент, и самое интересное — это только начало. Впереди оптимизация, масштабирование, новые фичи. Но главное, что разработчик понял: хороший AI-ассистент — это не замена опыту, а его ускоритель. Обычный коллега сказал бы: «Ну ты с AI-ассистентом кодишь?» А ты ответил бы: «Да, но это как работать с очень внимательным senior-разработчиком, который знает все паттерны и никогда не забывает про edge cases». 😄
Привязал бота к Strapi: потоки, синхронизация и локальный маппер
# Как я связал бота и Strapi: история о потоках, тестах и синхронизации Задача стояла такая: bot-social-publisher — мой проект, который вытягивает заметки о разработке и публикует их на сайт borisovai.tech. Раньше каждая заметка была независимой статьёй в Strapi. Но это было скучно. Хотелось превратить разбросанные публикации в **потоки** — контейнеры, где все заметки одного проекта живут вместе, с общим описанием, категориями и тегами. Типа: "Поток разработки my-project: 5 заметок, последние фичи и баг-фиксы". Первым делом открыл backend на Node.js + Strapi. Там уже была база под API, но нужно было достроить. Добавил параметр `thread_external_id` в функцию `publishNote()` — теперь заметка знает, к какому потоку её привязать. Создал новый маршрут `PUT /api/v1/threads/:id` для обновления описания и тегов потока. И ещё важный момент: поток может быть **пустым контейнером** без заметок внутри. Это позволяет создать структуру заранее, прежде чем летят первые публикации. Потом переключился на Python-часть бота. Вот тут уже кипела работа. Добавил таблицу `thread_sync` в SQLite — маппер, который запоминает: "проект X → поток с ID Y". Зачем это нужно? Когда бот публикует вторую заметку по тому же проекту, ему нужно мгновенно знать, какой поток уже создан. Без этого маппинга пришлось бы каждый раз ходить на API и искать нужный поток — медленно и ненадёжно. Создал отдельный модуль **ThreadSync** с методом `ensure_thread()`. Он проверяет локальную БД, и если потока нет — создаёт его через API, кеширует результат. После успешной публикации запускается `update_thread_digest()` — она берёт данные из базы ("3 фичи, 2 баг-фикса"), форматирует на русском и английском и пушит обновление потока обратно в Strapi через PUT. Вся логика живёт теперь в **WebsitePublisher** — инициализирует ThreadSync, вызывает его перед и после публикации. Асинхронно, с `aiosqlite` для неблокирующего доступа к базе. Неожиданно выяснилось вот что: обычно Strapi используют как просто контейнер для контента. А здесь я его заставляю выполнять структурирующую роль. Потоки — это не папочки в интерфейсе, это полноценные сущности API с собственной логикой обновления. Потребовалось хорошее понимание Strapi: разница между `POST` (создание) и `PUT` (обновление), роль `external_id` для связи внешних систем, обработка локализации (ru/en в одном вызове). Закоммитил изменения — Git наругался на CRLF vs Unix, но я коммитнул только три реально изменённых файла: database.py, thread_sync.py, website.py. Результат: 70 тестов проходят, 1 скипнут. Система работает. Теперь когда бот публикует заметку, происходит магия: проверяется локальная БД → если потока нет, создаётся → заметка летит в Strapi с привязкой → тут же обновляется описание потока. Всё это видно на https://borisovai.tech/ru/threads. Зелёные тесты — лучший знак того, что большая архитектурная работа прошла чисто. 😄
Спасаем разработчиков от лабиринта документации
# Как я спасал API документацию от размытых ссылок Проект **trend-analisis** рос, и с ним росла беда: разработчикам нужно было регистрироваться, читать документацию, переходить на API endpoint'ы — и каждый раз они путались в лабиринте вкладок и закладок. Задача была проста и назойлива одновременно: создать быстрый справочник по регистрации с прямыми ссылками на страницы API, чтобы всё было под рукой с первого клика. Звучит просто? Нет, потому что простых задач не бывает, есть только те, что казались простыми в начале 😄 ## В поиске правильной структуры Первым делом я разобрался, как люди вообще читают документацию. Оказалось, никто не хочет цикла: регистрируешься → переходишь в основную документацию → ищешь API методы → потом ещё раз ищешь примеры. Это как ходить пешком туда-обратно на протяжении всего проекта. Решил делать навигационный хаб — одно место, откуда можно прыгнуть в нужную точку документации за один клик. Для этого нужна была чёткая иерархия: какие разделы API важнее, где начинающим рыть не стоит, какие примеры самые полезные на старте. ## Архитектура справочника Я подумал о структуре как о карте города: есть главные улицы (основные API методы), есть боковые (advanced features), есть где-то офис регистрации. Сделал справочник с тремя слоями: 1. **Блок регистрации** — с инструкциями и ссылкой на форму 2. **API методы по категориям** — сгруппированы по типу операций (получение трендов, аналитика, экспорт) 3. **Примеры кода** — непосредственно в справочнике, чтобы не прыгать по вкладкам ## Познавательный момент про документацию Знаете, почему DevTools в браузере показывает сетевые запросы? Потому что разработчик Firebug (предшественник DevTools) Джо Хюбли в 2006 году понял, что если разработчик не видит, что происходит в сети, он вообще ничего не понимает. Документация работает по тому же принципу — разработчик должен *видеть путь от проблемы к решению*, а не искать его вслепую. ## Финальное решение В итоге сделал: - **Динамическое содержание** — справочник парсит структуру API из docstrings и автоматически создаёт якоря - **Sticky навигация** — панель с ссылками висит слева, прокручиваются только примеры - **QR-коды для мобильных** — потому что люди читают документацию на телефоне, даже если не хотят в этом признаваться Разработчики теперь открывают регистрацию, видят справочник, кликают на нужный endpoint — и вот они уже в нужной части документации. Без танцев с бубнами, без пяти вкладок браузера. Главный урок: документацию нужно строить с точки зрения пути, который пройдёт пользователь, а не с точки зрения, как удобнее её разработчику писать. Когда ты думаешь о маршруте, а не о каталоге — всё встаёт на место. Почему разработчик любит регулярные выражения? Потому что без них жизнь слишком скучна 😄
Когда GitLab Runner нашел 5 ошибок TypeScript за 9 секунд
# GitLab Runner сломал сборку: как мы спасали TypeScript проект Понедельник, 10 февраля. В 17:32 на сервере **vmi3037455** запустился очередной CI/CD пайплайн нашего проекта **trend-analisis**. GitLab Runner 18.8.0 уверенно начал свою работу: клонировал репозиторий, переключился на коммит f7646397 в ветке main, установил зависимости. Всё шло как надо, пока... Сначала казалось, что всё в порядке. `npm ci` отработал чисто: 500 пакетов установилось за 9 секунд, уязвимостей не найдено. Команда `npm run build -- --mode production` запустилась, TypeScript компилятор включился. И вот тут — **взрыв**. Пять ошибок TypeScript сломали всю сборку. Сначала я подумал, что это очередное невезение с типизацией React компонентов. Но посмотрев внимательнее на стек ошибок, понял: это не просто синтаксические проблемы. Это был признак того, что в коде **фронтенда рассинхронизировались типы** между компонентом и API. Проблема первая: в файле `src/routes/_dashboard/analyze.$jobId.report.tsx` компонент ожидал свойства **trend_description** и **trend_sources** на объекте AnalysisReport, но они попросту не существовали в типе. Это классический случай, когда один разработчик обновил API контракт, а другой забыл синхронизировать тип на фронтенде. Проблема вторая: импорт `@/hooks/use-latest-analysis` исчез из проекта. Компонент `src/routes/_dashboard/trend.$trendId.tsx` отчаянно его искал, но находил только воздух. Кто-то либо удалил хук, либо переместил его, не обновив импорты. Проблема третья совсем коварная: в роутере используется типизированная навигация (похоже, TanStack Router), и при переходе на страницу `/analyze/$jobId/report` не хватало параметра **search** в типе. Компилятор был совершенно прав — мы пытались пройти валидацию типов с неполными данными. Иронично, что всё это выглядит как обычная рабочая пятница в любом JavaScript проекте. TypeScript здесь одновременно наш спаситель и палач: он не позволит нам развернуть баг в production, но заставляет потратить время на то, чтобы привести типы в порядок. **Интересный факт:** GitLab Runner использует **shallow clone** с глубиной 20 коммитов для экономии трафика — видите параметр `git depth set to 20`. Это означает, что пайплайн работает быстро, но иногда может не найти необходимые коммиты при работе с историей. В данном случае это не помешало, но стоит помнить при отладке. В итоге перед нами встала классическая задача: синхронизировать типы TypeScript, переимпортировать удалённые хуки и обновить навигацию роутера. Сборка не пройдёт, пока всё это не будет в порядке. Это момент, когда TypeScript раскрывает свою суть: быть стеной между плохим кодом и production. Дальше предстояла работа по восстановлению целостности типов и проверка, не сломали ли мы что-нибудь ещё в спешке. Welcome to the JavaScript jungle! 😄
Привидение в истории сообщений: как tool_use без tool_result сломал бота
# Охота за привидением в чате: как `tool_use` без `tool_result` сломал бот Проект AI Agents — это система голосовых агентов с телеграм-интеграцией. Звучит просто, но под капотом там полноценная экосистема: асинхронная обработка сообщений, система памяти пользователей, рефлексия агента, напоминания. И вот однажды бот просто перестал запускаться. Сначала казалось, что это типичная проблема с конфигурацией. Но логи рассказывали более странную историю. API Anthropic выбрасывал ошибку: **"tool_use без соответствующего tool_result"**. Как будто кто-то забыл закрыть скобку, но на уровне сессии. Начал копать. Оказалось, что в `handlers.py` есть критический flow: когда агент вызывает инструмент через `chat_with_tools()`, а во время выполнения происходит исключение — `session.messages` остаётся в "повреждённом" состоянии. На сообщение прилетает `tool_use` блок, но соответствующего `tool_result` никогда не приходит. При следующем запросе эти повреждённые сообщения уходят обратно в API — и всё падает. Это было в трёх местах одновременно: в обработчике нормальных команд (строка 3070), в системе напоминаний (2584) и где-то ещё. Классический паттерн копируй-вставь с одинаковым багом. **Решение оказалось простым, но необходимым**: добавить автоматическую очистку `session.messages` в обработчик исключений. Когда что-то идёт не так во время вызова инструмента, просто очищаем последнее незавершённое сообщение. Вот и вся магия. Пока чинил это, нашёл ещё несколько интересных проблем. Например, система рефлексии агента `AgentReflector` читала из таблицы `episodic_memory`, которая может просто не существовать в базе. Пришлось переписать логику проверки с правильной обработкой исключений SQLite. И тут выяснилась ещё одна история: рефлексия использовала `AsyncAnthropic` напрямую вместо Claude CLI. Это означало, что каждый раз при рефлексии расходовались API credits. Пришлось мигрировать на использование CLI, как это было сделано в `reminder_watchdog_system`. Теперь агент может размышлять о своей работе совершенно бесплатно. Отдельное приключение ждало команду `/insights`. Там была проблема с парсингом markdown в Telegram: символы вроде `_`, `*`, `[`, `]` в тексте размышлений создавали невалидные сущности. Пришлось написать функцию для правильного экранирования спецсимволов перед отправкой в Telegram API. В итоге: бот запустился, логирование стало нормальным, система памяти работает исправно. Главный урок — когда API жалуется на незавершённые блоки, смотри на обработку исключений. Там всегда что-то забыли почистить. 😄 Как отличить разработчика от отладчика? Разработчик пишет код, который работает, отладчик пишет код, который объясняет, почему первый не работает.
Монорепо как зеркало: когда Python и JS живут в одном доме
# Монорепо как зеркало: Python + Next.js в одном проекте **Завязка** Представьте ситуацию: вы разработчик и в ваших руках проект *voice-agent* — голосовой помощник на основе Claude, построенный как монорепо. С одной стороны Python-backend (FastAPI, aiogram для Telegram), с другой — Next.js фронтенд (React 19, TypeScript 5.7) для Telegram Mini App. Звучит здорово, но вот в чём подвох: когда в одном репозитории живут две экосистемы с разными правилами игры, управлять ими становится искусством. **Развитие** Первой проблемой, которая выпрыгнула из неоткуда, была **забывчивость переменных окружения**. В Python проект использует `pydantic-settings` для конфигурации, но выяснилось, что эта библиотека не экспортирует значения автоматически в `os.environ`. Результат? Модульный код, читавший переменные прямо из окружения, падал с загадочными ошибками. Пришлось документировать эту ловушку в ERROR_JOURNAL.md — живом архиве подводных камней проекта, где уже скопилось десять таких «моментов истины». Далее встал вопрос архитектуры. Backend требовал **координатора** — центрального паттерна, который бы оркестрировал взаимодействие между агентами и фронтенд-запросами. На бумаге это выглядело идеально, но в коде его не было. Это создавало технический долг, который блокировал Phase 2 разработки. Пришлось вводить **phase-gate валидацию** — автоматическую проверку, которая гарантирует, что прежде чем переходить к следующей фазе, все артефакты предыдущей действительно на месте. В процессе появилась и проблема с **миграциями базы данных**. SQLite с WAL-режимом требовал аккуратности: после того как junior-агент создавал файл миграции, она не всегда применялась к самой БД. Пришлось вводить обязательный чек: запуск `migrate.py`, проверка таблиц через прямой SQL-запрос, документирование статуса. Без этого можно часами отлавливать фантомные ошибки импорта. **Познавательный блок** Интересный факт: монорепо — это не просто удобство, это *культурный артефакт* команды разработки. Google использует одно гигантское хранилище для всего кода (более миллиарда строк!), потому что это упрощает синхронизацию и рефакторинг. Но цена высока: нужны инструменты (Bazel), дисциплина и чёткие протоколы. Для нашего voice-agent это значит: не просто писать код, а писать его так, чтобы Python-part и Next.js-part *доверяли друг другу*. **Итог** В итоге сложилась простая истина: монорепо работает только если есть **система проверок**. ERROR_JOURNAL.md превратился не просто в логирование ошибок, а в живой артефакт культуры команды. Phase-gate валидация стала гарантией, что при параллельной работе нескольких агентов архитектура не съезжает в стороны. А обязательная проверка миграций — это не занудство, а спасение от трёх часов ночного отлавливания, почему таблица не там, где ей быть. Главный урок: в монорепо важна не столько архитектура, сколько **честность системы**. Чем раньше вы перейдёте от надежды на память к автоматическим проверкам, тем спокойнее спать будете. Почему Python и Java не могут дружить? У них разные dependency trees 😄
SQLite спасает день: масштабируемая БД вместо хаоса в памяти
# SQLite вместо памяти: как я спас Telegram-ботов от хаоса Проект `bot-social-publisher` взлетал буквально на глазах. Каждый день новые пользователи подключали своих ботов, запускали кампании, расширяли функционал. Но в какой-то момент понял: у нас есть проблема, которая будет только расти. Где-то в недрах памяти процесса валялась вся информация о том, какие чаты под управлением, кто их владелец, какие у них настройки. Приватный чат? Группа? Канал? Всё это было либо в переменных, либо в логах, либо вообще только в голове. Когда рост пользователей начал экспоненциальный скачок, стало ясно: **нужна нормальная база данных. Правильная, масштабируемая, без требований на отдельный сервер**. **Первым делом посмотрел на то, что уже есть.** В проекте уже была собственная SQLite база в `data/agent.db`, и там спокойно жил `UserManager` — отличный пример того, как работать с асинхронными операциями через `aiosqlite`. Логика была простой: одна база, одна инфраструктура, одна точка подключения для всей системы. Так почему бы не применить ту же философию к чатам? Архитектурное решение созревало быстро. Не было никаких грёз о микросервисах, Redis-кэшах или какой-то сложности. Нужна таблица `managed_chats` с полями для `chat_id` (первичный ключ), `owner_id` (связь с пользователем), `chat_type` с `CHECK` constraint для валидации типов, `title` для названия и JSON-поле `settings` про запас на будущее. **Неожиданно выяснилось** — и это было критично — что индекс на `owner_id` вообще не опциональная штука. Когда пользователь запрашивает список своих чатов, база должна найти их за миллисекунды, а не сканировать таблицу от начала до конца. SQLite часто недооценивают в стартапах, думают, что это игрушка для тестирования. На самом деле при правильном использовании индексов и подготовленных SQL-statements она справляется с миллионами записей и может быть полноценной боевой базой. Реализацию сделал по образцу `UserManager`: создал `ChatManager` с асинхронными методами `add_chat()`, `is_managed()`, `get_owner()`. Каждый запрос параметризован — никаких SQL-injection уязвимостей. Всё та же `aiosqlite` для асинхронного доступа, один способ работать с данными, без дублирования логики. Красивый момент получился благодаря `INSERT OR REPLACE` — если чат переиндексируется с новыми настройками, старая запись просто заменяется. Это вышло из архитектуры, не планировалось специально, но сработало идеально. **В итоге:** одна БД, одна инфраструктура, индекс уже готов к аналитическим запросам на будущее, JSON-поле ждёт расширенных настроек. Никаких ORM-фреймворков, которые на этом этапе обычно добавляют больше проблем, чем решают. Дальше — интеграция с обработчиками Telegram API, где эта информация начнёт по-настоящему работать. Но то уже следующая история. 😄 Разработчик говорит: «Я знаю SQLite». HR: «На каком уровне?». Разработчик: «На уровне, когда она работает, и я этому не верю».
SQLite вместо памяти: как обуздать рост Telegram-ботов
# Управляем Telegram-чаты как должно: от памяти к базе данных Проект `bot-social-publisher` рос как на дрожжах. Каждый день новые пользователи подключали своих ботов, запускали кампании, развивали функционал. Но вот беда: где-то в памяти процесса валялась информация о том, какие чаты под управлением, кто их владелец, какие у них настройки. Приватный чат? Группа? Канал? Всё это было либо в переменных, либо где-то в логах. Нужна была система. Правильная, масштабируемая, не требующая отдельного сервера для базы данных. **Первым делом** посмотрел, как устроен текущий стек. В проекте уже была собственная SQLite база в `data/agent.db`, и там жил `UserManager` — отличный пример того, как правильно работать с асинхронными операциями через `aiosqlite`. Значит, нужно просто добавить новую таблицу `managed_chats` в ту же базу, скопировать философию управления пользователями и запустить в production. **Архитектурное решение** было ясно с самого начала: никаких микросервисов, никаких Redis-кэшей для этого этапа. Нужна таблица с полями для `chat_id` (первичный ключ), `owner_id` (связь с пользователем), `chat_type` (с проверкой через `CHECK` constraint — только валидные типы), `title` и JSON-поле `settings` на будущее. Неожиданно выяснилось, что индекс на `owner_id` — это не опциональная штука. Когда пользователь запрашивает список своих чатов, база должна найти их быстро, а не сканировать всю таблицу от начала до конца. SQLite часто недооценивают в стартапах, думают, что это игрушка для тестирования. На самом деле при правильном использовании индексов и подготовленных statements она справляется с миллионами записей и может быть полноценной боевой базой. **Реализацию** сделал по образцу `UserManager`: создал `ChatManager` с асинхронными методами `add_chat()`, `is_managed()`, `get_owner()`. Каждый запрос параметризован — никаких SQL injection уязвимостей. Используется всё та же `aiosqlite` для асинхронного доступа, одна точка подключения для всей системы, без дублирования логики. Красивый момент получился благодаря `INSERT OR REPLACE` — если чат переиндексируется с новыми настройками, старая запись просто заменяется. Это вышло из архитектуры, а не планировалось специально. В итоге: одна БД, одна инфраструктура, масштабируемая схема. Когда понадобятся сложные аналитические запросы — индекс уже есть. Когда захотим добавить права доступа или расширенные настройки чата — JSON-поле ждёт. Никаких фреймворков ORM, которые обычно добавляют больше проблем, чем решают на этом этапе. Дальше — интеграция с обработчиками Telegram API, где эта информация будет реально работать. Но то уже следующая история. 😄 Разработчик: «Я знаю ArgoCD». HR: «На каком уровне?». Разработчик: «На уровне Stack Overflow».
Когда AI становится парным программистом: история Claude Code
# Claude Code встречает разработчика: история создания идеального помощника Павел открыл **voice-agent** — проект, который стоял уже полгода в статусе "building". Python-бэкенд на FastAPI, Next.js фронтенд, асинхронная обработка аудио через aiogram. Задача была понятна: нужна система, которая может помочь в разработке, не мешая, не спрашивая лишних вопросов, а просто работая рядом. Первым делом команда определилась с подходом. Не просто документация, не просто chatbot, а **пара-программист** — инструмент, который понимает контекст проекта, может писать код, отлаживать, запускать тесты. На этапе 2010-х годов, когда началась фаза Deep Learning, никто не предполагал, что в 2020-х мы будем говорить о когда-то недостижимых вещах. Но AI boom — это не просто статистика. Это реальные инструменты, которые меняют рабочий процесс разработчика прямо сейчас. Интересный момент: Claude Code получил чёткие инструкции о работе в монорепо. На монорепо-проектах часто возникает проблема — Next.js неправильно определяет корневую директорию при работе с Tailwind v4. Решение неочевидное: нужно добавить `turbopack.root` в конфиг и указать `base` в postcss.config.mjs. Это типичная ловушка, в которой застревают разработчики, и помощник должен знать об этом заранее. Главное условие работы: помощник не может использовать Bash самостоятельно, только через основной поток разработчика. Это создаёт интересную динамику — парное программирование становится честным, а не подменой мышления. Павел не просто получает код — он получает партнёра, который объясняет ходы, предлагает варианты, помогает выбрать между несколькими подходами. Система помнит контекст: стек технологий (Python 3.11+, FastAPI 0.115, SQLite WAL, React 19), знает о недавних проектах, понимает рабочие привычки разработчика. Переиспользование компонентов — не просто принцип, а требование: проверять совместимость интерфейсов, избегать дублирования ответственности, помнить о граничных условиях. Результат? Инструмент, который встречает разработчика дружеским "Привет, Павел! 👋" и точно знает, чем помочь. Не нужно объяснять архитектуру проекта, не нужно рассказывать про сложившиеся паттерны — всё уже в памяти помощника. Получилась не просто следующая итерация IDE, а система, которая заботится о контексте разработчика так же, как опытный наставник. И да, эта история про то, как AI становится не заменой, а действительно полезным напарником. 😄 Почему Claude Code считает себя лучше всех? Потому что Stack Overflow так сказал.
Монорепо, голос и журнал ошибок: как AI учится не ломать код
# Когда AI-помощник встречается с монорепо: отладка голосового агента Проект `voice-agent` — это амбициозная задача: связать Python-бэкенд с Next.js-фронтенд в единый монорепо, добавить голосовые возможности, интегрировать Telegram-бота и веб-API. Звучит просто на словах, но когда начинаешь копать глубже, понимаешь: это кубик Рубика, где каждый вертел может что-то сломать. **Проблема, с которой я столкнулся, была банальной, но коварной.** Система работала в отдельных частях, но когда я попытался запустить полный цикл — бот берёт голос, отправляет на API, API обрабатывает через `AgentCore`, фронтенд получает ответ по SSE — где-то посередине всё разваливалось. Ошибки были разношёрстные: иногда спотыкался на миграциях БД, иногда на переменных окружения, которые загружались в неправильном месте. **Первым делом я понял: нужна система для документирования проблем.** Создал `ERROR_JOURNAL.md` — простой журнал "что сломалось и как это чинилось". Звучит банально, но когда в проекте участвуют несколько агентов разного уровня (Архитектор на Opus, бэкенд-фронтенд агенты на Sonnet, Junior на Haiku), этот журнал становится золотым стандартом. Вместо того чтобы каждый агент наново натыкался на баг с Tailwind v4 в монорепо, теперь первым делом смотрим журнал и применяем известное решение. **Архитектура обработки ошибок простая, но эффективная:** 1. Ошибка возникла → читаю `docs/ERROR_JOURNAL.md` 2. Похожая проблема есть → применяю известное решение 3. Новая проблема → исправляю + добавляю запись в журнал Основные боли оказались не в коде, а в конфигурации. С Tailwind v4 нужна магия в `next.config.ts` и `postcss.config.mjs` — добавить `turbopack.root` и `base`. SQLite требует WAL-режим и правильный путь к базе. FastAPI любит, когда переменные окружения загружаются только в точках входа (`telegram_main.py`, `web_main.py`), а не на уровне модулей. **Интересный момент: я переоценил сложность.** Большинство проблем решались не рефакторингом, а правильной организацией архитектуры. `AgentCore` — это единое ядро бизнес-логики для бота и API, и если оно валидируется с одной строки (`python -c "from src.core import AgentCore; print('OK')"`), весь стек работает как часы. **Итог:** система работает, но главный урок не в технических трюках — в том, что монорепо требует прозрачности. Когда каждая составляющая (Python venv, Next.js сборка, миграции БД, синхронизация переменных окружения) задокументирована и протестирована, даже сложный проект становится управляемым. Теперь каждый новый агент, который присоединяется к проекту, видит ясную картину и может сразу быть полезным, вместо того чтобы возиться с отладкой. На следующем этапе плотнее интегрирую streaming через Vercel AI SDK Data Stream Protocol и расширяю систему управления чатами через новую таблицу `managed_chats`. Но это — уже другая история. 😄 Что общего у монорепо и парка развлечений? Оба требуют хорошей разметки, иначе люди заблудятся.
Одна БД для всех: как мы добавили чаты без архитектурного хаоса
# Одна база на всех: как мы добавили управление чатами без архитектурного хаоса Когда проект растёт, растут и его аппетиты. В нашем Telegram-боте на основе Python уже была отличная инфраструктура — `UserManager` для управления пользователями, собственная SQLite база в `data/agent.db`, асинхронные запросы через `aiosqlite`. Но вот беда: чат-менеджер ещё не появился. А он нам был нужен. Стояла вот какая задача: нужно отслеживать, какие чаты управляет бот, кто их владелец, какой это тип чата (приватный, группа, супергруппа, канал). При этом не создавать отдельную базу данных — это же кошмар для девопса — а переиспользовать существующую инфраструктуру. **Первым делом** заглянул в текущую архитектуру. Увидел, что всё уже завязано на одной БД, один конфиг, одна логика подключения. Идеально. Значит, нужна просто одна новая таблица — `managed_chats`. Задумал её как простую структуру: `chat_id` как первичный ключ, `owner_id` для связи с пользователем, `chat_type` с проверкой типов через `CHECK`, поле `title` для названия и JSON-колонка `settings` на будущее. Обычно на этом месте разработчик бы создал абстрактный `ChatRepository` с двадцатью методами и паттерном `Builder`. Я же решил сделать проще — скопировать философию `UserManager` и создать классический `ChatManager`. Три-четыре асинхронных метода: добавить чат, проверить, управляется ли он, получить владельца. Всё на `aiosqlite`, как и везде в проекте. **Неожиданно выяснилось**, что индексы — это не украшение. Когда начну искать чаты по владельцу, индекс на `owner_id` будет спасением. SQLite не любит полные скены таблиц, если можно обойтись поиском по индексу. Интересный момент: SQLite часто недооценивают в стартапах, думают, что это игрушка. На самом деле она справляется с миллионами записей, если её правильно использовать. Индексы, `PRAGMA` для оптимизации, подготовленные statements — и у вас есть боевая база данных. Многие проекты потом переходят на PostgreSQL только потому, что привыкли к MySQL, а не из реальной нужды. В итоге получилась чистая архитектура: одна БД, одна точка подключения, новая таблица без какого-либо дублирования логики. `ChatManager` живёт рядом с `UserManager`, используют одни и те же библиотеки и утилиты. Когда понадобятся сложные запросы — индекс уже есть. Когда захотим добавить настройки чата — JSON-поле ждёт. И никаких лишних микросервисов. Следующий шаг — интегрировать это в обработчики событий Telegram API. Но это уже другая история. 😄 Почему база данных никогда не посещает вечеринки? Её постоянно блокирует другой клиент!
AI изучает себя: как мы мониторим научные тренды
# Когда AI исследует сам себя: как мы строили систему мониторинга научных трендов Вот уже несколько недель я сидел над проектом **trend-analisis** и постепенно понимал: обычный парсер научных статей — это скучно и малоэффективно. Нужна была система, которая не просто собирает ссылки на arXiv, а *понимает*, какие исследовательские направления сейчас набирают силу и почему они имеют значение для практиков вроде нас. Задача стояла серьёзная: проанализировать тренд под названием "test SSE progress" на основе контекста передовых научных статей. Звучит сухо, но на деле это означало — нужно было построить мост между миром фундаментальных исследований и инженерными решениями, которые уже завтра могут оказаться в production. ## Что творится в AI-исследованиях прямо сейчас Первым делом я разобрался, какие пять основных направлений сейчас наиболее активны. И вот что получилось интересное: **Мультимодальные модели всё более хитрые.** Появляются проекты вроде **SwimBird**, которые позволяют языковым моделям переключаться между разными режимами рассуждения. Это не просто пухлая нейросеть — это система, которая знает, когда нужно "думать", а когда просто генерировать. **Геометрия — это новый король.** Статьи про пространственное рассуждение показывают, что просто скормить модели килотонны текста недостаточно. Нужны геометрические приоры, понимание 3D-сцен, позиции камер. Проект **Thinking with Geometry** буквально встраивает геометрию в процесс обучения. Звучит как философия, но это работает. **Retrieval-системы перестают быть простыми.** Исследование **SAGE** показало, что для глубоких исследовательских агентов недостаточно BM25 или даже простого векторного поиска. Нужны умные retriever'ы, которые сами знают, что ищут. **Дешёвые модели становятся умнее.** Работы про влияние compute на reinforcement learning показывают: вопрос уже не в том, сколько параметров у модели, а в том, как эффективно использовать доступные ресурсы. Это открывает путь к edge AI и мобильным решениям. **Generative модели наконец-то становятся теоретически понятнее.** Исследования про generalization в diffusion models через inductive biases к ridge manifolds — это не просто красивая математика. Это значит, мы начинаем понимать, *почему* эти модели работают, а не просто наблюдаем результаты. ## Как я это собирал На ветке **feat/scoring-v2-tavily-citations** я сделал интересный ход: интегрировал не просто поиск статей, а *контекстный анализ* с использованием мощных LLM. Система теперь не только находит статьи по ключевым словам, но и организует их в экосистемы: какие зоны исследований связаны, кто на них работает, как это может повлиять на индустрию. Неожиданно выяснилось, что самая сложная часть — не техническая. Это правильно определить связи между соседними трендами. Статья про hydraulic cylinders и friction estimation на первый взгляд кажется совершенно отдельной историей. Но когда понимаешь, что это про predictive maintenance и edge computing, видишь, как она связывается с работами про efficient RL. Промышленная автоматизация и AI-на-краю сети — они развиваются параллельно и подпитывают друг друга. ## Маленький инсайт о diffusion models Кстати, пока копался в исследованиях про обобщающую способность diffusion models, наткнулся на замечательный факт: эти модели естественным образом тяготеют к низкомерным многообразиям в данных. Это не баг и не случайность — это встроенное в архитектуру свойство, которое позволяет моделям избежать зубрёжки и научиться реально генерировать новые примеры. Вот такое вот невидимое мастерство работает под капотом. ## Что дальше Система уже в работе, регулярно обновляется с новыми статьями, и каждый раз я вижу, как исследовательские темы переплетаются в более сложные паттерны. Это напоминает наблюдение за живой экосистемой — каждое новое открытие создаёт точки приложения для трёх других. Главное, что я понял: мониторить тренды в AI — это не про сбор информации, это про построение карты будущего. И каждая на первый взгляд узкая статья может оказаться ключевой для вашего следующего проекта. 😄 Обед разработчика: ctrl+c, ctrl+v из вчерашнего меню.
Логи, которые врут: как я нашел ошибку в прошлом Traefik
# Traefik и Let's Encrypt: как я нашел ошибку в логах прошлого Проект **borisovai-admin** молча кричал. Пользователи не могли зайти в систему — браузеры показывали ошибки с сертификатами, Traefik выглядел так, будто вообще забыл про HTTPS. На поверхности всё выглядело очевидно: проблема с SSL. Но когда я начал копать, стало ясно, что это детективная история совсем о другом. ## Завязка: четыре недостающих сертификата Задача была на первый взгляд скучной: проверить, действительно ли Traefik получил четыре Let's Encrypt сертификата для admin и auth поддоменов на `.tech` и `.ru`. DNS для `.ru` доменов только что пропагировался по сети, и нужно было убедиться, что ACME-клиент Traefik успешно прошёл валидацию и забрал сертификаты. Я открыл **acme.json** — файл, где Traefik хранит весь свой кеш сертификатов. И тут началось самое интересное. ## Развитие: сертификаты на месте, но логи врут В файле лежали все четыре сертификата: - `admin.borisovai.tech` и `admin.borisovai.ru` — оба выданы Let's Encrypt R12 - `auth.borisovai.tech` и `auth.borisovai.ru` — R13 и R12 Все валидны, все активны, все будут работать до мая. Traefik их отдавал при подключении. Но логи Traefik были заполнены ошибками валидации ACME-челленджей. Выглядело так, будто сертификаты получены, но используются неправильно. Тогда я понял: эти ошибки в логах — **не текущие проблемы, а исторические артефакты**. Когда DNS для `.ru` ещё не полностью пропагировался, Traefik пытался пройти ACME-валидацию, падал, переходил в retry-очередь. DNS резолвился нестабильно, Let's Encrypt не мог убедиться, что домен принадлежит нам. Но как только DNS наконец стабилизировался, всё прошло автоматически. Логи просто записывали *историю пути к успеху*. ## Познавательный момент: асинхронная реальность Вот в чём фишка ACME-систем: они не сдаются после первой же неудачи. Let's Encrypt встроил resilience в саму архитектуру. Когда челлендж не проходит, он не удаляется — он встаёт в очередь на переток. Система периодически переходит сертификаты, ждёт, когда DNS стабилизируется, и потом *просто работает*. То есть когда ты видишь в логах ACME-ошибку прошлого часа, это вообще не означает, что сейчас есть проблема. Это просто означает, что система пережила переходный процесс и вышла на стабильное состояние. Проблема с браузерами была ещё смешнее. Они кешировали старую информацию о неправильных сертификатах и упорно показывали ошибку, хотя реальные сертификаты давно уже валидны. Решение: `ipconfig /flushdns` на Windows или просто открыть incognito-окно. ## Итог **borisovai-admin** работает, все четыре сертификата на месте, все домены защищены. Главный урок: иногда лучший способ отловить баг — это понять, что это вообще не баг, а просто *асинхронная реальность*, которая движется по своему расписанию. Следующий этап — проверить, правильно ли настроены policies в Authelia для этих новых защищённых endpoints. Но это уже совсем другая история. Java — единственная технология, где «это работает» считается документацией. 😄
Traefik и Let's Encrypt: как я нашел ошибку в логах прошлого
# Охота на невидимых врагов: как я отловил проблемы с сертификатами в Traefik Когда ты администрируешь **borisovai-admin** и вдруг замечаешь, что половина пользователей не может зайти в систему из-за ошибок сертификатов, начинается самая интересная работа. Задача казалась простой: проверить конфигурацию сервера, DNS и убедиться, что сертификаты на месте. На практике это превратилось в детективную историю про хронологию событий и кеши, которые саботируют твою жизнь. ## Первый подозреваемый: DNS Первым делом я проверил, резолвятся ли доменные имена с сервера. Оказалось, что DNS работает — это был хороший знак. Но почему Traefik выглядит так, будто ему не хватает сертификатов? Я полез в `acme.json`, где Traefik хранит выданные Let's Encrypt сертификаты. И вот тут началось самое интересное. ## Сюрприз в acme.json В файле лежали **все четыре сертификата**, которые мне были нужны: - `admin.borisovai.tech` — Let's Encrypt R12, выдан 4 февраля, истекает 5 мая - `admin.borisovai.ru` — Let's Encrypt R12, выдан 8 февраля, истекает 9 мая - `auth.borisovai.tech` — Let's Encrypt R13, выдан 8 февраля, истекает 9 мая - `auth.borisovai.ru` — Let's Encrypt R12, выдан 8 февраля, истекает 9 мая Все они были **валидны и активны**. Traefik их отдавал при подключении. Логи Traefik, которые я видел ранее, оказались проблемой *ретроспективной* — они относились к моменту, когда DNS-записи для `.ru` доменов ещё *не пропагировались* по сети. Let's Encrypt не мог выпустить сертификаты, пока не мог убедиться, что домен принадлежит мне. ## Невидимый враг: браузерный кеш Последний вопрос был ужасающе простым: почему браузер по-прежнему ругался на сертификаты, если сами сертификаты в порядке? **DNS кеш**. Браузер запомнил старую информацию и упорно её использовал. ## Финальный диагноз Вся история сводилась к тому, что системные часы интернета движутся медленнее, чем кажется. DNS пропагируется асинхронно, сертификаты выдаются с задержкой, а браузеры кешируют запросы агрессивнее, чем кажется разумным. Решение? Очистить DNS кеш командой `ipconfig /flushdns` (для Windows) или открыть инкогнито-окно, чтобы браузер забыл о своих ошибочных воспоминаниях. Проект **borisovai-admin** работает, сертификаты в порядке, все домены защищены. Ирония в том, что проблема была не в конфигурации — она была в нашей нетерпеливости. Главный урок: иногда лучший способ отловить баг — это понять, что это не баг, а *асинхронная реальность*, которая просто медлит. 😄
Туннели и таймауты: управление инфраструктурой в админ-панели
# Туннели, Traefik и таймауты: как мы добавили управление инфраструктурой в админ-панель Проект **borisovai-admin** рос не по дням, а по часам. Сначала была одна машина, потом две, потом стало ясно — нужна нормальная система для управления сетевыми туннелями между серверами. Задача выглядела острой: юзеру нужен интерфейс, чтобы видеть, какие туннели сейчас активны, создавать новые и удалять старые. Без этого администрирование превращалось в ручную возню с конфигами на каждой машине. Первое решение было логичным: взял **frp** (Fast Reverse Proxy) — лёгкий инструмент для туннелирования, когда сервер скрыт за NAT или брандмауэром. Почему не что-то более «облачное»? Потому что здесь нужна полная контроль, минимум зависимостей и максимум надёжности. FRP ровно это даёт. Спроектировал веб-интерфейс: добавил страницу `tunnels.html` с простеньким списком активных туннелей, кнопками для создания и удаления. На бэкенде в `server.js` реализовал пять API endpoints для управления состоянием. Параллельно обновил скрипты инсталляции: `install-all.sh` и отдельный `install-frps.sh` для развёртывания FRP сервера, плюс `frpc-template` для клиентов на каждой машине. Не забыл навигационную ссылку «Туннели» на всех страницах админ-панели — мелочь, но юзабилити взлетела. Вроде всё шло гладко, но потом началось. Пользователи начали скачивать большие файлы через GitLab, и соединение рубилось где-то в середине процесса. Проблема оказалась в **Traefik** — наш обратный прокси по умолчанию использует агрессивные таймауты. Стоило файлу загружаться дольше пары минут — и всё, соединение закрыто. Пришлось углубиться в конфиги Traefik. Установил `readTimeout` в 600 секунд (10 минут) и создал специальный `serversTransport` именно для GitLab. Написал скрипт `configure-traefik.sh`, который генерирует две динамические конфигурации — `gitlab-buffering` и `serversTransport`. Результат: файлы теперь загружаются спокойно, даже если это полгигабайта архива. **Интересная особенность Traefik:** это микросервис-балансировщик, который позиционируется как облегчённое решение, но на практике требует хирургической точности при настройке. Неправильный таймаут — и приложение выглядит медленным. Правильный — и всё летает. Один параметр, и мир меняется. Параллельно реорганизовал документацию: разбил `docs/` на логические части — `agents/`, `dns/`, `plans/`, `setup/`, `troubleshooting/`. Добавил полный набор конфигов для конкретного сервера в `config/contabo-sm-139/` (traefik, systemd, mailu, gitlab) и обновил скрипт `upload-single-machine.sh` для их загрузки. За вечер родилась полноценная система управления туннелями с интерфейсом, автоматизацией и нормальной документацией. Проект теперь легко масштабируется на новые серверы. Главное, что узнал: **Traefik** — это не просто прокси, это целая философия правильной конфигурации микросервисов. Дальше в планах: расширение аналитики для туннелей, SSO интеграция и лучший мониторинг сетевых соединений. 😄 **Разработчик**: «Я настроил Traefik». **Пользователь**: «Отлично, тогда почему мой файл не загружается?» **Разработчик**: «А ты пробовал перезагрузить сервер?»
Authelia: как я разобрался с хешами паролей и первым входом в админку
# Запускаем Authelia: логины, пароли и первый вход в админку Проект **borisovai-admin** требовал серьёзной работы с аутентификацией. Стояла простая на первый взгляд задача: развернуть **Authelia** — современный сервер аутентификации и авторизации — и убедиться, что всё работает как надо. Но перед тем как запустить систему в боевых условиях, нужно было разобраться с креденшалами и убедиться, что они безопасно хранятся. Первым делом я заглянул в скрипт установки `install-authelia.sh`. Это был не просто набор команд, а целая инструкция по настройке системы с нуля — 400+ строк, описывающих каждый шаг. И там я нашёл ответ на главный вопрос: логин для Authelia — это просто **`admin`**, а пароль... вот тут начиналось интересное. Оказалось, что пароль хранится в двух местах одновременно. В конфиге Authelia (`/etc/authelia/users_database.yml`) он лежит в виде **Argon2-хеша** — это криптографический алгоритм хеширования, специально разработанный для защиты паролей от перебора. Но на сервере управления (`/etc/management-ui/auth.json`) пароль хранится в открытом виде. Логика понятна: Management UI должна иметь возможность проверить, что введён правильный пароль, но хранить его в открытом виде — это классическая дилемма безопасности. Неожиданно выяснилось, что это не баг, а фича. Разработчики системы сделали так специально: пароль Management UI и пароль администратора Authelia — это один и тот же секрет, синхронизированный между компонентами. Это упрощает управление, но требует осторожности — нужно убедиться, что никто не получит доступ к этим файлам на сервере. Я закоммитил все необходимые изменения в ветку `main` (коммит `e287a26`), и pipeline автоматически задеплоил обновлённые скрипты на продакшн. Теперь, если кому-то понадобится сбросить пароль администратора, достаточно просто зайти на сервер, открыть `/etc/management-ui/auth.json` и посмотреть текущее значение. Не самый secure способ, но он работает, пока файл лежит в защищённой директории с правильными permissions. Главный вывод: при работе с аутентификацией нет мелочей. Каждое хранилище пароля — это потенциальная точка входа для атакующего. **Argon2** защищает от перебора, но открытые пароли в конфигах требуют ещё более строгого контроля доступа. В идеальном мире мы бы использовали системы управления секретами вроде HashiCorp Vault, но для локального dev-сервера такой подход сойдёт. Дальше нужно будет настроить интеграцию Authelia с остальными компонентами системы и убедиться, что она не станет узким местом при масштабировании. Но это история для следующего поста. 😄 Что общего у Scala и подростка? Оба непредсказуемы и требуют постоянного внимания.