Чистый интернет во всей домашней сети, блокировка мобильной рекламы, защита от трекеров и полное скрытие 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, из интернета напрямую до него не добраться.

Приветствую! С вами riopass.ru, и сегодня мы поговорим о боли, слезах и единственной вещи, которая отделяет системного администратора от нервного срыва - о резервном копировании.

Предыстория: ничто не предвещало беды. Изначально я задумал развернуть локальную нейросеть на базе Ollama на своей Raspberry Pi 5 под управлением Raspberry Pi OS. Через скрипты Pi-Apps установка не завелась. Я, как положено, всё вычистил и решил ставить с официального сайта, чтобы скрипт сам подтянул нужную архитектуру и всё настроил.

Туда же "до кучи" была установлена пачка других утилит и запущен процесс обновления компонентов. А потом я просто решил выключить "Малинку" для плановой замены домашнего роутера. И оставил так спустя день.

И она больше не включилась...

При подаче питания вентилятор начинал выть на все 120%, а графическая оболочка и система в целом отказывались стартовать. Умные ИИ-ассистенты, к которым я пошел за советом, дружно начали хоронить железо: "у вас умер адаптер - просадка V5", "сгорела SD-карта", "повредилась файловая система". Максимум, что показала диагностика - это пресловутый dirty bit на загрузочном разделе (признак внезапного отключения питания), который утилита fsck успешно сняла, но систему это не оживило.

Основная проблема крылась в самой Ollama и криво вставших обновлениях - они просто намертво вешали инициализацию ядра.

И тут я вспомнил про raspiBackup. Это гениальный скрипт от немецких разработчиков, который я когда-то давно настроил на еженедельный сброс дампов на свой мини-сервер через SMB-шару. Помню, тогда ещё думал: "Блин, ну это же минус 30-40 ГБ места на диске! Бэкапы, которые никогда не пригодятся мне не пригодяться".

В итоге именно эти "лишние" гигабайты меня и спасли. Потому что реанимировать систему удалось только накатив бэкап. Ниже - подробная инструкция, как восстановить Raspberry Pi из архива raspiBackup, используя сторонний ПК (в моем случае - рабочий ноутбук на Debian 13).

Инструкция: Восстановление raspiBackup на другом Linux-ПК

Если ваша Малинка "мертва", вы не сможете запустить скрипт восстановления на ней самой. Нам понадобится любой компьютер с Linux (например, Ubuntu, Debian или Mint) и кардридер/переходник.

Шаг 1. Готовим накопитель и бэкап

1. Подключаем флешку или NVMe-накопитель от мертвой Raspberry к нашему Linux-ПК.

2. Проверяем, под каким именем накопитель определился в системе:

   lsblk

   Внимательно ищем свой диск по размеру (например, /dev/sdb). Это критически важно, чтобы случайно не отформатировать системный диск ноутбука!

3. Убеждаемся, что папка с вашим бэкапом (вида Имя@debian-tar-backup-Дата) доступна на этом ПК - локально или примонтирована по сети. Я перекинул заранее через команду scp.

Шаг 2. Скачиваем утилиту

Если скрипта raspiBackup нет на вашем ПК, скачиваем его одной командой:

curl -sSLO https://raw.githubusercontent.com/framps/raspiBackup/master/raspiBackup.sh
chmod +x raspiBackup.sh

Шаг 3. Запускаем магию (Осторожно, пофиг!)

Если вы просто запустите скрипт на ПК (архитектура x86_64), он выдаст ошибку RBK0268E: Only Raspberries running Raspberry PI OS are supported. Он "видит", что вы не на ARM, и отказывается работать.

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

Выполняем команду (не забудьте подставить свои данные!):

sudo ./raspiBackup.sh --unsupportedEnvironment -d /dev/sdb /путь/к/папке/с/бэкапом

Где /dev/sdb - это ваш накопитель от Малинки.

На скриншоте выделил красным IPv6 Link-Local, то что подключился по RDP с PC на ноутбук. (на самом роутере у меня IPv6 выключен)

Что произойдет дальше:
Скрипт прочитает структуру старого диска, сам переразметит разделы, зальет boot-сектор и распакует ваш тяжелый tar.zst архив прямо в корень. Прогресс-бара распаковки архива не будет - терминал просто "задумается" на 10–20 минут. Не прерывайте процесс! Дождитесь сообщения об успехе, извлеките диск и вставляйте его в Raspberry. Она загрузится так, будто ничего и не ломалось. (У меня в обще ноутбук заснул, я думал всё сломалось, но нет, успех!)

Бонус: IPv6 Link-Local - как найти сервер, если роутер умер

В моей истории всё началось с замены роутера. Часто при смене сетевого оборудования, изменении подсетей (например, с 192.168.1.x на 192.168.0.x) или выходе из строя DHCP-сервера, ваш headless-сервер (без монитора) становится недоступным по сети. Вы не знаете его новый IP-адрес.

Здесь на сцену выходит IPv6 Link-Local (Локальный адрес канала).

Даже если в вашей сети нет интернета, нет роутера и нет DHCP-сервера, любое современное устройство с поддержкой IPv6 автоматически генерирует себе адрес в диапазоне fe80::/10. Этот адрес создается на основе MAC-адреса сетевой карты и существует только в пределах физического сегмента сети (от кабеля до кабеля).

Как это использовать для спасения?

Если Raspberry Pi потерялась в сети:

1. Берем обычный патч-корд и соединяем порт Ethernet на вашем ноутбуке напрямую с портом Raspberry Pi.
2. Включаем устройства. Они автоматически договорятся и создадут себе Link-Local адреса.
3.  На вашем ноутбуке (Windows/Linux) открываем терминал и сканируем соседей по IPv6 с помощью мультикаст-пинга:

•        На Linux/macOS: ping6 -I eth0 ff02::1 (где eth0 — ваше сетевое подключение).
•        На Windows: ping -6 ff02::1

Вам ответят адреса, начинающиеся на fe80::.... Один из них - это ваш ноутбук, второй - ваша потерянная Raspberry Pi!

Берем этот адрес и спокойно подключаемся по SSH:

ssh user@fe80::xxxx:xxxx:xxxx:xxxx%eth0

(Знак процента и имя интерфейса в конце обязательны, чтобы система поняла, через какой именно кабель стучаться).

Подключились напрямую - поправили настройки netplan или dhcpcd.conf под новый роутер, и сервер снова в строю.

Мораль: Изучайте сетевые технологии и делайте бэкапы. Это экономит не только время, но и не будете как Ганвест разговаривать потом.

Глоссарий к статье

Для тех, кто только погружается в мир Linux и домашних серверов, вот расшифровка ключевых терминов из статьи:

•  Ollama - инструмент (фреймворк), позволяющий разворачивать и запускать большие языковые нейросети (LLM) прямо у себя на домашнем железе, без интернета и цензуры.
•  Headless-сервер (безголовый сервер) - компьютер или микрокомпьютер (как наша Raspberry Pi), который работает без подключенного монитора, клавиатуры и мыши. Управляется исключительно по сети.
•  fsck (File System Consistency Check) - стандартная системная утилита в Linux. Врач-травматолог для жестких дисков и флешек: проверяет файловую систему на ошибки и пытается их исправить.
• Dirty bit (Грязный бит) - специальный флаг (метка) в файловой системе. Ставится автоматически, если выдернуть питание устройства до того, как система успела безопасно завершить работу с диском. Сигнализирует о том, что при следующей загрузке нужно запустить fsck.
• raspiBackup - мощный opensource-скрипт для Raspberry Pi. Умеет делать резервные копии работающей системы по расписанию и сохранять их на сетевые диски.
• SMB-шара (SMB Share) - общая сетевая папка, доступная другим устройствам в локальной сети. Названа в честь протокола Server Message Block, который исторически используется в Windows, но отлично понимается и Linux-системами.
• tar.zst - формат сжатого архива. Утилита tar собирает всю файловую систему в один большой файл-контейнер, а алгоритм zstd (Zstandard) сжимает его. Работает гораздо быстрее и эффективнее старых форматов вроде .gz или .zip.
• NVMe (Non-Volatile Memory Express) - современный протокол и формат быстрых твердотельных накопителей (SSD). Raspberry Pi 5 поддерживает их подключение через специальный шлейф (PCIe), что дает колоссальный прирост скорости по сравнению с обычными MicroSD-картами.
• DHCP-сервер (Dynamic Host Configuration Protocol) - служба, которая автоматически выдает IP-адреса всем устройствам в вашей домашней сети. Чаще всего эта функция встроена в ваш домашний Wi-Fi роутер.
• IPv6 Link-Local (Локальный адрес канала) - автоматический сетевой адрес (всегда начинается с fe80::), который любое современное устройство назначает себе само. Работает только в пределах одного физического провода или Wi-Fi сегмента. Позволяет устройствам общаться напрямую, даже если роутер сгорел, а DHCP-сервер мертв.
• SSH (Secure Shell) - защищенный сетевой протокол для удаленного управления компьютером через командную строку. Тот самый черный экран с белыми буквами, через который админы творят магию.

Если вы работаете с 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, при котором токены сохраняются в локальном файле настроек редактора без использования криптографической защиты операционной системы.

Raspberry Pi 5 - это невероятно мощный мини-компьютер, который идеально подходит для создания домашнего сервера, медиацентра или системы умного дома. Но чтобы выжать из него максимум и не захламлять систему десятками зависимостей, лучше всего использовать контейнеризацию.

Специально для читателей riopass.ru мы подготовили простую и быструю инструкцию по установке Docker на Raspberry Pi 5.

Подготовка системы

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

Откройте терминал на вашей Raspberry Pi (или подключитесь к ней по SSH) и введите следующую команду:

sudo apt update && sudo apt upgrade -y

Дождитесь завершения процесса. Если обновлений было много, не лишним будет перезагрузить устройство командой sudo reboot

Установка Docker

Самый простой и официально рекомендуемый способ установки Docker на Raspberry Pi OS (которая базируется на Debian) - использование автоматического скрипта установки.

1. Загрузка установочного скрипта

Скачайте официальный скрипт с сайта Docker с помощью утилиты curl:

curl -fsSL https://get.docker.com -o get-docker.sh

2. Запуск скрипта

Теперь запустите скачанный скрипт с правами суперпользователя:

sudo sh get-docker.sh

Процесс установки займет пару минут. Скрипт самостоятельно определит архитектуру вашего процессора (ARM64 для Raspberry Pi 5) и скачает нужные версии пакетов.

Настройка прав доступа (чтобы работать без sudo)

По умолчанию для выполнения команд Docker требуются права root. Постоянно писать sudo docker - это неудобно и не совсем безопасно. Чтобы этого избежать, нужно добавить вашего текущего пользователя (обычно это пользователь pi или тот, которого вы создали при установке системы) в группу docker

Выполните команду:

sudo usermod -aG docker $USER

Чтобы изменения вступили в силу без перезагрузки всей системы, примените новую группу:

newgrp docker

(Примечание: если после этого команды Docker все равно требуют sudo, просто перезагрузите Raspberry Pi командой sudo reboot).

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

Давайте убедимся, что всё прошло успешно. Введите в терминал команду для проверки версии:

docker --version

Вы должны увидеть актуальную версию Docker, например: Docker version 29.4.0, build 9d7ad9f.

А теперь - традиционный тест! Запустим тестовый контейнер hello-world:

docker run hello-world

Если установка прошла успешно, Docker скачает минималистичный образ и выведет на экран приветственное сообщение: "Hello from Docker!".

Настройка автозапуска

Чтобы контейнеры автоматически поднимались после сбоя питания или перезагрузки Raspberry Pi, нужно добавить службу Docker в автозагрузку:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Оставайтесь с riopass.ru, впереди еще много полезных шпаргалок по настройке вашего домашнего сервера!

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

В: Почему Docker лучше обычной установки программ через apt install?
О: Docker изолирует приложения. Вы можете запустить пять разных версий Python на одной Raspberry Pi 5, и они не будут конфликтовать. Кроме того, удаление программы в Docker - это просто удаление контейнера, после которого в основной системе не остается никакого "мусора".

В: Сильно ли Docker нагружает Raspberry Pi 5?

О: Raspberry Pi 5 обладает мощным процессором и быстрой оперативной памятью, поэтому накладные расходы на работу Docker практически незаметны (обычно это 1-2% ресурсов). Это гораздо эффективнее, чем использование виртуальных машин.

В: Что делать, если Docker не скачивает образы (ошибки "Timeout" или "Connection refused")?

О: В некоторых регионах доступ к официальному Docker Hub может быть ограничен или работать нестабильно. В таких случаях можно использовать зеркала (прокси-репозитории).
Одним из надежных вариантов является прокси от Timeweb. Чтобы им воспользоваться, нужно отредактировать (или создать) файл конфигурации:

sudo nano /etc/docker/daemon.json

Добавьте туда следующий адрес:

{
  "registry-mirrors": ["https://dockerhub.timeweb.cloud/"]
}

После этого перезапустите службу: sudo systemctl restart docker. Теперь образы будут скачиваться через это зеркало.

В: Нужно ли использовать 64-битную ОС для Docker на Raspberry Pi 5?

О: Да, крайне желательно. Raspberry Pi 5 - это 64-битное устройство, и Docker работает эффективнее именно на 64-битных версиях Raspberry Pi OS или Ubuntu. Это также дает доступ к большему количеству современных образов.

В: Как обновить Docker до последней версии?

О: Поскольку мы устанавливали его через официальный репозиторий, Docker будет обновляться автоматически при выполнении стандартной команды обновления системы: sudo apt update && sudo apt upgrade.

Глоссарий

• Docker (Докер) - специальная платформа, которая позволяет упаковать любую программу со всеми ее настройками и файлами в единый стандартизированный блок. Благодаря этому программа будет одинаково хорошо работать на любом устройстве, будь то ваш ноутбук или Raspberry Pi.
• Docker Hub - крупнейшее в мире публичное хранилище (реестр) образов Docker. Это своего рода "магазин приложений", откуда скачиваются официальные образы Python, Nginx, PostgreSQL и тысяч других программ.
• Контейнеризация - сама технология изоляции приложений друг от друга и от основной операционной системы. Контейнеры потребляют гораздо меньше ресурсов, чем традиционные виртуальные машины.
• Образ (Image) - это готовый неизменяемый шаблон или "чертеж" программы. Скачивая образ (например, hello-world), вы получаете инструкцию для системы, как именно запускать приложение.
• Контейнер (Container) - это "оживший" образ. Запущенная и работающая в изолированной среде программа. Из одного образа можно запустить несколько одинаковых контейнеров.
• Репозиторий (Repository) - коллекция образов Docker с одинаковым именем, но разными тегами (версиями). Например, в репозитории python могут быть теги 3.10, 3.12-slim и так далее.
• Терминал (Командная строка) - текстовый интерфейс для общения с операционной системой. Вместо того чтобы кликать мышкой по иконкам, вы вводите текстовые команды.
• SSH (Secure Shell) - защищенный протокол, который позволяет вам подключиться к терминалу вашей Raspberry Pi удаленно, например, с основного компьютера или ноутбука.
• Root / Sudo - Root это главный администратор (суперпользователь) в системах Linux, которому разрешено делать с системой абсолютно всё. Команда sudo (Superuser DO) позволяет обычному пользователю временно выполнить конкретную команду с правами этого самого главного администратора.
• Скрипт - текстовый файл, содержащий последовательность команд, которые компьютер должен выполнить автоматически (например, скрипт установки Docker скачивает, распаковывает и настраивает все нужные файлы за вас).

Если вы используете свой Raspberry Pi 5 в качестве настольного компьютера, ретро-консоли или медиацентра, вы наверняка сталкивались с тем, что установка некоторых программ в Linux требует поиска сложных команд и ручной компиляции кода. Именно эту проблему решает Pi-Apps.

Что такое Pi-Apps?
 

Pi-Apps - это бесплатный магазин приложений с открытым исходным кодом, созданный специально для Raspberry Pi (и других устройств на базе ARM/x86 Linux).

Главная его цель - максимально упростить процесс установки софта. По сути, это набор скриптов, упакованных в удобный графический интерфейс. С помощью Pi-Apps вы можете скачивать, обновлять и удалять десятки популярных программ буквально в пару кликов, без необходимости лезть в командную строку.

Что можно установить через Pi-Apps?

• Браузеры: Chromium (с поддержкой Widevine для Netflix/Spotify), Firefox, Tor и так далее
• Мессенджеры: Telegram, Discord, Skype.
• Разработка: Visual Studio Code, Arduino IDE, Android Studio.
• Игры: Minecraft, Doom, эмуляторы Box86/Box64 для запуска Windows-игр,.
• Утилиты: GIMP, OBS Studio, TeamViewer.

Как установить Pi-Apps на Raspberry Pi

Процесс установки невероятно прост и занимает всего пару минут. Все, что вам нужно - это доступ к интернету и открытый терминал.

***
Перед установкой любого нового софта рекомендуется обновить систему. Это поможет избежать конфликтов версий.

1. Откройте терминал (сочетание клавиш Ctrl + Alt + T).

2. Введите следующую команду и нажмите Enter:

   sudo apt update && sudo apt upgrade -y

3. Дождитесь завершения процесса обновления.

Установка Pi-Apps

Разработчик Pi-Apps (Botspot) подготовил удобный скрипт автоматической установки. В том же терминале введите одну простенькую команду:

wget -qO- https://raw.githubusercontent.com/Botspot/pi-apps/master/install | bash

Завершение и запуск

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

Как только в терминале появится сообщение об успешной установке, вы можете его закрыть.

Где найти Pi-Apps?

На вашем рабочем столе появится иконка Pi-Apps.

Также программу можно найти в главном меню Raspberry Pi OS в разделе "Стандартные" (Accessories).

Как пользоваться Pi-Apps

Интерфейс программы интуитивно понятен:

1. Запустите Pi-Apps.
2. Перед вами появится окно с категориями (Games, Internet, Tools и т.д.).
3. Выберите нужную категорию или воспользуйтесь кнопкой Search (Поиск), чтобы найти конкретное приложение.
4. Выберите программу и нажмите кнопку Install (Установить).
5. После этого откроется окно терминала, где вы сможете наблюдать за процессом установки. Как только он завершится, программа будет готова к использованию!

Для кого это решение:
Идеально подходит тем, у кого дома нет публичного/статического ("белого") IP-адреса, чтобы напрямую открыть порты, но есть любой недорогой VPS-сервер. В данном руководстве для примера, мы используем сервер игры Counter-Strike 1.6.
Как работает эта архитектура:
Мы превращаем VPS сервер в публичную "витрину" для домашнего железа, связывая их через неблокируемый VPN-туннель.

• VPS (Внешний шлюз): Смотрит в интернет своим реальным IP-адресом и принимает подключения игроков. Внутри туннеля AmneziaWG он получает адрес 10.8.0.1.
• Raspberry Pi 5 (Домашний сервер): Спокойно стоит за провайдерским NAT. Она сама инициирует подключение к VPS, пробивая туннель, и получает внутренний адрес 10.8.0.2.
• Магия маршрутизации: Мы берем внешний игровой порт (27015 UDP/TCP) на VPS и прозрачно пробрасываем его сквозь туннель прямо на вашу домашнюю "малинку", ну или linux сервер.

Главный плюс: мы буквально "вытягиваем" Raspberry Pi в глобальную сеть, не ломая то, что уже работает. Порт-форвардинг настраивается настолько ювелирно, что крутящиеся на VPS сайты, веб-сервисы и боты даже не заметят соседства с игровым сервером.

1. Установка AmneziaWG 

На сервере VPS (Ubuntu/Debian):

sudo add-apt-repository ppa:amnezia/ppa
sudo apt update
sudo apt install amneziawg-tools amneziawg-dkms -y

На Raspberry Pi 5 (Особый способ установки ключей, обходящий блокировки):

sudo apt update
sudo apt install -y gnupg2 curl linux-headers-$(uname -r)
# Скачиваем ключ через 80 порт
gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 57290828
gpg --export 57290828 | sudo tee /usr/share/keyrings/amnezia.gpg > /dev/null
# Добавляем репозиторий
echo "deb [signed-by=/usr/share/keyrings/amnezia.gpg] https://ppa.launchpadcontent.net/amnezia/ppa/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/amneziawg.list
sudo apt update
sudo apt install -y amneziawg-tools amneziawg-dkms

2. Генерация ключей

Все ключи для удобства генерируем на VPS, чтобы потом просто скопировать их в конфиги.

Выполняем на VPS:

mkdir -p ~/awg-keys && cd ~/awg-keys
awg genkey | tee server_private | awg pubkey > server_public
awg genkey | tee client_private | awg pubkey > client_public

# Выводим на экран и копируем в блокнот:
cat server_private && cat server_public
cat client_private && cat client_public

3. Настройка VPS (Сервер)

1. Включаем маршрутизацию (форвардинг) в ядре:

   echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p

2. Создаем конфигурационный файл:

   sudo nano /etc/amnezia/amneziawg/awg0.conf

3. Вставляем настройки (замените ключи на сгенерированные). Внимание: если ваш основной сетевой интерфейс называется не eth0, а ens3 - измените его в правилах PostUp/PostDown.

   [Interface]
   PrivateKey = <server_private>
   Address = 10.8.0.1/24
   ListenPort = 51820
   
   # Магические параметры Amnezia
   Jc = 4
   Jmin = 40
   Jmax = 70
   S1 = 29
   S2 = 15
   H1 = 2021056581
   H2 = 641527027
   H3 = 1018901243
   H4 = 301646271
   
   # Маскарадинг для выхода туннеля в сеть
   PostUp = iptables -t nat -A POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
   PostDown = iptables -t nat -D POSTROUTING -s 10.8.0.0/24 -o eth0 -j MASQUERADE
   
   [Peer]
   PublicKey = <client_public>
   AllowedIPs = 10.8.0.2/32

4. Открываем порт в фаерволе (если используете UFW) и запускаем туннель:

   sudo ufw allow 51820/udp
   sudo systemctl enable --now awg-quick@awg0

4. Настройка Raspberry Pi 5 (Клиент)

1. Создаем конфигурационный файл:

   sudo nano /etc/amnezia/amneziawg/awg0.conf

2. Вставляем настройки. Важно: Обязательно проверьте наличие заголовка [Peer], без него парсер выдаст ошибку Line unrecognized

   [Interface]
   PrivateKey = <client_private>
   Address = 10.8.0.2/24
   
   Jc = 4
   Jmin = 40
   Jmax = 70
   S1 = 29
   S2 = 15
   H1 = 2021056581
   H2 = 641527027
   H3 = 1018901243
   H4 = 301646271
   
   [Peer]
   PublicKey = <server_public>
   Endpoint = IP_ВАШЕГО_VPS:51820
   AllowedIPs = 10.8.0.0/24
   PersistentKeepalive = 25

3. Запускаем туннель и проверяем пинг до VPS:

   sudo systemctl enable --now awg-quick@awg0
   ping -c 4 10.8.0.1

5. Настройка проброса портов (NAT и UFW) на VPS

Чтобы внешний трафик, приходящий на публичный IP VPS по порту 27015, улетал на домашнюю малинку, выполняем на VPS:

1. Открываем нужные порты для входящих подключений:

   sudo ufw allow 27015/udp
   sudo ufw allow 27015/tcp

2. Критически важный шаг: Разрешаем транзитный (FORWARD) трафик в UFW, иначе фаервол молча убьет пакеты, идущие сквозь сервер в туннель:

   sudo ufw route allow proto udp to 10.8.0.2 port 27015
   sudo ufw route allow proto tcp to 10.8.0.2 port 27015

3. Прописываем правила iptables для перенаправления (DNAT) и обратной подмены адреса (SNAT/MASQUERADE):

   # Перенаправление внутрь туннеля
   sudo iptables -t nat -A PREROUTING -p udp --dport 27015 -j DNAT --to-destination 10.8.0.2:27015
   sudo iptables -t nat -A PREROUTING -p tcp --dport 27015 -j DNAT --to-destination 10.8.0.2:27015
   
   # Обратный маскарадинг
   sudo iptables -t nat -A POSTROUTING -d 10.8.0.2 -p udp --dport 27015 -j MASQUERADE
   sudo iptables -t nat -A POSTROUTING -d 10.8.0.2 -p tcp --dport 27015 -j MASQUERADE

4. Сохраняем правила iptables, чтобы они пережили перезагрузку сервера:

   sudo apt install iptables-persistent -y
   sudo netfilter-persistent save

Вывод:
Сервер работает стабильно, трафик полностью скрыт от DPI, а игровой сервер светит в мир с выделенного IP-адреса.