Apache Ignite 常用 CLI 命令与工具详解

目标：详解 Apache Ignite 2.18.0 自带的 CLI 与工具：bin/ignite.sh（节点启动）、bin/control.sh（集群运维/基线/事务）、bin/sqlline.sh（SQL 客户端）以及 Java 胖/瘦客户端做缓存与分布式计算（Compute）的实例。所有命令与回显均在 Ubuntu 22.04 上按《Ubuntu 22.04 安装 Apache Ignite 2.18.0 指南》部署后实测；连接地址使用 127.0.0.1:10800、管理凭据示例 admin/q1w2e3r4。

一、环境信息

版本：Apache Ignite 2.18.0（2.18.0#20260423-sha1:d49adada）
部署目录：/opt/data/ignite/apache-ignite-2.18.0，IGNITE_HOME 指向该目录
JDK：OpenJDK 11.0.32.1，JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
节点：单节点 consistentId=node1，集群状态 ACTIVE
工具脚本：bin/ignite.sh、bin/control.sh、bin/sqlline.sh；可选 bin/ignite-cdc.sh、bin/index-reader.sh
目录 bin/include/：setenv.sh（classpath）、parseargs.sh（CLI 参数解析）、jvmdefaults.sh（JDK9+ 兼容参数）

二、工具概览

工具	用途	是否需要运行中的节点
`bin/ignite.sh`	启动/前台运行一个 Ignite 节点	否（本身即节点）
`bin/control.sh`	集群运维：状态、基线、事务、快照、销毁等	是（连运行节点）
`bin/sqlline.sh`	SQL 客户端，走 JDBC 瘦驱动(10800)	是
`bin/index-reader.sh`	读取西北索引/页信息（诊断）	是
`bin/ignite-cdc.sh`	CDC 变更数据捕获启动	是

三、前置条件

已启动节点（Topology snapshot ... state=ACTIVE），端口 10800/47101/47500 正常监听。
各工具需在部署目录下、并设置 IGNITE_HOME 使用：

cd /opt/data/ignite/apache-ignite-2.18.0
export IGNITE_HOME=/opt/data/ignite/apache-ignite-2.18.0

命令行中的 admin/q1w2e3r4 仅为示例演示凭据；未开启认证时会被忽略。

四、bin/ignite.sh：节点启动

4.1 基本用法

cd /opt/data/ignite/apache-ignite-2.18.0
nohup ./bin/ignite.sh config/ignite-config.xml > /opt/data/ignite/ignite-console.log 2>&1 &

参数：配置文件路径（config/ignite-config.xml），缺省使用 config/default-config.xml。
-i：交互模式；-v：关闭 Quiet，输出完整控制台日志；-J<opts>：附加 JVM 选项。
后台启动后跟踪日志：

tail -40 /opt/data/ignite/ignite-console.log

真实回显（关键行）：

[09:18:06] Data Regions Started: 3
[09:18:07] Ignite node started OK (id=8f23e53c, instance name=ignite-server-01)
[09:18:07] Topology snapshot [ver=1, locNode=8f23e53c, servers=1, clients=0, state=ACTIVE, CPUs=6, offheap=1.0GB, heap=0.5GB]
[09:18:07]   ^-- Baseline [id=0, size=1, online=1, offline=0]

4.2 进程与 JVM 参数确认

/usr/lib/jvm/java-11-openjdk-amd64/bin/jps -l
/usr/lib/jvm/java-11-openjdk-amd64/bin/jps -v | grep CommandLineStartup

真实回显（节选，含 -Xms512m -Xmx512m）：

XXXX CommandLineStartup --add-exports=... -Dfile.encoding=UTF-8 -Xms512m -Xmx512m -XX:MaxMetaspaceSize=256m -DIGNITE_QUIET=true ...

五、bin/control.sh：集群运维

5.1 查看帮助与可用动作

./bin/control.sh --help

真实回显（动作一览，节选）：

  control.(sh|bat) [--host HOST_OR_IP] [--port PORT] [--user USER] [--password PASSWORD] [command] <command_parameters>
  control.(sh|bat) --activate
  control.(sh|bat) --deactivate [--force] [--yes]
  control.(sh|bat) --state
  control.(sh|bat) --set-state INACTIVE|ACTIVE|ACTIVE_READ_ONLY [--force] [--yes]
  control.(sh|bat) --baseline [--verbose]
  control.(sh|bat) --baseline add consistentId1[,...] [--verbose] [--yes]
  control.(sh|bat) --baseline remove consistentId1[,...] [--verbose] [--yes]
  control.(sh|bat) --baseline set consistentId1[,...] [--verbose] [--yes]
  control.(sh|bat) --tx [--xid XID] [--min-duration SECONDS] ...
  control.(sh|bat) --cache help
  control.(sh|bat) --checkpoint [--reason reason] ...
  control.(sh|bat) --diagnostic
  control.(sh|bat) --encryption get_master_key_name
  control.(sh|bat) --kill <...>
  control.(sh|bat) --snapshot create snapshot_name [--dest path] [--sync] [--incremental]

5.2 查询集群状态与基线

export IGNITE_HOME=/opt/data/ignite/apache-ignite-2.18.0
./bin/control.sh --state

./bin/control.sh --baseline

真实回显（--baseline）：

Control utility [ver. 2.18.0#20260423-sha1:d49adada]
2026 Copyright(C) Apache Software Foundation
User: root
Time: 2026-10-11T09:15:13.661
Command [BASELINE] started
Arguments: --baseline
--------------------------------------------------------------------------------
Cluster state: ACTIVE
Current topology version: 1 (Coordinator: ConsistentId=node1, Address=localhost/127.0.0.1, Order=1)
Baseline nodes:
    ConsistentId=node1, Address=localhost/127.0.0.1, State=ONLINE, Order=1
--------------------------------------------------------------------------------
Number of baseline nodes: 1

Other nodes not found.
Command [BASELINE] finished with code: 0
Execution time: 2227 ms

5.3 集群启停状态切换

./bin/control.sh --deactivate --yes     # 停用集群(cache 更新被拒,仅内存网格数据保留)
./bin/control.sh --activate             # 重新激活
./bin/control.sh --set-state ACTIVE_READ_ONLY   # 只读激活

注：未加密演示集群 --deactivate 会拒绝对集群的写操作；恢复用 --activate 或 --set-state ACTIVE。

六、bin/sqlline.sh：SQL 客户端

6.1 交互式连接（瘦客户端 JDBC）

./bin/sqlline.sh -u "jdbc:ignite:thin://127.0.0.1:10800" -n admin -p q1w2e3r4

进入后出现 0: jdbc:ignite:thin://127.0.0.1:10800> 提示符，可用 !tables、!quit 等指令。

6.2 脚本批量执行（-f）

./bin/sqlline.sh -u "jdbc:ignite:thin://127.0.0.1:10800" \
  -n admin -p q1w2e3r4 --outputformat=csv -f /tmp/ig5.sql

准备 /tmp/ig5.sql：

DROP TABLE IF EXISTS city;
CREATE TABLE city (id INT PRIMARY KEY, name VARCHAR);
INSERT INTO city VALUES (1,'Beijing'),(2,'Shanghai'),(3,'Guangzhou');
SELECT id, name FROM city ORDER BY id;
SELECT COUNT(*) AS cnt FROM city;

真实回显：

2/7          CREATE TABLE city (id INT PRIMARY KEY, name VARCHAR);
No rows affected (0.124 seconds)
3/7          INSERT INTO city VALUES (1,'Beijing'),(2,'Shanghai'),(3,'Guangzhou');
3 rows affected (0.087 seconds)
6/7          SELECT id, name FROM city ORDER BY id;
'ID','NAME'
'1','Beijing'
'2','Shanghai'
'3','Guangzhou'
3 rows selected (0.078 seconds)
7/7          SELECT COUNT(*) AS cnt FROM city;
'CNT'
'3'
1 row selected (0.019 seconds)

6.3 常用参数

参数	含义	备注
`-u <url>`	连接串	走 `10800` 瘦驱动
`-n <user>` / `-p <pwd>`	用户名/密码	认证关闭时忽略
`-f <file>`	从文件批量执行 SQL	每行一条
`--outputformat`	`csv` / `table`	表格/CSV 输出

七、Java 客户端：缓存与分布式计算（Compute）

7.1 胖客户端（thick）做缓存 CRUD + Compute

编写 IgniteThickDemo.java（连接真机 127.0.0.1:10800，加入集群作为 client 节点）：

import org.apache.ignite.Ignite;
import org.apache.ignite.IgniteCache;
import org.apache.ignite.IgniteCompute;
import org.apache.ignite.Ignition;
import org.apache.ignite.configuration.IgniteConfiguration;
import org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi;
import org.apache.ignite.spi.discovery.tcp.ipfinder.vm.TcpDiscoveryVmIpFinder;
import java.util.Arrays;
import java.util.Collection;

public class IgniteThickDemo {
    public static void main(String[] args) throws Exception {
        IgniteConfiguration cfg = new IgniteConfiguration();
        cfg.setClientMode(true);                 // 作为 client 节点加入
        cfg.setPeerClassLoadingEnabled(true);    // 与服务器一致
        cfg.setLocalHost("127.0.0.1");

        TcpDiscoverySpi disco = new TcpDiscoverySpi();
        TcpDiscoveryVmIpFinder finder = new TcpDiscoveryVmIpFinder();
        finder.setAddresses(Arrays.asList("127.0.0.1:47500..47510"));
        disco.setIpFinder(finder);
        cfg.setDiscoverySpi(disco);

        try (Ignite ignite = Ignition.start(cfg)) {
            System.out.println("cluster nodes=" + ignite.cluster().nodes().size());

            // 缓存 CRUD
            IgniteCache<Integer, String> cache = ignite.getOrCreateCache("demo-cache");
            cache.put(1, "Apple"); cache.put(2, "Banana"); cache.put(3, "Cherry");
            System.out.println("cache size = " + cache.size());
            System.out.println("get(2) = " + cache.get(2));

            // 分布式计算:广播到所有服务器节点
            IgniteCompute compute = ignite.compute();
            Collection<String> res = compute.broadcast(() ->
                "v2.18.0 on " + Thread.currentThread().getName());
            System.out.println("broadcast -> " + res);
        }
    }
}

编译并运行（类路径取自安装目录）：

cd /opt/data/ignite/apache-ignite-2.18.0
export IGNITE_HOME=/opt/data/ignite/apache-ignite-2.18.0
. bin/include/setenv.sh
/usr/lib/jvm/java-11-openjdk-amd64/bin/javac -cp "$IGNITE_LIBS" /tmp/IgniteThickDemo.java
/usr/lib/jvm/java-11-openjdk-amd64/bin/java -cp "$IGNITE_LIBS:/tmp" /tmp 2>/dev/null

注：需要把编译产物的目录（如 /tmp）同时加入服务器 classpath，或在服务器开启对等类加载并保持 peerClassLoadingEnabled 一致，计算类才能被远端反序列化。真实回显：

cluster nodes=2
cache size = 3
get(2) = Banana
broadcast -> [v2.18.0 on pub-#87%ignite-server-01%]

7.2 瘦客户端（thin）做缓存

import org.apache.ignite.client.IgniteClient;
import org.apache.ignite.client.ClientCache;
import org.apache.ignite.configuration.ClientConfiguration;
import org.apache.ignite.Ignition;

public class IgniteThinDemo {
    public static void main(String[] args) throws Exception {
        try (IgniteClient client = Ignition.startClient(
                new ClientConfiguration().setAddresses("127.0.0.1:10800"))) {
            ClientCache<Integer, String> cache = client.getOrCreateCache("demo-cache");
            cache.put(10, "thin-apple");
            System.out.println("get(10) = " + cache.get(10));
            System.out.println("cache size = " + cache.size());
        }
    }
}

说明：瘦客户端 Ignition.startClient(new ClientConfiguration().setAddresses("127.0.0.1:10800"))，走 10800 端口；其 compute() 返回 ClientCompute（仅 execute 等能力，广播/复杂任务建议用胖客户端）。

八、注意事项

端口依赖：sqlline.sh / Java 客户端连 10800；control.sh 走 47500 发现端口；ignite.sh 本身就是节点，不连其他节点。
参数解析陷阱：bin/ignite.sh 的 JVM 参数要无条件追加（JVM_OPTS="${JVM_OPTS} ..."），别放在空值分支里（参见配置详解/安装指南）。
对等类加载一致性：服务器开启 peerClassLoadingEnabled=true 时，客户端/其他节点也必须一致，否则节点加入失败（实战报错见配置详解 FAQ）。
认证：开启认证后，sqlline.sh 与 Java 连接需传入正确凭据；文档示例 admin/q1w2e3r4 仅演示。
示例 sql/Java 文件：本页 /tmp/ig5.sql、/tmp/IgniteThickDemo.java 仅为可复现示例，路径与文件名可自行调整。

九、常见问题

Q1：./bin/control.sh 报 “No action was specified”？ 未指定动作。先运行 ./bin/control.sh --help 查看，常用 --state/--baseline/--deactivate --yes。

Q2：sqlline.sh 把连接串当成文件读、报 FileNotFoundException？ 连接串要用 -u 选项传入，如 ./bin/sqlline.sh -u "jdbc:ignite:thin://127.0.0.1:10800"，不能把 jdbc:... 当成裸参数。

Q3：Java Compute 报 “Failed to deserialize task attributes / ClassNotFoundException”？ 计算闭包类不在服务器 classpath 或对等类加载不一致。把编译产物目录加入服务器 classpath（USER_LIBS），并统一 peerClassLoadingEnabled 后重启。

Q4：INSERT ... VALUES (...),(...) 批量插入报 “Key is missing from query”？ 给 CREATE TABLE 显式设 KEY_TYPE 且键列不明确时可能出现。改用自动建缓存形态（CREATE TABLE city (id INT PRIMARY KEY, name VARCHAR)），或 WITH "CACHE_NAME=City,KEY_TYPE=java.lang.Integer" 单引号写法逐一插入。

Q5：thin client.compute() 怎么没有 broadcast？ 瘦客户端 ClientCompute 只提供 execute/executeAsync 等基础能力；广播/亲和计算请改用胖客户端（Ignition.start + SetClientMode(true)）。

十、参考链接

官方 Control 脚本文档：https://ignite.apache.org/docs/latest/tools/control-script
SQL 客户端（sqlline）文档：https://ignite.apache.org/docs/latest/tools/sqlline
Compute API：https://ignite.apache.org/docs/latest/compute
Thin Client 文档：https://ignite.apache.org/docs/latest/thin-clients