1.2 Elasticsearch-单节点启动：开箱即用的 RESTful API

Elasticsearch单节点启动指南

最新推荐文章于 2025-12-07 16:10:55 发布

原创最新推荐文章于 2025-12-07 16:10:55 发布 · 904 阅读

29 ·

CC 4.0 BY-SA版权

CC BY-NC-SA 3.0

文章标签：

#elasticsearch #restful #大数据

elasticsearch 专栏收录该内容

28 篇文章

订阅专栏

1.2 Elasticsearch-单节点启动：开箱即用的 RESTful API

0. 写在动手之前

单节点实例不是“玩具”，而是所有 Elasticsearch 集群的原子模型。只要把下面三步跑通，你就拥有了后续水平扩展、滚动升级、跨机房容灾的同一套 RESTful 接口。本章全部命令在 macOS/Linux/WSL 下通用，Windows 用户把 curl 换成 PowerShell 的 Invoke-RestMethod 即可。

1. 获取发行包

# 1. 下载与上一章相同的 8.13.0 版本（已自带 JDK 21）
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.13.0-linux-x86_64.tar.gz
tar -xzf elasticsearch-8.13.0-linux-x86_64.tar.gz
cd elasticsearch-8.13.0/

2. 第一次启动：安全自动配置

8.x 默认开启安全。单节点场景下，Elasticsearch 会为你自动生成：

TLS 传输层证书
HTTP 层证书
内置用户 elastic 的初始密码
Kibana 注册令牌（可选）

# 2. 前台启动观察日志
./bin/elasticsearch

看到日志最后一行出现
HttpServerTransport publish_address {127.0.0.1:9200}, bound_addresses {[::1]:9200}
代表 RESTful 层已就绪。控制台会打印：

Password for the elastic user is: 4a3C2b1LRs68PvqQRzlD

记下密码，后面所有 curl 都要带。

3. 最简健康检查

# 3. 验证节点级信息
curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  https://localhost:9200

返回 JSON 片段：

{
  "name" : "jimn-mbp.local",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "Xc4b0sTpQ0KpU8Y2H5jpBg",
  "version" : {
    "number" : "8.13.0",
    "build_flavor" : "default",
    "build_type" : "tar",
    "lucene_version" : "9.10.0"
  },
  "tagline" : "You Know, for Search"
}

只要出现 "tagline" : "You Know, for Search"，就说明 RESTful 通道 100% 可用。

4. 集群级健康度 API

curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  https://localhost:9200/_cluster/health?pretty

单节点默认分片副本为 0，因此：
"status" : "yellow" 是正常预期，不是异常。
"number_of_nodes" : 1 再次确认你只跑了一个进程。

5. 节点统计：看 JVM、线程、文件句柄

curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  https://localhost:9200/_nodes/stats/jvm,os,process?pretty \
  | jq '.nodes[] | {name: .name, heap_used: .jvm.mem.heap_used_in_bytes}'

拿到堆内存用量，方便后面调优 -Xms/-Xmx。

6. 索引生命周期第一步：创建并写一条文档

# 6.1 创建索引（默认 1 分片 1 副本，单节点副本无法分配，会 yellow）
curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  -X PUT https://localhost:9200/shop_order

# 6.2 写文档，自动生成 _id
curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  -X POST https://localhost:9200/shop_order/_doc \
  -H 'Content-Type: application/json' \
  -d'
{
  "title": "Elasticsearch 8 实战",
  "price": 98.0,
  "timestamp": "2025-10-17T12:00:00Z"
}'

{"_id":"cQbnzI0BZaVvGgVfJcFP","result":"created","_shards":{"total":1,"successful":1,"failed":0}}

即代表写入成功。注意 _shards.successful=1，单节点只有主分片。

7. 读回刚才的文档

curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  https://localhost:9200/shop_order/_doc/cQbnzI0BZaVvGgVfJcFP?pretty

可以看到 _source 里正是刚才提交的 JSON。

8. 搜索：URI 查询与 DSL 查询对比

# 8.1 URI 查询（q=参数）
curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  https://localhost:9200/shop_order/_search?q=title:实战

# 8.2 DSL 查询（推荐生产使用）
curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  -X POST https://localhost:9200/shop_order/_search \
  -H 'Content-Type: application/json' \
  -d'
{
  "query": {
    "match": {
      "title": "实战"
    }
  }
}'

两者返回结构完全一致，都位于 hits.hits[] 数组。DSL 才是后续聚合、高亮、分页、过滤的真正入口。

9. 批量 bulk：一次 REST 调用写 100 条

# 9. 准备 bulk.ndjson（注意最后一行要换行）
cat > bulk.ndjson <<'EOF'
{"index":{"_index":"shop_order","_id":"1"}}
{"title":"MacBook Pro","price":19999}
{"index":{"_index":"shop_order","_id":"2"}}
{"title":"AirPods","price":1299}
{"index":{"_index":"shop_order","_id":"3"}}
{"title":"Magic Keyboard","price":799}
EOF

curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  -X POST https://localhost:9200/_bulk \
  -H 'Content-Type: application/x-ndjson' \
  --data-binary @bulk.ndjson

返回摘要
"errors":false 即全部成功；"took":123 代表 123ms 完成，可粗略估算单节点写入吞吐。

10. 常见启动报错速查表

日志关键字	原因	解决
`max virtual memory areas vm.max_map_count [65530] is too low`	系统内核参数不足	`sudo sysctl -w vm.max_map_count=262144`
`Unable to lock JVM Memory`	未启用 memlock	启动前 `ulimit -l unlimited`，或修改 `/etc/security/limits.conf`
`address already in use`	9200 被占用	`lsof -i:9200` 杀掉旧进程
`Certificate path does not exist`	找不到自动生成的证书	确认启动日志里 `HTTP CA certificate SHA-256 fingerprint` 行，重新拷贝 `http_ca.crt` 路径

11. 单节点调优三件套

禁用冗余副本：

curl -u elastic:4a3C2b1LRs68PvqQRzlD --cacert config/certs/http_ca.crt \
  -X PUT https://localhost:9200/*/_settings \
  -H 'Content-Type: application/json' \
  -d'{"number_of_replicas":0}'

集群状态立即变 green。

降低刷新间隔，提升写入吞吐：
"index.refresh_interval":"30s"
开发机内存有限时，把堆压到 512MB：
export ES_JAVA_OPTS="-Xms512m -Xmx512m"
同时关闭机器学习：
xpack.ml.enabled: false

12. 小结

单节点启动只需解压、运行、记住密码，就能通过 HTTPS + 基本认证获得完整的 RESTful 能力。
本章演示的 _cluster/health、_nodes/stats、_search、_bulk 四大端点，在任何规模集群里路径与参数完全一致；后续无论是垂直扩容（加内存）还是水平扩容（加节点），你依旧用同一套 URL、同一组 JSON 结构。掌握单节点，就是掌握整个 Elasticsearch 的“元模型”。
更多技术文章见公众号: 大城市小农民