Добавил документацию и описание репозитория

2026-06-13 17:10:53 +03:00
parent 82a81c16af
commit 5b53f4e8e8
12 changed files with 647 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Go и доставка одним бинарём
+
+- Дата: 2026-06-13
+
+## Контекст
+
+Jellybit — новый сервис, который будет жить на домашнем медиа-сервере
+umbar. Нужно выбрать язык и способ доставки. Силы и ограничения:
+
+- Это домашняя лаборатория, хочется максимально простой доставки: собрал
+  здесь — скопировал готовый артефакт на сервер, без рантайма и лишних
+  зависимостей на самой машине.
+- В umbar уже устоялось разделение: Python+uv используется вместе с
+  Ansible (инфраструктура), а не для прикладных сервисов.
+- У автора уже есть несколько сервисов на Go — это знакомый и привычный
+  стек именно под сервисы.
+- Сервису нужны: клиент qBittorrent, обращения к LLM, опц. клиенты
+  TMDB/TVDB, разбор имён релизов.
+
+## Рассмотренные варианты
+
+- **Go** — один статический бинарь (`CGO_ENABLED=0`), копируется на
+  сервер; минимальный docker-образ. Знакомый стек. Минус: нет хорошего
+  аналога питоновского `guessit` для разбора имён релизов.
+- **Python + uv** — богатая экосистема распознавания (`guessit`), но
+  тянет рантайм и зависимости на сервер; в проекте уже занят инфра-ролью
+  при Ansible. Смешивать прикладной сервис с инфра-тулингом не хочется.
+- **TypeScript / Node** — экосистема есть, но рантайм на сервере и не
+  основной стек автора для сервисов.
+
+## Решение
+
+Пишем jellybit на **Go**, доставляем одним статическим бинарём: сборка в
+этом репозитории → готовый артефакт с нужной обвязкой копируется на
+umbar. На сервере не нужны ни рантайм, ни менеджер пакетов.
+
+Причина: при домашней лаборатории решающее — простота доставки и
+знакомство со стеком, а не богатство библиотек распознавания. Слабость Go
+в разборе имён релизов закрываем дешёвым `go-ptn` плюс основной разбор всё
+равно делает LLM; при нехватке точности `guessit` можно завернуть лёгким
+сервисом-спутником рядом с бинарём (тоже один файл). Python остаётся за
+инфраструктурой (umbar, Ansible).
+
+## Последствия
+
+- `+` Доставка тривиальна: один файл, без рантайма и зависимостей на
+  сервере; минимальный docker-образ.
+- `+` Стек знаком автору, переиспользуется опыт других Go-сервисов.
+- `+` Чёткая граница: Go — прикладные сервисы, Python+uv — инфра.
+- `-` Нет первоклассного `guessit`; точность пред-парса ниже. Митигация:
+  `go-ptn` + LLM, при необходимости — guessit-спутник.
+- `-` Часть клиентов (например, TVDB v4) придётся писать руками — зрелых
+  готовых библиотек меньше, чем в Python.