@clickzetta/cz-cli-darwin-x64 0.3.81 → 0.3.84

package/bin/skills/clickzetta-lakehouse-connect/references/config-file.md

@@ -0,0 +1,435 @@
+# 配置文件管理 — connections.json 详细参考
+
+本文档详细说明 ClickZetta Lakehouse 的连接配置文件格式、搜索路径、多连接管理以及 Docker 部署方式。所有内容基于 `mcp-clickzetta-server` 项目中的真实代码。
+
+## 目录
+
+- [JSON 配置文件格式](#json-配置文件格式)
+- [五级搜索路径](#五级搜索路径)
+- [多连接管理](#多连接管理)
+- [环境变量备选](#环境变量备选)
+- [Docker / Kubernetes 部署配置](#docker--kubernetes-部署配置)
+- [system_config 参数说明](#system_config-参数说明)
+- [适用场景](#适用场景)
+- [常见问题排查](#常见问题排查)
+- [完整配置模板](#完整配置模板)
+
+---
+
+## JSON 配置文件格式
+
+配置文件 `connections.json` 包含两个顶层对象：`connections`（连接数组）和 `system_config`（系统级配置）。
+
+### 基本结构
+
+```json
+{
+  "connections": [
+    {
+      "is_default": true,
+      "connection_name": "dev",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "my_user",
+      "password": "my_password",
+      "instance": "my_instance",
+      "workspace": "my_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "开发环境",
+      "hints": {
+        "sdk.job.timeout": 300,
+        "query_tag": "dev-queries"
+      }
+    }
+  ],
+  "system_config": {
+    "allow_write": true,
+    "prefetch": false,
+    "log_level": "INFO",
+    "exclude_tools": []
+  }
+}
+```
+
+### 连接字段说明
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|:--|:--|:--|:--|:--|
+| `connection_name` | string | ✅ | — | 连接名称，用于在多连接中唯一标识 |
+| `service` | string | ✅ | — | API 服务地址，如 `cn-shanghai-alicloud.api.clickzetta.com` |
+| `username` | string | ✅ | — | 登录用户名 |
+| `password` | string | ✅ | — | 登录密码 |
+| `instance` | string | ✅ | — | 实例名称 |
+| `workspace` | string | ✅ | — | 工作空间名称 |
+| `schema` | string | ✅ | — | 默认 Schema |
+| `vcluster` | string | ❌ | `"default_ap"` | 虚拟集群名称 |
+| `is_default` | boolean | ❌ | `false` | 是否为默认连接 |
+| `description` | string | ❌ | `""` | 连接描述信息 |
+| `hints` | object | ❌ | 见下方 | SDK 运行时参数 |
+
+### hints 默认值
+
+当 `hints` 未配置时，系统自动使用以下默认值：
+
+```json
+{
+  "sdk.job.timeout": 300,
+  "query_tag": "Query from MCP Server",
+  "cz.storage.parquet.vector.index.read.memory.cache": "true",
+  "cz.storage.parquet.vector.index.read.local.cache": "false",
+  "cz.sql.table.scan.push.down.filter": "true",
+  "cz.sql.table.scan.enable.ensure.filter": "true",
+  "cz.storage.always.prefetch.internal": "true",
+  "cz.optimizer.generate.columns.always.valid": "true",
+  "cz.sql.index.prewhere.enabled": "true",
+  "cz.storage.parquet.enable.io.prefetch": "false"
+}
+```
+
+---
+
+## 五级搜索路径
+
+`ConnectionManager` 按以下优先级（从高到低）搜索配置文件，找到第一个可访问的文件即停止：
+
+| 优先级 | 路径 | 适用场景 |
+|:--|:--|:--|
+| 1（最高） | `/app/.clickzetta/lakehouse_connection/connections.json` | Docker 统一路径（推荐） |
+| 2 | `/app/config/lakehouse_connection/connections.json` | 旧版 Docker 兼容路径 |
+| 3 | `config/lakehouse_connection/connections.json` | 项目目录相对路径（本地开发） |
+| 4 | `~/.clickzetta/connections.json` | 用户主目录（仅非 Docker 环境） |
+| 5（最低） | `/app/.clickzetta/connections.json` | 简化 Docker 路径 |
+
+> **Windows Docker 环境**：系统会自动检测并添加额外的 Windows Docker 友好路径。
+
+### 搜索逻辑源码参考
+
+```python
+# 来自 connection_manager.py
+class ConnectionManager:
+    UNIFIED_CONFIG_FILE = "/app/.clickzetta/lakehouse_connection/connections.json"
+    DOCKER_CONFIG_FILE = "/app/config/lakehouse_connection/connections.json"
+    DEFAULT_CONFIG_FILE = "config/lakehouse_connection/connections.json"
+    USER_CONFIG_FILE = os.path.expanduser("~/.clickzetta/connections.json")
+    SIMPLE_CONFIG_FILE = "/app/.clickzetta/connections.json"
+```
+
+### 指定配置文件路径
+
+也可以在初始化时直接指定配置文件路径，跳过搜索逻辑：
+
+```python
+from mcp_clickzetta_server.connection_manager import ConnectionManager
+
+# 使用指定路径
+conn_manager = ConnectionManager(config_file="/path/to/my/connections.json")
+```
+
+---
+
+## 多连接管理
+
+### 配置多个连接
+
+在 `connections` 数组中定义多个连接，通过 `is_default` 标记默认连接：
+
+```json
+{
+  "connections": [
+    {
+      "is_default": true,
+      "connection_name": "dev",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "dev_user",
+      "password": "dev_password",
+      "instance": "dev_instance",
+      "workspace": "dev_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "开发环境"
+    },
+    {
+      "connection_name": "staging",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "staging_user",
+      "password": "staging_password",
+      "instance": "staging_instance",
+      "workspace": "staging_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "预发布环境"
+    },
+    {
+      "connection_name": "prod",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "prod_user",
+      "password": "prod_password",
+      "instance": "prod_instance",
+      "workspace": "prod_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "生产环境",
+      "hints": {
+        "sdk.job.timeout": 600,
+        "query_tag": "production-queries"
+      }
+    }
+  ],
+  "system_config": {
+    "allow_write": false,
+    "log_level": "WARNING"
+  }
+}
+```
+
+### 连接选择规则
+
+1. 如果有 `is_default: true` 的连接，自动设为活跃连接
+2. 如果有多个 `is_default: true`，使用最后一个
+3. 如果没有默认连接，使用第一个有效连接
+4. `service` 为 `"not_configured"` 的占位配置会被自动跳过
+
+### 代码中切换连接
+
+```python
+from mcp_clickzetta_server.connection_manager import ConnectionManager
+
+conn_manager = ConnectionManager()
+
+# 列出所有可用连接
+connections = conn_manager.list_connections()
+for conn in connections:
+    print(f"  {conn['name']}: {conn.get('description', '')}")
+
+# 切换到指定连接
+result = conn_manager.switch_connection("prod")
+print(f"已切换到: {result}")
+
+# 获取当前活跃连接配置
+active_config = conn_manager.get_active_config()
+print(f"当前连接: {active_config.connection_name}")
+print(f"工作空间: {active_config.workspace}")
+
+# 设置新的默认连接
+conn_manager.set_default_connection("staging")
+
+# 验证连接配置是否完整
+validation = conn_manager.validate_connection("dev")
+print(f"验证结果: {validation}")
+```
+
+---
+
+## 环境变量备选
+
+当没有找到配置文件时，系统会创建占位配置并启动。以下环境变量可用于配置连接参数：
+
+### 连接参数环境变量
+
+| 环境变量 | 对应字段 | 说明 |
+|:--|:--|:--|
+| `CLICKZETTA_SERVICE` | `service` | API 服务地址 |
+| `CLICKZETTA_USERNAME` | `username` | 用户名 |
+| `CLICKZETTA_PASSWORD` | `password` | 密码 |
+| `CLICKZETTA_INSTANCE` | `instance` | 实例名称 |
+| `CLICKZETTA_WORKSPACE` | `workspace` | 工作空间 |
+| `CLICKZETTA_SCHEMA` | `schema` | 默认 Schema |
+| `CLICKZETTA_VCLUSTER` | `vcluster` | 虚拟集群（默认 `default_ap`） |
+
+### 系统配置环境变量覆盖
+
+以下环境变量可覆盖 `system_config` 中的对应配置（优先级最高）：
+
+| 环境变量 | 对应配置 | 示例值 |
+|:--|:--|:--|
+| `MCP_ALLOW_WRITE` | `allow_write` | `"true"` / `"false"` |
+| `MCP_PREFETCH` | `prefetch` | `"true"` / `"false"` |
+| `MCP_LOG_LEVEL` | `log_level` | `"DEBUG"` / `"INFO"` / `"WARNING"` / `"ERROR"` |
+| `MCP_EXCLUDE_TOOLS` | `exclude_tools` | `"tool1,tool2,tool3"` |
+
+### 相似度搜索环境变量
+
+| 环境变量 | 对应配置 |
+|:--|:--|
+| `Similar_table_name` | `similar_search.table_name` |
+| `Similar_embedding_column_name` | `similar_search.embedding_column_name` |
+| `Similar_content_column_name` | `similar_search.content_column_name` |
+| `Similar_other_columns_name` | `similar_search.other_columns_name` |
+| `Similar_partition_scope` | `similar_search.partition_scope` |
+
+### 云存储环境变量
+
+| 环境变量 | 对应配置 |
+|:--|:--|
+| `AWS_ACCESS_KEY_ID` | `cloud_storage.aws_access_key_id` |
+| `AWS_SECRET_ACCESS_KEY` | `cloud_storage.aws_secret_access_key` |
+| `AWS_REGION` | `cloud_storage.aws_region` |
+
+### 配置优先级
+
+系统配置的加载优先级（从高到低）：
+
+1. **环境变量**（最高优先级）
+2. **配置文件中的 `system_config`**
+3. **内置默认值**（最低优先级）
+
+---
+
+## Docker / Kubernetes 部署配置
+
+### docker-compose.yml
+
+```yaml
+services:
+  mcp-server:
+    image: mcp-clickzetta-server:latest
+    volumes:
+      # 推荐：挂载到统一路径（优先级 1）
+      - ./config/connections.json:/app/.clickzetta/lakehouse_connection/connections.json:ro
+    environment:
+      # 可选：通过环境变量覆盖系统配置
+      - MCP_ALLOW_WRITE=false
+      - MCP_LOG_LEVEL=INFO
+```
+
+### 使用旧版路径
+
+```yaml
+services:
+  mcp-server:
+    image: mcp-clickzetta-server:latest
+    volumes:
+      # 旧版兼容路径（优先级 2）
+      - ./config/connections.json:/app/config/lakehouse_connection/connections.json:ro
+```
+
+### Kubernetes ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: clickzetta-config
+data:
+  connections.json: |
+    {
+      "connections": [
+        {
+          "is_default": true,
+          "connection_name": "prod",
+          "service": "cn-shanghai-alicloud.api.clickzetta.com",
+          "username": "prod_user",
+          "password": "prod_password",
+          "instance": "prod_instance",
+          "workspace": "prod_workspace",
+          "schema": "public",
+          "vcluster": "default_ap"
+        }
+      ],
+      "system_config": {
+        "allow_write": false,
+        "log_level": "WARNING"
+      }
+    }
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-server
+spec:
+  template:
+    spec:
+      containers:
+        - name: mcp-server
+          volumeMounts:
+            - name: config
+              mountPath: /app/.clickzetta/lakehouse_connection/connections.json
+              subPath: connections.json
+              readOnly: true
+      volumes:
+        - name: config
+          configMap:
+            name: clickzetta-config
+```
+
+> **安全提示**：生产环境建议使用 Kubernetes Secret 替代 ConfigMap 存储密码。
+
+---
+
+## system_config 参数说明
+
+### 核心参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:--|:--|:--|:--|
+| `allow_write` | boolean | `false` | 是否允许写操作（INSERT/UPDATE/DELETE） |
+| `prefetch` | boolean | `true` | 是否启用数据预取 |
+| `log_level` | string | `"INFO"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `exclude_tools` | array | `[]` | 需要排除的工具列表 |
+
+---
+
+## 适用场景
+
+| 场景 | 推荐配置方式 | 说明 |
+|:--|:--|:--|
+| 本地开发 | `~/.clickzetta/connections.json` | 用户主目录，个人配置 |
+| 团队共享 | `config/lakehouse_connection/connections.json` | 项目目录，可纳入版本管理 |
+| Docker 部署 | 挂载到 `/app/.clickzetta/lakehouse_connection/` | 统一路径，推荐方式 |
+| Kubernetes | ConfigMap / Secret | 声明式配置管理 |
+| CI/CD 流水线 | 环境变量 | 无需配置文件，适合自动化 |
+| 多环境切换 | 多连接 + `switch_connection()` | 在同一配置文件中管理多个环境 |
+
+---
+
+## 常见问题排查
+
+### 配置文件未找到
+
+```
+WARNING: 未找到任何可用的配置文件
+```
+
+**解决方案**：
+1. 确认文件存在于五级搜索路径之一
+2. 检查文件权限：`chmod 600 connections.json`
+3. Docker 环境检查挂载是否正确
+
+### JSON 格式错误
+
+```
+ERROR: 配置文件JSON格式错误
+```
+
+**解决方案**：
+1. 使用 JSON 验证工具检查格式
+2. 确保所有字符串使用双引号
+3. 检查是否有多余的逗号
+4. 确保中文字符使用 UTF-8 编码保存
+
+### 连接配置缺少必需字段
+
+每个连接必须包含以下 7 个必需字段：
+
+```
+connection_name, service, username, password, instance, workspace, schema
+```
+
+### 占位配置被跳过
+
+`service` 设置为 `"not_configured"` 的连接会被自动跳过。确保所有生产连接都配置了正确的 `service` 地址。
+
+---
+
+## 完整配置模板
+
+参考项目中的模板文件：`config/connections-template.json`
+
+```bash
+# 复制模板并修改
+cp config/connections-template.json ~/.clickzetta/connections.json
+# 编辑配置
+vim ~/.clickzetta/connections.json
+# 设置文件权限（保护密码）
+chmod 600 ~/.clickzetta/connections.json
+```