快速开始

在一台 Linux 主机上，用安装脚本或交付包完成单机安装并登录。

单机安装需要一台 Linux 主机、Docker 和已有的 Elasticsearch 8.x 或 9.x。安装脚本下载交付包并执行 deploy.sh，也可以手动下载交付包安装。SSO 和离线激活见安装。

前提条件

Ubuntu 20.04、22.04、24.04 或同等 Linux，不低于 2 vCPU、4 GB 内存、20 GB 磁盘。
Docker Engine 24 及以上，Docker Compose v2。
已有的 Elasticsearch 8.x 或 9.x 集群，网关主机可以访问。Kibana 可选。PoC 或没有 ELK 的主机可以在 deploy.sh 中选择自带 Elasticsearch 与 Kibana，见交付包安装。
一个 OpenAI 兼容的大模型端点，以及 API key 和模型名。火山方舟 coding 计划的模型名为 ark-code-latest。
一个访问域名，例如 copilot.corp.local。裸 IP 不能作为 TLS SNI，部分浏览器拒绝握手。没有内网 DNS 时，在分析师机器上添加 hosts 记录。

入站只需放通 443，80 用于跳转，可选。出站需要访问大模型端点 443 和 Elasticsearch 9200。在线激活商业许可时，还需要访问 license.reallysec.com 443。社区版未激活许可时不连接许可服务器。

安装脚本 install.sh 下载最新版交付包，校验 SHA-256，解压到 /opt/rst-ai-copilot-for-elastic 后执行 deploy.sh。脚本不安装 Docker，需要在交互式终端中执行。

步骤

执行安装脚本：

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

所有版本使用同一个交付包，未激活许可时以社区版运行。

完成后按下文验证与登录两步检查。离线主机的安装方式和脚本全部选项见交付包安装。

主机已有 Docker 24 及以上时跳过。

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # 重新登录后生效
docker compose version

从 GitHub Releases 下载 RST-AI-Copilot-for-Elastic-<版本>.tar.gz 与同名 .sha256 文件，所有版本使用同一个交付包。交付包内含镜像，安装时不访问镜像仓库。

sha256sum -c RST-AI-Copilot-for-Elastic-<版本>.tar.gz.sha256
tar xzf RST-AI-Copilot-for-Elastic-<版本>.tar.gz
cd RST-AI-Copilot-for-Elastic-<版本>

sudo ./deploy.sh

认证方式选 1（网关自带登录），Elasticsearch 来源选 1（已有集群），然后按提示填写大模型、时区、Elasticsearch 与 Kibana 地址、访问域名和管理员口令。脚本生成内部密钥并写入 .env（权限 600），启动容器并打印访问地址，全程约两分钟。

脚本同时生成 state/machine-id 与 state/server_guid。这两个文件是许可的硬件指纹，生成后不可重建。

curl -k https://copilot.corp.local/healthz   # {"status":"ok"}
curl -k https://copilot.corp.local/readyz    # es / es_write / timezone

readyz 中 es_write 必须为 ok。为 denied 时，Elasticsearch 账号缺少 .rst_copilot_* 索引的权限，见下文。

Elasticsearch 启用安全认证时，ES_USER 的角色至少包含下列权限。

索引	权限	用途
日志索引，例如 `logs-*`	`read`、`view_index_metadata`	查询
`.rst_copilot_*`	`create_index`、`read`、`write`、`manage`	网关自有索引：审计、状态、归档
`.alerts-security.alerts-`、`.internal.alerts-security.alerts-`	`read`、`view_index_metadata`	实时告警拉取。隐藏索引在 Kibana 角色页不自动补全，需手工输入

建议在 .env 中设置 RST_INDEX_WHITELIST=logs-*,filebeat-*，限制可查询的索引。完整说明见 Elasticsearch 权限。

使用付费功能时，由管理员激活许可，不需要重装。未激活时以社区版运行，各版本区别见版本对比。
在系统设置中配置索引白名单、脱敏档位和审计。
备份 ./state/ 目录，并用交付包中的 scripts/backup.sh 导出 gateway_state 卷。该脚本不备份 ./state/。

用安装脚本安装的主机，再次执行安装脚本。脚本保留安装目录中的 .env 与主机指纹。1.2.20 及更早版本安装的主机沿用原目录 /opt/rst-elastic-ai-copilot。

手动安装的主机，把新交付包解到同一目录，再次执行 sudo ./deploy.sh，选择保留现有 .env。脚本加载新镜像，把 GATEWAY_IMAGE_TAG 切到新版本并重启。回滚时用上一个镜像 tag 重启，许可状态不受影响。

在线激活的商业许可还支持在线更新，见升级与备份。

不要重建 state/machine-id 或 state/server_guid，不要执行 docker compose down -v。任一文件变化都会被许可视为更换硬件，需要重新激活。

/v2/ 无法打开

执行 docker compose -f docker-compose.prod.yml logs caddy gateway 查看日志。在防火墙或安全组放通 443，CADDY_SITE_ADDRESS 使用域名。

HTTPS 握手失败

CADDY_SITE_ADDRESS 填写了裸 IP。改为域名，并在分析师机器上添加 hosts 记录。

许可突然失效

state/machine-id 或 state/server_guid 被重建。从备份恢复原文件。

其他症状见常见问题。