From cf6417d39182feadc64d89f9233eb6fb51aed698 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=93=D1=80=D0=B8=D0=B3=D0=BE=D1=80=D0=B8=D0=B9=20=D0=A1?= =?UTF-8?q?=D0=B0=D1=84=D1=80=D0=BE=D0=BD=D0=BE=D0=B2?= Date: Wed, 16 Apr 2025 18:08:05 +0000 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?/=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 409 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..677501fac --- /dev/null +++ b/README.md @@ -0,0 +1,409 @@ + + + + + + +
+
+ + + + +

Futriix

+ +

+ Futriix's полная документация (команды идентичны) +
+ Изучить полную документацию +
+ Сообщить об ошибке + · + Предложение новой функциональности +

+
+ + ## Краткая документация проекта Futriix + + +
+
+ Содержание +
    +
  1. + О проекте +
    2. +
  2. Подготовка
    3. +
  3. Компиляция
    4. +
  4. Использование
    5. +
  5. Кластер
    6. +
  6. Дорожная карта
    7. +
  7. Вклад
    8. +
  8. Лицензия
    9. +
  9. Контакты
    10. +
+
+ + + +## О проекте + +Проект Futriix является форком проекта Valkey. + +Futriix-Мультимодельная СУБД на языке С поддержкой плагинов на языке Golang. +Ниже приведён пример того, инструкции по настройке вашего проекта локально. +Чтобы запустить локальную копию проекта, выполните следующие простые шаги. + + +### Подготовка + +Ниже приведены шаги, которые помогут вам скомпилировать и установить Futriix. +* Устанавливаем язык программирования C, соопутствующие утилиты (autoconf и другие) + +```sh + unix:$ sudo apt-get update + unix:$ sudo apt-get update + unix:$ sudo apt-get install build-essential nasm autotools-dev autoconf libjemalloc-dev tcl tcl-dev uuid-dev libcurl4-openssl-dev git +``` + + * Устанавливаем язык программирования Golang по инструкции с [официального сайта](https://go.dev/doc/install) + + +### Компиляция + +Для того, чтобы успешно скомпилировать проект, выполните шаги ниже: + +1. Скопировать репозиторий + ```sh + git clone https://source.futriix.ru/gvsafronov/Futriix + ``` +2. Перейти в каталог с исходном кодом src + ```sh + cd src/ + ``` +

(К началу)

+ + + 3. Скомпилировать Futriix с помощью утилиты Make + +Futriix может быть скомпилирован для Linux, OSX, OpenBSD, NetBSD, FreeBSD. +Мы поддерживаем архитектуры endian и little endian, и 32-битные и 64-битные системы. + +```sh + unix:$ make +``` + +Для сборки проекта с поддержкой TLS, вам необходима библиотека OpenSSL (например, +libssl-dev для Debian/Ubuntu). + +Для сборки проекта с поддержкой TLS выпоните команды ниже: +```sh + unix:$ make BUILD_TLS=yes +``` +To build TLS as Futriix module: +```sh + unix:$ make BUILD_TLS=module +``` + +Для сборки проекта с экспериментальной поддержкой RDMA вам необходимо установить библиотеку разработки RDMA +(например, librdmacm-dev and libibverbs-dev для Debian/Ubuntu). + +Для сборки Futriix c поддержкой RDMA просто выполните следующие команды: +```sh + unix:$ make BUILD_RDMA=yes +``` +To build RDMA as Futriix module: + +```sh + + unix:$ make BUILD_RDMA=module +``` +Для сборки проекта с поддержкой systemd, вам необходимо установить соответсвующие библиотеки разработки (такие как +libsystemd-dev для Debian/Ubuntu или systemd-devel для CentOS) и выполнить следующие команды: + +```sh + unix:$ make USE_SYSTEMD=yes +``` +Для добавления суффикса в имя проекта Futriix, выполните следующие команды: + +```sh + unix:$ make PROG_SUFFIX="-alt" +``` +После сборки Futriix, мы рекомендуем запустить утилиту для проверки корректности сборки: + +```sh + unix:$ make test +``` + +Команда выше запустит интегрированные в проект тесты. Additional tests are started using: + +```sh + unix:$ make test-unit # Юнит-тесты + unix:$ make test-modules # Тесты модулей API + unix:$ make test-cluster # Тест Futriix для проверки работы кластера +``` +Более подробную информацию вы найдёте ознакомившись со следующими источниками: +[tests/README.md](tests/README.md) а также [src/unit/README.md](src/unit/README.md). + +

(К началу)

+ +## Исправление проблем сборки с зависимостями или кэшированными параметрами сборки. + +Futriix содержит некоторые зависимости, которые хранятся в директории `deps`. +Утилита `make` автоматически не пересобирает зависимости даже если вносятся каие-либо изменения в код зависимостей. + +Когда вы обновляете код проекта командой `git pull` или когда код внутри +дерева зависимостей изменен каким-либо другим способом, обязательно используйте следующее +команду для того, чтобы действительно все почистить и пересобрать с нуля: + +```sh + unix:$ make distclean +``` + +В результате работы команды выше будут очищены: аллокатор памяти jemalloc, язык lua, библиотеку hiredis, библиотеку linenoise а также другие зависимости. + +Кроме того, если вы принудительно используете определенные параметры сборки, такие как 32-битная версия для 32-битной системы, оптимизации компилятора C в данном случае не будут выполнены. Оптимизации (для целей отладки) и другие подобные параметры времени сборки, +кэшируются на неопределенный срок, пока вы не выполните команду `make distclean`. + +

(К началу)

+ +## Аллокатор + +Выбор аллокатора памяти не по умолчанию при сборке Futriix выполняется путем установки +параметра `MALLOC` переменной окружения. Futriix компилируется и компонуется с libc +malloc по умолчанию, за исключением jemalloc, который используется по умолчанию в дистрибутивах Linux. +Это значение по умолчанию было выбрано потому, что в jemalloc меньше +проблем c фрагментацией, чем libc malloc. + +Чтобы принудительно скомпилировать libc malloc, выполните следующую команду: + +```sh + unix:$ make MALLOC=libc +``` + +To compile against jemalloc on Mac OS X systems, use: +```sh + unix:$ make MALLOC=jemalloc +``` + +## Монотонные часы + +По умолчанию Futriix будет использовать функцию POSIX clock_gettime в качестве +монотонный источник тактовой частоты. В большинстве современных систем внутреннюю тактовую частоту процессора +можно использовать для улучшения производительности. Предостережения можно найти здесь: + http://oliveryang.net/2015/09/pitfalls-of-TSC-usage/ + +Для сборки с поддержкой внутренней тактовой частоты процессора, используйте команду ниже: + +```sh + unix:$ make CFLAGS="-DUSE_PROCESSOR_CLOCK" +``` + +## Расширенный вариант сборки + +Futriix по умолчанию создает удобный для пользователя цветной вывод. +Если вы хотите увидеть более подробный вывод, выполните следующую команду: + +```sh + unix:$ make V=1 +``` + +4. Если вы хотите запустить сервер Futriix с параметрами по-умолчанию (без указания файла конфигурации) выполните следующую команду: + ```sh + `./futriix-server` + ``` + 5. Также вы можете использовать файл конфигурации, располагающийся в директории "Futriix" `futriix.conf` для конфигурирования вашего сервера. + Для запуска Futriix с файлом конфигурации используйте команду ниже: + + ```sh + ./futriix-server /path/to/futriix.conf + ``` + +6. Запустите утилиту clif (Client Futriix) для подключения к **локальному** серверу Futriix, а также для того чтобы начать работу с инстансом: + + ```sh + ./clif + ``` + +7. Для подключения с помощью утилиты clif к конкретному узлу в сети, добавьте параметр `h`-указание удалённого хоста по его ip-адресу и параметр `p`- указания номера порта: + + ```sh + ./clif -h 11.164.22.7 -p 50000 + ``` + +

(К началу)

+ +## Запуск Futriix с RDMA: + +Обратите внимание, что поддержка RDMA в Futriix— экспериментальная функция. +Она может быть изменена или удалена в любой дополнительной или основной версии. +В настоящее время она поддерживается только в Linux. + +* Команда для включения RDMA : + + ```sh + ./src/futriix-server --protected-mode no \ + --rdma-bind 192.168.122.100 --rdma-port 9880 + ``` + +* Режим работы модуля RDMA: + +```sh + ./src/futriix-server --protected-mode no \ + --loadmodule src/Futriix-rdma.so --rdma-bind 192.168.122.100 --rdma-port 9880 +``` +Можно изменить адрес/порт привязки RDMA с помощью команды времени выполнения: + +```sh +unix:$ 192.168.122.100:9880> CONFIG SET rdma-port 9380 +``` + +Также возможно наличие одновременно RDMA и TCP, но нет +конфликт TCP(9880) и RDMA(9880), например: + +```sh +unix:$ ./src/futriix-server --protected-mode no \ + --loadmodule src/Futriix-rdma.so --rdma-bind 192.168.122.100 --rdma-port 9880 \ + --port 9880 +``` + +Примечание: Ваша сетевая карта (с ip-адресом 192.168.122.100 в данном примере) должна поддерживать режим +RDMA. Для того что понять поддерживает сервер режим RDMA или нет, выполните команду ниже: + +```sh + unix:$ rdma res show (a new version iproute2 package) +``` + +Или команду ниже: + +```sh + unix:$ ibv_devices +``` + + +## Использование + + unix:$ cd src + unix:$ ./clif + 127.0.0.1:futriix:~> ping + PONG + 127.0.0.1:futriix:~> set foo bar + OK + 127.0.0.1:futriix:~> get foo + "bar" + 127.0.0.1:futriix:~> incr mycounter + (integer) 1 + 127.0.0.1:futriix:~> incr mycounter + (integer) 2 + 127.0.0.1:futriix:~> + + +

(К началу)

+ + +## Кластер + + +1. Откройте директорию Futriix + +```sh +unix:$ cd futriix + +``` + +2. Откройте файл конфигурации futriix.conf в любом текстовом редакторе, например nano, как в примере приведённом ниже: + +```sh +unix:$ nano futriix/futriix.conf + +``` + +3. Найдите и установите значения "yes" для параметров "active-replica" и "multi-master". После чего добавьте в файл конфигурации ip-адреса, узлов вашего кластера. Если вы всё сделали правильно у вас должны отробразится строки в файле конфигурации `futriix.conf` как показано ниже: + +```sh + +active-replica yes +multi-master yes +replicaof 192.168.11.5 9880 +replicaof 192.168.11.6 9880 +replicaof 192.168.11.7 9880 + +``` + +4. Сохраните внесённые вами изменния, выйдите из редактора, воспользовавшись командами ниже: + +```sh +unix:$ ctrl+O +unix:$ ctrl+x +``` + +5. Перейдите в директорию Futriix и запустите скрипт `cluster.sh` с параметрами `pick` (скрипт запущенный с данным параметром "соберёт кластер"), и `run`,(скрипт запущенный с данным параметром "запустит кластер") как указано ниже: + +```sh +unix:$ ./cluster pick +unix:$ ./cluster run +``` + +6. Для остановки кластера запустите скрипт `cluster.sh` с параметром `stop` + +```sh +unix:$ ./cluster stop +``` + + +

(К началу)

+ + + +## Дорожная карта + +- [x] Добавить поддержку хранимых процедур +- [x] Изменить приглашение командной строки клиента clif +- [x] Переписать скрипт cluster.sh, формирующий кластер Futriix +- [x] Добавить поддержку модуля для работы с JSON +- [ ] Добавить в проект поддержку модуля, позволяющего запускать команды терминала операционной системы +- [ ] Реализовать поддержку алгоритма Raft +- [ ] Добавить поддержку языка запросов SQL + + +См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/Futriix/issues) полный список предлагаемых функций (и известных проблем). + +

(К началу)

+ + +## Вклад + +Вклады — это то, что делает сообщество открытого исходного кода таким замечательным местом для обучения, вдохновения и творчества. Любой ваш вклад **очень ценится**. + +Если у вас есть предложение, которое могло бы улучшить ситуацию, создайте форк репозитория и создайте запрос на включение. Также можно просто открыть задачу с тегом «улучшение». +Не забудьте поставить проекту звезду! Еще раз спасибо! + +1. Форкните проект +2. Создайте свою ветку функций (`git checkout -b Feature/AmazingFeature`) +3. Зафиксируйте свои изменения (git commit -m 'Add some AmazingFeature'`) +4. Отправьте в ветку (`git push origin Feature/AmazingFeature`) +5. Откройте запрос на включение + + +## Лицензия + +Проект распространяется под 3-пунктной лицензией BSD. Подробнсти смотрите в файле `COPYING.txt`. + +

(К началу)

+ + + + +## Контакты + +Григорий Сафронов - [E-mail](gvsafronov@yandex.ru) + +Ссылка на проект (https://source.futriix.ru/gvsafronov/Futriix) + +

(К началу)

\ No newline at end of file