Поддержать проект через boosty

Кладезь - Система управления знаниями

Высокопроизводительная система управления знаниями с веб-интерфейсом, поддержкой LaTeX/Markdown редактора и гранулярной системой ролей.

Скриншоты

Светлая тема	Тёмная тема

Технологический стек

• База данных: PostgreSQL 15 Alpine
• Веб-сервер: Nginx с WebSocket поддержкой
• Контейнеризация: Docker Compose
• Backend: Node.js 18+ + Express.js
• Frontend: React 18 + Redux Toolkit
• WebSocket: Socket.IO (коллаборативное редактирование)
• Рендеринг формул: KaTeX
• Поиск: MeiliSearch v1.5 (полнотекстовый поиск с поддержкой опечаток)
• Кеширование: Redis (опционально)

Быстрый старт

Предварительные требования

• Docker и Docker Compose
• Git

Автоматическая установка и запуск

1. Клонирование репозитория

2. Запуск системы

   Скрипт автоматически:

   • Создаст
     .env
     файл из примера
   • Соберёт все Docker образы
   • Запустит все сервисы
   • Проверит их готовность

Ручная установка

1. Настройка переменных окружения

2. Запуск контейнеров

3. Проверка статуса

Доступ к системе

• Веб-интерфейс: http://kladez.local (или согласно настройкам в .env)
• База данных: localhost:5432 (PostgreSQL)
• API: http://kladez.local:3001

Учетные данные по умолчанию

• Логин: admin
• Пароль: admin123
• Email: admin@kladez.local

⚠️ Важно: Смените пароль администратора после первого входа!

Структура проекта

kladez/
├── backend/                 # Backend приложение
├── frontend/               # Frontend приложение  
├── database/               # Схема БД и миграции
│   ├── schema.sql         # Основная схема
│   └── seeds/             # Начальные данные
├── nginx/                 # Конфигурация веб-сервера
├── scripts/               # Скрипты развертывания
├── docs/                  # Документация
├── docker-compose.yml     # Конфигурация Docker
├── .env.example          # Пример переменных окружения
└── README.md             # Этот файл

Основной функционал

MVP (Минимально жизнеспособный продукт)

• ✅ Структура БД: Полная схема PostgreSQL с миграциями
• ✅ Аутентификация: JWT-токены + система ролей и групп
• ✅ Пользователи: Управление пользователями, роли (admin), группы безопасности
• ✅ Статьи: CRUD операции, версионность, статусы (draft/published/needs_update/archived)
• ✅ Разделы: Иерархическая организация статей по разделам
• ✅ Права доступа: Гранулярные права на разделы и статьи для пользователей/групп
• ✅ Веб-интерфейс: React SPA с React Router
• ✅ Системные настройки: Настройки через админ-панель и
  system_settings
  таблицу
• ✅ Аудит: Полный журнал изменений в
  audit_log

Расширенный функционал

• ✅ LaTeX редактор: Редактор с KaTeX для рендеринга формул
• ✅ Markdown: Поддержка Markdown разметки в статьях
• ✅ Темы: Настраиваемые темы оформления (цвета, шрифты) через UI
• ✅ Файлы: Загрузка и прикрепление файлов к статьям
• ✅ Хранилище: Файловое хранилище для контента (конфигурируется через настройки)
• ✅ Версионность: История версий статей с возможностью просмотра и восстановления
• ✅ Версии документации: Управление версиями документации (v1.0, v2.0, и т.д.)
• ✅ Полнотекстовый поиск: MeiliSearch с поддержкой:
  • Поиск с опечатками (typo tolerance)
  • Подсветка найденных фрагментов
  • Фильтрация и сортировка результатов
  • Поиск по статьям, разделам и пользователям
  • Настраиваемые правила ранжирования
• ✅ Коллаборативное редактирование: Real-time совместное редактирование через WebSocket
• ✅ LDAP: Интеграция с LDAP каталогом (ldapjs)
• ✅ Email: Email уведомления через Nodemailer
• ✅ Безопасность: Helmet, CORS, Rate Limiting, валидация данных

Управление системой

Команды управления

Разработка

Локальная разработка

1. Запуск в режиме разработки с Redis

2. Просмотр логов

3. Подключение к базе данных

Управление базой данных

Структура сервисов

• database (порт 5432) - PostgreSQL 15 Alpine
• backend (внутренний порт 3001) - Node.js API + WebSocket
• frontend (внутренний порт 3000) - React SPA
• webserver (порт 80/443) - Nginx reverse proxy с WebSocket поддержкой
• meilisearch (внутренний порт 7700) - Полнотекстовый поиск
• redis (порт 6379) - Кеширование (опционально)

Настройки

Переменные окружения

Основные переменные в

• DOMAIN
  - Доменное имя (по умолчанию: kladez.local)
• DB_PASSWORD
  - Пароль базы данных
• JWT_SECRET
  - Секрет для JWT токенов
• MEILI_MASTER_KEY
  - Мастер-ключ для MeiliSearch (обязательно изменить в продакшн)
• MEILI_ENV
  - Окружение MeiliSearch (development/production)
• SMTP_*
  - Настройки почтового сервера
• LDAP_*
  - Настройки LDAP (опционально)

Системные настройки

Настройки хранятся в таблице

• Регистрация пользователей
• Настройки темы оформления
• Ограничения на файлы
• SMTP настройки

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

• 🔒 Хеширование паролей (bcrypt)
• 🔒 JWT аутентификация
• 🔒 Защита от CSRF
• 🔒 Валидация входных данных
• 🔒 Ограничение прав доступа

Производительность

• ⚡ Индексы базы данных
• ⚡ Кеширование запросов
• ⚡ Сжатие статических файлов
• ⚡ Оптимизированные SQL запросы

Развертывание в продакшн

Первоначальное развертывание

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

2. Клонирование и настройка

3. Настройка домена

4. Запуск в продакшн режиме

SSL сертификат (Let's Encrypt)

Обновление системы

Автоматическое обновление (рекомендуется)

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

Что делает скрипт автоматического обновления:

1. ✅ Создаёт резервную копию базы данных и файлов
2. ✅ Сохраняет SSL сертификаты (если настроены)
3. ✅ Останавливает текущие сервисы
4. ✅ Обновляет код из Git репозитория
5. ✅ Восстанавливает SSL конфигурацию
6. ✅ Пересобирает и запускает обновлённые сервисы
7. ✅ Применяет новые миграции базы данных
8. ✅ Проверяет работоспособность всех сервисов
9. ✅ Автоматически откатывается при обнаружении ошибок

Автоматический откат:

• При любой ошибке система автоматически откатится к предыдущей версии
• Восстановит базу данных из бэкапа
• Восстановит предыдущий Git коммит
• Восстановит SSL сертификаты
• Перезапустит сервисы на предыдущей версии

Ручное обновление

Если автоматическое обновление недоступно, выполните шаги вручную:

Важно: При ручном обновлении миграции применяются автоматически при запуске через

Мониторинг и устранение неполадок

Проверка состояния системы

Типичные проблемы

Проблема: Сервисы не запускаются

Проблема: База данных недоступна

Проблема: Frontend не загружается

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

API Documentation

Основные эндпоинты

• GET /api/health
  - Проверка состояния API
• POST /api/auth/login
  - Аутентификация пользователя
• GET /api/articles
  - Список статей
• GET /api/sections
  - Разделы знаний
• GET /api/settings/public
  - Публичные настройки

Endpoints поиска

• GET /api/search/articles
  - Поиск статей с фильтрами и сортировкой
• GET /api/search/users
  - Поиск пользователей (только для администраторов)
• GET /api/search/sections
  - Поиск разделов
• GET /api/search/all
  - Универсальный поиск по всем сущностям
• POST /api/search/reindex
  - Полная переиндексация данных (только для администраторов)
• GET /api/search/stats
  - Статистика индексов MeiliSearch (только для администраторов)

Swagger документация

После запуска системы документация API доступна по адресу:

Поддержка

Получение помощи

• Логи системы:
  ./scripts/logs.sh
• Состояние сервисов:
  docker-compose ps
• Мониторинг: Проверьте
  /health
  эндпоинты

Контакты

• Техническая поддержка: Создайте issue в репозитории проекта
• Документация:
  /docs/
  директория в проекте

Лицензия

Этот проект распространяется под лицензией GNU General Public License v3.0 (GPLv3).

Подробности см. в файле LICENSE или на сайте GNU GPL v3.

Кладезь - Современная система управления знаниями для вашей команды

🚀 Быстрый запуск:

Миграции базы данных Кладезь

Описание

Эта директория содержит SQL-миграции для базы данных PostgreSQL системы Кладезь.

Автоматическое применение миграций

Миграции автоматически проверяются и применяются при запуске системы через

Ручное управление миграциями

Используйте скрипт

Правила именования

Миграции должны именоваться по шаблону:

XXX-описание-миграции.sql

Где

Список миграций

Создание новой миграции

1. Создайте файл с правильным именем:

2. Добавьте SQL-команды для изменения схемы БД

3. При следующем запуске системы миграция будет применена автоматически

Откат миграций

Автоматический откат не реализован. Для отката:

1. Вручную выполните обратные SQL-операции
2. Удалите запись из таблицы
   applied_migrations
   :

Отслеживание миграций

Система отслеживает применённые миграции в таблице:

Важные замечания

• Миграции применяются в алфавитном порядке
• Каждая миграция применяется только один раз
• При ошибке в миграции процесс запуска прерывается
• Всегда делайте резервную копию БД перед применением новых миграций