快速开始

在一台 Linux 主机上安装网关，接入已有的 QRadar Console 并登录。

单机安装只需要一台 Linux 主机、Docker、已有的 QRadar Console 和一个授权服务 Token，执行一次安装命令或 deploy.sh。SSO 和离线激活见安装。

前提条件

Ubuntu 20.04、22.04、24.04 或同等 Linux，不低于 2 vCPU、4 GB 内存、20 GB 磁盘。
Docker Engine 24 及以上，Docker Compose v2。
QRadar 7.5 及以上，网关主机可以访问 Console 的 443 端口。
一个授权服务 SEC Token，在 Console 的 Admin > Authorized Services 中创建。权限要求见下文。
一个 OpenAI 兼容的大模型端点，以及 API key 和模型名。火山方舟 coding 计划的模型名为 ark-code-latest。
一个访问域名，例如 copilot.corp.local。裸 IP 不能作为 TLS SNI，部分浏览器拒绝握手。没有内网 DNS 时，在分析师机器上添加 hosts 记录。

入站只需放通 443，80 用于跳转，可选。出站需要访问大模型端点 443 和 QRadar Console 443。在线激活商业许可时，还需要访问 license.reallysec.com 443。使用在线更新时，还需要访问 github.com 443，版本清单和内容包从 GitHub Releases 读取。

安装

安装 Docker

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

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

下载交付包并执行 deploy.sh

1.0.1 起，一条命令完成下载、SHA-256 校验、解压和部署。在交互式终端中执行：

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

脚本把交付包解压到 /opt/rst-ai-copilot-for-qradar，然后执行其中的 deploy.sh。所有版本使用同一个交付包，未激活许可时以社区版运行。

不使用安装脚本时，从 GitHub Releases 下载 RST-AI-Copilot-for-QRadar-<版本>.tar.gz 与同名 .sha256 文件，所有版本使用同一个交付包：

sha256sum -c RST-AI-Copilot-for-QRadar-<版本>.tar.gz.sha256
tar xzf RST-AI-Copilot-for-QRadar-<版本>.tar.gz
cd RST-AI-Copilot-for-QRadar-<版本>
sudo ./deploy.sh

交付包内含全部镜像，安装时不访问镜像仓库。其他选项和离线安装见交付包安装。

填写部署选项

认证方式选 1（网关自带登录），然后按提示填写大模型、时区、QRadar Console 地址与 SEC Token、Console 证书是否受信、访问域名和管理员口令。口令不少于 8 位。脚本生成内部密钥并写入 .env（权限 600），启动容器并打印访问地址，全程约两分钟。

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

验证

curl -k https://copilot.corp.local/healthz   # {"status":"ok"}
curl -k https://copilot.corp.local/readyz    # qradar / qradar_version

readyz 中 qradar 为 ok，qradar_version 是 Console 报告的版本。返回 503 时，qradar 字段给出原因：not_configured 表示尚未填写 Console，其他值是连接 Console 时的错误信息。

Token 权限

网关能看到的数据由 Token 背后的安全配置文件（Security Profile）和用户角色（User Role）决定。

项目	要求
安全配置文件	覆盖要查询的日志源和网络。范围之外的 Offense 不显示
用户角色	Ariel 搜索、Offenses、查看规则、日志源只读。关闭、备注、分配 Offense 需要 Offenses 写权限

单独创建一个授权服务给网关使用，不复用管理员 Token。完整说明见 QRadar Token 权限。

后续操作

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

升级

再次执行安装命令，或把新交付包解到同一目录后执行 sudo ./deploy.sh，选择保留现有 .env。脚本加载新镜像，把 GATEWAY_IMAGE_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 记录。

readyz 返回 503，qradar 为连接错误

网关主机到 Console 443 不通，或 QRADAR_URL 错误。Console 使用私有 CA 且开启了证书校验时，把 CA 证书放入 ./certs 并设置 RST_QRADAR_CA_CERT。

许可突然失效

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

其他症状见常见问题。

本页内容