trustgraph/docs/tech-specs/cassandra-consolidation.zh-cn.md

layout	title	parent
default	技术规范：Cassandra 配置整合	Chinese (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.

状态： 草稿 作者： 助理 日期： 2024-09-03

概述

本规范旨在解决 TrustGraph 代码库中 Cassandra 连接参数命名和配置模式的不一致问题。目前，存在两种不同的参数命名方案（cassandra_* 与 graph_*），这导致了混乱和维护复杂性。

问题陈述

当前代码库使用两组不同的 Cassandra 配置参数：

1. 知识/配置/库模块 使用： cassandra_host (主机列表) cassandra_user cassandra_password

2. 图/存储模块 使用： 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 输出必须： 显示已设置的环境变量值作为默认值 绝不显示密码值（显示 **** 或 <set> 代替） 在帮助文本中清楚地指示解析顺序

示例帮助输出：

--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: <set from environment>)

实现细节

参数解析顺序

对于每个 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 时，将使用认证：

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

实施策略

第一阶段：创建通用的配置辅助工具

创建实用函数，以标准化所有处理器中的 Cassandra 配置：

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: <set>)"
        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

第二阶段：使用 graph_* 参数更新模块

1. 将参数名称从 graph_* 更改为 cassandra_*
2. 将自定义 add_args() 方法替换为标准化的 add_cassandra_args()
3. 使用通用的配置辅助函数
4. 更新文档字符串

示例转换：

# 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

第三阶段：使用 cassandra_* 参数更新模块

1. 在缺失的地方添加命令行参数支持（例如：kg-store）
2. 将现有的参数定义替换为 add_cassandra_args()
3. 使用 resolve_cassandra_config() 以实现一致的解析
4. 确保一致的主机列表处理

第四阶段：更新测试和文档

1. 更新所有测试文件以使用新的参数名称
2. 更新命令行界面 (CLI) 文档
3. 更新 API 文档
4. 添加环境变量文档

向后兼容性

为了在过渡期间保持向后兼容性：

1. 弃用警告，用于 graph_* 参数
2. 参数别名 - 初始阶段接受旧名称和新名称
3. 分阶段发布，在多个版本中进行
4. 文档更新，包含迁移指南

示例向后兼容代码：

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 示例使用环境变量

时间线

第一周： 实施通用的配置助手，并更新 graph_* 模块 第二周： 为现有的 cassandra_* 模块添加环境变量支持 第三周： 更新测试和文档 第四周： 集成测试和错误修复

未来考虑

考虑将此模式扩展到其他数据库配置（例如，Elasticsearch） 实施配置验证和更好的错误消息 添加对 Cassandra 连接池配置的支持 考虑添加对配置文件支持（.env 文件）