linux下安装Elasticsearch

发表于 更新于 分类于 ， ， 置顶 精品
阅读次数： 本文字数： 5.8k 阅读时长 ≈ 21 分钟

摘要

  • 本文介绍如何在linux下安装Elasticsearch

  • Elasticsearch版本8.17.3

下载

1
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.17.3-linux-x86_64.tar.gz

  • 下载完成后解压到/usr/local/elasticsearch目录下，解压命令如下：

1
2
mkdir /usr/local/elasticsearch
tar -zxvf elasticsearch-8.17.3-linux-x86_64.tar.gz -C /usr/local/elasticsearch

ElasticSearch目录结构

1
2
3
4
5
6
7
8
bin        # 脚本文件，包括启动elasticsearch，安装插件，运行统计数据等
config     # 配置文件目录，如elasticsearch配置、角色配置、jvm配置、证书等。
data       # 数据目录，默认值 $ES_HOME/data，包含节点、分片、索引、文档的所有数据，生产环境建议修改
jdk        # JDK目录，用于运行Elasticsearch，7.x以后自带
lib        # Elasticsearch依赖的JAR包
logs       # 日志目录，默认值 $ES_HOME/logs，生产环境建议修改
modules    # 包含所有的Elasticsearch模块，如Cluster、Discovery、Indices等
plugins    # 已安装插件目录

创建启动用户

  • elasticsearch和kibana都不能用root用户启动

  • 创建用户elastic，并设置密码

1
2
useradd elastic
passwd elastic

  • 修改elasticsearch安装目录的用户权限

1
chown -R elastic:elastic /usr/local/elasticsearch

配置环境变量

  • 进入elastic用户主目录，/home/elastic目录下，设置用户级别的环境变量

1
2
# 切换到elastic用户
su - elastic

  • vim .bash_profile

1
2
3
4
# Elasticsearch安装目录，它用于定位Elasticsearch的配置文件、插件和其他相关资源。
export ES_HOME=/usr/local/elasticsearch/elasticsearch-8.17.3
# Elasticsearch使用的JDK安装目录，在启动Elasticsearch时，它会检查ES_JAVA_HOME环境变量并使用其中的Java路径。
export ES_JAVA_HOME=/usr/local/elasticsearch/elasticsearch-8.17.3/jdk/

  • 执行以下命令使配置生效

1
source .bash_profile

配置JVM参数（可选）

  • ES比较耗内存，建议虚拟机4G或以上内存，jvm1g以上的内存分配

  • 进入/usr/local/elasticsearch/elasticsearch-8.17.3/config目录，修改jvm.options文件，调整jvm堆内存大小

1
2
-Xms4g # 设置最小堆内存，默认4g，不能小于1g
-Xmx4g # 设置最大堆内存，默认4g，Xmx不要超过机器内存的50%，不要超过30g

创建数据和日志存储目录

1
2
3
4
# 切换到elastic用户
su - elastic
# 创建目录
mkdir /usr/local/elasticsearch/data /usr/local/elasticsearch/log

配置启动文件

  • 进入/usr/local/elasticsearch/elasticsearch-8.17.3/config目录，修改elasticsearch.yml文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 集群名称，多个节点如果要组成同一个集群，那么集群名称一定要配置成相同，默认值elasticsearch
cluster.name: test-elk
# 节点名称，默认值当前节点部署所在机器的主机名
node.name: node-1
# 数据存储路径，默认值 $ES_HOME/data
path.data: /usr/local/elasticsearch/data
# 日志存储路径，默认值 $ES_HOME/logs
path.logs: /usr/local/elasticsearch/logs
# 配置ES启动时是否进行内存锁定检查，默认值true，本机内存比较小时设置为false
bootstrap.memory_lock: false
# 允许通过任何地址访问，开启远程访问
network.host: 0.0.0.0
# 配置当前ES节点对外提供服务的http端口，默认 9200
http.port: 9200
# 配置当前ES节点对外提供服务的tcp端口，默认 9300
transport.port: 9300
# 集群内的主机列表
discovery.seed_hosts: ["127.0.0.1"]
# 第一次启动时需要参与选主的节点名称
cluster.initial_master_nodes: ["node-1"]

#解决跨域问题
http.cors.enabled: true
http.cors.allow-origin: "*"

启动ElasticSearch服务

  • 进入/usr/local/elasticsearch/elasticsearch-8.17.3目录，执行以下命令启动服务

1
2
3
./bin/elasticsearch
# 后台启动
./bin/elasticsearch -d

ES启动前的引导检查

  • ES启动时，默认会进行引导检查，所谓引导检查就是在服务启动之前对一些重要的配置项进行检查，检查其配置值是否是合理的。引导检查包括对JVM大小、内存锁、虚拟内存、最大线程数、集群发现相关配置等相关的检查，如果某一项或者几项的配置不合理，ES会拒绝启动服务。

  • 如果启动服务时，报以下错误，则需要解决引导检查中的问题

  • 1.max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144];

    • 原因：最大虚拟内存太小,调大系统的虚拟内存
    • 解决办法：
    1
    2
    3
    4
    5
    6
    # root用户下运行
    vim /etc/sysctl.conf
    # 追加以下内容：
    vm.max_map_count=262144
    # 保存退出之后执行如下命令：
    sysctl -p

  • 2.max file descriptors [4096] for elasticsearch process is too low, increase to at least [65536]

    • 原因：文件描述符太小，调大系统的文件描述符
    • 解决办法：
    1
    2
    3
    4
    5
    6
    7
    # root用户下运行
    vim /etc/security/limits.conf
    # 末尾添加如下配置：
    * soft nofile 65536
    * hard nofile 65536
    * soft nproc 4096
    * hard nproc 4096

  • 如果只是单节点的开发环境，则可以关闭引导检查，生成环境不建议这样做，因为关闭引导检查后，ES服务将无法保证集群的高可用性。

1
2
3
4
5
# 进入elasticsearch安装目录
vim config/elasticsearch.yml
# 添加如下配置：
# 指定节点为单节点，可以绕过引导检查
discovery.type: single-node

服务正常启动后仍然不能正常访问

  • 访问服务

1
2
curl http://127.0.0.1:9200
curl: (52) Empty reply from server

  • 查看日志/usr/local/elasticsearch/elasticsearch-8.17.3/logs/test-elk.log，发现报如下警告：

1
[WARN ][o.e.h.n.Netty4HttpServerTransport] [node-1] received plaintext http traffic on an https channel, closing connection Netty4HttpChannel{localAddress=/127.0.0.1:9200, remoteAddress=/127.0.0.1:38426}

  • 原因是ES在启动服务时默认开启了 X-Pack 安全功能，查看配置文件/usr/local/elasticsearch/elasticsearch-8.17.3/config/elasticsearch.yml，发现配置项xpack.security.xxx相关配置项被自动添加了，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
#----------------------- BEGIN SECURITY AUTO CONFIGURATION -----------------------
#
# The following settings, TLS certificates, and keys have been automatically
# generated to configure Elasticsearch security features on 20-03-2025 08:53:20
#
# --------------------------------------------------------------------------------

# Enable security features
# 启用 Elasticsearch 的安全特性，包括用户认证、角色管理、加密等。
# 开启了 X-Pack 安全功能，这意味着你需要进行用户认证才能访问 Elasticsearch。
# 如果需要关闭 X-Pack 安全功能，你可以将 xpack.security.enabled 设置为 false。
xpack.security.enabled: true
# 启用安全注册功能，允许通过交互式向导来配置安全设置。
# 这使得你可以通过 Kibana 或命令行工具来自动配置 SSL 证书和其他安全设置。
xpack.security.enrollment.enabled: true

# Enable encryption for HTTP API client connections, such as Kibana, Logstash, and Agents
# 启用 HTTP API 客户端连接的加密
# Kibana、Logstash 和其他通过 HTTP API 连接到 Elasticsearch 的客户端将使用 HTTPS 进行通信，增强安全性。
xpack.security.http.ssl:
  enabled: true # 启用 HTTP 层的 SSL 加密，即https访问，确保客户端与 Elasticsearch 之间的通信是加密的。设置为false时，关闭加密，即http访问
  keystore.path: certs/http.p12 # 指定用于 HTTP 层加密的密钥库文件路径。这是一个 PKCS12 文件，包含用于加密和验证的公钥和私钥。

# Enable encryption and mutual authentication between cluster nodes
# 启用节点间的加密和双向认证
# Elasticsearch 集群中的节点之间的通信将使用 SSL 加密，并且每个节点都会验证其他节点的身份，从而增强集群的安全性。
# 所有节点要配置相同的证书
xpack.security.transport.ssl:
  enabled: true # 启用传输层的 SSL 加密，确保节点之间的内部通信是加密的。
  verification_mode: certificate # 设置验证模式为 certificate，这意味着节点之间需要双向认证（即每个节点都需要验证对方的身份）。
  keystore.path: certs/transport.p12 # 指定用于传输层加密的密钥库文件路径。这是另一个 PKCS12 文件，包含用于加密和验证的公钥和私钥。
  truststore.path: certs/transport.p12 # 指定用于存储信任证书的信任库文件路径。这通常与密钥库相同，但可以不同。
#----------------------- END SECURITY AUTO CONFIGURATION -------------------------

  • 解决方法：

    • 1.不想开启安全认证，将 xpack.security.enabled 设置为 false，这样即便下面的配置都设置为true也不会有效。
    • 2.不想https访问，将 xpack.security.http.ssl.enabled 设置为 false，但这样会导致无法通过认证Token添加其它节点或Kibana。
    • 3.不想节点间通信加密，将 xpack.security.transport.ssl.enabled 设置为 false

  • 为了保证ES的安全，我这里就开启安全认证，并且通过https访问ES，但此时我们访问ES的API就需要带上认证用户，那么用户名和密码是什么呢？

  • 实际上在ES第一次正常启动时其日志中就打印了自动配置的安全相关的信息提示，里面就给出了登录用户和初始的密码，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 这些日志信息提供了 Elasticsearch 8 在首次启动时自动配置的安全特性、生成的默认密码、证书指纹以及如何配置 Kibana 和其他节点加入集群的详细说明。
✅ Elasticsearch security features have been automatically configured!
✅ Authentication is enabled and cluster connections are encrypted.

# 这是 elastic 用户的默认密码。系统建议你使用 bin/elasticsearch-reset-password -u elastic 命令来重置此密码。
ℹ️  Password for the elastic user (reset with `bin/elasticsearch-reset-password -u elastic`):
  BNb=*qz6_M*mXL9uZiSP # 这里会打印出ES自动生成的密码

# 这是 HTTP CA 证书的 SHA-256 指纹。CA 证书用于验证 HTTPS 连接的身份。
ℹ️  HTTP CA certificate SHA-256 fingerprint:
  3f141c16dfc6e165894bc1672084b220dcdd22ffe02116d51ac18003cfaa5a1d

# 提供了将 Kibana 配置为使用此 Elasticsearch 集群的步骤。
ℹ️  Configure Kibana to use this cluster:
# 启动 Kibana 并按照终端中显示的配置链接进行操作。
• Run Kibana and click the configuration link in the terminal when Kibana starts.
# 复制提供的注册令牌，并在浏览器中打开 Kibana 时粘贴此令牌。令牌在接下来的 30 分钟内有效。
# 补充说明：生成新的kibana注册令牌：bin/elasticsearch-create-enrollment-token -s kibana
• Copy the following enrollment token and paste it into Kibana in your browser (valid for the next 30 minutes):
  eyJ2ZXIiOiI4LjE0LjAiLCJhZHIiOlsiMTAuMjUwLjAuMjM5OjkyMDAiXSwiZmdyIjoiM2YxNDFjMTZkZmM2ZTE2NTg5NGJjMTY3MjA4NGIyMjBkY2RkMjJmZmUwMjExNmQ1MWFjMTgwMDNjZmFhNWExZCIsImtleSI6ImFSWFBzcFVCTVVmc1d5aUJnbjBtOmRzbVBLQV95UXhDZkJpXzQyWDNEMVEifQ==

# 提供了将新的 Elasticsearch 节点加入现有集群的步骤。
ℹ️ Configure other nodes to join this cluster:
# 使用 bin/elasticsearch --enrollment-token <token> 命令启动新的 Elasticsearch 节点。令牌在接下来的 30 分钟内有效。
# 补充说明：生成新的节点注册令牌：bin/elasticsearch-create-enrollment-token -s node
• Copy the following enrollment token and start new Elasticsearch nodes with `bin/elasticsearch --enrollment-token <token>` (valid for the next 30 minutes):
  eyJ2ZXIiOiI4LjE0LjAiLCJhZHIiOlsiMTAuMjUwLjAuMjM5OjkyMDAiXSwiZmdyIjoiM2YxNDFjMTZkZmM2ZTE2NTg5NGJjMTY3MjA4NGIyMjBkY2RkMjJmZmUwMjExNmQ1MWFjMTgwMDNjZmFhNWExZCIsImtleSI6ImF4WFBzcFVCTVVmc1d5aUJnbjFtOkFEallPdnpzUzh1MGJqOFpfVFE4a3cifQ==
# 如果你在 Docker 中运行 Elasticsearch，可以使用 docker run -e "ENROLLMENT_TOKEN=<token>" docker.elastic.co/elasticsearch/elasticsearch:8.17.3 命令启动新节点。
  If you're running in Docker, copy the enrollment token and run:
  `docker run -e "ENROLLMENT_TOKEN=<token>" docker.elastic.co/elasticsearch/elasticsearch:8.17.3`
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  • 登录用户为elastic[其角色为超级用户]，我们可以通过日志查看初始的密码，也可以通过如下命令重置密码

1
2
3
4
# 重置密码，密码自动生成
bin/elasticsearch-reset-password -u elastic
# 重置密码，自己输入要设置的密码，比如我这里这是为 123456
bin/elasticsearch-reset-password -u elastic -i

  • curl 访问ES服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# -k 忽略证书校验
curl -u elastic:123456 -k https://127.0.0.1:9200
# 或者 将认证信息通过header传递，elastic:123456 通过base64加密
curl -k https://127.0.0.1:9200 -H 'Authorization: Basic ZWxhc3RpYzoxMjM0NTY='
# 也可以通过证书访问https服务，这个证书就是ES在开启安全认证启动时自动生成的
curl -u elastic:123456 --cacert /usr/local/elasticsearch/elasticsearch-8.17.3/config/certs/http_ca.crt  https://127.0.0.1:9200
# 输出如下：
{
  "name" : "node-1",
  "cluster_name" : "test-elk",
  "cluster_uuid" : "RykjCSPnSCi4Hsi37uziWw",
  "version" : {
    "number" : "8.17.3",
    "build_flavor" : "default",
    "build_type" : "tar",
    "build_hash" : "a091390de485bd4b127884f7e565c0cad59b10d2",
    "build_date" : "2025-02-28T10:07:26.089129809Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.0",
    "minimum_wire_compatibility_version" : "7.17.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "You Know, for Search"
}

开发模式和生产模式

  • 开发模式：如果用户只是出于学习目的，可以在配置文件中添加 discovery.type=single-node ，表示单节点模式，即开发模式。此模式可以绕过引导检查。
  • 生产模式：当用户配置了有关集群的相关配置项时就会触发生产模式，在生产模式下，服务启动会触发ES的引导检查或者叫启动检查（bootstrap checks），引导检查十分严格，即某些检查项不通过则ES服务将无法启动。
    • 引导检查：在服务启动之前对一些重要的配置项进行检查，检查其配置值是否是合理的。引导检查包括对JVM大小、内存锁、虚拟内存、最大线程数、集群发现相关配置等相关的检查，如果某一项或者几项的配置不合理，ES会拒绝启动服务，并且在开发模式下的某些警告信息会升级成错误信息输出。引导检查十分严格，之所以宁可拒绝服务也要阻止用户启动服务是为了防止用户在对ES的基本使用不了解的前提下启动服务而导致的后期性能问题无法解决或者解决起来很麻烦。因为一旦服务以某种不合理的配置启动，时间久了之后可能会产生较大的性能问题，但此时集群已经变得难以维护和扩展，ES为了避免这种情况而做出了引导检查的设置，本来在开发模式下为警告的启动日志会升级为报错（Error）。这种设定虽然增加了用户的使用门槛，但是避免了日后产生更大的问题。

ES浏览器插件

  • Elasticvue : chrome/edge 插件，用于在浏览器中查看ES集群信息，功能非常强大

ES自启动脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 创建服务文件
$ vim /usr/lib/systemd/system/es.service
[Unit]
Description=elasticsearch
Documentation=https://www.elastic.co
After=network.target

[Service]
Type=simple
PrivateTmp=true
# 指定ES用户
User=elastic
Group=elastic
LimitNOFILE=100000
LimitNPROC=100000
Restart=yes
# 启动命令
ExecStart=/usr/local/elasticsearch/elasticsearch-8.17.3/bin/elasticsearch
ExecRestart=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s QUIT $MAINPID

[Install]
WantedBy=multi-user.target

# 重新加载
$ systemctl daemon-reload

# 启动
$ systemctl start es
# 停止
$ systemctl stop es
# 查看状态
$ systemctl status es
# 设置开机启动
$ systemctl enable es

通过ApiKey访问ES

  • 关于ApiKey的详细介绍，可以参考官方文档

  • 创建ApiKey

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl -k 'https://127.0.0.1:9200/_security/api_key?pretty' \
-u elastic:123456 \
--header 'Content-Type: application/json' \
--data '{
    "name": "elastic_api_key",
    "expiration": "1d"
}'
# 请求参数说明：
# name: ApiKey的名称
# expiration: ApiKey的过期时间，这里设置为一天，如果不设置，则永不过期
# 请求参数中还有一个重要的参数 `role_descriptors`，其含义是，指定ApiKey所拥有的权限，即角色。如果不进行设置，则默认使用当前认证用户的的角色
# metadata: ApiKey的元数据，即自定义的键值对，这里可以不设置

# 输出：
{
  "id":"70It0ZUBrL2GcOxX0d1L",
  "name":"elastic_api_key",
  "expiration":1743057595723,
  "api_key":"s85lqVkmQISkBlgXCTJmDQ",
  "encoded":"NzBJdDBaVUJyTDJHY094WDBkMUw6czg1bHFWa21RSVNrQmxnWENUSm1EUQ=="
}
# 输出参数说明：
# id: ApiKey的id
# name: ApiKey的名称
# expiration: ApiKey的过期时间，单位为毫秒
# api_key: ApiKey的密钥
# encoded: 对 `id:api_key` 进行base64编码，即可得到 `encoded`
    # echo -n '70It0ZUBrL2GcOxX0d1L:s85lqVkmQISkBlgXCTJmDQ' | base64
    # 输出：
    # NzBJdDBaVUJyTDJHY094WDBkMUw6czg1bHFWa21RSVNrQmxnWENUSm1EUQ==

  • 使用ApiKey访问ES

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 这里的ApiKey，就是上面输出的encoded
curl -k 'https://127.0.0.1:9200?pretty' \
-H 'Authorization: ApiKey NzBJdDBaVUJyTDJHY094WDBkMUw6czg1bHFWa21RSVNrQmxnWENUSm1EUQ=='
# 输出
{
  "name" : "node-1",
  "cluster_name" : "test-elk",
  "cluster_uuid" : "RykjCSPnSCi4Hsi37uziWw",
  "version" : {
    "number" : "8.17.3",
    "build_flavor" : "default",
    "build_type" : "tar",
    "build_hash" : "a091390de485bd4b127884f7e565c0cad59b10d2",
    "build_date" : "2025-02-28T10:07:26.089129809Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.0",
    "minimum_wire_compatibility_version" : "7.17.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "You Know, for Search"
}
1
2
3
4
5
6
7
8
9
curl -u elastic:123456 -k 'https://127.0.0.1:9200/_security/api_key?name=elastic_api_key&pretty'
# 请求参数说明：
# name: ApiKey的名称，不同的ApiKey可以拥有相同的名称，但id不同，所以通过name进行查询可能会返回多个结果
# 或者 id: ApiKey的id，建议通过id进行查询，id唯一，所以通过id进行查询只会返回一个结果
# username: 查询指定用户的ApiKey
# owner: 是否只查询当前认证用户名下的ApiKey，默认为false，为false时必须至少设置name\ids\username中的一个参数

# 不加任何参数进行查询，则返回所有ApiKey的信息
curl -u elastic:123456 -k 'https://127.0.0.1:9200/_security/api_key?pretty'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
curl -u elastic:123456 -X PUT -k 'https://127.0.0.1:9200/_security/api_key/{ApiKeyId}?pretty' \
--header 'Content-Type: application/json' \
--data '{
    "expiration": "1h",
    "role_descriptors": {
        "role-a": {
        "indices": [
            {
                "names": ["*"],
                "privileges": ["write"]
            }
        ]
        }
    },
    "metadata": {
        "environment": {
            "level": 2,
            "trusted": true,
            "tags": ["production"]
        }
    }
}'

# 可以更新的参数有：
# expiration: ApiKey的过期时间，如果已经设置过expiration，此时希望使其永不过期，则只能将其设置为一个比较大的时间，比如 "expiration": "100y"
# role_descriptors: ApiKey所拥有的角色，原先设置了role_descriptors，更新时希望其使用认证用户的角色，则此时可以将其设置为 "role_descriptors": {}
# metadata: ApiKey的元数据，原先设置了 metadata ，更新时希望去除所有 metadata 信息，则此时可以将其设置为 "metadata": {}
# 注意：三个参数可以只更新其中任何一个，更新哪个就只替换哪个，没有被更新的参数不会受到修改，当然也可以同时更新全部

  • 置ApiKey无效，参考官方文档，官方没有提供删除ApiKey的接口，只有置无效的接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
curl -u elastic:123456 -X DELETE -k 'https://127.0.0.1:9200/_security/api_key?pretty' \
--header 'Content-Type: application/json' \
--data '{
    "name": "elastic_api_key"
}'
# 请求参数说明：
# name: ApiKey的名称，会
# 或者使用  "ids" : [ "70It0ZUBrL2GcOxX0d1L" ] ，通过id进行删除，此时可以一次删除多个ApiKey
# username: 删除指定用户的ApiKey
# owner: 是否只删除当前认证用户名下的ApiKey，默认为false，为false时必须至少设置name\ids\username中的一个参数

# 输出：
{
  "invalidated_api_keys":[
    "70It0ZUBrL2GcOxX0d1L"
  ],
  "previously_invalidated_api_keys":[ ],
  "error_count":0
}
# 输出参数说明：
# invalidated_api_keys: 被删除的ApiKey的id列表
# previously_invalidated_api_keys: 之前被删除的ApiKey的id列表
# error_count: 错误数量，如果为0，则表示成功

  • 使用ApiKey的优缺点

    • 优点
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    安全性:
        细粒度控制: API Key 可以与特定的角色描述符关联，允许非常细化的权限控制。这有助于遵循最小权限原则，只授予必要的访问权限。
        时间限制: 可以为 API Key 设置过期时间，确保密钥不会永远有效，减少长期泄露的风险。
        可撤销性: 如果怀疑某个 API Key 被泄露或不再需要，可以随时撤销该密钥，提高安全性。
    方便性:
        易于生成和管理: 创建和管理 API Key 的过程通常很简单，可以通过 REST API 或 Kibana 界面进行。
        无需用户交互: 一旦生成，API Key 可以直接用于自动化脚本或应用程序，无需用户手动登录或提供凭据。
    审计和监控:
        跟踪使用情况: 通过日志记录和审计功能，可以跟踪哪个 API Key 进行了哪些操作，便于安全审计和问题排查。
        活动监控: 可以监控 API Key 的活动，及时发现异常行为，并采取相应的措施。
    灵活性:
        多种用途: API Key 可以用于各种用途，如应用程序集成、数据导入导出、监控工具等。
        多环境支持: 可以为不同的环境（开发、测试、生产）生成独立的 API Key，确保各环境之间的隔离。
    • 缺点
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    安全性风险:
        密钥存储: API Key 需要安全地存储和传输，如果密钥被泄露，攻击者可以利用它进行未授权的操作。
        静态凭证: 与动态的身份验证机制（如 OAuth 令牌）相比，API Key 是静态的，一旦泄露可能会导致长期的安全风险。
    管理复杂性:
        密钥管理: 随着时间和使用规模的增长，管理和维护大量 API Key 可能会变得复杂。需要定期更新和撤销老旧的密钥。
        角色分配: 细粒度的权限控制虽然提供了安全性，但也增加了配置和管理的复杂性。
    缺乏用户上下文:
        匿名性: API Key 通常没有用户上下文信息，不像基于用户的认证机制（如 Basic Auth 或 OAuth），这可能不利于某些依赖用户身份的功能。
    依赖客户端配置:
        易错性: 如果客户端配置不当，如错误地处理或暴露 API Key，可能会导致安全漏洞。
        更新挑战: 更新 API Key 后，所有使用该密钥的客户端都需要同步更新，这在大规模环境中可能是一个挑战。

  • 何时使用 API Key

    • 当您需要为自动化脚本、第三方服务或应用程序提供访问权限时。
    • 当您希望实现细粒度的权限控制并能够轻松管理密钥的生命周期时。
    • 当不需要用户上下文或复杂的用户会话管理时。

  • 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
# 创建ApiKey
curl -X POST -k 'https://127.0.0.1:9200/_security/api_key?pretty' \
-u elastic:123456 \
--header 'Content-Type: application/json' \
--data '{
  "name": "my-api-key",
  "expiration": "1d",
  "role_descriptors": {
    "role-a": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  },
  "metadata": {
    "application": "my-application",
    "environment": {
       "level": 1,
       "trusted": true,
       "tags": ["dev", "staging"]
    }
  }
}'
# name: ApiKey的名称
# expiration: ApiKey的过期时间，支持的时间单位为：s（秒），m（分钟），h（小时），d（天），w（周），M（月），y（年）
    # expiration不能设置小于1分钟的时间，如果省略expiration，则表示无过期时间
# role_descriptors: 角色描述符，包含多个角色
    # role-a: 角色描述符名称，包含集群和索引的权限描述
        # cluster: 集群权限
            # all: 表示拥有全部集群权限
            # manage: 可以管理集群设置、模板和节点上的分片分配。
            # monitor: 可以监视集群的状态。
            # manage_security: 可以管理安全设置，如用户、角色和角色映射。
            # manage_api_key: 管理 API Key
        # indices: 索引权限，包含names和privileges，
            # names: 表示索引名称，index-a*表示所有以index-a开头的索引，all表示所有索引
            # privileges: 表示索引权限
                # read: 表示拥有索引的读取权限
                # write: 表示拥有索引的写入权限
                # delete: 表示拥有索引的删除权限
                # index: 表示拥有索引的索引权限
                # manage: 表示拥有索引的设置和映射权限
                # monitor: 表示拥有索引的监控权限
                # create_index: 表示允许创建索引
                # crud: 组合了 read, index, delete 权限
                # all: 表示拥有全部索引权限
            # allow_restricted_indices: 表示是否允许对 restricted indices(受限制索引，比如以.开头的索引) 进行操作，true表示允许，false表示不允许
# metadata: 元数据
    # application: 表示应用程序名称
    # environment: 表示环境信息
        # level: 表示环境级别
        # trusted: 表示是否受信任
        # tags: 表示环境标签

# 输出：
{
  "id" : "-kKu0ZUBrL2GcOxX0t1R",
  "name" : "my-api-key",
  "expiration" : 1743066050130,
  "api_key" : "03eNOYg_SCCHdzc0orsRvw",
  "encoded" : "LWtLdTBaVUJyTDJHY094WDB0MVI6MDNlTk9ZZ19TQ0NIZHpjMG9yc1J2dw=="
}

# 查看ApiKey信息，根据id查询只会返回一个ApiKey，根据name查询会返回多个ApiKey
curl -u elastic:123456 -k 'https://127.0.0.1:9200/_security/api_key?id=-kKu0ZUBrL2GcOxX0t1R&pretty'
# 输出：
{
  "api_keys" : [
    {
      "id" : "-kKu0ZUBrL2GcOxX0t1R",
      "name" : "my-api-key",
      "type" : "rest",
      "creation" : 1742979650130,
      "expiration" : 1743066050130,
      "invalidated" : false,
      "username" : "elastic",
      "realm" : "reserved",
      "realm_type" : "reserved",
      "metadata" : {
        "environment" : {
          "level" : 1,
          "trusted" : true,
          "tags" : [
            "dev",
            "staging"
          ]
        },
        "application" : "my-application"
      },
      "role_descriptors" : {
        "role-a" : {
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index-a*"
              ],
              "privileges" : [
                "read"
              ],
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : { },
          "transient_metadata" : {
            "enabled" : true
          }
        },
        "role-b" : {
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index-b*"
              ],
              "privileges" : [
                "all"
              ],
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : { },
          "transient_metadata" : {
            "enabled" : true
          }
        }
      }
    }
  ]
}

# 更新ApiKey
curl -u elastic:123456 -X PUT -k 'https://127.0.0.1:9200/_security/api_key/-kKu0ZUBrL2GcOxX0t1R?pretty' \
--header 'Content-Type: application/json' \
--data '{
    "metadata": {}
}'
# 输出：
{
  "updated" : true
}

# 置ApiKey无效
curl -u elastic:123456 -X DELETE -k 'https://127.0.0.1:9200/_security/api_key?pretty' \
--header 'Content-Type: application/json' \
--data '{
   "ids" : [ "-kKu0ZUBrL2GcOxX0t1R" ]
}'
# 输出：
{
  "invalidated_api_keys" : [
    "-kKu0ZUBrL2GcOxX0t1R"
  ],
  "previously_invalidated_api_keys" : [ ],
  "error_count" : 0
}