交付包安装

用安装脚本安装

安装脚本 install.sh 随每个版本的 Release 发布。脚本下载交付包与 .sha256 文件，校验后解压到安装目录，再执行 deploy.sh。主机需要已安装 Docker Engine 24 及以上与 Docker Compose v2，并在交互式终端中以 root 执行。

curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Elastic/releases/latest/download/install.sh | sudo bash

所有版本使用同一个交付包：未激活许可时以社区版运行，在 系统设置 的 产品激活 中激活许可后，原地解锁对应版本的功能，不需要重装。

再次执行安装脚本时，交付包解压到同一目录，目录中的 .env 与 state/ 保留，许可指纹不变。

在离线主机上安装

步骤

1. 在能访问 GitHub 的主机上执行：

   curl -fsSL https://github.com/Reallysec/RST-AI-Copilot-for-Elastic/releases/latest/download/install.sh | bash -s -- --download-only

2. 把当前目录下的 RST-AI-Copilot-for-Elastic-<版本>.tar.gz 拷到离线主机。

3. 在离线主机上按下文 执行 deploy.sh 安装。

使用自带 Elasticsearch 与 Kibana 时，把 Release 页的 RST-AI-Copilot-for-Elastic-elk-images-<版本>.tar.gz 一并拷到解压后的目录，见 自带 Elasticsearch 与 Kibana。

获取交付包

交付包在 GitHub Releases 页面发布，文件为 RST-AI-Copilot-for-Elastic-<版本>.tar.gz 与校验文件 RST-AI-Copilot-for-Elastic-<版本>.tar.gz.sha256。所有版本使用同一个交付包，功能范围由激活的许可决定。

解开后的目录：

RST-AI-Copilot-for-Elastic-<版本>/
├── RST-AI-Copilot-for-Elastic-images-<版本>.tar   # 网关与 Caddy 镜像，deploy.sh 自动加载
├── deploy.sh                                  # 交互式安装脚本
├── docker-compose.prod.yml                    # 标准形态：Caddy、网关、userdb
├── docker-compose.sso.yml                     # SSO 形态
├── Caddyfile / Caddyfile.sso
├── .env.example                               # 全部配置项及说明
├── deploy/rst-update.sh                       # 在线更新安装器
├── scripts/backup.sh / restore.sh
└── docs/                                      # 部署、备份手册与发版说明

安装不访问镜像仓库。解包前执行 sha256sum -c RST-AI-Copilot-for-Elastic-<版本>.tar.gz.sha256 校验完整性。

执行 deploy.sh

tar xzf RST-AI-Copilot-for-Elastic-<版本>.tar.gz
cd RST-AI-Copilot-for-Elastic-<版本>
sudo ./deploy.sh

脚本分七步执行。

第 5 步的提示与取值：

state/machine-id 与 state/server_guid 是许可的硬件指纹，生成后不可重建。

自带 Elasticsearch 与 Kibana

第 4 步 Elasticsearch 来源选 2 时，deploy.sh 在 .env 中写入 ES_URL=http://elasticsearch:9200 与 KIBANA_URL=http://kibana:5601，并以 --profile bundled-elk 启动 docker-compose.prod.yml 中的 elasticsearch 与 kibana 两个容器。这一形态用于 PoC 和没有 ELK 的主机，生产环境连接已有集群。

交付包不含这两个镜像。主机能访问 docker.elastic.co 时，deploy.sh 发现缺少镜像后询问是否在线拉取。离线主机把 Release 页的可选附件 RST-AI-Copilot-for-Elastic-elk-images-<版本>.tar.gz 放到安装目录（与 deploy.sh 同一目录），deploy.sh 在第 2 步加载。缺少镜像且不在线拉取时，脚本中止。

deploy.sh 按以下顺序决定写入 .env 的 RST_ELK_VERSION：

1. .env 中已有该值时沿用。
2. 没有该值、但主机上已有自带 Elasticsearch 的数据卷（es_data 或 sso_es_data）时，写入 8.12.2。1.2.4 之前的安装属于这种情况。
3. 其他情况（新装）写入 9.5.3。离线附件 elk-images 中也是 9.5.3。

Elasticsearch 9.x 不能直接打开 8.x 的数据。已有自带 Elasticsearch 数据的主机不要只把 RST_ELK_VERSION 改成 9.5.3，否则 Elasticsearch 无法启动。

多用户账号表

多用户与三档角色（admin、analyst、viewer）的账号保存在网关自有的 Postgres 中，不写入 Elasticsearch。deploy.sh 启动 userdb 容器并设置 RST_USER_DB_URL，安装完成后即可在 用户 页添加账号。

手动安装时，在 .env 中设置：

RST_USER_DB_PASSWORD=<32 位随机串>
RST_USER_DB_URL=postgresql://rst:<同上>@userdb:5432/rst_users

然后执行 docker compose -f docker-compose.prod.yml up -d userdb gateway caddy。首次启动时网关建表，并把 RST_ADMIN_USERNAME 与 RST_ADMIN_PASSWORD_HASH 写为第一个管理员。使用自有 Postgres 时，把 RST_USER_DB_URL 指向该实例，不启动 userdb。

启用 SSO 后账号由 IdP 管理，RST_USER_DB_URL 不生效。

验证安装

curl -k https://<域名>/healthz     # {"status":"ok"}
curl -k https://<域名>/readyz      # {"status":"ready","es":"ok","es_write":"ok","timezone":"+08:00",...}
docker compose -f docker-compose.prod.yml ps

打开 https://<域名>/v2/，以 admin 和安装时设置的口令登录。默认证书为自签证书，生产环境修改 Caddyfile 换成自有证书。

手动安装

不使用 deploy.sh 时：

docker load < RST-AI-Copilot-for-Elastic-images-*.tar
cp .env.example .env            # 填写 LLM_*、ES_*、CADDY_SITE_ADDRESS、RST_GATEWAY_SHARED_SECRET、RST_ADMIN_TOKEN、RST_USER_DB_PASSWORD、GATEWAY_IMAGE_TAG
mkdir -p state
openssl rand -hex 16 > state/machine-id
cat /proc/sys/kernel/random/uuid > state/server_guid
chmod 644 state/*               # 网关以 uid 10001 运行，600 无法读取
docker compose -f docker-compose.prod.yml up -d

管理员口令哈希由 docker exec rst-ai-copilot-for-elastic-gateway python -m backend.session_auth '<口令>' 生成，写入 .env 的 RST_ADMIN_PASSWORD_HASH。哈希中的每个 $ 写为 $$，否则 compose 会把它当作变量。

后续操作

1. 使用付费引擎时，激活许可。
2. 在系统设置中配置索引白名单、脱敏档位和审计。
3. 在 AI 配置中配置知识库向量模型。
4. 把 ./state/、gateway_state 卷和 userdb_data 卷纳入备份，见升级与备份。