常见问题

按症状查原因和处理。页面、模型、许可、权限、结果、集成、性能。

排障时先看三处：App 页面顶部横幅（许可、引擎、通道的即时提示）、调用审计中该次调用的错误码、index=_internal sourcetype=splunkd component=PersistentScript copilot（handler 的 Python 异常）。

页面

症状	原因与处理
App 打开为空白或旧界面	Splunk Web 缓存静态资源，App build 号变化后才更新。浏览器强制刷新（Ctrl+Shift+R）；升级后 build 未变时执行 `splunk restart splunkweb`
顶部出现 Splunk 的 Something went wrong 灰条	1.6.0 之前的加载器让懒加载的页面启动了两份 React。升级到 1.6.0 及以上
弹窗或下拉选择后无反应	同上，1.6.0 前的加载器隐藏了弹层。升级
语言切换不生效	切换会刷新页面。AI 输出语言由 `response_language` 单独决定

症状	原因与处理
测试连接失败	URL 需带版本路径（方舟为 `…/api/coding/v3`，不是 `…/api/v3`）；key 对该模型无权限；搜索头到端点的 443 不通
每次调用 30 秒以上	思考模式未关闭。在 AI 配置的 provider 卡把思考模式设为关闭；方舟同一提示词从 29 秒降到 5.8 秒
某模型一调用就 400	该模型不识别思考参数（方舟上的 kimi、glm、minimax）。1.8.0 及以上按模型家族发送参数；旧版把思考模式设为跟随模型默认
调查或平台解读超时	1.8.0 之前一轮工具调用没有上限。升级，或调小 `[agentic] max_tool_calls`。`requests` 引擎退回只试一次
引擎显示 `requests fallback`	fallback 包、Splunk 低于 10.2、或 `bin/lib/` 依赖缺失。AI 配置页写明原因；功能不缺
输出语言不正确	`[llm] response_language`：`auto` 跟随浏览器，`zh` 或 `en` 固定
`llm_error`	模型返回不是 JSON。模型偶尔用单引号 Python 字面量作答，1.7.0 及以上已兜底；连续出现时更换模型或关闭思考

症状	原因与处理
激活成功后立即提示绑定到另一台机器	1.6.0 前 phone-home 用了许可中的占位 GUID 计算指纹。升级后撤销再激活
`machine_id_unreadable`	容器没有 `/etc/machine-id`。启动时写入一个固定的 32 位十六进制值，不能每次随机
检测规则 `feature_sealed` 而许可有效	许可不含检测，或离线许可签发时未带密钥，或功能密钥未随激活下发（撤销后重新激活一次）
宽限期内	24 小时没有成功心跳。检查到 `license.reallysec.com:443` 的出站；`[license_server] url` 被 `local/` 覆盖过时改回

症状	原因与处理
所有 AI 请求 `forbidden`	用户没有任何 rst 角色，缺少 `copilot_use`。分配 `rst_copilot_viewer` 及以上
按钮提示需要分析员或管理员权限	档位不足，见角色与权限
存为 Report 报 `forbidden`（1.8.0）	`copilot_deploy` 整个端点被 admin 闸门拦截。升级到 1.8.0 验证修复版及以上
平台健康多项 `unknown`	用户对 `licenser`、`cluster` 等端点无读权限；Free 许可下集群端点返回 402

症状	原因与处理
结果持续为空	索引白名单未包含目标索引；数据不在时间窗内（卡片给出索引数据范围）；日志原文用词与问法不同（卡片列出放宽条件后的条数）
模型编造字段或负责人	模型不知道本实例有哪些 lookup 与宏。在处置手册同步 Splunk 对象
同一句两次结果不同	生成是非确定性的。需要固定时复制 SPL 或存为常用查询
纠错后下一次仍是原样	确认条选择了忽略；或命中缓存（1.9.0 已把知识库命中折进缓存 key）

症状	原因与处理
Incident Review 没有用 Copilot 调查	`workflow_actions.conf` 需要 `splunk restart` 生效；ES 的 Incident Review 只显示对 `event_id` 字段有效的动作
写回 ES `es_not_installed`	本机没有 ES，或 `SplunkEnterpriseSecuritySuite` 对当前用户不可见
部署规则 `deploy_rejected: alert.severity`	Splunk Free 许可不支持告警。Enterprise 正常
通道试发失败	行内显示通道原文：签名错误（飞书 19001）、域名不在白名单、URL 已失效
工单 `tickets_not_configured` 或 `ticket_auth_failed`	对外通道的工单系统未配置或凭据被拒；本地实例需列入 `[tickets] allowed_hosts`
定时任务（基线、KB 同步、自动分诊）不执行	脚本输入以 `splunk-system-user` 运行，Free 许可没有该用户
MCP 全部 401 或未响应	见 MCP 接入的排障

1.9.0 实测（火山方舟 ark-code-latest，思考关闭，agentic）：

明显慢于该量级时先检查思考模式和 [agentic] max_tool_calls。