Linkwarden

Обзор

Linkwarden — менеджер закладок и web-архив для одного пользователя, семьи или небольшой команды. Он собирает ссылки в коллекции, добавляет теги, выполняет полнотекстовый поиск и сохраняет страницы, документы и снимки для чтения после исчезновения оригинала. Есть совместные коллекции, browser extension и официальные Android/iOS-клиенты.

Рецепт запускает закреплённый Linkwarden v2.16.2 с PostgreSQL 16 и Meilisearch 1.13.3. Приложение сохраняет архивы в отдельном volume, база и поисковый индекс также постоянны. Web-порт доступен только на localhost, внутренние сервисы не публикуются, а сохранённый HTML обслуживается через отдельный origin.

Безопасность и границы рецепта

Полный HTTP smoke-тест прошёл на amd64; backup и restore практически не проверялись. Headless browser получает недоверенные URL и может расходовать много CPU, RAM и диска. Доступ к private network и insecure TLS принудительно запрещён, но это не заменяет egress firewall для недоверенных пользователей. Сохранённый HTML изолирован отдельным origin без общих cookies. Регистрация поставляется открытой, чтобы можно было создать первую учётную запись, и сама не закрывается: сразу после регистрации задайте NEXT_PUBLIC_DISABLE_REGISTRATION=true и пересоздайте контейнер, иначе зарегистрироваться сможет любой, кто дошёл до адреса.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Нужны Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Выделите минимум 2 CPU, 2 ГБ RAM и 5 ГБ диска; рекомендуется 4 ГБ RAM и отдельный запас диска под web-архивы. Официальный образ заявляет amd64 и arm64.

docker --version
docker compose version

2. Подготовьте рецепт и независимые секреты

mkdir -p ~/services/linkwarden
cd ~/services/linkwarden
cp .env.example .env
chmod 600 .env
nextauth_secret="$(openssl rand -hex 32)"
postgres_password="$(openssl rand -hex 32)"
meili_key="$(openssl rand -hex 32)"
sed -i "s|^NEXTAUTH_SECRET=.*|NEXTAUTH_SECRET=$nextauth_secret|" .env
sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$postgres_password|" .env
sed -i "s|^MEILI_MASTER_KEY=.*|MEILI_MASTER_KEY=$meili_key|" .env
unset nextauth_secret postgres_password meili_key

Все три секрета обязательны, должны отличаться и не меняться после первого запуска. Hex-значение безопасно внутри PostgreSQL URL. Сохраните секреты в менеджере паролей.

Все переменные .env:

• LINKWARDEN_PORT — локальный web-порт, по умолчанию 3000;
• LINKWARDEN_URL — точный внешний URL основного приложения без завершающего /;
• LINKWARDEN_USER_CONTENT_URL — отдельный HTTPS origin для сохранённого HTML, желательно на другом registrable domain и без общих cookies;
• NEXT_PUBLIC_DISABLE_REGISTRATION — false только для создания первого account, после чего обязательно true;
• NEXTAUTH_SECRET — постоянный секрет сессий и токенов NextAuth;
• POSTGRES_PASSWORD — отдельный URL-safe пароль PostgreSQL;
• MEILI_MASTER_KEY — отдельный master key Meilisearch;
• POSTGRES_DB и POSTGRES_USER — имя базы и роли, меняются только до первого запуска;
• LINKWARDEN_TIME_ZONE — часовой пояс IANA;
• LINKWARDEN_DATA_VOLUME, LINKWARDEN_DB_VOLUME и LINKWARDEN_MEILI_VOLUME — имена volumes для архивов, PostgreSQL и поискового индекса;
• LINKWARDEN_BACKUP_DIR — каталог итоговых архивов на хосте.

NEXTAUTH_URL рецепт формирует как ${LINKWARDEN_URL}/api/v1/auth, а BASE_URL равен LINKWARDEN_URL. Не задавайте auth URL без /api/v1/auth.

3. Запустите и закройте регистрацию

docker compose config
docker compose pull
docker compose up -d --wait --wait-timeout 900
docker compose ps
curl -I http://127.0.0.1:3000/

Откройте LINKWARDEN_URL, создайте первую учётную запись, затем немедленно задайте NEXT_PUBLIC_DISABLE_REGISTRATION=true и примените настройку:

docker compose up -d --force-recreate linkwarden

Проверьте в приватном окне, что регистрация больше недоступна. Не публикуйте сервис до выполнения этого шага.

Запуск на VPS

Оставьте bind 127.0.0.1:${LINKWARDEN_PORT}:3000: снаружи приложение доступно только через HTTPS proxy на хосте. PostgreSQL и Meilisearch не имеют published ports. В firewall откройте только SSH, HTTP и HTTPS. Создайте DNS для основного и user-content origins до первого запуска.

Доступ в доверенной локальной сети

Предпочтителен SSH-туннель ssh -L 3000:127.0.0.1:3000 user@server; для него используйте LINKWARDEN_URL=http://localhost:3000. Для постоянного LAN-доступа замените localhost bind на конкретный private IP, задайте совпадающий URL и ограничьте порт firewall. Не используйте 0.0.0.0 без сетевых ограничений. Без HTTPS отдельная origin-изоляция сохранённого контента слабее, поэтому этот режим подходит только доверенной сети.

Домен, HTTPS и сохранённый HTML

Укажите LINKWARDEN_URL=https://links.example.com и отдельный LINKWARDEN_USER_CONTENT_URL=https://saved.example.net, затем замените оба host в Caddy, Nginx или Traefik. Для лучшей изоляции используйте другой registrable domain, а не поддомен основного приложения, и не задавайте общие parent-domain cookies. Сертификат должен покрывать оба host; в Nginx замените пример путями к подходящему SAN либо отдельным сертификатам. Proxy должен поддерживать WebSocket и сохранять Host/X-Forwarded-Proto.

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает Linkwarden и Meilisearch, оставляет PostgreSQL работающим для native pg_dump, архивирует /data/data, /meili_data, .env и Compose, после чего запускает сервисы. UI JSON export не является полным backup: в нём нет сохранённых страниц, документов и извлечённого текста. Архив содержит секреты и пользовательский контент: зашифруйте его, скопируйте за пределы сервера и регулярно проверяйте restore.

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

Restore необратимо заменяет приложение, PostgreSQL и индекс Meilisearch. Используйте те же версии Linkwarden, PostgreSQL и Meilisearch и активный .env:

./restore.sh ./backups/linkwarden-YYYYMMDDTHHMMSSZ.tar
curl -I http://127.0.0.1:3000/

Скрипт сначала делает страховочный backup текущего состояния, пересоздаёт три volumes, восстанавливает dump и запускает стек. Сохранённый configuration.env оставляется только для сравнения. Практический restore ещё не проверен; сначала испытайте копию на отдельном сервере.

Обновление Linkwarden

Сделайте backup, прочитайте release notes и замените точный тег ghcr.io/linkwarden/linkwarden:v2.16.2 на проверенную версию. Не используйте latest и не обновляйте одновременно PostgreSQL либо Meilisearch:

docker compose pull
docker compose up -d --wait --wait-timeout 900
curl -I http://127.0.0.1:3000/
docker compose logs --tail=200 linkwarden postgres meilisearch

Миграции базы выполняются при запуске приложения. PostgreSQL major update требует нового пустого volume и восстановления native dump. Смена major Meilisearch требует проверки его upgrade guide; храните старый volume до проверки поиска.

Откат

Не запускайте старый Linkwarden поверх базы после новых migrations. Верните все прежние точные теги и восстановите полный pre-update архив через restore.sh. После неудачной смены PostgreSQL или Meilisearch подключайте прежний образ только к сохранённому старому volume либо восстанавливайте совместимый dump/backup в пустой volume.

Остановка и полное удаление

docker compose down сохраняет данные. После проверки внешнего backup удалить всё безвозвратно:

docker compose down
docker volume rm linkwarden-data linkwarden-postgres linkwarden-meilisearch
rm -rf ~/services/linkwarden

Если имена volumes изменены в .env, подставьте фактические значения.

Источники: self-hosting setup, environment variables, user-content domain, release v2.16.2 и PostgreSQL upgrades.

Диагностика

Linkwarden не становится healthy

docker compose ps
docker compose logs --tail=200 linkwarden postgres meilisearch
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q linkwarden)"
curl -I http://127.0.0.1:3000/

Проверьте три обязательных разных секрета, состояние зависимостей, свободные RAM и диск. POSTGRES_PASSWORD должен быть URL-safe, потому что входит в DATABASE_URL. Не удаляйте volumes рабочей установки при диагностике.

Redirect или вход ведёт на неверный URL

LINKWARDEN_URL должен точно совпадать с внешней схемой и host без завершающего /. Рецепт передаёт NEXTAUTH_URL=${LINKWARDEN_URL}/api/v1/auth и BASE_URL=${LINKWARDEN_URL}. После изменения пересоздайте Linkwarden и удалите старые cookies. Убедитесь, что proxy передаёт исходный Host и X-Forwarded-Proto=https.

Регистрация всё ещё доступна

Задайте NEXT_PUBLIC_DISABLE_REGISTRATION=true, выполните docker compose up -d --force-recreate linkwarden и проверьте страницу в приватном окне. Простого restart недостаточно, если контейнер не был пересоздан.

Сохранённая страница не открывается или использует основной origin

Проверьте LINKWARDEN_USER_CONTENT_URL, DNS, TLS и второй host в proxy. Origin должен отличаться от основного приложения и не разделять с ним cookies. Не обходите проблему, включая private network access либо insecure TLS.

Не сохраняется внутренний или self-signed URL

Это ожидаемая защита: ALLOW_PRIVATE_NETWORK_ACCESS=false и ALLOW_INSECURE_TLS=false закреплены в Compose. Не ослабляйте их для общего instance. Для доверенного внутреннего ресурса предпочтительнее публичный валидный HTTPS endpoint или отдельный изолированный instance с egress firewall.

Поиск не возвращает новые закладки

docker compose logs --tail=200 meilisearch linkwarden
docker compose exec meilisearch curl --fail http://127.0.0.1:7700/health

Убедитесь, что MEILI_MASTER_KEY одинаков у обоих сервисов и volume не заполнен. Не удаляйте индекс до полного backup. Если upstream предлагает штатную переиндексацию для этой версии, запустите её только после сохранения PostgreSQL и архивов.

Ошибка 502 от reverse proxy

С хоста выполните curl -I http://127.0.0.1:3000/. Проверьте upstream, firewall и namespace proxy. Из контейнера 127.0.0.1 указывает на сам proxy-контейнер, а не Linkwarden на хосте; используйте host gateway или общую закрытую сеть.