--- layout: default title: "Техническое описание: Консолидация конфигурации Cassandra" parent: "Russian (Beta)" --- # Техническое описание: Консолидация конфигурации Cassandra > **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta. **Статус:** Черновик **Автор:** Assistant **Дата:** 2024-09-03 ## Обзор Данное техническое описание посвящено неконсистентности именования и шаблонов конфигурации параметров подключения к Cassandra в кодовой базе TrustGraph. В настоящее время существуют две различные схемы именования параметров (`cassandra_*` против `graph_*`), что приводит к путанице и усложняет обслуживание. ## Описание проблемы В кодовой базе в настоящее время используются два различных набора параметров конфигурации Cassandra: 1. **Модули Knowledge/Config/Library** используют: `cassandra_host` (список хостов) `cassandra_user` `cassandra_password` 2. **Модули Graph/Storage** используют: `graph_host` (один хост, иногда преобразуется в список) `graph_username` `graph_password` 3. **Неконсистентное использование в командной строке**: Некоторые процессоры (например, `kg-store`) не предоставляют параметры Cassandra в качестве аргументов командной строки Другие процессоры предоставляют их с разными именами и форматами Тексты справки не отражают значения переменных окружения по умолчанию Оба набора параметров подключаются к одному кластеру Cassandra, но с разными соглашениями об именовании, что приводит к: Путанице в конфигурации для пользователей Увеличенной нагрузке на обслуживание Неконсистентной документации Возможности неправильной конфигурации Невозможности перезаписать настройки через командную строку в некоторых процессорах ## Предлагаемое решение ### 1. Стандартизация имен параметров Все модули будут использовать согласованные имена параметров `cassandra_*`: `cassandra_host` - Список хостов (хранится внутри как список) `cassandra_username` - Имя пользователя для аутентификации `cassandra_password` - Пароль для аутентификации ### 2. Аргументы командной строки Все процессоры ДОЛЖНЫ предоставлять конфигурацию Cassandra через аргументы командной строки: `--cassandra-host` - Список хостов, разделенный запятыми `--cassandra-username` - Имя пользователя для аутентификации `--cassandra-password` - Пароль для аутентификации ### 3. Передача через переменные окружения Если параметры командной строки не указаны явно, система будет проверять переменные окружения: `CASSANDRA_HOST` - Список хостов, разделенный запятыми `CASSANDRA_USERNAME` - Имя пользователя для аутентификации `CASSANDRA_PASSWORD` - Пароль для аутентификации ### 4. Значения по умолчанию Если ни параметры командной строки, ни переменные окружения не указаны: `cassandra_host` по умолчанию `["cassandra"]` `cassandra_username` по умолчанию `None` (без аутентификации) `cassandra_password` по умолчанию `None` (без аутентификации) ### 5. Требования к тексту справки Вывод команды `--help` должен: Показывать значения переменных окружения в качестве значений по умолчанию, если они установлены Никогда не отображать значения паролей (показывать `****` или `` вместо этого) Четко указывать порядок разрешения в тексте справки Пример вывода справки: ``` --cassandra-host HOST Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2) [from CASSANDRA_HOST environment variable] --cassandra-username USERNAME Cassandra username (default: cassandra_user) [from CASSANDRA_USERNAME environment variable] --cassandra-password PASSWORD Cassandra password (default: ) ``` ## Детали реализации ### Порядок разрешения параметров Для каждого параметра Cassandra порядок разрешения будет следующим: 1. Значение аргумента командной строки 2. Значение переменной окружения (`CASSANDRA_*`) 3. Значение по умолчанию ### Обработка параметров хостов Параметр `cassandra_host`: Командная строка принимает строку, разделенную запятыми: `--cassandra-host "host1,host2,host3"` Переменная окружения принимает строку, разделенную запятыми: `CASSANDRA_HOST="host1,host2,host3"` Внутри всегда хранится в виде списка: `["host1", "host2", "host3"]` Один хост: `"localhost"` → преобразуется в `["localhost"]` Уже является списком: `["host1", "host2"]` → используется как есть ### Логика аутентификации Аутентификация будет использоваться, когда указаны и `cassandra_username`, и `cassandra_password`: ```python if cassandra_username and cassandra_password: # Use SSL context and PlainTextAuthProvider else: # Connect without authentication ``` ## Файлы для изменения ### Модули, использующие параметры `graph_*` (которые необходимо изменить): `trustgraph-flow/trustgraph/storage/triples/cassandra/write.py` `trustgraph-flow/trustgraph/storage/objects/cassandra/write.py` `trustgraph-flow/trustgraph/storage/rows/cassandra/write.py` `trustgraph-flow/trustgraph/query/triples/cassandra/service.py` ### Модули, использующие параметры `cassandra_*` (которые необходимо обновить с использованием резервного варианта из среды): `trustgraph-flow/trustgraph/tables/config.py` `trustgraph-flow/trustgraph/tables/knowledge.py` `trustgraph-flow/trustgraph/tables/library.py` `trustgraph-flow/trustgraph/storage/knowledge/store.py` `trustgraph-flow/trustgraph/cores/knowledge.py` `trustgraph-flow/trustgraph/librarian/librarian.py` `trustgraph-flow/trustgraph/librarian/service.py` `trustgraph-flow/trustgraph/config/service/service.py` `trustgraph-flow/trustgraph/cores/service.py` ### Тестовые файлы для обновления: `tests/unit/test_cores/test_knowledge_manager.py` `tests/unit/test_storage/test_triples_cassandra_storage.py` `tests/unit/test_query/test_triples_cassandra_query.py` `tests/integration/test_objects_cassandra_integration.py` ## Стратегия реализации ### Этап 1: Создание общего вспомогательного класса конфигурации Создайте вспомогательные функции для стандартизации конфигурации Cassandra во всех процессорах: ```python import os import argparse def get_cassandra_defaults(): """Get default values from environment variables or fallback.""" return { 'host': os.getenv('CASSANDRA_HOST', 'cassandra'), 'username': os.getenv('CASSANDRA_USERNAME'), 'password': os.getenv('CASSANDRA_PASSWORD') } def add_cassandra_args(parser: argparse.ArgumentParser): """ Add standardized Cassandra arguments to an argument parser. Shows environment variable values in help text. """ defaults = get_cassandra_defaults() # Format help text with env var indication host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})" if 'CASSANDRA_HOST' in os.environ: host_help += " [from CASSANDRA_HOST]" username_help = f"Cassandra username" if defaults['username']: username_help += f" (default: {defaults['username']})" if 'CASSANDRA_USERNAME' in os.environ: username_help += " [from CASSANDRA_USERNAME]" password_help = "Cassandra password" if defaults['password']: password_help += " (default: )" if 'CASSANDRA_PASSWORD' in os.environ: password_help += " [from CASSANDRA_PASSWORD]" parser.add_argument( '--cassandra-host', default=defaults['host'], help=host_help ) parser.add_argument( '--cassandra-username', default=defaults['username'], help=username_help ) parser.add_argument( '--cassandra-password', default=defaults['password'], help=password_help ) def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]: """ Convert argparse args to Cassandra configuration. Returns: tuple: (hosts_list, username, password) """ # Convert host string to list if isinstance(args.cassandra_host, str): hosts = [h.strip() for h in args.cassandra_host.split(',')] else: hosts = args.cassandra_host return hosts, args.cassandra_username, args.cassandra_password ``` ### Фаза 2: Обновление модулей с использованием параметров `graph_*` 1. Изменить имена параметров с `graph_*` на `cassandra_*` 2. Заменить собственные методы `add_args()` на стандартизированные методы `add_cassandra_args()` 3. Использовать общие вспомогательные функции конфигурации 4. Обновить строки документации Пример преобразования: ```python # OLD CODE @staticmethod def add_args(parser): parser.add_argument( '-g', '--graph-host', default="localhost", help=f'Graph host (default: localhost)' ) parser.add_argument( '--graph-username', default=None, help=f'Cassandra username' ) # NEW CODE @staticmethod def add_args(parser): FlowProcessor.add_args(parser) add_cassandra_args(parser) # Use standard helper ``` ### Фаза 3: Обновление модулей с использованием параметров `cassandra_*` 1. Добавить поддержку аргументов командной строки там, где это отсутствует (например, `kg-store`). 2. Заменить существующие определения аргументов на `add_cassandra_args()`. 3. Использовать `resolve_cassandra_config()` для обеспечения согласованности разрешения. 4. Обеспечить согласованную обработку списка хостов. ### Фаза 4: Обновление тестов и документации 1. Обновить все файлы тестов для использования новых имен параметров. 2. Обновить документацию CLI. 3. Обновить документацию API. 4. Добавить документацию по переменным окружения. ## Обратная совместимость Для поддержания обратной совместимости во время перехода: 1. **Предупреждения об устаревании** для параметров `graph_*`. 2. **Псевдонимы параметров** - изначально принимать как старые, так и новые имена. 3. **Поэтапное внедрение** в течение нескольких релизов. 4. **Обновления документации** с руководством по миграции. Пример кода обратной совместимости: ```python def __init__(self, **params): # Handle deprecated graph_* parameters if 'graph_host' in params: warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning) params.setdefault('cassandra_host', params.pop('graph_host')) if 'graph_username' in params: warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning) params.setdefault('cassandra_username', params.pop('graph_username')) # ... continue with standard resolution ``` ## Стратегия тестирования 1. **Юнит-тесты** для логики разрешения конфигурации 2. **Интеграционные тесты** с различными комбинациями конфигурации 3. **Тесты переменных окружения** 4. **Тесты обратной совместимости** с устаревшими параметрами 5. **Тесты Docker Compose** с переменными окружения ## Обновления документации 1. Обновить всю документацию по командам CLI 2. Обновить документацию API 3. Создать руководство по миграции 4. Обновить примеры Docker Compose 5. Обновить справочную документацию по конфигурации ## Риски и меры по их снижению | Риск | Влияние | Меры по снижению | |------|--------|------------| | Изменения, нарушающие работу пользователей | Высокое | Реализовать период обратной совместимости | | Спутанность конфигурации во время перехода | Среднее | Четкая документация и предупреждения об устаревании | | Сбои в тестах | Среднее | Комплексное обновление тестов | | Проблемы при развертывании Docker | Высокое | Обновить все примеры Docker Compose | ## Критерии успеха [ ] Все модули используют согласованные имена параметров `cassandra_*` [ ] Все процессоры предоставляют настройки Cassandra через аргументы командной строки [ ] Текстовая справка по командной строке показывает значения переменных окружения по умолчанию [ ] Значения паролей никогда не отображаются в справке [ ] Механизм отката к переменным окружения работает правильно [ ] `cassandra_host` последовательно обрабатывается как список внутри [ ] Обратная совместимость поддерживается не менее 2 версий [ ] Все тесты проходят с новой системой конфигурации [ ] Документация полностью обновлена [ ] Примеры Docker Compose работают с переменными окружения ## План **Неделя 1:** Реализовать общий помощник конфигурации и обновить модули `graph_*` **Неделя 2:** Добавить поддержку переменных окружения в существующие модули `cassandra_*` **Неделя 3:** Обновить тесты и документацию **Неделя 4:** Интеграционное тестирование и исправление ошибок ## Будущие соображения Рассмотреть возможность расширения этой модели на другие конфигурации баз данных (например, Elasticsearch) Реализовать проверку конфигурации и улучшенные сообщения об ошибках Добавить поддержку конфигурации пула соединений Cassandra Рассмотреть возможность добавления поддержки файлов конфигурации (.env)