快速开始

从交付包到能登录的最短路径：一台 Linux 主机、Docker、你现网的 QRadar Console 和一个授权服务 Token，跑一遍 deploy.sh。

准备

项	要求
主机	Ubuntu 20.04 / 22.04 / 24.04 或等价 Linux，2 vCPU / 4 GB / 20 GB+
运行时	Docker Engine 24+ 与 Docker Compose v2
QRadar	你现网的 7.5.x（REST API 20.0），Console 443 从网关主机可达
Token	一个授权服务 SEC Token（Admin → Authorized Services），其安全配置覆盖要查的日志源，用户角色带 Ariel / Offenses / Rules / Log Sources 读权限
大模型	一个 OpenAI 兼容端点的 URL / API key / 模型名（火山方舟 coding 计划用 `ark-code-latest`）
访问名	一个域名（如 `copilot.corp.local`），不能用裸 IP（IP 作 TLS SNI 不合规，部分浏览器握手失败）；没有内网 DNS 就给分析师机器加一条 hosts

入站只需 443（可选 80 跳转）。出站需要：大模型端点 443、QRadar Console 443、license.reallysec.com 443（离线部署可以没有，见许可）。

安装

装 Docker（如果还没有）

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

解开交付包

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

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

跑 `deploy.sh`

./deploy.sh

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

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

验证

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；带 401 的是 Token 无效或过期；连接类错误是网关主机到 Console 443 不通或地址填错。

Token 权限

网关能看到什么，由 Token 背后的安全配置（Security Profile）和用户角色（User Role）决定，网关自己不做更多。最少要：

安全配置：网关要查的日志源（或日志源组）、网络；Offense 只会看到这些范围内的
用户角色：Ariel 搜索、Offenses（要关闭 / 加备注 / 分配就得有写）、查看规则、日志源管理（只读）

建议单独建一个只带这些权限的授权服务，不要复用管理员 Token。细节见QRadar Token 权限。

安全建议：.env 里设 RST_LOG_SOURCE_WHITELIST=WinCollect @ *,PaloAlto-* 在 Token 之上再收一层：模型只能提及白名单内的日志源，每次 Ariel 搜索前也按它拦截。

装完之后

激活许可：付费引擎要它，试用许可免费。
/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` 503，原因带 401	Token 无效、过期，或授权服务被停用
`readyz` 503，连接错误	`QRADAR_URL` 填错；网关主机到 Console 443 不通；开了证书校验但 Console 是私有 CA 且没放 `RST_QRADAR_CA_CERT`
查询报 `qradar_forbidden`	Token 的用户角色缺 Ariel 权限，或安全配置不覆盖目标日志源
Offense 列表一直为空	安全配置不覆盖任何日志源 / 网络；`RST_OFFENSE_INGEST_LOOKBACK`（默认 7d）内没有 OPEN Offense
许可突然失效	是否重建过 `state/machine-id` / `state/server_guid`

本页内容