WEB Proxy для Telegram Desktop на своём VPS

В моей инфраструктуре давно крутится Telegram-трафик через SOCKS5-туннель на VPS — но у этого подхода есть минусы: SOCKS5 легко режется DPI, а клиент надо настраивать отдельно. Альтернатива от самих разработчиков Telegram Desktop — WEB Proxy: прокси, который маскируется под обычный HTTPS-сайт на 443-м порту. Такой трафик не отличить от обычного захода на сайт, а подключение настраивается в два поля в настройках клиента.

В этой статье — как я развернул tproxy-server на свежем VPS (Debian 13, Hostkey), какие проблемы встретил в установщике и как их обошёл. Полезно всем, кто решит поднять свой WEB Proxy.

Зачем WEB Proxy, а не SOCKS5

Схема работы tproxy-server:

Telegram Desktop → HTTPS:443 → Caddy → tproxy-server:8080 → MTProxy:2398 → Telegram
                                        └ admin :8081 (/readyz, /healthz)

Caddy отдаёт Let’s Encrypt сертификат и проксирует весь трафик на tproxy-server, который сам решает: обычные запросы отдаёт сайт-маскировку, а запросы WEB Proxy — гонит в MTProxy. Снаружи это просто HTTPS-сайт.

Установка: что делает install.sh

У upstream отличный установщик — deploy/install.sh делает почти всё сам:

• ставит пакеты (ca-certificates, curl, nftables);
• ставит Caddy 2.11.4 и Go 1.26.5 (если нет);
• собирает tproxy-server из исходников;
• собирает MTProxy (pinned commit f36d8af) в /opt/MTProxy;
• создаёт systemd-сервисы: tproxy-server, mtproxy, tproxy-firewall, caddy;
• настраивает таймер refresh-mtproxy-config (обновление списка серверов Telegram раз в сутки);
• поднимает nft-правило, закрывающее порты MTProxy (2398, 8888) от внешнего мира.

Запуск:

1
2
3

./deploy/install.sh --hostname vps03.nixg.ru \
  --email me@example.com --site-dir /tmp/tproxy-site \
  --secret "$(cat /tmp/tproxy-secret.txt)"

--secret — 32 hex-символа (openssl rand -hex 16), --site-dir — каталог со статическим сайтом-маскировкой.

Грабли №1: mtproxy.service падает с 203/EXEC, readyz 503

После первого прогона установщика tproxy-server был active, Caddy слушал 80/443, но прокси не работал:

1

● mtproxy.service - failed (Result: exit-code), status=203/EXEC

Порт 2398 не слушался, а /readyz административного эндпоинта отдавал 503 (readyz — это «вся цепочка готова», healthz при этом был 200).

Причина оказалась в правах на бинарь после сборки. Установщик собирает MTProxy в /opt/MTProxy/objs/bin/mtproto-proxy, но из-за umask бинарь и каталоги получают права 700 root:root. Юнит mtproxy.service запускается от пользователя mtproxy (с NoNewPrivileges=true и ProtectSystem=strict) — процесс не может прочитать бинарь и умирает с 203/EXEC.

Лечится одной серией команд:

1
2
3
4

chmod 755 /opt/MTProxy /opt/MTProxy/objs /opt/MTProxy/objs/bin
chown root:mtproxy /opt/MTProxy/objs/bin/mtproto-proxy
chmod 750 /opt/MTProxy/objs/bin/mtproto-proxy
systemctl restart mtproxy

После этого mtproxy — active (running), слушает 0.0.0.0:2398, readyz → 200.

Грабли №2: флейк go test в установщике

Первый прогон install.sh (холодный кэш Go, сборка всех пакетов параллельно) упал на тестах:

1
2

FAIL: internal/config — TestLoadAcceptsSystemdCredentialReadPermissions:
group/other-readable profiles file outside a credential directory was accepted

А повторный go test ./... (тёплый кэш) — PASS. Это классическая гонка при холодном параллельном прогоне тестов, а не баг кода. Лечение простое: перезапустить install.sh — дальше идёт нормально.

Грабли №3: «не открыты порты 80/443» — ложная тревога

Снаружи curl на 80/443 не отвечал, и я заподозрил firewall провайдера (Hostkey). Пошёл в панель — а там вообще нет настроек firewall/прокси. Полез в документацию, искал API…

На самом деле всё проще: порты у провайдера открыты по умолчанию, просто на 80/443 ничего не слушало — curl получал connection refused. Проверка: поднимаю временный python3 -m http.server 80 → TCP connect снаружи OK. После установки Caddy сам слушает 80/443.

Так что если у вас после установки снаружи не открывается сайт — сначала проверьте, что порт слушается (ss -tlnp), а не ищите firewall в панели провайдера.

Проверка после установки

1
2
3
4
5
6

systemctl status tproxy-server mtproxy tproxy-firewall caddy   # все active
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8081/readyz    # 200
curl -s -o /dev/null -w '%{http_code}' https://vps03.nixg.ru/          # 200 (сайт)
openssl s_client -connect vps03.nixg.ru:443 -servername vps03.nixg.ru  # LE-серт
ss -tlnp | grep -E ':80 |:443|:2398|:8080|:8081'
nft list ruleset | grep -E '2398|8888'   # закрыто от внешнего мира

Наружу видны только 80/443. MTProxy-бэкенд (2398, 8888) закрыт nft — iifname != "lo" ... drop, то есть бэкенд не светится и не принимает подключения напрямую.

Настройка клиента

В Telegram Desktop: Settings → Advanced → Connection Type → Use custom proxy → NEW PROXY → WEB Proxy:

• hostname: vps03.nixg.ru
• secret: (32 hex-символа, которые вы сгенерировали)

Итог

WEB Proxy — отличная замена SOCKS5-туннелю, если нужна маскировка под обычный HTTPS: настраивается в два поля, трафик неотличим от сайта, а готовый установщик upstream делает почти всю работу. Главные грабли — права на бинарь MTProxy после сборки (203/EXEC) и ложная тревога с «закрытыми портами». Оба решаются за пару минут, если знать, куда смотреть.

Полный набор файлов (заметки, сайт-маскировку, команду установки) я сложил в репозиторий tproxy-web — точнее, в свой tproxy-web на gitverse, а INSTALL_NOTES.md с деталями лежит там же.

Как я перевёл aux-задачи Hermes на локальные модели

У меня на домашнем сервере живёт агент Hermes — он ведёт блог, следит за сертификатами, ходит в мессенджеры и выполняет кучу мелких, но важных задач. Основную модель он берёт в облаке (провайдер polza.ai, 131K контекст), а для вспомогательных задач — генерации заголовков, извлечения текста из веб-страниц, описания картинок (vision) и сжатия контекста — у него есть отдельный механизм auxiliary. По умолчанию все aux-задачи тоже резолвятся в облако, а значит — тратят токены и деньги.

На сервере стоит видеокарта RTX 5060 Ti 16 GB (да, та самая, про которую я писал в статье про зависание Ubuntu при загрузке). Раз есть GPU — почему бы не увести aux-задачи на локальные модели? Приватность, скорость, ноль затрат на API. Рассказываю, как выбирал модель, как настраивал и какой грабли встретил при отключении режима размышлений (thinking) у Qwen3.

Что такое auxiliary-задачи в Hermes

Hermes — агент с модульной архитектурой. Кроме основной модели (которая думает и пишет ответы), он вызывает вспомогательные (auxiliary) задачи через отдельный клиент — auxiliary_client.py. В моей версии их несколько:

Ключевой момент: только compression требует большого контекста (64K). Это жёсткое требование самого Hermes — для сжатия истории ему нужна модель, которая видит весь диалог. Локальные GGUF-модели до 64K не дотягивают (проверил: qwen3-8b упирается в 40960 токенов контекста, qwen2.5-coder-14b — в 32768; теги «64k/65k» в названиях моделей — маркетинг, реальный контекст меньше). Поэтому compression я оставил в облаке, а вот все остальные aux-задачи — кандидаты на локализацию.

Выбор модели

Критерии были простые:

1. Модель должна уметь vision (для vision-задачи).
2. Должна влезать в 16 GB VRAM вместе с эмбеддинг-моделью bge-m3 и основной текст-моделью.
3. Должна быстро отвечать — aux-задачи вызываются часто, ждать минуту утомительно.
4. Желательно уметь закрыть и текстовые задачи (генерация заголовков, извлечение текста) — чтобы не гонять облако вообще.

Я поставил qwen3-vl:8b — мультимодальную модель Qwen 8B с поддержкой vision. Она весит ~6.1 GB, контекст 262K (но KV cache на полный контекст — ~309 GB, так что реально держу num_ctx=8192). Проверил через /api/show — у неё есть capability vision, значит Hermes её увидит как vision-модель.

Важный нюанс про qwen3-vl: она великолепно описывает картинки (проверено E2E — отвечает «red»/«blue» на цветные картинки за 1-10 секунд), но для текстовых задач она… слишком умная. На простой вопрос «какой сегодня день недели» она генерирует 3778 токенов рассуждений и отвечает через 64 секунды! Это потому, что qwen3-модели по умолчанию включён режим reasoning/thinking. Для заголовков и извлечения текста это неприемлемо.

Поэтому я взял две модели:

• qwen3-vl:8b — для vision (картинки);
• qwen3:8b — для текстовых aux (title_generation, web_extract), с принудительно отключённым thinking.

Настройка

Hermes поддерживает per-task конфигурацию auxiliary-задач в config.yaml. Формат:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

auxiliary:
  vision:
    provider: custom
    model: qwen3-vl:8b
    base_url: http://localhost:11434/v1
    api_key: ollama
  title_generation:
    provider: custom
    model: qwen3:8b
    base_url: http://localhost:11434/v1
    api_key: ollama
    extra_body:
      think: false
  web_extract:
    provider: custom
    model: qwen3:8b
    base_url: http://localhost:11434/v1
    api_key: ollama
    extra_body:
      think: false

Настройка через CLI:

1
2
3
4
5

hermes config set auxiliary.vision.provider custom
hermes config set auxiliary.vision.model qwen3-vl:8b
hermes config set auxiliary.vision.base_url http://localhost:11434/v1
hermes config set auxiliary.vision.api_key ollama
# и так для каждой задачи

Пара важных граблей:

• api_key обязан быть непустым. В коде Hermes пустой api_key означает «унаследовать ключ основного провайдера» — и тогда он попытается сходить в polza.ai с локальной моделью. Я поставил заглушку ollama (Ollama её не проверяет).
• Ollama надо форматировать через OpenAI-совместимый эндпоинт /v1/chat/completions — именно так Hermes ходит в локальные модели.
• Для qwen3-vl держать num_ctx небольшим (я использую 8192), иначе Ollama пытается зарезервировать KV cache под весь 262K контекст — это ~309 GB, runner падает с EOF.

Допиливание отключения режима размышлений (thinking)

Самая интересная часть. Qwen3-модели (и qwen3, и qwen3-vl) по умолчанию генерируют скрытый поток рассуждений (thinking/reasoning) перед ответом. Для aux-задач это означает:

• Заголовок генерируется 64 секунды вместо 3-5.
• При ограниченном max_tokens ответ вообще пустой — весь бюджет съедает thinking, до content дело не доходит.

Я перепробовал несколько способов отключить thinking, и вот что выяснилось:

Что НЕ работает (в Ollama)

Я проверил chat template модели — там есть команды /think и /no_think, но они не активируются в Ollama (флаг IsThinkSet не выставляется).

Что работает

Единственный рабочий способ — корневой параметр think: false в теле запроса:

1
2
3
4
5

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{"role": "user", "content": "Привет!"}],
  "think": false
}'

Ответ приходит через 0.7 секунды (вместо 64!), reasoning=false, content заполнен. Именно эту опцию я и прописал в extra_body конфига Hermes:

1
2

extra_body:
  think: false

В коде Hermes extra_body уходит в корень JSON-тела запроса — как раз туда, куда Ollama ждёт параметр think.

Проверка E2E

После настройки прогнал реальные вызовы через вспомогательный клиент Hermes (call_llm):

VRAM и память

На RTX 5060 Ti 16 GB в памяти держатся одновременно:

• qwen3-vl:8b — ~7.2 GB (vision)
• qwen3:8b — ~6.1 GB (текст)
• bge-m3 — ~1.2 GB (эмбеддинги)

Итого ~14.5 GB — влезает с запасом, и переключение vision↔текст происходит без выгрузки модели. Проверено через /api/ps: после текстового вызова в памяти остаются обе модели.

Итог

• Vision полностью локальный — картинки описываются на сервере, в облако не уходят.
• Текстовые aux (заголовки, извлечение текста) — локальные, быстрые, бесплатные.
• Compression остался в облаке — ему нужен контекст 64K, который локально не влезает.
• Облачные токены тратятся только на основную модель и сжатие контекста — экономия существенная.

Самое ценное знание, которым делюсь: если вы используете Qwen3 в Ollama для вспомогательных задач — не забудьте think: false. Это превращает задумчивую модель, которая час думает над заголовком, в мгновенного исполнителя. И помните: /no_think, enable_thinking и thinking: disabled — в Ollama не работают, работает только корневой think: false.

Полезные ссылки: Hermes Agent · Ollama qwen3-vl · Ollama qwen3

Расскажу про то как один параметр в кофиге Wireguard причинил мне опыт по разбору половины сетевых настроек Ubuntu. Один с виду безобидный параметр… IaC блин нужен обязательно. Я просто забыл что и для чего менял, а потом уже поздно было вспоминать.

Симптомы: тишина в эфире и гора dropped пакетов

Всё началось с того, полсе смерти системного диска в моем домашнем сервере, я перестал крутить его 24/7 и набегами по выходным конифгурировал его, пытаясь вернуть привычный набор сервисом. И вот однажды включаю я сервер, а у меня проблема с системным резолвом DNS. Так-то напрямую nslookup ya.ru 8.8.8.8 выдает всё нормально. но система ни в какую не хочет резолвить адреса. Так-то я забыл, что неделей ранее я настраивал Wireguard со своими VPS, и что именно после настройки Wireguard сервер потерял доступ к локальной сети и интернету. начал ковырять, ИИшка подсказала что на Ubuntu надо netplan копать, начал фигачить yamlики, тут время вышло и я еще на неделю забросил комп. И вот вчера, сейчас далеко за полночь, я его включил и опять начал разбираться, естественно забыл не только то что я две недели назад делал, но и то чем неделю назад занимался. И вот картинка, сервер загрузился, подозрительно долго грузился кстати, но по сети недоступен.

Первая диагностика через ip -s link show показала тревожную картину на интерфейсе eno1:

• RX: 53 000+ пакетов принято.
• Dropped: 21 000+ пакетов отброшено.
• TX: Всего 40 пакетов отправлено.

Команда ip route show выводила только маршрут для интерфейса wg0. Маршрута по умолчанию через физический интерфейс не было. Система «не видела» шлюза.

Команда ip a показала, что на всех интерфейсах, кроме loopback, ip-адреса отсутствуют.

Попытки перезапустить службы или применить конфигурацию через sudo netplan apply не давали результата. Интерфейс зависал в состоянии configuring, а адрес не присваивался.

Расследование: кто виноват?

1. Конфликт маршрутизации

Первоначальная гипотеза была в том, что WireGuard перехватывает весь трафик. Однако в конфиге wg0.conf параметр AllowedIPs был ограничен подсетью туннеля (10.8.0.0/24). Он не должен был блокировать локальную сеть.

Проблема оказалась глубже: отсутствие маршрута по умолчанию для eno1 означало, что ядро просто не знало, куда девать исходящие пакеты, кроме как в туннель (если бы он был активен) или в никуда.

2. Почему DHCP молчал?

Ubuntu 24.04 использует стек systemd-networkd для управления сетью на серверных сборках. Конфигурация задается через Netplan (YAML-файлы).

Проверка статуса показала:

1
2

networkctl status eno1
State: routable (configuring)

Статус configuring в сочетании с routable — это классический признак того, что демон ждет завершения какой-то операции. В логах journalctl -u systemd-networkd не было ошибок получения адреса IPv4, зато постоянно терялась аренда IPv6 (DHCPv6 lease lost).

Оказалось, что systemd-networkd по умолчанию пытается настроить и IPv4, и IPv6. Если сервер DHCPv6 не отвечает или есть проблемы с Router Advertisements (RA), демон может зависнуть в ожидании, блокируя переход интерфейса в полностью рабочее состояние для IPv4.

3. Долгая загрузка

При перезагрузке я заметил, что система висит на этапе Job systemd-networkd-wait-online.service. Однако служба wait-online держала систему, пока сеть не поднимется. Поскольку сеть не могла подняться из-за зависшего DHCP-клиента, загрузка затягивалась.

Решение: поэтапный демонтаж проблем

Шаг 1. Отключение ожидания сети

Чтобы система загружалась быстро, даже если сеть сбоит, отключил службу ожидания:

1
2

sudo systemctl disable systemd-networkd-wait-online.service
sudo systemctl mask systemd-networkd-wait-online.service

Шаг 2. Отключение IPv6

Возможно проблема долгой загрузки была в ожидании ответов IPv6, а поскольку в моей инфраструктуре он пока не критичен, то я отключил его на уровне ядра. Это сузило площадь ошибок в конфигурации systemd-networkd, я сосредоточился только на IPv4.

В /etc/sysctl.conf добавил:

1
2
3

net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.lo.disable_ipv6=1

И применил изменения: sudo sysctl -p.

Шаг 3. Переход на прямую конфигурацию systemd-networkd

Файлы Netplan (/etc/netplan/*.yaml) генерируют конфиги для бэкенда. У меня их было два, и они могли конфликтовать или содержать избыточные параметры, тем более я уже и не помнил как и почему я их именно так писал. Изолировал прослойку Netplan, создав файл-заглушку /etc/systemd/network/10-eno1.network с настройками для systemd-networkd:

1
2
3
4
5
6
7
8

[Match]
Name=eno1

[Network]
DHCP=ipv4
IPv6AcceptRA=no
DNS=1.1.1.1
DNS=8.8.8.8

Ключевой момент здесь — DHCP=ipv4. Тут явно говорим демону: «Используй только IPv4, игнорируй IPv6». Параметр IPv6AcceptRA=no дополнительно страхует от ожидания сообщений роутера.

Удалил старые файлы из /etc/netplan/, чтобы избежать двойного применения настроек, и перезапустил службу:

1

sudo systemctl restart systemd-networkd

Интерфейс сразу получил адрес 192.168.1.3 и перешел в статус routable (configured). Системный резолв DNS заработал.

Шаг 4. Финальный босс: DNS и WireGuard

Пинги пошли, но nslookup ya.ru выдавал таймауты на 127.0.0.53 (локальный stub-resolver systemd-resolved). Вот про эту штуку я не знал, поэтому теперь знаю что не нужно поднимать на каждом сервер unbound, в systemd все есть из коробки.

Проверка resolvectl status показала странность:

• Link 2 (eno1): DNS Servers: 1.1.1.1, 8.8.8.8
• Link 5 (wg0): DNS Domain: ~.

Правда я её не заметил сперва, но консультации с ИИ не всегда являются потерей времени. Символ ~. означает «глобальный поиск». WireGuard, увидев в своем конфиге строку DNS = 1.1.1.1, автоматически сообщил системе, что этот DNS-сервер должен обрабатывать все запросы, перекрывая настройки физического интерфейса. Но так как туннель до собственных серверов и маршрутов до внешних DNS в нём нет, разрешения имен не работали.

Решение: В файле /etc/wireguard/wg0.conf я закомментировал всего лишь одну строку, как потом выяснилось добавленной в конфиг по рекомендаци такой же ИИшечки:

1

# DNS = 1.1.1.1

Переподнял туннель:

1
2

sudo wg-quick down wg0
sudo wg-quick up wg0

Теперь wg0 имеетв выводк networkctl status eno1 Current Scopes: none, а все DNS-запросы идут через основной интерфейс eno1 на публичные серверы Cloudflare и Google.

Итоги и выводы

1. WireGuard и DNS: Параметр DNS в конфиге WireGuard — это не просто рекомендация, а команда для системы изменить глобальные настройки резолвинга. Если ты не хочешь, чтобы туннель перехватывал все DNS-запросы, не указывай этот параметр в конфиге клиента, либо используйте более тонкие настройки Domains (если клиент поддерживает).
2. Ubuntu 24.04 и IPv6: По умолчанию включенный IPv6 может вызывать задержки при получении адреса IPv4, если инфраструктура не готова к v6. В домашних лабораториях его часто проще отключить, чем дебажить RA и DHCPv6.
3. Netplan vs systemd-networkd: Netplan удобен, но иногда прямая конфигурация systemd-networkd дает больше прозрачности и контроля, особенно при отладке сложных случаев с DHCP.
4. systemd-networkd-wait-online: На серверах, где сеть может падать или долго подниматься, эту службу лучше маскировать, иначе она будет тормозить загрузку всей ОС.

Эта ошибка в конфиге WG стоила мне нескольких часов, но теперь моя домашняя лаборатория работает стабильно, а конфиги приведены к минимальному и понятному виду, а я узнал еще что-то новенькое про любимый Линукс.

(Ссылка на диалог с Qwen)[https://chat.qwen.ai/s/0cfbc11b-dae3-4dba-bfaf-b0788172d07c?fev=0.2.45]

На домашней машине у меня всё еще Winodws 10 стоит(домашние предпочитают удобные цепи закрытого софта вместо свободы), но доставать ноут каждый раз когда нужно управлять инфраструктурой через Ansible бывает сложно, самый практичный путь — поставить Debian в WSL2 и работать уже внутри него. Такой сценарий дает полноценную Linux-среду, не требует отдельной виртуальной машины и удобно бэкапится целиком через wsl –export в формат VHDX.

Ниже — полностью рабочая схема без Microsoft Store: ручная установка WSL2, импорт Debian, настройка uv, установка ansible-core, маппинг проекта на D:\ansible и резервное копирование через VHDX.

Что понадобится

Для WSL2 на Windows 10 нужна версия 2004 и сборка 19041 или новее, а также включенная аппаратная виртуализация в BIOS/UEFI. Установка WSL и Debian выполняется из PowerShell от имени администратора.

• Windows 10 с поддержкой WSL2.
• PowerShell с правами администратора.
• Доступ к интернету для загрузки компонентов и пакетов.
• Папка для WSL, например D:\WSL\Debian.
• Папка для проектов, например D:\ansible.

Включаем WSL2 вручную

Если Microsoft Store недоступен или вы не хотите им пользоваться, включите компоненты Windows вручную:

1
2

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

После этого перезагрузи ПК. Эти два компонента нужны для работы WSL2, потому что дистрибутив запускается внутри легковесной виртуальной машины.

Затем задаём WSL2 как версию по умолчанию:

1

wsl --set-default-version 2

Устанавливаем Debian без Store

Для установки Debian без Microsoft Store удобнее использовать импорт rootfs-архива или готового VHDX-образа. Важно не искать случайные архивы по форумам, а брать Debian из официального источника или собирать rootfs на основе официального образа Debian.

На практике удобны два пути:

скачать официальный Debian-образ и подготовить из него rootfs;

либо сразу импортировать уже готовый rootfs-архив, если он у вас есть.

Пример импорта:

1
2

mkdir D:\WSL\Debian
wsl --import Debian D:\WSL\Debian D:\Downloads\debian-rootfs.tar --version 2

После этого запускаем Debian так:

1

wsl -d Debian

Если Debian уже был установлен из Store, его можно перенести в управляемый каталог через экспорт и повторный импорт, что особенно удобно для бэкапа и миграции.

Перенос Debian из Store

Сценарий переноса простой: экспортируем текущий дистрибутив, затем импортируем его в нужную папку. Microsoft документирует wsl –export, wsl –unregister и wsl –import как штатный путь для переноса и резервного копирования WSL-дистрибутивов. ​

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Смотрим имя дистрибутива:
wsl -l -v

#Останавливаем WSL
wsl --shutdown

#Экспортируем Debian в архив
wsl --export Debian D:\Backup\Debian.tar

#Удаляем старую регистрацию, если нужен чистый перенос

wsl --unregister Debian

#Импортируем в управляемую папку
wsl --import Debian D:\WSL\Debian D:\Backup\Debian.tar --version 2

После этого Debian будет жить в D:\WSL\Debian, а не в Store-профиле пользователя, и им станет проще управлять и делать бэкап.

Настраиваем Ansible через uv

Для Ansible в WSL2 я рекомендую не системную установку и не pip в системный Python, а отдельное виртуальное окружение, управляемое через uv. Такой подход изолирует зависимости, не трогает системный Python Debian и позволяет легко воспроизводить окружение после восстановления из бэкапа.

ansible-core — это базовый движок Ansible. В отличие от полного пакета ansible, он содержит только ядро: выполнение playbook’ов, inventory-логику, CLI и основную инфраструктуру. Это делает установку легче, прозрачнее и удобнее для проектного workflow.

Минимальный набор для установки:

• uv;
• ansible-core;
• openssh-client;
• git;
• python3.

После входа в Debian:

1
2
3

sudo apt update
sudo apt install -y curl git openssh-client python3
curl --proto '=https' --tlsv1.2 -LsSf https://releases.astral.sh/github/uv/releases/download/0.11.7/uv-installer.sh | sh

После установки uv нужно переоткрытьshell-сессию или добавьте uv в PATH, если установщик это не сделал автоматически. uv умеет создавать виртуальные окружения и ставить пакеты внутрь них, а также работать с выбранным Python-интерпретатором.

Создаем окружение Если проект лежит в ~/ansible:

1
2
3
4

cd ~/ansible
uv venv
source .venv/bin/activate
uv pip install ansible-core

Если нужен линтер:

1

uv pip install ansible-core ansible-lint

Такой workflow хорош тем, что версию Ansible можно менять независимо от системы, а зависимости проекта не смешиваются с Debian-пакетами.

Почему ansible-core удобнее Для рабочей машины под Ansible ansible-core обычно удобнее, чем полный пакет ansible, по нескольким причинам. Во-первых, он меньше и чище, поэтому окружение проще поддерживать. Во-вторых, вы явно контролируете, какие коллекции и зависимости нужны именно вашему проекту. В-третьих, это снижает зависимость от версии, которую выдает системный репозиторий Debian.

Практически это означает следующее:

• ansible-core ставится в проектный venv;
• коллекции ставятся отдельно через ansible-galaxy или по requirements.yml;
• при необходимости окружение можно пересоздать за пару минут.

Рекомендуемый workflow

1
2
3
4
5

mkdir -p ~/ansible
cd ~/ansible
uv venv
source .venv/bin/activate
uv pip install ansible-core

Дальше в репозитории храним:

• playbook’и;
• inventory;
• requirements.yml;
• ansible.cfg. Сами зависимости и .venv в Git не добавляем. Это делает проект переносимым и аккуратным.

Маппинг ~/ansible в D:\ansible

Если хотите хранить проект на диске Windows, используйте стандартный путь WSL: D:\ansible в Linux виден как /mnt/d/ansible. Это штатный механизм WSL, а для обратного преобразования путей существует wslpath. ​ Самый простой вариант:

1

cd /mnt/d/ansible

Если хотите, чтобы в Linux путь был именно ~/ansible, создайте символическую ссылку:

1
2

rm -rf ~/ansible
ln -s /mnt/d/ansible ~/ansible

После этого ~/ansible будет указывать на D:\ansible. Это удобно: в Ansible-проектах вы работаете с привычным Linux-путем, а файлы физически лежат на Windows-диске. ​

Команды управления WSL

Минимальный набор команд для повседневной работы:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Показать все дистрибутивы и их версию
wsl -l -v

# Запустить Debian
wsl -d Debian

# Сделать Debian дистрибутивом по умолчанию
wsl --set-default Debian

#​ Полностью остановить WSL2
wsl --shutdown

# Остановить только Debian
wsl --terminate Debian

# Перевести Debian в WSL2, если он вдруг оказался в WSL1
wsl --set-version Debian 2

Бэкап через VHDX

Для WSL2 самый удобный резервный формат — VHDX. Microsoft прямо поддерживает экспорт дистрибутива в VHDX через wsl –export … –vhd, а затем импорт обратно через wsl –import … –vhd. Это сохраняет весь дистрибутив целиком, включая Ansible, Python-окружение, ключи, историю shell и рабочие файлы.

1
2
3
4
5

# Перед бэкапом обязательно останавливаем WSL
wsl --shutdown

# Затем создаtv бэкап
wsl --export Debian D:\Backup\Debian\Debian.vhdx --vhd

Это удобнее ручного копирования ext4.vhdx, потому что команда сразу создает переносимый снимок дистрибутива в формате VHDX.

Восстановление

Если нужно восстановить среду из такого бэкапа, импортируем VHDX как дистрибутив:

1

wsl --import DebianRestored D:\WSL\DebianRestored D:\Backup\Debian\Debian.vhdx --vhd --version 2

Если мы храним дистрибутив в отдельной папке и используете import-in-place, можно подключить существующий VHDX без распаковки. Это особенно удобно при переносе среды на другой диск или другой компьютер.

Практичная схема для работы

Для повседневного использования я бы рекомендовал такую схему:

• Debian живет в WSL2;
• Ansible ставится через uv в .venv;
• проекты лежат в D:\ansible и маппятся через /mnt/d/ansible;
• резервная копия делается через wsl –export … –vhd;
• .venv в Git не хранится, а dependencies фиксируются в документации или requirements.yml.

Такой подход дает хорошую изоляцию, быстрый старт после восстановления и удобную миграцию между машинами. Для WSL2 это один из самых практичных способов использовать Ansible в Windows 10 без необходимости перезагрузки.

Проблема: рутина при создании постов

Когда я только начинал вести блог на Hugo, каждый новый пост создавался через боль и страдания:

1. Создать папку вручную content/posts/название-поста/
2. Скопировать туда index.md из соседней папки
3. Отредактировать front matter (дату, заголовок, теги)
4. Придумать slug для красивого URL
5. …и не забыть, что папку лучше назвать на латинице

На всё это уходило пара минут чисто механической работы. А когда постов 10–20, это начинает реально бесить.

В этой статье я расскажу, как я решил эту проблему с помощью штатных возможностей Hugo: архетипов (archetypes), пермалинков (permalinks) и правильной организации бандлов (bundles).

Что такое бандл и зачем папка для каждого поста

Hugo поддерживает три типа контента:

Три способа хранения контента в Hugo

1. Простой файл .md (без папки)

Самый простой способ — просто положить файл мой-пост.md в папку content/posts/:

1
2
3
4
5

content/
└── posts/
    ├── первый-пост.md
    ├── второй-пост.md
    └── третий-пост.md

Плюсы:

• Максимально просто, ничего создавать не нужно
• Подходит для простых постов без изображений

Минусы:

• Все изображения нужно класть в общую папку static/images/
• Нельзя прикрепить к посту специфичные файлы (PDF, архивы и т.д.)
• Изображения нужно называть уникально, чтобы не пересекались с другими постами

2. Leaf bundle (папка + index.md)

1
2
3
4
5
6

content/
└── posts/
    └── мой-пост/
        ├── index.md
        ├── hero.jpg
        └── code-example.py

Плюсы:

• Все ресурсы поста в одном месте
• Можно ссылаться на изображения относительно:
• Не нужно думать об уникальности имён файлов

Минусы:

• Нужно создавать папку (но мы это автоматизировали)

3. Branch bundle (папка + _index.md)

1
2
3
4
5
6

content/
├── posts/
│   ├── _index.md          <- описывает секцию /posts/
│   ├── первый-пост.md
│   └── мой-пост/
│       └── index.md

Плюсы:

• _index.md позволяет задать заголовок, описание для всей секции
• Можно настроить отдельный шаблон для списка постов

Структура моего блога:

1
2
3
4
5
6
7
8
9

content/
├── posts/
│ ├── hugo-slugs-archetypes-bundles/
│ │ ├── index.md
│ │ ├── images/
│ │ │ └── diagram.png
│ │ └── code-example.txt
│ └── другой-пост/
│ └── index.md

Плюсы такого подхода:

• Все посты хранятся одинаково — папка + index.md. Не нужно думать, какой способ выбрать.
• Все файлы поста в одном месте
• Можно удобно ссылаться на изображения: ![схема](images/diagram.png)
• Не нужно придумывать уникальные имена для картинок глобально
• Если я захочу экспортировать пост в другой блог, достаточно скопировать одну папку со всеми ресурсами.

Почему папку бандла нужно называть на латинице

Здесь кроется важный момент. Hugo позволяет использовать любые символы в именах папок, включая кириллицу. Но есть две причины использовать латиницу:

1. Чистые URL. Если папка называется мой-пост, то URL будет /%D0%BC%D0%BE%D0%B9-%D0%BF%D0%BE%D1%81%D1%82/. Браузер это поймёт, но выглядит ужасно.
2. Slug без транслитерации. Имя папки удобно использовать как slug — последний сегмент URL. А латиница в URL — это стандарт и хороший тон.

Правило: папку называем на латинице (например, my-awesome-post), а заголовок внутри пишем по-русски.

Как автоматизировать создание бандла через консоль

Команда для создания бандла с одной папкой:

1

hugo new content posts/название-папки/index.md

Hugo сам создаст папку, сгенерирует index.md с front matter из архетипа.

Важно: эта команда появилась в Hugo 0.112. В старых версиях нужно было сначала создать папку, потом файл.

Настройка архетипа (archetype)

Архетип — это шаблон для новых файлов. Он лежит в archetypes/default.md (или в archetypes/post-bundle.md для конкретного типа).

Мой архетип выглядит так (TOML-формат):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
date = '{{ .Date }}'
lastmod = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
slug = '{{ .File.ContentBaseName }}'
description = ''
author = 'Кразя'

categories = [
  'uncategorized'
]

tags = [
  'draft'
]
---

Разберём ключевые моменты: Поле Значение title Берёт имя папки, заменяет дефисы на пробелы и делает заглавные буквы. my-awesome-post → My Awesome Post slug Просто берёт имя папки как есть: my-awesome-post .File.ContentBaseName Встроенная переменная Hugo — имя текущей папки без расширения и пути

После создания поста я вручную меняю title на русский и заполняю description, categories, tags.

Настройка permalinks для красивых URL

Чтобы URL выглядел как 2025/03/my-awesome-post/, а не как posts/my-awesome-post/, добавляем в hugo.toml:

1
2

[permalinks]
  posts = "/:year/:month/:slug/"

Теперь при сборке сайта Hugo сам построит нужную структуру. При этом внутри content/ всё остаётся по-прежнему — папка в posts/.

Полный цикл создания поста (без лишних телодвижений)

Вот как теперь выглядит создание нового поста в моём блоге:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 1. Создаём бандл с латинским именем папки
hugo new content posts/hugo-best-practices/index.md

# 2. Открываем файл и правим русский заголовок, описание, теги
vim content/posts/hugo-best-practices/index.md

# 3. Пишем пост в markdown
# 4. Смотрим локально
hugo server -D

# 5. Публикуем
make deploy

Что ещё можно добавить в front matter

В процессе настройки я выяснил, что Hugo поддерживает много полезных полей:

Итог

После всех настроек создание нового поста занимает ровно столько времени, сколько нужно на написание контента. Никакой ручной возни с папками и копированием index.md.

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

• Используйте leaf bundles (папка + index.md) для хранения всех ресурсов поста в одном месте

• Папки называйте на латинице — это даст чистые URL и автоматический slug

• Настройте архетип с переменной {{ .File.ContentBaseName }} для автоматической генерации title и slug

• Добавьте [permalinks] в конфиг для красивых URL с датами

Создавайте новый пост одной командой: bash hugo new content posts/имя-папки/index.md

Теперь можно сосредоточиться на том, ради чего всё затевалось — на содержании.

Если у тебя есть свои лайфхаки по Hugo или ты знаешь, как сделать транслитерацию slug прямо из заголовка — пишите мне в Telegram https://t.me/kpa39l. Обсудим.