Ubuntu 24.04 安装 OpenSearch 2.x

目标：在 Ubuntu 24.04 上通过官方 APT 源安装 OpenSearch 2.x（实测版本 2.19.6），配置单节点模式并关闭安全插件简化部署，覆盖 GPG key 导入、repo 配置、demo 安全配置、systemd 托管的启动方式。本文档已在 Ubuntu 24.04 真实服务器上全流程实测。

环境信息

信息项	实测值	说明
操作系统	Ubuntu 24.04 LTS	真实服务器
系统架构	x86_64	amd64
内核版本	6.8.0-138-generic
包管理器	apt（deb 系）	Ubuntu 默认
OpenSearch 版本	2.19.6（apt 源当前最新 2.x）	`apt-cache policy opensearch` 确认
捆绑 JDK	OpenJDK 21.0.11（Temurin）	deb 包自带，无需单独装 Java
服务器主机	`opensearch-node1`	实测保留
配置目录	`/etc/opensearch/`	opensearch.yml 所在
数据目录	`/var/lib/opensearch/`	path.data
日志目录	`/var/log/opensearch/`	path.logs
网络连通性	可达	需访问 artifacts.opensearch.org

前置条件

拥有服务器 root / sudo 权限
系统已 apt-get update 更新
网络可访问 artifacts.opensearch.org（官方下载/APT 源）
准备一个强密码用于安装期 demo 安全配置（2.12+ 安装必需，见步骤 3 踩坑）
计划以单节点运行（多节点集群需另行配置 discovery 与安全）

部署步骤

步骤 1. 更新系统并安装依赖

先更新 apt 缓存，再安装后续添加 APT 源所需的基础工具。

执行命令：

apt-get update
apt-get install -y curl gnupg apt-transport-https ca-certificates

执行结果：

Running hooks in /etc/ca-certificates/update.d...
done.

💡 命令解释：apt-get install 安装后续添加 APT 源所需的工具——curl 下载 GPG key、gnupg 导入密钥、apt-transport-https 支持 HTTPS 源、ca-certificates 提供 CA 证书。

💡 说明：OpenSearch deb 包自带捆绑 JDK，无需单独安装 Java。

步骤 2. 导入官方 GPG key 并添加 APT 源

官方文档目前提供的正确仓库路径为 https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt（老文档中的 releases/browse/... 路径已失效，实测返回 403，见常见问题 1）。

执行命令：

curl -o- https://artifacts.opensearch.org/publickeys/opensearch.pgp | gpg --dearmor --batch --yes -o /usr/share/keyrings/opensearch-keyring
echo "deb [signed-by=/usr/share/keyrings/opensearch-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" > /etc/apt/sources.list.d/opensearch-2.x.list
apt-get update
apt-cache policy opensearch

执行结果：

# apt-get update 关键输出
Get:3 https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable InRelease [7553 B]
Get:6 https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable/main amd64 Packages [4447 B]

# apt-cache policy opensearch（节选）
opensearch:
  Installed: (none)
  Candidate: 2.19.6
  Version table:
     2.19.6 500
        500 https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable/main amd64 Packages
     2.19.5 500
     2.19.4 500
     2.19.3 500
     ...
     2.12.0 500
     2.11.1 500
     ...

💡 命令解释：curl -o- ... | gpg --dearmor 下载官方 GPG 公钥并转为 apt 需要的二进制 keyring 格式（/usr/share/keyrings/opensearch-keyring）；signed-by= 指定用该 keyring 校验仓库签名；deb [signed-by=...] <URL> stable main 是标准第三方 APT 源写法。

💡 说明：stable 是 OpenSearch 2.x 仓库的发行版代号（其 Packages 索引直接位于仓库根），main 是组件名。实测最新候选版本为 2.19.6（官方 APT 源始终优先更新）。

步骤 3. 安装 OpenSearch（2.12+ 必须设置 admin 密码变量）

OpenSearch 2.12 及以后版本，安装期 postinst 脚本会尝试执行 demo 安全配置，必须通过环境变量 OPENSEARCH_INITIAL_ADMIN_PASSWORD 提供自定义 admin 密码，否则安装报错。

执行命令（失败版，用于展示踩坑）：

DEBIAN_FRONTEND=noninteractive apt-get install -y opensearch

执行结果：

Setting up opensearch (2.19.6) ...
Running OpenSearch Post-Installation Script
ERROR: Something went wrong during demo configuration installation. Please see the logs in /var/log/opensearch/install_demo_configuration.log
dpkg: error processing package opensearch (--configure):
 installed opensearch package post-installation script subprocess returned error exit status 1
Errors were encountered while processing:
 opensearch
E: Sub-process /usr/bin/dpkg returned an error code (1)

⚠️ 错误：postinst 的 demo 配置安装失败，dpkg 配置阶段返回 exit 1。

💡 排查思路：查看 /var/log/opensearch/install_demo_configuration.log：

No custom admin password found. Please provide a password via the environment variable OPENSEARCH_INITIAL_ADMIN_PASSWORD.

修复命令（正确安装）：

DEBIAN_FRONTEND=noninteractive env OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:?请在环境变量中设置} apt-get install -y opensearch

修复后结果：

Creating opensearch user... OK
Creating opensearch group... OK
### OpenSearch Security Demo Installer
### ** Warning: Do not use on production or public reachable systems **
Detected OpenSearch Version: 2.19.6
Detected OpenSearch Security Version: 2.19.6.0
Admin password set successfully.
### Success
...
### Breaking change in packaging since 2.13.0
 In 2.13.0 and later releases of OpenSearch, we have changed the permissions associated with access to installed files
 ...

💡 命令解释：env OPENSEARCH_INITIAL_ADMIN_PASSWORD=... 在调用 dpkg 时注入环境变量，postinst 用它设置 demo 安全配置的 admin 密码；DEBIAN_FRONTEND=noninteractive 跳过交互提示。密码为敏感值，请通过外部环境变量注入。

💡 说明：demo 安全配置（Demo Installer）只适合本地测试，会生成自签证书并默认启用安全插件，生产环境禁止使用。本环境后续步骤会直接关闭安全插件简化。

验证安装结构：

ls -d /etc/opensearch /var/lib/opensearch /var/log/opensearch /usr/share/opensearch/jdk
/usr/share/opensearch/jdk/bin/java -version

执行结果：

/etc/opensearch /var/lib/opensearch /var/log/opensearch /usr/share/opensearch/jdk
openjdk version "21.0.11" 2026-04-21 LTS
OpenJDK Runtime Environment Temurin-21.0.11+7 (build 21.0.11+7-LTS)

💡 说明：deb 包安装路径与 tarball 一致（/usr/share/opensearch），配置文件在 /etc/opensearch，数据/日志分别在 /var/lib/opensearch、/var/log/opensearch，并自带捆绑 JDK 21。

步骤 4. 配置单节点（opensearch.yml）

备份后追加单节点配置，并关闭安全插件（plugins.security.disabled: true）。

执行命令：

cp /etc/opensearch/opensearch.yml /etc/opensearch/opensearch.yml.bak
cat >> /etc/opensearch/opensearch.yml <<'EOF'

# ===== 以下为单节点实测追加配置 =====
cluster.name: opensearch-node1
node.name: opensearch-node1
network.host: 0.0.0.0
http.port: 9200
discovery.type: single-node
plugins.security.disabled: true
EOF
tail -6 /etc/opensearch/opensearch.yml

执行结果：

cluster.name: opensearch-node1
node.name: opensearch-node1
network.host: 0.0.0.0
http.port: 9200
discovery.type: single-node
plugins.security.disabled: true

💡 命令解释：discovery.type: single-node 进入单节点模式（跳过多数 bootstrap 检查，生产多节点集群不能使用）；network.host: 0.0.0.0 监听所有网卡；plugins.security.disabled: true 关闭安全插件，无需证书/密码即可访问，测试环境简化。

💡 说明：配置全部追加到文件尾部覆盖模板默认值。若仅关闭安全插件而不改其他项，安装期生成的 demo 证书不会加载，启动即无认证。

步骤 5. 启动 OpenSearch（systemd 服务）

OpenSearch deb 包自带 systemd 单元，用 systemctl 托管节点。

执行命令：

sudo systemctl daemon-reload
sudo systemctl enable opensearch
sudo systemctl start opensearch
sudo systemctl status --no-pager opensearch
sleep 20
curl -s http://127.0.0.1:9200/_cluster/health?pretty

执行结果：

# systemctl status 显示 active (running)
{
  "cluster_name" : "opensearch-node1",
  "status" : "green",
  "number_of_nodes" : 1,
  ...
  "active_shards_percent_as_number" : 100.0
}

💡 命令解释：systemctl enable opensearch 设置开机自启，systemctl start opensearch 立即启动节点，status --no-pager 查看运行状态；enable/start/status 每行仅针对 opensearch 一个单元。

💡 说明：可用 journalctl -u opensearch -f 实时查看启动日志排障；也可前台运行 /usr/share/opensearch/bin/opensearch（会占用终端，适合排障）。

执行命令（验证写入）：

curl -s -X POST http://127.0.0.1:9200/apt_test/_doc/1 -H 'Content-Type: application/json' -d '{"msg":"apt install ok"}'

执行结果：

{"_index":"apt_test","_id":"1","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":0,"_primary_term":1}

💡 说明：_shards.total: 2 / successful: 1 —— 默认 1 副本，单节点无法分配副本分片，索引为 yellow（主分片写入成功，数据可用）。单节点环境可在索引 settings 中设 number_of_replicas: 0 消除 yellow（详见《配置参数详解》）。

配置说明

配置项 1：基础参数（/etc/opensearch/opensearch.yml）

cluster.name: opensearch-node1      # 集群名，多节点必须一致
node.name: opensearch-node1         # 节点名
network.host: 0.0.0.0               # 监听地址
http.port: 9200                     # HTTP 端口
discovery.type: single-node         # 单节点模式

配置项 2：安全插件开关

plugins.security.disabled: true     # 关闭安全插件（测试简化；生产请删除并配置证书/密码）

⚠️ 生产环境不要关闭安全插件：至少应保留默认启用并用 securityadmin.sh 配置证书与密码，或用安装期 OPENSEARCH_INITIAL_ADMIN_PASSWORD 设置的 admin 密码登录。

配置项 3：JVM 堆内存

deb 安装默认堆为 1g（/usr/share/opensearch/config/jvm.options 中 -Xms1g -Xmx1g）。内存受限时通过环境变量覆盖：

export OPENSEARCH_JAVA_OPTS="-Xms512m -Xmx512m"

💡 说明：OPENSEARCH_JAVA_OPTS 会追加到 JVM 启动参数尾部，覆盖 jvm.options 中的默认堆设置（实测 ps 进程参数可见 -Xms1g -Xmx1g 后追加的 -Xms512m -Xmx512m 生效）。

注意事项

2.12+ 安装必须设置 OPENSEARCH_INITIAL_ADMIN_PASSWORD，否则 postinst 报错（步骤 3 实测）。
关闭安全插件后不要对外网暴露 9200 端口，无认证任何人可读写。
单节点模式仅适合测试/小规模场景；生产多节点必须移除 discovery.type: single-node 并配置 cluster 发现。
服务由 systemd 托管，统一使用 systemctl start/stop/status opensearch 管理。
索引默认 1 副本，单节点会出现 yellow；可设置 number_of_replicas: 0。
文件属主必须为 opensearch 用户：chown -R opensearch:opensearch /var/lib/opensearch /var/log/opensearch。

常见问题

问题 1：apt 源报 403 Forbidden

现象： apt-get update 报 Err:5 ... 403 Forbidden，InRelease 拉取失败。

原因： 使用了旧文档的仓库路径 https://artifacts.opensearch.org/releases/browse/opensearch/2.x/（browse 是浏览页面路径，实测 403）。

解决： 改用官方当前路径：

echo "deb [signed-by=/usr/share/keyrings/opensearch-keyring] https://artifacts.opensearch.org/releases/bundle/opensearch/2.x/apt stable main" > /etc/apt/sources.list.d/opensearch-2.x.list
apt-get update

问题 2：安装报错 "No custom admin password found"

现象： apt-get install -y opensearch 在 Setting up opensearch 阶段报 ERROR: Something went wrong during demo configuration installation，dpkg exit 1。

原因： OpenSearch 2.12+ 安装期必须提供 demo 安全配置的 admin 密码，未设置 OPENSEARCH_INITIAL_ADMIN_PASSWORD（实测日志原文：No custom admin password found. Please provide a password via the environment variable OPENSEARCH_INITIAL_ADMIN_PASSWORD.）。

解决：

DEBIAN_FRONTEND=noninteractive env OPENSEARCH_INITIAL_ADMIN_PASSWORD=${OPENSEARCH_INITIAL_ADMIN_PASSWORD:?请在环境变量中设置} apt-get install -y opensearch

问题 3：启动后 9200 端口无响应

原因与排查： 依次检查——配置文件语法（YAML 缩进）；日志 /var/log/opensearch/opensearch-<cluster.name>.log 尾部；目录属主（ls -ld /var/lib/opensearch 应为 opensearch opensearch）；是否有安全插件初始化报错（plugins.security.disabled: true 可绕过）。

卸载方式

systemctl stop opensearch
DEBIAN_FRONTEND=noninteractive apt-get purge -y opensearch
rm -rf /var/lib/opensearch /var/log/opensearch /etc/opensearch
rm -f /etc/apt/sources.list.d/opensearch-2.x.list /usr/share/keyrings/opensearch-keyring

💡 说明：apt-get purge 会删除配置目录；数据与日志目录（/var/lib/opensearch、/var/log/opensearch）不会自动清理，备份后手动删除。

参考链接

本文档由 www.quzuo.net 平台开发