Karakeep

Обзор

Karakeep собирает ссылки, текстовые заметки, изображения и PDF в личной библиотеке. Списки, теги, избранное и полнотекстовый поиск подходят для исследований, домашних справочников и отложенного чтения. Официальные приложения Android и iOS и расширения браузера отправляют материалы на сервер; отдельный настольный клиент не входит в рецепт.

При сравнении с Linkwarden оцените списки, сохраняемые форматы, совместный доступ и поиск. Karakeep также хранит обычные текстовые заметки рядом со ссылками. Добавление URL не гарантирует сохранения страницы за платным доступом, входом или защитой от ботов.

Рецепт запускает официальное приложение с SQLite, Meilisearch 1.41.0 и отдельным браузером. Планируйте два ядра, минимум 2 ГБ RAM (рекомендуется 4 ГБ) и 10 ГБ диска плюс сохранённые материалы. Задания браузера могут потребовать больше; следите за диском и памятью. Надёжный уровень развёртывания не поддерживается: в этом рецепте одного сервера нет внешней базы, мониторинга и лимитов ресурсов.

Upstream поддерживает пароль и встроенный OIDC; рецепт настраивает только пароль. SAML, второй фактор, вход по доверенному заголовку, SMTP и AI-провайдер не настроены. AI-теги необязательны: сохранение и поиск работают без API-ключа. Сквозного шифрования резервных копий нет.

Лицензия приложения — AGPL-3.0, рецепта — MIT. Перед изменением и сетевым предоставлением программы прочитайте лицензию upstream. Карточка остаётся экспериментальной до появления более широкого опыта эксплуатации.

Источники: возможности и клиенты, настройка, безопасность, релиз, лицензия.

Оценка безопасности

В проверенной конфигурации регистрация закрыта, а внутренние порты не публикуются. Базовая защита от SSRF и изоляция контейнеров не делают враждебные страницы безопасными. Допускайте доверенные учётные записи и задавайте отдельную политику исходящего трафика. Этот обзор не является аудитом безопасности.

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

Подготовка сервера

Используйте 64-битную Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Планируйте два ядра, минимум 2 ГБ RAM (рекомендуется 4 ГБ) и 10 ГБ диска плюс сохранённые материалы. Это ориентиры для планирования, а не результат нагрузочного теста.

mkdir -p ~/services/karakeep
cd ~/services/karakeep
# Скопируйте сюда все файлы рецепта, включая proxy/ и скрипты.
cp .env.example .env
chmod 600 .env
openssl rand -hex 32
openssl rand -hex 32

Запишите два разных сгенерированных значения в KARAKEEP_AUTH_SECRET и KARAKEEP_MEILI_KEY. Скрипты подключают .env как доверенную конфигурацию shell. Используйте безопасные для shell значения и ограничьте доступ других пользователей.

Именованный том data содержит SQLite, загрузки, сохранённые страницы и состояние очередей в /data. Том search хранит индекс Meilisearch в /meili_data. Состояние Chrome временное. Compose привязывает оба тома к проекту; сохраняйте имя проекта. Порты API поиска и DevTools браузера не публикуются.

Запуск и создание учётной записи

Не включайте reverse proxy. Задайте KARAKEEP_DISABLE_SIGNUPS=false, затем:

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:3000/api/health

На своём компьютере выполните ssh -L 3000:127.0.0.1:3000 user@server. Откройте http://localhost:3000, зарегистрируйтесь с уникальным паролем и проверьте вход. Задайте KARAKEEP_DISABLE_SIGNUPS=true и пересоздайте приложение:

docker compose up -d --wait --wait-timeout 600 karakeep

Публикуйте прокси только после закрытия регистрации. Готовых учётных данных в рецепте нет. Для дополнительных пользователей нужно ещё одно контролируемое окно регистрации. AI, SMTP и OIDC не настроены. Добавляйте внешний AI-ключ только после согласия с условиями обработки данных и оплаты.

VPS

Сначала создайте учётную запись через туннель. Задайте KARAKEEP_URL=https://keep.example.com, настройте DNS и HTTPS-прокси и пересоздайте Karakeep. Разрешите в firewall только SSH, HTTP и HTTPS. Оставьте порт 3000 на loopback и храните зашифрованные копии вне сервера.

Доверенная локальная сеть

Используйте SSH-туннель или HTTPS-прокси, доступный из доверенной LAN/VPN. Для прокси на хосте сохраняйте loopback-привязку. Если намеренно публикуете приватный интерфейс, ограничьте его firewall и задайте в KARAKEEP_URL точный origin пользователей. Не открывайте окно регистрации недоверенным пользователям.

Домен и HTTPS

Выберите пример в proxy/. Caddy получает сертификаты; Nginx нужны пути к сертификатам; Traefik — точка входа websecure и resolver letsencrypt. Эти примеры прокси на хосте направляют запросы на 127.0.0.1:3000. Контейнерный прокси должен иметь общую сеть с Karakeep и использовать karakeep:3000; его loopback не является loopback хоста.

Замените домен и задайте в KARAKEEP_URL тот же внешний origin. Правильно передавайте Host и X-Forwarded-Proto; HTTPS-origin включает secure cookies. Пример Nginx допускает тело запроса до 50 МБ. Проверьте вход и загрузку по итоговому URL. Не публикуйте порты 7700 и 9222.

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

./backup.sh

Скрипт останавливает Karakeep и Meilisearch, архивирует оба полных тома, активный .env и Compose, затем запускает только ранее работавшие сервисы. Приватный архив — backups/karakeep-<timestamp>.tar. SQLite и WAL нужно копировать вместе при остановленной записи. Храните индекс вместе с подходящей версией поискового движка.

Зашифруйте архив и скопируйте вне сервера. Он содержит учётные записи, приватные заметки, страницы, файлы, ключи и секреты. Личный экспорт и CLI-миграция между серверами не заменяют эту копию.

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

Восстановление заменяет оба тома. Используйте доверенный архив и совпадающие версии приложения и Meilisearch. На новом сервере скопируйте рецепт, изучите архивные compose.yaml и configuration.env и сначала создайте совместимую активную конфигурацию. Архивная конфигурация автоматически не активируется.

docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/karakeep-TIMESTAMP.tar
curl --fail http://127.0.0.1:3000/api/health

Скрипт проверяет состав архива, создаёт страховочную копию, заменяет тома и ждёт healthcheck. Если замена прервана, оставьте сервисы остановленными до восстановления проверенного архива. Войдите, прочитайте приватную заметку, откройте сохранённый файл и найдите известный материал. Smoke-тест проверяет учётную запись, приватную заметку и файл после удаления обоих исходных томов; он не доказывает восстановление между версиями.

Обновление

1. Прочитайте release notes и создайте копию вне сервера.
2. Измените KARAKEEP_VERSION на проверенную точную версию. Отдельно закреплённый образ Chrome меняйте после проверки его релиза и совместимости.
3. Выполните docker compose pull, затем docker compose up -d --wait --wait-timeout 600. Проверьте логи, вход, сохранённую страницу и поиск.
4. Смена версии Meilisearch — отдельная миграция. Следуйте официальному руководству: полная копия, параметр миграции именно для выбранной версии движка, затем удаление этого параметра. Не запускайте новый движок на старых данных без миграции или осознанного пересоздания индекса.

Миграции приложения выполняются при запуске. Не используйте теги latest и release. Успешный healthcheck сам по себе не доказывает сохранность поиска и материалов.

Откат

Не запускайте старое приложение на мигрировавшей SQLite или старый Meilisearch на новом индексе.

1. Сохраните архив до обновления и соответствующие рецепт и конфигурацию.
2. Остановите запись: docker compose stop karakeep meilisearch.
3. Верните точные старые версии приложения и вспомогательных образов в активных Compose и .env; сохраните подходящие секреты. Скачайте эти образы.
4. Выполните docker compose create, не запуская их на новых данных.
5. Выполните ./restore.sh ./backups/karakeep-BEFORE-UPDATE.tar, затем проверьте вход, заметки, файлы и поиск. Страховочная копия умеет архивировать остановленные контейнеры без запуска старого приложения на новом состоянии.

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

docker compose down сохраняет тома. После проверки зашифрованной внешней копии docker compose down --volumes навсегда удаляет библиотеку и индекс. Удаление каталога рецепта также удаляет локальную конфигурацию и копии. Не используйте глобальную очистку Docker.

Источники: Docker, настройка, безопасность, ограничения миграции.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Ошибка запуска или healthcheck

Выполните docker compose ps --all и docker compose logs --tail=200 karakeep meilisearch chrome. Проверьте диск и RAM через df -h и free -m. Заданиям браузера нужно больше памяти, чем простаивающему приложению. Убедитесь, что заменили оба секрета и сохранили ключ Meilisearch между перезапусками. docker compose config --quiet проверяет подстановки; не публикуйте полную итоговую конфигурацию с секретами.

Не работает вход или пропадают cookies

Проверьте, что KARAKEEP_URL точно совпадает с открытым origin, включая схему и нестандартный порт. HTTPS-origin требует HTTPS и правильных forwarded-заголовков. Для первого запуска используйте http://localhost:3000 через SSH-туннель. Регистрация намеренно отключена; временно включайте её только в доверенном окне настройки, затем закройте и пересоздайте приложение. OIDC и SMTP требуют дополнительной настройки upstream и не входят в рецепт.

Страница не сохраняется

Проверьте health Chrome и логи краулера. Платный доступ, вход, защита от ботов, большие файлы и неподдерживаемые сайты могут мешать сохранению. Внутренние адреса по умолчанию блокируются; не отключайте защиту от SSRF ради произвольной закладки. Приложению и браузеру нужен исходящий доступ. Не публикуйте отладочный порт Chrome как способ устранения проблемы.

Поиск сломался после смены движка

Найдите в логах Meilisearch сообщение о несовместимой версии базы. Верните старый движок вместе с подходящей полной копией либо выполните официальную миграцию/пересоздание индекса. Не удаляйте том всей библиотеки ради пересоздания поискового индекса.

Ошибка копирования или восстановления

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

Источники: настройка, безопасность, обновление Meilisearch.