# Elasticsearch 9.3.1 本机安装记录

按 [ES_9](./ES_9) 文档在本机完成安装，数据与日志安装在 **/data** 目录下。

## 安装概要

| 项目 | 说明 |
|------|------|
| 版本 | Elasticsearch 9.3.1（APT 9.x 源） |
| 安装方式 | 官方 APT 源，二进制在 `/usr/share/elasticsearch` |
| 数据目录 | `/data/elasticsearch/data` |
| 日志目录 | `/data/elasticsearch/logs` |
| 配置 | `/etc/elasticsearch/elasticsearch.yml` |
| 模式 | 单机单节点 `discovery.type: single-node` |
| 安全 | 当前为开启状态（HTTP 访问需认证） |
| HTTP | `http://0.0.0.0:9200` |
| Kibana | 9.3.1，`http://0.0.0.0:5601`，已安装并启用 |

## 已执行步骤

1. 添加 ES 9.x APT 源与 GPG，`apt-get install elasticsearch`
2. 创建 `/data/elasticsearch/{data,logs}` 并 `chown elasticsearch:elasticsearch`
3. 配置 `elasticsearch.yml`：cluster、node、path.data/logs、network、discovery、security
4. JVM 堆：`/etc/elasticsearch/jvm.options.d/heap.options` 中 `-Xms4g -Xmx4g`（本机约 15GB 内存）
5. sysctl 与 limits 已按文档追加（vm.max_map_count、nofile、nproc、memlock 等）
6. `systemctl enable elasticsearch` 且 `systemctl start elasticsearch`
7. Kibana：`apt-get install kibana`，配置 `/etc/kibana/kibana.yml`（server.host: 0.0.0.0, elasticsearch.hosts: http://127.0.0.1:9200），`systemctl enable kibana` 且 `systemctl start kibana`

## 验证

```bash
curl http://127.0.0.1:9200
# 返回 cluster_name: searchengine-cluster, version.number: 9.3.1
```

## 常用命令

```bash
# Elasticsearch
sudo systemctl status elasticsearch   # 状态
sudo systemctl start elasticsearch    # 启动
sudo systemctl stop elasticsearch      # 停止

# Kibana
sudo systemctl status kibana
sudo systemctl start kibana
sudo systemctl stop kibana
```

## Kibana

- **版本**：9.3.1（与 ES 同源）
- **配置**：`/etc/kibana/kibana.yml`
- **当前关键配置**：
  - `server.host: "0.0.0.0"`
  - `server.port: 5601`
  - `elasticsearch.hosts: ["http://localhost:9200"]`
  - `elasticsearch.serviceAccountToken: "<token>"`
- **访问**：浏览器打开 `http://<本机IP>:5601`（当前会跳转登录页）

## 2026-03-11 Kibana 故障修复记录

### 现象

- `systemctl status kibana` 显示运行，但公网访问 `:5601` 页面无法打开或长时间无响应。
- 日志出现 `savedobjects-service` 长时间迁移；HTTP 端口虽然监听但请求超时。

### 根因

1. **监听地址问题（已修复）**  
   Kibana 一度仅监听 `127.0.0.1:5601`，外部无法直接访问。

2. **认证方式问题（核心根因，已修复）**  
   Kibana 使用了业务用户 `saas`（`elasticsearch.username/password`）连接 ES。  
   迁移阶段需要对 `.kibana_*` 受限索引执行创建动作，日志报错：
   - `security_exception`
   - `action [indices:admin/create] is unauthorized ... on restricted indices [.kibana_*]`
   导致 Saved Objects migration 卡住，HTTP 长时间无有效响应。

### 修复动作

1. 在 `/etc/kibana/kibana.yml` 固化对外监听：
   - `server.host: "0.0.0.0"`
   - `server.port: 5601`
2. 在 ES 创建 Kibana service account token：
   - `POST /_security/service/elastic/kibana/credential/token/kibana-server-1`
3. Kibana 认证改为 service token（官方推荐）：
   - 删除 `elasticsearch.username`
   - 删除 `elasticsearch.password`
   - 新增 `elasticsearch.serviceAccountToken`
4. 重启并验证：
   - `systemctl status kibana` = `active (running)`
   - `ss -lntp | grep 5601` = `0.0.0.0:5601`
   - 日志出现 `Completed all migrations`
   - 访问 `http://<IP>:5601/` 返回 `302 -> /login`

### 排障命令速查

```bash
# 服务与监听
sudo systemctl status kibana --no-pager -n 50
sudo ss -lntp | grep 5601

# Kibana 日志（关注迁移与权限报错）
sudo tail -n 200 /var/log/kibana/kibana.log
sudo journalctl -u kibana -n 200 --no-pager

# 本机/公网 HTTP 验证
curl -I http://127.0.0.1:5601/
curl -I http://<公网IP>:5601/
```

### 注意事项

- **不要**让 Kibana 复用应用侧业务账号（如 `.env` 的 `ES_USERNAME/ES_PASSWORD`）作为系统连接账号。
- 优先使用 `elasticsearch.serviceAccountToken`。
- 如果手动操作过 `/run/kibana/kibana.pid`，可能造成 stop/restart 流程异常，需用 systemd 重新拉起并确认状态。

## 与 SearchEngine 项目集成

- 环境变量或配置中 ES 地址：`ES_HOST=http://127.0.0.1:9200`
- 索引与导入：使用项目内 `mappings/search_products.json`（9.3 建议 bfloat16）及 `./scripts/ingest.sh` 等脚本。