Add files via upload

docs/zh-CN/troubleshooting.md

@@ -0,0 +1,224 @@
+# 排错指南
+
+本文按现象列出常见问题。优先查看服务日志、浏览器控制台和 `/api-docs` 中的接口响应。
+
+## 无法访问页面
+
+检查：
+
+- 服务是否启动。
+- 端口是否被占用。
+- 配置中是否启用 HTTPS。
+- 访问协议是否正确。
+
+默认配置常见地址：
+
+```text
+https://127.0.0.1:8080/
+```
+
+如果使用自签证书，浏览器会提示不受信任，需要手动继续访问。
+
+## 登录失败
+
+检查：
+
+- `config.yaml` 中的 `auth.password`。
+- 是否修改后未重启或未应用配置。
+- 浏览器 Cookie 是否异常，可尝试无痕窗口。
+- 审计日志中是否有登录失败节流。
+
+生产环境忘记密码时，需要在服务器上修改 `config.yaml` 并重启服务。
+
+## 模型无响应
+
+检查：
+
+- `openai.base_url` 是否包含正确路径，如 `/v1`。
+- `openai.api_key` 是否有效。
+- `openai.model` 是否存在。
+- 服务商是否支持当前 `reasoning` 字段。
+
+可在系统设置中使用模型测试。若网关报 400，先尝试：
+
+```yaml
+openai:
+  reasoning:
+    mode: off
+```
+
+## 流式输出中断
+
+常见原因：
+
+- 反向代理缓冲 SSE。
+- 模型网关超时。
+- 浏览器网络断开。
+- 上下文过大。
+
+Nginx 需要：
+
+```nginx
+proxy_buffering off;
+proxy_http_version 1.1;
+```
+
+## 工具执行失败
+
+检查：
+
+- 工具命令是否已安装到 PATH。
+- `tools/*.yaml` 参数 schema 是否正确。
+- 是否被 HITL 拒绝。
+- 是否超过 `agent.tool_timeout_minutes`。
+- Shell 长时间无输出是否触发 `shell_no_output_timeout_seconds`。
+
+工具配置可参考 `tools/README.md`。
+
+## MCP 连不上
+
+内置 MCP：
+
+- 检查 `mcp.enabled`。
+- 检查 `mcp.port`。
+- 检查 `auth_header` 和 `auth_header_value`。
+
+外部 MCP：
+
+- stdio：检查命令路径、工作目录、环境变量。
+- HTTP/SSE：检查 URL、认证、网络连通性。
+- 查看 `/api/external-mcp/stats`。
+
+## 知识库不可用
+
+检查：
+
+- `knowledge.enabled: true`。
+- embedding 配置是否正确。
+- 是否已经扫描并重建索引。
+- `data/knowledge.db` 是否可写。
+- 嵌入服务是否 429 或超时。
+
+如果索引大量失败，降低：
+
+```yaml
+knowledge:
+  indexing:
+    batch_size: 5
+    rate_limit_delay_ms: 600
+```
+
+## 机器人没有回复
+
+检查：
+
+- 对应平台 `robots.<platform>.enabled`。
+- 平台回调 URL 是否指向 `/api/robot/...`。
+- Token、secret、verify_token 是否一致。
+- 服务器是否可被平台访问。
+- 群聊是否需要 @ 机器人。
+
+详细步骤见 [机器人使用说明](robot.md)。
+
+## C2 监听器启动失败
+
+检查：
+
+- `c2.enabled`。
+- 端口是否被占用。
+- 防火墙或安全组。
+- 是否需要管理员权限绑定低端口。
+
+关闭 C2 后 `/api/c2/*` 返回 503 是预期行为。
+
+## WebShell 命令乱码
+
+处理：
+
+- 确认目标系统编码。
+- 尝试更短命令。
+- 使用 base64 包装输出。
+- Windows 目标检查代码页。
+
+## 数据库锁或写入失败
+
+检查：
+
+- `data/` 是否可写。
+- 是否多个实例共用同一个 SQLite 文件。
+- 磁盘是否满。
+- 是否异常复制了 WAL/SHM 文件。
+
+生产环境不要让多个进程同时写同一份 SQLite 数据库。
+
+## 前端页面异常
+
+检查：
+
+- 浏览器控制台错误。
+- 静态资源是否加载成功。
+- 修改前端后是否刷新缓存。
+- i18n key 是否缺失。
+
+接口异常时打开 `/api-docs` 对照请求体。
+
+## 诊断顺序
+
+遇到问题时不要直接改配置，先定位层级：
+
+1. 进程：服务是否还在，日志是否有 panic。
+2. 网络：端口、HTTPS、反向代理、浏览器控制台。
+3. 认证：`/api/auth/validate` 是否 200。
+4. 配置：`/api/config` 是否能读，应用后是否报错。
+5. 模型：模型测试是否通过。
+6. 工具：工具列表和单个 schema 是否正常。
+7. 数据库：`data/` 是否可写，有无锁。
+8. 业务模块：知识库、MCP、C2、WebShell 分别测最小动作。
+
+先定位层级，再改参数。否则容易把一个代理问题误判成模型问题。
+
+## 最小诊断命令
+
+```bash
+# 进程和端口
+lsof -i :8080
+
+# 本机 HTTPS 是否通
+curl -k -I https://127.0.0.1:8080/
+
+# 静态资源是否通
+curl -k -I https://127.0.0.1:8080/static/logo.png
+
+# 查看数据库文件
+ls -lh data/
+```
+
+如果经过 Nginx，再分别测代理地址和回源地址，确认问题在哪一层。
+
+## 常见误判
+
+- “模型坏了”：实际是 HITL 挂起等待审批。
+- “工具没加载”：实际是 tool_search 隐藏了大部分工具。
+- “知识库没效果”：实际是索引没重建或 risk_type 过滤过窄。
+- “C2 接口坏了”：实际是 `c2.enabled: false`，返回 503 是正常保护。
+- “配置保存了但没生效”：实际是监听端口/TLS 需要重启。
+- “机器人不回复”：实际是平台侧没有正确配置回调 URL 或验签参数。
+
+## 故障报告模板
+
+提交问题时建议附：
+
+```text
+版本/提交：
+启动方式：
+访问方式：http/https/反向代理：
+相关配置段：
+复现步骤：
+预期结果：
+实际结果：
+服务端日志：
+浏览器控制台：
+相关接口响应：
+```
+
+有了这些信息，定位速度通常会快很多。