Как развернуть LinkBreeze через Docker Compose
Пошаговое руководство по установке LinkBreeze на VPS с использованием Caddy. Вы узнаете, как настроить SQLite, обеспечить отслеживание кликов и зафиксировать версии образов.
Что такое LinkBreeze
LinkBreeze — это self-hosted альтернатива Linktree: один Docker-контейнер, который обслуживает публичную страницу со ссылками и панель администратора, используя базу данных в одном файле SQLite. Проект распространяется по лицензии MIT, написан на TypeScript с использованием Next.js и опубликован в виде образа контейнера на Docker Hub как omnirise/linkbreeze и на GHCR как ghcr.io/omnirise/linkbreeze; более старые релизы использовали ghcr.io/manak-hash/linkbreeze. Для запуска вам потребуется VPS, домен с A-записью, указывающей на этот VPS, открытые порты 80 и 443, а также Docker Engine с плагином Compose.
Это руководство охватывает развертывание, которое официально поддерживается репозиторием: Docker Compose за reverse proxy, который самостоятельно получает сертификаты. Также рассматриваются возможные сбои, так как ссылка в профиле — это публичный URL, по которому переходят другие люди, и нерабочая ссылка означает потерю перехода.
Прежде чем приступать, учтите, насколько этот проект новый.
Достаточно ли LinkBreeze зрелый для публичной ссылки в профиле?
Первый релиз с тегом, v1.0.0, датирован 1 июля 2026 года. Этому проекту несколько месяцев, а не лет.
В журнале изменений упоминаются проблемы с видимостью аккаунта GitHub. На 2 ноября 2026 года канонический репозиторий GitHub по адресу github.com/OmniRise/LinkBreeze является публичным, наряду с официальным зеркалом проекта на GitLab, gitlab.com/omnirise00/linkbreeze, и образом на Docker Hub.
Данные, на которых построен график
[
{
"week": "2026-06-29",
"releases": 3,
"cumulative": 3
},
{
"week": "2026-07-06",
"releases": 3,
"cumulative": 6
},
{
"week": "2026-07-13",
"releases": 1,
"cumulative": 7
},
{
"week": "2026-07-20",
"releases": 2,
"cumulative": 9
},
{
"week": "2026-07-27",
"releases": 3,
"cumulative": 12
},
{
"week": "2026-08-03",
"releases": 2,
"cumulative": 14
},
{
"week": "2026-08-10",
"releases": 4,
"cumulative": 18
},
{
"week": "2026-08-17",
"releases": 1,
"cumulative": 19
},
{
"week": "2026-08-24",
"releases": 1,
"cumulative": 20
},
{
"week": "2026-08-31",
"releases": 0,
"cumulative": 20
},
{
"week": "2026-09-07",
"releases": 0,
"cumulative": 20
},
{
"week": "2026-09-14",
"releases": 1,
"cumulative": 21
},
{
"week": "2026-09-21",
"releases": 1,
"cumulative": 22
}
]Начиная с v1.0.0, проект выпустил 22 релизов с тегами за 13 календарные недели, вплоть до v1.4.1 от 23 сентября 2026 года. Этот график заканчивается на v1.4.1; v1.5.0 последовал 24 октября, а v1.5.1 — 27 октября 2026 года.
Воспринимайте это как два отдельных факта. Сопровождающий активен, ошибки исправляются в течение нескольких дней. Схема базы данных и настройки по умолчанию всё ещё меняются, поэтому инстанс, который вы развернёте и забудете, со временем сильно разойдётся с актуальным кодом.
Лицензия защищает вас от худшего сценария. MIT в сочетании с образом контейнера и файлом SQLite на вашем диске означает, что если разработка прекратится, то, что у вас есть, продолжит работать. От чего она не защищает, так это от публичного веб-приложения, которое перестаёт получать обновления безопасности и со временем становится угрозой. Разворачивайте это как сервис, который вы будете регулярно обновлять, и обеспечьте работу процедуры резервного копирования, описанной ниже, с первого же дня.
Закрепляйте тег образа, не используйте latest
Текущий рабочий процесс выпуска обновлений отправляет два тега для каждой версии в Docker Hub и GHCR: latest и git-тег в исходном виде, включая v. Таким образом, закрепленным тегом для релиза v1.4.1 является docker.io/omnirise/linkbreeze:v1.4.1. Релизы до версии v1.4.0 тегировались иначе: рабочий процесс удалял v, и эти релизы существуют в GHCR только в виде чисел, например ghcr.io/manak-hash/linkbreeze:1.2.7. Если указать тег в неверном формате, Docker сообщит об ошибке manifest unknown, так как этот тег никогда не был отправлен в реестр. Docker Hub, который теперь указан в README как путь по умолчанию для команды pull, также содержит v1.5.1 — тег, используемый официальным пакетом Unraid для этого проекта.
Закрепляйте тег, потому что latest постоянно меняется. При частоте обновлений, указанной в таблице выше, использование docker compose pull вместо latest означает непроверенное обновление страницы, которую использует ваша аудитория. При использовании закрепленного тега обновление происходит только тогда, когда вы сами редактируете файл конфигурации.
Еще один момент касательно образа. Начиная с версии v1.4.0, это манифест с поддержкой нескольких архитектур для linux/amd64 и linux/arm64, каждый из которых собран на нативном раннере. Если вы запускаете ARM VPS вместо x86, тот же самый тег загрузит сборку arm64, и на сервере не потребуется ничего компилировать. Релизы до v1.3.2 публиковались только для linux/amd64, а 32-битные платы arm/v7 намеренно исключены, поэтому использование старого тега или попытка запуска на 32-битной плате приведет к ошибке no matching manifest.
Развертывание LinkBreeze за Caddy с автоматическим TLS
Caddy самостоятельно запрашивает и обновляет сертификаты от Let's Encrypt, поэтому для TLS (transport layer security) не требуется отдельная настройка сертификатов. Весь процесс развертывания сводится к трем файлам в одной директории.
Сначала сгенерируйте секретный ключ:
mkdir -p ~/linkbreeze && cd ~/linkbreeze
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .envSECRET_KEY подписывает cookie сессии администратора и «солит» хеш посетителей аналитики. Начиная с версии v1.4.0, этот же ключ используется для шифрования сохраненных секретов двухфакторной аутентификации (TOTP). В файле compose, опубликованном вместе с v1.4.1, по умолчанию используется ${SECRET_KEY:-changeme-in-production}. Если использовать этот файл без изменения ключа, сессии будут подписываться ключом, который опубликован в открытом репозитории проекта. Установите ключ до первого запуска, так как его последующая смена приведет к выходу из системы и сбросу «соли» аналитики.
Создайте файл docker-compose.yml:
services:
linkbreeze:
image: docker.io/omnirise/linkbreeze:v1.4.1
restart: unless-stopped
volumes:
- linkbreeze-data:/app/data
environment:
- DATABASE_PATH=/app/data/linkbreeze.db
- SECRET_KEY=${SECRET_KEY}
- BASE_URL=https://links.example.com
networks:
- linkbreeze-net
caddy:
image: caddy:2-alpine
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data
- caddy-config:/config
networks:
- linkbreeze-net
networks:
linkbreeze-net:
volumes:
linkbreeze-data:
caddy-data:
caddy-config:Параметр BASE_URL не является обязательным, но его стоит настроить: он сообщает приложению его реальный публичный адрес. Это предотвращает ситуацию, когда запрос с поддельным заголовком Host заставляет приложение генерировать ссылки на чужой домен.
Создайте рядом файл Caddyfile, указав в нем свой домен:
links.example.com {
encode zstd gzip
reverse_proxy linkbreeze:3000
}Caddy по умолчанию устанавливает заголовки X-Forwarded-For и X-Forwarded-Proto для проксируемых запросов, которые передают адрес клиента для аналитики и транспорт для безопасности cookie сессии. Запустите проект:
docker compose up -d
docker compose ps
docker compose logs -f caddyКоманда docker compose ps должна показать, что контейнер LinkBreeze находится в состоянии healthy. Образ содержит собственную проверку работоспособности (healthcheck) wget --spider -q http://127.0.0.1:3000/api/health, поэтому добавлять её вручную не нужно. Не копируйте healthcheck из примера Caddy в репозитории: он вызывает curl, а образ построен на базе node:22-alpine, в которой есть только busybox wget и отсутствует curl. Такой контейнер будет сообщать о статусе unhealthy, даже если страницы отдаются корректно.
Откройте https://links.example.com в браузере. При первом посещении вы попадете в мастер настройки по адресу /setup, где создается единственная учетная запись администратора. После этого панель управления будет доступна по адресу /dashboard, а форма входа — по адресу /login. В закрепленном релизе v1.4.1 эта учетная запись является локальной для данного экземпляра, и в ней нет встроенного механизма единого входа (SSO). Если вы хотите защитить панель управления тем же способом, что и другие ваши сервисы, используйте прокси с поддержкой forward auth, например self-hosted Authentik. Нативная поддержка единого входа OIDC по состоянию на 2 ноября 2026 года находится в списке невыпущенных функций.
Обратите внимание на то, чего не делает файл compose: он не публикует порт 3000. Только Caddy слушает запросы на публичном интерфейсе. Если синтаксис Docker Compose для вас в новинку, в статье основы Docker Compose для VPS описаны все используемые здесь концепции. Если перед этим сервисом у вас уже работает другой прокси, в статье сравнение Nginx, Caddy и Traefik объясняются необходимые изменения. В репозитории есть готовые примеры для Nginx с Certbot, Traefik и туннелем Cloudflare.
Где хранятся ваши данные и что должен содержать бэкап
DATABASE_PATH указывает на /app/data/linkbreeze.db. Загруженные аватары и миниатюры ссылок записываются рядом с ним в /app/data/uploads. Оба элемента находятся в именованном томе linkbreeze-data, поэтому единицей бэкапа является том, а не сам файл базы данных. Если восстановить файл без директории с загрузками, каждое изображение на странице будет выдавать ошибку 404.
Всё остальное действительно находится в этой единственной базе данных: страницы, ссылки, настройки, темы, подписчики email-рассылки и строки аналитики.
Выполняйте копирование при остановленном контейнере:
docker compose stop linkbreeze
docker compose cp linkbreeze:/app/data ./backup-$(date +%F)
docker compose start linkbreezeСначала остановите контейнер, так как копирование базы данных SQLite во время записи может захватить незавершенную транзакцию, и копия откроется как поврежденный файл. Во время копирования страница будет недоступна. Восстановление выполняется аналогично в обратном порядке:
docker compose stop linkbreeze
docker compose cp ./backup-2026-08-14/. linkbreeze:/app/data
docker compose start linkbreeze
docker compose logs -f linkbreezeПанель управления также предлагает экспорт в формате JSON, который доступен по адресу /api/backup как linkbreeze-backup-YYYY-MM-DD.json. Он содержит профиль, ссылки и их разделы, настройки, сохраненные темы и записи о пользовательских шрифтах. Он не содержит историю аналитики, подписчиков email-рассылки, учетную запись администратора или загруженные файлы. Восстановление из этого файла удаляет текущие строки в шести таблицах, которые он затрагивает, перед вставкой данных из файла. Рассматривайте это как снимок конфигурации для переноса на другой хост или отмены ошибки редактирования. Копия тома — это и есть бэкап.
Здесь действуют те же два правила хранения, что и везде, где вы используете SQLite в продакшене на VPS. Храните базу данных на локальном диске, так как блокировки SQLite ненадежны в сетевых файловых системах, и о проблеме вы узнаете только после повреждения страницы. Если вы заменяете именованный том на bind mount хоста, сначала выполните chown для директории на хосте: контейнер работает от имени пользователя node, не имеющего прав root, с uid 1000 в node:22-alpine. Директория, созданная от имени root, будет недоступна для записи, поэтому приложение не сможет открыть базу данных, и контейнер завершит работу при запуске. Bind mounts против именованных томов в Compose подробно описывает этот выбор.
Аналитика и баннер согласия, которые вам не нужны
Это функция, оправдывающая самостоятельный хостинг страницы, которую можно было бы бесплатно разместить в другом месте.
Аналитика работает без использования cookies. Встроенная аналитика не устанавливает файлы cookie для посетителей и не загружает сторонние скрипты отслеживания; внешняя аналитика и встраиваемые элементы являются дополнительными функциями. Посетитель идентифицируется с помощью SHA-256 хеша IP-адреса, строки user agent и соли, обрезанного до 16 шестнадцатеричных символов. Сама соль является хешем текущей даты UTC и вашего SECRET_KEY, поэтому она меняется в полночь по UTC, и хеши за вчерашний день невозможно сопоставить с сегодняшними. Исходный IP-адрес никогда не записывается в базу данных.
Клики подсчитываются на сервере. Каждая http ссылка на публичной странице указывает на /go/<id> в вашем собственном домене, который фиксирует клик, а затем отвечает 302 редиректом на реальный адрес назначения. Таким образом, подсчет работает для читателей с отключенным JavaScript, а также внутри браузеров приложений, которые блокируют фоновые запросы. Просмотры страниц записываются на стороне сервера при отрисовке публичной страницы; /api/track обрабатывает события кликов и открытия всплывающих окон.
Стоит учитывать два исключения. Запросы с действительной сессией администратора пропускаются, поэтому редактирование собственной страницы не завышает показатели. Известные user agents поисковых роботов также пропускаются.
О согласии: встроенная аналитика не использует cookie для отслеживания, но правила в отношении cookie также охватывают схожие технологии, включая снятие цифровых отпечатков устройств (fingerprinting). Одно лишь отслеживание без использования cookies не гарантирует, что баннер согласия не требуется. Ваши обязательства по-прежнему зависят от того, где живут ваши читатели, поэтому проверьте их, а также любые внешние аналитические инструменты или встраиваемые элементы, которые вы активируете.
Один нюанс, который удивляет пользователей: при смене SECRET_KEY меняется и ежедневная соль, поэтому с этого момента каждый вернувшийся посетитель будет учитываться как новый.
Почему столбец страны в аналитике пуст?
Потому что в вашем стеке нет компонентов, которые устанавливали бы заголовок страны. LinkBreeze определяет страну на основе прокси-заголовков, таких как cf-ipcountry и x-vercel-ip-country. На VPS, работающем за собственным Caddy или Nginx, эти заголовки отсутствуют, поэтому страна записывается как null, а разбивка остается пустой. Внутри контейнера нет базы данных GeoIP.
Есть два способа заполнить эти данные. Разместите Cloudflare перед доменом и включите функцию Add visitor location headers в разделе Managed Transform, чтобы передавать cf-ipcountry. Либо настройте передачу одного из этих заголовков в вашем reverse proxy на основе локального GeoIP-поиска.
Связанная с этим проблема опаснее, поэтому проверьте её. Обработчики кликов и просмотров считывают адрес клиента сначала из X-Forwarded-For, затем из X-Real-IP, и переходят к 0.0.0.0, если ни один из заголовков не найден. Если опубликовать порт 3000 напрямую в интернет без передачи заголовков адреса, посетители с одинаковым user agent будут иметь общий хеш в течение суток по UTC; разные user agent по-прежнему будут создавать разные хеши, а хеш будет обновляться ежедневно. В этом случае лимиты на количество событий (60 в минуту) для /api/track и /go/<id> будут применяться ко всей вашей аудитории как к одному пользователю с fallback-адресом. При использовании директивы reverse_proxy, указанной выше, Caddy автоматически установит нужный заголовок, и обе проблемы будут решены.
Импорт из Linktree и что не переносится
Мастер миграции в панели управления принимает публичный URL профиля или экспортированный файл. Он распознает страницы linktr.ee, bento.me, lnk.bio, tap.link, hopp.bio, beacons.ai, solo.to, linkfly, mssg.me и LittleLink, а также общие экспорты в форматах HTML и JSON. Для URL Linktree или Bento он считывает __NEXT_DATA__ JSON, который эти страницы содержат. Для статической страницы он считывает теги ссылок.
Переносятся заголовок, URL, описание и изображение каждой ссылки, информация о том, является ли ссылка профилем в социальной сети, а также ваше отображаемое имя, биография и аватар. Вы выбираете, какие из найденных ссылок сохранить, прежде чем данные будут записаны в базу данных.
Не переносятся история аналитики, тема оформления и макет, подписчики электронной почты, запланированные даты публикации и всё то, что старая платформа хранит за собственным логином. Планируйте воссоздание внешнего вида вручную и примите тот факт, что старая история кликов останется на прежнем сервисе.
Импортер запрашивает URL с вашего сервера, а не из вашего браузера, поэтому он отклоняет адреса, которые не являются публичными. Private/local URLs are not allowed означает, что вы указали адрес внутри вашей собственной сети, и этот отказ намерен: без него любой пользователь с доступом к панели управления мог бы использовать ваш сервер для сканирования машин, доступных только вашему серверу. Другие сообщения, которые вы можете увидеть: Only http and https URLs are allowed, Request timed out и Response too large.
Парсинг зависит от разметки стороннего ресурса. В версии v1.5.1 импортер исправляет ошибку Linktree, из-за которой подтягивались партнерские ссылки платформы вместо собственных ссылок профиля. Обновитесь перед импортом из Linktree; профили, ссылки которых отрисовываются только в браузере, по-прежнему требуют использования вкладки File или ручного ввода. Если мастер ничего не находит на странице, где явно есть ссылки, добавьте их вручную, не дожидаясь исправления. Если вам нужны измеримые короткие ссылки, а не страница профиля, самохостируемый сокращатель ссылок, например Shlink справится с этой задачей и будет успешно работать на том же сервере.
Обновление зафиксированного развертывания
# edit the image tag in docker-compose.yml, then
docker compose pull
docker compose up -d
docker compose logs -f linkbreezeМиграции схемы выполняются автоматически при запуске контейнера. Документированного способа выполнить их в обратном порядке не существует, поэтому сначала создайте копию тома. Обновление, которое нельзя отменить, безопасно только в том случае, если вы можете восстановить состояние, которое было до него.
Панель управления должна отображать баннер при появлении нового релиза. Зафиксированная версия v1.4.1 проверяет небольшой файл версии на GitHub; начиная с v1.5.0, выпущенной 24 октября 2026 года, проверка баннера запрашивает linkbreeze.omnirise.dev/latest-version.json. Результаты кэшируются на 24 часа, но кнопка ручной проверки Check now обходит этот кэш, в том числе в версии v1.4.1. Эти проверки не отправляют данные об экземпляре в теле запроса. В журнале изменений указано, что версии с v1.2.0 по v1.4.0 опрашивали адрес, который отвечал 404, и баннер никогда не отображался. Пока вы не запустите версию с веб-эндпоинтом, не ждите появления баннера: следите за журналом изменений на linkbreeze.omnirise.dev/changelog самостоятельно. В версии v1.5.1 в разделе Settings также появилась карточка статуса обновления, которая проверяет GitHub и веб-сайт, с кнопкой Recheck, обходящей кэш. Прочитайте примечания к выпуску перед тем, как менять тег, поскольку на данном этапе проекта минорная версия может изменить настройки по умолчанию, от которых вы зависите.
Типичные ошибки и сообщения, которые вы увидите
manifest unknown при выполнении pull. Тег указан в неверном формате для данного релиза. Начиная с версии v1.4.0, теги содержат v, поэтому используйте :v1.4.1. Релизы в GHCR до версии v1.3.2 используют только цифры, например :1.2.7, а Docker Hub также содержит теги новых версий, такие как v1.5.1.
no matching manifest for linux/arm64/v8 in the manifest list entries. Вы зафиксировали версию (pin) до v1.4.0, которая была выпущена только для архитектуры amd64. Измените фиксацию на v1.4.1, где есть сборка для arm64. 32-битная плата arm/v7 выдает такую же ошибку на любом релизе, так как сборка под эту платформу не предусмотрена.
Контейнер сообщает unhealthy, хотя страница загружается нормально. Healthcheck в вашем файле compose вызывает curl, которого нет в образе. Удалите его и позвольте работать встроенному в образ healthcheck wget.
Caddy выдает ошибку сертификата или не отвечает. Проверьте docker compose logs caddy. Убедитесь, что A-запись указывает на этот VPS и что порты 80 и 443 доступны: Caddy может пройти валидацию через HTTP-челлендж на порту 80 или TLS-ALPN-челлендж на порту 443.
Количество уникальных посетителей застыло на отметке 1. Проверьте, устанавливает ли прокси заголовки X-Forwarded-For или X-Real-IP. Без любого из этих заголовков посетители с одинаковыми user agent получают общий хеш в течение суток (UTC); хеш также включает ежедневную соль, поэтому отсутствие заголовков не приводит к тому, что хеш всех посетителей совпадает постоянно.
Контейнер завершает работу сразу после запуска, хотя вчера всё работало. Если вы перешли с именованного тома на bind mount, директория с данными принадлежит пользователю root, а приложение работает от uid 1000, поэтому оно не может открыть файл базы данных. Выполните sudo chown -R 1000:1000 для директории на хосте.
Запросы отслеживания возвращают HTTP 429. Сработало ограничение по количеству запросов на IP-адрес для /api/track. Отдельный лимит для /go/<id> пропускает запись клика, но всё равно возвращает редирект 302 на целевую страницу.
FAQ
Готов ли LinkBreeze для публичного использования в качестве ссылки в профиле?
Это молодой проект, первый релиз которого датирован 1 июля 2026 года. В период с этой даты по 23 сентября 2026 года, когда вышла версия v1.4.1, было выпущено 22 релиза, большинство из них — до середины августа, поэтому поведение системы быстро менялось. Релизы v1.5.0 и v1.5.1 вышли 24 и 27 октября 2026 года, а основной репозиторий на GitHub стал публичным 2 ноября 2026 года. Лицензия MIT и локальный файл SQLite означают, что страница продолжит работать, даже если разработка прекратится. Однако публичное веб-приложение без обновлений безопасности становится фактором риска, поэтому рассматривайте его как ПО, которое требует регулярного обновления, а не как решение для однократной установки.
Какой тег образа LinkBreeze следует использовать?
Используйте тег версии, например docker.io/omnirise/linkbreeze:v1.4.1, и меняйте его осознанно. Начиная с версии v1.4.0, процесс сборки отправляет в реестр тег latest и git-тег с префиксом v, поэтому тег :1.4.1 без v не существует, и Docker вернет ошибку manifest unknown. Для релизов до v1.3.2 ситуация обратная: в GHCR доступны только голые номера версий. Начиная с v1.4.0, образ собирается для архитектур linux/amd64 и linux/arm64, поэтому VPS на базе arm64 загружает его напрямую без необходимости локальной сборки.
Почему статистика по странам в LinkBreeze остается пустой?
LinkBreeze считывает страну посетителя из заголовков прокси, таких как cf-ipcountry или x-vercel-ip-country, и не содержит собственной базы данных GeoIP. VPS, работающий за вашим собственным Caddy или Nginx, не передает эти заголовки, поэтому страна сохраняется как null. Разместите Cloudflare перед доменом и включите функцию Add visitor location headers в разделе Managed Transform, либо настройте ваш reverse proxy так, чтобы он добавлял один из этих заголовков на основе локального GeoIP-запроса.
Что именно нужно резервировать и как выполнять восстановление?
Создавайте резервную копию всего тома linkbreeze-data, а не только файла базы данных. В /app/data/linkbreeze.db хранятся все ссылки, страницы, настройки, подписчики и записи аналитики, а в /app/data/uploads — аватары и миниатюры изображений, на которые ссылается страница. Остановите контейнер, выполните docker compose cp linkbreeze:/app/data ./backup-$(date +%F), затем запустите его снова. Восстановление выполняется путем копирования директории обратно в остановленный контейнер и его последующего запуска. Экспорт в формате JSON из панели управления — это лишь снимок конфигурации профиля, ссылок, настроек, тем и шрифтов; он не содержит данных аналитики и изображений.
Переносятся ли аналитика и тема при импорте из Linktree?
Нет. Мастер миграции считывает заголовки ссылок, URL-адреса, описания и изображения из вашего старого публичного профиля, а также отображаемое имя, биографию и аватар. История аналитики, тема оформления, список подписчиков и даты запланированных публикаций не переносятся. После импорта настройте внешний вид в редакторе тем; история кликов останется на старой платформе.