При подготовке материала использовались тезисы из книги Чипа Хьюена "AI-инженерия"
Не понятные термины смотрите в конце: "FAQ: Расширенный словарь терминов AI- и ML-инженера"

Индустрия искусственного интеллекта переживает тектонический сдвиг. Граница между классическим машинным обучением и созданием современных ИИ-приложений стала настолько резкой, что породила новую профессию, новые стандарты разработки и даже новые интернет-мемы. Разбираемся, чем на самом деле занимаются AI-инженеры, зачем им нужна фундаментальная математика и на какие проекты стоит обратить внимание.

Разница между ML-инжинирингом и AI-инжинирингом?

Смена парадигмы произошла в результате перехода от обучения моделей под узкие задачи к использованию готовых мультимодальных и языковых систем.

• ML-инжиниринг (традиционный) сфокусирован на полном цикле создания моделей: сборе и ручной разметке данных, конструировании признаков (feature engineering), подборе архитектур нейросетей, обучении с нуля и тонкой настройке гиперпараметров.
• AI-инжиниринг опирается на готовые базовые модели (Foundation Models, LLM). Основная работа смещается от создания архитектур к их адаптации и оркестрации: промт-инжинирингу, построению конвейеров контекста (RAG), созданию автономных агентов и дообучению.

Зачем AI-инженеру нужна "база" (ML и статистика)?

Несмотря на то что приложения на основе базовых моделей можно создавать, не имея познаний в области ML, понимание основ машинного обучения и статистики поможет разрабатывать более эффективные приложения и избежать ненужных сложностей. Для уверенной работы в сфере AI-инженерии необходимо разбираться в следующих понятиях:

• Концепции из области теории вероятности, такие как выборка, детерминизм и распределение.  
• Понятия из области ML, такие как обучение с учителем, обучение без учителя, логарифмическое правдоподобие, градиентный спуск, обратное распространение, функция потерь и настройка гиперпараметров.  
• Различные архитектуры нейронных сетей, включая прямое распространение, рекуррентные сети и трансформеры.  
• Метрики, такие как доля правильных ответов алгоритма, F1-мера, точность, полнота, косинусное сходство и кросс-энтропия.

Специфика данных: проблема мультиязычности

При проектировании AI-приложений критически важно учитывать, на каких данных обучалась фундаментная модель. Английский язык доминирует в Интернете. Анализ набора данных Common Crawl показывает, что он составляет почти половину данных (45,88 %). Английский в восемь раз превосходит второй по распространенности язык - русский (5,97 %).  Следом идут немецкий (5,88 %), китайский (4,87 %) и японский (4,79 %). Языки, слабо представленные в качестве обучающих данных (как правило, те, что не вошли в этот список и занимают менее 1%), считаются низкоресурсными. Это напрямую влияет на качество и логику работы AI-приложений на разных языках. 

Иллюзия простоты: от прототипа к production.

Многие разработчики попадают в ловушку быстрого старта. В сфере искусственного интеллекта действует правило: подняться от 0 до 60 легко, а от 60 до 100 - крайне трудно. Из-за первоначального успеха компании часто сильно недооценивают время, которое потребуется, чтобы улучшить продукт. Отличный пример - опыт компании LinkedIn: им потребовался месяц, чтобы достичь 80 % желаемого результата. Но затем им понадобилось еще четыре месяца, чтобы наконец превысить 95 %. Много времени было потрачено на работу над дефектами продукта и борьбу с галлюцинациями, а малая скорость достижения каждого последующего 1 % прироста сильно разочаровывала инженеров.  

Влияние AI на рынок: угроза или наставник?

Готовые AI-системы уже ломают привычные бизнес-модели. Многие образовательные организации используют AI для создания более совершенных продуктов, однако немало тех, кто считает, что AI отбирает у них работу. Например, компания Chegg, которая помогает студентам выполнять домашние задания, отметила, что цена их акций резко упала - с 28 долларов при запуске ChatGPT в ноябре 2022 года до 2 долларов в сентябре 2024-го, поскольку студенты обращаются за помощью к AI.  Если риск заключается в том, что AI может заменить многие навыки, то возможность кроется в его использовании в качестве наставника для приобретения любого умения. AI способен помочь человеку быстро освоить азы многих навыков, а затем можно продолжить заниматься самостоятельно, чтобы превзойти AI.

Откуда взялся мем про AI-разработчиков? Кто такие "оберточники" и почему в IT-сообществе смеются над AI-разработчиками?

Если вы зайдете в комментарии на Хабре, Дваче или в профильные Telegram-каналы, то быстро заметите специфическое, часто откровенно токсичное отношение к тем, кто называет себя "AI-разработчиком". В рунете популярны грубые шутки, приравнивающие создателей ИИ-приложений к людям "нетрадиционной ориентации".

Этот локальный мем возник не на пустом месте. За агрессивным юмором скрывается глубокий конфликт внутри индустрии, который строится на трех фундаментальных факторах:

1. Синдром "оберточника" и обесценивание сложной инженерии.
   Для классического бэкенд-разработчика (например, пишущего на Python) создание рабочего продукта - это долгий процесс. Нужно спроектировать архитектуру, настроить реляционную базу данных, продумать кэширование, обернуть всё это в Docker-контейнеры и настроить Linux-сервер для деплоя. Это требует фундаментальных знаний компьютерных наук и понимания того, как работает память и сеть. На этом фоне в индустрию ворвался тренд на "вайб-кодинг" (vibe-coding). Появились тысячи стартаперов, которые создают продукты, просто написав красивый фронтенд, который отправляет текстовый промт через API к серверам OpenAI (ChatGPT) или Anthropic (Claude). Таких разработчиков пренебрежительно прозвали "оберточниками" (wrapper builders). У них нет базы данных, нет своей бизнес-логики и нет бэкенда - весь их продукт является лишь тонкой графической "оберткой" над чужой нейросетью. Снобизм классических инженеров вызван тем, что написание пары API-запросов теперь модно называть громким словом "AI-инжиниринг".

2. Информационный шум и венчурный "пузырь"

   Второй фактор раздражения - колоссальная финансовая несправедливость и хайп. Инженеры, решающие действительно сложные технические задачи (построение отказоустойчивых highload-систем, оптимизация сложных SQL-запросов, обеспечение информационной безопасности), годами борются за повышение бюджетов. В то же время поверхностные "AI-агентства", состоящие из маркетологов и пары джуниоров, привлекают миллионные инвестиции под обещания "внедрить ИИ". Большинство таких проектов не имеет под собой технической ценности (никакого moat - защитного барьера) и умирает, как только OpenAI выпускает очередное обновление, встраивая функционал этого стартапа в свой базовый чат. Этот "пузырь" вызывает закономерный скепсис и раздражение у технического ядра IT-сообщества.

3. Токсичное наследие рунета и защита профессии
   Специфика русскоязычной интернет-культуры такова, что любые легковесные тренды, снижающие порог входа в профессию, встречают агрессивное сопротивление. Подобные обесцененные ярлыки - это защитный механизм сообщества. Двадцать лет назад системные программисты смеялись над веб-мастерами. Десять лет назад бэкендеры выдумывали обидные прозвища для фронтендеров ("формошлепы") и PHP-разработчиков. Недавно объектом насмешек были специалисты по No-Code и блокчейн-энтузиасты. Сегодня эстафетная палочка хейта перешла к AI-инженерам. Называя ИИ-разработчиков "нетрадиционными", классические IT-специалисты пытаются провести черту между "настоящей" инженерией и теми, кто просто удачно оседлал временный хайп.

14 крутых open-source проектов AI-приложений

Если вы хотите посмотреть, как выглядит настоящий, качественный AI-инжиниринг на практике, обратите внимание на эти репозитории GitHub (у каждого десятки тысяч звезд):

abi/screenshot-to-code - преобразует скриншоты, макеты и видео в чистый HTML/Tailwind, React или Vue с помощью Vision-моделей.

gpt-engineer-org/gpt-engineer - инструмент, генерирующий целые кодовые базы и рабочие проекты по текстовому описанию архитектуры.

open-interpreter/open-interpreter - локальная среда выполнения: модель напрямую пишет и выполняет Python/Bash-код на вашей машине для автоматизации задач и управления ОС.

sawyerhood/draw-a-ui - визуальный канвас, превращающий набросанные от руки схематичные скетчи в рабочий HTML-интерфейс.

mendableai/firecrawl - мощный AI-пайплайн, который сканирует веб-сайты и конвертирует их страницы в чистый Markdown для последующего использования в RAG и кодогенерации.

Significant-Gravitas/AutoGPT - один из самых популярных автономных мультиагентных проектов, разбивающий масштабные цели на цепочки действий.

All-Hands-AI/OpenHands (ранее OpenDevin) - открытая платформа разработки ИИ-агентов, способных самостоятельно модифицировать репозитории, читать логи компиляции и исправлять баги.

Nutlope/aicommits - CLI-утилита, анализирующая git diff и автоматически формирующая информативные сообщения для коммитов по стандартам Conventional Commits.

sweepai/sweep - автономный ассистент, превращающий проблемы (Issues) на GitHub в готовые Pull Requests с исправленным кодом и тестами.

reworkd/AgentGPT - веб-платформа для развертывания автономных настраиваемых агентов прямо в браузере для выполнения исследовательских задач.
eosphoros-ai/DB-GPT - мощный фреймворк для локального развертывания AI. Позволяет безопасно общаться с базами данных с помощью естественного языка (Text-to-SQL) без риска утечки корпоративной информации.

sqlchat/sqlchat - чат-ориентированный SQL-клиент. Инструмент предлагает использовать диалоговый интерфейс вместо громоздкого классического UI для выполнения запросов, модификации и настройки базы данных.

mckaywrigley/ai-code-translator - легковесный инструмент на основе языковых моделей, который берет исходный код на одном языке программирования и автоматически переводит его на другой (отлично подходит для переписывания легаси-проектов).

joshpxyne/GPT-Migrate - AI-агент, предназначенный для автоматизации масштабной миграции целых кодовых баз. Анализирует структуру репозитория и может пошагово переносить бэкенд с одного языка или фреймворка на другой.

FAQ: Расширенный словарь терминов AI- и ML-инженера

Чтобы окончательно разобраться в специфике современной ИИ-разработки, вот краткая расшифровка главных отраслевых терминов:

• Что такое RAG (Retrieval-Augmented Generation)?
  Это архитектурный подход, при котором языковая модель перед генерацией ответа сначала ищет нужные факты во внешней базе данных (например, во внутренней документации компании). Грубо говоря, это способ дать ИИ "прочитать" ваши личные документы, чтобы он отвечал строго по ним и не придумывал факты.
• Что такое Эмбеддинги (Embeddings)?
  Это способ перевода текста, изображений или звука в массивы чисел (векторы). Эмбеддинги позволяют алгоритмам математически вычислять "смысловую близость" слов. Благодаря им база данных понимает, что слова "собака" и "щенок" находятся близко друг к другу, а "собака" и "швеллер" - далеко.
• Что такое MLOps (Machine Learning Operations)?
  Это аналог классического DevOps, но адаптированный для систем машинного обучения. MLOps-инженеры настраивают автоматизацию, CI/CD-пайплайны, мониторинг и бесперебойный деплой нейросетей на серверы.
• Что такое Галлюцинации ИИ?
  Ситуация, когда языковая модель генерирует грамматически правильный и очень уверенный, но абсолютно ложный или выдуманный ответ. Борьба с галлюцинациями - одна из главных задач AI-инженеров при подготовке продукта к релизу.
• Что такое LoRA и PEFT?
  Обучение огромных моделей (вроде GPT) с нуля требует гигантских вычислительных мощностей и суперкомпьютеров. PEFT (Parameter-Efficient Fine-Tuning) и в частности LoRA - это методы "дешевого" дообучения. Они позволяют слегка скорректировать поведение модели под вашу конкретную задачу, обновив лишь крошечную долю её параметров, что можно сделать даже на одной хорошей потребительской видеокарте.
• Что такое "Вайб-кодинг" (Vibe-coding)?
  Новый сленговый термин. Означает процесс написания программ, когда разработчик не пишет код руками по строчкам, а пишет промты на естественном языке. Человек задает общий "вайб" и логику архитектуры, а рутинную генерацию синтаксиса делегирует агентам или инструментам вроде Cursor и GitHub Copilot.

1. Данные и характер работы систем

• Детерминированный / закрытый вывод
  Свойственен классическому машинному обучению (ML). На один и тот же входной набор данных алгоритм всегда выдает один и тот же результат из строго заданного набора. Результатом является класс (например, спам / не спам) или конкретное число (предсказание цены).
• Вероятностный / открытый вывод
  Свойственен генеративному ИИ (AI-инженерия). Модель не знает точного ответа, а математически предсказывает вероятности следующих токенов. Выходные данные ничем не ограничены - это генерация текста, рабочего программного кода или изображений. На один и тот же запрос при разных генерациях можно получить разные результаты.
• Разметка и табличные данные
  Классический формат данных для ML - реляционные таблицы (как в базах SQL), где каждая строка имеет известную целевую переменную (разметку). Например, база квартир, где известны площадь, район и точная цена продажи.
• Неструктурированные данные и Векторные БД
  То, с чем работает современный ИИ: сырые тексты статей, логи, изображения, аудио. Чтобы нейросеть могла искать информацию по таким данным, они превращаются в векторы (эмбеддинги) и сохраняются в специализированные векторные базы данных (например, Qdrant, Milvus), заточенные под быстрый поиск по смыслу, а не по ключевым словам.
• Feature engineering (Конструирование признаков)
  Ручной аналитический процесс в классическом ML. Инженер берет сырые данные и с помощью математики и логики создает из них новые признаки, чтобы помочь алгоритму. Пример: из столбца "дата рождения" вычислить новый признак "возраст в днях". В современном AI нейросети извлекают нужные признаки из контекста самостоятельно.

2. Базовые концепции обучения и статистики

• Выборка, детерминизм и распределение
  Базовые понятия теории вероятностей. Выборка - часть данных из генеральной совокупности, на которой мы обучаем или тестируем модель. Детерминизм - строгая предсказуемость результата алгоритма. Распределение - описание того, с какой частотой и вероятностью в данных появляются те или иные значения.
• Обучение с учителем (Supervised) и без учителя (Unsupervised)
  В первом случае алгоритм учится на примерах, где заранее дан правильный ответ (человек разметил, где на фото коты, а где собаки). Во втором случае алгоритм получает сырые данные без подсказок и сам ищет в них скрытые закономерности (например, разбивает пользователей на кластеры по поведению).
• Градиентный спуск и Обратное распространение (Backpropagation)
  Градиентный спуск - математический алгоритм оптимизации. Он шаг за шагом корректирует веса (настройки) нейросети, чтобы минимизировать ошибку (как бы "спускаясь" на дно ямы, где ошибка равна нулю). Обратное распространение - механизм, позволяющий сети понять, какой именно нейрон на предыдущем слое совершил ошибку, чтобы скорректировать его вес.
• Функция потерь (Loss) и Логарифмическое правдоподобие
  Математические формулы, которые оценивают качество работы модели в процессе обучения. Функция потерь вычисляет, насколько сильно предсказание нейросети отклонилось от идеала. Логарифмическое правдоподобие оценивает вероятность того, что модель выдаст реальные, правильные данные.
• Гиперпараметры
  В отличие от внутренних параметров (весов), которые нейросеть настраивает сама в процессе обучения, гиперпараметры задает сам разработчик до старта (например, сколько слоев будет в сети, с какой скоростью ей учиться).

3. Архитектуры нейронных сетей

• Прямое распространение (Feedforward)
  Самый базовый тип нейросетей. Сигнал идет строго в одном направлении: от входного слоя к выходному. Не имеют памяти, поэтому плохо подходят для понимания текста.
• Рекуррентные сети (RNN)
  Архитектура, обладающая своеобразной "памятью". Они обрабатывают данные последовательно (слово за словом), поэтому их долгое время использовали для машинного перевода. Их минус - они забывают контекст, если текст слишком длинный.
• Трансформеры (Transformers)
  Архитектура, совершившая революцию и подарившая нам ChatGPT. Благодаря механизму "внимания" (Attention), трансформер анализирует все слова в тексте одновременно. Он мгновенно понимает логические связи между первым и тысячным словом в документе, не теряя контекст.

4. Метрики оценки качества моделей

• Accuracy (Доля правильных ответов) - самый простой показатель: процент верных предсказаний от общего числа.
• Precision (Точность) - показывает, сколько из тех объектов, что модель назвала положительными, реально являются таковыми (минимизация ложных срабатываний).
• Recall (Полнота) - показывает, какую долю из всех реальных положительных объектов модель смогла найти (минимизация пропусков).
• F1-мера - сбалансированная метрика, представляющая собой среднее гармоническое между Точностью и Полнотой.
• Кросс-энтропия - метрика потерь в задачах классификации (например, при предсказании следующего слова), измеряющая разницу между предсказанием сети и реальностью.
• Косинусное сходство - математическая мера, показывающая, насколько два вектора направлены в одну сторону. В AI используется для оценки смысловой близости текстов (чем ближе показатель к 1, тем больше похож смысл).

5. Популярный стек технологий

• Python - безоговорочный язык №1 в индустрии машинного обучения и AI.
• PyTorch - самый популярный открытый фреймворк для создания и обучения глубоких нейронных сетей.
• Scikit-learn - классическая библиотека Python для базового машинного обучения (регрессии, деревья решений), используемая в традиционном ML-инжиниринге.
• LangChain и LlamaIndex - мощные Python-фреймворки оркестрации для AI-инженеров. С их помощью пишут логику AI-агентов, настраивают RAG (подключают нейросети к корпоративным базам данных) и управляют памятью ботов.
• vLLM - высокопроизводительная библиотека для быстрого инференса (запуска и обработки запросов) больших языковых моделей на серверах. Позволяет экономить ресурсы видеокарт.

Сегодня расскажу историю о том, как я до 4 часов ночи пытался восстановить обычное VNC-соединение между двумя ПК на Windows 11. Спойлер: виновником торжества оказалось основное сетевое оборудование, но по пути пришлось столкнуться с логикой Microsoft и обновить систему до Pro-версии + попутно решая проблему, с сайтом riopass.ru, который не работал по причине магистральных блокировок.

Сначала в ход пошла моя классическая база. Было обновлено ПО на обеих сторонах с нуля (RealVNC Viewer на клиенте и TightVNC Server на хосте). Настройка сервера, смена паролей, полное отключение брандмауэра Windows и антивирусов, проброс 5900 порта и приложения в брэндмауэре - результата ноль. Не помогла даже перезагрузка.
Далее я исключил промежуточное сетевое оборудование (на котором была какая то защита от spoofing'а) и соединил ПК напрямую интернет-кабелем. Удивительно, но и это не решило проблему.

RDP и ключи с ggsel, ну нафига?

Раз VNC сдался, я решил зайти через RDP. Но для этого нужна Windows 11 Pro. В ходе ночных экспериментов на ggsel за копейки был куплен ключ с привязкой к аккаунту Microsoft (Retail).

Интересный момент: в инструкции к ключу было строго указано, что обновить OEM-версию Home до Pro не выйдет, но у меня всё успешно обновилось. А вот дальше начались проблемы с экосистемой Microsoft.
Оказалось, что подключиться по RDP к компу с официальным аккаунтом Microsoft (в формате MicrosoftAccount\your@mail.ru) - тот еще квест. Система не пускает из-за особенностей работы модуля TPM и ПИН-кодов Windows Hello. Даже если отключить ПИН-код и оставить только вход по паролю, RDP может выдавать ошибку авторизации. Чтобы всё завелось, пришлось заходить в аккаунт, сбрасывать пароль и отключать требование входа только через Windows Hello. Но и это не помогло! RDP работает только с локальной или корпоративной утечкой! В итоге пришлось подключаться с локальной учеткой... Azure ID у меня нету :)
 

Магия Wi-Fi и китайских роутеров.

После всех манипуляций, ради эксперимента подключил этот проблемный мини-ПК по Wi-Fi. И - о чудо! - моментально заработали и RDP, и VNC.
Далее я вернулся к проводному соединению, вручную изменил статический IP-адрес на роутере через Mi Home, и доступ снова появился. Правда, радость была недолгой: отвалился сетевой диск. При попытке его подключить система выдавала таймаут, зависал проводник и у меня почему то вернулось OneDrive, а ранее работавшие адреса перестали пинговаться. В итоге помогла только полная перезагрузка того ПК, с которого я инициировал подключение.

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

Сложив всю картину воедино, стало ясно, что корнем всех бед оказался роутер Xiaomi. То, как в нем реализована связка MAC/IP, как происходит согласование таблиц маршрутизации и почему он хаотично изолирует часть портов и клиентов друг от друга, - останется загадкой навсегда, наверное даже для китайцев которые написали прошивку для этого роутера. Из-за его зависших таблиц прямой кабель изначально тоже не работал, так как сетевой интерфейс ПК не мог корректно обновить данные.

Суть этой истории такова:

• Будьте осторожны с недорогими китайскими роутерами. Иногда они ведут себя абсолютно непредсказуемо в плане фильтрации трафика, подкидывая проблемы там, где их быть не должно.
• Старое доброе правило "выключить и включить" всё ещё актуально, особенно если непонятно, на каком этапе застрял пакет.
• Идеальных систем не существует. Несовершенно всё: от китайского роутера за полторы тысячи рублей до логики работы сервисов огромной корпорации вроде Microsoft.

P.S. Почему я отдельно упомянул Microsoft? Ещё давно, мой аккаунт просто улетел в блокировку за "подозрительную активность". При попытке зайти на сайт microsoft.com для авторизации система начала навязчиво требовать создание ключей TPM (Passkeys), хотя они уже были созданы ранее. Из-за этого происходил замкнутый круг и постоянно вылетала ошибка.
В итоге пришлось отказаться от входа по ПИН-коду, запрашивать одноразовый код на почту и сбрасывать пароль. Только чудом зайдя в аккаунт таким способом, я добился того, что всё заработало. И, как оказалось, никакие ключи заново создавать на самом деле было не нужно это не доработка Microsoft, когда Windows обновился с Home на Pro.

Чистый интернет во всей домашней сети, блокировка мобильной рекламы, защита от трекеров и полное скрытие DNS-запросов от провайдера - всё это можно реализовать силами одной лишь Raspberry Pi или другим устройством на Linux.

Долгое время королем сетевой блокировки считался Pi-hole, но сегодня индустрия двинулась дальше. AdGuard Home - более современное решение: оно написано на Go, работает "из коробки" с шифрованием (DoH, DoT, DoQ) и поддерживает мощный Adblock-синтаксис фильтров.

В этой статье мы разберем, как правильно развернуть AdGuard Home в Docker на Raspberry Pi, как решить частую проблему занятого 53-го порта (особенно если у вас стоят другие сервисы вроде v2rayA/Xray) и как правильно настроить систему для RU-сегмента.

Подготовка: Решаем проблему 53-го порта

Главная сложность при установке любого DNS-сервера в Docker - борьба за порт 53. Этот порт необходим для работы DNS, но в современных дистрибутивах Linux (включая Raspberry Pi OS и Ubuntu) он часто уже занят системным резолвером (systemd-resolved), встроенным dnsmasq или прокси-глушилками (например, движком Xray).

Перед стартом проверим, свободен ли порт. Выполните команду в терминале малинки:

sudo ss -tulpn | grep :53

Сценарий 1: Порт занят службой systemd-resolved

Если в выводе вы увидели этот процесс, его нужно отключить, чтобы освободить порт для Docker:

sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved
sudo rm /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf

Сценарий 2: Порт частично занят другими сервисами (Xray, VPN, dnsmasq)

Если вы увидели, что на порту 53 висят другие важные службы (например, на локальных адресах 127.2.0.17 или 10.42.0.1), отключать их нельзя - это сломает ваши туннели или внутреннюю сеть.

Решение: Мы заставим AdGuard Home слушать порт 53 только на основном IP-адресе вашей Raspberry Pi, который смотрит в домашнюю сеть.

Узнайте локальный IP-адрес малинки:

hostname -I

(Допустим, ваш адрес 192.168.1.50. Запомните его, он пригодится при написании Docker Compose).

Шаг 1: Развертывание через Docker Compose (Предполагается, что у Вас уже установлен и настроен Docker)

Создадим отдельную директорию для проекта и конфигурационный файл:

mkdir -p ~/adguard && cd ~/adguard
nano docker-compose.yml

Вставьте в файл следующий конфиг. Внимание: замените 192.168.1.50 на реальный IP-адрес вашей Raspberry Pi!

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    ports:
      # Привязываем DNS к конкретному IP малинки, чтобы избежать конфликтов
      - "192.168.1.50:53:53/tcp"
      - "192.168.1.50:53:53/udp"
      # Веб-панель управления
      - "80:80/tcp"
      # Порт для первичной инициализации      
      - "3000:3000/tcp"  
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

Сохраните файл (Ctrl+O, затем Enter) и закройте редактор (Ctrl+X).

Запускаем контейнер:

docker compose up -d

Шаг 2: Первичная настройка AdGuard Home

Откройте браузер и перейдите по адресу: http://<IP_ВАШЕЙ_МАЛИНКИ>:3000.

Перед вами откроется приветственный мастер установки:

1. Веб-интерфейс: Оставляйте "Все интерфейсы" и порт 80.

2. DNS-сервер: Оставляйте "Все интерфейсы" и порт 53.

   Примечание: Внутри контейнера AdGuard должен слушать всё, Docker сам перенаправит трафик с внешнего IP на внутренний.

3. Нажмите Далее, придумайте логин и надежный пароль для администратора.

После завершения панель управления станет доступна по обычному адресу: http://<IP_ВАШЕЙ_МАЛИНКИ>.

Шаг 3: Настройка шифрования (DNS-over-HTTPS / QUIC)

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

• В панели управления перейдите в Настройки -> Настройки DNS.

• В поле Апстрим DNS-серверы удалите всё и вставьте этот список быстрых и зашифрованных серверов:

  https://dns.cloudflare.com/dns-query
  quic://dns.adguard-dns.com
  tls://dns.quad9.net
  https://dns.google/dns-query

• Ниже в режиме маршрутизации выберите "Параллельные запросы" - AdGuard будет опрашивать все серверы одновременно и выбирать самый быстрый ответ. Это ускорит загрузку сайтов.

• В поле Серверы начальной загрузки (Bootstrap DNS) вставьте обычные IP-адреса. Они нужны системе только для того, чтобы в первый раз узнать координаты зашифрованных серверов:

  9.9.9.10
  149.112.112.10
  2620:fe::10
  2620:fe::fe:10
  1.1.1.1
  1.0.0.1
  8.8.8.8
  9.9.9.9

• Нажмите Проверить апстримы и, если всё ок, нажмите Применить.

Шаг 4: Подключаем лучшие фильтры для рунета (и где искать пропавшие списки)

Чтобы не перегружать оперативную память Raspberry Pi и не вызывать "поломку" нормальных сайтов, списки блокировок нужно подбирать аккуратно. В последних версиях AdGuard Home разработчики сильно почистили встроенные каталоги.

Перейдите в Фильтры -> Черные списки DNS -> Добавить черный список

Рекомендуемый сбалансированный набор:

• Общие: AdGuard DNS filter (включен по умолчанию, отлично режет базовую рекламу и трекеры) и OISD Blocklist Full (идеальный агрегатор без ложных срабатываний)..
• Региональные: AdGuard Russian filter и RU AdList (без них реклама Яндекса, Mail.ru и локальных сетей будет пролетать).
• Безопасность: Phishing URL Blocklist (PhishTank and OpenPhish), Malicious URL Blocklist (URLhaus) (Они надежно защитят домашнюю сеть от фишинга и вирусов.), WindowsSpyBlocker (глушит телеметрию Windows, не ломая обновления системы).

Куда пропал список для России и защита от трекеров?

Если вы не нашли в меню "Региональные" привычный российский фильтр - не пугайтесь. Дело в том, что разработчики AdGuard перенесли все актуальные DNS-блокировки для России (и правила против трекеров) прямо в базовый AdGuard DNS filter. Технически, вы уже защищены от отечественной рекламы "из коробки".

Как добавить кастомные списки вручную (Для продвинутых):

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

• Для блокировки телеметрии Windows 10/11 (без поломки обновлений):
  • Название: WindowsSpyBlocker
  • URL: https://raw.githubusercontent.com/crazy-max/WindowsSpyBlocker/master/data/hosts/spy.txt
• Для жесткой блокировки Яндекс.Метрики, Mail.ru и тизерных сетей:
  • Название: RU AdList
  • URL: https://easylist-downloads.adblockplus.org/advblock.txt

Нажмите "Сохранить", и AdGuard сам скачает актуальные правила.

Заключение: Направляем трафик

Теперь, когда ваш персональный DNS-сервер готов, нужно направить на него трафик.

У вас есть два пути:

1. Для всего дома: Зайдите в настройки вашего домашнего роутера, найдите параметры DHCP и в поле Primary DNS (Основной DNS) введите IP-адрес вашей Raspberry Pi. Перезагрузите роутер. Теперь все устройства (телефоны, ТВ, ноутбуки) защищены автоматически.
2. Для одного устройства: Если не хотите трогать роутер, зайдите в сетевые настройки конкретного ПК или смартфона и укажите IP малинки в качестве DNS вручную.

Что в итоге?

Вы получили полный контроль над своим сетевым трафиком. Вкладка "Журнал запросов" в AdGuard Home наглядно покажет, какие устройства и куда пытаются "стучаться" в фоновом режиме. Если какой-то нужный вам сайт или банк случайно заблокируется - вы сможете внести его в белый список прямо из лога в один клик.

Часто задаваемые вопросы (FAQ)

Почему AdGuard Home не блокирует рекламу внутри видео на YouTube, VK или Rutube?

Потому что эти платформы используют технологию серверной вклейки рекламы (SSAI - Server-Side Ad Insertion). Рекламные ролики и основное видео склеиваются на серверах корпораций и отдаются на ваше устройство с одного и того же домена единым зашифрованным потоком. DNS-фильтр работает на уровне доменов: он либо заблокирует весь видеопоток целиком, либо пропустит его вместе с рекламой. Для блокировки in-stream рекламы вам всё еще понадобятся браузерные расширения (например, uBlock Origin) или модифицированные клиенты (ReVanced).

У меня перестал открываться нужный сайт (Сбербанк, Госуслуги, Кинопоиск). Как починить?

Такое иногда случается - это типичное "ложное срабатывание" одного из черных списков. Не паникуйте! Откройте веб-панель AdGuard Home, перейдите в раздел "Журнал запросов". Найдите там свежую красную строчку с заблокированным доменом вашего сервиса и просто нажмите кнопку "Разблокировать". Сайт моментально заработает.

Что произойдет, если Raspberry Pi зависнет или я выдерну ее из розетки?

Это важный нюанс, о котором нужно помнить. Если вы указали малинку в настройках роутера как единственный DNS-сервер для всего дома, то при её отключении у всех устройств в квартире "пропадет" интернет. Сайты просто перестанут открываться (хотя мессенджеры по прямым IP могут работать). Если вы планируете выключить сервер надолго, не забудьте вернуть в настройках роутера автоматическое получение DNS от провайдера.

Что будет, если дома отключится электричество? Придется ли запускать всё заново?

Нет. В конфигурации нашего Docker-файла прописано правило restart: unless-stopped. Это значит, что как только Raspberry Pi получит питание и загрузится, AdGuard Home запустится автоматически, и интернет у всех устройств в доме восстановится.

Можно ли использовать AdGuard Home одновременно с VPN или обходом DPI (например, v2rayA / Xray)?

Да, они прекрасно работают на одном сервере. Более того, это классическая связка для современного домашнего сервера. Главное правило - грамотно настроить порты (как описано в нашей инструкции), чтобы движок VPN и Docker-контейнер с AdGuard не пытались одновременно занять 53-й порт на всех сетевых интерфейсах. Привязка AdGuard к локальному IP-адресу полностью решает эту проблему.

Глоссарий терминов

• DNS (Domain Name System) - "телефонная книга" интернета. Переводит понятные человеку адреса (например, riopass.ru) в числовые IP-адреса серверов (например, 192.168.1.1), которые понимают компьютеры.
• Апстрим DNS (Upstream DNS) - вышестоящий сервер в интернете. Когда вы вводите адрес сайта, а ваш домашний AdGuard Home не знает его IP-адреса, он обращается именно к апстрим-серверам (например, к серверам Cloudflare или Google) за ответом.
• Серверы начальной загрузки (Bootstrap DNS) - обычные, нешифрованные серверы (например, 1.1.1.1). Они нужны вашему AdGuard только в самую первую секунду работы: чтобы перевести буквенный адрес шифрованного апстрим-сервера (типа dns.cloudflare.com) в цифры и установить с ним защищенное соединение.
• DNS-over-HTTPS (DoH) / DNS-over-QUIC (DoQ) - современные протоколы шифрования. Заворачивают ваши DNS-запросы в непроницаемый криптографический туннель. Благодаря им ваш интернет-провайдер не видит, на какие сайты вы заходите, и не может подменить ответ (например, выдать страницу-заглушку о блокировке).
• Порт 53 - стандартная "дверь" в сетевом оборудовании, через которую проходит весь нешифрованный DNS-трафик.
• DHCP (Dynamic Host Configuration Protocol) - служба на вашем домашнем роутере, которая автоматически раздает IP-адреса и настройки сети (включая адрес нашего нового DNS-сервера) всем подключающимся телефонам, телевизорам и компьютерам.
• Docker / Docker Compose - система контейнеризации. Позволяет запускать программы (например, AdGuard Home) в изолированной среде со всеми необходимыми зависимостями, чтобы они не конфликтовали с основной операционной системой (Raspberry Pi OS).
• systemd-resolved - встроенная в Linux системная служба для управления сетевыми именами. Часто является главной головной болью при настройке собственных DNS-серверов, так как намертво занимает порт 53.
• v2rayA / Xray - мощные современные инструменты для маршрутизации трафика и обхода систем глубокого анализа пакетов (DPI). Часто устанавливаются на тот же сервер, что и AdGuard Home, для создания комплексного домашнего шлюза.
• SSAI (Server-Side Ad Insertion) - серверная вклейка рекламы. Технология, из-за которой AdGuard Home и другие сетевые блокировщики не могут вырезать рекламу внутри видеороликов на YouTube или VK Video. Видео и реклама отдаются с одного домена единым зашифрованным потоком.
• Ложные срабатывания (False Positives) - ситуация, когда из-за слишком агрессивных списков фильтрации под блокировку попадает полезный домен. Из-за этого может сломаться верстка сайта или перестать работать авторизация в приложении банка.
• Локальный IP-адрес - внутренний адрес устройства в вашей домашней сети (обычно начинается на 192.168.x.x или 10.x.x.x). Доступ к нему есть только у устройств, подключенных к вашему домашнему Wi-Fi, из интернета напрямую до него не добраться.

Сегодня мы разберем одно из самых удобных решений для селф-хостинга - установку Outline VPN. Он работает на базе зашифрованного протокола Shadowsocks, который изначально создавался для обхода Великого китайского файрвола. Главный плюс Outline - невероятно простое управление доступом для всех ваших устройств, семьи и друзей через удобный графический интерфейс.

Что такое Outline, кому он принадлежит и почему это надежно?

Outline - это не просто очередное VPN-приложение, а проект с открытым исходным кодом, который разрабатывается Jigsaw - технологическим инкубатором внутри корпорации Google (Alphabet). Изначально Outline создавался специально для журналистов, правозащитников и новостных организаций, чтобы обеспечить им безопасный доступ к информации в странах с жесткой интернет-цензурой.

Почему Outline считается надежным и безопасным:

•  Протокол маскировки: В основе Outline лежит протокол Shadowsocks. Он не просто шифрует данные, но и маскирует их. Для систем блокировок (DPI) ваш трафик выглядит не как VPN-соединение, а как обычный, нечитаемый "белый шум". Это позволяет успешно обходить даже "Великий китайский файрвол".
• Независимый аудит: Поскольку код проекта полностью открыт (Open Source), его регулярно проверяют независимые компании в сфере кибербезопасности (например, Radically Open Security и Cure53). В нем нет скрытых "бэкдоров".
• Отсутствие логов (No-logs policy): Outline Manager и серверная часть технически не собирают и не хранят историю ваших веб-запросов. Вы контролируете свой сервер, и никто (даже Google) не имеет доступа к вашему трафику. Менеджер собирает лишь статистику объема переданных мегабайт, чтобы вы могли контролировать лимиты.

Скриншот приложения клиента:

Задача 1: Аренда сервера (VPS)

Для начала нам нужен виртуальный сервер за пределами РФ (не у хостера, который аффилирован с российскими компаниями или имеет российские стыки. Это не паранойя - это реальная техническая проблема, и она влияет и на приватность, и на обход блокировок, и на SEO‑репутацию IP).

• Локация: Для пользователей из РФ идеальный баланс между пингом и стабильностью дают Германия, Нидерланды или Швеция. Выберите любого удобного зарубежного хостинг-провайдера (Hetzner, DigitalOcean, Vultr, Linode, OVHcloud или проверенных посредников).

  Можем посоветовать реселлера koara.io :

  Можете использовать нашу реферальную ссылку: https://koara.cloud/?from=1893 

  Промокод: sale_1893

•    Тариф: Арендуйте самый дешевый тариф (обычно хватает 1 vCPU и 1-2 GB RAM).
•    Операционная система: Строго чистая Ubuntu 22.04 (и выше) или Debian 12 (и выше).
•    Виртуализация: Строго KVM.

После оплаты хостер выдаст вам IP-адрес сервера и пароль пользователя root.

Задача 2: Базовая безопасность сервера (Отказ от паролей)

Оставлять сервер с доступом по паролю в интернете - плохая идея. Его начнут атаковать боты-брутфорсеры в первые же минуты. Мы настроим доступ по криптографическому SSH-ключу.

Откройте PowerShell (если у вас Windows) или терминал (Linux/macOS) и выполните следующие шаги:

0. Первая кровь - смена пароля root

Подключитесь к серверу через терминал:
ssh root@ВАШ_IP

Введите команду passwd для смены пароля.

Важно: Не используйте простые слова. Мы рекомендуем генерировать пароль длиной не менее 13 символов. Для создания надежного пароля воспользуйтесь генератором на нашем сайте https://riopass.ru/. Такой пароль методом брутфорса будут взламывать десятилетиями.

На домашнем ПК:

1. Генерация ключа:

   Введите команду:

   ssh-keygen -t ed25519 -f "$HOME\.ssh\vpn_key" -C "outline-server"

   Нажмите дважды Enter, когда система попросит ввести пароль (passphrase). В вашей папке .ssh появятся два файла: vpn_key (ваш секретный ключ) и vpn_key.pub (публичный ключ для сервера).

2. Копирование публичного ключа на сервер:

   Выведите содержимое публичного ключа на экран и скопируйте его:

   cat "$HOME\.ssh\vpn_key.pub"

   Теперь подключитесь к вашему новому серверу по паролю, который дал хостер:
   ssh root@ВАШ_IP_АДРЕС

   Cоздайте папку для ключей и запишите туда скопированный ключ:

   mkdir -p ~/.ssh
   chmod 700 ~/.ssh
   nano ~/.ssh/authorized_keys

   Вставьте ваш ключ (ssh-ed25519...) в редактор, сохраните файл (Ctrl+O, Enter, Ctrl+X) и выдайте права:
   chmod 600 ~/.ssh/authorized_keys

3. Отключение входа по паролю:

   Теперь скажем серверу пускать только владельца ключа. Откройте конфигурацию SSH:

   nano /etc/ssh/sshd_config

   Найдите и измените следующие строки:

   PasswordAuthentication no
   PermitRootLogin prohibit-password
   KbdInteractiveAuthentication no

   Перезапустите службу SSH, чтобы применить настройки:

   systemctl restart ssh

   Готово! Ваш сервер теперь защищен.

Задача 3: Установка Outline VPN

Архитектура Outline состоит из двух программ: Manager (для управления сервером на вашем ПК) и Client (для подключения к VPN на телефоне или ПК).

1. Подготовка Outline Manager:

   1. Скачайте Outline Manager с официального сайта (getoutline.org) и установите на свой компьютер. Если сайт блокируется, то перейдите в официальный репозиторий на GitHub

      Прямо на главной странице в описании (файл README.md) собраны прямые ссылки на загрузку Outline Manager (для Windows, macOS, Linux) и Outline Client для всех платформ.

   2. Откройте программу и выберите плитку "Настроить Outline где угодно" (Set up Outline anywhere).
   3. Программа выдаст вам длинную команду, которая начинается с sudo bash -c .... Скопируйте её
2. Установка на сервер:
   1. Вернитесь в терминал (PowerShell), где вы подключены к вашему серверу.

   2. Вставьте скопированную команду и нажмите Enter.

      Примечание: Если скрипт спросит, установить ли Docker, соглашайтесь (нажмите Y и Enter).

   3. Установка займет пару минут. В конце терминал выдаст зеленый текст — это ваши конфигурационные данные (API URL и сертификат), которые выглядят примерно так: {"apiUrl":"https://...","certSha256":"..."}. Скопируйте весь этот блок.

3. Привязка сервера к Менеджеру:

   1. Вернитесь в Outline Manager.
   2. Вставьте скопированный из терминала зеленый блок во второе поле ввода и нажмите "Готово".

   Сервер настроен! Теперь перед вами панель управления вашим VPN.

Этап 4: Подключение устройств и раздельное туннелирование

Создание ключей и подключение:

1. В Outline Manager нажмите "Добавить новый ключ". Вы можете переименовать его (например, "Мой iPhone" или "Ноутбук жены").

   

2. Нажмите кнопку "Поделиться" рядом с ключом. Скопируйте полученный код доступа (начинается на ss://...). Но не забудьте про ПРЕФИКСЫ - https://riopass.ru/tips/117/ без них могут блокировать соединение.
3. Скачайте приложение Outline Client на ваш телефон (из Google Play / App Store) или компьютер.

Чтобы безопасно подключиться к интернету, используйте этот сервер.

1. Скачайте и установите на устройство приложение Outline:

iOS: https://itunes.apple.com/app/outline-app/id1356177741
macOS: https://itunes.apple.com/app/outline-app/id1356178125
Windows: https://s3.amazonaws.com/outline-releases/client/windows/stable/Outline-Client.exe
Linux: https://support.getoutline.org/client/getting-started/install-linux/
Android: https://play.google.com/store/apps/details?id=org.outline.android.client
Дополнительная ссылка для Android: https://s3.amazonaws.com/outline-releases/client/android/stable/Outline-Client.apk

2. Получите ключ доступа, который начинается с ss://, а затем скопируйте его.

3. Откройте клиент Outline. Если ваш ключ доступа определился автоматически, нажмите "Подключиться". Если этого не произошло, вставьте ключ в поле и нажмите "Подключиться".

Теперь у вас есть доступ к свободному интернету. Чтобы убедиться, что вы подключились к серверу, введите в Google Поиске фразу "Какой у меня IP-адрес". IP-адрес, указанный в Google, должен совпадать с IP-адресом в клиенте Outline.

Дополнительные сведения можно найти на странице https://getoutline.org/.

Откройте Client. Он автоматически распознает скопированный ключ из буфера обмена. Нажмите "Добавить сервер" и затем "Подключить". И не забудьте про ПРЕФИКСЫ - https://riopass.ru/tips/117/ 

Раздельное туннелирование (Split Tunneling):

В отличие от Amnezia, десктопный клиент Outline пропускает через VPN весь трафик устройства по умолчанию.

Поздравляем! Теперь у вас есть собственный, надежный VPN. Остались вопросы? Пишите на почту техподдержки riopass.ru, разберем любые ошибки!

FAQ: Частые вопросы и решение проблем

В: Провайдер всё-таки заблокировал мой Outline. Подключение идет, но интернета нет. Что делать?
О: Протокол Shadowsocks, на котором базируется Outline, иногда подвергается ковровым блокировкам со стороны ТСПУ (особенно во время массовых ограничений). Роскомнадзор может блокировать конкретный порт на вашем сервере.

• Решение: Зайдите в Outline Manager, нажмите на настройки сервера и измените "Порт для новых ключей доступа" на случайный (например, 8443, 443 или любой от 1024 до 65535). После этого создайте новый ключ доступа для своего устройства — часто это полностью решает проблему.

В: Можно ли поделиться своим VPN с семьей или друзьями?
О: Да, и Outline создан именно для этого! Вы можете создать десятки независимых ключей в Outline Manager. Вы будете видеть, сколько гигабайт трафика потратил каждый пользователь, и сможете удалить ключ в один клик.
Но помните: Чем больше людей одновременно качают тяжелые файлы через ваш единственный IP-адрес, тем выше риск привлечь внимание систем блокировки. Делитесь доступом с умом.

В: Скорость через VPN сильно упала. Как исправить?
О: Ваш магистральный провайдер пытается "зашейпить" (искусственно ограничить) трафик. Попробуйте сменить порт в настройках сервера (как описано выше) или перевыпустить ключи. Если это не помогает регулярно, возможно, вам стоит рассмотреть установку протокола Xray/Reality (см. нашу инструкцию по Amnezia VPN).

В: Почему периодически обрывается прямое подключение к серверу по SSH?
О: Чаще всего это банальный таймаут - сервер сам разрывает соединение из-за долгого бездействия (если вы ничего не вводите в консоль). Если падает активное подключение, это может означать, что провайдер видит факт SSH-соединения с зарубежным IP и обрывает его. В тяжелых случаях поможет смена хостинг-провайдера на менее "засвеченного" у систем фильтрации.

В: Мой российский провайдер увидит, какие сайты я посещаю через Outline?
О: Нет. Провайдер будет видеть только то, что вы передаете нечитаемый зашифрованный поток данных на неизвестный зарубежный IP-адрес. Ваши DNS-запросы, история посещений и скачанные файлы надежно спрятаны.

Глоссарий

• VPS (Virtual Private Server): Виртуальный выделенный сервер. Грубо говоря, это изолированная часть мощного компьютера (сервера) в дата-центре, которую вы арендуете и полностью контролируете.
• SSH (Secure Shell): Сетевой протокол, позволяющий безопасно подключаться к удаленному серверу и управлять им с помощью текстовых команд в терминале.
• Shadowsocks: Открытый протокол шифрования данных, изначально разработанный в Китае для обхода государственной цензуры. В отличие от классических VPN, он маскирует трафик под обычное HTTPS-соединение.
• DPI (Deep Packet Inspection): Технология глубокого анализа сетевых пакетов. Провайдеры используют её для проверки того, какие именно данные вы передаете, чтобы блокировать неугодные протоколы и сайты.
• ТСПУ (Технические средства противодействия угрозам): Оборудование, которое Роскомнадзор обязывает устанавливать всех российских провайдеров. Именно эта "черная коробка" занимается фильтрацией (DPI) и блокировкой сайтов.
• Раздельное туннелирование (Split Tunneling): Настройка, позволяющая пустить часть интернет-трафика (например, заблокированные сайты) через VPN, а другую часть (например, банковские приложения) - напрямую через вашего провайдера.
• Брутфорс (Brute-force): Хакерский метод угадывания паролей путем их сплошного автоматического перебора. Именно поэтому мы отключили вход по паролю в Задаче 2.
• Docker: Программная платформа, которая упаковывает приложения (в нашем случае серверную часть Outline) и все их зависимости в изолированные контейнеры. Это позволяет легко развернуть VPN на сервере одной командой, не засоряя саму операционную систему.
• KVM (Kernel-based Virtual Machine): Технология аппаратной виртуализации, позволяющая создать на сервере полностью изолированную виртуальную машину со своим ядром ОС. В отличие от более дешевой технологии контейнеризации (например, OpenVZ), KVM гарантирует, что Docker и Outline будут работать без сбоев.
• Open Source (Открытый исходный код): Модель разработки программного обеспечения, при которой любой желающий (в том числе независимые аудиторы безопасности) может посмотреть, как написан код программы. Это гарантия того, что в приложении нет скрытых шпионских модулей.
• Ping (Пинг): Время в миллисекундах, за которое пакет данных доходит от вашего компьютера до сервера и возвращается обратно. Чем он ниже, тем отзывчивее будет интернет через VPN.
• Root: Главный администратор (суперпользователь) в системах на базе Linux, имеющий абсолютные, неограниченные права на изменение любых настроек сервера.
• SSH-ключ (Криптографический ключ): Альтернатива обычному паролю. Это связка из двух файлов (приватного и публичного). Приватный ключ надежно хранится только на вашем устройстве, а публичный - на сервере. Войти на сервер может только обладатель приватного ключа.
• Бэкдор (Backdoor): Буквально "черный ход" или программная "закладка". Это преднамеренно скрытая уязвимость или специальный алгоритм в коде программы, который позволяет разработчикам, хакерам или спецслужбам получить несанкционированный доступ к устройству, обойти шифрование и незаметно перехватывать трафик в обход стандартных систем защиты. Благодаря тому, что код Outline полностью открыт (Open Source), независимые аудиторы могут проверить его и гарантировать, что в нем нет подобных скрытых угроз.

Если вы работаете с Visual Studio Code на Raspberry Pi (или любом другом Linux-дистрибутиве с нестандартной графической оболочкой, например на Wayland), то рано или поздно при попытке авторизоваться в GitHub или синхронизировать настройки вы увидите назойливое окно:

"An OS keyring couldn't be identified for storing the encryption related data in your current desktop environment."

Редактор предложит перейти по ссылке или выбрать Use weaker encryption. В этой статье мы разберем, почему нельзя нажимать кнопку слабого шифрования, и как настроить всё правильно с точки зрения безопасности.

Почему это происходит?

VS Code (построенный на базе Chromium) пытается найти системное защищенное хранилище (keyring), чтобы безопасно спрятать туда ваш токен авторизации (OAuth). Однако в легковесных средах на Raspberry Pi демон ключей часто либо не установлен, либо запускается не так, как ожидает редактор. В итоге VS Code "слепнет" и выдает ошибку.

Быстрое, но опасное решение (Не рекомендую)

Самый частый совет в интернете - прописать в настройках запуска VS Code параметр "password-store": "basic". Да, окно ошибки пропадет. Но ваш секретный токен от GitHub будет сохранен в обычном текстовом файле. Если кто-то получит доступ к файловой системе вашей "малинки" - он получит и полный доступ к вашим репозиториям.

Правильное решение: Настраиваем gnome-keyring

Мы пойдем по пути системного администратора и заставим VS Code работать с системным шифрованием через libsecret.

1. Установка необходимых библиотек

Открываем терминал и ставим сам менеджер ключей и графическую утилиту для управления им:

sudo apt update
sudo apt install gnome-keyring libpam-gnome-keyring seahorse libsecret-1-0 libsecret-tools

2. Создание системной связки ключей

Чтобы система могла хранить пароли, нам нужно физически создать "сейф".

1. Запускаем установленную утилиту (в терминале вводим seahorse & или ищем "Пароли и ключи" в меню приложений).
2. Жмем правой кнопкой мыши в левой колонке -> Создать новую связку ключей (New Keyring).
3. Важно! Называем её строго Login (с большой буквы).
4. Программа попросит задать пароль. Укажите точно такой же пароль, с которым вы входите в систему. Это позволит Linux автоматически открывать сейф при загрузке.
5. Нажмите на новую связку правой кнопкой и выберите "Сделать по умолчанию".

3. Принудительное указание хранилища для VS Code

Осталось сказать редактору, чтобы он перестал гадать и использовал именно нашу новую связку.

1. Закройте VS Code, если он открыт, и "убейте" фоновые процессы командой: killall code

2. Откройте файл аргументов запуска:

   nano ~/.vscode/argv.json

3. Добавьте строку "password-store": "gnome-libsecret" перед закрывающей скобкой. Должно получиться так(если в файле ещё что то было не забудьте поставить запятую, подробнее читайте в FAQ ниже):

   {
       "disable-hardware-acceleration": true,
       "password-store": "gnome-libsecret"
   }

4. Сохраните изменения (Ctrl+O, Enter, Ctrl+X).

Ура!

Запускаем Visual Studio Code и спокойно авторизуемся в GitHub. Больше никаких ошибок! Токен надежно зашифрован алгоритмами операционной системы, а любые другие расширения (Copilot, базы данных) будут автоматически использовать это безопасное хранилище.

FAQ: Часто задаваемые вопросы и возможные ошибки

1. Почему в инструкции сказано "не забудьте поставить запятую" в файле argv.json?
Файл argv.json написан в формате JSON. Одно из главных правил этого формата - все параметры внутри фигурных скобок { } должны разделяться запятыми. Запятая ставится после каждого параметра, кроме самого последнего.

Если в вашем файле уже были какие-то настройки, и вы добавляете "password-store" в конец, обязательно поставьте запятую после предыдущей строки.
❌ Неправильно (вызовет ошибку при запуске VS Code):

{
    "disable-crash-reporter": true
    "password-store": "gnome-libsecret"
}

✅ Правильно:

{
    "disable-crash-reporter": true,
    "password-store": "gnome-libsecret"
}

2. Что делать, если файла ~/.vscode/argv.json вообще нет?

Такое бывает, если вы только что установили редактор и ни разу не меняли параметры его запуска. Просто создайте этот файл вручную и впишите туда структуру с нуля:

{
    "password-store": "gnome-libsecret"
}

(Заметьте: так как параметр здесь всего один, запятая после него не ставится).

3. Я поменял пароль от своего пользователя на Raspberry Pi, и теперь при запуске VS Code снова выскакивают окна.

Когда мы создавали связку ключей Login, мы задали ей пароль, совпадающий с паролем вашего пользователя. Это позволяет системе разблокировать сейф автоматически при входе. Если вы изменили пароль пользователя в Linux (через команду passwd), пароль от сейфа Login остался старым, и автоматическая разблокировка сломалась.
Как исправить: Откройте утилиту Seahorse ("Пароли и ключи"), нажмите правой кнопкой мыши на связку Login, выберите "Изменить пароль" и укажите ваш новый пароль от системы.

4. Подойдет ли эта инструкция для других дистрибутивов Linux (Ubuntu, Debian, Fedora)?

Да, абсолютно. Проблема с "keychain issues" в Visual Studio Code не является эксклюзивом для Raspberry Pi. Она возникает на любом Linux-дистрибутиве, где графическая оболочка (особенно на базе Wayland) или оконный менеджер (i3, sway) не инициализирует gnome-keyring должным образом по умолчанию. Описанный метод с libsecret - это универсальное и правильное решение для всего семейства Linux.

Глоссарий

• Keyring / Keychain (Связка ключей) - системное зашифрованное хранилище в операционной системе, предназначенное для безопасного хранения паролей, ключей шифрования и сертификатов.
• OAuth-токен - специальный цифровой ключ (строка символов), который GitHub выдает приложению (например, Visual Studio Code), чтобы оно могло выполнять действия от вашего имени без необходимости каждый раз вводить логин и пароль.
• gnome-keyring - фоновая служба (демон) в Linux, которая отвечает за управление системной связкой ключей и обеспечивает безопасное хранение секретов.
• libsecret - системная библиотека, которая служит стандартизированным "мостом". Через нее различные программы (включая VS Code) общаются с gnome-keyring, чтобы положить или достать пароль, не вникая в тонкости работы самого хранилища.
• Seahorse (Пароли и ключи) - графическая программа для среды Linux, которая позволяет пользователю визуально просматривать, создавать и управлять своими связками ключей и паролями.
• Wayland - современный протокол графического сервера в Linux (активно используется в последних версиях Raspberry Pi OS). Из-за его архитектурных отличий от старого X11 некоторые классические механизмы (например, автозапуск менеджеров паролей) могут работать нестандартно, что и вызывает подобные ошибки.
• argv.json - скрытый конфигурационный файл Visual Studio Code, в котором задаются низкоуровневые параметры запуска редактора, применяемые еще до загрузки основного графического интерфейса.
• Weaker encryption (Слабое шифрование) - механизм обходного хранения секретов в VS Code, при котором токены сохраняются в локальном файле настроек редактора без использования криптографической защиты операционной системы.

Интернет может казаться магией, но под капотом скрываются строгие и логичные алгоритмы. Один из самых важных - это DNS (Domain Name System или Система доменных имён). Если бы не DNS, нам бы пришлось запоминать длинные ряды цифр вместо удобных названий сайтов, таких как www.riopass.ru.

Что такое DNS?

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

DNS делает абсолютно то же самое для интернета:

• Люди привыкли использовать понятные доменные имена (например, yandex.ru, google.com).
• Компьютеры и серверы общаются друг с другом исключительно с помощью IP-адресов (например, 192.0.2.1 или 2a00:1450:4010:c05::8b).

DNS - это глобальная телефонная книга интернета, которая мгновенно переводит человекочитаемые адреса в машинные IP-адреса.

Как происходит преобразование адреса?

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

Локальное преобразование
Прежде чем беспокоить глобальные серверы, ваш компьютер пытается найти ответ у себя "в карманах".

• Кэш браузера: Ваш браузер (Chrome, Safari, Firefox) хранит записи о сайтах, которые вы недавно посещали. Первым делом он проверяет свой собственный кэш.
• Кэш операционной системы (ОС): Если браузер не нашел IP-адрес, он передает запрос операционной системе (Windows, macOS, Linux). ОС проверяет свой кэш DNS. Также на этом этапе проверяется локальный файл hosts (специальный текстовый файл, где пользователи могут вручную прописать соответствие IP и домена).
• Кэш маршрутизатора (Роутера): Если на компьютере ответа нет, запрос уходит на ваш домашний или офисный роутер. У него тоже есть своя небольшая память для DNS-запросов.

Если ни на одном из этих локальных этапов IP-адрес не найден, компьютер обращается за помощью во внешний мир.

Клиент -> Резолвер: рекурсивный запрос
Резолвер -> ROOT/TLD/авторитетный: итеративные запросы

Преобразование в рамках интернета

Здесь в игру вступает иерархия серверов интернета. Ваш запрос передается рекурсивному DNS-серверу (обычно его предоставляет ваш интернет-провайдер). Его задача - бегать по инстанциям, пока не найдет нужный ответ.

Вот как выглядит его маршрут:

• Корневые серверы (Root Nameservers):
  Рекурсивный сервер не знает, где находится example.com, поэтому он идет к "самым главным" серверам интернета - корневым. Они не знают точного IP-адреса сайта, но знают, кто отвечает за зону .com, .ru или .org.
• Серверы доменных зон верхнего уровня (TLD Nameservers):
  Корневой сервер отправляет запрос к серверу, отвечающему за конкретную зону (например, к TLD-серверу зоны .com). Этот сервер тоже не знает точный IP сайта, но знает, у какого сервера находится эта информация.
• Авторитативные серверы (Authoritative Nameservers):
  Это финальная инстанция. TLD-сервер указывает на авторитативный сервер, который физически хранит нужную DNS-запись для example.com. Этот сервер выдает точный IP-адрес.

Рекурсивный сервер получает IP-адрес, сохраняет его в свой кэш (чтобы в следующий раз ответить быстрее) и отдает вашему браузеру. Браузер подключается к серверу по полученному IP-адресу, и вы видите сайт.

Виды DNS-запросов: Как именно общаются серверы

1. Рекурсивный запрос (Recursive Query)
   Это запрос в стиле: "Сделай всю работу за меня и дай готовый ответ".
   Когда ваш компьютер обращается к DNS-серверу провайдера (или к 8.8.8.8), он отправляет именно рекурсивный запрос. Это означает, что сервер берет на себя обязательство пройти по всем инстанциям (корневые серверы, TLD, авторитативные) и вернуть вашему компьютеру либо готовый IP-адрес, либо сообщение об ошибке (если домена не существует). Ваш компьютер при этом просто ждет.
2. Итеративный запрос (Iterative / Non-recursive Query)
   Это запрос в стиле: "Дай мне лучший ответ, который у тебя есть прямо сейчас".
   Именно так общаются между собой сами DNS-серверы в глобальной сети. Когда рекурсивный сервер провайдера спрашивает корневой сервер: "Где example.com?", он делает итеративный запрос. Корневой сервер не будет искать ответ сам. Он скажет: "Я не знаю точный IP, но я знаю, кто отвечает за зону .com. Вот его адрес, иди спроси у него". Рекурсивный сервер принимает этот ответ и делает следующий итеративный запрос уже к TLD-серверу.

Направления запросов: Прямые, Обратные и Инверсные

Помимо способа поиска, запросы делятся по тому, что именно мы ищем. Здесь важно не путать термины.

1. Прямой запрос (Forward DNS Query)
   Это классика, о которой мы говорили выше. У нас есть доменное имя (человекочитаемое), и мы хотим получить его IP-адрес (машинный).
   Это самый частый сценарий. Допустим, мы хотим узнать, на каком IP-адресе "живет" сайт riopass.ru.
   В Windows (через cmd или PowerShell): -> Введите команду: -> nslookup riopass.ru, если порт 53 заблокирован то nslookup riopass.ru 8.8.8.8
   В ответе вы увидите DNS-сервер, который обработал ваш запрос, и ниже сам IP-адрес сайта.

2. Обратный запрос (Reverse DNS Query / rDNS)
   Здесь всё наоборот: у нас есть IP-адрес, и мы хотим узнать, какое доменное имя за ним закреплено. Это часто используется для проверки на спам (почтовые серверы проверяют, совпадает ли IP-адрес отправителя с его доменом) или при трассировке сетей (утилита traceroute). Для этого используется специальная доменная зона in-addr.arpa и записи типа PTR (Pointer).

   Теперь попробуем выполнить rDNS-запрос. Возьмем всем известный публичный DNS-сервер от Google с адресом 8.8.8.8 и проверим, какое доменное имя за ним закреплено в глобальной сети. В Windows: ->Просто введите IP вместо домена: -> nslookup 8.8.8.8 -> В ответе в строке Name: вы увидите dns.google.

3. Инверсный запрос (Inverse Query / IQUERY)
   А вот здесь кроется технический нюанс, о котором многие забывают. Инверсный запрос - это старый и специфический механизм. В нем клиент просил сервер найти доменное имя, основываясь на любой известной ресурсной записи (не обязательно на IP-адресе).
   Из-за высокой нагрузки на серверы и сложностей в реализации, инверсные запросы были официально признаны устаревшими (deprecated) еще в 2002 году документом RFC 3425. Сегодня в современном интернете они не используются, их место полностью заняли обратные запросы (rDNS).

Дополнение:
По умолчанию утилиты ищут A-запись (IPv4-адрес). Но если вам нужно узнать, какие серверы обрабатывают электронную почту для домена (MX-записи), тип запроса нужно указать явно. Попробуем на примере Яндекса: -> В Windows: -> nslookup -type=MX yandex.ru

В Linux / macOS: -> dig yandex.ru MX +short -> В ответ вы получите список серверов (например, mx.yandex.ru) и их приоритеты - именно туда отправляются письма, когда вы пишете на адрес @yandex.ru.

Часто задаваемые вопросы (FAQ)

1. Почему при переезде сайта на другой хостинг он какое-то время не работает?
Это связано с процессом обновления кэша. На каждом этапе (у провайдеров, на роутерах) DNS-записи кэшируются на определенное время (этот параметр называется TTL - Time to Live). Пока это время не истечет, серверы будут отдавать старый IP-адрес. Полное обновление по всему миру может занимать от пары часов до 48 часов.

2. Что значит "Сбросить DNS-кэш" (Flush DNS)?
Иногда ваш компьютер запоминает устаревший или ошибочный IP-адрес (например, если сайт недавно сменил сервер). Очистка (сброс) кэша заставляет операционную систему забыть старые данные и выполнить глобальный поиск заново, получив актуальный адрес.

3. Зачем люди меняют DNS-серверы на 8.8.8.8 (Google) или 1.1.1.1 (Cloudflare)?
По умолчанию вы используете рекурсивные серверы вашего интернет-провайдера. Иногда они работают медленно, нестабильно или блокируют определенные ресурсы. Переключение на публичные серверы от Google или Cloudflare часто ускоряет загрузку страниц и повышает приватность.

4. Что такое записи типа A, CNAME, MX?
На авторитативном сервере данные хранятся в виде разных записей:

• A-запись: Связывает домен с IPv4-адресом (самая частая).
• CNAME: "Псевдоним", связывает один домен с другим (например, www.site.com с site.com).
• MX-запись: Указывает, какой сервер обрабатывает электронную почту для этого домена.