Хранение закладок: karakeep с AI‑тегированием

Полный гайд по установке и настройке karakeep — self-hosted приложения для хранения закладок, заметок и изображений с AI-тегированием и полнотекстовым поиском.

Не указано

Алексей Кузнецов

Системный администратор23 января 2026 г.

sudo apt update && sudo apt upgrade -y
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y
sudo usermod -aG docker $USER
newgrp docker
sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

git clone https://github.com/karakeep-app/karakeep.git
cd karakeep
cp .env.example .env
nano .env

# Установка Ollama (следуйте инструкциям на ollama.ai)
# Запуск Ollama:
ollama serve
# В другой консоли:
ollama pull mistral

# В .env добавьте:
AI_ENABLED=true
OLLAMA_URL=http://host.docker.internal:11434

docker-compose up -d --build
docker-compose logs -f app

Пример URL для добавления закладки:
http://<ваш_ip>:3000/add?url=https://example.com

# В docker-compose.yml раскомментируйте:
# meilisearch:
#   image: getmeili/meilisearch:latest
#   environment:
#     - MEILISEARCH_MASTER_KEY=your_master_key
#   ports:
#     - "7700:7700"
#   volumes:
#     - meili_data:/meili_data

# В .env добавьте:
SEARCH_PROVIDER=meilisearch
MEILISEARCH_URL=http://meilisearch:7700
MEILISEARCH_KEY=your_master_key

docker-compose up -d

# Установка Nginx и Certbot:
sudo apt install nginx certbot python3-certbot-nginx -y

# Создание конфига Nginx (/etc/nginx/sites-available/karakeep):
server {
    listen 80;
    server_name yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Активация и получение SSL:
sudo ln -s /etc/nginx/sites-available/karakeep /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d yourdomain.com

# Ручной бэкап БД:
docker-compose exec db pg_dump -U karakeep_user karakeep > backup_$(date +%Y%m%d).sql

# Бэкап файлов:
tar -czf karakeep_files.tar.gz /путь/к/karakeep/data/uploads

# Автоматизация через cron (ежедневно в 2:00):
0 2 * * * cd /путь/к/karakeep && docker-compose exec db pg_dump -U karakeep_user karakeep > /backups/karakeep_$(date +\%Y\%m\%d).sql

Гайд по развертыванию самодельного склада закладок karakeep с AI-тегированием и полнотекстовым поиском

Введение: Зачем нужен самодельный менеджер закладок?

Современные менеджеры закладок, такие как Raindrop.io или Pocket, предлагают удобство, но часто страдают от ограничений: зависимость от облачных сервисов, проблемы с конфиденциальностью, отсутствие гибкой настройки или высокая стоимость премиум-функций. Самодельное решение, как karakeep, позволяет взять контроль над своими данными. Это локально развертываемое приложение, которое хранит все закладки, заметки и изображения на вашем сервере. Основные преимущества:

• Контроль данных: Никакой передачи информации третьим сторонам. Все остается на вашем железе.
• Настраиваемость: Возможность интеграции с внешними сервисами, такими как AI-модели для автоматической классификации.
• Масштабируемость: Подходит как для личного использования, так и для небольших команд.

Karakeep особенно актуален для тех, кто хочет объединить закладки, заметки и медиа в одном месте с продвинутыми функциями поиска. В этом гайде мы разберем полный процесс развертывания, от подготовки окружения до настройки безопасности.

Особенности karakeep: AI-тегирование, полнотекстовый поиск, хранение ссылок, заметок и изображений

Karakeep — это open-source проект (доступен на GitHub), построенный на стеке Node.js и базе данных PostgreSQL. Он поддерживает ключевые функции:

• AI-тегирование: Интеграция с внешними LLM (например, через API Ollama или OpenAI) для автоматического присвоения тегов на основе содержимого страниц. Это упрощает организацию: система анализирует текст и предлагает релевантные категории (например, "технологии", "новости").
• Полнотекстовый поиск: Использует встроенный движок (на базе PostgreSQL или подключаемых индексаторов вроде Meilisearch) для поиска не только по заголовкам, но и по содержимому страниц, заметок и извлеченным текстам из изображений (через OCR).
• Хранение разнообразных данных: Поддержка ссылок, текстовых заметок, изображений (с кэшированием для быстрого доступа). Данные хранятся в базе, что обеспечивает целостность и возможность резервного копирования.
• Дополнительно: Веб-интерфейс с возможностью импорта/экспорта, поддержка RSS-лент, адаптивный дизайн для мобильных устройств.

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

Предварительные требования и подготовка окружения (Docker, сервер)

Для развертывания karakeep потребуется сервер с установленным Docker. Проект использует Docker Compose для оркестрации контейнеров (приложение, база данных, опционально — AI-сервис).

Минимальные требования к серверу:

• Операционная система: Linux (Ubuntu/Debian рекомендуется), macOS или Windows с WSL2.
• Аппаратные ресурсы:
  • CPU: 2+ ядра (для AI-функций — 4+ ядра).
  • RAM: 4+ ГБ (8+ ГБ для больших баз с полнотекстовым поиском).
  • Дисковое пространство: 10+ ГБ (зависит от объема закладок и изображений; PostgreSQL + индексы могут занимать много места).
  • Сеть: Статический IP или доступ к домену для внешнего доступа.
• Программное обеспечение:
  • Docker: Версия 20.10+.
  • Docker Compose: Версия 2.20+.
  • Git: Для клонирования репозитория.

Установка Docker и Docker Compose (Ubuntu/Debian):

1. Обновите пакеты:

   sudo apt update && sudo apt upgrade -y
   

2. Установите Docker:

   sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt update
   sudo apt install docker-ce docker-ce-cli containerd.io -y
   sudo usermod -aG docker $USER  # Добавьте текущего пользователя в группу docker
   newgrp docker  # Примените изменения без перелогина
   

3. Установите Docker Compose:

   sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
   sudo chmod +x /usr/local/bin/docker-compose
   docker-compose --version  # Проверка
   

4. Для AI-тегирования (опционально): Установите Ollama для локальной работы с LLM (например, Mistral). Следуйте инструкциям на ollama.ai. Запустите сервис:

   ollama serve
   

Если сервер недоступен напрямую (например, за NAT), настройте проброс портов или используйте VPN. Для продакшена рекомендую VPS от проверенных провайдеров (например, Hetzner, DigitalOcean).

Пошаговая установка karakeep: конфигурация docker-compose.yml

Karakeep поставляется с готовым docker-compose файлом. Мы развернем его на локальном сервере.

Шаг 1: Клонирование репозитория

Перейдите в домашнюю директорию и клонируйте проект:

git clone https://github.com/karakeep-app/karakeep.git
cd karakeep

Шаг 2: Настройка переменных окружения

Создайте файл .env в корне проекта (на основе примера .env.example):

cp .env.example .env
nano .env  # Редактируйте необходимые параметры

Ключевые переменные:

• POSTGRES_USER и POSTGRES_PASSWORD: Логин и пароль для БД (замените на надежные).
• POSTGRES_DB: Имя базы данных (например, karakeep).
• JWT_SECRET: Секретный ключ для аутентификации (генерируйте случайно: openssl rand -hex 32).
• API_URL: URL для доступа к API (для локального теста: http://localhost:3000).
• AI_ENABLED: true для включения AI-тегирования (требует Ollama или API OpenAI).

Пример .env:

POSTGRES_USER=karakeep_user
POSTGRES_PASSWORD=strong_password_here
POSTGRES_DB=karakeep
JWT_SECRET=your_jwt_secret_here
API_URL=http://localhost:3000
AI_ENABLED=true
OLLAMA_URL=http://host.docker.internal:11434  # Для доступа к Ollama из контейнера

Шаг 3: Конфигурация docker-compose.yml

Файл docker-compose.yml уже в репозитории, но проверьте его содержимое. Вот основной фрагмент (с комментариями):

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"  # Веб-интерфейс
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      - JWT_SECRET=${JWT_SECRET}
      - API_URL=${API_URL}
      - AI_ENABLED=${AI_ENABLED}
      - OLLAMA_URL=${OLLAMA_URL}
    depends_on:
      - db
    volumes:
      - ./data/uploads:/app/uploads  # Хранение изображений
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"  # Для доступа извне (опционально, ограничьте брандмауэром)
    restart: unless-stopped

  # Опционально: Для полнотекстового поиска (если не используете встроенный PostgreSQL)
  # meilisearch:
  #   image: getmeili/meilisearch:latest
  #   environment:
  #     - MEILISEARCH_MASTER_KEY=your_master_key
  #   ports:
  #     - "7700:7700"
  #   volumes:
  #     - meili_data:/meili_data

volumes:
  postgres_data:
  # meili_data:

Если используете Meilisearch для ускоренного поиска, раскомментируйте соответствующий блок и добавьте в .env MEILISEARCH_URL=http://meilisearch:7700 и MEILISEARCH_KEY=your_master_key.

Шаг 4: Запуск

1. Соберите и запустите контейнеры:

   docker-compose up -d --build
   

2. Проверьте логи:

   docker-compose logs -f app
   

3. Приложение будет доступно по http://localhost:3000 (или IP вашего сервера: http://<server_ip>:3000).

Если возникает ошибка (например, порт занят), измените порт в docker-compose.yml (например, 3001:3000).

Первоначальная настройка и регистрация аккаунта

После запуска откройте браузер и перейдите на http://<server_ip>:3000. Вы увидите экран приветствия.

1. Регистрация администратора:

   • Нажмите "Sign Up".
   • Введите email и пароль (рекомендую использовать менеджер паролей).
   • Для первого аккаунта автоматически назначаются права администратора.
   • Если AI включен, система предложит настроить интеграцию на этом этапе.

2. Первоначальная конфигурация:

   • В настройках (Settings) задайте название базы, часовой пояс и язык интерфейса (русский поддерживается частично, английский — полностью).
   • Импортируйте существующие закладки из браузера (Chrome, Firefox) или файла JSON/HTML (опция в интерфейсе).
   • Настройте расширение браузера (если доступно) для быстрого добавления.

3. Проверка подключения:

   • Убедитесь, что база данных заполнена (проверьте логи db контейнера).
   • Если AI включен, выполните тестовый запрос в настройках AI.

Как добавлять и организовывать закладки: интерфейс и функции

Karakeep предлагает интуитивный веб-интерфейс, напоминающий Trello или Notion.

Добавление закладок:

1. Нажмите "+" в правом верхнем углу.
2. Вставьте URL, и система автоматически извлечет заголовок, описание и изображение (через пакетный обработчик).
3. Для заметок: Используйте текстовый редактор с поддержкой Markdown.
4. Для изображений: Загрузите файл (лимит ~10 МБ на файл, настраивается в .env как MAX_UPLOAD_SIZE).

Организация:

• Коллекции (Collections): Группируйте закладки по темам (например, "Работа", "Личное"). Создавайте через боковое меню.
• Теги: Присваивайте вручную или автоматически (AI-тегирование). Фильтруйте по тегам в поиске.
• Избранное: Отмечайте звездочкой для быстрого доступа.
• Интерфейс: Главная страница — список закладок с предпросмотром. Используйте сортировку по дате, имени или тегам. Мобильная версия адаптивна.

Функции:

• Быстрое добавление: Через URL-параметр (например, http://<server_ip>:3000/add?url=https://example.com).
• Интеграции: Webhook для уведомлений (например, в Telegram через внешние сервисы).
• Экспорт: В JSON или CSV для миграции.

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

Настройка и использование AI-тегирования

AI-тегирование в karakeep использует внешние модели для анализа контента. Поддерживаются Ollama (локально) или OpenAI (облако).

Настройка:

1. Убедитесь, что AI_ENABLED=true в .env.
2. Для Ollama:
   • Установите модель: ollama pull mistral (или другую, например, llama2).
   • В настройках karakeep укажите URL Ollama (http://host.docker.internal:11434 для Docker на том же хосте).
   • Для внешнего Ollama: Используйте IP сервера и порт 11434, убедитесь в доступности.
3. Для OpenAI:
   • Получите API-ключ на platform.openai.com.
   • Добавьте в .env: OPENAI_API_KEY=sk-... и AI_PROVIDER=openai.

Использование:

1. При добавлении закладки, включите опцию "AI Tagging" в форме.
2. Система отправит текст страницы в модель и вернет предложенные теги (например, ["AI", "Technology"]).
3. Подтвердите или отредактируйте теги перед сохранением.
4. Для массовой обработки: В настройках есть опция "Batch Tagging" для существующих закладок.

Оптимизация:

• Используйте локальные модели (Ollama) для конфиденциальности и низкой задержки.
• Настройте промпт в коде (редактируйте src/services/ai.js в репозитории) для специфичных тегов (например, на русском языке).
• Ограничьте токены входа, чтобы снизить нагрузку на CPU.

Особенности полнотекстового поиска и его оптимизация

Полнотекстовый поиск в karakeep реализован на базе PostgreSQL (через расширение pg_trgm и tsvector) или интегрируется с Meilisearch.

Как работает:

• Индексируется содержимое страниц (извлеченный текст через библиотеку вроде puppeteer или cheerio), заметки и OCR для изображений (с помощью Tesseract через API).
• Поиск поддерживает булевы операторы (AND, OR), фразы в кавычках и ранжирование по релевантности.

Настройка:

1. Для PostgreSQL (по умолчанию):

   • Проверьте, что расширения установлены (автоматически в контейнере).
   • В настройках: Включите "Full-Text Search".

2. Для Meilisearch (рекомендуется для больших баз >10k закладок):

   • Раскомментируйте сервис в docker-compose.yml.
   • В .env добавьте SEARCH_PROVIDER=meilisearch и URL.
   • Перезапустите: docker-compose up -d.
   • Индексация запустится автоматически при добавлении закладок (можно вручную в админке).

Оптимизация:

• Индексация: Обновляйте индексы раз в день (через cron-задачу на хосте: docker-compose exec app npm run index).
• Язык: Для русского текста настройте лемматизацию (в config/search.js укажите language: 'russian').
• Производительность: На слабом сервере используйте PostgreSQL; на мощном — Meilisearch для субсекундного поиска. Мониторьте нагрузку через docker stats.
• Пример запроса: В интерфейсе введите "AI technology" — система найдет закладки с соответствующими тегами и текстом.

Советы по бэкапу и восстановлению данных

Регулярные бэкапы критичны, так как данные хранятся локально.

Бэкап:

1. База данных:
   • Ручной: docker-compose exec db pg_dump -U karakeep_user karakeep > backup_$(date +%Y%m%d).sql.
   • Автоматический: Настройте cron на хосте (например, ежедневно в 2:00):

     0 2 * * * cd /path/to/karakeep && docker-compose exec db pg_dump -U karakeep_user karakeep > /backups/karakeep_$(date +\%Y\%m\%d).sql
     

2. Файлы (изображения): Копируйте папку ./data/uploads (в том же томе, что и в docker-compose.yml).
3. Полный бэкап: Архивируйте весь проект: tar -czf karakeep_backup.tar.gz /path/to/karakeep.
4. Облако: Используйте rclone или rsync для синхронизации с S3/другим сервером. Например:

   rclone sync /path/to/karakeep remote:backups/karakeep
   

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

1. Остановите контейнеры: docker-compose down.
2. Восстановите БД: docker-compose exec -T db psql -U karakeep_user karakeep < backup_file.sql.
3. Скопируйте файлы обратно в папку uploads.
4. Запустите: docker-compose up -d.
5. Проверьте целостность: Войдите в интерфейс и выполните поиск.

Частота: Для личного использования — раз в неделю; для активных пользователей — ежедневно. Храните бэкапы на отдельном диске или в облаке.

Безопасность и доступ из интернета (прокси, HTTPS)

По умолчанию karakeep работает на HTTP и не защищен для внешнего доступа.

Безопасность:

• Пароли: Используйте сильные JWT-секреты и пароли БД. Включите 2FA (если поддерживается в будущих версиях).
• Брандмауэр: Ограничьте порты: ufw allow 3000/tcp (для локального теста), но для продакшена используйте прокси.
• Обновления: Периодически обновляйте репозиторий: git pull && docker-compose build --no-cache.
• Ограничение доступа: В docker-compose.yml добавьте network_mode: "host" или используйте Docker networks для изоляции.

Доступ из интернета (с HTTPS):

1. Прокси с Nginx (рекомендуется):
   • Установите Nginx: sudo apt install nginx.
   • Создайте конфиг /etc/nginx/sites-available/karakeep:

     server {
         listen 80;
         server_name yourdomain.com;  # Или IP
     
         location / {
             proxy_pass http://localhost:3000;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         }
     }
     

   • Активируйте: sudo ln -s /etc/nginx/sites-available/karakeep /etc/nginx/sites-enabled/ и sudo nginx -t && sudo systemctl reload nginx.
2. HTTPS (Let's Encrypt):
   • Установите Certbot: sudo apt install certbot python3-certbot-nginx.
   • Запустите: sudo certbot --nginx -d yourdomain.com.
   • Nginx автоматически настроит HTTPS и перенаправление HTTP->HTTPS.
3. Для локального теста без домена: Используйте SSH-туннель:

   ssh -L 3000:localhost:3000 user@server  # Доступ через http://localhost:3000
   

   Или Cloudflare Tunnel для бесплатного HTTPS без сервера.

Важно: Никогда не открывайте порты напрямую (3000, 5432) в интернете без прокси. Мониторьте логи на предмет попыток взлома.

Альтернативные решения и когда karakeep может не подойти

Karakeep — отличный выбор, но не универсален.

Альтернативы:

• LinkAce: Простой менеджер закладок на PHP/MySQL, без AI, но легче в развертывании. Подходит для базовых нужд.
• Shiori: Go-based, фокус на архивации страниц (снимки), без полнотекстового поиска. Для ценителей офлайн-доступа.
• Wallabag: PHP/Symfony, с поддержкой RSS и импорта, но без встроенного AI. Хорош для читателей статей.
• Obsidian + плагины: Для личных заметок с локальным хранением, но без веб-интерфейса.

Когда karakeep не подходит:

• Слабое железо: Если сервер <4 ГБ RAM или без SSD, полнотекстовый поиск и AI будут медленными. Рассмотрите SaaS вроде Notion.
• Отсутствие DevOps-навыков: Если Docker — сложность, попробуйте облачные alternatives (Raindrop.io Premium за $3/мес).
• Командная работа >5 человек: Karakeep не имеет встроенных прав доступа (только один пользователь). Для команд используйте Linkwarden.
• Требования к AI без затрат: OpenAI платный; локальные модели требуют GPU для скорости. Если это критично, избегайте AI-функций.

Karakeep идеален для технически подкованных одиночек, ценящих конфиденциальность и гибкость.

Заключение: Стоит ли переходить на самодостаточное решение?

Переход на karakeep оправдан, если вы устали от ограничений облачных сервисов и готовы вложить время в настройку. Преимущества — полный контроль, продвинутый поиск и AI без подписок — перевешивают для активных пользователей. Однако оцените свои ресурсы: если сервер слабый или навыков Docker нет, начните с альтернатив вроде Wallabag. В итоге, karakeep — это инвестиция в долгосрочную автономность, но тестовый запуск на локальной машине поможет принять решение. Если вопросы — обращайтесь к документации проекта на GitHub.