--- name: alibabacloud-lindorm-agent-skill description: | Alibaba Cloud Lindorm cloud native multi-model database Skill. Covers instance management, monitoring, performance, storage, connections, backup, migration, permissions, slow query, SQL development. Lindorm is domain-specific knowledge — answers MUST reference Skill documents or official Alibaba Cloud documentation; direct responses from training knowledge are prohibited. Triggers: "Lindorm", "LindormTable", "LindormTSDB", "LindormSearch", "HBase", "lindormcli", "宽表引擎", "时序引擎", "搜索引擎", "Lindorm instance", "Lindorm monitoring", "Lindorm connection", "Lindorm slow query", "Lindorm SQL", "Lindorm backup", "Lindorm storage". --- # Lindorm Agent Skill Alibaba Cloud Lindorm cloud native multi-model database Skill. Covers three domains: **Operations Management**, **Developer Guidance**, and **Reference Materials**. ## Core Capability Matrix | Category | Sub-Scenarios | Reference Docs | |---------|--------------|----------------| | **01-Dev Guidance** | Connection setup, quick start, SQL guide, table design | `references/01-dev/` | | **02-Ops Management** | Instance mgmt, monitoring, error troubleshooting, storage analysis, connection diagnostics, backup & restore, migration, permissions, slow query | `references/02-ops/` | | **03-Reference** | CLI command list, RAM permission list | `references/03-ref/` | ## Decision Tree ``` User Request ├── Connection / DDL / SQL / Code examples → 01-dev │ ├── Connection address / code → references/01-dev/connection-guide.md │ ├── DDL / write / query examples → references/01-dev/quick-start-guide.md │ ├── SQL connection & development → references/01-dev/sql-client-guide.md │ ├── SQL syntax reference → references/01-dev/sql-operations.md │ ├── MySQL compatibility → references/01-dev/sql-usage-notes.md │ └── Table design guide → references/01-dev/table-design.md │ ├── Instance / Monitoring / Errors / Performance / Storage / Connection / Scaling / Backup / Migration / Permissions / Slow query → 02-ops │ ├── Instance management → references/02-ops/instance-management.md │ ├── Monitoring / Alerts → references/02-ops/monitoring-guide.md │ ├── Error codes → references/02-ops/error-troubleshoot.md │ ├── Storage analysis → references/02-ops/storage-analysis.md │ ├── Connection diagnostics → references/02-ops/connection-troubleshoot.md │ ├── Scale up/down → references/02-ops/instance-management.md │ ├── Backup & restore → references/02-ops/backup-restore.md │ ├── Data migration → references/02-ops/data-migration.md │ ├── Account & permissions → references/02-ops/user-permission.md │ └── Slow query analysis → references/02-ops/slow-query-analysis.md │ └── Command list / Permission reference / Specs → 03-ref ├── CLI command list → references/03-ref/related-commands.md ├── RAM permission list → references/03-ref/ram-policies.md ├── Aliyun CLI setup → references/03-ref/cli-installation-guide.md ├── Lindorm CLI / HBase Shell → references/03-ref/lindorm-cli-guide.md ├── Acceptance criteria → references/03-ref/acceptance-criteria.md └── Verification methods → references/03-ref/verification-method.md ``` ## Quick Mapping Table | User says | Scenario | Reference Doc | |-----------|----------|---------------| | "how to connect / connection address" | Connection setup | `references/01-dev/connection-guide.md` | | "create table / insert / query examples" | Quick start | `references/01-dev/quick-start-guide.md` | | "how to create a table" | Table design | `references/01-dev/table-design.md` | | "SQL syntax" | SQL reference | `references/01-dev/sql-operations.md` | | "how to use SQL" | SQL guide | `references/01-dev/sql-client-guide.md` | | "MySQL compatibility" | SQL notes | `references/01-dev/sql-usage-notes.md` | | "list instances / what instances exist" | Instance management | `references/02-ops/instance-management.md` | | "CPU / memory / QPS / latency" | Monitoring query | `references/02-ops/monitoring-guide.md` | | "configure alerts / alert notifications" | Monitoring alerts | `references/02-ops/monitoring-guide.md` | | "got an error / error code" | Error troubleshooting | `references/02-ops/error-troubleshoot.md` | | "slow query / query is slow" | Slow query analysis | `references/02-ops/slow-query-analysis.md` | | "poor performance / high RT" | Monitoring query | `references/02-ops/monitoring-guide.md` | | "cannot connect / connection timeout" | Connection diagnostics | `references/02-ops/connection-troubleshoot.md` | | "storage usage" | Storage analysis | `references/02-ops/storage-analysis.md` | | "hot/cold data / tiered storage" | Storage analysis | `references/02-ops/storage-analysis.md` | | "scale up / add nodes" | Scaling | `references/02-ops/instance-management.md` | | "backup / restore data" | Backup & restore | `references/02-ops/backup-restore.md` | | "data migration / sync" | Data migration | `references/02-ops/data-migration.md` | | "create account / permissions" | Permission management | `references/02-ops/user-permission.md` | | "lindorm-cli / lindormcli" | Lindorm CLI | `references/03-ref/lindorm-cli-guide.md` | | "HBase Shell / hbase shell" | HBase Shell | `references/03-ref/lindorm-cli-guide.md` | ## Aliyun CLI ### Prerequisites When CLI invocation is required, the Agent must verify: 1. **CLI installed**: `aliyun version` >= 3.3.3; if not installed, see `references/03-ref/cli-installation-guide.md` 2. **Credentials configured**: > **Security Rules:** > - **NEVER** read, echo, or print AK/SK values > - **NEVER** ask the user to input AK/SK directly in the conversation or command line > - **ONLY** use `aliyun configure list` to check credential status > > If no valid profile exists, STOP. Configure credentials **outside of this session**. 3. **Permissions granted**: Minimum `AliyunLindormReadOnlyAccess` + `AliyunCloudMonitorReadOnlyAccess` > **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted ### AI-Mode Lifecycle [Internal Agent Rule — Do NOT Show to User] > **[MUST] AI-Mode Full Lifecycle** — AI-mode is required for Agent Skill execution. > > **Step 1: Enable AI-Mode** — At the **start** of the Core Workflow (before any CLI invocation): > ```bash > aliyun configure ai-mode enable > ``` > > **Step 2: Set User-Agent** — Immediately after enabling AI-Mode: > ```bash > aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-lindorm-agent-skill" > ``` > > **Step 3: Update Plugins** — Ensure CLI plugins are up-to-date: > ```bash > aliyun configure set --auto-plugin-install true > aliyun plugin update > ``` > > **Step 4: Disable AI-Mode at EVERY exit point** — Before delivering the final response for ANY reason (success, failure, error, cancellation), always disable AI-mode first: > ```bash > aliyun configure ai-mode disable > ``` ### Parameter Confirmation Before executing any command, all user-configurable parameters (region, instance ID, time range, etc.) **must** be confirmed with the user. ### Version Detection For instance operations, the Agent must first call `get-lindorm-instance` to retrieve `ServiceType` and determine the instance version. All subsequent command selection depends on this: | ServiceType | Version | Deployment | |------------|---------|-----------| | `lindorm` | V1 | Single-AZ | | `lindorm_multizone` | V1 | Multi-AZ (HA) | | `lindorm_multizone_basic` | V1 | Multi-AZ (Basic) | | `lindorm_v2` | V2 | Single-AZ | | `lindorm_v2_multizone` | V2 | Multi-AZ (Basic) | | `lindorm_v2_multizone_ha` | V2 | Multi-AZ (HA) | ### General Policies **Region Policy** | Scenario | Command | Requires `--region` | |---------|---------|---------------------| | Query all-region overview | `get-instance-summary` | ❌ Not needed | | Query instance list | `get-lindorm-instance-list` | ✅ Required, default `cn-shanghai` | | Query instance details / engine / storage / whitelist | Other `hitsdb` commands | ❌ Not needed, auto-resolved by `--instance-id` | | Cloud monitoring query | `cms` commands | ❌ Not needed, region auto-resolved via `instanceId` | **Time Format** Cloud Monitor time parameter timezone notes: - ✅ `2026-04-14 08:00:00` (local time, parsed as **CST Beijing time**) - ✅ `1773897600000` (Unix millisecond timestamp, no timezone ambiguity) - ✅ `2026-04-14T08:00:00Z` (ISO 8601 UTC **full format**, parsed as **UTC**, i.e. CST+8 = 16:00) - ❌ `2026-04-14T08:00Z` (ISO 8601 **short format, no seconds — unsupported**, returns `parse param time error`) - ❌ **Never use UTC Z format for user-intended local times** (e.g. if user says "14:00", write `2026-04-14 14:00:00`, not `2026-04-14T14:00:00Z`) - ⚠️ Note: local time and ISO 8601 Z format query different time windows — common source of timezone-related issues ### Command Reference #### Instance Management (hitsdb — Lindorm product alias) | Command | Description | Example | |---------|-------------|---------| | `aliyun hitsdb describe-regions` | List supported regions | `aliyun hitsdb describe-regions` | | `aliyun hitsdb get-instance-summary` | All-region instance overview (no `--region` needed) | `aliyun hitsdb get-instance-summary` | | `aliyun hitsdb get-lindorm-instance-list` | List instances (ID, status, engine flags; filterable by region/type) | `aliyun hitsdb get-lindorm-instance-list --region cn-shanghai` | | `aliyun hitsdb get-lindorm-instance` | Get config/version/status (ServiceType, engine node count, spec; **no connection address**) | `aliyun hitsdb get-lindorm-instance --instance-id ld-xxx` | | `aliyun hitsdb get-lindorm-instance-engine-list` | Get connection addresses (host:port per engine, public/private network) | `aliyun hitsdb get-lindorm-instance-engine-list --instance-id ld-xxx` | | `aliyun hitsdb get-lindorm-fs-used-detail` | V1 storage usage details | `aliyun hitsdb get-lindorm-fs-used-detail --instance-id ld-xxx` | | `aliyun hitsdb get-lindorm-v2-storage-usage` | V2 storage usage details | `aliyun hitsdb get-lindorm-v2-storage-usage --instance-id ld-xxx` | | `aliyun hitsdb get-instance-ip-white-list` | Get IP whitelist | `aliyun hitsdb get-instance-ip-white-list --instance-id ld-xxx` | #### Engine Types | Engine | V1 Code | V2 Code | Notes | |--------|---------|---------|-------| | LindormTable | `lindorm` | `lindorm` | HBase-compatible, supports SQL (recommended) | | LindormTable (columnar) | — | `lcolumn` | V2 only | | LindormTSDB | `tsdb` | `tsdb` | Time-series data storage | | LindormSearch | `solr` | `lsearch` | Port 30070 (ES-compatible) / 10020 (Solr internal) | | Lindorm Tunnel Service | `bds` | `bds` | Formerly BDS, no external connection | | Compute Engine | `compute` | `compute` | Flink streaming engine, no external connection | | Stream Engine | `stream` | `lstream` | Port 33060 (MySQL protocol) | | Message Engine | — | `lmessage` | Kafka-compatible, supports topic management and message production/consumption | | Vector Engine | `lvector` | `lvector` | Vector retrieval engine | | AI Engine | `lai` | `lai` | AI retrieval engine; domain `proxy-ai-vpc` / `proxy-aiproxy-vpc` | | LindormDFS | `file` | `file` | OSS-compatible storage (HDFS protocol, port 9000) | #### Port Quick Reference | Engine | Protocol | Port | Notes | |--------|----------|------|-------| | LindormTable | MySQL protocol | 33060 | ✅ Recommended, preferred for SQL connections | | LindormTable | HBase API | 30020 | HBase native API compatible | | LindormTable | Avatica protocol | 30060 | ⚠️ Legacy only, migrate to MySQL protocol | | LindormTable | Cassandra CQL | 9042 | ⚠️ Legacy only, Cassandra protocol compatible | | Stream Engine | MySQL protocol | 33060 | Stream SQL via MySQL protocol | | LindormTSDB | HTTP SQL | 8242 | HTTP SQL API | | LindormSearch | ES-compatible / Solr | 30070 | Elasticsearch-compatible port, fixed | | LindormDFS | HDFS | 9000 | NameNode port | #### Cloud Monitor API (aliyun cms) | Command | Description | Example | |---------|-------------|---------| | `aliyun cms describe-metric-meta-list` | List available monitoring metrics | `aliyun cms describe-metric-meta-list --namespace acs_lindorm` | | `aliyun cms describe-metric-last` | Get latest monitoring data (returns per-node data; Datapoints is a JSON string requiring secondary parsing) | `aliyun cms describe-metric-last --namespace acs_lindorm --metric-name cpu_idle --dimensions '[{"instanceId":"ld-xxx"}]'` | | `aliyun cms describe-metric-data` | Get historical trend data (aggregated by period, no host dimension) | `aliyun cms describe-metric-data --namespace acs_lindorm --metric-name cpu_idle --dimensions '[{"instanceId":"ld-xxx"}]' --start-time "2026-04-14 08:00:00" --end-time "2026-04-14 09:00:00" --period 60` | **Metric Mapping** | User says | V1 Metric | V2 Metric | Unit | |-----------|-----------|-----------|------| | CPU usage | `100 - cpu_idle` | `100 - cpu_idle` | % | | Memory usage | `mem_used_percent` | `1 - mem_free / mem_total` | % | | QPS | `read_ops` + `write_ops` | `read_ops` + `write_ops` | ops/s | | Latency / RT | `read_rt` / `get_rt_avg` | `read_rt` / `get_rt_avg` | ms | | P99 latency | `get_rt_p99` / `put_rt_p99` | — (no data) | ms | | Hot storage usage rate | `hot_storage_used_percent` | `get-lindorm-v2-storage-usage` | % | | Total storage usage rate | `storage_used_percent` | `get-lindorm-v2-storage-usage` | % | | Hot storage bytes | `hot_storage_used_bytes` | `get-lindorm-v2-storage-usage` | bytes | | Cold storage usage rate | `cold_storage_used_percent` | `get-lindorm-v2-storage-usage` | % | | Cold storage bytes | `cold_storage_used_bytes` | `get-lindorm-v2-storage-usage` | bytes | Full metric details: `references/02-ops/monitoring-guide.md` ## Interaction Guidelines ### Output Format **Monitoring Query**: ``` [Summary] CPU usage 25% (normal) [Time] [Trend] Stable (variance <10%) [Details] avg 24.5%, max 32.1%, min 18.3% ``` **Error Troubleshooting**: ``` [Error Code] InvalidParameter.InstanceId [Meaning] Instance ID is invalid or does not exist [Possible Causes] 1.xxx 2.xxx 3.xxx [Resolution Steps] 1.xxx 2.xxx 3.xxx ``` **Instance List**: ``` [Region] cn-shanghai [Count] 3 | ID | Name | Status | Engines | |----|------|--------|---------| | ld-xxx | prod | Running | LindormTable + LindormTSDB | ``` ## Code Generation Standards ### General Principles 1. **Reference Skill documents first**: Lindorm is domain-specific knowledge — information must come from references docs; direct answers from training knowledge are prohibited 2. **Check official docs when Skill doesn't cover it**: For scenarios not covered by references docs, consult official Alibaba Cloud documentation ### Pre-Generation Checklist - □ Connection parameter names are correct (MySQL protocol: `jdbc:mysql://host:33060`, HBase API: `hbase.zookeeper.quorum`) - □ Port numbers are correct (LindormTable/Stream Engine MySQL 33060, HBase API 30020, LindormTSDB HTTP 8242, LindormSearch 30070) - □ Include official documentation link FILE:references/01-dev/connection-guide.md # 连接信息获取场景当用户询问"怎么连接实例"、"连接地址是什么"、"需要什么 SDK"时，按本指南执行。 ## 触发条件用户的典型表达： - "怎么连接 ld-xxx？" - "给我连接地址" - "用 Java 怎么连接？" - "时序引擎的端口是多少？" - "给我一个连接示例" ## 核心原则 **Agent 是解决方案提供者**，而不是指路者： 2. **Agent 提取关键信息**并整理成完整答案（代码示例、依赖配置、参数说明） 3. **用户无需离开对话**就能得到可执行的连接代码 4. 连接地址从 API 无法获取时，**明确告知控制台精确路径**（精确到按钮位置） 5. 文档链接作为补充参考，用户如需深入了解可查看 --- ## 执行流程 ### 阶段一：获取实例基本信息执行以下命令获取实例的架构版本、连接端点和网络配置： ```bash # 1. 获取实例详情（判断 V1/V2 架构） aliyun hitsdb get-lindorm-instance \ --instance-id # 2. 获取各引擎连接端点 aliyun hitsdb get-lindorm-instance-engine-list \ --instance-id ``` **需要提取的关键信息**： | 信息项 | 来源字段 | 说明 | |--------|----------|------| | 架构版本 | `ServiceType` | `lindorm_v2*` = V2 新架构, `lindorm` = V1 老架构 | | 连接地址 | `NetInfoList`（V1/V2 均使用此字段） | 各引擎的域名和端口 | | 网络类型 | `NetType` | `"0"` = 公网可用, `"2"` = 仅 VPC 内网（字符串类型，V1/V2 相同） | | 引擎版本 | `EngineList` | 各引擎的版本号 | > **注意**：`get-lindorm-instance-engine-list` 对 V1 和 V2 都返回 `NetInfoList` + `NetType`。另一个 V2 专属 API `get-lindorm-v2-instance-details` 返回 `ConnectAddressList` + `Type=INTRANET/INTERNET`，见阶段二。 **端点域名格式**：域名格式见 [sql-client-guide.md](sql-client-guide.md)，含V1/V2 ServiceType判断逻辑和完整示例 --- ### 阶段二：确认连接条件在提供连接代码前，必须确认以下两项： #### 1. 公网访问检查 **方式一：通过 `get-lindorm-instance-engine-list`（V1/V2 通用）** 检查 `NetInfoList` 中的 `NetType` 字段（字符串类型）： - `"0"`: 公网可用 - `"2"`: 仅 VPC 内网 **方式二：通过 `get-lindorm-v2-instance-details`（仅 V2）** 检查 `ConnectAddressList` 中的 `Type` 字段： - `INTERNET`: 公网可用 - `INTRANET`: 仅 VPC 内网 **如果只有 VPC 内网地址（NetType="2" 或 Type=INTRANET）**： > ⚠️ 当前实例 SQL 端口仅支持 VPC 内网访问。从本地电脑连接需要： > 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) > 2. 点击实例 ID → **数据库连接** → **引擎** 页签 > 3. 点击右上角 **「开通公网地址」** > 4. 配置白名单（您的本地 IP 地址） > > 或者，您可以在阿里云 ECS（与 Lindorm 同 VPC）上执行连接和操作。 #### 2. 密码获取与确认 **V2 实例**： ```bash aliyun hitsdb get-lindorm-v2-instance-details \ --instance-id ``` 提取 `InitialRootPassword` 字段，用户名为 `root`。 > ⚠️ **密码获取/确认流程：** > 1. **首次连接**：使用 `InitialRootPassword` > 2. **连接失败/密码错误**：停止执行，**必须询问用户**当前密码 > 3. **执行变更操作**（如创建表、修改配置）：**必须获得用户明确授权** **V1 实例**： - **默认用户名**：`root` - **默认密码**：`root` - **如果忘记密码**：通过集群管理系统修改 - 路径：[Lindorm 控制台](https://lindorm.console.aliyun.com/) → 实例 ID → **数据库连接** → **宽表引擎** → **Lindorm Insight** → **用户管理** - 修改密码后需要**重启引擎**才能生效 --- ### 阶段三：提供连接信息整理阶段一、二获取的信息，直接给用户完整的连接方案： ``` 实例 ld-xxx 已开通以下引擎： - 宽表引擎（版本 2.8.6，V2 新架构） - 时序引擎（版本 2.7.15）【连接地址】（已通过 API 获取） - 内网（VPC）：ld-xxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 - 公网：ld-xxx-proxy-lindorm-pub.lindorm.aliyuncs.com:33060 > ⚠️ 从公网（本地电脑等）连接时，必须使用公网地址（`-pub`），不能用内网地址（`-vpc`），否则连接超时。【SQL 连接凭证】 - 用户名：root - 密码：（V2 实例已通过 get-lindorm-v2-instance-details 获取 InitialRootPassword； V1 实例请在控制台 Lindorm Insight → 用户管理中查看） ``` **连通性验证**（MySQL 命令行）： ```bash mysql -h <连接地址> -P 33060 -u root -p \ --get-server-public-key --ssl-mode=DISABLED ``` 连接成功后提示用户： > 连接已验证成功。需要建表、写入数据的完整示例吗？可以告诉我您使用的引擎类型，我为您提供完整代码。 **各引擎端口速查**： | 引擎 | 协议 | 端口 | |------|------|------| | 宽表引擎 | MySQL 协议（推荐） | 33060 | | 宽表引擎 | HBase API | 30020 | | 时序引擎 | HTTP SQL API | 8242 | | 搜索引擎 | Elasticsearch API | 30070 | | 流引擎 | MySQL 协议 | 33060 | **各引擎连接方式总览**（Agent 根据用户需求路由到正确的文档）： | 引擎 | 连接方式 | 推荐 | 官方文档 | |------|---------|------|----------| | 宽表引擎 | MySQL 协议 SQL | ⭐ 推荐 | [Java JDBC](https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-java-jdbc-interface)、[Python](https://help.aliyun.com/zh/lindorm/user-guide/python-based-application-development-1)、多语言见 [sql-client-guide.md](sql-client-guide.md) | | 宽表引擎 | HBase API | 常用 | [Java](https://help.aliyun.com/zh/lindorm/user-guide/use-the-hbase-api-for-java-to-connect-to-and-use-the-wide-table-engine)、[非Java](https://help.aliyun.com/zh/lindorm/user-guide/use-the-hbase-api-for-a-non-java-language-to-connect-to-and-use-the-wide-table-engine)，代码示例见 [quick-start-guide.md 场景F](quick-start-guide.md#场景-f宽表引擎-hbase-api-快速开始) | | 宽表引擎 | Cassandra CQL | 存量 | [Java Driver](https://help.aliyun.com/zh/lindorm/user-guide/use-a-cassandra-client-driver-for-java-to-connect-to-and-use-the-wide-table-engine)、[非Java](https://help.aliyun.com/zh/lindorm/user-guide/use-a-multi-language-cassandra-client-driver-to-connect-to-and-use-the-wide-table-engine) | | 宽表引擎 | S3 协议 | 存量 | [Java](https://help.aliyun.com/zh/lindorm/user-guide/connect-and-use-the-wide-table-engine-with-the-s3)、[非Java](https://help.aliyun.com/zh/lindorm/user-guide/connect-via-s3-non-java-api-and-use-the-wide-table) | | 时序引擎 | JDBC Driver | ⭐ 推荐 | [JDBC Driver](https://help.aliyun.com/zh/lindorm/user-guide/use-the-jdbc-driver-for-lindorm-to-connect-to-and-use-lindormtsdb) | | 时序引擎 | HTTP SQL API | 轻量 | [HTTP API](https://help.aliyun.com/zh/lindorm/user-guide/http-sql-api-user-guide) | | 搜索引擎 | Elasticsearch API | ⭐ 推荐 | [Java REST Client](https://help.aliyun.com/zh/lindorm/user-guide/java-low-level-rest-client) | | 向量引擎 | Elasticsearch API | ⭐ 推荐 | 复用搜索引擎端口 30070，[向量开发指南](https://help.aliyun.com/zh/lindorm/user-guide/foundation) | | 流引擎 | MySQL 协议 ETL SQL | ⭐ 推荐 | [实时ETL](https://help.aliyun.com/zh/lindorm/user-guide/real-time-etl) | | 流引擎 | Kafka 客户端 | 数据接入 | [Kafka写入](https://help.aliyun.com/zh/lindorm/use-an-open-source-apache-kafka-client-to-write-data-to-the-lindorm-streaming-engine) | | LindormDFS | HDFS Shell / 客户端 | - | [底层文件访问概览](https://help.aliyun.com/zh/lindorm/user-guide/lindormdfs)、[运维指南](https://help.aliyun.com/zh/lindorm/user-guide/lindormdfs-user-guide/) | | 计算引擎 | JDBC / JAR / Python | - | [JDBC访问](https://help.aliyun.com/zh/lindorm/user-guide/use-sql-to-connect-to-ldps)、[JAR作业](https://help.aliyun.com/zh/lindorm/user-guide/jar-job-development-practice) | > **LindormDFS 和计算引擎** Skill 不提供代码示例，如用户询问请引导至上述官方文档或[连接总览](https://help.aliyun.com/zh/lindorm/getting-started/connect-to-an-instance)。 --- ### 阶段四：白名单检查 **Agent 主动检查白名单**： ```bash aliyun hitsdb get-instance-ip-white-list \ --instance-id ``` **分析后给出明确建议**： ``` 【白名单检查】当前白名单配置：10.0.0.0/8 【分析】 - 如果您的客户端 IP 在 10.0.0.0/8 网段内 → ✅ 可以直接连接 - 如果您的客户端 IP 不在白名单中 → ❌ 需要添加【添加白名单】（精确步骤） 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) → 在实例列表页，单击**目标实例ID** → 在左侧导航栏，单击**访问控制** → **白名单** 2. 点击"创建分组白名单"或修改已有分组 3. 添加客户端 IP（内网环境填 VPC IP，公网环境填公网 IP） - 单个 IP：192.168.1.100 - IP 段：192.168.1.0/24 4. 点击"确定"保存 > 💡 查看自己公网 IP：`curl ifconfig.me` 【安全提示】 - ⚠️ 不建议使用 0.0.0.0/0（允许所有 IP），存在安全风险 - ✅ 建议只添加必要的 IP 或 VPC 网段需要我帮您排查连接问题吗？ ``` --- ## 下一步引导连接验证成功后，根据用户需求引导： - **建表/写入/查询** → 参考 [quick-start-guide.md](quick-start-guide.md)（含宽表、时序、搜索、向量、流引擎完整示例） - **连接失败排查** → 参考 [connection-troubleshoot.md](../02-ops/connection-troubleshoot.md) - **用户权限管理** → 参考 [user-permission.md](../02-ops/user-permission.md) FILE:references/01-dev/quick-start-guide.md # 快速开始场景当用户询问"怎么建表"、"怎么写入数据"、"怎么查询数据"等开发入门问题时，按本指南执行。 ## 触发条件用户的典型表达： - "怎么建表？" - "怎么写入数据？" - "给我一个完整的示例" - "宽表引擎怎么用？" - "时序数据怎么存储？" ## 核心原则 **Agent 主动做重活**，而不是让用户自己探索： 1. **Agent 提取完整代码示例**，直接给用户可执行的代码 2. 只在必要时附上文档链接作为"了解更多"的补充 3. **目标**：用户拿到代码后可以直接运行，无需再自己查文档 --- ## 执行流程 ### 步骤 1：确认引擎类型先询问用户使用哪个引擎（如果未明确）： ``` 您想使用哪个引擎？ 1. 宽表引擎（适合半结构化数据，兼容 HBase） 2. 时序引擎（适合 IoT、监控等时序数据） 3. 搜索引擎（适合全文检索）或者告诉我您的使用场景，我来推荐引擎。 ``` --- ### 步骤 2：Agent 查询官方文档并生成完整示例 **⚠️ 强制要求**：在提供任何代码示例之前，**必须**从 Skill references 文档获取信息，Skill 未覆盖时查询官方文档确认。 **Agent 需要做的**：根据引擎类型，访问阿里云 Lindorm 官方文档获取最新示例 **查询目标**： - 官方文档：https://help.aliyun.com/zh/lindorm/ - 关键信息：建表、写入、查询的完整代码示例 **必须从官方文档中提取并验证**： - ✅ 最新的 Maven 依赖版本（不是训练数据中的旧版本） - ✅ 正确的 API 调用方式（如 Connection vs HConnection） - ✅ 当前推荐的建表语句格式 - ✅ 官方验证过的写入/查询代码 - ✅ 最佳实践和性能优化建议 **验证清单**： ``` 在提供代码之前，Agent 必须确认： □ 已访问官方文档获取最新示例 □ SDK 版本号是最新的（如 alilindorm-table-sdk 2.x） □ API 调用方式是当前推荐的（不是已废弃的 API） □ 建表/写入/查询代码经过官方验证 □ 已附上官方文档链接供用户深入学习 ``` **然后整理成完整可执行的代码，直接给用户**。 --- ## 按引擎类型生成完整示例 ### 场景 A：宽表引擎快速开始 **Agent 执行查询后，直接给用户完整答案**： ``` 【宽表引擎完整示例】我已为您准备好从连接到查询的完整代码（基于官方文档最新版本）： ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：添加 Maven 依赖】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ com.mysql mysql-connector-j 8.3.0 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：连接实例】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ import java.sql.*; import java.util.Properties; public class LindormQuickStart { public static void main(String[] args) throws Exception { // 1. 配置连接（MySQL 协议，推荐） // Agent 根据实例 ServiceType 选择正确的域名格式，参见 sql-client-guide.md Class.forName("com.mysql.cj.jdbc.Driver"); String url = "jdbc:mysql://<您的连接地址>:33060/default?sslMode=disabled"; Properties props = new Properties(); props.setProperty("user", "your-username"); props.setProperty("password", "your-password"); Connection conn = DriverManager.getConnection(url, props); Statement stmt = conn.createStatement(); // 2. 建表 stmt.execute("CREATE TABLE IF NOT EXISTS users (" + "id VARCHAR PRIMARY KEY," + "name VARCHAR," + "age INT," + "city VARCHAR)"); System.out.println("表创建成功"); // 3. 写入数据 stmt.execute("INSERT INTO users (id, name, age, city) VALUES " + "('1', 'Alice', 25, 'Shanghai'), " + "('2', 'Bob', 30, 'Beijing')"); System.out.println("数据写入成功"); // 4. 查询数据 ResultSet rs = stmt.executeQuery("SELECT * FROM users WHERE age > 20"); while (rs.next()) { System.out.println("name=" + rs.getString("name") + ", age=" + rs.getInt("age")); } // 5. 关闭连接 rs.close(); stmt.close(); conn.close(); } } ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【批量写入优化】（生产环境推荐） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ // 批量写入（使用 PreparedStatement） String sql = "INSERT INTO users (id, name, age, city) VALUES (?, ?, ?, ?)"; PreparedStatement pstmt = conn.prepareStatement(sql); for (int i = 0; i < 10000; i++) { pstmt.setString(1, "id_" + i); pstmt.setString(2, "user_" + i); pstmt.setInt(3, 20 + i % 50); pstmt.setString(4, "city_" + i % 10); pstmt.addBatch(); if (i % 1000 == 0) { pstmt.executeBatch(); // 每 1000 行提交一次 } } pstmt.executeBatch(); // 提交剩余数据【完整文档】如需了解更多（二级索引、全局索引、性能优化）： https://help.aliyun.com/zh/lindorm/user-guide/lindorm-wide-table-engine ``` --- ### 场景 B：时序引擎快速开始 **Agent 从官方文档提取最新示例**： > **推荐连接方式**：官方推荐使用 [JDBC Driver](https://help.aliyun.com/zh/lindorm/user-guide/use-the-jdbc-driver-for-lindorm-to-connect-to-and-use-lindormtsdb)（支持 Java）。以下示例采用 HTTP SQL API（轻量级，适合 Python 等非 Java 语言快速验证）。参考文档：https://help.aliyun.com/zh/lindorm/user-guide/http-sql-api-user-guide **然后直接给用户完整代码**： ``` 【时序引擎完整示例】（Python HTTP SQL API）我已为您准备好时序数据写入和查询的完整代码： ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：安装依赖】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ pip install requests ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：完整示例代码】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ import requests import time # 1. 连接配置 host = "您的时序引擎连接地址" # 从控制台"数据库连接"页面获取 port = 8242 url = f"http://{host}:{port}/api/v2/sql" # 2. 建表 create_sql = """CREATE TABLE IF NOT EXISTS sensor ( device_id VARCHAR NOT NULL, region VARCHAR NOT NULL, time TIMESTAMP NOT NULL, temperature DOUBLE, humidity BIGINT, PRIMARY KEY(device_id, region, time) )""" response = requests.post(url, data=create_sql) print(f"建表结果: {response.status_code}") # 3. 写入数据（单条） insert_sql = f"""INSERT INTO sensor (device_id, region, time, temperature, humidity) VALUES ('F07A1260', 'north-cn', '{time.strftime('%Y-%m-%d %H:%M:%S')}', 75.3, 45)""" response = requests.post(url, data=insert_sql) print(f"写入结果: {response.status_code}") # 4. 批量写入（推荐） # 注意：主键为 (device_id, region, time)，同一设备同一时间戳会 UPSERT 覆盖 import datetime now = datetime.datetime.now() times = [(now + datetime.timedelta(seconds=i)).strftime('%Y-%m-%d %H:%M:%S') for i in range(4)] batch_sql = f"""INSERT INTO sensor (device_id, region, time, temperature, humidity) VALUES ('F07A1260', 'north-cn', '{times[0]}', 75.3, 45), ('F07A1260', 'north-cn', '{times[1]}', 76.1, 47), ('F07A1261', 'south-cn', '{times[2]}', 18.1, 44), ('F07A1261', 'south-cn', '{times[3]}', 19.7, 44)""" response = requests.post(url, data=batch_sql) print(f"批量写入结果: {response.status_code}") # 5. 查询数据 query_sql = "SELECT device_id, region, time, temperature FROM sensor LIMIT 100" response = requests.post(url, data=query_sql) result = response.json() for row in result.get('rows', []): print(f"设备: {row[0]}, 区域: {row[1]}, 时间: {row[2]}, 温度: {row[3]}") ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【生产环境建议】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. 批量写入：每次写入 100-1000 个数据点 2. 数据压缩：时序引擎自动压缩，无需手动配置 3. TTL 设置：建议设置数据过期时间（如 90 天） 4. 异常处理：添加重试机制和错误日志【完整文档】如需了解更多（HTTP API 详细参数、降采样、预聚合、TTL）： https://help.aliyun.com/zh/lindorm/user-guide/http-sql-api-user-guide ``` --- ### 场景 C：搜索引擎快速开始 **Agent 执行查询后，直接给用户完整答案**： ``` 【搜索引擎完整示例】（兼容 Elasticsearch 7.10 API）我已为您准备好搜索引擎的完整代码（Java Low Level REST Client）： ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：获取连接信息】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 控制台 → 数据库连接 → 搜索引擎页签 - Elasticsearch 兼容地址（专有网络或公网） - 默认用户名和密码 - 端口固定为 30070 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：添加 Maven 依赖】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ org.elasticsearch.client elasticsearch-rest-client 7.10.0 org.apache.logging.log4j log4j-core 2.8.2 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 3：连接并操作】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ import org.apache.http.HttpHost; import org.apache.http.auth.AuthScope; import org.apache.http.auth.UsernamePasswordCredentials; import org.apache.http.client.CredentialsProvider; import org.apache.http.impl.client.BasicCredentialsProvider; import org.apache.http.impl.nio.client.HttpAsyncClientBuilder; import org.elasticsearch.client.RestClient; import org.elasticsearch.client.RestClientBuilder; import org.elasticsearch.client.Request; import org.elasticsearch.client.Response; import org.apache.http.util.EntityUtils; public class LindormSearchQuickStart { public static void main(String[] args) throws Exception { // 1. 配置连接（Elasticsearch 兼容，端口 30070） // Agent 根据实例 ServiceType 选择域名格式：V1=.lindorm.rds.aliyuncs.com，V2=.lindorm.aliyuncs.com String searchUrl = "ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com"; int searchPort = 30070; String username = "user"; // 从控制台获取 String password = "test"; // 从控制台获取 final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials(username, password)); RestClientBuilder builder = RestClient.builder(new HttpHost(searchUrl, searchPort)); builder.setHttpClientConfigCallback(httpClientBuilder -> httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider)); try (RestClient client = builder.build()) { String indexName = "products"; // 2. 创建索引 Request createReq = new Request("PUT", "/" + indexName); createReq.setJsonEntity("{" + " \"settings\":{\"index.number_of_shards\": 1}," + " \"mappings\":{" + " \"properties\":{" + " \"name\":{\"type\":\"text\"}," + " \"price\":{\"type\":\"double\"}," + " \"category\":{\"type\":\"keyword\"}" + " }" + " }" + "}"); Response resp = client.performRequest(createReq); System.out.println("创建索引: " + EntityUtils.toString(resp.getEntity())); // 3. 批量写入文档 Request bulkReq = new Request("POST", "/_bulk"); StringBuilder bulk = new StringBuilder(); bulk.append("{\"index\":{\"_index\":\"products\",\"_id\":\"1\"}}\n"); bulk.append("{\"name\":\"iPhone 15\",\"price\":7999.0,\"category\":\"手机\"}\n"); bulk.append("{\"index\":{\"_index\":\"products\",\"_id\":\"2\"}}\n"); bulk.append("{\"name\":\"MacBook Pro\",\"price\":14999.0,\"category\":\"电脑\"}\n"); bulk.append("{\"index\":{\"_index\":\"products\",\"_id\":\"3\"}}\n"); bulk.append("{\"name\":\"AirPods Pro\",\"price\":1899.0,\"category\":\"耳机\"}\n"); bulkReq.setJsonEntity(bulk.toString()); client.performRequest(bulkReq); System.out.println("批量写入完成"); // 4. 刷新索引（强制写入数据可见） client.performRequest(new Request("POST", "/" + indexName + "/_refresh")); // 5. 全文检索 Request searchReq = new Request("GET", "/" + indexName + "/_search"); searchReq.setJsonEntity("{" + " \"query\":{" + " \"match\":{\"name\":\"Pro\"}" + " }" + "}"); resp = client.performRequest(searchReq); System.out.println("搜索结果: " + EntityUtils.toString(resp.getEntity())); // 6. 查询单个文档 resp = client.performRequest(new Request("GET", "/" + indexName + "/_doc/1")); System.out.println("文档1: " + EntityUtils.toString(resp.getEntity())); // 7. 删除索引 client.performRequest(new Request("DELETE", "/" + indexName)); System.out.println("索引已删除"); } } } ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【curl 快速验证】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # 创建索引 curl -u user:password -X PUT "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/products" \ -H 'Content-Type: application/json' -d ' {"settings":{"index.number_of_shards":1}, "mappings":{"properties":{"name":{"type":"text"},"price":{"type":"double"}}}}' # 写入文档 curl -u user:password -X POST "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/products/_doc/1" \ -H 'Content-Type: application/json' -d '{"name":"iPhone 15","price":7999}' # 全文检索 curl -u user:password -X GET "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/products/_search" \ -H 'Content-Type: application/json' -d '{"query":{"match":{"name":"iPhone"}}}' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【搜索引擎关键参数】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 参数 | 值 | 说明 | |------|-----|------| | 端口 | **30070** | Elasticsearch 兼容端口，固定不变 | | 协议 | HTTP | 不支持 HTTPS | | 认证 | Basic Auth | 用户名密码从控制台获取 | | 兼容版本 | ES 7.10 | 兼容 Elasticsearch 7.10 及更早版本 API | | 写入后可见 | 需手动 _refresh | 或等待自动 refresh（默认1秒） | 【完整文档】搜索引擎开发指南： https://help.aliyun.com/zh/lindorm/user-guide/lindormsearch/ https://help.aliyun.com/zh/lindorm/user-guide/java-low-level-rest-client ``` --- ### 场景 D：向量引擎快速开始 **Agent 执行查询后，直接给用户完整答案**： ``` 【向量引擎完整示例】（通过搜索引擎 ES API 访问） Lindorm 向量引擎无独立连接地址，通过搜索引擎的 Elasticsearch 兼容 API 访问（端口 30070）。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：获取连接信息】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 与搜索引擎相同： - 连接地址：搜索引擎的 Elasticsearch 兼容地址（公网或 VPC） - 端口：30070 - 认证：Basic Auth（用户名/密码） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：创建向量索引（hnsw）】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ curl -u user:password -X PUT "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/vector_test" \ -H 'Content-Type: application/json' -d '{ "settings": { "number_of_shards": 1, "knn": true }, "mappings": { "_source": {"excludes": ["vector1"]}, "properties": { "vector1": { "type": "knn_vector", "dimension": 3, "method": { "engine": "lvector", "name": "hnsw", "space_type": "l2", "parameters": { "m": 24, "ef_construction": 500 } } }, "field1": {"type": "long"}, "name": {"type": "keyword"} } } }' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 3：写入向量数据】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ curl -u user:password -X POST "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/_bulk" \ -H 'Content-Type: application/x-ndjson' -d ' {"index":{"_index":"vector_test","_id":"1"}} {"field1":1,"name":"苹果","vector1":[1.2,1.3,1.4]} {"index":{"_index":"vector_test","_id":"2"}} {"field1":2,"name":"香蕉","vector1":[2.2,2.3,2.4]} {"index":{"_index":"vector_test","_id":"3"}} {"field1":3,"name":"橙子","vector1":[3.2,3.3,3.4]} ' # 刷新索引使数据可见 curl -u user:password -X POST "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/vector_test/_refresh" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 4：KNN 近似搜索】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # 查找与 [1.3,1.4,1.5] 最相似的 3 个向量 # 注意：KNN 搜索默认不返回 _source，必须显式指定需要返回的字段 curl -u user:password -X GET "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/vector_test/_search" \ -H 'Content-Type: application/json' -d '{ "size": 3, "_source": ["field1", "name"], "query": { "knn": { "vector1": { "vector": [1.3,1.4,1.5], "k": 3 } } } }' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 5：向量+标量混合检索】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ curl -u user:password -X GET "http://ld-xxxx-proxy-search-pub.lindorm.rds.aliyuncs.com:30070/vector_test/_search" \ -H 'Content-Type: application/json' -d '{ "size": 3, "_source": ["field1", "name"], "query": { "bool": { "must": [ { "knn": { "vector1": { "vector": [1.3,1.4,1.5], "k": 10 } } } ], "filter": [ {"range": {"field1": {"gte": 1, "lte": 3}}} ] } } }' ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【向量引擎关键参数】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 参数 | 值 | 说明 | |------|-----|------| | 接入方式 | 搜索引擎 ES API | 无独立连接地址，复用搜索引擎端口 30070 | | 向量类型 | knn_vector | 需指定 dimension（维度） | | 索引算法 | hnsw | 支持 l2、cosinesimil（实测均可用） | | 写入后可见 | 需 _refresh | 或等待自动刷新 | 【完整文档】向量引擎开发指南： https://help.aliyun.com/zh/lindorm/user-guide/foundation ``` --- ### 场景 E：流引擎快速开始 **Agent 执行查询后，直接给用户完整答案**： ``` 【流引擎完整示例】（ETL SQL 实时同步与预计算） Lindorm 流引擎通过 MySQL 协议访问（端口 33060），使用 ETL SQL 实现实时数据同步和预计算。 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：在宽表引擎创建源表和结果表】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -- 连接宽表引擎（MySQL 协议） mysql -h <宽表引擎地址> -P 33060 -u root -p -- 创建源表 CREATE TABLE source_tbl(id INT, val DOUBLE, PRIMARY KEY(id)); -- 创建镜像表（实时同步目标） CREATE TABLE sink_tbl(id INT, val DOUBLE, PRIMARY KEY(id)); ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：在流引擎创建 ETL（实时镜像）】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -- 连接流引擎（MySQL 协议，端口相同） mysql -h <流引擎地址> -P 33060 -u root -p -- 创建实时同步 ETL CREATE ETL sync_etl AS INSERT INTO sink_tbl SELECT * FROM source_tbl; ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 3：验证实时同步】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -- 在宽表引擎插入数据 INSERT INTO source_tbl(id, val) VALUES (1, 1.1), (2, 2.2); -- 查询镜像表（数据已实时同步） SELECT * FROM sink_tbl; +------+------+ | id | val | +------+------+ | 1 | 1.1 | | 2 | 2.2 | +------+------+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 4：多表 JOIN 预计算】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -- 在宽表引擎创建用户表和订单表 CREATE TABLE user_tbl(user_id VARCHAR NOT NULL, user_name VARCHAR, PRIMARY KEY(user_id)); CREATE TABLE order_tbl( order_id VARCHAR NOT NULL, user_id VARCHAR, amount DOUBLE, PRIMARY KEY(order_id) ); -- 为 JOIN 字段创建索引（必须） CREATE INDEX idx_user_id ON order_tbl(user_id); -- 创建结果表（预打宽，需可更新） CREATE TABLE user_order_tbl( order_id VARCHAR NOT NULL, user_id VARCHAR, user_name VARCHAR, amount DOUBLE, PRIMARY KEY(order_id) ) WITH (MUTABILITY='MUTABLE_UDT'); -- 在流引擎创建 JOIN ETL（需使用完整表名） CREATE ETL join_etl AS INSERT INTO `lindorm_table`.`default`.`user_order_tbl`(order_id, user_id, user_name, amount) SELECT o.order_id, o.user_id, u.user_name, o.amount FROM `lindorm_table`.`default`.`order_tbl` o JOIN `lindorm_table`.`default`.`user_tbl` u ON o.user_id = u.user_id; -- 插入测试数据 INSERT INTO user_tbl VALUES ('U001', '张三'), ('U002', '李四'); INSERT INTO order_tbl VALUES ('O001', 'U001', 100.0), ('O002', 'U001', 200.0); -- 查询结果表（已实时 JOIN） SELECT * FROM user_order_tbl; +----------+---------+-----------+--------+ | order_id | user_id | user_name | amount | +----------+---------+-----------+--------+ | O001 | U001 | 张三 | 100.0 | | O002 | U001 | 张三 | 200.0 | +----------+---------+-----------+--------+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【流引擎关键参数】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 参数 | 值 | 说明 | |------|-----|------| | 连接方式 | MySQL 协议 | 与宽表引擎相同，端口 33060 | | 核心语法 | CREATE ETL | `CREATE ETL name AS INSERT INTO ... SELECT ...` | | 表名格式 | 完整路径 | 跨库查询需用 `lindorm_table.default.tablename` | | JOIN 要求 | 必须有索引 | JOIN key 需有二级索引，否则报错 | | 结果表 | MUTABLE_UDT | 预计算结果表需支持更新 | | 实时性 | 近实时 | 数据变更后秒级同步 | 【管理 ETL】 -- 查看所有 ETL SHOW ETLS; -- 删除 ETL DROP ETL IF EXISTS etl_name; 【完整文档】流引擎开发指南： https://help.aliyun.com/zh/lindorm/user-guide/real-time-etl ``` --- ### 场景 F：宽表引擎 HBase API 快速开始 **适用场景**：已有 HBase 应用迁移、需要 KV 级操作的场景。新用户推荐优先使用场景 A（MySQL 协议 SQL）。参考文档：https://help.aliyun.com/zh/lindorm/user-guide/use-the-hbase-api-for-java-to-connect-to-and-use-the-wide-table-engine HBase SDK 安装：https://help.aliyun.com/zh/lindorm/user-guide/install-and-upgrade-hbase-sdk-for-java **Agent 从官方文档提取最新示例**： ``` 【宽表引擎 HBase API 完整示例】（Java） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 1：添加 Maven 依赖】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ com.aliyun.hbase alihbase-client 1.8.8 com.aliyun.hbase alihbase-client 2.8.7 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 2：配置连接】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.hbase.*; import org.apache.hadoop.hbase.client.*; import org.apache.hadoop.hbase.util.Bytes; public class LindormHBaseQuickStart { public static void main(String[] args) throws Exception { // 1. 配置连接（端口 30020） // 连接地址从控制台"数据库连接"页面获取 HBase API 地址 Configuration conf = HBaseConfiguration.create(); conf.set("hbase.zookeeper.quorum", "<您的连接地址>:30020"); conf.set("hbase.client.username", "用户名"); conf.set("hbase.client.password", "密码"); // 2. 创建连接（线程安全，全局复用，程序结束时关闭） Connection connection = ConnectionFactory.createConnection(conf); ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 3：DDL 操作（建表/删表）】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ try (Admin admin = connection.getAdmin()) { // 建表 HTableDescriptor htd = new HTableDescriptor(TableName.valueOf("tablename")); htd.addFamily(new HColumnDescriptor(Bytes.toBytes("family"))); // 创建单分区表（生产环境建议预分区，避免热点） admin.createTable(htd); // 预分区建表示例（推荐） // byte[][] splitKeys = new byte[][] { // Bytes.toBytes("10"), Bytes.toBytes("20"), Bytes.toBytes("30") // }; // admin.createTable(htd, splitKeys); // disable 表（truncate/删除前必须先 disable） // admin.disableTable(TableName.valueOf("tablename")); // admin.truncateTable(TableName.valueOf("tablename"), true); // admin.deleteTable(TableName.valueOf("tablename")); } ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【步骤 4：DML 操作（读写删查）】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ // Table 为非线程安全对象，每个线程必须从 Connection 中获取自己的 Table try (Table table = connection.getTable(TableName.valueOf("tablename"))) { // 插入数据 Put put = new Put(Bytes.toBytes("row")); put.addColumn(Bytes.toBytes("family"), Bytes.toBytes("qualifier"), Bytes.toBytes("value")); table.put(put); // 单行读取 Get get = new Get(Bytes.toBytes("row")); Result res = table.get(get); // 删除一行数据 Delete delete = new Delete(Bytes.toBytes("row")); table.delete(delete); // Scan 范围查询 Scan scan = new Scan(Bytes.toBytes("startRow"), Bytes.toBytes("endRow")); ResultScanner scanner = table.getScanner(scan); for (Result result : scanner) { // 处理查询结果 } scanner.close(); } connection.close(); } } ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 【HBase API 关键参数】 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | 参数 | 值 | 说明 | |------|-----|------| | 端口 | **30020** | HBase API 专用端口，固定不变 | | Connection | 线程安全 | 全局创建一次，程序结束时关闭 | | Table | 非线程安全 | 每个线程必须获取自己的 Table 对象 | | 建表 | 建议预分区 | 单 Region 会导致热点，生产环境必须预分区 | | 认证 | 用户名/密码 | 从控制台获取 | 【完整文档】 - Java：https://help.aliyun.com/zh/lindorm/user-guide/use-the-hbase-api-for-java-to-connect-to-and-use-the-wide-table-engine - 非 Java（Thrift2）：https://help.aliyun.com/zh/lindorm/user-guide/use-the-hbase-api-for-a-non-java-language-to-connect-to-and-use-the-wide-table-engine ``` FILE:references/01-dev/sql-client-guide.md # Lindorm SQL 客户端开发指南本文档提供多语言连接 Lindorm SQL 的开发参考，包括 Java、Python、Go、C/C++、C#、Rust、PHP、Node.js 等语言的连接示例、连接池配置和框架集成方案。 > **推荐**: MySQL 协议更加稳定可靠，性能更优，推荐新用户使用 MySQL 协议连接宽表引擎。 ## 通用前提条件 - 已开通 MySQL 协议兼容功能（控制台 > 数据库连接 > 宽表引擎） - 已将客户端 IP 添加至白名单 - MySQL 协议端口请以 `SKILL.md` →「代码生成规范 / 端口号速查表」为准 ### 连接域名格式（Agent 根据实例类型自动选择） Lindorm 实例分为 V1 和 V2 两种架构，域名格式不同。Agent 执行时应： 1. **查询实例详情**获取 `ServiceType` 2. **判断架构类型**： - `lindorm_v2*` → 使用 V2 域名格式 - `lindorm` → 使用 V1 域名格式 3. **自动填充**正确的连接地址 | 架构 | ServiceType | 域名格式 | 内网示例 | 公网示例 | |------|-------------|----------|----------|----------| | **V2** | `lindorm_v2*` | `*.lindorm.aliyuncs.com` | `ld-xxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060` | `ld-xxx-proxy-lindorm-pub.lindorm.aliyuncs.com:33060` | | **V1** | `lindorm` | `*.lindorm.rds.aliyuncs.com` | `ld-xxx-proxy-lindorm.lindorm.rds.aliyuncs.com:33060` | `ld-xxx-proxy-lindorm-public.lindorm.rds.aliyuncs.com:33060` | > **V1 宽表引擎有两个 MySQL 地址**：`proxy-lindorm` 和 `proxy-sql-lindorm`，功能相同，任选其一即可。 > > **V1 公网地址需开通公网访问后才可用**，默认仅提供内网地址。公网地址后缀为 `-public`。 > > **获取方式**：控制台 → 实例详情 → 数据库连接，或执行 `aliyun hitsdb get-lindorm-instance-engine-list --instance-id ` --- ## 注意事项 - 只能基于本 Skill 文档中明确记载的内容回答用户问题，严禁推测、联想或凭训练知识生成文档中不存在的 SQL 语法、参数、功能或配置。 - 如果文档中没有相关信息，必须明确告知用户"当前文档未收录此内容"，并引导用户查阅阿里云官方文档（help.aliyun.com）确认。 - 生成的代码示例必须基于文档中的模板，参数和语法必须与文档一致。 --- ## 执行步骤 ### 步骤1：识别用户程序开发语言 --- ### 步骤2：根据用户开发语言选择连接方式 #### 官方使用文档地址 **基于 SQL 的应用开发：** https://help.aliyun.com/zh/lindorm/user-guide/add-connect-wide-table-engines-through-lindorm-query-language/ **使用 MySQL 协议的应用开发(推荐)** 1. **Java** - JDBC接口：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-java-jdbc-interface - 连接池Druid：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-java-connection-pool-druid - LindormDataSource：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-lindormdatasource - ORM框架MyBatis：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-java-orm-framework-mybatis 2. **Python** - 原生Python：https://help.aliyun.com/zh/lindorm/user-guide/python-based-application-development-1 - ORM框架：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-python-orm-framework 3. **Go** - 原生Go：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-go - ORM框架：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-go-orm-framework 4. **C** - C API：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-c-api 5. **C#** - 原生C#：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-c 6. **Rust** - 原生Rust：https://help.aliyun.com/zh/lindorm/user-guide/rust-based-application-development 7. **PHP** - 原生PHP：https://help.aliyun.com/zh/lindorm/user-guide/php-based-application-development 8. **Node.js** - 原生Node.js：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-node-js 9. **ODBC** - ODBC接口：https://help.aliyun.com/zh/lindorm/user-guide/application-development-based-on-odbc **Avatica协议**（仅存量维护） 1. **Java** - JDBC接口：https://help.aliyun.com/zh/lindorm/user-guide/call-java-api-operations-in-sql-based-connection-to-and-usage-of-lindormtable - 连接池Druid：https://help.aliyun.com/zh/lindorm/user-guide/through-the-connection-pool-druid-connection-wide-table-engine 2. **Python** - DB-API：https://help.aliyun.com/zh/lindorm/user-guide/use-the-lindorm-sql-api-for-a-non-java-language-to-connect-to-and-use-the-wide-table-engine-lindormtable - 连接池DBUtils：https://help.aliyun.com/zh/lindorm/user-guide/use-dbutils-to-connect-to-lindormtable 3. **Go** - database/sql接口：https://help.aliyun.com/zh/lindorm/user-guide/use-the-apis-provided-by-the-database-or-sql-library-of-go-to-develop-applications --- ### 步骤3：提供连接示例 --- ## 常见连接示例 ### MySQL 协议（推荐）所有示例使用 `<您的连接地址>` 占位符，Agent 根据实例 ServiceType 自动填充正确的 V1/V2 域名。 #### Java ##### 1. JDBC 接口 **依赖**: ```xml com.mysql mysql-connector-j 8.3.0 ``` **连接代码**: ```java Class.forName("com.mysql.cj.jdbc.Driver"); String username = "root"; String password = "your_password"; String database = "default"; String url = "jdbc:mysql://<您的连接地址>:33060/" + database + "?sslMode=disabled&allowPublicKeyRetrieval=true&useServerPrepStmts=true" + "&useLocalSessionState=true&rewriteBatchedStatements=true&cachePrepStmts=true" + "&prepStmtCacheSize=100&prepStmtCacheSqlLimit=50000000"; Properties properties = new Properties(); properties.put("user", username); properties.put("password", password); Connection connection = DriverManager.getConnection(url, properties); ``` **CRUD 示例**: ```java // 创建表 try (Statement stmt = connection.createStatement()) { stmt.executeUpdate("CREATE TABLE IF NOT EXISTS user_test(id VARCHAR, name VARCHAR, PRIMARY KEY(id))"); } // 批量插入 (推荐使用 INSERT，语义与 UPSERT 相同) String sql = "INSERT INTO user_test(id, name) VALUES(?, ?)"; try (PreparedStatement ps = connection.prepareStatement(sql)) { for (int i = 0; i < 100; i++) { ps.setString(1, "id" + i); ps.setString(2, "name" + i); ps.addBatch(); } ps.executeBatch(); // batchSize 建议 50-100 } // 查询 try (PreparedStatement ps = connection.prepareStatement("SELECT * FROM user_test WHERE id = ?")) { ps.setString(1, "id1"); ResultSet rs = ps.executeQuery(); while (rs.next()) { System.out.println("id=" + rs.getString(1) + ", name=" + rs.getString(2)); } } // 关闭连接 connection.close(); ``` ##### 2. Druid 连接池 **依赖**: ```xml com.alibaba druid 1.2.11 com.mysql mysql-connector-j 8.3.0 ``` **配置文件** (`druid.properties`): ```properties driverClassName=com.mysql.cj.jdbc.Driver url=jdbc:mysql://<您的连接地址>:33060/default?sslMode=disabled&allowPublicKeyRetrieval=true&useServerPrepStmts=true&useLocalSessionState=true&rewriteBatchedStatements=true&cachePrepStmts=true&prepStmtCacheSize=100&prepStmtCacheSqlLimit=50000000&socketTimeout=120000 username=root password=your_password init=true initialSize=10 maxActive=40 minIdle=40 maxWait=30000 # 避免连接负载不均衡 druid.phyMaxUseCount=10000 phyTimeoutMillis=1800000 # 连接保活 druid.keepAlive=true druid.keepAliveBetweenTimeMillis=120000 timeBetweenEvictionRunsMillis=60000 minEvictableIdleTimeMillis=300000 maxEvictableIdleTimeMillis=600000 testWhileIdle=true testOnBorrow=false testOnReturn=false ``` **初始化连接池**: ```java Properties properties = new Properties(); InputStream inputStream = getClass().getClassLoader().getResourceAsStream("druid.properties"); properties.load(inputStream); DataSource dataSource = DruidDataSourceFactory.createDataSource(properties); // 使用连接 try (Connection conn = dataSource.getConnection()) { // 执行 SQL... } ``` ##### 3. LindormDataSource（官方推荐）封装了开箱即用的最佳配置，支持多可用区就近访问。 **依赖**: ```xml com.mysql mysql-connector-j 8.3.0 com.aliyun.lindorm lindorm-sql-datasource 2.2.1.4 ``` **使用方式**: ```java LindormDataSourceConfig config = new LindormDataSourceConfig(); config.setJdbcUrl("jdbc:mysql://<您的连接地址>:33060/default"); config.setUsername("root"); config.setPassword("your_password"); config.setMaximumPoolSize(30); LindormDataSource dataSource = new LindormDataSource(config); try (Connection conn = dataSource.getConnection()) { // 执行 SQL... } ``` **Spring Boot 2.x 集成**: ```xml com.aliyun.lindorm lindorm-sql-datasource-springboot-starter 2.2.1.4 ``` ```yaml # application.yml spring: datasource: lindorm: jdbc-url: jdbc:mysql://<您的连接地址>:33060/default username: root password: your_password maximum-pool-size: 30 ``` ##### 4. MyBatis 框架 **依赖**: ```xml org.mybatis mybatis 3.5.14 com.mysql mysql-connector-j 8.3.0 ``` **配置文件** (`mybatis-config.xml`): ```xml ``` **Mapper 示例**: ```java public interface UserMapper { @Update("CREATE TABLE IF NOT EXISTS demo_user(id INT, name VARCHAR, PRIMARY KEY(id))") void createUserTable(); @Insert("UPSERT INTO demo_user(id, name) VALUES(#{userId}, #{userName})") int upsertUser(User user); @Select("SELECT * FROM demo_user WHERE id = #{userId}") User selectOneUser(@Param("userId") int userId); @Delete("DELETE FROM demo_user WHERE id = #{userId}") int deleteUser(@Param("userId") int userId); } ``` --- #### Python ##### 1. mysql-connector-python **安装**: `pip install mysql-connector-python==8.0.15` **直连模式**: ```python import mysql.connector connection = mysql.connector.connect( host='<您的连接地址>', port=33060, user='root', passwd='your_password', database='default' ) cursor = connection.cursor(prepared=True) # 创建表 cursor.execute("CREATE TABLE IF NOT EXISTS test_python(c1 INTEGER, c2 INTEGER, c3 VARCHAR, PRIMARY KEY(c1))") # 插入数据 (参数化防止 SQL 注入) cursor.execute("UPSERT INTO test_python(c1, c2, c3) VALUES(?, ?, ?)", (1, 1, 'value1')) # 查询 cursor.execute("SELECT * FROM test_python WHERE c1 = ?", (1,)) print(cursor.fetchall()) cursor.close() connection.close() ``` **连接池模式**: ```python from mysql.connector import pooling connection_pool = pooling.MySQLConnectionPool( pool_name="mypool", pool_size=20, host='<您的连接地址>', port=33060, user='root', password='your_password', database='default' ) connection = connection_pool.get_connection() cursor = connection.cursor(prepared=True) # ... 执行 SQL cursor.close() connection.close() # 返回到连接池 ``` ##### 2. SQLAlchemy ORM **安装**: ```bash pip install PyMySQL pip install SQLAlchemy ``` **示例**: ```python from sqlalchemy import create_engine, Column, String, Integer, Float from sqlalchemy.orm import declarative_base, sessionmaker Base = declarative_base() class Player(Base): __tablename__ = 'player' player_id = Column(Integer, primary_key=True, autoincrement=False) player_name = Column(String(255)) player_height = Column(Float) engine = create_engine('mysql+pymysql://root:your_password@<您的连接地址>:33060/default') Session = sessionmaker(bind=engine) # 建表 Base.metadata.create_all(engine) # 写入数据 session = Session() session.add(Player(player_id=1001, player_name="john", player_height=2.08)) session.commit() # 查询 rows = session.query(Player).filter(Player.player_id == 1001).all() print([str(row) for row in rows]) ``` --- #### Go ##### 1. database/sql + MySQL Driver **依赖** (`go.mod`): ```go require github.com/go-sql-driver/mysql v1.7.1 ``` **示例**: ```go package main import ( "database/sql" "fmt" "time" _ "github.com/go-sql-driver/mysql" ) func main() { url := "root:your_password@tcp(<您的连接地址>:33060)/default?timeout=10s" db, err := sql.Open("mysql", url) if err != nil { panic(err) } defer db.Close() // 连接池配置 db.SetMaxOpenConns(20) db.SetMaxIdleConns(20) db.SetConnMaxIdleTime(8 * time.Minute) db.SetConnMaxLifetime(30 * time.Minute) // 创建表 db.Exec("CREATE TABLE IF NOT EXISTS user_test(id INT, name VARCHAR, age INT, PRIMARY KEY(id))") // 插入 (参数绑定方式) stmt, _ := db.Prepare("UPSERT INTO user_test(id, name, age) VALUES(?, ?, ?)") stmt.Exec(1, "zhangsan", 17) // 查询 rows, _ := db.Query("SELECT * FROM user_test") defer rows.Close() for rows.Next() { var id, age int var name string rows.Scan(&id, &name, &age) fmt.Printf("id=%d, name=%s, age=%d\n", id, name, age) } } ``` ##### 2. GORM 框架 **依赖**: ```go require ( gorm.io/driver/mysql v1.5.1 gorm.io/gorm v1.25.4 ) ``` **示例**: ```go package main import ( "gorm.io/driver/mysql" "gorm.io/gorm" ) type Product struct { ID int64 `gorm:"primaryKey;autoIncrement:false"` Code string `gorm:"type:varchar"` Price float64 } func main() { dsn := "root:your_password@tcp(<您的连接地址>:33060)/default" db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{}) // 重要: Lindorm 不支持事务，必须关闭 session := db.Session(&gorm.Session{SkipDefaultTransaction: true}) // 建表 session.Migrator().CreateTable(&Product{}) // 写入 session.Create(&Product{ID: 1, Code: "D42", Price: 100.1}) // 查询 var product Product session.First(&product, 1) } ``` --- #### C/C++ **安装** (CentOS): `yum install mysql-devel` **示例**: ```c #include #include "mysql/mysql.h" int main() { MYSQL conn; mysql_init(&conn); if (!mysql_real_connect(&conn, "<您的连接地址>", "root", "your_password", "default", 33060, NULL, 0)) { printf("连接失败: %s\n", mysql_error(&conn)); return 1; } // 创建表 mysql_query(&conn, "CREATE TABLE IF NOT EXISTS user_test(id INT, name VARCHAR, PRIMARY KEY(id))"); // 插入数据 mysql_query(&conn, "UPSERT INTO user_test(id, name) VALUES(1, 'test')"); // 查询数据 mysql_query(&conn, "SELECT * FROM user_test"); MYSQL_RES *result = mysql_store_result(&conn); MYSQL_ROW row; while ((row = mysql_fetch_row(result))) { printf("id=%s, name=%s\n", row[0], row[1]); } mysql_close(&conn); return 0; } ``` **编译**: `gcc -o demo demo.c $(mysql_config --cflags) $(mysql_config --libs)` --- #### C# **安装**: `dotnet add package MySql.Data -v 8.0.11` **示例**: ```csharp using MySql.Data.MySqlClient; string connStr = "server=<您的连接地址>;UID=root;database=default;port=33060;password=your_password"; MySqlConnection conn = new MySqlConnection(connStr); conn.Open(); MySqlCommand cmd = new MySqlCommand("SHOW DATABASES", conn); MySqlDataReader rdr = cmd.ExecuteReader(); while (rdr.Read()) { Console.WriteLine(rdr[0]); } conn.Close(); ``` --- #### Rust **依赖** (`Cargo.toml`): ```toml [dependencies] mysql = "*" ``` **示例**: ```rust use mysql::*; use mysql::prelude::*; fn main() { let opts = OptsBuilder::new() .ip_or_hostname(Some("<您的连接地址>")) .user(Some("root")) .pass(Some("your_password")) .db_name(Some("default")) .tcp_port(33060); let pool = Pool::new(opts).unwrap(); let mut conn = pool.get_conn().unwrap(); // 创建表 conn.query_drop("CREATE TABLE IF NOT EXISTS user_test(id INT, name VARCHAR, PRIMARY KEY(id))").unwrap(); // 插入 conn.exec_drop("UPSERT INTO user_test(id, name) VALUES(?, ?)", (1, "test")).unwrap(); // 查询 let result: Vec<(i32, String)> = conn.query("SELECT * FROM user_test").unwrap(); for (id, name) in result { println!("id={}, name={}", id, name); } } ``` --- #### PHP **要求**: PHP 8.0+，安装 php-mysql 模块 **示例**: ```php "; $lindorm_username = "root"; $lindorm_password = "your_password"; $lindorm_database = "default"; $lindorm_port = 33060; $conn = mysqli_connect($lindorm_addr, $lindorm_username, $lindorm_password, $lindorm_database, $lindorm_port); // 创建表 mysqli_query($conn, "CREATE TABLE IF NOT EXISTS user_test(id INT, name VARCHAR, PRIMARY KEY(id))"); // 插入数据 mysqli_query($conn, "UPSERT INTO user_test(id, name) VALUES(1, 'test')"); // 查询数据 $result = mysqli_query($conn, "SELECT * FROM user_test"); while ($row = mysqli_fetch_array($result)) { printf("id=%d, name=%s\n", $row["id"], $row["name"]); } mysqli_close($conn); ?> ``` --- #### Node.js **安装**: `npm install mysql2` **示例**: ```javascript var mysql = require('mysql2'); var connection = mysql.createConnection({ host: '<您的连接地址>', port: 33060, user: 'root', password: 'your_password', database: 'default', connectTimeout: 10000 }); connection.connect(function(err) { if (err) throw err; console.log("Connected!"); // 查询 connection.query('SHOW DATABASES', function(err, results) { if (err) throw err; console.log(results); }); connection.end(); }); ``` --- #### ODBC **安装** (Linux): ```bash # 下载 MySQL ODBC 驱动: https://dev.mysql.com/downloads/connector/odbc/ yum install unixODBC-devel ``` **配置** (`/etc/odbcinst.ini`): ```ini [MySQL] Description = ODBC for MySQL Driver64 = /usr/lib64/libmyodbc8a.so Setup64 = /usr/lib64/libmyodbc8w.so FileUsage = 1 ``` **C 代码示例**: ```c #include #include int main() { SQLHENV env; SQLHDBC dbc; SQLRETURN ret; SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &env); SQLSetEnvAttr(env, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, SQL_IS_INTEGER); SQLAllocHandle(SQL_HANDLE_DBC, env, &dbc); ret = SQLDriverConnect(dbc, NULL, (SQLCHAR*)"DRIVER={MySQL};SERVER=<您的连接地址>;PORT=33060;DATABASE=default;USER=root;PASSWORD=your_password", SQL_NTS, NULL, 0, NULL, SQL_DRIVER_COMPLETE); if (ret == SQL_SUCCESS) { printf("连接成功\n"); // ... 执行 SQL } SQLFreeHandle(SQL_HANDLE_DBC, dbc); SQLFreeHandle(SQL_HANDLE_ENV, env); return 0; } ``` --- ### Avatica 协议（仅存量维护） > **注意**: Avatica 协议目前处于存量维护状态，**不推荐新用户使用**。 > > Avatica 域名格式略有不同： > - V2: `ld-xxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:30060` > - V1: `ld-xxx-proxy-lindorm.lindorm.rds.aliyuncs.com:30060` #### Java (Avatica) **依赖**: ```xml com.aliyun.lindorm lindorm-all-client 2.2.1.3 ``` **连接代码**: ```java String url = "jdbc:lindorm:table:url=http://<您的连接地址>:30060"; Properties properties = new Properties(); properties.put("user", "root"); properties.put("password", "your_password"); properties.put("database", "default"); Connection connection = DriverManager.getConnection(url, properties); ``` #### Python (Avatica - phoenixdb) **安装**: `pip install phoenixdb==1.2.0` ```python import phoenixdb connect_kw_args = { 'lindorm_user': 'root', 'lindorm_password': 'your_password', 'database': 'default' } database_url = 'http://<您的连接地址>:30060' connection = phoenixdb.connect(database_url, autocommit=True, **connect_kw_args) with connection.cursor() as cursor: cursor.execute("SELECT * FROM test_table") print(cursor.fetchall()) connection.close() ``` #### Go (Avatica) **依赖** (`go.mod`): ```go require github.com/apache/calcite-avatica-go/v5 v5.0.0 replace github.com/apache/calcite-avatica-go/v5 => github.com/aliyun/alibabacloud-lindorm-go-sql-driver/v5 v5.0.6 ``` --- ### 最佳实践 #### 连接参数建议 | 参数 | 建议值 | 说明 | |------|--------|------| | sslMode | disabled | 不使用 SSL，提升性能 | | useServerPrepStmts | true | 启用服务端预处理 | | rewriteBatchedStatements | true | 优化批量写入性能 | | cachePrepStmts | true | 缓存预处理语句 | | prepStmtCacheSize | 100 | 缓存数量 | #### 写入性能优化 1. **使用 Batch 写入**: batchSize 建议 50-100 2. **使用 INSERT 而非 UPSERT**: MySQL 协议下 INSERT 语义与 UPSERT 相同，但有客户端优化 3. **增加并发**: 通过多线程/协程增加写入吞吐 #### 连接池配置 1. 连接保持时间不宜过长，建议配置 `phyMaxUseCount` 和 `phyTimeoutMillis` 2. 执行完查询后及时调用 `close()` 归还连接 3. 建议启用连接保活检测 #### 注意事项 - **Lindorm 不支持事务**: 使用 GORM 等 ORM 框架时需关闭事务 - **UPDATE 仅支持单行**: WHERE 条件必须指定全部主键 - **连接空闲超时**: 服务端会主动断开空闲 10 分钟的连接 FILE:references/01-dev/sql-operations.md # Lindorm SQL 语法参考以下收录了常用的 DDL 和 DML 语句。 ## 重要约束 > **此约束具有最高优先级，必须严格遵守。** 1. **禁止推测和联想**：只能基于本 Skill 文档中明确记载的内容回答用户问题，严禁推测、联想或生成文档中不存在的 SQL 语法、参数、功能或配置。 2. **不确定时必须声明**：如果文档中没有相关信息，必须明确告知用户“当前文档未收录此内容”，并引导用户查阅官方文档。 3. **禁止混淆来源**：不得将其他数据库（如 MySQL、HBase、PostgreSQL）的语法或特性当作 Lindorm 的功能来回答。 4. **代码示例需要出处**：生成的代码示例必须基于文档中的模板，参数和语法必须与文档一致。 ## 执行步骤 1. 当用户提到的 SQL 语句已收录在下方文档中时，优先使用收录的信息回复用户。 2. 如果用户提到的 SQL 语句未收录在下方文档中时，查询官方文档回复用户。 - **DDL**: https://help.aliyun.com/zh/lindorm/developer-reference/wide-table-ddl/ - **DML**: https://help.aliyun.com/zh/lindorm/developer-reference/wide-table-dml/ - **DCL**：https://help.aliyun.com/zh/lindorm/developer-reference/wide-table-dcl/ 3. 如果用户提到的 SQL 语句既未收录在下方文档中，也未找到官方文档中的相关信息时，必须明确告知用户“当前文档未收录此内容”。 ## DDL 语句 > 详细建表语法、数据类型、表属性请参考 table-design.md ### CREATE TABLE - 创建表 **基本语法**: ```sql CREATE TABLE [IF NOT EXISTS] table_name ( column_name data_type [NOT NULL], ... PRIMARY KEY (column_name [, column_name]...) ) [WITH (option = value, ...)] ``` **示例 - 基础建表**: ```sql CREATE TABLE IF NOT EXISTS user_profile ( user_id VARCHAR NOT NULL, nickname VARCHAR, age INTEGER, balance DOUBLE, created_at TIMESTAMP, PRIMARY KEY (user_id) ); ``` **示例 - 复合主键**: ```sql CREATE TABLE IF NOT EXISTS order_detail ( order_id VARCHAR NOT NULL, item_seq INTEGER NOT NULL, product_name VARCHAR, quantity INTEGER, price DOUBLE, PRIMARY KEY (order_id, item_seq) ); ``` **示例 - 带表属性**: ```sql CREATE TABLE IF NOT EXISTS logs ( log_id VARCHAR NOT NULL, level VARCHAR, message VARCHAR, created_at TIMESTAMP, PRIMARY KEY (log_id) ) WITH ( TTL = '604800', -- 7天过期 COMPRESSION = 'ZSTD', -- ZSTD压缩 NUMREGIONS = 10 -- 预分10个Region ); ``` **示例 - 预分区建表**: ```sql CREATE TABLE IF NOT EXISTS metrics ( metric_id VARCHAR NOT NULL, value DOUBLE, ts TIMESTAMP, PRIMARY KEY (metric_id) ) WITH ( NUMREGIONS = 8, STARTKEY = '0', ENDKEY = '9' ); ``` **示例 - 指定分区键**: ```sql CREATE TABLE IF NOT EXISTS events ( event_id VARCHAR NOT NULL, event_type VARCHAR, payload VARCHAR, PRIMARY KEY (event_id) ) WITH ( SPLITKEYS = 'a,b,c,d,e,f,g,h,i' ); ``` ### 常用表属性 | 属性 | 类型 | 说明 | 示例 | |------|------|------|------| | TTL | INT | 数据有效期(秒) | TTL = '86400' (1天) | | COMPRESSION | STRING | 压缩算法: SNAPPY/ZSTD/LZ4 | COMPRESSION = 'ZSTD' | | NUMREGIONS | INT | 预分区数量 | NUMREGIONS = 16 | | STARTKEY | STRING | 分区起始Key | STARTKEY = '0' | | ENDKEY | STRING | 分区结束Key | ENDKEY = 'z' | | SPLITKEYS | STRING | 自定义分区点 | SPLITKEYS = 'a,m,z' | | MUTABILITY | STRING | 索引写入模式 | MUTABILITY = 'MUTABLE_LATEST' | | CONSISTENCY | STRING | 一致性级别 | CONSISTENCY = 'strong' | ### ALTER TABLE - 修改表 **添加列**: ```sql ALTER TABLE user_profile ADD COLUMN email VARCHAR; ALTER TABLE user_profile ADD COLUMN phone VARCHAR, address VARCHAR; ``` **修改 TTL**: ```sql ALTER TABLE logs SET TTL = '2592000'; -- 改为30天 ALTER TABLE logs SET TTL = ''; -- 取消TTL，数据不过期 ``` ### DROP TABLE - 删除表 ```sql DROP TABLE IF EXISTS table_name; ``` ### TRUNCATE TABLE - 清空表 ```sql TRUNCATE TABLE table_name; ``` ### CREATE INDEX - 创建索引 **二级索引**: ```sql -- 在建表时创建 CREATE TABLE orders ( order_id VARCHAR NOT NULL, user_id VARCHAR, status VARCHAR, amount DOUBLE, PRIMARY KEY (order_id), INDEX idx_user USING KV (user_id), INDEX idx_status USING KV (status) INCLUDE (amount) ); -- 单独创建二级索引 CREATE INDEX idx_user USING KV ON orders (user_id); ``` **搜索索引**: > ⚠️ **重要**：搜索索引需先在控制台开通（宽表引擎 → 搜索索引 → 立即开通），否则创建会报 `SERVER INTERNAL ERROR`。详见 [table-design.md](table-design.md#搜索索引开通条件)。 ```sql -- 基础搜索索引 CREATE INDEX idx_search USING SEARCH ON orders (status); -- 带分词器的搜索索引 CREATE INDEX idx_text USING SEARCH ON articles ( title(type=text, analyzer=ik), content(type=text, analyzer=ik) ); -- 分词查询 SELECT * FROM articles WHERE MATCH(content) AGAINST('关键词'); ``` ### SHOW / DESCRIBE - 查看信息 ```sql -- 查看所有表 SHOW TABLES; -- 查看表结构 DESCRIBE table_name; -- 查看建表语句 SHOW CREATE TABLE table_name; -- 查看索引 SHOW INDEX FROM table_name; ``` --- ## DML 语句 ### UPSERT - 插入/更新数据 UPSERT 是 Lindorm 推荐的写入方式，如果主键存在则更新，不存在则插入。 **单条写入**: ```sql UPSERT INTO user_profile (user_id, nickname, age) VALUES ('u001', '张三', 25); ``` **带时间戳写入** (使用 HINT): ```sql -- 指定写入数据的时间戳（毫秒） UPSERT /*+ _l_ts_(1704067200000) */ INTO user_profile (user_id, nickname, age) VALUES ('u001', '张三', 25); ``` **批量写入** (PreparedStatement): ```java String sql = "UPSERT INTO user_profile (user_id, nickname, age) VALUES (?, ?, ?)"; PreparedStatement ps = conn.prepareStatement(sql); for (int i = 0; i < 100; i++) { ps.setString(1, "u" + i); ps.setString(2, "user_" + i); ps.setInt(3, 20 + i % 50); ps.addBatch(); } ps.executeBatch(); ``` ### SELECT - 查询数据 **基本查询**: ```sql SELECT * FROM user_profile WHERE user_id = 'u001'; ``` **指定列查询** (推荐): ```sql SELECT user_id, nickname, age FROM user_profile WHERE user_id = 'u001'; ``` **范围查询**: ```sql SELECT * FROM user_profile WHERE user_id >= 'u001' AND user_id < 'u100'; ``` **排序与分页**: ```sql SELECT * FROM user_profile ORDER BY user_id LIMIT 100 OFFSET 0; ``` **条件查询**: ```sql SELECT * FROM user_profile WHERE age > 25 AND age < 35; SELECT * FROM user_profile WHERE nickname LIKE '张%'; SELECT * FROM user_profile WHERE user_id IN ('u001', 'u002', 'u003'); ``` **聚合查询**: ```sql SELECT COUNT(*) FROM user_profile; SELECT MAX(age), MIN(age), AVG(age) FROM user_profile; ``` **HINT 使用**: ```sql -- 强制允许低效查询（全表扫描） SELECT /*+ _l_allow_filtering_ */ * FROM user_profile; -- 指定操作超时时间（毫秒） SELECT /*+ _l_operation_timeout_(30000) */ * FROM user_profile WHERE age > 25; -- 强制使用索引 SELECT /*+ _l_force_index_('idx_name') */ * FROM user_profile WHERE name = 'test'; -- 忽略索引 SELECT /*+ _l_ignore_index_ */ * FROM user_profile WHERE name = 'test'; ``` ### UPDATE - 更新数据 **重要**: UPDATE 必须指定完整的主键条件。 ```sql -- 正确: 指定完整主键 UPDATE user_profile SET age = 26 WHERE user_id = 'u001'; -- 错误: 不支持批量更新 UPDATE user_profile SET age = 26 WHERE age > 25; -- 会报错 ``` ### DELETE - 删除数据 **单行删除**: ```sql DELETE FROM user_profile WHERE user_id = 'u001'; ``` **复合主键删除**: ```sql DELETE FROM order_detail WHERE order_id = 'o001' AND item_seq = 1; ``` ### JSON 数据写入与查询 > 数据类型定义请参考 [table-design.md](table-design.md) **写入方式**: ```sql -- 方式 1: 直接写入 JSON 字符串 UPSERT INTO tb(p1, c2) VALUES(1, '{"k1": 4, "k2": {"k3": {"k4": 4}}}'); -- 方式 2: 使用 json_object 函数 UPSERT INTO tb(p1, c2) VALUES(2, json_object('k1', 2, 'k2', '2')); -- 等价于：UPSERT INTO tb(p1,c2) VALUES(2,'{"k1":2,"k2":"2"}'); -- 方式 3: 使用 json_array 函数 UPSERT INTO tb(p1, c2) VALUES(3, json_array(1, 2, json_object('k1', 3, 'k2', '3'))); -- 等价于：UPSERT INTO tb(p1,c2) VALUES(3,'[1,2,{"k1":3,"k2":"3"}]'); ``` **查询 JSON 字段**: ```sql -- 获取 JSON 对象中的值 (SELECT 子句) SELECT p1, json_extract(c2, '$.k1') AS k1_value FROM tb WHERE p1 = 1; -- 嵌套路径查询 SELECT json_extract(c2, '$.k2.k3.k4') FROM tb WHERE p1 = 4; -- 数组索引访问 SELECT json_extract(c2, '$[2].k2') FROM tb WHERE p1 = 3; -- WHERE 条件过滤 SELECT * FROM tb WHERE p1 >= 1 AND p1 < 4 AND json_extract(c2, '$.k2') > '0'; ``` --- ## 常用函数 ### 字符串函数 > 要求宽表引擎 2.5.1.1+ | 函数 | 说明 | 示例 | |------|------|------| | `CONCAT(s1, s2, ...)` | 拼接多个字符串 | `SELECT CONCAT('a','b','c')` → `abc` | | `LENGTH(s)` | 计算字符串长度 | `SELECT LENGTH('hello')` → `5` | | `LOWER(s)` | 转为小写 | `SELECT LOWER('ABC')` → `abc` | | `UPPER(s)` | 转为大写 | `SELECT UPPER('abc')` → `ABC` | | `TRIM(s)` | 删除前后空格 | `SELECT TRIM(' ab ')` → `ab` | | `SUBSTR(s, pos[, len])` | 截取子串 | `SELECT SUBSTR('hello', 2, 3)` → `ell` | | `REPLACE(s, from, to)` | 替换子串 | `SELECT REPLACE('abc', 'b', 'x')` → `axc` | | `REVERSE(s)` | 返回逆序字符串 | `SELECT REVERSE('abc')` → `cba` | | `MD5(s)` | 计算 MD5 哈希 | `SELECT MD5('abc')` → `900150983cd24fb0...` | | `SHA256(s)` | 计算 SHA256 哈希 | `SELECT SHA256('abc')` → `ba7816bf8f01cfea...` | | `START_WITH(s, prefix)` | 判断前缀 | `SELECT START_WITH('hello', 'he')` → `true` | **正则表达式函数**: ```sql -- REGEXP_REPLACE: 正则替换，支持指定开始位置 SELECT REGEXP_REPLACE('abcbc', 'b', 'x', 2); -- axcxc -- REGEXP_SUBSTR: 正则提取子串 SELECT REGEXP_SUBSTR('abc123def', '[0-9]+'); -- 123 -- MATCH: 判断是否匹配正则 SELECT * FROM table WHERE MATCH(column, 'pattern'); ``` ### 聚合函数 | 函数 | 说明 | 示例 | |------|------|------| | `COUNT(*)` | 统计行数 | `SELECT COUNT(*) FROM table` | | `COUNT(column)` | 统计非 NULL 值个数 | `SELECT COUNT(name) FROM table` | | `SUM(column)` | 求和（仅数值类型） | `SELECT SUM(amount) FROM orders` | | `AVG(column)` | 平均值（仅数值类型） | `SELECT AVG(price) FROM products` | | `MAX(column)` | 最大值 | `SELECT MAX(score) FROM results` | | `MIN(column)` | 最小值 | `SELECT MIN(score) FROM results` | **高级聚合函数** (宽表引擎 2.7.9+): ```sql -- HEAD: 返回第一个非 NULL 值，支持排序 SELECT HEAD(temperature ORDER BY time) FROM sensor; -- 最早的温度 SELECT HEAD(temperature ORDER BY time DESC) FROM sensor; -- 最新的温度 -- GROUP_CONCAT: 分组拼接字符串 SELECT region, GROUP_CONCAT(device_id) FROM sensor GROUP BY region; -- 结果: north-cn | dev1,dev2,dev3 -- GROUP_CONCAT 带排序和分隔符 SELECT region, GROUP_CONCAT(device_id ORDER BY time SEPARATOR '|') FROM sensor GROUP BY region; -- 结果: north-cn | dev1|dev2|dev3 -- GROUP_CONCAT 去重 SELECT region, GROUP_CONCAT(DISTINCT device_id) FROM sensor GROUP BY region; ``` ### 时间函数 > 要求宽表引擎 2.7.8+，Lindorm SQL 2.8.7.0+ | 函数 | 说明 | 示例 | |------|------|------| | `DATE_FORMAT(ts, format)` | 格式化时间戳 | 见下方示例 | | `FROM_UNIXTIME(seconds)` | Unix 时间戳转 TIMESTAMP | `SELECT FROM_UNIXTIME(1704067200)` | | `UNIX_TIMESTAMP(ts)` | TIMESTAMP 转 Unix 时间戳 | `SELECT UNIX_TIMESTAMP('2024-01-01 00:00:00')` | | `DATEDIFF(ts1, ts2)` | 计算日期差(天) | `SELECT DATEDIFF('2024-01-05', '2024-01-01')` → `4` | **DATE_FORMAT 格式说明符**: ```sql SELECT DATE_FORMAT('2024-01-15 17:30:45', '%Y-%m-%d %H:%i:%s'); -- 2024-01-15 17:30:45 SELECT DATE_FORMAT('2024-01-15 17:30:45', '%Y年%m月%d日 %H:%i'); -- 2024年01月15日 17:30 SELECT DATE_FORMAT('2024-01-15 17:30:45', 'at %T on %b %D, %Y'); -- at 17:30:45 on JAN 15th, 2024 ``` | 格式符 | 说明 | 示例 | |--------|------|------| | `%Y` | 四位年份 | 2024 | | `%y` | 两位年份 | 24 | | `%m` | 两位月份 | 01-12 | | `%d` | 两位日期 | 01-31 | | `%H` | 24小时制小时 | 00-23 | | `%h` | 12小时制小时 | 01-12 | | `%i` | 分钟 | 00-59 | | `%s` / `%S` | 秒 | 00-59 | | `%T` | 时间 (HH:mm:ss) | 17:30:45 | | `%D` | 带序数的日期 | 1st, 2nd, 15th | | `%b` | 月份缩写 | Jan, Feb | | `%M` | 月份全称 | January | | `%W` | 星期全称 | Monday | | `%a` | 星期缩写 | Mon | | `%p` | AM/PM | AM | **FROM_UNIXTIME 示例**: ```sql -- Unix 时间戳转 TIMESTAMP SELECT FROM_UNIXTIME(1704067200); -- 2024-01-01 08:00:00 (+08:00时区) -- 支持毫秒精度（使用小数） SELECT FROM_UNIXTIME(1704067200.123); -- 2024-01-01 08:00:00.123 -- 同时格式化输出 SELECT FROM_UNIXTIME(1704067200, '%Y-%m-%d'); -- 2024-01-01 ``` **常用 JSON 函数**: **构造函数**: - `json_object(key1, value1, ...)`: 构建 JSON 对象 ```sql SELECT json_object('name', 'Alice', 'age', 25); -- {"name": "Alice", "age": 25} ``` - `json_array(value1, value2, ...)`: 构建 JSON 数组 ```sql SELECT json_array('Java', 'Python', 'Go'); -- ["Java", "Python", "Go"] ``` **提取函数**: - `json_extract(json_doc, path)`: 提取 JSON 值（返回 JSON 类型） ```sql SELECT json_extract('{"name": "Alice"}', '$.name'); -- "Alice" ``` - `json_extract_string(json_doc, path)`: 提取并转换为 VARCHAR 类型 ```sql SELECT json_extract_string('{"name": "Alice"}', '$.name'); -- Alice (VARCHAR) ``` - `json_extract_long(json_doc, path)`: 提取并转换为 BIGINT 类型 ```sql SELECT json_extract_long('{"id": 123456}', '$.id'); -- 123456 (BIGINT) ``` - `json_extract_double(json_doc, path)`: 提取并转换为 DOUBLE 类型 ```sql SELECT json_extract_double('{"score": 95.5}', '$.score'); -- 95.5 (DOUBLE) ``` **路径语法**: - `$.key`: 访问对象的 key - `$[index]`: 访问数组的索引（从 0 开始） - `$.key1.key2`: 嵌套访问 - `$[*]`: 通配符匹配所有数组元素 **包含检查函数**: - `json_contains(target, candidate[, path])`: 检查是否包含指定值 ```sql -- 检查数组是否包含某个元素 SELECT json_contains('["Java", "Python"]', '"Java"'); -- 1 (true) -- 检查对象是否包含某个属性 SELECT json_contains('{"a": 1, "b": 2}', '{"a": 1}'); -- 1 (true) -- 检查指定路径 SELECT json_contains('{"skills": ["Java", "Python"]}', '"Java"', '$.skills'); -- 1 (true) -- WHERE 条件中使用 SELECT * FROM table WHERE json_contains(data, '"active"', '$.status'); ``` **更新函数**: - `json_set(json_doc, path, value[, path, value]...)`: 插入或更新值 ```sql SELECT json_set('{"a": 1}', '$.b', 2); -- {"a": 1, "b": 2} ``` - `json_insert(json_doc, path, value)`: 仅在路径不存在时插入 ```sql SELECT json_insert('{"a": 1}', '$.b', 2); -- {"a": 1, "b": 2} ``` - `json_replace(json_doc, path, value)`: 仅在路径存在时更新 ```sql SELECT json_replace('{"a": 1}', '$.a', 10); -- {"a": 10} ``` - `json_remove(json_doc, path[, path]...)`: 删除指定路径的值 ```sql SELECT json_remove('{"a": 1, "b": 2}', '$.b'); -- {"a": 1} ``` **注意事项**: - 如果在 JSON 列中写入非 JSON 对象或字符串，会报错 - 不同数据类型比较规则与 MySQL 相同 --- ## 特殊语法 ### HINT 语法详解 HINT 是 SQL 的补充语法，可以改变 SQL 的执行方式。HINT 必须紧跟在 `INSERT`、`UPSERT`、`DELETE`、`SELECT` 关键字之后。 > 要求宽表引擎 2.3.1+ **基本语法**: ```sql /*+ hint1, hint2, ... */ ``` #### HINT 参数列表 | HINT | 类型 | 说明 | 支持语句 | |------|------|------|----------| | `_l_operation_timeout_(N)` | INT | DML 操作超时时间，单位毫秒，默认 120000 | UPSERT, DELETE, UPDATE, SELECT | | `_l_allow_filtering_` | - | 允许低效全表扫描查询 | SELECT | | `_l_force_index_('idx')` | STRING | 强制使用指定索引 | SELECT | | `_l_ignore_index_` | - | 忽略索引，直接查表 | SELECT | | `_l_ts_(N)` | BIGINT | 指定写入/查询的时间戳（毫秒） | UPSERT, SELECT | | `_l_versions_(N)` | INT | 返回最新 N 个版本的数据 | SELECT | | `_l_ts_min_(N)` | BIGINT | 过滤结果，返回时间戳 >= N 的数据 | SELECT | | `_l_ts_max_(N)` | BIGINT | 过滤结果，返回时间戳 < N 的数据 | SELECT | | `_l_hot_only_` / `_l_hot_only_(true)` | BOOLEAN | 仅查询热存储数据 | SELECT | #### 超时与性能控制 ```sql -- 设置操作超时时间 30 秒 SELECT /*+ _l_operation_timeout_(30000) */ COUNT(*) FROM big_table; -- 允许全表扫描（当 WHERE 条件不包含主键时） SELECT /*+ _l_allow_filtering_ */ * FROM users WHERE age > 30; -- 组合使用 SELECT /*+ _l_operation_timeout_(30000), _l_allow_filtering_ */ * FROM users WHERE age > 30; ``` #### 索引控制 ```sql -- 强制使用指定索引 SELECT /*+ _l_force_index_('idx_user_name') */ * FROM users WHERE name = 'test'; -- 忽略索引，直接查主表（用于性能对比） SELECT /*+ _l_ignore_index_ */ * FROM users WHERE name = 'test'; ``` **注意**: `_l_force_index_` 和 `_l_ignore_index_` 不能同时使用 #### 多版本数据管理 Lindorm 支持每列存储多个版本的数据，通过时间戳标识版本（时间戳越大版本越新）。 **创建多版本表**: ```sql -- VERSIONS='5' 表示每列最多保留 5 个版本 CREATE TABLE sensor_data ( device_id VARCHAR, temperature DOUBLE, PRIMARY KEY(device_id) ) WITH (VERSIONS='5'); -- 修改已有表的版本数 ALTER TABLE sensor_data SET 'VERSIONS' = '10'; ``` **写入指定时间戳**: ```sql -- 指定时间戳写入（毫秒） UPSERT /*+ _l_ts_(1704067200000) */ INTO sensor_data(device_id, temperature) VALUES ('dev001', 25.5); UPSERT /*+ _l_ts_(1704067260000) */ INTO sensor_data(device_id, temperature) VALUES ('dev001', 26.0); -- 同一设备，新版本 ``` **查询多版本数据**: ```sql -- 查询指定时间戳的数据 SELECT /*+ _l_ts_(1704067200000) */ device_id, temperature FROM sensor_data WHERE device_id = 'dev001'; -- 查询最新 N 个版本 SELECT /*+ _l_versions_(3) */ device_id, temperature, temperature_l_ts FROM sensor_data WHERE device_id = 'dev001'; -- 查询时间戳范围 [min, max) SELECT /*+ _l_ts_min_(1704067200000), _l_ts_max_(1704153600000) */ device_id, temperature, temperature_l_ts FROM sensor_data WHERE device_id = 'dev001'; ``` **查看列的时间戳**: 在列名后加 `_l_ts` 后缀 ```sql -- temperature_l_ts 返回 temperature 列的时间戳 SELECT /*+ _l_versions_(2) */ device_id, temperature, temperature_l_ts FROM sensor_data; ``` #### 热数据查询当开通冷存储功能后，可使用 HINT 仅查询热存储中的数据： ```sql -- 仅查询热数据 SELECT /*+ _l_hot_only_ */ * FROM sensor_data WHERE device_id = 'dev001'; SELECT /*+ _l_hot_only_(true) */ * FROM sensor_data WHERE device_id = 'dev001'; -- 查询所有数据（包括冷数据），与不使用 HINT 等价 SELECT /*+ _l_hot_only_(false) */ * FROM sensor_data WHERE device_id = 'dev001'; ``` **注意**: 不支持单独查询冷数据 ### 动态列 Lindorm 支持动态列，无需预定义即可写入新列。 ```sql -- 写入动态列 UPSERT INTO user_profile (user_id, _dyn_col_name1) VALUES ('u001', 'value1'); -- 查询动态列 SELECT user_id, _dyn_col_name1 FROM user_profile WHERE user_id = 'u001'; ``` ### TTL 相关 ```sql -- 查看表的 TTL 设置 SHOW CREATE TABLE table_name; -- 修改 TTL ALTER TABLE table_name SET TTL = '86400'; -- 取消 TTL（数据永不过期） ALTER TABLE table_name SET TTL = ''; ``` **注意**: Lindorm 不支持行级 TTL，TTL 是表级别的属性。 --- ## SQL 注意事项 ### 与 MySQL 的差异 | 特性 | MySQL | Lindorm SQL | |------|-------|-------------| | 写入语句 | INSERT/UPDATE | UPSERT (推荐) | | UPDATE 范围 | 支持批量 | 仅单行 | | 自增主键 | 支持 | 不支持 | | 外键 | 支持 | 不支持 | | 事务 | ACID | 单行原子性 | | JOIN | 支持 | 不支持 | ### 性能建议 1. **主键查询最快**: 尽量使用主键作为查询条件 2. **避免全表扫描**: 无索引列 WHERE 会被低效查询拦截，需创建索引或用 `/*+ _l_allow_filtering_ */` 3. **限制返回行数**: 使用 LIMIT 避免大量数据返回 4. **使用 PreparedStatement**: 批量操作必用 5. **选择性 SELECT**: 只查询需要的列 6. **子查询用派生表**: WHERE IN/EXISTS 子查询需确保子查询中的过滤列有索引 7. **后缀模糊用搜索索引**: LIKE 前缀 `xxx%` 用二级索引即可，后缀模糊 `%xxx` 需搜索索引（SEARCH） ### 窗口函数 ⚠️ **有限支持**：官方兼容性文档标注窗口函数为"暂不支持"，语法不报错但可能存在**正确性或稳定性风险**（服务端计算开销较大）。实测 ROW_NUMBER/RANK/DENSE_RANK/LEAD/SUM OVER/AVG OVER 在当前版本可正常执行，LAG 在低版本存在解析器 bug。生产环境**谨慎使用**，建议优先用计算引擎（OLAP）处理窗口计算。 ```sql -- ROW_NUMBER: 按分组编号 SELECT id, user_name, amount, ROW_NUMBER() OVER (PARTITION BY user_name ORDER BY amount DESC) AS rn FROM orders; -- RANK: 排名 SELECT id, user_name, amount, RANK() OVER (ORDER BY amount DESC) AS rnk FROM orders; -- SUM OVER: 分组累计求和 SELECT id, user_name, amount, SUM(amount) OVER (PARTITION BY user_name) AS user_total FROM orders; -- LEAD/LAG: 前后行引用 SELECT id, amount, LAG(amount) OVER (ORDER BY id) AS prev_amt, LEAD(amount) OVER (ORDER BY id) AS next_amt FROM orders; ``` ### 子查询 Lindorm SQL 支持派生表（FROM 子句中的子查询），WHERE IN/EXISTS 子查询需索引支持： ```sql -- 派生表（推荐，无索引也可用） SELECT * FROM ( SELECT user_name, SUM(amount) AS total FROM orders GROUP BY user_name ) AS t WHERE total > 4000; -- WHERE IN 子查询（需子查询中过滤列有索引） SELECT * FROM orders WHERE user_name IN (SELECT name FROM users WHERE city = '杭州'); -- 标量子查询（需索引支持） SELECT id, user_name, (SELECT COUNT(*) FROM orders o2 WHERE o2.user_name = orders.user_name) AS order_cnt FROM orders; ``` > 详见 [sql-usage-notes.md](sql-usage-notes.md) 中的子查询支持章节。 ### 保留关键字以下关键字不能作为表名或列名使用： ``` SELECT, FROM, WHERE, AND, OR, NOT, IN, LIKE, BETWEEN, IS, NULL, TRUE, FALSE, CREATE, ALTER, DROP, TABLE, INDEX, PRIMARY, KEY, VALUES, UPSERT, UPDATE, DELETE, INSERT, INTO, SET, ORDER, BY, ASC, DESC, LIMIT, OFFSET ``` 如需使用保留字，请用双引号括起： ```sql CREATE TABLE "order" ("select" VARCHAR, PRIMARY KEY("select")); ``` FILE:references/01-dev/sql-usage-notes.md # Lindorm SQL 使用注意事项 ## 目录 - [与 MySQL 的兼容性差异](#与-mysql-的兼容性差异) - [查询结果不符合预期的排查](#查询结果不符合预期的排查) - [SQL 使用注意事项](#sql-使用注意事项) - [HASH 打散注意事项](#hash-打散注意事项) - [冷热分离注意事项](#冷热分离注意事项) - [Compaction 与存储管理](#compaction-与存储管理) --- ## 与 MySQL 的兼容性差异 Lindorm SQL 兼容 MySQL 5.7/8.0 的部分功能和语法，但由于产品架构不同，部分语法或功能并没有被完全支持。 ### 词法要素差异 | 项目 | Lindorm SQL | MySQL | |------|-------------|-------| | 大小写敏感 | 数据库对象标识符严格区分大小写 | 可配置 | | 标识符引用 | 必须用反引号 \` 引用 | 支持多种方式 | | 字符串常量 | 只能用单引号 ' | 支持单引号和双引号 | ### 不支持的数据类型 - BIT 类型 - MEDIUMINT 类型 - REAL 类型 - 各种 TEXT 类型 - DATETIME 类型 - 除 BIGINT UNSIGNED 以外的 UNSIGNED 类型 > 对于 TINYINT、INTEGER、BIGINT 等整型类型，不支持指定具体的长度限制。 ### 事务支持 Lindorm 不支持多行事务（即一次读写多行数据的事务性）。 ### INSERT 语义差异 Lindorm SQL 的 INSERT 本质是 UPSERT，对于主键相同的数据会直接覆盖写入语句中涉及到的字段/列。 > 传统数据库中基于全主键的等值过滤条件进行 UPDATE 的语句建议改成使用 INSERT 语句，来取得更好的性能。 **INSERT 限制**： - INSERT 语句需要显式指定待写入的表的字段列表 - 字段列表中必须至少指定一个非主键列 ### DELETE/UPDATE 限制 DELETE 和 UPDATE 语句必须指定 WHERE 条件，且需要 WHERE 过滤条件能够明确指定所有主键的等值条件精确定位到一条数据。 > 如果 WHERE 过滤条件可以定位到一批数据，默认无法执行。若需要批量删除/更新，需联系 Lindorm 技术支持配置系统参数启用。 **批量操作注意事项**： - 批量删除/更新时，操作的原子性无法保证 - 批量操作是先查后删/更新，请尽可能保证 WHERE 条件能够高效命中索引 - 大量删除操作会影响某些查询场景的性能，可以设置 TTL 的情况下优先通过 TTL 让数据过期 ### SELECT 限制 - 不支持 JOIN（INNER JOIN / LEFT JOIN / RIGHT JOIN 均不支持，报错 `JOIN is not allowed in Lindorm SQL`） - 不支持 UNION、UNION ALL - 不支持 INTERSECT、MINUS/EXCEPT（MINUS 报语法错误；INTERSECT/EXCEPT 语法不报错但运行时触发低效查询拦截，实际不可用） ### 子查询支持 Lindorm SQL 对子查询提供有限支持，具体取决于子查询形式和是否创建索引： | 子查询形式 | 无索引 | 有二级索引 | 说明 | |-----------|--------|-----------|------| | 派生表（FROM 子句） | ✅ 支持 | ✅ 支持 | `SELECT * FROM (SELECT ...) AS t` | | 派生表 + WHERE | ✅ 支持 | ✅ 支持 | 外层 WHERE 过滤派生表结果 | | 多层嵌套派生表 | ✅ 支持 | ✅ 支持 | 多层 FROM 子查询嵌套 | | 标量子查询（SELECT 列） | ❌ 低效拦截 | ✅ 支持 | `(SELECT COUNT(*) FROM ...) AS cnt` | | WHERE IN 子查询 | ❌ 低效拦截 | ✅ 支持 | 需子查询中的过滤列有索引 | | WHERE EXISTS 子查询 | ❌ 低效拦截 | ✅ 支持 | 需子查询中的过滤列有索引 | > **关键说明**：WHERE IN / EXISTS / 标量子查询的失败不是语法不支持，而是因为无索引导致全表扫描被**低效查询拦截**机制拒绝。创建二级索引后即可正常执行。 **官方文档**：https://help.aliyun.com/zh/lindorm/user-guide/compatibility-comparison-between-lindorm-sql-and-mysql ### 窗口函数支持 ⚠️ **有限支持**：官方兼容性文档标注窗口函数为"暂不支持"，语法不报错但可能存在**正确性或稳定性风险**（服务端计算开销较大）。实测 ROW_NUMBER/RANK/DENSE_RANK/LEAD/SUM OVER/AVG OVER 在当前版本可正常执行，LAG 在低版本存在解析器 bug（`LAG(...) AS alias` 报错）。生产环境**谨慎使用**，建议优先用计算引擎（OLAP）处理窗口计算。 | 窗口函数 | 说明 | 示例 | |---------|------|------| | `ROW_NUMBER()` | 行号 | `ROW_NUMBER() OVER (PARTITION BY col ORDER BY col)` | | `RANK()` | 排名（相同值同排名，跳号） | `RANK() OVER (ORDER BY col DESC)` | | `DENSE_RANK()` | 排名（相同值同排名，不跳号） | `DENSE_RANK() OVER (ORDER BY col)` | | `SUM() OVER` | 累计求和 | `SUM(amount) OVER (PARTITION BY user_id)` | | `AVG() OVER` | 累计平均 | `AVG(score) OVER (PARTITION BY class_id)` | | `LEAD(col, offset)` | 后续行 | `LEAD(amount, 1) OVER (ORDER BY id)` | | `LAG(col, offset)` | 前置行 | `LAG(amount, 1) OVER (ORDER BY id)` | ### 低效查询拦截 Lindorm 默认会拦截可能导致全表扫描的查询，报错 `DoNotRetryIOException: Detect inefficient query`。 **触发场景**：WHERE 条件中的列没有索引，且无法通过主键定位数据。 **解决方案**： 1. **创建二级索引**（推荐）：对 WHERE 条件中的列创建二级索引 ```sql CREATE INDEX idx_region ON orders (region) INCLUDE (user_name, amount); -- 之后 WHERE region = '华东' 即可走索引 ``` 2. **使用 HINT 允许全表扫描**（慎用，可能影响性能）： ```sql SELECT /*+ _l_allow_filtering_ */ * FROM orders WHERE region = '华东'; ``` 3. **添加主键范围条件**： ```sql SELECT * FROM orders WHERE id >= 1 AND id < 100 AND region = '华东'; ``` > **索引生效时间**：建索引后需等待构建完成才能生效。二级索引(KV)约 10 秒，搜索索引(SEARCH)约 30 秒。立即查询可能仍报低效查询错误。 > 索引类型选择：二级索引（KV）支持等值/范围/前缀模糊查询；后缀模糊（`%xxx`）需搜索索引（SEARCH）。详见 [table-design.md](table-design.md)。 ### LIKE 和范围查询二级索引（KV）支持范围查询和 LIKE 前缀匹配： | 查询类型 | 二级索引(KV) | 搜索索引(SEARCH) | |---------|-------------|-----------------| | 等值 `=` | ✅ | ✅ | | IN | ✅ | ✅ | | 范围 `> < >= <=` | ✅ | ✅ | | BETWEEN | ✅ | ✅ | | LIKE 前缀 `'xxx%'` | ✅ | ✅ | | LIKE 单字符 `'xxx_'` | ✅ | ✅ | | LIKE 后缀 `'%xxx'` | ❌ | ✅ | | LIKE 包含 `'%xxx%'` | ❌ | ✅ | | 多维查询 | ❌ | ✅ | ```sql -- 二级索引：支持等值、范围、LIKE前缀 CREATE INDEX idx_amount ON orders (amount) INCLUDE (user_name, product); -- 之后这些查询都能走索引： -- WHERE amount = 3999 -- WHERE amount > 1000 -- WHERE amount BETWEEN 1000 AND 5000 -- WHERE product LIKE '手%' -- 搜索索引：支持后缀模糊、多维查询、分词查询 -- ⚠️ 需先在控制台开通搜索索引功能，否则报 SERVER INTERNAL ERROR CREATE INDEX idx_search USING SEARCH ON orders (region, product, amount); -- 支持：WHERE product LIKE '%脑%' -- 支持：WHERE region = '华东' AND amount > 1000 ``` ### 分词查询（MATCH AGAINST）搜索索引支持分词查询，使用 `MATCH ... AGAINST` 语法： ```sql -- 创建带分词器的搜索索引 CREATE INDEX idx_text USING SEARCH ON articles ( content(type=text, analyzer=ik) ); -- 分词查询：匹配包含"功能介绍"的记录 SELECT * FROM articles WHERE MATCH(content) AGAINST('功能介绍'); -- 会匹配包含"功能"、"介绍"或"功能介绍"的记录 ``` **支持的分词器**：`standard`（默认）、`ik`（中文推荐）、`english`、`whitespace`、`comma` > 详细说明见 [table-design.md](table-design.md#搜索索引开通条件) ### ALTER TABLE 限制 - 支持加列和删列，但不支持重命名列 - 不支持修改列定义（包括列类型、精度、默认值等） - 不支持通过 ALTER TABLE 语句增减索引 - 不支持修改表的主键 ### 其他不支持的语法 - RENAME TABLE - REPLACE - SELECT ... FOR SHARE - 显式事务语法（START TRANSACTION, COMMIT, ROLLBACK） - CREATE TABLE AS SELECT - 表的导入/导出语法（IMPORT, LOAD） - EXPLAIN ANALYZE - FOREIGN KEY - 唯一索引（UNIQUE INDEX） --- ## 查询结果不符合预期的排查 Lindorm 宽表引擎的存储模型是基于 LSM-Tree 实现的。数据写入是即时可见的，不会出现写入后过一段时间才可见的情况。如果查询结果不符合预期，请按以下原因排查。 ### 1. 数据未正常写入或查询发起的时间在数据写入前如果写入链路出现问题，可能导致写入延迟或无法正常写入数据。建议在查询条件中添加 HINT 参数，指定查询结果中返回数据写入的时间戳，根据该时间戳判断是否出现了查询先于写入的情况。 ### 2. STRING 字段中含有非正常的停止符或不可见字符如果 STRING 字段中包含不可见字符，可能造成查询结果不符合预期。 **排查方法**：使用范围查询确认是否存在类似问题，例如 `WHERE orderID > "1000" LIMIT 1`。 > Lindorm 不支持 STRING 字段的中间包含停止符（结尾有停止符是正常的）。 ### 3. 查询条件中列名填写错误 - **列名大小写错误**：Lindorm 的列名是大小写敏感的 - **未指定列簇**：如果使用了多 family 功能，必须在查询条件中指定 family，例如 `WHERE meta:column1=xxx` ### 4. 表属性设置了 TTL，查询时数据已过期 TTL 的单位是秒（s），时间戳的单位为毫秒（ms）。 **常见问题**： - 写入数据时指定了较早的时间戳，且该时间戳与当前时间的差值大于 TTL 设定值，可能在写入时就被清理掉 - 如果在时间戳的使用上未遵循时间语义，而是使用自定义的版本号（例如 1、2、3、4 这种比较小的数字），数据极易被过期清理 - 使用较大的自定义时间戳/版本号（如微秒或纳秒时间戳），可能造成数据无法正常过期清理 ### 5. 设置了 Cell TTL，查询时数据已过期 Cell TTL 单位为毫秒（ms）。如果 KV 上设置了 Cell TTL，其过期时间为 `min{Cell 上设置的过期时间, 表属性上的过期时间}`。 ### 6. 删除请求的时间戳设置不合理删除请求支持设置时间戳/版本号，代表删除该行/该列在此时间/版本之前的数据。 - 如果删除请求的时间戳比数据写入的时间戳/版本号小，那么这行数据不会被删除 - 如果删除请求设置的时间戳/版本号较大，删除请求提交后将持续生效，后续写入的数据可能被立即删除 > SQL 访问方式不支持设置删除时间戳。 ### 7. 表属性 VERSIONS 被设置为 0 VERSIONS 属性的值为 0 表示表中的数据不会保留，任何写入的数据都将被删除，无法查询。 **解决方案**：删除表并重新建表，或将 VERSIONS 属性修改为大于等于 1 的值。 ### 8. 表属性为 IMMUTABLE 的表有更新 IMMUTABLE 表示该表仅支持整行写入（即一行的数据通过一条 UPSERT 语句写入），不可更新或删除。 --- ## SQL 使用注意事项 ### 动态列表 SELECT * 限制开启动态列的表可能包含大量的动态列，且表的 Schema 定义不固定。对这类表进行全表扫描将会导致 IO 消耗严重。 **解决方案**：在 SELECT 语句中添加 LIMIT 子句，限制返回结果的数量，例如 `SELECT * FROM test LIMIT 10`。 ### 常用表属性单位 | 属性 | 单位 | 说明 | |------|------|------| | TTL | 秒 (s) | 数据有效期 | | COMPACTION_MAJOR_PERIOD | 毫秒 (ms) | Major Compaction 周期 | | 时间戳 | 毫秒 (ms) | 数据版本时间 | | Cell TTL | 毫秒 (ms) | 单个 KV 过期时间 | --- ## HASH 打散注意事项主键 HASH 打散功能通过 HASH 函数将数据分散到不同的分片（Region），避免数据倾斜和负载不均等问题。 ### DDL 限制 - HASH 函数表达式必须放在最前面 - 错误：`PRIMARY KEY(p1, hash32(p1), p2)` - 正确：`PRIMARY KEY(hash32(p1), p1, p2)` - 在主键列或索引中对某列使用 HASH 算法时，必须指定该列为主键列或索引列 - 已指定 HASH 算法的主键列不支持修改 - 使用主键 HASH 打散功能后，不支持使用 bulkload 方式导入数据 ### DML 限制 **写入数据**：无需在 SQL 语句中添加 HASH 相关参数，系统自动生成并填充 HASH 值。 **查询数据**： - 必须指定所有已使用 HASH 算法的主键列的值，否则系统无法计算 HASH 值，导致查询全表 - 对于使用了 HASH 算法的主键列，查询条件必须为等值查询，不支持范围查询 ```sql -- 推荐的使用方式 SELECT * FROM t1 WHERE p1=1 AND p2=1; -- 不推荐：未指定主键列 p1 的值，会导致查询全表 SELECT * FROM t1 WHERE p2=1; -- 错误：不支持 HASH 列的范围查询 SELECT * FROM t1 WHERE p2=1 AND p1>2 AND p1<8; ``` --- ## 冷热分离注意事项 ### 数据何时进入冷存储 Lindorm 通过 Compaction 机制异步将冷数据从热存储归档至冷存储： - 系统触发时间默认为冷热分界线的一半 - 最小为 1 天 - 最大为 Major Compaction 周期的一半（默认 20 天）例如：冷热分界线为 3 天，则默认 1.5 天自动触发一次 Compaction 归档任务。 ### 手动触发 Compaction 可以通过 `major_compact 'tableName'` 手动触发 Compaction。 > `major_compact` 命令会加重 IO 负载，不建议频繁使用。如果执行 Compaction 后数据还未进入冷存储，可能是数据还未写入磁盘，请先执行 flush 操作。 ### 自定义时间列冷热分离 - 如果一行数据未写入自定义时间列，该行数据会被保留在热存储区，不会冷热分离 - 如果更新的冷数据不是自定义时间列，更新后的数据依旧是冷数据 - 如果更新的是自定义时间列中的数据，需要根据新写入的时间内容来重新划分冷热数据 ### 按时间戳冷热分离由于更新后的数据重新记录了时间戳，因此冷数据更新后变为热数据。 ### HOT_ONLY 查询注意事项查询语句可以通过设置 `HOT_ONLY` / `_l_hot_only_` 仅查询热数据。但由于数据归档至冷存储的操作是周期性触发的，部分冷数据可能会滞留在热存储，导致查询结果中包含冷数据。 **解决方案**：在查询条件中添加热数据时间范围： ```sql SELECT /*+ _l_hot_only_(true), _l_ts_min_(1000), _l_ts_max_(2001) */ * FROM test WHERE p1>1; ``` ### 索引表与主表冷数据不一致主表和索引表的冷数据归档过程是独立的，且归档操作是周期性触发的，导致主表和索引表滞留在热存储的数据不一致，进而出现查询到的冷数据不一致的现象。 **解决方案**：在查询条件中添加热数据的时间范围。 ### 开启冷热分离后立即触发 Compaction 当前时间减去最旧的文件的生成时间大于冷数据归档周期时，则会触发冷数据转存。 --- ## Compaction 与存储管理 ### Compaction 的作用 - 清理过期数据（TTL） - 清理删除操作的遗留标记（deleteMarker） - 归档冷热数据 - 压缩数据减少空间占用 ### Compaction 自动触发周期系统默认的自动触发周期为 20 天。在 TTL 场景下，默认周期为 `min(TTL 值, 20 天)`。 **修改触发周期**： ```sql -- 将自动触发周期修改为 2 天（单位为毫秒） ALTER TABLE SET 'COMPACTION_MAJOR_PERIOD'='172800000'; ``` ### Compaction 对业务的影响 Compaction 操作处理数据时会消耗 CPU。CPU 资源充足时对业务没有太大影响，反而有助于提升读性能、释放存储空间。 **监控 Compaction 状态**：通过实例监控查看宽表引擎指标 > 集群负载 > Compaction 队列长度。如果该数值持续增长或始终持平，说明可能存在大量排队任务。 **优化建议**： - 如果 CPU 利用率小于 40%，宽表 2.6.5 以上版本支持自动根据 load 调整参数，直接升级小版本即可 - 如果 CPU 利用率大于 40%，建议增加宽表引擎节点数量 ### 已设置 TTL 但存储仍在上涨通过实例监控查看 Compaction 队列长度，确认是否存在任务积压情况，如果积压较多就会出现数据清理滞后的现象。如果队列无任务且读写负载较低，可以手动执行 Compaction 或调整 Major Compaction 周期。 ### 磁盘容量上限处理 - 扩容热存储容量 - 通过 `DROP TABLE` 直接删除无用的表，立即释放存储空间 - 通过 `TRUNCATE TABLE` 清空表中数据，立即释放存储空间 > 请勿使用 DELETE 直接删除数据。Lindorm 的删除操作是直接写入删除标记（Delete Marker），等到下次触发 Compaction 操作才会被彻底清理。 ### 磁盘容量上限后无法删除数据磁盘达到容量上限后系统将禁止所有数据的写入，包括删除标记。删除标记无法写入将导致需删除的数据无法通过 Compaction 操作清理。 ### 压缩算法和编码方式可以将表的压缩算法 COMPRESSION 设置为 ZSTD，编码方式 DATA_BLOCK_ENCODING 设置为 INDEX，并执行 Major Compact 以减少存储空间。 ```sql ALTER TABLE SET 'COMPRESSION' = 'ZSTD','DATA_BLOCK_ENCODING' = 'INDEX'; ALTER TABLE COMPACT; ``` > 如果您是通过 SQL 方式创建的表，则默认已设置，无需重复设置。 FILE:references/01-dev/table-design.md # Lindorm SQL 建表语句指南本文档提供 Lindorm 宽表建表语句的完整指南，包括语法、最佳实践和高级特性。 ## 数据类型 ### 数据类型查找规则当使用 Lindorm 宽表引擎建表时，需要了解其支持的数据类型。Lindorm 宽表引擎支持基础数据类型、JSON 数据类型和空间数据类型。 1. 当用户提到的数据类型不在 Lindorm 宽表引擎支持的数据类型范围内时，需要提示用户 Lindorm 宽表引擎支持的数据类型，并提供相关文档链接。 2. 数据类型优先从下文的表格中选择。 3. 当数据类型不在下文表格中时，需要查找官方文档： - **基础数据类型**: https://help.aliyun.com/zh/lindorm/developer-reference/basic-data-types - **JSON 数据类型**: https://help.aliyun.com/zh/lindorm/developer-reference/json-data-type - **空间数据类型**: https://help.aliyun.com/zh/lindorm/developer-reference/spatial-data-type-1 4. 如果数据类型仍然不在支持范围内，需要提示用户不支持该数据类型或联系技术支持。 ### 基本数据类型 | 类型 | 字节长度 | 说明 | Java 映射 | 取值范围/精度 | |------|----------|------|-----------|----------------| | BOOLEAN | 1 字节 | 布尔型 | java.lang.Boolean | true / false | | TINYINT | 1 字节 | 8 位精确数值 | java.lang.Byte | -128 ~ 127 (有符号) | | SMALLINT | 2 字节 | 16 位精确数值 | java.lang.Short | -32768 ~ 32767 | | INTEGER | 4 字节 | 32 位精确数值 | java.lang.Integer | -2^31 ~ 2^31-1 | | BIGINT | 8 字节 | 64 位精确数值 | java.lang.Long | -2^63 ~ 2^63-1 | | FLOAT | 4 字节 | 单精度浮点数 | java.lang.Float | 约 7 位有效数字 | | DOUBLE | 8 字节 | 双精度浮点数 | java.lang.Double | 约 15-17 位有效数字，科学计数法表示 | | DECIMAL(precision, scale) | 变长 | 高精度十进制 | java.math.BigDecimal | precision: [1,38], scale: [0,precision] | | VARCHAR | 变长 | 变长字符串 | java.lang.String | 最大 2MB，支持中文 | | CHAR(n) | n 字节 | 定长字符串 | java.lang.String | 固定长度 n，不足自动补空格 | | BINARY(n) | n 字节 | 定长二进制 | byte[] | 固定 n 字节，不足补 0，超出截断 | | VARBINARY | 变长 | 变长二进制 | byte[] | 作为主键时只能是最后一列 | | DATE | 4 字节 | 日期（仅日期无时间） | java.sql.Date | YYYY-MM-DD，**不推荐**（时区转换易出错） | | TIME | 4 字节 | 时间 | java.sql.Time | HH:mm:ss，受时区影响 | | TIMESTAMP | 8 字节 | 时间戳 | java.sql.Timestamp | 0001-01-01 00:00:00 ~ 9999-12-31 23:59:59 | **重要说明**: - **TIMESTAMP**: Lindorm 支持的最大值为 `9999-12-31 23:59:59`，而 MySQL 仅支持到 `2038-01-19 03:14:07` - **DECIMAL**: 适用于金额等高精度场景，监控等精度要求不高的场景推荐使用 FLOAT/DOUBLE - **DATE/TIME**: 在时区转换过程中易出现日期错误，建议避免使用 ### JSON 数据类型 **适用引擎**: 仅宽表引擎支持（要求版本 2.6.2+） **限制**: 主键列不支持 JSON 类型 **建表语法**: ```sql -- 创建表时指定 JSON 列 CREATE TABLE tb ( p1 INT, c1 VARCHAR, c2 JSON, PRIMARY KEY(p1) ); -- 修改表添加 JSON 列 ALTER TABLE tb ADD c3 JSON; ``` ### 类型使用建议 - **主键列**: 推荐使用 VARCHAR 或 BIGINT，VARBINARY 只能作为最后一列主键 - **时间戳**: 优先使用 TIMESTAMP（范围更大），或使用 BIGINT (毫秒) - **大文本**: 使用 VARCHAR，最大 2MB - **二进制**: 使用 BINARY(n) 或 VARBINARY - **高精度数值**: 使用 DECIMAL(如金额) - **一般数值**: 使用 INTEGER/BIGINT/FLOAT/DOUBLE - **避免使用**: DATE、TIME（时区问题） ## 基础语法 **注意事项**: - 只能基于本 Skill 文档中明确记载的内容回答用户问题，严禁推测、联想或生成文档中不存在的 SQL 语法、参数、功能或配置。 - 如果文档中没有相关信息，必须明确告知用户“当前文档未收录此内容”，并引导用户查阅官方文档。 - 生成的代码示例必须基于文档中的模板，参数和语法必须与文档一致。 ### CREATE TABLE 语法 ```sql CREATE TABLE [ IF NOT EXISTS ] table_identifier '(' column_definition ( ',' column_definition )* ',' PRIMARY KEY '(' primary_key ')' ( ',' {KEY|INDEX} [index_identifier] [ USING index_method_definition ] [ INCLUDE column_identifier ( ',' column_identifier )* ] [ WITH index_options ] )* ')' [ WITH table_options ] ``` **语法要素说明：** | 语法要素 | 说明 | |---------|-----------------------------------------------------------------------| | column_definition | `column_identifier data_type [ NOT NULL ] [ DEFAULT default_value ] ` | | primary_key | `column_identifier [ ',' column_identifier (ASC\|DESC)]` | | index_method_definition | `{ KV \| SEARCH }` | | index_options | `'(' option_definition (',' option_definition )*')'` | | table_options | `'(' option_definition (',' option_definition )* ')'` | | option_definition | `option_identifier '=' string_literal` | ### DEFAULT 子句列定义支持通过 DEFAULT 子句设置默认值。 **限制：** - 默认值只能是列类型的常量表达式或无参函数 `NOW()` - 不可以设置为 NULL **示例：** ```sql CREATE TABLE orders ( id VARCHAR NOT NULL, status INTEGER DEFAULT -1, create_time TIMESTAMP DEFAULT NOW(), remark VARCHAR DEFAULT 'pending', PRIMARY KEY(id) ); ``` ### 命名规范 **表名（table_identifier）：** - 可包含数字、大小写英文字符、半角句号（.）、中划线（-）和下划线（_） - 不能以半角句号（.）或中划线（-）开头 - 长度为 1~255 字符 **列名（column_identifier）：** - 可包含数字、大小写英文字符、半角句号（.）、中划线（-）和下划线（_） - 不允许使用系统保留关键字 - 长度不能超过 255 字节 ### 基础建表示例 ```sql -- 基础表 CREATE TABLE orders ( channel VARCHAR NOT NULL, id VARCHAR NOT NULL, ts TIMESTAMP NOT NULL, status VARCHAR, location VARCHAR, PRIMARY KEY(channel, id, ts) ); -- 带表属性的表 CREATE TABLE orders ( channel VARCHAR NOT NULL, id VARCHAR NOT NULL, ts TIMESTAMP NOT NULL, status VARCHAR, PRIMARY KEY(channel, id, ts) ) WITH ( COMPRESSION = 'ZSTD', TTL = '86400' ); ``` ## 主键设计 ### 主键特性 - **不可修改**：主键在建表时确定，建表后不可增加、删除、更换顺序或修改数据类型 - **唯一性**：所有主键列共同组成 RowKey，在一张表里是唯一的 - **聚簇索引**：数据按照主键顺序存储，遵循最左匹配原则 ### 主键限制 - 单个主键列的最大长度为 2 KB - 所有主键列的长度之和不能超过 30 KB - 单个非主键列的最大长度不能超过 2 MB ### 主键设计最佳实践 #### 避免热点问题 ```sql -- 错误示例：递增主键导致写入热点 CREATE TABLE logs ( timestamp BIGINT NOT NULL, message VARCHAR, PRIMARY KEY(timestamp) ); -- 正确示例：使用 HASH 打散 CREATE TABLE logs ( timestamp BIGINT NOT NULL, hostname VARCHAR NOT NULL, message VARCHAR, PRIMARY KEY(hash32(timestamp), timestamp, hostname) ); ``` #### 主键设计原则 1. **主键第一列尽量分散**：不建议使用相同前缀 2. **避免自增数据**：如时间戳列作为第一列 3. **避免枚举值**：如 order_type 作为第一列 4. **主键列数量**：建议控制在 1~3 个 5. **主键值长度**：建议尽量短小，使用固定长度类型 #### 常见场景设计 **日志/时序数据：** ```sql -- 查询某机器某指标某段时间数据 CREATE TABLE logs ( hostname VARCHAR NOT NULL, log_event VARCHAR NOT NULL, timestamp BIGINT NOT NULL, content VARCHAR, PRIMARY KEY(hostname, log_event, timestamp) ); -- 查询最新数据（倒序） CREATE TABLE logs ( hostname VARCHAR NOT NULL, log_event VARCHAR NOT NULL, timestamp BIGINT NOT NULL, content VARCHAR, PRIMARY KEY(hostname, log_event, timestamp DESC) ); -- 时间维度数据量大，使用分桶打散 CREATE TABLE logs ( bucket BIGINT NOT NULL, timestamp BIGINT NOT NULL, hostname VARCHAR NOT NULL, log_event VARCHAR NOT NULL, content VARCHAR, PRIMARY KEY(bucket, timestamp, hostname, log_event) ); -- 写入时：bucket = timestamp % numBuckets ``` **交易数据：** ```sql -- 按卖家查询 CREATE TABLE seller_orders ( seller_id VARCHAR NOT NULL, timestamp BIGINT NOT NULL, order_number VARCHAR NOT NULL, amount BIGINT, PRIMARY KEY(seller_id, timestamp, order_number) ); -- 按买家查询 CREATE TABLE buyer_orders ( buyer_id VARCHAR NOT NULL, timestamp BIGINT NOT NULL, order_number VARCHAR NOT NULL, amount BIGINT, PRIMARY KEY(buyer_id, timestamp, order_number) ); -- 按订单号查询 CREATE TABLE order_index ( order_number VARCHAR NOT NULL, seller_id VARCHAR, buyer_id VARCHAR, PRIMARY KEY(order_number) ); ``` ## HASH 主键打散使用 HASH 函数将数据分散到不同分片，避免数据倾斜和热点问题。 ### 支持的 HASH 算法 | 算法 | 说明 | |------|------| | hash8 | 8 位 HASH，存储消耗最小 | | hash32 | 32 位 HASH，每对 keyValue 额外消耗 4 Bytes | | hash64 | 64 位 HASH，存储消耗最大 | ### 使用示例 ```sql -- 对单个主键列使用 HASH CREATE TABLE t1 ( p1 BIGINT, p2 INTEGER, c1 INTEGER, c2 VARCHAR, PRIMARY KEY(hash32(p1), p1, p2) ); -- 对多个主键列使用 HASH CREATE TABLE t2 ( p1 BIGINT, p2 INTEGER, c1 INTEGER, c2 VARCHAR, PRIMARY KEY(hash8(p1, p2), p1, p2) ); ``` ### 注意事项 - HASH 函数表达式必须放在主键最前面 - 已使用 HASH 算法的主键列不支持修改 - 查询时必须指定所有已使用 HASH 算法的主键列的值 - HASH 列只支持等值查询，不支持范围查询 - 使用主键 HASH 打散后，不支持 bulkload 方式导入数据 ## 表属性（WITH 子句） ### 常用表属性 | 属性 | 类型 | 说明 | |------|------|------| | COMPRESSION | STRING | 压缩算法：SNAPPY、ZSTD、LZ4。默认 ZSTD | | TTL | INT | 数据有效期，单位秒。默认为空（不过期） | | NUMREGIONS | INT | 预分区 Region 数 | | STARTKEY / ENDKEY | 与主键第一列类型相同 | 预分区起止 Key | | SPLITKEYS | 与主键第一列类型相同 | 预分区分裂点 | | DYNAMIC_COLUMNS | STRING | 是否开启动态列，'true' 或 'false' | | MUTABILITY | STRING | 索引写入模式：IMMUTABLE、MUTABLE_LATEST 等 | | CONSISTENCY | STRING | 一致性级别：eventual（默认）、strong | ### 示例 ```sql -- 设置压缩和 TTL CREATE TABLE logs ( id VARCHAR NOT NULL, content VARCHAR, PRIMARY KEY(id) ) WITH ( COMPRESSION = 'ZSTD', TTL = '2592000' -- 30 天 ); -- 设置预分区 CREATE TABLE orders ( id VARCHAR NOT NULL, amount BIGINT, PRIMARY KEY(id) ) WITH ( NUMREGIONS = '16', STARTKEY = 'a', ENDKEY = 'z' ); ``` ## 动态列动态列允许在建表时未显式定义的列在运行时动态写入。 ### 开启动态列 ```sql -- 建表时开启 CREATE TABLE t_dynamic ( p1 INT, c1 INT, c2 VARCHAR, PRIMARY KEY(p1) ) WITH (DYNAMIC_COLUMNS = 'true'); -- 已有表开启 ALTER TABLE t_dynamic SET 'DYNAMIC_COLUMNS' = 'true'; ``` ### 写入动态列动态列的数据类型均为 VARBINARY（字节数组）。 ```sql -- SQL 文本写入（值为 HexString） UPSERT INTO t_dynamic (p1, c2, c3) VALUES (1, '1', '41'); -- 使用 x'' 语法指定 HexString（SQL 引擎 2.6.8+） UPSERT INTO t_dynamic (p1, c4) VALUES (3, x'ef0011'); ``` ### 查询动态列 ```sql -- 显式指定动态列 SELECT p1, c2, c3, c4 FROM t_dynamic WHERE p1 = 1; -- 使用 SELECT *（必须添加 LIMIT） SELECT * FROM t_dynamic LIMIT 10; ``` ## 通配符列通配符列实现多数据类型动态列写入，解决动态列仅支持 VARBINARY 的限制。 ### 支持的通配符 | 通配符 | 说明 | |--------|------| | * | 匹配任意字符序列，包括空序列 | | ? | 匹配任意单个字符 | ### 使用示例 ```sql -- 创建带通配符列的表 CREATE TABLE tb ( pk INTEGER, c1 VARCHAR, `c2*` BIGINT, `c3*` VARCHAR, PRIMARY KEY(pk) ) WITH (wildcard_column = 'c2*,c3*'); -- 写入数据 UPSERT INTO tb(pk, c1, c2, c21, c22, c31) VALUES (1, 'a1', 2, 21, 22, 'c3'); ``` ### 限制 - 通配符列不能作为主键 - SELECT * 查询必须添加 LIMIT - 仅支持为通配符列创建搜索索引，不支持二级索引 - 不支持使用通配符列名进行数据查询，必须使用实际列名 ## 索引（建表时创建）在 CREATE TABLE 语句中通过 KEY 或 INDEX 子句创建索引。 ### 语法 ```sql CREATE TABLE table_name ( column_definitions, PRIMARY KEY(pk_columns), {KEY|INDEX} [index_name] [ USING { KV | SEARCH } ] [ INCLUDE (columns) ] [ WITH (index_options) ] ); ``` ### 索引类型 | 类型 | 关键字 | 说明 | |------|--------|------| | 二级索引 | KV（默认） | 适用于非主键匹配场景 | | 搜索索引 | SEARCH | 适用于多维查询、分词、模糊查询场景 | ### 冗余列设置在建表时创建索引，可通过 INCLUDE 或 WITH (INDEX_COVERED_TYPE) 设置冗余列： ```sql -- 显式指定冗余列 CREATE TABLE sensor ( device_id VARCHAR NOT NULL, region VARCHAR NOT NULL, time TIMESTAMP NOT NULL, temperature DOUBLE, humidity BIGINT, PRIMARY KEY(device_id, region, time), KEY (temperature, time) INCLUDE (humidity) ); -- 冗余所有已定义列 CREATE TABLE sensor ( device_id VARCHAR NOT NULL, region VARCHAR NOT NULL, time TIMESTAMP NOT NULL, temperature DOUBLE, humidity BIGINT, PRIMARY KEY(device_id, region, time), KEY (temperature, time) WITH (INDEX_COVERED_TYPE = 'COVERED_ALL_COLUMNS_IN_SCHEMA') ); ``` ### 示例 ```sql -- 创建表同时创建二级索引 CREATE TABLE orders ( order_id VARCHAR NOT NULL, user_id VARCHAR NOT NULL, amount BIGINT, PRIMARY KEY(order_id), INDEX idx_user USING KV (user_id) INCLUDE (amount) ); -- 创建表同时创建搜索索引 CREATE TABLE products ( id VARCHAR NOT NULL, name VARCHAR, description VARCHAR, PRIMARY KEY(id), INDEX idx_search USING SEARCH (name, description) ); ``` ## CREATE INDEX 语法单独创建索引的语法。 ```sql CREATE INDEX [IF NOT EXISTS] [index_name] [ USING { KV | SEARCH | COLUMNAR } ] ON table_name (index_key_expression) [ INCLUDE (columns) ] [ { ASYNC | SYNC } ] [ WITH (index_options) ]; ``` ### 索引类型 | 参数 | 索引类型 | 说明 | |------|----------|------| | KV | 二级索引 | 默认类型，每表最多 3 个 | | SEARCH | 搜索索引 | 全文搜索，每表最多 1 个 | | COLUMNAR | 列存索引 | 分析计算，每表最多 1 个 | ### 列存索引开通条件 **旧版列存索引**（默认，已正式发布）： | 引擎 | 作用 | |------|------| | 宽表引擎 | 源数据存储 | | LindormDFS | 文件存储（版本 >= 4.0.0） | | 计算引擎 | 执行分析查询 | **开通说明**： 1. **开通 Lindorm 计算引擎** 2. **购买计算资源**（为宽表引擎到计算引擎的数据同步购买计算资源） **控制台开通路径**： 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，选择**宽表引擎** 4. 单击**列存索引**页签，并单击**立即开通** 5. 在弹出的对话框中单击**确定** **创建列存索引示例**（旧版，已正式发布）： ```sql -- 创建列存索引（旧版，同步延迟约15分钟） CREATE INDEX idx_columnar USING COLUMNAR ON my_table( pk0, pk1, pt_d, col0, col1 ) PARTITION BY ENUMERABLE (pt_d, bucket(16, pk0)) WITH ( `lindorm_columnar.user.index.database` = 'my_index_db', -- 列存索引所在库名 `lindorm_columnar.user.index.table` = 'my_index_tbl' -- 列存索引表名 ); ``` **查询列存索引**： ```sql -- 使用 HINT 指定走列存索引查询 SELECT /*+ _use_ldps_(cg_name), _columnar_index_ */ pk1, SUM(col0) FROM my_db.my_table WHERE pt_d = '2024-01-01' GROUP BY pk1; ``` > **注意**：`cg_name` 为计算引擎 OLAP 资源组的名称。 --- ### 新版列存索引（实时同步） > ⚠️ **如需秒级同步延迟**，可使用新版列存索引，目前处于**邀测阶段**。 **新旧版对比**： | 特性 | 旧版列存索引 | 新版列存索引 | |------|-------------|-------------| | **同步延迟** | 15 分钟 | **实时（秒级）** | | **数据新鲜度** | 延迟较高 | 近实时 | | **适用场景** | 离线分析 | 实时分析 | | **版本状态** | 已正式发布 | 邀测阶段 | **申请方式**： - 联系 Lindorm 技术支持申请使用（可在阿里云官网提交工单或联系您的客户经理） **新版引擎版本要求**： | 引擎 | 版本要求 | 作用 | |------|---------|------| | 宽表引擎 | >= 2.8.6 | 源数据存储 | | LTS | >= 3.9.1 | 日志实时订阅 | | 列存引擎 | >= 3.10.15 | 索引数据存储 | | 计算引擎 | - | 执行分析查询 | > **重要区别**：新版列存索引依赖**列存引擎**存储索引数据，支持秒级同步；旧版不依赖列存引擎，同步延迟约15分钟。 **新版创建语法**：新增 `lindorm_columnar.user.index.type = 'LCE'` 属性： ```sql -- 创建列存索引（新版，秒级同步） CREATE INDEX idx_columnar USING COLUMNAR ON my_table( pk0, pk1, pt_d, col0, col1 ) PARTITION BY ENUMERABLE (pt_d, bucket(16, pk0)) WITH ( `lindorm_columnar.user.index.database` = 'my_index_db', -- 列存索引所在库名 `lindorm_columnar.user.index.table` = 'my_index_tbl', -- 列存索引表名 `lindorm_columnar.user.index.type` = 'LCE' -- 新版必填，指定走新版链路 ); ``` > **重要**：`lindorm_columnar.user.index.type = 'LCE'` 为新版必填项，缺失则走旧版链路（15分钟延迟）。 **官方文档**：[列存索引新版](https://help.aliyun.com/zh/lindorm/user-guide/column-store-index-new-version) ### 搜索索引开通条件 > ⚠️ **重要**：搜索索引需要先在控制台开通后才能使用，否则创建索引会报 `SERVER INTERNAL ERROR`。 **开通步骤**： 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，单击**宽表引擎** → **搜索索引** 4. 点击「立即开通」 4. 配置以下参数： | 参数 | 说明 | 建议 | |------|------|------| | 搜索节点规格 | 搜索引擎处理能力 | 16核64GB（QPS 500+，写入 TPS 50000+） | | 搜索节点数量 | 搜索节点个数 | 至少 2 个（避免单点故障） | | LTS 数据同步规格 | 数据同步服务 | 4核16GB | | LTS 节点数量 | 同步节点个数 | 建议 2 个 | | 存储空间 | 搜索引擎存储大小 | 按数据量评估 | > **依赖说明**：搜索索引依赖 LTS 数据同步服务，开通时会同时开通 LTS。如已开通备份恢复或数据订阅功能，则无需重复开通 LTS。 **官方文档**：https://help.aliyun.com/zh/lindorm/user-guide/enable-the-search-index-feature #### 搜索索引适用场景 | 场景 | 说明 | 示例 | |------|------|------| | 多维组合查询 | 任意索引列随机组合查询 | `WHERE c1=? AND c2=?` 或 `WHERE c3=?` | | 分词查询 | 文本分词匹配 | `MATCH(content) AGAINST('关键词')` | | 模糊查询 | LIKE 后缀/包含 | `WHERE name LIKE '%关键词%'` | | 聚合分析 | COUNT/SUM/MIN/MAX/AVG | `SELECT COUNT(*) GROUP BY` | | 排序分页 | 任意索引列排序 | `ORDER BY create_time DESC LIMIT 10` | #### 分词查询语法（MATCH AGAINST）搜索索引支持分词查询，使用 `MATCH ... AGAINST` 语法： ```sql -- 创建带分词器的搜索索引 CREATE INDEX idx_text USING SEARCH ON articles ( title(type=text, analyzer=ik), content(type=text, analyzer=ik) ); -- 分词查询：查询 content 列包含"功能介绍"的记录 SELECT * FROM articles WHERE MATCH(content) AGAINST('功能介绍'); -- 会匹配包含"功能"、"介绍"或"功能介绍"的记录 ``` **支持的分词器**： | 分词器 | 说明 | |--------|------| | standard | 标准分词器（默认） | | ik | 中文智能分词（推荐） | | english | 英文分词 | | whitespace | 按空格分词 | | comma | 按逗号分词 | #### 数据类型限制 > ⚠️ 搜索索引**不支持以下数据类型**：DECIMAL、DATE、TIME。如需使用，请用 DOUBLE 替代 DECIMAL，用 TIMESTAMP 替代 DATE/TIME。 **错误示例**：搜索索引列使用 DECIMAL 会报错 `Incompatible data type casting` #### 索引构建时间 | 索引类型 | 构建时间（实测参考） | |---------|-------------------| | 二级索引(KV) | 约 10 秒 | | 搜索索引(SEARCH) | **约 30 秒** | > 在索引构建完成前执行查询仍会报"低效查询拦截"错误。实际构建时间因数据量而异，建议创建索引后等待足够时间再查询。 #### 冷热分离场景注意事项 > ⚠️ 如果实例已开启冷热分离功能，搜索索引构建过程会回查数据，冷存储（容量型云存储）的限流会直接影响索引构建效率，可能导致写入操作出现反压现象。 **开通冷存储前提**： - 需先在控制台开通**容量型云存储**作为冷存储介质 - 开通路径：登录 Lindorm 控制台 → 选择地域 → 实例列表 → 目标实例ID → 左侧导航栏**冷存储** → 单击**开通** - ⚠️ **警告**：开通过程需要**滚动重启实例**，可能导致读写请求**延迟波动或连接中断**，建议在业务低峰期操作 - 实例存储类型为**本地 HDD 盘**时，不支持开通容量型云存储 **建议**： - 在数据写入热存储期间完成索引构建 - 或临时提升冷存储读取限流 ### 二级索引冗余列（INCLUDE）冗余列用于将其他列的数据复制到索引表中，避免查询时回表主表，提升查询性能。 **默认行为**： - Lindorm SQL 2.9.3.10 及以上版本：未指定 INCLUDE 时，默认**不冗余**任何列 - Lindorm SQL 2.9.3.10 之前版本：未指定 INCLUDE 时，默认**冗余所有列** **冗余所有列（INDEX_COVERED_TYPE）**：如果需要冗余所有列，可通过索引属性 `INDEX_COVERED_TYPE` 设置： | 取值 | 说明 | |------|------| | COVERED_ALL_COLUMNS_IN_SCHEMA | 冗余主表中所有已定义的列 | | COVERED_DYNAMIC_COLUMNS | 冗余所有列，包括动态列（适用于动态表） | ```sql -- 冗余所有已定义列 CREATE INDEX idx_user ON orders (user_id) WITH (INDEX_COVERED_TYPE = 'COVERED_ALL_COLUMNS_IN_SCHEMA'); -- 动态表冗余所有列（包括动态列） CREATE INDEX idx_user ON orders (user_id) WITH (INDEX_COVERED_TYPE = 'COVERED_DYNAMIC_COLUMNS'); ``` **使用建议**： - 建议显式指定需要冗余的列，避免依赖默认行为 - 冗余列会增加存储空间，建议只冗余查询中常用的列 - 仅二级索引支持冗余列，搜索索引和列存索引不支持 **注意事项**： - 显式指定的冗余列不可以包含主键列和索引列 **显式指定冗余列示例**： ```sql -- 显式指定冗余列 CREATE INDEX idx_user ON orders (user_id) INCLUDE (amount, status); -- 查询时可直接从索引获取 amount 和 status，无需回表 SELECT user_id, amount, status FROM orders WHERE user_id = 'u001'; ``` ### 示例 ```sql -- 创建二级索引 CREATE INDEX idx_user ON orders (user_id); -- 创建带冗余列的二级索引 CREATE INDEX idx_user ON orders (user_id) INCLUDE (amount, status); -- 创建搜索索引 CREATE INDEX idx_search USING SEARCH ON products (name, description); -- 使用通配符创建搜索索引 CREATE INDEX idx_all USING SEARCH ON products (*); -- 使用函数表达式创建索引 CREATE INDEX idx_hash ON orders (hash64(user_id, order_date), user_id, order_date); ``` ### 搜索索引键属性 ```sql -- 使用分词器 CREATE INDEX idx_text USING SEARCH ON articles ( title(type=text, analyzer=ik), content(type=text, analyzer=ik) ); ``` | 属性 | 说明 | |------|------| | indexed | 是否创建索引，默认 true | | rowStored | 是否存储原始数据，默认 false | | columnStored | 是否列存储，默认 true | | type | 分词字段设为 text | | analyzer | 分词器：standard、english、ik、whitespace、comma | ## 冷热分离 ### 基于时间戳的冷热分离 ```sql -- 建表时设置 CREATE TABLE dt ( p1 INTEGER, p2 INTEGER, c1 VARCHAR, c2 BIGINT, PRIMARY KEY(p1 DESC) ) WITH ( COMPRESSION = 'ZSTD', CHS = '86400', -- 冷热分界线，单位秒 CHS_L2 = 'storagetype=COLD' ); -- 已有表开启 ALTER TABLE dt SET 'CHS' = '86400', 'CHS_L2' = 'storagetype=COLD'; ``` ### 基于自定义时间列的冷热分离 ```sql -- 建表时设置 CREATE TABLE dt ( p1 INTEGER, p2 BIGINT, p3 BIGINT, c1 VARCHAR, PRIMARY KEY(p1, p2, p3) ) WITH ( COMPRESSION = 'ZSTD', CHS = '86400', CHS_L2 = 'storagetype=COLD', CHS_COLUMN = 'COLUMN=p2' -- 指定时间列 ); -- 指定时间单位 CREATE TABLE dt ( p1 INTEGER, p2 BIGINT, p3 BIGINT, c1 VARCHAR, PRIMARY KEY(p1, p2, p3) ) WITH ( COMPRESSION = 'ZSTD', CHS = '86400', CHS_L2 = 'storagetype=COLD', CHS_COLUMN = 'COLUMN=p2|TIMEUNIT=SECONDS' ); ``` **CHS_COLUMN 注意事项：** - 自定义时间列必须为主键 - 自定义时间列不能作为主键第一列 - 仅支持 BIGINT 和 TIMESTAMP 类型 ### 修改和取消冷热分离 ```sql -- 修改冷热分界线 ALTER TABLE dt SET 'CHS' = '1000'; -- 取消冷热分离 ALTER TABLE dt SET 'CHS' = '', 'CHS_L2' = '', 'CHS_COLUMN' = ''; ``` ## 纠删码（EC）纠删码是一种数据冗余存储机制，可在保证相同可靠性的同时节约存储空间。 ### 前提条件 - 宽表引擎 2.5.4+，底层存储 4.3.4+ - 至少 7 个节点 - 本地 HDD 盘 ### 使用方法 ```sql -- 建表时开启 CREATE TABLE dt ( p1 INTEGER, p2 INTEGER, PRIMARY KEY(p1) ) WITH (EC_POLICY = 'RS-4-2'); -- 修改纠删码算法 ALTER TABLE dt SET 'EC_POLICY' = 'RS-4-2'; -- 删除纠删码算法 ALTER TABLE dt SET 'EC_POLICY' = ''; ``` **说明：** RS-4-2 算法在存储效率上等价于 1.5 副本。 ## 预分区建议在数据量大或使用 Bulkload 导入数据时设置预分区。 ### 预分区数量建议 | 场景 | 建议分区数 | |------|-----------| | SQL/HBase API 写入 | 节点数 × 4 | | Bulkload 批量导入 | 数据量(GB) ÷ 8 | ### 示例 ```sql -- 指定分区数和起止 Key CREATE TABLE orders ( id VARCHAR NOT NULL, amount BIGINT, PRIMARY KEY(id) ) WITH ( NUMREGIONS = '16', STARTKEY = 'a', ENDKEY = 'z' ); -- 指定分裂点 CREATE TABLE orders ( id INTEGER NOT NULL, amount BIGINT, PRIMARY KEY(id) ) WITH ( SPLITKEYS = '100,200,300,400,500' ); ``` ## 完整建表示例 ### 物联网设备数据表 ```sql CREATE TABLE iot_device_data ( device_id VARCHAR NOT NULL, timestamp BIGINT NOT NULL, metric_name VARCHAR NOT NULL, metric_value DOUBLE, `extra_*` VARCHAR, PRIMARY KEY(hash32(device_id), device_id, timestamp DESC, metric_name) ) WITH ( COMPRESSION = 'ZSTD', TTL = '7776000', -- 90 天 DYNAMIC_COLUMNS = 'true', wildcard_column = 'extra_*', CHS = '2592000', -- 30 天后归档到冷存储 CHS_L2 = 'storagetype=COLD', CHS_COLUMN = 'COLUMN=timestamp|TIMEUNIT=SECONDS' ); -- 创建按设备类型查询的二级索引 CREATE INDEX idx_metric ON iot_device_data (metric_name) INCLUDE (metric_value); ``` ### 电商订单表 ```sql CREATE TABLE orders ( order_id VARCHAR NOT NULL, user_id VARCHAR NOT NULL, create_time BIGINT NOT NULL, status VARCHAR, amount BIGINT, items VARCHAR, PRIMARY KEY(hash32(order_id), order_id), INDEX idx_user USING KV (user_id, create_time DESC) INCLUDE (status, amount) ) WITH ( COMPRESSION = 'ZSTD', CONSISTENCY = 'strong', MUTABILITY = 'MUTABLE_LATEST', NUMREGIONS = '32' ); -- 创建搜索索引支持商品搜索 CREATE INDEX idx_search USING SEARCH ON orders (items(type=text, analyzer=ik)); ``` ### 日志分析表 ```sql CREATE TABLE app_logs ( bucket INTEGER NOT NULL, timestamp BIGINT NOT NULL, app_id VARCHAR NOT NULL, level VARCHAR NOT NULL, message VARCHAR, stack_trace VARCHAR, PRIMARY KEY(bucket, timestamp, app_id, level) ) WITH ( COMPRESSION = 'ZSTD', TTL = '604800', -- 7 天 EC_POLICY = 'RS-4-2', CHS = '86400', -- 1 天后归档 CHS_L2 = 'storagetype=COLD' ); -- 写入时：bucket = timestamp % 16 ``` FILE:references/02-ops/backup-restore.md # 备份与恢复场景 ## 触发条件 - "如何备份 Lindorm 数据？" - "怎么恢复到昨天的数据状态？" - "能帮我查看备份列表吗？" - "误删数据后怎么找回？" - "自动备份的周期是多久？" --- ## Agent 行为原则 **安全边界：查询备份信息 + 引导手动操作，恢复操作需用户确认** 1. Agent 暂无直接查询备份列表的 API 2. 提供控制台路径配置自动备份策略 3. 给出恢复步骤，但不直接执行恢复操作 4. 恢复操作会覆盖当前数据，需用户明确确认 --- ## 官方文档 | 场景 | 文档链接 | |------|---------| | 开通备份恢复 | https://help.aliyun.com/zh/lindorm/user-guide/backup-and-restoration | | 自动备份配置 | https://help.aliyun.com/zh/lindorm/user-guide/automatic-backup-of-data-of-lindorm-wide-tables | | 恢复到当前实例 | https://help.aliyun.com/zh/lindorm/user-guide/restore-backup-data-to-the-instance-that-corresponds-to-the-original-data | | 增值服务费用 | https://help.aliyun.com/zh/lindorm/product-overview/value-added-services-pricing | --- ## 各引擎备份能力 | 引擎 | 备份恢复能力 | 说明 | |------|------------|------| | **宽表引擎** | ✅ 支持 | 本文档描述的完整备份恢复功能 | | **搜索引擎** | ❌ 无独立备份 | 搜索索引数据源头在宽表，宽表备份恢复后需重建搜索索引 | | **时序引擎** | ❌ 无独立备份 | 暂无官方备份恢复文档 | | **计算引擎** | ❌ 无需备份 | 无状态Spark计算服务，作业结果落回存储引擎，存储引擎备份已覆盖 | > 官方仅提供宽表引擎的备份恢复功能，其他引擎暂无独立备份方案。 | 类型 | 说明 | 配置方式 | |------|------|---------| | **全量备份** | 备份完整的表数据和结构 | 控制台配置周期和范围 | | **增量备份** | 自动备份变更数据 | 开通后自动运行，无需配置 | ### 全量备份可配置参数 | 参数 | 说明 | 可选范围 | 推荐值 | |------|------|---------|--------| | 备份表 | 指定备份范围 | `*` 全库，或 `namespace:table` 格式（如 `default:test` 表示default命名空间下以test开头的表） | `*`（全库） | | 全量备份周期 | 触发间隔 | 3-10 天 | 7 天 | | 下次全量备份时间 | 开始时间点 | 建议业务低峰期 | 02:00 | | 全量备份保留个数 | 保留的备份数量 | 3-12 个 | 7 个 | ### 备份恢复性能参考（不可配置） | 指标 | 说明 | 参考值 | |------|------|--------| | RPO | 故障时可接受的最大数据丢失量 | < 30 秒（实时增量同步） | | 全量恢复速度 | OSS 最大带宽 / LTS 单机 | 1 GB/s / 100 MB/s | | 增量恢复速度 | Lindorm 目的集群单机 / LTS 单机 | 30-40 MB/s / 100 MB/s | --- ## 场景A：配置自动备份 ### 步骤1：开通备份恢复功能 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，单击**宽表引擎** → **备份恢复** 4. 点击"立即开通" - 若未开通搜索索引或数据订阅：跳转变配页面，需选择 **LTS Core 规格** 和 **节点数量**（规格选择见增值服务文档），完成后点击"立即购买" - 若已开通搜索索引或数据订阅：直接开通，无需变配 ⚠️ **不支持实例类型**：Lindorm新版实例、单节点实例暂不支持备份恢复功能 ### 步骤2：配置全量备份策略 1. 在左侧导航栏，单击**宽表引擎** → **备份恢复** → **全量备份** 2. 点击"创建" 3. 配置参数（推荐值见上方参数表）： - **备份表**：`*`（全库）或指定表如 `default:user_table` - **全量备份周期**：7 天（周期太短可能无法完成备份，太长影响恢复时间） - **下次全量备份时间**：02:00（业务低峰期） - **全量备份保留个数**：7 个 4. 点击"确认" ⚠️ **空间评估**：备份空间不足会导致备份中断。全量备份空间 ≈ (保留个数+1) × 单个全备大小；增量空间 ≈ 日志保留天数 × 每天增量LOG大小。可在 **宽表引擎** → **备份恢复** → **全量备份** 区域查看单个全备大小，增量LOG大小可通过监控获取写入速度估算 ### 验证备份配置后系统会在设定时间自动执行。查看路径：**宽表引擎** → **备份恢复** → **全量备份列表** ### 注意事项 - 首次备份会扫描全表，耗时较长 - 备份过程不影响业务读写 - 增量备份自动运行，无需配置 - 备份存储按量计费，具体价格见[增值服务计费说明](https://help.aliyun.com/zh/lindorm/product-overview/value-added-services-pricing) --- ## 场景B：恢复历史数据 ### 前提条件 1. 实例已开通备份恢复功能（⚠️ Lindorm新版实例、单节点实例暂不支持） 2. 存在误删前的备份（查看路径：**宽表引擎** → **备份恢复** → **全量备份列表**） 3. 备份时间点在保留期内 ### 方式1：恢复到当前实例 **⚠️ 风险警告：会覆盖当前实例的指定表数据，恢复期间表不可用。建议恢复前先清空原表数据，或在测试实例验证** 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，单击**宽表引擎** → **备份恢复** 4. 在全量备份列表中，点击"发起数据恢复" 5. 配置参数： - **恢复集群**：当前实例（⚠️ 版本升级后原版本备份数据不能用于恢复新版本） - **时间点**：选择备份时间点 - **全库恢复**：否（推荐指定表） - **恢复表**：一行写一个，格式为 `namespace:table`（如 `default:testTable`）；恢复到其他表名格式为 `namespace:table/namespace:table2`（如 `default:testTable/default:testTable2`） 6. 点击"确定" ### 方式2：恢复到其他实例适用场景：数据迁移、环境复制注意事项： - 目标实例需有足够存储空间 - 目标实例版本需与源实例一致 - 不支持跨版本恢复 ### 恢复进度查询控制台路径：**宽表引擎** → **备份恢复** → **恢复列表** ### 恢复后验证 ```sql -- 验证数据量 SELECT COUNT(*) FROM user_table; -- 查看部分数据 SELECT * FROM user_table LIMIT 10; ``` --- ## 常见问题 | 问题 | 原因 | 解决方法 | |------|------|---------| | 恢复失败：存储空间不足 | 目标实例空间不够 | 扩容存储空间后重试，或清理无用数据 | | 恢复失败：版本不兼容 | 源和目标实例版本不一致 | 确保版本一致；版本升级后原版本备份数据不能用于恢复新版本 | | 最近可恢复到哪个时间点？ | WAL备份至OSS周期 | 正常情况下最多丢失30秒数据 | | 恢复需要多长时间？ | 取决于数据量 | 全量恢复约100MB/s（LTS单机），增量恢复约30-40MB/s | | 能恢复到其他表名吗？ | 支持 | 格式 `namespace:table/namespace:table2`，可恢复同名表到另一个表 | --- ## 缺参追问 | 缺失参数 | 追问话术 | 默认策略 | |---------|---------|----------| | 实例ID | "请问是哪个 Lindorm 实例需要配置备份？" | 引导用户在控制台操作 | | 备份周期 | "您希望多久备份一次？（推荐7天）" | 默认 7 天 | | 保留个数 | "备份数据需要保留几个？（推荐7个）" | 默认 7 个 | | 恢复时间点 | "请问需要恢复到哪个时间点的数据？" | 列出最近的备份列表供选择 | | 恢复范围 | "需要恢复所有表还是指定的表？" | 默认提示指定表更安全 | --- ## 关联场景 - 备份后数据迁移 → `data-migration.md` - 恢复后性能验证 → `monitoring-guide.md` FILE:references/02-ops/connection-troubleshoot.md # 连接问题排查场景当用户反馈"无法连接 Lindorm 实例"、"连接超时"等问题时，按本指南执行排查。 ## 触发条件用户的典型表达： - "连不上实例" - "连接超时" - "无法访问 Lindorm" - "白名单配置对吗？" - "为什么连接被拒绝？" ## 排查原则连接问题排查采用**分层排查**策略：实例状态 → 白名单 → 网络配置，逐层定位问题。输出格式：**问题定位 → 根因分析 → 解决方案** ## 执行流程 ### 步骤 1：检查实例状态 **目的**：确认实例是否正常运行。 **执行命令**： ```bash aliyun hitsdb get-lindorm-instance \ --instance-id ``` **检查要点**： | 实例状态 | 含义 | 能否连接 | 解决方案 | |---------|------|:--------:|----------| | `ACTIVATION` | 运行中 | ✅ 可以 | 继续排查其他项 | | `CREATING` | 创建中 | ❌ 等待 | 等待实例创建完成（通常 10-30 分钟） | | `MAINTAINING` | 维护中 | ⚠️ 可能中断 | 等待维护完成或联系技术支持 | | `STOPPED` | 已停止 | ❌ 需要启动 | 启动实例后再连接 | | `DELETED` | 已释放 | ❌ 无法恢复 | 实例已释放，无法连接 | | `CLASS_CHANGING` | 变配中 | ⚠️ 可能中断 | 等待变配完成 | **输出示例**： ``` 【步骤 1：实例状态检查】 ✅ 实例状态正常 - 实例 ID：ld-uf6l5kr48wqm6rf1h - 状态：ACTIVATION（运行中） - 创建时间：2025-01-15 10:30:00 继续排查白名单配置... ``` 如果状态异常： ``` 【步骤 1：实例状态检查】 ❌ 实例状态异常 - 实例 ID：ld-uf6l5kr48wqm6rf1h - 状态：CREATING（创建中）【根因】实例尚未创建完成，无法连接【解决方案】 - 等待 10-30 分钟，实例创建完成后自动变为 ACTIVATION 状态 - 可通过 get_instance 命令持续检查状态 ``` --- ### 步骤 2：检查白名单配置 **目的**：确认客户端 IP 是否在白名单中。 **执行命令**： ```bash aliyun hitsdb get-instance-ip-white-list \ --instance-id ``` **检查要点**： - 白名单中是否包含客户端 IP？ - 白名单格式是否正确？ - 单个 IP：`192.168.1.100` - IP 段：`192.168.1.0/24` - 公网访问：`0.0.0.0/0`（⚠️ 不推荐，安全风险高） - 内网访问需要：同 VPC 或 VPC 网段在白名单中 **输出示例**： ``` 【步骤 2：白名单检查】当前白名单配置： - 10.0.0.0/8（内网 VPC 网段） - 172.16.1.100（特定 IP）【检查结果】 - 您的客户端 IP：192.168.1.50 - ❌ 未在白名单中【根因】客户端 IP 不在白名单中，连接被拒绝【解决方案】 1. 方案一：将客户端 IP 加入白名单 📍 精确路径： 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，单击**访问控制** → **白名单** 4. 点击"修改"添加客户端 IP： - 单个 IP：192.168.1.50 - IP 段：192.168.1.0/24 2. 方案二：使用同 VPC 内的 ECS 访问 - 确保 ECS 与 Lindorm 在同一 VPC - 白名单配置为 VPC 网段（如 10.0.0.0/8）如需更多细节，可参考官方白名单配置指南： https://help.aliyun.com/zh/lindorm/getting-started/configure-a-whitelist 需要帮您查看网络配置吗？ ``` --- ### 步骤 3：检查网络配置 **目的**：确认网络类型和访问方式是否匹配。 **执行命令**： ```bash aliyun hitsdb get-lindorm-instance \ --instance-id ``` **检查要点**：从实例详情中提取网络配置： - `NetworkType`：网络类型（`vpc`） - `VpcId`：VPC ID - `VswitchId`：交换机 ID **网络类型与访问方式**： | 网络类型 | 访问方式 | 要求 | 连接地址特征 | |---------|---------|------|---------------| | `vpc` | **内网访问** | 客户端在同 VPC 内 | V1: `-vpc.lindorm.rds.aliyuncs.com`；V2: `-vpc.lindorm.aliyuncs.com`（INTRANET） | | `vpc` | **公网访问** | 已开通公网地址 + 白名单包含公网 IP | V1: `-pub.lindorm.rds.aliyuncs.com`；V2: `-pub.lindorm.aliyuncs.com`（INTERNET） | **输出示例**： ``` 【步骤 3：网络配置检查】网络配置： - 网络类型：VPC - VPC ID：vpc-uf6xxxxx - 交换机 ID：vsw-uf6xxxxx 【访问方式判断】 - 您的客户端：公网 IP（182.92.xxx.xxx） - 实例配置：VPC 内网【根因】实例为 VPC 内网访问，客户端在公网，无法直连【解决方案】 1. 方案一：使用同 VPC 内的 ECS 访问 - 在同 VPC 内创建 ECS 实例 - 通过 ECS 内网 IP 访问 Lindorm 2. 方案二：开通公网连接地址（推荐公网用户使用） 📍 精确路径： 1. 控制台：https://lindorm.console.aliyun.com/ 2. 点击实例 ID "ld-xxx" 3. 左侧菜单：**配置与管理** → **数据库连接** 4. 找到对应引擎，点击**申请公网连接地址** 5. 等待公网地址生成（通常 1-3 分钟） 6. **配置与管理** → **访问控制** → **白名单** → 添加客户端公网 IP > ⚠️ 开通公网地址不等于绑定 EIP。Lindorm 的公网访问是通过"申请公网连接地址"实现的，无需绑定 EIP。 3. 方案三：配置 VPN/专线连接 - 通过 VPN 或专线将客户端网络与 VPC 打通如需更多细节，可参考官方连接指南： https://help.aliyun.com/zh/lindorm/getting-started/connect-to-an-instance ``` --- ### 步骤 4：网络连通性测试（高级排查） **目的**：使用网络工具（ping、telnet）验证网络连通性。 **⚠️ 前提条件**：前三步检查均正常，但仍无法连接。 #### 4.1 使用 ping 测试网络可达性（参考性） **⚠️ 注意**：ping 测试仅供参考，**ping 不通不代表无法连接**。 **适用场景**：初步判断网络层连通性，但 Lindorm 可能禁用 ICMP 响应。 **操作步骤**： ```bash # 从客户端机器执行 ping # 示例 ping lindorm-xxx.lindorm.rds.aliyuncs.com ``` **结果判断**： | 结果 | 含义 | 后续操作 | |-----|------|----------| | ✅ 正常响应 | 网络层可达 | 继续检查端口（步骤 4.2） | | ❌ Request timeout | ICMP 被禁用或网络不通 | **继续用 telnet 测试端口，不要直接判定为网络不通** | | ❌ Unknown host | DNS 解析失败 | 检查 DNS 配置或使用 IP 直接连接 | **重要提示**： - 云产品通常禁用 ICMP（ping）响应以提高安全性 - **ping 不通时，优先使用 `telnet/nc` 或客户端直接连接测试** - 只有当 telnet 也失败时，才判定为网络连通性问题 **完整排查指南**： - 官方文档：[使用 ping 命令检查连接](https://help.aliyun.com/zh/lindorm/support/run-the-ping-command-to-check-the-connection-between-an-ecs-instance-and-a-lindorm-instance) #### 4.2 使用 telnet 测试端口连通性 **适用场景**：ping 通但仍无法连接，需要测试具体端口是否开放。 **操作步骤**： ```bash # 测试宽表引擎 HBase API 端口 telnet 30020 # 测试宽表引擎 MySQL 协议端口（推荐） telnet 33060 # 测试时序引擎端口 telnet 8242 # 测试搜索引擎端口 telnet 30070 ``` **常用端口**：端口请以 `SKILL.md` →「代码生成规范 / 端口号速查表」为准。 **结果判断**： ```bash # ✅ 端口连通（正常） Trying ... Connected to . Escape character is '^]'. # ❌ 端口不通（异常） Trying ... telnet: connect to address : Connection refused ``` **常见问题**： - 端口不通 → 检查安全组规则是否开放对应端口 - 端口连通但连接失败 → 检查认证信息（用户名/密码/AccessKey） **完整排查指南**： - 官方文档：[使用 telnet 命令检查端口连通性](https://help.aliyun.com/zh/lindorm/support/run-the-telnet-command-to-check-the-connectivity-of-the-service-ports-of-lindorm) #### 4.3 安全组规则检查 **适用场景**：ping 或 telnet 不通，需要检查 ECS 安全组。 **检查要点**： 1. ECS 出方向规则：允许访问 Lindorm IP 和端口 2. Lindorm 白名单：包含 ECS 的 IP **配置示例**： ``` ECS 安全组出方向规则： - 协议：TCP - 端口范围：根据所用引擎/协议放通（端口见 SKILL.md →「代码生成规范 / 端口号速查表」） - 目标：Lindorm 实例 IP 或 0.0.0.0/0 Lindorm 白名单： - 添加 ECS 私网 IP 或 VPC 网段 ``` --- ## 常见问题与解决方案 ### 问题 1：连接超时 **可能原因**： 1. 实例状态非 ACTIVATION 2. 网络不通（VPC/白名单问题） 3. 端口未开放或防火墙拦截 **排查步骤**： 1. 检查实例状态（步骤 1） 2. 检查白名单配置（步骤 2） 3. 检查网络配置（步骤 3） 4. 确认使用正确的连接地址和端口 --- ### 问题 2：认证失败 **可能原因**： 1. 用户名或密码错误 2. AccessKey 无权限 **排查步骤**： 1. 确认用户名密码正确（Lindorm 控制台 → 账号管理） 2. 确认 AccessKey 有 Lindorm 操作权限（RAM 控制台 → 权限管理） --- ### 问题 3：公网无法访问 **可能原因**： 1. 未开通公网访问（未申请公网连接地址） 2. 白名单未包含公网 IP **排查步骤**： 1. 确认实例已开通公网连接地址（Lindorm 控制台 → 配置与管理 → 数据库连接 → 查看是否有公网地址） 2. 确认白名单包含公网 IP（步骤 2） --- ### 问题 4：内网无法访问 **可能原因**： 1. 不在同一 VPC 2. 未配置 VPC 访问白名单 **排查步骤**： 1. 确认客户端在同 VPC 内（步骤 3） 2. 确认白名单包含 VPC 网段（步骤 2） --- ## 常见连接错误及解决方案 Agent 在遇到连接错误时，应该查询官方文档获取详细的解决方案： **⭐ 重点文档**： - **Lindorm 连接问题及解决方案**：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-issues-and-solutions - **Lindorm 连接错误及解决方案**：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-errors-and-solutions **常见错误类型**： | 错误类型 | 示例错误信息 | 参考文档 | |---------|------------|---------| | **连接超时** | Connection timeout, SocketTimeoutException | 上述文档 + ping/telnet 排查 | | **连接被拒绝** | Connection refused | 检查端口、安全组、白名单 | | **认证失败** | Authentication failed | 检查用户名密码、AccessKey | | **网络不可达** | Network is unreachable | 检查 VPC、路由表 | | **DNS 解析失败** | Unknown host | 检查 DNS 配置 | **特殊场景**： - **Spark 访问连接超时**：https://help.aliyun.com/zh/lindorm/support/cause-analysis-of-connection-timout-problem-in-sparkonmc-access-to --- ## 连接地址获取 Lindorm 不同引擎有不同的连接地址。**务必根据客户端所在环境选择对应的地址**： ### 确认客户端环境 | 客户端位置 | 应使用的地址 | 地址特征 | |-----------|-------------|----------| | 阿里云 ECS（同 VPC） | 内网地址 | V1: `-vpc.lindorm.rds.aliyuncs.com`；V2: `-vpc.lindorm.aliyuncs.com`（Type=INTRANET） | | 本地电脑 / 公网服务器 | 公网地址 | V1: `-pub.lindorm.rds.aliyuncs.com`；V2: `-pub.lindorm.aliyuncs.com`（Type=INTERNET） | | 阿里云 ECS（跨 VPC） | 公网地址或云企业网 | 需额外配置网络打通 | > ⚠️ **常见错误**：从公网环境使用 VPC 内网地址，导致连接超时。必须确认客户端所处环境后选择对应地址。 ### 获取连接地址 **方法 1：阿里云控制台** 📍 精确路径： 1. 控制台：https://lindorm.console.aliyun.com/ 2. 点击实例 ID "ld-xxx" 3. 左侧菜单：**配置与管理** → **数据库连接** 4. 查看各引擎的内网/公网连接地址 5. 如果没有公网地址，点击**申请公网连接地址** > ⚠️ 开通公网地址不等于绑定 EIP。Lindorm 的公网访问是通过"申请公网连接地址"实现的，无需绑定 EIP。 **方法 2：通过 API 获取** ```bash # V1/V2 通用：查询引擎连接端点 aliyun hitsdb get-lindorm-instance-engine-list --instance-id ld-xxx # V2 专属：查询实例详情（含 ConnectAddressList） aliyun hitsdb get-lindorm-v2-instance-details --instance-id ld-xxx ``` **`get-lindorm-instance-engine-list`（V1/V2 通用）**：返回 `NetInfoList`，通过 `NetType` 判断网络类型： - `NetType: "0"` → 公网地址（`-pub`） - `NetType: "2"` → VPC 内网地址（`-vpc`） **`get-lindorm-v2-instance-details`（仅 V2）**：返回 `ConnectAddressList`，通过 `Type` 判断网络类型： - `Type: INTERNET` → 公网地址（`-pub`） - `Type: INTRANET` → VPC 内网地址（`-vpc`） > 如果两个 API 返回中都没有公网地址（无 `NetType: "0"` 且无 `Type: INTERNET`），说明尚未开通公网，需在控制台申请。 ### 开通公网访问 **前提**：需要从公网（本地电脑等）连接 Lindorm。 📍 操作路径： 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页，单击**目标实例ID** 3. 在左侧导航栏，单击**数据库连接** 4. 切换至目标引擎页签，单击右上角**开通公网地址** 5. 等待地址生成（1-3 分钟） 6. 在左侧导航栏，单击**访问控制** → **白名单** → 添加客户端公网 IP > 💡 查看自己公网 IP：`curl ifconfig.me` --- ## 快速诊断命令一键执行完整排查： ```bash # 1. 检查实例状态 aliyun hitsdb get-lindorm-instance --instance-id ld-xxx # 2. 检查白名单 aliyun hitsdb get-instance-ip-white-list --instance-id ld-xxx ``` --- ## 完整排查清单 **基础检查（使用 API）**： | 检查项 | 命令 | 期望结果 | |--------|------|----------| | **实例状态** | `aliyun hitsdb get-lindorm-instance --instance-id ` | `InstanceStatus = ACTIVATION` | | **白名单配置** | `aliyun hitsdb get-instance-ip-white-list --instance-id ` | 包含客户端 IP 或 VPC 网段 | | **网络类型** | `aliyun hitsdb get-lindorm-instance --instance-id ` | `NetworkType = vpc` | | **VPC 匹配** | `aliyun hitsdb get-lindorm-instance --instance-id ` | 客户端与实例在同 VPC（内网访问） | | **公网地址** | 控制台或 API 查看 | 已开通公网连接地址（非 EIP） | **网络连通性测试（高级排查）**： | 检查项 | 命令 | 期望结果 | |--------|------|----------| | **网络可达性** | `ping ` | 正常响应 | | **端口连通性** | `telnet ` | Connected | | **DNS 解析** | `nslookup ` | 正确解析到 IP | | **安全组规则** | 控制台查看 | 允许访问对应端口 | --- ## 官方文档索引（供 Agent 参考） Agent 在处理连接问题时，**强烈建议**查询以下官方文档获取最新信息： | 文档 | 链接 | 用途 | |------|------|------| | **Lindorm 连接问题及解决方案** | [点击查看](https://help.aliyun.com/zh/lindorm/support/lindorm-connection-issues-and-solutions) | ⭐ 常见连接问题汇总 | | **Lindorm 连接错误及解决方案** | [点击查看](https://help.aliyun.com/zh/lindorm/support/lindorm-connection-errors-and-solutions) | ⭐ 连接错误码解释 | | **使用 ping 命令检查连接** | [点击查看](https://help.aliyun.com/zh/lindorm/support/run-the-ping-command-to-check-the-connection-between-an-ecs-instance-and-a-lindorm-instance) | ⭐ 网络可达性测试 | | **使用 telnet 命令检查端口** | [点击查看](https://help.aliyun.com/zh/lindorm/support/run-the-telnet-command-to-check-the-connectivity-of-the-service-ports-of-lindorm) | ⭐ 端口连通性测试 | | **Spark 连接超时问题** | [点击查看](https://help.aliyun.com/zh/lindorm/support/cause-analysis-of-connection-timout-problem-in-sparkonmc-access-to) | Spark 特定场景 | **⭐ 重点文档**：前 4 个文档是连接问题排查的核心参考，Agent 在处理连接问题时应该优先查询。 --- ## 输出格式连接问题诊断报告采用固定结构： ``` 【连接问题诊断报告】实例 ld-uf6l5kr48wqm6rf1h 【问题定位】白名单配置问题【根因分析】 - 实例状态：✅ ACTIVATION（运行中） - 白名单配置：❌ 客户端 IP 未在白名单中 - 当前白名单：10.0.0.0/8, 172.16.1.100 - 客户端 IP：192.168.1.50 - 网络配置：✅ VPC 配置正常 - 网络测试： - ping：✅ 通 - telnet 30020：❌ 连接被拒绝（白名单限制）【解决方案】 1. 将客户端 IP 加入白名单： 📍 精确路径： 1. 控制台：https://lindorm.console.aliyun.com/ 2. 点击实例 ID "ld-xxx" 3. 安全设置 → IP 白名单 → 修改 4. 添加 IP：192.168.1.50 或 192.168.1.0/24 2. 或使用同 VPC 内的 ECS 访问 📚 完整故障排查指南： - 连接问题汇总：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-issues-and-solutions - 连接错误解决：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-errors-and-solutions 按上述方案修改后，请重试连接。如仍有问题，请提供错误日志。 ``` --- ## 缺参处理 ### 缺 instance-id **追问策略**：先 `list_instances` 让用户选择实例。 --- ## 错误处理 | 错误 | 原因 | 引导用户 | |------|------|----------| | **实例不存在** | 实例 ID 错误或已释放 | 建议先 `list_instances` 确认实例 ID | | **权限不足** | Access Key 无 Lindorm 权限 | 提示需要 `AliyunLindormReadOnlyAccess` 权限 | FILE:references/02-ops/data-migration.md # 数据迁移场景 ## 触发条件 - "如何从 MySQL 导入数据到 Lindorm？" - "怎么把 HBase 集群数据迁移过来？" - "从 Kafka 实时同步数据到 Lindorm 的步骤？" - "能帮我规划数据迁移方案吗？" ## 核心原则 **⚠️ 安全边界：只读 + 引导，严禁直接执行迁移操作** 迁移涉及源库连接信息（账号密码），直接执行可能泄露敏感信息或导致数据丢失。Agent 只提供方案和步骤，引导用户通过控制台操作。 --- ## 官方文档 - LTS（原BDS）服务介绍：https://help.aliyun.com/zh/lindorm/user-guide/bds-introduction - MySQL/RDS → Lindorm（DTS）：https://help.aliyun.com/zh/dts/user-guide/migrate-data-from-an-apsaradb-rds-for-mysql-instance-to-a-lindorm-instance - HBase → Lindorm（LTS）：https://help.aliyun.com/zh/lindorm/user-guide/synchronize-full-and-incremental-data - Lindorm 数据订阅（→ Kafka 导出）：https://help.aliyun.com/zh/lindorm/user-guide/real-time-data-subscription/ - 字段类型映射：https://help.aliyun.com/zh/lindorm/developer-reference/basic-data-types --- ## 迁移方案选择 | 源端 | 推荐方案 | 支持全量+增量 | 关键限制 | |------|---------|-------------|---------| | MySQL/RDS | **DTS**（新用户推荐） | ✅ | ⚠️ 不支持自动表结构迁移，需预先在Lindorm手动建表 | | HBase 1.x/2.x | **LTS** | ✅ | Bulkload写入的数据不会被增量同步 | | Lindorm → Lindorm | **LTS** | ✅ | 需确保网络连通 | | Kafka → Lindorm | **LTS 流式通道** | ✅ | — | | 自建/特殊需求 | 开源工具（Canal/Sqoop/脚本） | 视工具 | Lindorm非完整MySQL，部分工具可能因DDL差异失败 | > ⚠️ LTS原有的RDS同步功能已于2023年3月10日下线，之后购买的LTS实例不再支持MySQL迁移。新用户请用DTS。 --- ## 方案A：DTS 迁移（MySQL/RDS → Lindorm） ### 步骤 1. **进入 DTS 控制台** → https://dts.console.aliyun.com/ → 数据迁移 → 创建任务 2. **配置源库与目标库**：源库类型 MySQL，目标库 Lindorm（需已开通宽表引擎 MySQL 兼容地址） 3. **预先在 Lindorm 手动建表**（⚠️ DTS 不支持自动表结构迁移，参考字段类型映射处理 ENUM→VARCHAR 等类型转换） 4. **预检查**：系统自动检查源库连通性、账号权限、binlog配置（增量迁移需 binlog_format=ROW） 5. **启动迁移**：可在控制台实时查看进度和数据量 6. **验证数据**：在 Lindorm 执行 `SELECT COUNT(*) FROM your_table;` 与源库对比 ### 注意事项 - 全量迁移期间请勿修改源库表结构 - 增量同步前提：MySQL 端必须开启 binlog（binlog_format=ROW） - 建议在业务低峰期执行 --- ## 方案B：LTS 迁移（HBase → Lindorm） ### 步骤 1. **开通 LTS 服务**：Lindorm 控制台 → 目标实例 → 数据生态服务 → 开通 LTS 2. **创建迁移任务**：LTS 操作页面 → 导入Lindorm/HBase → 一键迁移 → 创建任务 3. **配置源端与目标端**：源端 HBase 集群（需与 LTS 网络连通），目标端 Lindorm 宽表引擎；选择 ☑️ 表结构迁移 + ☑️ 历史数据迁移 + ☑️ 实时数据复制 4. **监控与验证**：实时查看迁移进度，LTS 数据抽样校验，业务验证后执行流量切换 ### 注意事项 - 确保 LTS、源 HBase、目标 Lindorm 三者网络已打通 - 增量同步基于 HBase WAL，Bulkload 写入的数据不会被同步 - 迁移前确认目标实例存储空间充足 --- ## 方案C：开源工具迁移 ### C-1：Canal（MySQL → Lindorm 实时同步）解析 MySQL binlog 实时同步到 Lindorm。 1. 部署 Canal Server 2. 配置 Canal 监听 MySQL binlog 3. 使用 Canal Adapter 将数据写入 Lindorm 参考：https://github.com/alibaba/canal ### C-2：Sqoop（Hadoop → Lindorm 批量导入） > ⚠️ Lindorm 宽表引擎是MySQL兼容而非完整MySQL，Sqoop可能因DDL差异失败。 ```bash # 连接地址根据实例 ServiceType 选择（见 sql-client-guide.md →「连接域名格式」） # V1/V2 MySQL 协议端口均为 33060 sqoop export \ --connect jdbc:mysql://<您的连接地址>:<端口>/default \ --table my_table \ --export-dir /user/hive/warehouse/my_table \ --input-fields-terminated-by '\t' ``` ### C-3：自定义脚本适用于数据量小或特殊转换需求。示例： 1. 从源库导出数据（mysqldump、HBase Export） 2. 数据清洗和格式转换 3. 使用 Lindorm SDK 或 MySQL 协议批量写入 Python 示例（MySQL → Lindorm）： ```python import pymysql # 1. 读取 MySQL 数据 mysql_conn = pymysql.connect(host='...', user='...', password='...', database='source_db') cursor = mysql_conn.cursor() cursor.execute("SELECT * FROM source_table") # 2. 写入 Lindorm（MySQL 协议） # 连接地址根据实例 ServiceType 选择（见 sql-client-guide.md） # V1/V2 MySQL 协议端口均为 33060（域名格式见 sql-client-guide.md） lindorm_conn = pymysql.connect( host='<您的连接地址>', port=<端口>, user='root', password='your-password', database='default' ) lindorm_cursor = lindorm_conn.cursor() for row in cursor: placeholders = ','.join(['%s'] * len(row)) lindorm_cursor.execute(f"INSERT INTO target_table VALUES ({placeholders})", row) lindorm_conn.commit() ``` --- ## 常见问题 | 问题 | 原因 | 解决方法 | |------|------|---------| | 连通性检查失败 | 网络不通/白名单未配置 | 确认同一VPC或已配公网；添加源库IP到Lindorm白名单 | | 表结构不兼容 | MySQL类型无Lindorm对应 | ENUM→VARCHAR；TEXT/BLOB超2MB需拆分；必须有主键 | | 增量同步断开 | MySQL binlog被清理 | 增大binlog保留时间；重新配置DTS任务 | | 目标存储不足 | 数据量超预期 | 迁移前确认Lindorm存储空间（建议预留20GB+） | --- ## 关联场景 - 迁移后性能对比 → `monitoring-guide.md` - 验证数据一致性 → `monitoring-guide.md` 查询写入指标 - 迁移任务监控 → LTS 控制台实时查看（暂无 API 支持） FILE:references/02-ops/error-troubleshoot.md # 错误排查场景当用户遇到错误码、异常、报错信息时，按本指南执行。 ## 触发条件 - "报错了：InvalidParameter.InstanceId" - "连接失败：Connection refused" - "为什么提示 AuthenticationFailed？" - "SQL 报错：error code 1045" - "这个错误是什么意思？" ## 核心原则 1. **Agent 提取关键信息**：错误码、错误含义、解决步骤 2. **提供可执行的排查步骤**，不只是抛出文档链接 3. **结合实例状态**，给出针对性建议 --- ## 错误类型分类 | 错误类型 | 示例 | 处理方式 | |---------|------|---------| | **CLI/API 错误** | InvalidParameter, Forbidden.RAM, InstanceNotFound | 速查表一 | | **连接错误** | Connection refused, Timeout, Retry exhausted | 速查表二 | | **SQL 错误** | Error 1045, 1146, 1064, 3024 | 速查表三 | | **性能/限流** | Quota exceeded, Too many connections | 速查表四 | --- ## 速查表一：CLI/API 错误码 | 错误码 | 含义 | 可能原因 | 解决方法 | |--------|------|---------|---------| | `InvalidParameter.InstanceId` | 实例ID无效 | ID格式错误、不存在、已释放 | 检查格式（应为 ld-xxx），用 `get-lindorm-instance --instance-id ` 确认是否存在 | | `InstanceNotFound` | 实例不存在 | ID错误、已释放 | 用 `get-lindorm-instance --instance-id ` 确认 | | `InstanceStatusInvalid` | 实例状态不支持操作 | 实例非运行中 | 等待实例变为 ACTIVATION | | `InstanceLocked` | 实例被锁定 | 欠费、安全原因、运维中 | 检查账户余额、联系技术支持 | | `QuotaExceeded` | 配额不足 | 超过地域配额限制 | 提交工单申请提额 | | `Instance.IsNotValid` | 实例ID格式合法但不存在 | ID错误、已释放 | 通过 `get-instance-summary` 确认 | | `InvalidAccessKeyId.NotFound` | AccessKey不存在 | AK ID错误 | 检查 AK 配置 | | `SignatureDoesNotMatch` | 签名错误 | AK Secret错误 | 验证 Secret 正确性 | | `Forbidden.RAM` | RAM权限不足 | 缺少Lindorm权限 | 添加 `AliyunLindormReadOnlyAccess` 权限 | | `UnauthorizedOperation` | 未授权操作 | 缺少特定操作权限 | 联系主账号授权 | | `Throttling.User` | 用户级别限流 | 请求频率过高 | 降低频率、添加重试机制 | | `Throttling.System` | 系统级别限流 | 系统负载高 | 稍后重试 | --- ## 速查表二：连接错误 ### 网络错误 | 错误信息 | 原因 | 排查步骤 | |---------|------|---------| | `Connection refused` | 端口不通 | 1. 检查白名单 2. 检查安全组 3. telnet 测试端口 | | `Connection timeout` | 网络不可达 | 1. 确认网络类型（VPC/公网）2. 检查路由 3. ping 测试 | | `Unknown host` | DNS解析失败 | 检查连接地址拼写 | | `Network is unreachable` | 网络不通 | 确认 VPC 配置、检查跨 VPC/跨地域访问 | ### 认证错误（SQL层面） | 错误信息 | 原因 | 解决方法 | |---------|------|---------| | `Authentication failed` (Error 1045) | 用户名/密码错误 | 检查密码，遗忘请去控制台重置 | | `Access denied` (Error 1227) | 权限不足 | 检查用户权限配置 | ### HBase 客户端错误（官方连接报错） | 错误信息 | 原因 | 解决方法 | |---------|------|---------| | `Retry exhausted when update config from seedserver` | 连接地址或端口错误（官方：HBase兼容端口为30020） | 确认端口正确（端口见 SKILL.md →「端口号速查表」），检查网络 | | `Failed to connect to jdbc:lindorm:table:url=****` | SQL连接失败（⚠️ Avatica 协议仅存量维护） | 确认端口正确，建议迁移到 MySQL 协议 | | `DoNotRetryIOException: Detect inefficient query` | 全表扫描被拦截（官方：WHERE条件列无索引） | 见 sql-usage-notes.md →「低效查询拦截」 | > 官方连接排查顺序：白名单 → 安全组 → 网络类型匹配 → 公网/专线 ### 时序引擎错误 | 错误信息 | 原因 | 解决方法 | |---------|------|---------| | `TSDB error: table not found` | 表不存在 | 检查表名 | | `TSDB error: invalid timestamp` | 时间戳格式错误 | 使用毫秒级时间戳 | | `Write limit exceeded` | 写入限流 | 降低写入频率、扩容 | --- ## 速查表三：SQL 错误码（官方参考）以下为官方文档中的 MySQL 兼容错误码和 Lindorm 扩展错误码，完整列表见 https://help.aliyun.com/zh/lindorm/developer-reference/common-error-codes-reference ### 常见 MySQL 兼容错误码 | 错误码 | 含义 | 官方处理建议 | |--------|------|------------| | 1040 | 连接数过多（单节点） | 重新审视连接使用方式；2.7.0.0前上限1000，2.7.0.0+上限4000 | | 1045 | 认证失败 | 确认认证信息是否正确 | | 1049 | 未知 Database | 指定正确的 Database 名称 | | 1050 | 表已存在 | 使用其他表名或 IF NOT EXISTS | | 1054 | 未知列名 | 确认 SQL 中的列名是否实际存在 | | 1064 | SQL语法错误 | 参考 SQL 语法文档校正 | | 1146 | 表不存在 | 检查表名是否输入有误 | ### 常见 Lindorm 扩展错误码 | 错误码 | 含义 | 官方处理建议 | |--------|------|------------| | 3024 | 查询超时 | 重试；若仍超时联系技术支持 | | 8005 | 表不存在 | 检查表名 | | 8008 | 超出资源限制 | 查询：缩小时间范围/增加WHERE；写入：限制TPS | | 9001 | 不支持的语法 | 对照SQL语法文档，避免使用不支持的语法 | | 9003 | 认证方法不适用于旧版本用户 | 参考MySQL协议兼容文档，指定支持的认证方法 | --- ## 速查表四：监控指标异常 | 指标异常 | 可能原因 | 排查建议 | V2 注意 | |---------|---------|---------|--------| | `cpu_idle < 10%` | CPU使用率过高 | 查询慢查询日志、考虑扩容 | — | | `mem_used_percent > 90%` | 内存紧张 | 检查缓存配置、扩容 | ⚠️ V2返回空，需用 `1 - mem_free/mem_total` 计算 | | `storage_used_percent > 85%` | 存储空间不足 | 清理数据或扩容 | ⚠️ V2需用 `get-lindorm-v2-storage-usage` API | | `read_rt_p99 > 1000ms` | 查询延迟高 | 分析慢查询、创建索引 | ⚠️ V2返回空 | | `write_rt_p99 > 500ms` | 写入延迟高 | 检查写入模式、考虑扩容 | ⚠️ V2返回空 | --- ## 常见错误处理示例 ### 示例：InvalidParameter.InstanceId ``` 【错误分析】InvalidParameter.InstanceId 【错误含义】实例 ID 参数无效【可能原因】 1. 实例 ID 格式不正确（应为 ld-xxx） 2. 实例不存在或已释放【排查步骤】步骤 1：验证 ID 格式 — 确认以 ld- 开头步骤 2：确认是否存在 — aliyun hitsdb get-lindorm-instance --instance-id （API 自动定位地域，无需指定 --region）【官方文档】https://help.aliyun.com/zh/lindorm/developer-reference/common-error-codes-reference ``` ### 示例：认证失败（Error 1045） ``` 【错误分析】Access denied / Authentication failed (Error 1045) 【错误含义】用户名或密码不正确【排查步骤】步骤 1：确认密码正确（如遗忘请去控制台重置）步骤 2：检查 RAM 权限 — 确保包含 AliyunLindormReadOnlyAccess 步骤 3：验证修复 — aliyun hitsdb get-instance-summary 【常见错误】 ❌ 使用子账号但未授权 Lindorm 权限 ❌ 实例 ID 格式错误或实例不存在 ``` --- ## 官方文档 - **错误码参考**：https://help.aliyun.com/zh/lindorm/developer-reference/common-error-codes-reference - **连接报错与解决**：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-errors-and-solutions - **连接问题与解决**：https://help.aliyun.com/zh/lindorm/support/lindorm-connection-issues-and-solutions - **SQL FAQ**：https://help.aliyun.com/zh/lindorm/developer-reference/sql-faq - **技术支持**：通过阿里云工单系统提交 --- ## 关联场景 - 连接问题 → `connection-troubleshoot.md` - 性能问题 → `monitoring-guide.md` - SQL 使用 → `sql-usage-notes.md` FILE:references/02-ops/instance-management.md # 实例管理场景覆盖实例查询（列表、详情、引擎、存储）与扩缩容知识告知。 ## 触发条件 - "我有哪些 Lindorm 实例？" - "列出 cn-shanghai 的所有实例" - "ld-xxx 这个实例是什么配置？" - "这个实例开了哪些引擎？" - "磁盘还剩多少空间？" - "实例存储快满了，怎么扩容？" - "需要加配置，怎么操作？" --- ## 查询流程 ### 流程 1：列出所有实例 **适用场景**：用户想查看某个地域下的所有实例，或不知道具体实例 ID。 **地域策略**： - **默认行为**：用户未指定地域时，默认查询 `cn-shanghai`（华东2-上海），并**必须明确告知**"本次查询的是上海地域" - **扩展查询**：用户说"所有地域/不确定/可能在其他地域"时，先执行 `get-instance-summary` 获取全地域概览，再按需逐地域查询 **执行命令**： ```bash # 查询指定地域的实例列表（--region 必需） aliyun hitsdb get-lindorm-instance-list --region cn-shanghai # 查询全地域实例概览（无需 --region） aliyun hitsdb get-instance-summary # 查询所有地域 aliyun hitsdb describe-regions ``` **关键字段说明**： | 字段 | 含义 | 常见值 | |------|------|--------| | InstanceId | 实例 ID | `ld-xxx` | | InstanceAlias | 实例别名 | 用户自定义名称 | | InstanceStatus | 实例状态 | `ACTIVATION`（运行中）
`CREATING`（创建中）
`STOPPED`（已停止） | | PayType | 付费类型 | `POSTPAY`（按量）
`PREPAY`（包年包月） | | RegionId | 地域 ID | `cn-shanghai` | | ZoneId | 可用区 ID | `cn-shanghai-e` | | NetworkType | 网络类型 | `vpc` | --- ### 流程 2：查询实例详情 **适用场景**：用户想了解某个实例的完整配置信息。 **执行命令**： ```bash aliyun hitsdb get-lindorm-instance --instance-id ``` **参数说明**： - `--instance-id`：实例 ID（必填） - `--region`：地域 ID（可选，根据 instance-id 自动定位） **关键字段说明**： | 分类 | 字段 | 含义 | |------|------|------| | **基本** | InstanceId / InstanceAlias / InstanceStatus / CreateTime / ExpireTime | 实例 ID、别名、状态、创建时间、到期时间 | | **网络** | VpcId / VswitchId / NetworkType | VPC、交换机、网络类型 | | **存储** | InstanceStorage / DiskCategory / DiskUsage / ColdStorage | 存储容量(GB)、磁盘类型、使用率(%)、冷存储容量 | | **引擎** | EngineList / EnableLTS / EnableSearch | 引擎列表、时序/搜索开关 | --- ### 流程 3：查询实例引擎列表 **适用场景**：用户想知道实例开了哪些引擎、每个引擎的规格和版本。 **执行命令**： ```bash aliyun hitsdb get-lindorm-instance-engine-list --instance-id ``` **关键字段说明**： | 字段 | 含义 | |------|------| | EngineType | 引擎类型，详见 SKILL.md →「引擎类型」 | | Version | 当前版本 | | LatestVersion | 最新可升级版本 | | CpuCount | CPU 核心数 | | MemorySize | 内存大小（GB） | | CoreCount | 节点数量 | --- ### 流程 4：查询存储详情 **适用场景**：用户想了解存储使用情况、冷热分层。 **执行命令**（根据版本选择）： ```bash # V1 实例 aliyun hitsdb get-lindorm-fs-used-detail --instance-id # V2 实例 aliyun hitsdb get-lindorm-v2-storage-usage --instance-id ``` **关键字段说明**： **V1 实例**（`get-lindorm-fs-used-detail`）： | 字段 | 含义 | |------|------| | FsCapacity | 文件引擎总容量（bytes） | | FsCapacityHot / FsCapacityCold | 热/冷存储容量（bytes） | | FsUsedHot / FsUsedCold | 热/冷存储已使用（bytes） | | FsUsedOnLindormTable | Lindorm 宽表已使用量 | | FsUsedOnLindormTableData | 宽表数据量 | | FsUsedOnLindormTableWAL | WAL 日志量 | **V2 实例**（`get-lindorm-v2-storage-usage`）： | 字段 | 含义 | |------|------| | UsageByDiskCategory[] | 按磁盘类型的使用详情数组 | | └ diskType | 磁盘类型（`PerformanceCloudStorage` / `CapacityCloudStorage`） | | └ capacity | 容量（bytes） | | └ used | 已使用（bytes） | | └ usedLindormTable | 宽表已使用 | | └ usedLindormTsdb | 时序已使用 | | CapacityByDiskCategory[] | 按磁盘类别的容量信息数组 | | └ category | 类别（`PERF_CLOUD_ESSD_PL1` / `REMOTE_CAP_OSS` 等） | | └ capacity | 容量（GB） | --- ## 扩缩容知识 **⚠️ 只读 Skill 不执行扩缩容变更命令**，以下为知识告知，引导用户在控制台操作。 ### 扩容方式对比 | 瓶颈类型 | 方案 | 生效时间 | 业务影响 | |---------|------|---------|---------| | 存储不足 | 存储扩容（在线） | 5-10 分钟 | 无影响 | | QPS 不足 | 增加节点数（水平扩展） | 10-20 分钟 | 无影响 | | 单查询延迟高 | 升级节点规格（垂直扩展） | ~30 分钟（滚动重启） | 建议低峰操作 | 操作路径：Lindorm 控制台 → 实例详情 → 变配 ### 扩缩容约束 - 缩容需满足：已使用空间 < 目标容量 - 24 小时内最多变配 3 次，两次间隔至少 1 小时 - 扩容失败（库存不足）时可换可用区或换规格 ### 官方文档 - 管理存储空间：https://help.aliyun.com/zh/lindorm/user-guide/manage-storage-space/ - 变更容量型云存储容量：https://help.aliyun.com/zh/lindorm/user-guide/expand-cold-storage - 计费模式说明：https://help.aliyun.com/zh/lindorm/product-overview/billing --- ## 缺参处理 | 缺参 | 策略 | |------|------| | 缺 region | 默认查询 `cn-shanghai`，主动告知本次查询地域；用户说"所有地域"时先用 `get-instance-summary` | | 缺 instance-id | 先列出实例列表，让用户选择 | --- ## 错误处理 | 错误 | 原因 | 引导 | |------|------|------| | 实例不存在 | 实例 ID 错误或已释放 | 用 `get-lindorm-instance-list` 确认实例 ID | | 地域不匹配 | 实例在其他地域 | 提示用户指定正确地域 | | 权限不足 | AK 无 Lindorm 权限 | 需要 `AliyunLindormReadOnlyAccess` 权限 | --- ## 关联场景 - 扩容前性能分析 → `monitoring-guide.md` - 存储使用详情 → `storage-analysis.md` - 扩容后监控设置 → `monitoring-guide.md` FILE:references/02-ops/monitoring-guide.md # 监控与报警场景覆盖 Lindorm 监控数据查询、指标说明和报警配置。 ## 触发条件 - "CPU 使用率多少？" - "最近 3 小时的 CPU 趋势" - "怎么配置报警？" - "存储快满了，能设置自动通知吗？" --- ## 查询监控数据 ### 查询最新数据 ```bash aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name \ --dimensions '[{"instanceId":""}]' ``` **返回值说明**： - `Datapoints` 是 JSON **字符串**（不是数组），需要二次解析 - 每个数据点含 `instanceId`、`host`（节点名，如 table-1/search-1/zk-1）、`userId`、`timestamp`、`Average`/`Maximum`/`Minimum` - 一个实例会返回**多个数据点**（每个节点一个），需要聚合或筛选 host ### 查询历史趋势 ```bash aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name \ --dimensions '[{"instanceId":""}]' \ --start-time "" \ --end-time "" \ --period ``` **返回值说明**： - `Datapoints` 同样是 JSON 字符串，需二次解析 - 按 period 聚合后无 `host` 维度，返回全实例级别的聚合值 - 每个数据点含 `timestamp`、`Average`/`Maximum`/`Minimum` **参数**： - `--namespace`：固定 `acs_lindorm` - `--metric-name`：见下方指标分类，V2 实例部分指标无数据或需换算 - `--dimensions`：JSON 数组格式，必须指定 `instanceId` - `--start-time` / `--end-time`：时间格式见 SKILL.md →「时间格式」 **period 建议**： | 时间范围 | period | 说明 | |---------|--------|------| | ≤ 1 小时 | 60 | 1 分钟粒度 | | ≤ 24 小时 | 300 | 5 分钟粒度 | | > 24 小时 | 3600 | 1 小时粒度 | **相对时间处理**：用户说"最近 3 小时"时，先执行 `date "+%Y-%m-%d %H:%M:%S"` 获取当前时间，再计算 start/end。默认时间范围：最近 1 小时。 **数据保留**：云监控最多保留 30 天，更长周期需开通日志服务存储。 --- ## 指标说明 > 统一使用**无前缀指标**（如 `cpu_idle`），兼容性最佳。`lindorm_multi_` 前缀指标仅 `lindorm_multizone` 实例可用，其他实例类型不可用。 ### CPU 指标 | 指标 | 描述 | 单位 | 正常范围 | 告警阈值 | |------|------|------|---------|---------| | `cpu_idle` | CPU 空闲率 | % | > 20% | < 20% | | `cpu_user` | CPU 用户使用率 | % | < 80% | > 80% | | `cpu_system` | CPU 系统使用率 | % | < 30% | > 30% | | `cpu_wio` | CPU IO 等待 | % | < 30% | > 30% | CPU 空闲率 < 20%：CPU 瓶颈；cpu_wio > 30%：磁盘 IO 瓶颈 > **CPU + Load 综合判断**：Load > CPU 核数 = 处理排队、亚健康状态；CPU 利用率不高但 Load 偏高 = 磁盘使用率过高（与 cpu_wio 配合判断） ### 内存指标 | 指标 | 描述 | 单位 | V1 | V2 | |------|------|------|----|----| | `mem_used_percent` | 内存使用率 | % | ✅ | ⚠️ 无数据 | | `mem_total` | 内存总量 | bytes | ✅ | ✅ | | `mem_free` | 空闲内存 | bytes | ✅ | ✅ | | `mem_buff_cache` | 缓存大小 | bytes | ✅ | ✅ | V2 内存使用率需用 `1 - mem_free / mem_total` 计算。 > **Java 内存特性**：Lindorm 与 HBase 均为 Java 实现，70%-85% 内存使用率是健康常态（JVM BlockCache/MemStore/HDFS 页缓存），92% 以上才需关注。不建议对 80% 设置报警。 > > **宽表引擎堆内存报警**：宽表计算节点内存使用比率 ≥ 85%~90% 且持续 30~60 分钟时建议报警。堆内存短期波动是正常的（GC 会回收），只有持续过高才需关注。 ### QPS 指标 | 指标 | 描述 | 单位 | |------|------|------| | `read_ops` | 读请求量 | ops/s | | `write_ops` | 写请求量 | ops/s | | `get_num_ops` | Get 每秒请求数 | ops/s | | `put_num_ops` | Put 每秒请求数 | ops/s | | `scan_num_ops` | Scan 每秒请求数 | ops/s | > **QPS 指标解读**： > - BatchGet 无论包含多少行都只算一次点查调用，因此使用 BatchGet 时 avg RT 会高于单行 Get > - Scan 请求会被拆分为子调用以流式返回，Scan QPS ≠ 实际 Scan 请求数，Scan RT 是每个子调用的平均耗时 ### 延迟指标 | 指标 | 描述 | 单位 | 正常范围 | 告警阈值 | V2 | |------|------|------|---------|---------|-----| | `read_rt` | 读平均延迟 | ms | < 10ms | > 50ms | ✅ | | `write_rt` | 写平均延迟 | ms | < 10ms | > 50ms | ✅ | | `get_rt_avg` | Get 平均延迟 | ms | < 10ms | > 50ms | ✅ | | `put_rt_avg` | Put 平均延迟 | ms | < 10ms | > 50ms | ✅ | | `get_rt_p99` | Get P99 延迟 | ms | < 50ms | > 100ms | ⚠️ 无数据 | | `put_rt_p99` | Put P99 延迟 | ms | < 50ms | > 100ms | ⚠️ 无数据 | | `scan_rt_avg` | Scan 平均延迟 | ms | < 50ms | > 200ms | ✅ | | `scan_rt_p99` | Scan P99 延迟 | ms | < 200ms | > 500ms | ✅ | ### 存储指标 | 指标 | 描述 | 单位 | 告警阈值 | V2 | |------|------|------|---------|-----| | `hot_storage_used_percent` | 热存储使用率 | % | > 80% | ⚠️ 无数据 | | `hot_storage_used_bytes` | 热存储使用量 | bytes | — | ✅ | | `cold_storage_used_percent` | 冷存储使用率 | % | > 80% | ⚠️ 无数据 | | `cold_storage_used_bytes` | 冷存储使用量 | bytes | — | ✅ | | `storage_used_percent` | 总存储使用率 | % | > 80% | ⚠️ 无数据 | | `storage_used_bytes` | 总存储使用量 | bytes | — | ✅ | V2 存储使用率需通过 `get-lindorm-v2-storage-usage` API 获取，云监控无数据。 > ⚠️ **存储硬限制**：热存储或冷存储水位 ≥ 95% 时，系统自动禁止数据写入。建议容量告警线设置在 75%~80%，提前扩容避免影响业务。 ### 网络与负载指标 | 指标 | 描述 | 单位 | |------|------|------| | `bytes_in` | 网络流入 | bytes/s | | `bytes_out` | 网络流出 | bytes/s | | `load_one` | 1 分钟平均负载 | — | | `load_five` | 5 分钟平均负载 | — | | `handler_queue_size` | Handler 队列长度 | — | | `compaction_queue_size` | Compaction 队列长度 | — | > **Compaction 队列判断**：长期稳定在某值 = 健康（白天高峰积压、晚上低谷自动处理是正常周期）；持续上涨且无下降趋势 = 资源不足需扩容。长期积压会导致文件数增多、读 RT 升高，严重时出现反压写导致写 RT 增加甚至超时。 > **网络/磁盘限流**：不同规格实例有不同的网络带宽和磁盘 IOPS 上限（参见[实例规格族](https://help.aliyun.com/zh/lindorm/product-overview/instance-types)和[块存储性能](https://help.aliyun.com/zh/block-storage/product-overview/block-storage-performance)），读写流量超过云盘带宽上限会限流导致业务受损。 ### 引擎专用指标 | 引擎 | 指标前缀 | 关键指标 | |------|---------|---------| | LSQL（宽表SQL） | `lql_` | `lql_select_ops`、`lql_upsert_ops`、`lql_select_avg_rt`、`lql_select_p99_rt`、`lql_connection` | | 搜索引擎 | `search_` | `search_cpu_idle`、`search_mem_used_percent`、`search_select_1minRate`、`search_select_p99_rt` | | 时序引擎 | `tsdb_` | `tsdb_datapoints_added`、`tsdb_disk_used`、`tsdb_jvm_used_percent` | | 文件引擎 | `Lindorm_File_` | `Lindorm_File_ReadBandwidth`、`Lindorm_File_WriteBandwidth`、`Lindorm_File_ReadLatency`、`Lindorm_File_WriteLatency` | 引擎专用指标需对应引擎已开通才返回数据。完整 323 个指标可通过 `aliyun cms describe-metric-meta-list --namespace acs_lindorm` 查询。 ### 业务词到指标映射 | 用户说 | 指标 | |--------|------| | CPU 使用率 | `cpu_idle`（空闲率，使用率 = 100 - cpu_idle） | | 内存使用率 | `mem_used_percent`（V1）/ `1 - mem_free / mem_total`（V2） | | QPS | `read_ops` + `write_ops` | | 延迟/RT | `read_rt` 或 `write_rt` | | P99 延迟 | `get_rt_p99` / `put_rt_p99`（V1）/ —（V2 无数据） | | 存储使用率 | `hot_storage_used_percent`（V1）/ `get-lindorm-v2-storage-usage` API（V2） | | 网络流量 | `bytes_in` + `bytes_out` | | 负载 | `load_one` | --- ## 宽表引擎指标解读 ### Region 数量建议每个 Region 都占用元数据内存，数量过多会导致内存不足。 | 机器内存 | 单机建议 Region 数 | |---------|-------------------| | 8 GB | < 500 | | 16 GB | < 1000 | | 32 GB | < 2000 | | 64 GB | < 3000 | | 128 GB | < 5000 | 可通过宽表计算节点内存使用量 / 内存总量判断是否存在内存不足问题。减少 Region 数的方法：减少表数量、减少建表时预分区个数。 ### 其他宽表指标解读 | 指标 | 含义 | 判断 | |------|------|------| | HandlerQueue 长度 | 请求排队数 | > 0 = 请求排队，服务器资源无法承载当前请求量，建议升级配置增加 CPU | | Compaction 队列长度 | Compaction 任务排队数 | 长期稳定某值 = 健康；持续上涨 = 资源不足需扩容。长期积压会导致文件数增多、读 RT 升高，严重时反压写导致写 RT 增加甚至超时 | | Region 平均文件数 | 分片内平均文件数 | 越多读 RT 越大；文件总数过多可能导致 Full GC 或 OOM | | Region 最大文件数 | 单 Region 最大文件数 | 超限会反压写导致写超时（具体限制见[数据请求的限制](https://help.aliyun.com/zh/lindorm/product-overview/quotas-and-limits#p-fq0-foz-ocy)） | | 写流量（KB/s） | 写入宽表引擎的流量 | 列转 KeyValue 形式，实际写入量大于业务写入量。写入吞吐过大可能导致 Compaction 积压 | ### 写入吞吐建议写入吞吐过大可能导致 Compaction 积压，影响实例稳定性。 | 配置 | 建议写入吞吐 | |------|-------------| | 4C8G | < 5 MB/s | | 8C16G | < 10 MB/s | | 16C32G | < 30 MB/s | | 32C64G | < 60 MB/s | 实际使用时结合 `compaction_queue_size` 和 Region 平均文件数综合判断。 --- ## 报警配置 **⚠️ 安全边界：Agent 只查询数据、提供建议，不直接创建报警规则**（涉及联系人手机号/邮箱等敏感信息且需验证） ### 报警规则类型 | 类型 | 说明 | 示例 | |------|------|------| | **阈值报警** | 指标数值越界触发 | CPU 使用率 > 80% 持续 5 分钟 | | **事件报警** | 系统事件触发 | NodeDown（节点宕机）、RegionError（Region 异常） | 事件报警无法通过指标阈值捕获，是运维关键能力。 ### 配置路径 1. **Lindorm 控制台**：实例详情 → 告警管理 → 创建报警规则 2. **云监控控制台**：报警服务 → 报警规则 → 创建报警规则 → 选择产品"Lindorm" ### 报警规则关键参数 | 参数 | 说明 | 可选值 | |------|------|--------| | 统计周期 | 数据聚合粒度 | 60s / 300s / 900s / 1800s / 3600s / 86400s | | 统计方法 | 数据聚合方式 | Average / Maximum / Minimum / Sum | | 比较运算符 | 阈值比较方式 | >= / > / <= / < / != | | 连续次数 | 连续满足条件的次数 | 1-100（推荐 1-3） | | 静默期 | 触发后的通知静默时间 | 5min - 24h | | 报警级别 | 三级独立阈值 | Critical / Warn / Info | > **cpu_idle 报警方向**：cpu_idle 是空闲率，报警条件应设为 `cpu_idle ≤ 阈值`（即使用率 ≥ 100 - 阈值） ### 推荐阈值 | 指标 | V1 | V2 | Info（提醒） | Warn（警告） | Critical（严重） | |------|----|----|-------------|-------------|----------------| | CPU 使用率 | `cpu_idle ≤ 30` | `cpu_idle ≤ 30` | ≤ 30%（持续 30min） | ≤ 20%（持续 5min） | ≤ 5%（持续 3min） | | 内存使用率 | `mem_used_percent` | `1 - mem_free/mem_total` | ≥ 85%（持续 30min） | ≥ 92%（持续 5min） | — | | 热存储使用率 | `hot_storage_used_percent` | `get-lindorm-v2-storage-usage` API | ≥ 70% | ≥ 80% | ≥ 90% | | P99 延迟 | `get_rt_p99` | —（无数据） | ≥ 50ms | ≥ 100ms | ≥ 200ms | > V2 存储报警：云监控无 `hot_storage_used_percent` / `storage_used_percent` 数据，需通过 `get-lindorm-v2-storage-usage` API 获取，或在控制台配置基于存储空间的报警规则。 ### 通知渠道 | 渠道 | 说明 | 适用级别 | |------|------|---------| | 短信 | 手机号需验证 | Warn / Critical | | 邮件 | 邮箱需验证 | Info / Warn / Critical | | 钉钉 | 群机器人 Webhook | Warn / Critical | | 电话 | 语音报警 | Critical | | Webhook | 自定义 HTTP 回调 | 全级别 | | 阿里云 App | App 内推送 | Info / Warn / Critical | 联系人管理路径：云监控控制台 → 通知管理 → 联系人/联系组 ### 常见报警问题 - **未收到通知**：检查联系人是否已验证、报警条件是否真正触发、通知时段是否覆盖、通知策略是否关联规则 - **报警过多**：提高阈值、增加持续时间、配置静默期（5min-24h）、使用复合条件（多指标同时满足才报警） --- ## 错误处理 | 错误 | 原因 | 引导 | |------|------|------| | 无数据点 | 时间范围内实例未运行或无流量 | 调整时间范围或检查实例状态 | | 权限不足 | AK 无云监控权限 | 需要 `AliyunCloudMonitorReadOnlyAccess` | | 指标不存在 | 指标名错误或该实例类型不支持 | 先验证指标可用性 | --- ## 官方文档 - 报警配置：https://help.aliyun.com/zh/lindorm/user-guide/manage-alerts - 创建报警规则：https://help.aliyun.com/zh/lindorm/user-guide/create-an-alert-rule - 监控指标说明：https://help.aliyun.com/zh/lindorm/user-guide/instance-monitoring - 监控报警最佳实践：https://help.aliyun.com/zh/lindorm/user-guide/monitoring-alarm-best-practices --- ## 关联场景 - 性能诊断后排查具体慢SQL → `slow-query-analysis.md` - 存储分析 → `storage-analysis.md` - 扩缩容 → `instance-management.md` FILE:references/02-ops/slow-query-analysis.md # 慢查询分析场景当用户询问"有没有慢查询"、"查询慢是什么原因"、"怎么优化查询"、"怎么开启慢日志"时，按本指南执行。 ## 触发条件用户的典型表达： - "有没有慢查询日志？" - "怎么开启慢日志/慢查询记录" - "查询慢，帮我分析原因" - "Top 10 最慢的查询" - "怎么优化查询性能？" ## 核心原则 **证据驱动的诊断流程**： 1. **先收集最小必要信息**（引擎类型、时间窗口、操作类型） 2. **用监控确认现象**（延迟指标趋势） 3. **要求用户提供证据**（慢 SQL、执行计划、慢日志） 4. **基于证据给针对性建议**（而非通用优化大全） 5. **提供可执行的优化代码**（从官方文档提取最佳实践） > ⚠️ **禁止行为**：在缺少具体慢 SQL/执行计划/慢日志证据时，直接给出"5 类优化方案"或概率判断。 --- ## 慢查询日志管理 > **版本要求**： > - 实时定位/终止慢查询：宽表引擎 **2.6.3+**，Lindorm SQL **2.6.6+** > - 慢查询回溯（慢日志记录）：宽表引擎 **2.8.2.13+** > > 以下 SQL 均通过 Lindorm SQL 客户端执行（MySQL Workbench / DBeaver / Navicat / ClusterManager 均可），**立即生效，无需重启实例**。 ### 1. 实时定位当前慢查询 ```sql -- 查看当前正在执行的所有查询（含查询 ID / UUID） SHOW PROCESSLIST; ``` **说明**：返回结果中的 `ID` 字段为 UUID，用于后续终止操作。 ### 2. 终止慢查询 ```sql -- 终止指定查询（ID 从 SHOW PROCESSLIST 获取） KILL QUERY '581f9ab8-68af-4c93-b73a-eb99679ed192'; ``` ### 3. 开启慢查询回溯（Slow Log 记录） **Step 1：开启功能** ```sql ALTER SYSTEM SET SLOW_QUERY_RECORD_ENABLE = true; ``` **Step 2：设置慢查询阈值（单位：毫秒）** ```sql -- 示例：超过 10 秒记录（按业务需要调整，不建议设置过小） ALTER SYSTEM SET SLOW_QUERY_TIME_MS = 10000; ``` **Step 3：查询慢日志视图** ```sql -- 查看最近 10 条慢查询 SELECT * FROM lindorm._slow_query_ LIMIT 10; -- 按时间筛选（query_start_time 为 Unix 毫秒时间戳） SELECT COUNT(sql_query_s) AS num FROM lindorm._slow_query_ WHERE query_start_time >= 1680152319000; ``` **慢日志视图字段说明**： | 字段名 | 说明 | |--------|------| | `query_start_time` | 查询请求的发起时间（Unix 毫秒时间戳） | | `query_id` | 查询请求 ID | | `sql_query_id` | 查询请求的 SQL 语句（无 SQL 则为空） | | `sql_query_s` | SQL 语句内容（无 SQL 则为空） | | `duration_i` | 查询执行时间 | | `status_s` | 查询最终状态（成功/失败） | | `ip_s` | 发送查询请求的 IP 地址 | | `server_s` | 查询执行的节点 | | `query_s` | 执行的内部查询请求语句 | > ⚠️ **注意事项**： > - 慢日志记录默认只保留 **1 小时** > - 频繁记录慢查询对实例性能有一定影响，性能敏感场景不宜将阈值设置过小 > - 视图名 `lindorm._slow_query_` 固定，不可修改 **官方文档**：https://help.aliyun.com/zh/lindorm/developer-reference/slow-query-diagnostics --- ## 执行流程 ### Step 0：强制收集最小信息（缺参则追问，不下结论） **必须确认的信息**： | 信息项 | 为什么必须 | 追问话术 | |--------|-----------|---------| | **引擎类型** | 宽表 SQL / HBase API / 时序 / 搜索引擎的优化策略完全不同 | "您使用的是哪个引擎？宽表 SQL、HBase API、时序引擎还是搜索引擎？" | | **发生时间窗口** | 需要确定查询趋势和关联事件 | "慢查询大概从什么时候开始？持续多久了？" | | **慢的操作类型** | 读/写/Scan/聚合的排查方向不同 | "是查询慢还是写入慢？具体的操作类型是什么？" | | **具体 SQL/操作**（如有） | 没有具体语句无法给出针对性建议 | "能否提供一条具体的慢 SQL 或操作代码？" | **缺参时的标准回复**： ``` 我需要先了解一些信息，才能帮您准确诊断： 1. 您使用的是哪个引擎？（宽表 SQL / HBase API / 时序 / 搜索） 2. 慢查询大概从什么时候开始？ 3. 是读操作慢还是写操作慢？ 4. 能否提供一条具体的慢 SQL 或操作示例？有了这些信息，我可以帮您： - 查询相关监控指标确认问题 - 分析具体的执行计划 - 给出针对性的优化建议 ``` --- ### Step 1：用监控确认现象（avg vs p99 + 趋势） **Agent 先查询延迟指标**： ```bash # P99 延迟（更能反映慢请求） aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name get_rt_p99 \ --dimensions '[{"instanceId":""}]' \ --start-time "" \ --end-time "" \ --period 60 # 平均延迟 aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name read_rt \ --dimensions '[{"instanceId":""}]' \ --start-time "" \ --end-time "" \ --period 60 ``` **Agent 分析后给客观描述**（不下结论、不给概率）： ``` 【延迟指标观察】实例 ld-xxx（最近 1 小时） - 平均延迟：35ms - P99 延迟：180ms - P99 与平均值差距：5.1 倍【客观描述】延迟分布存在明显长尾，部分请求耗时显著高于平均水平。【下一步】要确定具体原因，需要查看具体的慢查询证据。请选择以下任一方式：方式 1（推荐）：提供具体慢 SQL - 如果您知道哪条 SQL 慢，请提供 SQL 文本 - 我可以帮您分析执行计划方式 2：查看 ClusterManager 慢查询日志 - 路径：控制台 → 实例 → ClusterManager → 查询分析 → 慢查询日志 - 找到 Top 慢查询后告诉我查询特征方式 3：提供应用侧观察 - 您的应用日志中是否有具体报错或超时的操作？ ``` --- ### Step 2：要求用户提供证据（满足其一即可） **证据类型**（至少提供一种）： | 证据类型 | 适用场景 | 如何获取 | |---------|---------|---------| | **慢 SQL + EXPLAIN** | 宽表 SQL 慢查询 | 用户提供 SQL 文本，Agent 指导执行 EXPLAIN | | **ClusterManager 慢日志** | 所有引擎 | 控制台 → ClusterManager → 查询分析 → 慢查询日志 | | **HBase Scan/Get 参数** | HBase API 慢查询 | 用户提供代码中的 Scan/Get 配置 | | **应用错误日志** | 有明确报错场景 | 应用侧的超时/错误日志 | **未提供证据时的标准回复**： ``` 目前我能看到延迟分布存在长尾，但无法确定具体原因。请提供以下任一证据，我才能给出针对性优化建议：选项 A：一条具体的慢 SQL（如果您知道是哪条）选项 B：ClusterManager 中的 Top 慢查询截图/文本选项 C：您的应用日志中相关的错误信息 ⚠️ 注意：在没有具体证据的情况下，我不建议直接应用通用优化方案，因为不同原因（全表扫描、热点、大查询等）的优化方向可能完全不同。 ``` --- ### Step 3：基于证据分类输出（只给命中的 1-2 条策略） **收到证据后，根据证据类型选择对应优化方向**： | 证据特征 | 问题类型 | 优化方向 | |---------|---------|----------| | EXPLAIN 显示 TABLE FULL SCAN，扫描行数大（> 100万） | 全表扫描 | 添加 RowKey 范围条件、创建二级索引 | | 单行查询耗时长，返回数据量大（> 1MB） | 查询大量列 | 只 SELECT 需要的列，避免 `SELECT *` | | 少量 RowKey 延迟极高，CPU 节点分布不均 | RowKey 热点 | RowKey 加盐/反转分散，创建全局索引 | | 批量 Get/Scan 超时或内存溢出 | 大数据量批量查询 | 分批查询（batchSize 50-100），SQL 用 LIMIT 分页 | | 查询非主键列性能极差，随数据量线性变慢 | 缺少索引 | 创建二级索引（`CREATE INDEX`）或全局索引（`CREATE GLOBAL INDEX`） | > 根据用户提供的证据，**只输出命中的 1-2 条策略**，并给出对应的可执行 SQL/代码示例。 --- ### Step 4：告知用户如何获取证据（如用户无法提供） **给出精确路径，不让用户自己摸索**： ``` 【查看具体慢查询日志】虽然我已给您提供了通用优化方案，但如果您想查看**具体哪条查询最慢**，请通过 ClusterManager 查看： 📍 确路径： 1. 登录控制台：https://lindorm.console.aliyun.com/ 2. 点击实例 ID "ld-xxx" 进入实例详情 3. 左侧菜单：数据库连接 → 点击"通过 ClusterManager 访问" 4. 进入 ClusterManager → 查询分析 → 慢查询日志 5. 查看： - Top 10 最慢查询 - 查询耗时、扫描行数 - 查询发生时间【查看到慢查询后】告诉我具体的查询类型（Scan/Get/RowKey 特征），我来给出针对性优化方案。 📚 ClusterManager 使用文档： https://help.aliyun.com/zh/lindorm/user-guide/log-in-to-the-cluster-management-system ``` --- ### Step 5：综合性能诊断（有证据后） **Agent 结合延迟指标 + CPU/内存/QPS，给出综合诊断**： ```bash # 查询 CPU 空闲率 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":""}]' # 查询内存使用率 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name mem_used_percent \ --dimensions '[{"instanceId":""}]' # 查询 QPS aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name read_ops \ --dimensions '[{"instanceId":""}]' ``` **有证据后的综合分析示例**： ``` 【综合诊断】实例 ld-xxx（最近 1 小时） 📊 性能指标： - P99 延迟：180ms - 平均延迟：35ms - P99/avg 倍数：5.1x - CPU 空闲率：65% - 内存使用率：55% 🔍 用户提供的证据： - 引擎类型：宽表 SQL - 慢 SQL：SELECT * FROM orders WHERE status = 'pending' - EXPLAIN 显示：TABLE FULL SCAN ✅ 诊断结论：全表扫描导致的慢查询。表 orders 没有 status 列的索引，查询需要扫描全表。 💡 针对性优化方案： 1. 【推荐】创建二级索引： CREATE INDEX idx_status ON orders(status) INCLUDE (order_id, amount); 2. 【临时】限制返回行数： SELECT * FROM orders WHERE status = 'pending' LIMIT 100; 3. 【长期】如 status 选择性低，考虑使用搜索索引支持多条件查询请确认优化方案后，我可以提供完整的执行语句。 ``` --- ## 优化方案参考当用户提供了具体证据后，Agent 从以下官方文档提取针对性优化建议： | 证据类型 | 参考文档 | 提取内容 | |---------|---------|---------| | 全表扫描 | [SQL 常见问题](https://help.aliyun.com/zh/lindorm/developer-reference/sql-faq) | 低效查询规避、索引使用、最左匹配原则 | | 热点问题 | [如何设计宽表主键](https://help.aliyun.com/zh/lindorm/user-guide/how-to-design-the-rowkey-field) | 加盐、反转、分区策略、避免热点 | | 大查询 | [游标分页](https://help.aliyun.com/zh/lindorm/introduction-to-the-use-of-cursor-paging) | LIMIT 分页、游标分页、避免内存溢出 | | 索引选择 | [二级索引](https://help.aliyun.com/zh/lindorm/user-guide/high-performance-native-secondary-indexes) | 二级索引 vs 搜索索引选择 | > **原则**：只提取与用户证据匹配的方案，不要一次性给出所有优化方案。 --- ## 官方文档索引（供 Agent 参考） | 场景 | 官方文档 | 预期提取内容 | |------|---------|-------------| | **慢查询诊断** | [慢查询诊断](https://help.aliyun.com/zh/lindorm/developer-reference/slow-query-diagnostics) | 慢查询定位方法、诊断工具、优化建议 | | **二级索引** | [二级索引](https://help.aliyun.com/zh/lindorm/user-guide/high-performance-native-secondary-indexes) | 索引类型、创建语法、使用场景 | | **全局索引** | [CREATE INDEX](https://help.aliyun.com/zh/lindorm/developer-reference/te-create-index) | GLOBAL 关键字、索引类型区别、语法参数 | | **主键/RowKey 设计** | [如何设计宽表主键](https://help.aliyun.com/zh/lindorm/user-guide/how-to-design-the-rowkey-field) | 加盐、反转、分区策略、避免热点 | | **索引创建总览** | [CREATE INDEX 索引对比](https://help.aliyun.com/zh/lindorm/developer-reference/te-create-index) | 二级索引 vs 搜索索引 vs 列存索引选择 | | **ClusterManager** | [ClusterManager 使用](https://help.aliyun.com/zh/lindorm/user-guide/log-in-to-the-cluster-management-system) | 访问路径、慢查询日志查看 | FILE:references/02-ops/storage-analysis.md # 存储分析场景当用户关心 Lindorm 实例的存储使用情况、冷热数据分布、存储增长趋势时，按本指南执行。 ## 触发条件用户的典型表达： - "磁盘还剩多少？" - "存储快满了吗？" - "冷热存储分别用了多少？" - "存储增长趋势如何？" - "ld-xxx 使用了多少存储？" - "热存储使用率是多少？" ## 核心能力 - **存储详情查询**：总容量、已用容量、冷热分布 - **存储使用率监控**：热存储/冷存储使用率趋势 - **存储增长分析**：历史趋势、增长速率 - **冷热分层建议**：何时启用冷存储、冷热数据迁移策略 ## 执行流程 ### 流程 1：获取存储详情（快照数据） **适用场景**：用户想快速了解当前存储使用情况。 **执行命令**： ```bash # V1 实例 aliyun hitsdb get-lindorm-fs-used-detail \ --instance-id # V2 实例（instanceType=lindorm_v2） aliyun hitsdb get-lindorm-v2-storage-usage \ --instance-id ``` **输出呈现**：先给结论性摘要： - 总容量（热+冷） - 已用容量（热+冷） - 使用率（%） - 冷热分布占比 - 告警状态（是否接近阈值）再按需展开详细字段。 **关键字段说明**： **V1 实例**（`get-lindorm-fs-used-detail`）： | 字段 | 含义 | 单位 | |------|------|------| | `FsCapacity` | 文件引擎总容量 | bytes | | `FsCapacityHot` | 热存储容量 | bytes | | `FsCapacityCold` | 冷存储容量 | bytes | | `FsUsedHot` | 热存储已使用 | bytes | | `FsUsedCold` | 冷存储已使用 | bytes | | `FsUsedOnLindormTable` | Lindorm 宽表已使用 | bytes | | `FsUsedOnLindormTableData` | 宽表数据量 | bytes | | `FsUsedOnLindormTableWAL` | WAL 日志量 | bytes | **V1 计算公式**： - **总容量** = `FsCapacityHot` + `FsCapacityCold` - **已用容量** = `FsUsedHot` + `FsUsedCold` - **存储使用率** = (已用容量 / 总容量) × 100% - **热存储使用率** = (`FsUsedHot` / `FsCapacityHot`) × 100% - **冷存储使用率** = (`FsUsedCold` / `FsCapacityCold`) × 100% **V2 实例**（`get-lindorm-v2-storage-usage`）： | 字段 | 含义 | 单位 | |------|------|------| | `UsageByDiskCategory[]` | 按磁盘类型的使用详情数组 | — | | └ `diskType` | 磁盘类型 | `PerformanceCloudStorage`（热）/ `CapacityCloudStorage`（冷） | | └ `capacity` | 磁盘容量 | bytes | | └ `used` | 已使用量 | bytes | | └ `usedLindormTable` | 宽表已使用 | bytes | | └ `usedLindormTsdb` | 时序已使用 | bytes | | `CapacityByDiskCategory[]` | 按磁盘类别的容量信息 | — | | └ `category` | 类别 | `PERF_CLOUD_ESSD_PL1` / `REMOTE_CAP_OSS` 等 | | └ `capacity` | 容量 | GB | **V2 计算公式**： - **热存储使用率** = `PerformanceCloudStorage.used` / `PerformanceCloudStorage.capacity` × 100% - **冷存储使用率** = `CapacityCloudStorage.used` / `CapacityCloudStorage.capacity` × 100% - **总使用量** = Σ 各 diskType 的 `used` **示例输出**： ``` 【存储使用情况】实例 ld-uf6l5kr48wqm6rf1h 【总容量】800GB（热存储 500GB + 冷存储 300GB）【已用容量】520GB（65%） - 热存储已用：320GB（64%） - 冷存储已用：200GB（67%）【状态】⚠️ 热存储接近阈值（推荐 < 80%）【存储分布】 - Lindorm 宽表：480GB（数据 450GB + WAL 30GB） - 其他：40GB 【建议】热存储使用率较高，建议： 1. 检查是否可将历史数据迁移到冷存储 2. 考虑扩容热存储或启用自动冷热分层 📍 在控制台查看存储详情： 1. 控制台：https://lindorm.console.aliyun.com/ 2. 点击实例 ID "ld-xxx" 3. 左侧菜单：存储信息 4. 查看： - 总存储容量 - 热存储使用量/使用率 - 冷存储使用量/使用率 - 存储增长趋势（最近 7 天/30 天） 📍 在 ClusterManager 查看详细存储分析： 1. 控制台 → ld-xxx → 数据库连接 → "通过 ClusterManager 访问" 2. 存储分析 → 查看： - 表级存储占用 Top 10 - 列族存储分布 - 数据膨胀分析需要查看存储增长趋势吗？ ``` --- ### 流程 2：查询存储使用率（实时监控） **适用场景**：用户想查看最新的存储使用率（通过云监控）。 **执行命令**： ```bash # 热存储使用率 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name hot_storage_used_percent \ --dimensions '[{"instanceId":""}]' # 冷存储使用率 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name cold_storage_used_percent \ --dimensions '[{"instanceId":""}]' ``` **输出呈现**： - 当前热存储使用率 - 当前冷存储使用率 - 是否接近告警阈值（80%） --- ### 流程 3：查询存储历史趋势 **适用场景**：用户想分析存储增长趋势、预测何时需要扩容。 **执行命令**： ```bash # 热存储已使用量（过去 7 天，每小时 1 个点） aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name hot_storage_used_bytes \ --dimensions '[{"instanceId":""}]' \ --start-time "<7天前格式: YYYY-MM-DD HH:MM:SS>" \ --end-time "<当前时间格式: YYYY-MM-DD HH:MM:SS>" \ --period 3600 # 冷存储已使用量（过去 7 天，每小时 1 个点） aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name cold_storage_used_bytes \ --dimensions '[{"instanceId":""}]' \ --start-time "<7天前格式: YYYY-MM-DD HH:MM:SS>" \ --end-time "<当前时间格式: YYYY-MM-DD HH:MM:SS>" \ --period 3600 ``` **分析要点**： - 计算日均增长量（GB/天） - 预测存储耗尽时间（按当前增长速率） - 判断增长趋势（线性/指数/平稳） **示例输出**： ``` 【存储增长趋势】实例 ld-uf6l5kr48wqm6rf1h（过去 7 天）【热存储】 - 7 天前：280GB - 当前：320GB - 增长量：40GB（日均 5.7GB） - 趋势：线性增长 - 预测：按当前速率，热存储将在 32 天后达到 80% 阈值【冷存储】 - 7 天前：195GB - 当前：200GB - 增长量：5GB（日均 0.7GB） - 趋势：平稳【建议】 - 短期：热存储增长较快，建议 1 个月内扩容或启用自动冷热分层 - 长期：冷存储增长平稳，暂无压力如需更多细节，可参考官方存储管理指南： https://help.aliyun.com/zh/lindorm/user-guide/storage-management 📚 冷热分层配置指南： https://help.aliyun.com/zh/lindorm/user-guide/hot-and-cold-separation/ 需要帮您配置冷热分层策略吗？ ``` --- ## 存储相关监控指标 ### 热存储指标 | 指标名称 | 描述 | 单位 | 告警阈值 | |----------|------|------|----------| | `hot_storage_total_bytes` | 热存储总容量 | bytes | - | | `hot_storage_used_bytes` | 热存储已使用 | bytes | - | | `hot_storage_used_percent` | 热存储使用率 | % | > 80% | ### 冷存储指标 | 指标名称 | 描述 | 单位 | 告警阈值 | |----------|------|------|----------| | `cold_storage_total_bytes` | 冷存储总容量 | bytes | - | | `cold_storage_used_bytes` | 冷存储已使用 | bytes | - | | `cold_storage_used_percent` | 冷存储使用率 | % | > 80% | ### 其他存储指标 | 指标名称 | 描述 | 单位 | |----------|------|------| | `storage_total_bytes` | 存储空间总量 | bytes | | `storage_used_bytes` | 存储空间使用量 | bytes | | `storage_used_percent` | 存储空间使用比例 | % | | `table_hot_storage_used_bytes` | 宽表热存储使用量 | bytes | | `table_cold_storage_used_bytes` | 宽表冷存储使用量 | bytes | | `tsdb_hot_storage_used_bytes` | 时序热存储使用量 | bytes | | `tsdb_cold_storage_used_bytes` | 时序冷存储使用量 | bytes | --- ## 存储使用率阈值与告警 Lindorm 默认磁盘使用率阈值为 **80%**。 | 存储使用率 | 状态 | 影响 | 建议 | |-----------|------|------|------| | < 60% | ✅ 正常 | 无影响 | 持续监控 | | 60% - 80% | ⚠️ 关注 | 无影响 | 考虑扩容计划 | | 80% - 90% | ⚠️ 告警 | 写入性能下降 | 尽快扩容或清理数据 | | 90% - 95% | 🚨 严重告警 | 写入性能严重下降 | 立即扩容或清理数据 | | ≥ 95% | 🔴 系统禁止写入 | 系统自动禁止数据写入（硬限制） | 必须扩容后才能恢复写入 | --- ## 冷热分层优化建议 ### 何时启用冷存储？ | 场景 | 建议 | |------|------| | 历史数据访问频率低（< 1 次/天） | 启用冷存储，设置自动冷热分层策略 | | 热存储使用率 > 60% | 考虑将历史数据迁移到冷存储 | | 成本优化 | 冷存储成本仅为标准型云存储的 20%（约1/5），适合长期归档 | ### 开通冷存储（容量型云存储） > ⚠️ **警告**：开通过程中需要**滚动重启实例**，可能会导致部分业务的读写请求出现**延迟波动或连接中断**，建议在**业务低峰期**操作。 **前提条件：** - 实例存储类型为**本地 HDD 盘**时，**不支持**开通容量型云存储 - 云存储类型（性能型/标准型）实例支持开通 **控制台开通路径：** 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在页面左上角，选择实例所属的**地域** 3. 在实例列表页，单击**目标实例ID**或者目标实例所在行操作列的**管理** 4. 在左侧导航栏，选择**冷存储** 5. 单击**开通** 6. 设置**容量型云存储容量** 7. 阅读并勾选服务协议，单击**立即购买** **存储类型说明：** | 存储类型 | 用途 | 是否支持冷热分层 | |---------|------|-----------------| | 性能型云存储 | 热存储，低延迟（< 10ms） | ✅ 支持（需开通容量型作为冷存储） | | 标准型云存储 | 热存储，中等延迟 | ✅ 支持（需开通容量型作为冷存储） | | 容量型云存储 | 冷存储，低成本（标准型云存储的 20%） | ✅ 作为冷存储介质 | | 本地 HDD 盘 | 本地存储 | ❌ 不支持冷热分层 | > **注意**：容量型云存储与性能型/标准型云存储可以**并存**，无需变更现有存储类型。 ### 冷热分层策略 - **自动分层**：设置时间策略（如数据写入 30 天后自动转冷） - **手动分层**：通过 Lindorm 表属性配置冷热分层规则 - **查询优化**：冷数据查询延迟较高（通常 > 100ms），热数据查询延迟低（< 10ms） 📍 配置冷热分层： 1. 通过 Lindorm SQL： ```sql ALTER TABLE metrics SET COLD_DATA_AGE = 2592000; -- 30 天后转冷 ``` 2. 通过 HBase Shell： ```bash alter 'metrics', {NAME => 'cf', COLD_DATA_AGE => 2592000} ``` ### 冷存储性能说明 | 指标 | 热存储（性能型） | 冷存储（容量型） | |------|----------------|-----------------| | 查询延迟 | < 10ms | > 100ms | | 存储成本 | 基准 | 仅为标准型云存储的 20% | | 适用场景 | 高频访问 | 低频访问（< 1次/天） | | 读取 IOPS | 高 | 限流（每 25GiB 容量 1 IOPS） | 如需更多细节，可参考官方配置指南： https://help.aliyun.com/zh/lindorm/user-guide/hot-and-cold-separation/ 📚 冷热分离最佳实践： https://help.aliyun.com/zh/lindorm/user-guide/enable-cold-storage --- ## 缺参处理 ### 缺 instance-id **追问策略**：先用 `aliyun hitsdb get-instance-summary` 确认地域，再用 `aliyun hitsdb get-lindorm-instance-list --region ` 让用户选择实例。 ### 缺时间范围（存储趋势分析） **默认策略**：使用过去 7 天，并告知用户。 --- ## 错误处理 | 错误 | 原因 | 引导用户 | |------|------|----------| | **无存储详情** | 实例未开通文件引擎或实例状态异常 | 检查实例状态和引擎配置 | | **指标无数据** | 时间范围内无数据或指标名错误 | 调整时间范围或确认指标名 | | **权限不足** | Access Key 无 Lindorm 权限 | 提示需要 `AliyunLindormReadOnlyAccess` 权限 | --- ## 常见场景速查 | 用户描述 | 执行流程 | |----------|----------| | "磁盘还剩多少？" | 流程 1：获取存储详情 | | "存储快满了吗？" | 流程 2：查询存储使用率 | | "存储增长趋势如何？" | 流程 3：查询存储历史趋势 | | "冷热存储分别用了多少？" | 流程 1：获取存储详情（区分冷热） | | "什么时候需要扩容？" | 流程 3：分析增长趋势并预测 | FILE:references/02-ops/user-permission.md # 账号权限管理场景 ## 触发条件 **用户意图：** 创建数据库用户、配置表级权限、实现权限隔离。 **典型问法：** - "怎么创建一个只读账号？" - "如何给开发环境配置独立的账号？" - "能限制某个用户只能访问指定的表吗？" - "怎么查看用户的权限列表？" - "如何回收用户权限？" --- ## Agent 行为原则 **⚠️ 安全边界：提供权限配置指导，不直接创建用户或授权** 1. **查询能力：** Agent 暂无直接查询用户列表和权限的 API 2. **提供方案：** 提供权限配置的最佳实践和操作步骤 3. **引导操作：** 引导用户通过 Lindorm Insight 控制台进行权限管理 4. **不执行变更：** 不直接创建用户、授权或回收权限 5. **权限关键字：** Lindorm SQL 使用 READ/WRITE/SYSTEM/ADMIN/TRASH 权限体系，与 MySQL 的 SELECT/INSERT/UPDATE/DELETE 不同 6. **V1/V2 实例区别：** Lindorm 旧版实例通过 Lindorm Insight（ClusterManager）管理用户权限；**Lindorm 新版实例**需使用「统一用户认证及权限管理系统」，操作方式不同，需先确认实例版本 --- ## 执行流程 ### 官方文档参考 **账号权限管理相关文档：** - 用户权限管理：https://help.aliyun.com/zh/lindorm/user-guide/user-and-permission-management - Ranger 权限配置：https://help.aliyun.com/zh/lindorm/user-guide/use-ranger-to-control-data-access - SQL 权限管理：https://help.aliyun.com/zh/lindorm/user-guide/manage-namespaces - 访问控制（RAM）：https://help.aliyun.com/zh/lindorm/security-and-compliance/ ### 根据用户场景提供配置方案 --- ## 输出示例 ### 完整对话示例1：创建只读账号 **用户：** "我想创建一个只读账号给 BI 团队使用" **Agent：** ```markdown 好的，我来帮您创建一个只读账号。Lindorm 支持两种权限管理方式，我推荐使用 **Lindorm Insight 控制台**（更直观）。 ## 只读账号创建方案 ### 方案1：通过 Lindorm Insight 控制台（推荐） #### 步骤1：登录 Lindorm Insight 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/) 2. 在实例列表页面，单击**目标实例ID** 3. 在左侧导航栏，单击**数据库连接** 4. 在宽表引擎页面的 **Lindorm Insight** 区域中，单击**通过 ClusterManager 公网访问**（或专有网络访问） 5. 输入用户名和密码登录 ⚠️ **首次登录需重置密码：** - 在宽表引擎页面的 Lindorm Insight 区域中，单击**重置 UI 访问密码** - 密码规则：2~30位，需包含大写字母、小写字母、特殊字符和数字中的一种或多种 - 允许的特殊字符：`_` 和 `-` #### 步骤2：创建只读用户 1. Lindorm Insight 页面 → 左侧菜单 → **数据管理 > 用户管理** 2. 点击"创建用户" 3. 配置参数： ``` 用户名：bi_readonly 密码：********（强密码，包含大小写字母+数字+特殊字符）确认密码：******** ``` 4. 点击"确定" #### 步骤3：授予只读权限 1. 用户列表 → 找到 `bi_readonly` → 点击"授权" 2. 选择权限类型： ``` 权限范围：指定命名空间和表命名空间：default（或您的业务命名空间）表名：*（所有表）或指定表名权限类型：☑️ 只读（READ） ``` 3. 点击"确定" #### 步骤4：验证权限新用户可以使用以下方式连接： **连接信息：** > Agent 根据实例 ServiceType 自动选择正确的 V1/V2 域名格式，参见 `sql-client-guide.md` →「连接域名格式」 ```bash mysql -h <您的连接地址> -P 33060 -u bi_readonly -p # 地址获取：控制台实例详情 → 数据库连接，或 aliyun hitsdb get-lindorm-instance-engine-list --instance-id ``` **测试只读权限：** ```sql -- 可以执行的操作 SELECT * FROM default.user_table LIMIT 10; -- ✅ 成功 -- 不能执行的操作 CREATE TABLE test_table (...); -- ❌ 权限不足 INSERT INTO default.user_table VALUES (...); -- ❌ 权限不足 DELETE FROM default.user_table WHERE ...; -- ❌ 权限不足 ``` ### 方案2：通过 SQL 操作 ⚠️ **注意：Lindorm SQL 权限体系与 MySQL 不同，使用 READ/WRITE/SYSTEM/ADMIN/TRASH 关键字** #### 步骤1：使用管理员账号连接 ```bash # MySQL 协议连接（推荐） mysql -h <您的连接地址> -P 33060 -u root -p ``` #### 步骤2：创建用户并授权 ```sql -- 1. 创建用户 CREATE USER IF NOT EXISTS bi_readonly identified BY 'YourStrongPassword123!'; -- 2. 授予指定表的只读权限（需先确认表存在） GRANT READ ON TABLE default.user_table TO bi_readonly; GRANT READ ON TABLE default.order_table TO bi_readonly; -- 或授予整个数据库的只读权限（database 名若为保留字需用反引号） GRANT READ ON DATABASE `default` TO bi_readonly; -- 授予读写权限 GRANT READ, WRITE ON DATABASE dev TO dev_user; -- 3. 查看所有用户权限 SHOW PRIVILEGES; -- 查看所有用户 SHOW USERS; ``` #### 步骤3：验证权限使用新用户登录并测试： ```bash mysql -h <您的连接地址> -P 33060 -u bi_readonly -p ``` ### 权限对照表 | 权限类型 | SQL 关键字 | 允许的操作 | |---------|----------|-----------| | 只读 | READ | 查询数据 | | 读写 | READ, WRITE | 查询、插入、更新、删除 | | 管理员 | ADMIN | 创建/删除表和索引等 DDL | | 删除 | TRASH | TRUNCATE TABLE（清空表数据） | | 系统 | SYSTEM | 管理用户权限、COMPACT、FLUSH 等运维操作（仅全局授权） | ### 安全建议 ✅ **推荐做法：** - 为不同环境创建独立账号（生产/测试/开发） - 使用强密码（至少 12 位，包含大小写字母+数字+特殊字符） - 定期轮换密码（建议 90 天） - 遵循最小权限原则（只授予必要的权限） - 对敏感表设置更严格的权限 ❌ **避免做法：** - 不要共享默认管理员账号 - 不要给所有用户授予管理员权限 - 不要使用弱密码（如 123456、password） ### 官方文档 - 完整权限管理指南：https://help.aliyun.com/zh/lindorm/user-guide/user-and-permission-management - SQL 权限命令：https://help.aliyun.com/zh/lindorm/user-guide/manage-namespaces ``` --- ### 完整对话示例2：配置表级权限隔离 **用户：** "开发团队和运维团队需要访问不同的表，怎么配置？" **Agent：** ```markdown 好的，我来帮您规划表级权限隔离方案。 ## 表级权限隔离方案 ### 业务场景分析 - **开发团队：** 需要访问开发环境的表，可读写 - **运维团队：** 需要访问所有表，但只读（监控、排查问题） - **隔离目标：** 开发团队不能访问生产表，运维团队不能修改数据 ### 推荐方案：命名空间 + 表级权限 #### 步骤1：规划命名空间结构 ``` lindorm_instance ├── namespace: prod（生产环境） │ ├── user_table │ ├── order_table │ └── payment_table ├── namespace: dev（开发环境） │ ├── test_user_table │ └── test_order_table └── namespace: staging（预发环境） └── staging_user_table ``` #### 步骤2：创建用户并授权 **2.1 创建开发团队账号** ```sql -- 通过 Lindorm Insight 或 SQL 创建 CREATE USER IF NOT EXISTS dev_team identified BY 'DevPassword123!'; -- 授予 dev 数据库的读写权限 GRANT READ, WRITE ON DATABASE dev TO dev_team; -- 查看权限 SHOW PRIVILEGES; ``` **2.2 创建运维团队账号** ```sql -- 创建用户 CREATE USER IF NOT EXISTS ops_team identified BY 'OpsPassword123!'; -- 授予所有数据库的只读权限 GRANT READ ON DATABASE prod TO ops_team; GRANT READ ON DATABASE dev TO ops_team; GRANT READ ON DATABASE staging TO ops_team; -- 查看权限 SHOW PRIVILEGES; ``` #### 步骤3：验证权限隔离 **开发团队测试：** ```sql -- 连接：mysql -h <您的连接地址> -P 33060 -u dev_team -p -- ✅ 可以操作 dev 命名空间 SELECT * FROM dev.test_user_table; INSERT INTO dev.test_user_table VALUES (...); -- ❌ 不能访问 prod 命名空间 SELECT * FROM prod.user_table; -- 报错：权限不足 ``` **运维团队测试：** ```sql -- 连接：mysql -h <您的连接地址> -P 33060 -u ops_team -p -- ✅ 可以查询所有命名空间 SELECT * FROM prod.user_table; SELECT * FROM dev.test_user_table; -- ❌ 不能修改数据 INSERT INTO prod.user_table VALUES (...); -- 报错：权限不足 DELETE FROM prod.user_table WHERE ...; -- 报错：权限不足 ``` ### 更细粒度的权限控制如果需要更细粒度的控制（如只允许访问指定的列），可以使用 **Ranger**： #### 步骤1：开通 Ranger 1. Lindorm 控制台 → 实例详情 → 数据库连接 2. 计算引擎 → 点击"开通 Ranger 地址" #### 步骤2：配置 Ranger 策略 1. 访问 Ranger 管理页面 2. 创建策略： ``` 策略名称：dev_team_policy 资源： - 命名空间：dev - 表：*（所有表） - 列：*（所有列）用户/组：dev_team 权限：READ, WRITE ``` #### 步骤3：配置列级权限（可选） ``` 策略名称：ops_sensitive_data_mask 资源： - 命名空间：prod - 表：user_table - 列：phone, id_card（敏感列）用户/组：ops_team 权限：READ ``` ### 权限管理最佳实践 #### 1. 使用用户组（推荐） ``` 用户组划分： - admin_group：管理员组（DBA） - dev_group：开发组 - ops_group：运维组 - readonly_group：只读组（BI、分析）好处： - 新用户加入组即可继承权限 - 统一管理，避免重复授权 - 便于权限审计 ``` #### 2. 权限申请流程 ``` 1. 开发人员提交工单申请权限 2. DBA 审核并创建账号 3. 授予最小必要权限 4. 定期审查和回收不用的权限 ``` #### 3. 审计日志监控 ``` 开通 SQL 审计日志（控制台 → 宽表引擎 → SQL审计日志）监控： - 谁访问了哪些表 - 执行了哪些操作 - 是否有越权访问 ``` ### 官方文档 - Ranger 权限管理：https://help.aliyun.com/zh/lindorm/user-guide/use-ranger-to-control-data-access - 命名空间管理：https://help.aliyun.com/zh/lindorm/user-guide/log-in-to-the-cluster-management-system ``` --- ### 完整对话示例3：回收用户权限 **用户：** "一个员工离职了，怎么回收他的账号权限？" **Agent：** ```markdown 明白了，员工离职需要及时回收权限以保障安全。 ## 账号权限回收方案 ### 方案1：删除用户（彻底移除） #### 通过 Lindorm Insight 控制台 1. 登录 [Lindorm 控制台](https://lindorm.console.aliyun.com/)，进入目标实例的**数据库连接**页面 2. 在宽表引擎页面的 **Lindorm Insight** 区域中，单击**通过 ClusterManager 公网访问** 3. 登录 Lindorm Insight 后，进入**数据管理 > 用户管理** → **用户列表** 4. 找到目标用户 → 点击"删除" 5. 确认删除 #### 通过 SQL 命令 ```sql -- 1. 查看现有用户权限 SHOW PRIVILEGES; -- 2. 删除用户（自动回收所有权限） DROP USER employee_username; -- 3. 验证删除 SHOW USERS; -- 目标用户不再列表中，说明已删除 ``` ### 方案2：禁用用户（保留账号，临时禁用） Lindorm 暂不支持直接禁用用户，建议： #### 方案A：回收所有权限 ```sql -- 查看用户当前权限 SHOW PRIVILEGES; -- 逐一回收权限 REVOKE READ ON DATABASE prod FROM employee_username; REVOKE READ, WRITE ON DATABASE dev FROM employee_username; -- 验证权限已回收 SHOW PRIVILEGES; ``` #### 方案B：修改密码（使原密码失效） ```sql -- 修改为随机强密码，用户无法再登录 ALTER USER employee_username SET PASSWORD = 'RandomStrongPassword!@#$%123456'; ``` ### 方案3：批量回收权限（多个离职员工）如果有多个员工离职，可以使用脚本批量处理： ```sql -- 删除多个用户 DROP USER 'employee1'; DROP USER 'employee2'; DROP USER 'employee3'; -- 或使用脚本循环执行 ``` ### 权限回收检查清单完成权限回收后，请检查以下项目： - [ ] **数据库账号**：已删除或禁用 - [ ] **白名单 IP**：已移除离职员工的办公 IP - [ ] **RAM 账号**：已删除或禁用阿里云 RAM 子账号 - [ ] **报警联系人**：已从报警联系人组中移除 - [ ] **密钥/证书**：已轮换相关密钥和证书 - [ ] **审计日志**：检查离职前是否有异常操作 ### 安全建议 ✅ **推荐做法：** 1. **立即回收：** 员工离职当天立即回收所有权限 2. **交接完成后删除：** 确认业务交接完成后再删除账号 3. **审计日志保留：** 保留用户的操作审计日志至少 180 天 4. **定期审查：** 每季度审查用户列表，清理不再使用的账号 ⚠️ **注意事项：** - 删除用户前，确认没有正在运行的应用使用该账号 - 如果应用还在使用，先切换到新账号再删除旧账号 - 重要账号删除前，建议先备份操作日志 ### 账号生命周期管理建议建立完整的账号生命周期管理流程： ``` 1. 入职 → 创建账号 → 授予最小权限 2. 在职 → 定期审查权限 → 根据职责调整 3. 离职 → 立即禁用 → 确认交接 → 删除账号 ``` ### 官方文档 - 用户权限管理：https://help.aliyun.com/zh/lindorm/user-guide/user-and-permission-management - SQL 权限命令：https://help.aliyun.com/zh/lindorm/user-guide/manage-namespaces ``` --- ## 缺参追问 | 缺失参数 | 追问话术 | 默认策略 | |---------|---------|----------| | 用户类型 | "请问是创建只读账号还是读写账号？" | 默认推荐只读账号（安全） | | 权限范围 | "需要访问哪些命名空间或表？" | 默认提供指定表权限方案 | | 用户名 | "请提供要创建的用户名" | 提供命名规范建议 | | 操作类型 | "是创建新用户还是修改现有用户权限？" | 默认按创建新用户引导 | --- ## 错误处理 ### 常见问题 #### 问题1：用户创建失败 - 用户名已存在 **Agent 输出：** ``` 用户创建失败，可能是用户名已存在。 **排查步骤：** 1. **查看现有用户列表** - Lindorm Insight → 数据管理 > 用户管理 → 用户列表 - 或通过 SQL：`SHOW USERS;` 2. **选择解决方案** **方案A：使用不同的用户名** ```sql CREATE USER new_username identified BY 'Password123!'; ``` **方案B：删除旧用户后重新创建** ```sql -- 先删除 DROP USER existing_username; -- 再创建 CREATE USER existing_username identified BY 'NewPassword123!'; ``` **方案C：修改现有用户密码** ```sql ALTER USER existing_username SET PASSWORD = 'NewPassword123!'; ``` **官方文档：** https://help.aliyun.com/zh/lindorm/user-guide/user-and-permission-management ``` #### 问题2：权限授予失败 - 表不存在 **Agent 输出：** ``` 权限授予失败，可能是表不存在。 **排查步骤：** 1. **查看表是否存在** ```sql -- 查看命名空间列表 SHOW SCHEMAS; -- 查看指定命名空间的表 SHOW TABLES IN default; ``` 2. **确认表名格式** Lindorm SQL 通过 MySQL 协议连接时，表名格式为：`ON TABLE namespace.table` **正确示例：** ```sql GRANT READ ON TABLE default.user_table TO username; -- ✅ ``` **错误示例：** ```sql GRANT READ ON user_table TO username; -- ❌ 缺少 TABLE 关键字和命名空间 ``` 3. **如果表确实不存在** - 先创建表，再授权 - 或授予整个数据库的权限： ```sql GRANT READ ON DATABASE `default` TO username; ``` **官方文档：** https://help.aliyun.com/zh/lindorm/user-guide/manage-namespaces ``` #### 问题3：用户连接失败 - 认证错误 **Agent 输出：** ``` 用户连接失败，认证错误，请检查： **1. 用户名是否正确** - 确认用户名拼写无误 - Lindorm 用户名区分大小写 **2. 密码是否正确** - 确认密码无误 - 注意大小写和特殊字符 **3. 白名单是否配置** - 确认客户端 IP 已加入白名单 - 控制台 → 访问控制 → 白名单 **4. 连接地址是否正确** - 确认使用正确的连接地址和端口（端口见 SKILL.md →「端口号速查表」） **5. 用户是否有连接权限** 验证用户权限： ```sql -- 查看所有用户及权限 SHOW PRIVILEGES; SHOW USERS; ``` **测试连接：** ```bash # MySQL 协议连接（推荐） mysql -h <您的连接地址> -P 33060 -u username -p # HBase API 连接（需要在代码中配置） ``` **官方文档：** https://help.aliyun.com/zh/lindorm/user-guide/user-and-permission-management ``` --- ## 关联场景 - 白名单配置 → 跳转 `../01-dev/connection-guide.md` - 连接信息获取 → 跳转 `../01-dev/connection-guide.md` - 审计日志查询 → 控制台操作，无 API 支持 - RAM 访问控制 → 跳转官方文档 --- ## 技术说明 ### 为何不直接创建用户和授权？ 1. **安全风险：** 用户账号和权限是核心安全配置，错误操作可能导致： - 权限泄漏（授权过大） - 业务中断（误删用户） - 数据泄露（未经审批的账号创建） 2. **密码管理：** 用户密码是敏感信息，Agent 不应直接生成或管理密码 3. **审批流程：** 企业通常有严格的权限申请和审批流程，不应绕过 4. **符合最佳实践：** 账号和权限管理应通过控制台或审计的 SQL 操作，便于追溯和审计 ### Agent 提供的价值 - ✅ 提供权限规划方案和最佳实践 - ✅ 完整的权限配置步骤和 SQL 命令 - ✅ 权限隔离和安全加固建议 - ✅ 排查权限问题的完整方案 - ✅ 权限生命周期管理指导 FILE:references/03-ref/acceptance-criteria.md # Acceptance Criteria: alibabacloud-lindorm-agent-skill **Scenario**: Lindorm 全场景运维管理 **Purpose**: Skill 验收标准 --- ## Correct CLI 命令模式 ### 1. Lindorm API 调用（aliyun hitsdb） #### ✅ CORRECT ```bash # 查询实例列表（默认上海地域） aliyun hitsdb get-lindorm-instance-list --region cn-shanghai # 查询实例详情 aliyun hitsdb get-lindorm-instance --instance-id ld-uf6l5kr48wqm6rf1h # 查询存储详情 aliyun hitsdb get-lindorm-fs-used-detail --instance-id ld-uf6l5kr48wqm6rf1h # 查询 V2 实例存储详情 aliyun hitsdb get-lindorm-v2-storage-usage --instance-id ld-uf64f07n285tlbaz2 # 查询引擎列表 aliyun hitsdb get-lindorm-instance-engine-list --instance-id ld-uf6l5kr48wqm6rf1h # 查询 IP 白名单 aliyun hitsdb get-instance-ip-white-list --instance-id ld-uf6l5kr48wqm6rf1h # 查询地域列表 aliyun hitsdb describe-regions # 查询实例概览（所有地域） aliyun hitsdb get-instance-summary ``` #### ❌ INCORRECT ```bash # 错误：实例 ID 格式错误 aliyun hitsdb get-lindorm-instance --instance-id lindorm-xxx --region cn-shanghai # ❌ 应使用 ld-xxx 格式 # 错误：缺少必需参数 aliyun hitsdb get-lindorm-instance --region cn-shanghai # ❌ 缺少 --instance-id # 错误：使用错误的地域格式 aliyun hitsdb get-lindorm-instance-list --region Shanghai # ❌ 应使用 cn-shanghai ``` ### 2. 云监控 API 调用（aliyun cms） #### ✅ CORRECT ```bash # 查询 Lindorm 监控指标列表 aliyun cms describe-metric-meta-list --namespace acs_lindorm # 查询 CPU 空闲率最新数据 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-uf6l5kr48wqm6rf1h"}]' # 查询历史监控数据（指定时间范围） aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-uf6l5kr48wqm6rf1h"}]' \ --start-time "2026-04-14 08:00:00" \ --end-time "2026-04-14 09:00:00" \ --period 60 ``` #### ❌ INCORRECT ```bash # 错误：错误的 namespace aliyun cms describe-metric-meta-list --namespace acs_hbase --region cn-shanghai # ❌ 应使用 acs_lindorm # 错误：错误的指标名称 aliyun cms describe-metric-last --metric-name cpu_usage # ❌ 应使用 cpu_idle # 错误：dimensions 格式错误 aliyun cms describe-metric-last --dimensions "instanceId=ld-xxx" # ❌ 应使用 JSON 数组格式 ``` --- ## 参数验证模式 ### 1. 实例 ID 格式 #### ✅ CORRECT ``` ld-uf6l5kr48wqm6rf1h # ✅ 以 ld- 开头，后接字母数字 ld-bp1234567890abcdef # ✅ 正确格式 ``` #### ❌ INCORRECT ``` lindorm-xxx # ❌ 不以 ld- 开头 ld_xxx # ❌ 使用下划线而非连字符 LD-XXX # ❌ 使用大写（建议使用小写） ``` ### 2. 地域格式 #### ✅ CORRECT ``` cn-shanghai # ✅ 正确格式 cn-beijing # ✅ 正确格式 cn-hangzhou # ✅ 正确格式 ``` #### ❌ INCORRECT ``` shanghai # ❌ 缺少 cn- 前缀 CN-SHANGHAI # ❌ 使用大写 cn_shanghai # ❌ 使用下划线 ``` ### 3. 时间格式时间格式规则见 SKILL.md →「时间格式」，验收正误对比： #### ✅ CORRECT ```bash --start-time "2026-04-14 08:00:00" # ✅ 本地时间格式（推荐），解析为 CST --start-time "1773897600000" # ✅ Unix 毫秒时间戳 --start-time "2026-04-14T08:00:00Z" # ✅ ISO 8601 UTC，解析为 UTC（注意时区换算：UTC+8=CST） ``` #### ❌ INCORRECT ```bash --start-time "2026-04-14T08:00Z" # ❌ ISO 8601 短格式（无秒）不支持，报 parse param time error --start-time "2026/04/14 08:00:00" # ❌ 使用斜杠分隔 --start-time "08:00:00" # ❌ 仅提供时间，缺少日期 ``` --- ## 输出格式验证 ### 1. 监控数据输出 #### ✅ CORRECT 输出结构 ```json { "Datapoints": [ { "instanceId": "ld-uf6l5kr48wqm6rf1h", "timestamp": 1773897600000, "Average": 75.5 } ], "DatapointCount": 1, "Success": true } ``` #### 验证要点 - `Datapoints` 数组存在且非空 - 每个数据点包含 `instanceId`, `timestamp`, `Average`（部分指标含 `Maximum`/`Minimum`） - `Average` 在合理范围（如 CPU 空闲率 0-100） ### 2. 实例列表输出 #### ✅ CORRECT 输出结构 ```json { "InstanceList": [ { "InstanceId": "ld-uf6l5kr48wqm6rf1h", "InstanceAlias": "生产环境", "InstanceStatus": "ACTIVATION", "RegionId": "cn-shanghai" } ], "TotalCount": 1 } ``` #### 验证要点 - `InstanceList` 数组存在 - 每个实例包含 `InstanceId`, `InstanceStatus` - `InstanceStatus` 为有效状态值（ACTIVATION, CREATING, STOPPED） --- ## 错误处理模式 ### 1. API 错误响应 #### ✅ CORRECT 错误处理 ```json { "Code": "InvalidParameter.InstanceId", "Message": "The specified instance ID is invalid.", "RequestId": "xxx" } ``` **处理流程**： 1. 读取 `Code` 字段识别错误类型 2. 参考 `references/02-ops/error-troubleshoot.md` 查找解决方案 3. 引导用户检查参数或权限 #### ❌ INCORRECT 错误处理 - 忽略错误码，直接返回原始错误信息 - 凭训练知识猜测错误原因（应查官方文档） --- ## 场景触发验证 ### 正确触发场景 | 用户输入 | 触发场景 | 执行文档 | |---------|---------|---------| | "我有哪些 Lindorm 实例" | 实例查询 | `02-ops/instance-management.md` | | "CPU 使用率是多少" | 监控查询 | `02-ops/monitoring-guide.md` | | "报错 InvalidParameter" | 错误排查 | `02-ops/error-troubleshoot.md` | | "怎么连接 Lindorm" | 连接指南 | `01-dev/connection-guide.md` | | "怎么建表" | 建表指南 | `01-dev/table-design.md` | ### 错误触发场景 | 用户输入 | 错误处理 | |---------|---------| | "RDS 实例有哪些" | ❌ 不应触发 Lindorm skill，应提示使用 RDS skill | | "MySQL 怎么用" | ❌ 不应触发，除非明确提到 Lindorm SQL | --- ## 安全规范验证安全规则见 SKILL.md →「前置条件 → 凭证已配置」。 #### ❌ FORBIDDEN ```bash echo $ALIBABA_CLOUD_ACCESS_KEY_ID # ❌ 禁止读取/打印 AK/SK "请输入您的 AccessKey ID" # ❌ 禁止在对话中要求用户输入 aliyun configure set --access-key-id LTAI5t # ❌ 禁止硬编码凭证 ``` FILE:references/03-ref/cli-installation-guide.md # Aliyun CLI Installation & Configuration Guide Complete guide for installing and configuring Aliyun CLI. > **Aliyun CLI 3.3.3+**: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage. ## Installation ### macOS **Using Homebrew (Recommended)** ```bash brew install aliyun-cli # Upgrade to latest brew upgrade aliyun-cli # Verify version (>= 3.3.3) aliyun version ``` **Using Binary** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz # Extract tar -xzf aliyun-cli-macosx-latest-amd64.tgz # Move to PATH sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` ### Linux **Debian/Ubuntu** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-amd64.tgz sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` **CentOS/RHEL** ```bash # Download wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-amd64.tgz sudo mv aliyun /usr/local/bin/ # Verify aliyun version ``` **ARM64 Architecture** ```bash # Download ARM64 version wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz # Extract and install tar -xzf aliyun-cli-linux-latest-arm64.tgz sudo mv aliyun /usr/local/bin/ ``` ### Windows **Using Binary** 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: `aliyun version` **Using PowerShell** ```powershell # Download Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip" # Extract Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli # Add to PATH (requires admin privileges) $env:Path += ";C:\aliyun-cli" [Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine) # Verify aliyun version ``` ## Configuration ### Quick Start ```bash aliyun configure set \ --mode AK \ --access-key-id \ --access-key-secret \ --region cn-hangzhou ``` All `aliyun configure` commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts. **Where to Get Access Keys** 1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once ### Configuration Modes Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags. #### 1. AK Mode (Access Key) Most common mode for personal accounts and scripts. ```bash aliyun configure set \ --mode AK \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --region cn-hangzhou ``` Configuration is stored in `~/.aliyun/config.json`: ```json { "current": "default", "profiles": [ { "name": "default", "mode": "AK", "access_key_id": "LTAI5tXXXXXXXX", "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX", "region_id": "cn-hangzhou", "output_format": "json", "language": "en" } ] } ``` #### 2. StsToken Mode (Temporary Credentials) For short-lived access (tokens expire in 1-12 hours). ```bash aliyun configure set \ --mode StsToken \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --sts-token v1.0:XXXXXXXXXXXXXXXX \ --region cn-hangzhou ``` Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access. #### 3. RamRoleArn Mode (Assume RAM Role) Assume a RAM role for elevated or cross-account access. ```bash aliyun configure set \ --mode RamRoleArn \ --access-key-id LTAI5tXXXXXXXX \ --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \ --ram-role-arn acs:ram::123456789012:role/AdminRole \ --role-session-name my-session \ --region cn-hangzhou ``` Use cases: cross-account resource access, temporary elevated privileges, role-based access control. #### 4. EcsRamRole Mode (ECS Instance RAM Role) Use the RAM role attached to an ECS instance — no credentials needed. ```bash aliyun configure set \ --mode EcsRamRole \ --ram-role-name MyEcsRole \ --region cn-hangzhou ``` Requirements: must be running on an ECS instance with a RAM role attached. Use cases: scripts and automation running on ECS instances. #### 5. RsaKeyPair Mode (RSA Key Pair) Use RSA key pair for authentication (generate key pair in Aliyun Console first). ```bash aliyun configure set \ --mode RsaKeyPair \ --private-key /path/to/private-key.pem \ --key-pair-name my-key-pair \ --region cn-hangzhou ``` #### 6. RamRoleArnWithEcs Mode (ECS + RAM Role) Combine ECS instance role with RAM role assumption for cross-account access from ECS. ```bash aliyun configure set \ --mode RamRoleArnWithEcs \ --ram-role-name MyEcsRole \ --ram-role-arn acs:ram::123456789012:role/TargetRole \ --role-session-name my-session \ --region cn-hangzhou ``` ### Environment Variables **Highest priority** - overrides config file **Access Key Mode** ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret export ALIBABA_CLOUD_REGION_ID=cn-hangzhou ``` **STS Token Mode** ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token export ALIBABA_CLOUD_REGION_ID=cn-hangzhou ``` **ECS RAM Role Mode** ```bash export ALIBABA_CLOUD_ECS_METADATA=role_name ``` **Use Case**: - CI/CD pipelines - Docker containers - Temporary credential override ### Managing Multiple Profiles **Create Named Profiles** ```bash aliyun configure set --profile projectA \ --mode AK \ --access-key-id LTAI5tAAAAAAAA \ --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \ --region cn-hangzhou aliyun configure set --profile projectB \ --mode AK \ --access-key-id LTAI5tBBBBBBBB \ --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \ --region cn-shanghai ``` **Use Specific Profile** ```bash aliyun ecs describe-instances --profile projectA export ALIBABA_CLOUD_PROFILE=projectA aliyun ecs describe-instances # Uses projectA ``` **List and Switch Profiles** ```bash aliyun configure list # List all profiles aliyun configure set --current projectA # Switch default profile ``` ### Credential Priority Credentials are loaded in this order (first found wins): 1. **Command-line flag**: `--profile ` 2. **Environment variable**: `ALIBABA_CLOUD_PROFILE` 3. **Environment credentials**: `ALIBABA_CLOUD_ACCESS_KEY_ID`, etc. 4. **Configuration file**: `~/.aliyun/config.json` (current profile) 5. **ECS Instance RAM Role**: If running on ECS with attached role ## Verification ### Test Authentication ```bash # Basic test - list regions aliyun ecs describe-regions # Expected output: JSON array of regions ``` **If successful**, you'll see: ```json { "Regions": { "Region": [ { "RegionId": "cn-hangzhou", "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com", "LocalName": "华东 1（杭州）" }, ... ] }, "RequestId": "..." } ``` **If failed**, you'll see error messages: - `InvalidAccessKeyId.NotFound` - Wrong Access Key ID - `SignatureDoesNotMatch` - Wrong Access Key Secret - `InvalidSecurityToken.Expired` - STS token expired (for StsToken mode) - `Forbidden.RAM` - Insufficient permissions ### Debug Configuration ```bash # Show current configuration aliyun configure get # Test with debug logging aliyun ecs describe-regions --log-level=debug # Check credential provider aliyun configure get mode ``` ## Security Best Practices ### 1. Use RAM Users (Not Root Account) ❌ **Don't**: Use Aliyun root account credentials ✅ **Do**: Create RAM users with specific permissions ```bash # Create RAM user in console # Attach only necessary policies # Use RAM user's access keys ``` ### 2. Principle of Least Privilege Grant only the minimum permissions needed: ```bash # Example: Read-only ECS access # Attach policy: AliyunECSReadOnlyAccess ``` ### 3. Rotate Access Keys Regularly ```bash # Create new access key in RAM Console, then update configuration aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET # Delete old access key from console ``` ### 4. Use STS Tokens for Temporary Access ```bash aliyun configure set --mode StsToken \ --access-key-id XXXX --access-key-secret XXXX \ --sts-token XXXX --region cn-hangzhou ``` ### 5. Use ECS RAM Roles When Possible ```bash aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou ``` ### 6. Never Commit Credentials ```bash # Add to .gitignore echo "~/.aliyun/config.json" >> .gitignore # Use environment variables in CI/CD instead ``` ### 7. Secure Config File ```bash # Restrict permissions chmod 600 ~/.aliyun/config.json ``` ## Troubleshooting ### Issue: Command Not Found ```bash # Check installation which aliyun # Check PATH echo $PATH # Reinstall or add to PATH ``` ### Issue: Authentication Failed ```bash # Verify configuration aliyun configure get # Test with debug aliyun ecs describe-regions --log-level=debug # Check credentials in console # Verify access key is active ``` ### Issue: Permission Denied ```bash # Error: Forbidden.RAM # Check RAM user permissions # Attach necessary policies in RAM console # Example: AliyunECSFullAccess for ECS operations ``` ### Issue: STS Token Expired ```bash # Error: InvalidSecurityToken.Expired # Reconfigure with new token aliyun configure set --mode StsToken \ --access-key-id XXXX --access-key-secret XXXX \ --sts-token NEW_TOKEN --region cn-hangzhou ``` ### Issue: Wrong Region ```bash # Some resources may not exist in the specified region # Check available regions aliyun ecs describe-regions # Update default region aliyun configure set region cn-shanghai ``` ## Advanced Configuration ### Custom Endpoint ```bash # Use custom or private endpoint export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com ``` ### Proxy Settings ```bash # HTTP proxy export HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 # No proxy for specific domains export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com ``` ### Timeout Settings ```bash # Connection timeout (default: 10s) export ALIBABA_CLOUD_CONNECT_TIMEOUT=30 # Read timeout (default: 10s) export ALIBABA_CLOUD_READ_TIMEOUT=30 ``` ## Next Steps After installation and configuration: 1. **Install plugins** for services you need (v3.3.3+ supports all published product plugins): ```bash aliyun plugin install --names hitsdb cms # List all available plugins aliyun plugin list-remote ``` 2. **Explore commands**: ```bash aliyun hitsdb --help aliyun cms --help ``` 3. **Read documentation**: - 参考阿里云官方文档：https://help.aliyun.com/zh/cli/ ## References - Official Documentation: https://help.aliyun.com/zh/cli/ - RAM Console: https://ram.console.aliyun.com/ - Access Key Management: https://ram.console.aliyun.com/manage/ak - Plugin Repository: https://github.com/aliyun/aliyun-cli FILE:references/03-ref/lindorm-cli-guide.md # Lindorm CLI & HBase Shell Guide Lindorm 专用命令行工具指南，覆盖 Lindorm CLI（SQL/TSDB）和 HBase Shell（alihbase）。 --- ## Lindorm CLI Lindorm CLI is the official command-line client for connecting to and operating Lindorm wide table engine (SQL) and time series engine (TSDB). > **Official Doc**: https://help.aliyun.com/zh/lindorm/user-guide/use-lindorm-cli-to-connect-to-and-use-lindormtable ### Installation #### Download Links | Platform | Download URL | |----------|-------------| | Linux x64 | `https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-latest.tar.gz` | | Linux ARM64 | `https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-arm64-latest.tar.gz` | | macOS AMD64 | `https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-mac-amd64-latest.tar.gz` | | macOS ARM64 | `https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-mac-arm64-latest.tar.gz` | | Windows x64 | `https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-windows-x64-latest.zip` | #### Installation Steps (macOS/Linux) ```bash # 1. Download (example: macOS ARM64) curl -L -o lindorm-cli.tar.gz "https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-mac-arm64-latest.tar.gz" # 2. Extract tar -xzf lindorm-cli.tar.gz # 3. Move to PATH sudo mv lindorm-cli /usr/local/bin/ # 4. Verify lindorm-cli -version # Expected output: lindorm-cli version: 2.2.0 (or later) ``` #### Installation Steps (Windows) 1. Download the ZIP file from the table above 2. Extract the ZIP 3. Add the directory to PATH 4. Verify: `lindorm-cli -version` ### Connection Methods Lindorm CLI supports two connection protocols: #### 1. MySQL Protocol (Wide Table Engine) ```bash # Connect to wide table engine via MySQL protocol lindorm-cli -url :33060 -username root -password -database # Example (V2 instance) lindorm-cli -url ld-uf6nbdlx5n34q6l6t-proxy-lindorm-pub.lindorm.aliyuncs.com:33060 \ -username root -password XUzmhKMpuyhx -database default # URL can also use mysql:// prefix lindorm-cli -url mysql://ld-xxx-proxy-lindorm-pub.lindorm.aliyuncs.com:33060 \ -username root -password -database ``` #### 2. Avatica/TSDB Protocol (Time Series Engine) ```bash # Connect to TSDB engine via Avatica JDBC protocol lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password # Example (V2 instance) lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://ld-uf6nbdlx5n34q6l6t-proxy-tsdb-pub.lindorm.aliyuncs.com:8242' \ -username root -password XUzmhKMpuyhx ``` ### Usage Modes #### Non-Interactive Mode (-execute) Execute a single SQL command and quit: ```bash lindorm-cli -url :33060 -username root -password \ -database -execute "SELECT * FROM my_table" -format table ``` #### Interactive Mode (Pipe) Pipe multiple SQL commands: ```bash echo "UPSERT INTO t1 VALUES ('k1','v1',10); SELECT * FROM t1;" | \ lindorm-cli -url :33060 -username root -password -database -format table ``` #### Output Format Options | Format | Description | Example | |--------|-------------|---------| | `table` | Formatted table with borders | Default, good for terminal | | `csv` | CSV format | Good for data export | | `column` | Column-aligned plain text | Compact display | | `vertical` | Vertical (one field per line) | Like MySQL `\G` | | `json` | JSON with base64-encoded strings | Use `-pretty` for readable JSON | ```bash # Table format (default) lindorm-cli ... -execute "SELECT * FROM t1" -format table # CSV format lindorm-cli ... -execute "SELECT * FROM t1" -format csv # JSON format with pretty print lindorm-cli ... -execute "SELECT * FROM t1" -format json -pretty # Write output to file lindorm-cli ... -execute "SELECT * FROM t1" -format table -output result.txt ``` #### Precision for TSDB Queries ```bash # Timestamp formats for TSDB queries lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://...' ... -precision ms # milliseconds lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://...' ... -precision s # seconds lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://...' ... -precision rfc3339 # RFC 3339 format ``` ### SQL Syntax Notes for Lindorm CLI > **Important**: Lindorm CLI's SQL parser has subtle differences from the mysql CLI client. #### CREATE TABLE Syntax Lindorm CLI requires `PRIMARY KEY` to be specified **inside** the column definition parentheses (MySQL standard style), not as a separate clause outside: ```sql -- ✅ Correct: PRIMARY KEY inside column list (also works in mysql client) CREATE TABLE t1 (id VARCHAR NOT NULL, name VARCHAR, score INT, PRIMARY KEY(id)); -- ❌ Wrong: PRIMARY KEY as separate clause (works in mysql client but fails in lindorm-cli -execute) CREATE TABLE t1 (id VARCHAR NOT NULL, name VARCHAR, score INT) PRIMARY KEY (id); ``` > The `PRIMARY KEY` outside the parentheses syntax works with the `mysql` CLI client but causes `"Encountered PRIMARY PRIMARY"` error in lindorm-cli `-execute` mode. #### UPSERT vs INSERT Lindorm SQL uses `UPSERT` as the primary write operation (INSERT is also UPSERT semantics): ```sql -- UPSERT is recommended UPSERT INTO t1 (id, name, score) VALUES ('k1', 'Alice', 88); -- Bulk UPSERT UPSERT INTO t1 (id, name, score) VALUES ('k1','Alice',88), ('k2','Bob',95), ('k3','Carol',72); ``` #### Reserved Words Avoid using SQL reserved words as column names (e.g., `value`, `key`, `timestamp`). If needed, quote with backticks: ```sql -- ❌ Error: "value" is reserved CREATE TABLE t1 (id VARCHAR, value INT, PRIMARY KEY(id)); -- ✅ Correct: use backticks or avoid reserved words CREATE TABLE t1 (id VARCHAR, `value` INT, PRIMARY KEY(id)); ``` ### Lindorm CLI Common Operations ```bash # Show databases lindorm-cli -url :33060 -username root -password -execute "SHOW DATABASES" -format table # Create database lindorm-cli -url :33060 -username root -password -execute "CREATE DATABASE my_db" -format table # Create table (use inline PRIMARY KEY syntax) lindorm-cli -url :33060 -username root -password -database my_db \ -execute "CREATE TABLE users (id VARCHAR NOT NULL, name VARCHAR, age INT, PRIMARY KEY(id))" -format table # Insert data lindorm-cli -url :33060 -username root -password -database my_db \ -execute "UPSERT INTO users (id, name, age) VALUES ('u1','Alice',25)" -format table # Query data lindorm-cli -url :33060 -username root -password -database my_db \ -execute "SELECT * FROM users" -format table # Create secondary index (no USING KV in mysql protocol) lindorm-cli -url :33060 -username root -password -database my_db \ -execute "CREATE INDEX idx_age ON users (age)" -format table # Describe table lindorm-cli -url :33060 -username root -password -database my_db \ -execute "DESCRIBE users" -format table # Drop table lindorm-cli -url :33060 -username root -password -database my_db \ -execute "DROP TABLE IF EXISTS users" -format table ``` ### TSDB Operations via Lindorm CLI ```bash # Connect to TSDB lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password # Show databases lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password -execute "SHOW DATABASES" -format table # Create TSDB table lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password \ -execute "CREATE TABLE ts_test (p VARCHAR NOT NULL, t TIMESTAMP NOT NULL, v DOUBLE, PRIMARY KEY(p, t))" -format table # Upsert time series data lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password \ -execute "UPSERT INTO ts_test (p, t, v) VALUES ('cpu', '2024-01-01 10:00:00', 85.5)" -format table # Query with time range lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password \ -execute "SELECT * FROM ts_test WHERE p='cpu' AND t >= '2024-01-01 00:00:00'" -format table # Query with millisecond precision lindorm-cli -url 'jdbc:lindorm:tsdb:url=http://:8242' \ -username root -password \ -execute "SELECT * FROM ts_test" -format table -precision ms ``` ### Lindorm CLI Limitations 1. **Avatica (port 30060) not supported for wide table**: lindorm-cli only supports MySQL protocol for wide table and `jdbc:lindorm:tsdb:` URL for TSDB. It cannot connect to the generic Avatica SQL port (30060) — use `mysql` client or `phoenixdb` Python library for that. 2. **CREATE TABLE syntax**: Must use inline `PRIMARY KEY` inside column list, not as separate clause. 3. **JSON format encoding**: JSON output uses base64 encoding for VARCHAR values. Use `table` or `csv` format for readable output. 4. **Non-interactive only**: lindorm-cli `-execute` mode runs one command per invocation. For multi-command workflows, use pipe or multiple invocations. ### Lindorm CLI References - Official Documentation (Wide Table): https://help.aliyun.com/zh/lindorm/user-guide/use-lindorm-cli-to-connect-to-and-use-lindormtable - Official Documentation (TSDB): https://help.aliyun.com/zh/lindorm/user-guide/use-lindorm-cli-to-connect-to-and-use-lindorm-tsdb --- ## HBase Shell (alihbase) HBase Shell is used for native HBase API operations on Lindorm wide table engine. **Lindorm requires the dedicated `alihbase shell` (not the open-source Apache HBase Shell)**. > **Critical**: The open-source Apache HBase Shell cannot connect to Lindorm's public network endpoint. It resolves ZK addresses to internal IPs that are inaccessible from outside. You must use `alihbase shell` from Alibaba Cloud. ### alihbase Shell Installation > **Download URL**: The `alihbase shell` can be downloaded directly from the public OSS URL: > `https://hbaseuepublic.oss-cn-beijing.aliyuncs.com/hbaseue-shell.tar.gz` #### Step-by-Step Installation 1. **Download alihbase shell**: ```bash curl -L -o hbaseue-shell.tar.gz "https://hbaseuepublic.oss-cn-beijing.aliyuncs.com/hbaseue-shell.tar.gz" ``` 2. **Extract and install**: ```bash # Extract (creates alihbase-2.0.22 directory) tar -xzf hbaseue-shell.tar.gz # Navigate to the directory cd alihbase-2.0.22 # Run alihbase shell ./bin/hbase shell ``` #### Connection Configuration alihbase shell connects to Lindorm via ZooKeeper address with username/password authentication: ```bash # Option 2: Configuration file (hbase-site.xml) — recommended # Place in conf/ directory: cat > conf/hbase-site.xml << 'EOF' hbase.zookeeper.quorum :30020 hbase.client.username root hbase.client.password EOF ./bin/alihbase shell ``` #### Java Requirements - **JDK 8+** is required - Verify: `java -version` ### alihbase Shell Common Operations ```ruby # Create table with column family create 'my_table', 'cf1' # Put data put 'my_table', 'row1', 'cf1:name', 'Alice' put 'my_table', 'row1', 'cf1:age', '25' # Get a row get 'my_table', 'row1' # Scan table scan 'my_table' # Scan with limit scan 'my_table', {LIMIT => 10} # Delete a column delete 'my_table', 'row1', 'cf1:age' # Describe table describe 'my_table' # Count rows count 'my_table' # Disable and drop table disable 'my_table' drop 'my_table' ``` ### Alternative: HBase Operations via SQL If alihbase shell is not available, you can perform equivalent HBase operations using SQL through `mysql` client or `lindorm-cli`: | HBase Shell Command | SQL Equivalent | |--------------------|----------------| | `create 't', 'cf1'` | `CREATE TABLE t (pk VARCHAR NOT NULL, cf1:col VARCHAR, PRIMARY KEY(pk)) WITH (DYNAMIC_COLUMNS=true)` | | `put 't', 'r1', 'cf1:name', 'Alice'` | `UPSERT INTO t (pk, `cf1:name`) VALUES ('r1', 'Alice')` | | `get 't', 'r1'` | `SELECT * FROM t WHERE pk='r1'` | | `scan 't'` | `SELECT * FROM t` | | `delete 't', 'r1', 'cf1:age'` | `DELETE FROM t WHERE pk='r1'` (deletes entire row) | > Note: SQL operations on HBase-style tables use `DYNAMIC_COLUMNS=true` table property and colon-separated column family syntax (`cf1:col_name`). ### HBase Shell References - Official Documentation: https://help.aliyun.com/zh/lindorm/user-guide/use-hbase-shell-to-connect-to-and-use-the-wide-table-engine - alihbase-client Maven: `com.aliyun.hbase:alihbase-client:2.8.11` - alihbase-shell Maven: `com.aliyun.hbase:alihbase-shell:2.8.7` (JAR only, not standalone binary) FILE:references/03-ref/ram-policies.md # RAM 权限策略列表本 Skill 涉及的所有 API 及对应的 RAM 权限要求。 > **策略名称说明**：Lindorm 官方系统策略为 `AliyunLindormReadOnlyAccess`（只读）、`AliyunLindormFullAccess`（完全）、`AliyunLindormDevelopAccess`（开发者）。 ## Lindorm API 权限 | API Action | 权限策略 | 说明 | |------------|---------|------| | `DescribeRegions` | `AliyunLindormReadOnlyAccess` | 查询地域列表 | | `GetLindormInstanceList` | `AliyunLindormReadOnlyAccess` | 查询实例列表 | | `GetLindormInstance` | `AliyunLindormReadOnlyAccess` | 查询实例详情 | | `GetLindormV2InstanceDetails` | `AliyunLindormReadOnlyAccess` | 查询 V2 实例详情 | | `GetLindormInstanceEngineList` | `AliyunLindormReadOnlyAccess` | 查询实例引擎列表 | | `GetLindormFsUsedDetail` | `AliyunLindormReadOnlyAccess` | 查询存储详情（V1） | | `GetLindormV2StorageUsage` | `AliyunLindormReadOnlyAccess` | 查询存储详情（V2） | | `GetInstanceIpWhiteList` | `AliyunLindormReadOnlyAccess` | 查询 IP 白名单 | ## 云监控 API 权限 | API Action | 权限策略 | 说明 | |------------|---------|------| | `DescribeMetricMetaList` | `AliyunCloudMonitorReadOnlyAccess` | 查询监控指标列表 | | `DescribeMetricLast` | `AliyunCloudMonitorReadOnlyAccess` | 查询最新监控数据 | | `DescribeMetricData` | `AliyunCloudMonitorReadOnlyAccess` | 查询历史监控数据 | ## 系统权限策略 ### 只读权限（推荐） > 本 Skill 为只读操作场景，仅需以下权限。 ```json { "Statement": [ { "Effect": "Allow", "Action": [ "hitsdb:DescribeRegions", "hitsdb:GetLindormInstanceList", "hitsdb:GetLindormInstance", "hitsdb:GetLindormV2InstanceDetails", "hitsdb:GetLindormInstanceEngineList", "hitsdb:GetLindormFsUsedDetail", "hitsdb:GetLindormV2StorageUsage", "hitsdb:GetInstanceIpWhiteList" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cms:DescribeMetricMetaList", "cms:DescribeMetricLast", "cms:DescribeMetricData" ], "Resource": "*" } ], "Version": "1" } ``` > ℹ️ **关于写操作权限**：本 Skill 不执行任何写操作。如用户确实需要创建/修改/删除实例等写操作，请直接授予官方系统策略 `AliyunLindormFullAccess`。 ## 权限配置步骤 ### 通过 RAM 控制台配置 1. 登录 [RAM 控制台](https://ram.console.aliyun.com/) 2. 创建 RAM 用户或使用现有用户 3. 在用户详情页，点击"添加权限" 4. 选择权限策略： - 只读：`AliyunLindormReadOnlyAccess` + `AliyunCloudMonitorReadOnlyAccess` - 完全：`AliyunLindormFullAccess` 5. 确认授权 ### 通过 CLI 配置 ```bash # 创建 RAM 用户 aliyun ram create-user --user-name lindorm-operator # 添加只读权限 aliyun ram attach-policy-to-user \ --user-name lindorm-operator \ --policy-name AliyunLindormReadOnlyAccess \ --policy-type System aliyun ram attach-policy-to-user \ --user-name lindorm-operator \ --policy-name AliyunCloudMonitorReadOnlyAccess \ --policy-type System ``` ## 权限验证执行以下命令验证权限是否配置正确： ```bash # 测试 Lindorm 权限 aliyun hitsdb get-lindorm-instance-list --region cn-shanghai # 测试云监控权限 aliyun cms describe-metric-meta-list --namespace acs_lindorm ``` 如果返回 `Forbidden.RAM` 错误，说明权限不足，需按上述步骤添加权限。 ## 权限不足时的处理流程 1. 检查当前用户权限：在 RAM 控制台查看用户授权策略 2. 确认需要的权限：参考上述 API 权限列表 3. 申请权限：联系主账号管理员添加对应权限策略 4. 验证权限：重新执行测试命令确认权限生效 FILE:references/03-ref/related-commands.md # CLI 命令列表本 Skill 涉及的所有 aliyun CLI 命令。 ## Lindorm 实例管理 CLI **产品名**: `hitsdb`（Lindorm 产品别名） **API Version**: `2020-06-15` ### 插件安装 ```bash # 安装 Lindorm 插件 aliyun plugin install --names hitsdb # 启用自动插件安装（推荐） aliyun configure set --auto-plugin-install true ``` ### 查询命令 | CLI 命令 | 说明 | 必需参数 | 返回关键字段 | |----------|------|---------|-------------| | `aliyun hitsdb describe-regions` | 查询支持的地域列表 | 无 | `Regions[]`: RegionId, LocalName, RegionEndpoint | | `aliyun hitsdb get-instance-summary` | 查询全地域实例概览（无需 `--region`） | 无 | `RegionalSummary[]`: RegionId, RunningCount, LockingCount, Total | | `aliyun hitsdb get-lindorm-instance-list` | 查实例列表（ID、状态、引擎开关，支持按地域/类型筛选） | `--region` | `InstanceList[]`: InstanceId, InstanceAlias, InstanceStatus, ServiceType, Enable* 引擎开关 | | `aliyun hitsdb get-lindorm-instance` | 查配置/版本/状态（ServiceType、引擎节点数、规格，**不含连接地址**） | `--instance-id` | InstanceStatus, ServiceType, VpcId, `EngineList[]`: Engine, CoreCount, CpuCount, MemorySize, Specification, Version | | `aliyun hitsdb get-lindorm-instance-engine-list` | 查连接地址（各引擎 host:port、公网/内网） | `--instance-id` | `EngineList[]`: EngineType, `NetInfoList[]`: ConnectionString, Port, NetType(`"2"`=内网/`"0"`=公网) | | `aliyun hitsdb get-lindorm-fs-used-detail` | 查询存储详情（V1） | `--instance-id` | FsCapacity, FsUsedHot/Cold, FsUsedOnLindormTable/TSDB/Search, `LStorageUsageList[]` | | `aliyun hitsdb get-lindorm-v2-storage-usage` | 查询存储详情（V2） | `--instance-id` | `UsageByDiskCategory[]`: capacity, used, usedLindormTable/Tsdb/Search3/Column3/Vector3/Message3 | | `aliyun hitsdb get-instance-ip-white-list` | 查询 IP 白名单 | `--instance-id` | `GroupList[]`: GroupName, SecurityIpList | | `aliyun hitsdb get-lindorm-v2-instance-details` | 查询 V2 实例详情 | `--instance-id` | V2 实例的详细配置信息 | ### 管理命令 | CLI 命令 | 说明 | 必需参数 | |----------|------|---------| | `aliyun hitsdb create-lindorm-instance` | 创建实例 | 多个参数，见 --help | | `aliyun hitsdb create-lindorm-v2-instance` | 创建 V2 实例 | 多个参数，见 --help | | `aliyun hitsdb release-lindorm-instance` | 释放实例 | `--instance-id`, `--region` | | `aliyun hitsdb upgrade-lindorm-instance` | 变配实例 | `--instance-id`, `--region` | | `aliyun hitsdb update-instance-ip-white-list` | 更新 IP 白名单 | `--instance-id`, `--region`, `--group-name`, `--security-ip-list` | | `aliyun hitsdb update-lindorm-instance-attribute` | 更新实例属性 | `--instance-id`, `--region` | ### 执行示例 ```bash # 查询地域 aliyun hitsdb describe-regions # 查询实例概览（无需 region，自动返回所有地域） aliyun hitsdb get-instance-summary # 查询实例列表（需要指定地域） aliyun hitsdb get-lindorm-instance-list --region cn-shanghai # 查询实例详情（无需 region） aliyun hitsdb get-lindorm-instance --instance-id ld-uf6nbdlx5n34q6l6t # 查询引擎列表（无需 region） aliyun hitsdb get-lindorm-instance-engine-list --instance-id ld-uf6nbdlx5n34q6l6t # 查询存储详情 V1（无需 region） aliyun hitsdb get-lindorm-fs-used-detail --instance-id ld-uf6cx7381qw2u5u8w # 查询存储详情 V2（无需 region） aliyun hitsdb get-lindorm-v2-storage-usage --instance-id ld-uf6nbdlx5n34q6l6t # 查询 IP 白名单（无需 region） aliyun hitsdb get-instance-ip-white-list --instance-id ld-uf6nbdlx5n34q6l6t # 带过滤条件的实例列表查询 aliyun hitsdb get-lindorm-instance-list --region cn-shanghai --service-type lindorm_v2 --support-engine 4 ``` ### 返回值结构 #### get-lindorm-instance-list → 查实例列表返回实例基本信息，不含连接地址、不含引擎节点数/规格。 ```json { "InstanceList": [ { "InstanceId": "ld-xxx", "InstanceAlias": "实例名称", "InstanceStatus": "ACTIVATION", "ServiceType": "lindorm_v2", "InstanceStorage": "320", "VpcId": "vpc-xxx", "RegionId": "cn-shanghai", "EnableLts": true, "EnableStream": true, "EnableCompute": true, "EnableVector": false } ], "Total": 1 } ``` #### get-lindorm-instance → 查配置/版本/状态返回单个实例的详细配置，含引擎节点数/规格/版本，**不含连接地址**。 ```json { "InstanceId": "ld-xxx", "InstanceStatus": "ACTIVATION", "ServiceType": "lindorm_v2", "NetworkType": "vpc", "VpcId": "vpc-xxx", "DiskUsage": "15.3%", "DiskCategory": "cloud_essd", "EngineList": [ { "Engine": "lindorm", "CoreCount": "2", "CpuCount": "4", "MemorySize": "16GB", "Specification": "lindorm.g.xlarge", "Version": "2.8.6.4" }, { "Engine": "tsdb", "CoreCount": "2", "CpuCount": "4", "MemorySize": "16GB", "Specification": "lindorm.g.xlarge", "Version": "3.7.11" } ] } ``` #### get-lindorm-instance-engine-list → 查连接地址返回各引擎的连接地址和网络类型，**不含配置/节点数信息**。 ```json { "EngineList": [ { "EngineType": "lindorm", "NetInfoList": [ { "ConnectionString": "ld-xxx-proxy-lindorm.lindorm.rds.aliyuncs.com", "Port": 30020, "NetType": "2", "AccessType": 1 }, { "ConnectionString": "ld-xxx-proxy-lindorm.lindorm.rds.aliyuncs.com", "Port": 33060, "NetType": "2", "AccessType": 5 } ] }, { "EngineType": "tsdb", "NetInfoList": [ { "ConnectionString": "ld-xxx-proxy-tsdb.lindorm.rds.aliyuncs.com", "Port": 8242, "NetType": "2", "AccessType": 1 } ] } ] } ``` **NetType 说明**：`"2"` = 内网，`"0"` = 公网 #### get-instance-ip-white-list → 查 IP 白名单 ```json { "InstanceId": "ld-xxx", "GroupList": [ { "GroupName": "default", "SecurityIpList": "127.0.0.1" }, { "GroupName": "office", "SecurityIpList": "140.205.0.0/24" } ] } ``` #### get-lindorm-fs-used-detail → V1 存储详情 ```json { "FsCapacity": "429496729600", "FsUsedHot": "789543", "FsUsedCold": "0", "FsUsedOnLindormTable": "44093", "FsUsedOnLindormTSDB": "856", "FsUsedOnLindormSearch": "0", "FsUsedOnLindormTableData": "15452", "FsUsedOnLindormTableWAL": "10304", "LStorageUsageList": [ { "DiskType": "StandardCloudStorage", "Capacity": "429496729600", "Used": "912591424", "UsedLindormTable": "43694", "UsedLindormTsdb": "356", "UsedLindormSearch": "310515", "UsedLindormMessage3": "433856", "UsedOther": "911803003" } ], "Valid": "true" } ``` > 单位均为 bytes。 #### get-lindorm-v2-storage-usage → V2 存储详情 ```json { "CapacityByDiskCategory": [ { "category": "PERF_CLOUD_ESSD_PL1", "capacity": 960, "usedCapacity": 0, "mode": "CLOUD_STORAGE" }, { "category": "LOCAL_BUFFER", "capacity": 480, "usedCapacity": 0, "mode": "REMOTE_STORAGE" }, { "category": "REMOTE_CAP_OSS", "capacity": 100, "usedCapacity": 0, "mode": "REMOTE_STORAGE" } ], "UsageByDiskCategory": [ { "diskType": "PerformanceCloudStorage", "capacity": 1030792151040, "used": 2506614016, "usedLindormTable": 662244, "usedLindormTsdb": 159406, "usedLindormSearch3": 363609, "usedLindormColumn3": 228742, "usedLindormVector3": 441015, "usedLindormMessage3": 208236, "usedLindormSpark": 2240333801, "usedOther": 264216963 } ] } ``` > `CapacityByDiskCategory` 单位为 GB，`UsageByDiskCategory` 单位为 bytes。 --- ### 参数说明 #### `--region` 地域参数 | 地域 ID | 地域名称 | |---------|---------| | `cn-shanghai` | 华东2（上海）- 默认 | | `cn-beijing` | 华北2（北京） | | `cn-hangzhou` | 华东1（杭州） | | `cn-shenzhen` | 华南1（深圳） | | `cn-zhangjiakou` | 华北3（张家口） | | `cn-qingdao` | 华北1（青岛） | | `cn-wulanchabu` | 华北6（乌兰察布） | | `cn-guangzhou` | 华南3（广州） | | `cn-chengdu` | 西南1（成都） | #### `--instance-id` 实例 ID 格式：`ld-xxx`（以 ld- 开头，后接字母数字） #### `--service-type` 实例类型完整列表见 SKILL.md →「版本判断」 | 值 | 说明 | |----|------| | `lindorm` | Lindorm V1 单可用区实例 | | `lindorm_multizone` | Lindorm V1 多可用区实例 | | `lindorm_multizone_basic` | Lindorm V1 多可用区（基础版） | | `lindorm_v2` | Lindorm V2 单可用区实例 | | `lindorm_v2_multizone` | Lindorm V2 多可用区（基础版） | | `lindorm_v2_multizone_ha` | Lindorm V2 多可用区（高可用版） | | `serverless_lindorm` | Lindorm Serverless 实例 | | `lindorm_standalone` | Lindorm 单节点（开发测试） | #### `--support-engine` 引擎类型（位掩码） | 值 | 引擎代码 | 说明 | |----|---------|------| | `1` | 搜索引擎 | `solr` / `lsearch` | | `2` | 时序引擎 | `tsdb` | | `4` | 宽表引擎 | `lindorm` / `lcolumn` | | `8` | 文件引擎 | `file` | | `15` = 1+2+4+8 | 全部引擎 | 宽表 + 时序 + 搜索 + 文件 | #### 引擎类型详情引擎类型详情见 SKILL.md →「引擎类型详情」 --- ## 云监控 CLI **产品名**: `cms` **Namespace**: `acs_lindorm` ### 插件安装 ```bash # 安装云监控插件 aliyun plugin install --names cms ``` ### 查询命令 | CLI 命令 | 说明 | 必需参数 | |----------|------|---------| | `aliyun cms describe-metric-meta-list` | 查询指标列表 | `--namespace`, `--region` | `--region` 可选 | | `aliyun cms describe-metric-last` | 查询最新数据 | `--namespace`, `--metric-name`, `--dimensions` | `--region` 可选，通过 instanceId 自动定位 | | `aliyun cms describe-metric-data` | 查询历史数据 | `--namespace`, `--metric-name`, `--dimensions`, `--start-time`, `--end-time` | `--region` 可选，通过 instanceId 自动定位 | ### 执行示例 ```bash # 查询 Lindorm 监控指标列表 aliyun cms describe-metric-meta-list --namespace acs_lindorm # 查询 CPU 空闲率最新数据 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-uf6nbdlx5n34q6l6t"}]' # 查询内存使用率最新数据 aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name mem_used_percent \ --dimensions '[{"instanceId":"ld-uf6nbdlx5n34q6l6t"}]' # 查询历史监控数据（指定时间范围） aliyun cms describe-metric-data \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-uf6nbdlx5n34q6l6t"}]' \ --start-time "2026-04-14 08:00:00" \ --end-time "2026-04-14 09:00:00" \ --period 60 ``` ### 返回值结构 #### describe-metric-meta-list → 查指标列表 ```json { "Code": 200, "Resources": { "Resource": [ { "MetricName": "cpu_idle", "Namespace": "acs_lindorm", "Description": "CPU空闲率", "Unit": "%", "Periods": "60,300", "Dimensions": "userId,instanceId,host", "Statistics": "Average,Maximum,Minimum" } ] } } ``` #### describe-metric-last → 查最新数据 ```json { "Code": "200", "Period": "60", "Datapoints": "[{\"timestamp\":1776414660000,\"instanceId\":\"ld-xxx\",\"host\":\"table-1\",\"userId\":\"149xxx\",\"Average\":93.241,\"Maximum\":94.217,\"Minimum\":91.082}]" } ``` > 注意：`Datapoints` 是 JSON **字符串**，需要二次解析。每个数据点含 `host`（节点名）和 `userId`。 #### describe-metric-data → 查历史数据返回结构与 `describe-metric-last` 相同，`Datapoints` 含多个时间点的数据。 --- ### 参数说明 #### `--dimensions` 维度参数（JSON 数组） **格式说明**：Linux/macOS 用单引号包裹（无需转义），Windows CMD 用双引号+转义。 ```bash # ✅ Linux/macOS 推荐格式（单引号，无需转义） --dimensions '[{"instanceId":"ld-xxx"}]' # ✅ Windows CMD 格式（双引号+转义） --dimensions "[{\"instanceId\":\"ld-xxx\"}]" ``` 多维度示例： ```bash --dimensions "[{\"instanceId\":\"ld-xxx\"},{\"instanceId\":\"ld-yyy\"}]" ``` #### `--start-time` / `--end-time` 时间参数时间格式说明见 SKILL.md →「时间格式」 #### `--period` 采集周期（秒） | 值 | 说明 | |----|------| | `60` | 1 分钟（默认） | | `300` | 5 分钟 | | `900` | 15 分钟 | | `3600` | 1 小时 | --- 常用监控指标见 `references/02-ops/monitoring-guide.md` --- ## JMESPath 查询过滤使用 `--cli-query` 过滤输出： ```bash # 仅返回实例 ID 和名称 aliyun hitsdb get-lindorm-instance-list --region cn-shanghai \ --cli-query 'InstanceList[].[InstanceId,InstanceAlias,InstanceStatus]' # 仅返回特定实例的引擎类型（无需 --region） aliyun hitsdb get-lindorm-instance-engine-list \ --instance-id ld-uf6nbdlx5n34q6l6t \ --cli-query 'EngineList[].[EngineType,NetInfoList[0].ConnectionString]' # 仅返回监控数据平均值 aliyun cms describe-metric-last \ --namespace acs_lindorm --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-xxx"}]' \ --cli-query 'Datapoints' ``` --- ## 分页查询使用 `--pager` 合并多页结果： ```bash # 自动合并所有分页的实例列表 aliyun hitsdb get-lindorm-instance-list --region cn-shanghai --pager ``` --- ## 错误处理 | 错误信息 | 原因 | 解决方法 | |---------|------|---------| | `Instance.IsNotValid` | 实例 ID 无效或不存在 | 使用 `get-lindorm-instance-list --region ` 确认实例 ID | | `InvalidParameter.InstanceId` | 实例 ID 格式错误 | 使用 `ld-xxx` 格式 | | `InstanceNotFound` | 实例不存在 | 检查地域和实例 ID | | `Forbidden.RAM` | 权限不足 | 添加 `AliyunLindormReadOnlyAccess` 权限 | | `Throttling.User` | API 限流 | 降低调用频率或稍后重试 | --- ## 相关文档 - Lindorm API 文档：https://help.aliyun.com/zh/lindorm/developer-reference/api-reference - 云监控 API 文档：https://help.aliyun.com/zh/cms/developer-reference/api-reference - Aliyun CLI 安装指南：`./cli-installation-guide.md` - Lindorm CLI / HBase Shell 指南：`./lindorm-cli-guide.md` FILE:references/03-ref/verification-method.md # 验证方法执行操作后如何验证成功。 ## 实例查询验证 ### 验证实例列表查询成功 **作用**：查实例列表（ID、状态、引擎开关，支持按地域/类型筛选） ```bash aliyun hitsdb get-lindorm-instance-list --region cn-shanghai ``` **返回关键字段**： - `InstanceList[]`：InstanceId, InstanceAlias, InstanceStatus, ServiceType - `Enable*` 引擎开关：EnableLts, EnableStream, EnableCompute, EnableVector 等 - 不含连接地址、不含引擎节点数/规格 **成功标志**： - `InstanceList` 数组非空 **失败标志**： - `Forbidden.RAM`：权限不足 - `InvalidParameter`：参数错误 ### 验证实例详情查询成功 **作用**：查配置/版本/状态（ServiceType、引擎节点数、规格，**不含连接地址**） ```bash aliyun hitsdb get-lindorm-instance --instance-id ld-xxx ``` **返回关键字段**： - 实例信息：InstanceId, InstanceStatus, ServiceType, VpcId, DiskUsage - `EngineList[]`：Engine, CoreCount(节点数), CpuCount, MemorySize, Specification, Version - 不含连接地址（需连接地址请用 `get-lindorm-instance-engine-list`） **成功标志**： - `InstanceStatus` 为 `ACTIVATION` 表示运行中 **验证步骤**： 1. 检查 `InstanceId` 与请求参数一致 2. 检查 `ServiceType` 判断 V1(`lindorm`)/V2(`lindorm_v2`) 3. 检查 `EngineList` 引擎列表的节点数和规格 ## 监控查询验证 ### 验证指标列表查询成功 ```bash aliyun cms describe-metric-meta-list --namespace acs_lindorm ``` **成功标志**： - 返回 JSON 包含 `Resources` 数组 - 数组中包含指标对象，包含 `MetricName`, `Namespace`, `Description` 等字段 ### 验证监控数据查询成功 ```bash aliyun cms describe-metric-last \ --namespace acs_lindorm \ --metric-name cpu_idle \ --dimensions '[{"instanceId":"ld-xxx"}]' ``` **成功标志**： - 返回 JSON 包含 `Datapoints` 字段 - `Datapoints` 包含数据点，包含 `instanceId`, `timestamp`, `Average` 等字段 - `Code` 为 `200` 表示成功 **验证步骤**： 1. 检查 `Datapoints` 字段不为空 2. 检查数据点中的 `instanceId` 与请求参数一致 3. 检查 `Average` 字段的数值范围合理（如 CPU 空闲率 0-100） ## 存储查询验证 ### 验证存储详情查询成功 ```bash # V1 实例 aliyun hitsdb get-lindorm-fs-used-detail --instance-id ld-xxx # V2 实例 aliyun hitsdb get-lindorm-v2-storage-usage --instance-id ld-xxx ``` **成功标志**： - 返回 JSON 包含存储容量相关字段 - 数值单位为 bytes ## IP 白名单验证 ### 验证白名单查询成功 ```bash aliyun hitsdb get-instance-ip-white-list --instance-id ld-xxx ``` **成功标志**： - 返回 JSON 包含 `GroupList` 数组 - 数组中包含 IP 地址或 CIDR 格式的白名单规则 ## 连接验证 ### 验证网络连通性使用 telnet 或 nc 测试端口连通性： ```bash # 测试 MySQL 协议端口（33060） telnet 33060 # 测试 HBase API 端口（30020） telnet 30020 # 测试时序引擎 HTTP 端口（8242） curl http://:8242/api/v2/status ``` **成功标志**： - telnet 显示 "Connected to xxx" - curl 返回正常状态响应 ## 验证清单执行任何操作后，按以下清单验证： | 操作 | 验证命令 | 成功标志 | |------|---------|---------| | 查实例列表 | `aliyun hitsdb get-lindorm-instance-list` | `InstanceList` 数组非空，含 InstanceId/Status/Enable* | | 查配置/状态 | `aliyun hitsdb get-lindorm-instance` | `EngineList` 含 CoreCount/Specification/Version（不含连接地址） | | 查连接地址 | `aliyun hitsdb get-lindorm-instance-engine-list` | `NetInfoList` 含 ConnectionString/Port/NetType | | 查询存储详情 | `aliyun hitsdb get-lindorm-fs-used-detail` | 包含存储容量数据 | | 查询 IP 白名单 | `aliyun hitsdb get-instance-ip-white-list` | 包含白名单规则 | | 查询监控指标 | `aliyun cms describe-metric-meta-list` | `Resources` 数组非空 | | 查询监控数据 | `aliyun cms describe-metric-last` | `Datapoints` 字段非空 |

Alibabacloud Lindorm Agent Skill

Comments (0)