快速开始

从交付包到能登录的最短路径：一台 Linux 主机、Docker、你已有的 Elasticsearch，跑一遍 deploy.sh。

准备

项	要求
主机	Ubuntu 20.04 / 22.04 / 24.04 或等价 Linux，2 vCPU / 4 GB / 20 GB+
运行时	Docker Engine 24+ 与 Docker Compose v2
Elasticsearch	你已有的 8.x，网关主机网络可达；Kibana 可选
大模型	一个 OpenAI 兼容端点的 URL / API key / 模型名（火山方舟 coding 计划用 `ark-code-latest`）
访问名	一个域名（如 `copilot.corp.local`），不能用裸 IP（IP 作 TLS SNI 不合规，部分浏览器握手失败）；没有内网 DNS 就给分析师机器加一条 hosts

入站只需 443（可选 80 跳转）。出站需要：大模型端点 443、你的 ES 9200、license.reallysec.com 443（气隙部署可以没有，见许可）。

安装

装 Docker（如果还没有）

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

解开交付包

交付包是一个 RST-Elastic-AI-Copilot-<版本>.tar.gz，里面已经带了镜像，不需要访问任何镜像仓库。

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

跑 `deploy.sh`

./deploy.sh

它会依次：预检 Docker → 生成 state/machine-id 和 state/server_guid（许可的硬件指纹，永不重建）→ docker load 镜像 → 问你认证方式（选 1，网关自带登录）和 ES 来源（选 1，已有 ELK）→ 问大模型 URL / key / 模型、时区、ES / Kibana 地址、访问域名、管理员口令 → 生成内部密钥写进 .env（600）→ docker compose up -d 并等到 healthy。

结束时会打印访问地址。全程大约两分钟。

验证

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，ES 账号缺 .rst_copilot_* 索引的权限，见下面。

ES 账号权限

如果你的 ES 开了安全，给 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-* 限制可查询的索引范围。

装完之后

激活许可：付费引擎要它，试用许可免费。
/v2/settings 配索引白名单、脱敏档位、审计。
备份：./state/ 目录整个拷走；gateway_state 卷用包里的 scripts/backup.sh（它只导出卷，不含 ./state/）。

升级

把新交付包解到同一个目录，再跑一次 ./deploy.sh，选「保留现有 .env」，它会 load 新镜像、把 GATEWAY_IMAGE_TAG 切到新版本并重启。回滚就用上一个镜像 tag 重启，许可状态在 state/ 和卷里，不会丢。

永远不要重建 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
`readyz` 里 `es_write=denied`	ES 账号缺 `.rst_copilot_*` 的建 / 写权限
查询报错或空	ES 是否可达；`RST_INDEX_WHITELIST` 是否漏了目标索引；大模型 key / endpoint 是否正确
许可突然失效	是否重建过 `state/machine-id` / `state/server_guid`

本页内容