常见问题与基础 API (FAQ)

常用排错指南

Q: 服务启动后，管理台提示无法连接到后台？

A: 这通常由于前后端通讯跨域（CORS）或者 WebSocket 地址配置有误导致。 请按以下步骤排除故障：

1. 检查 docker-compose.community.yml 中分配给管理界面及 AppServer 的端口映射（默认 5173 / 3000）是否运行正常。
2. 确保配置文件的 .env 中的后端地址 URL 是可外界解析的 IP，而非虚拟的域名，如：VITE_API_BASE_URL=http://<您的IP>:3000/api/v1。
3. 参考「连接排障章节」重试。

Q: 为什么我在管理界面上看不到实时的呼叫卡片弹出来？

A:

• 首先确认左下角的 “总控台连接状态（WebSocket）”是否是绿色常亮态。
• 检查底层收集引擎 IE 容器是否收到了源头 PBX (如 Asterisk / FreeSWITCH) 发送的 SIP/HEP 信令，通过如下命令查看是否有解析日志滚动：

  docker-compose logs -f ie

• 若未有日志，请排查上游交换机有没有将包引流到 IE 服务器的特定端口（默认 UDP 9060 / UDP 5060）。

Q: 支持从 Windows 宿主机部署系统吗？

A: 技术上通过 WSL2 与 Docker Desktop 我们支持运行本系统，但我们推荐极力避免将生产环境部署在 Windows 上，尤其对于包含 UDP/RTP 高频次多通道通讯的软件，Linux (Rocky / Ubuntu) 的内核网络栈能提供成倍优异性能与稳定性保障。

---

开放基础 API 参考

系统提供一套面向集成开发者的基础 RESTful API（该体系为持续演进状态，详细入参和回调模型可能视版本轻微变动）。 使用 API 请在请求头带上您的管理员或 API Token : Authorization: Bearer <Token>。

1. 探活与状态检查

GET /api/v1/health

• 用途：返回系统基础微服务集的心跳存活指标及依赖库时延情况。

2. 获取实时活动通话集合

GET /api/v1/calls/active

• 用途：获得正在全系统中处于活动 (建立期/振铃/通话中) 状态的 JSON 数据表与摘要信息。

3. 获取坐席指标大屏卡片统计 (示例)

GET /api/v1/metrics/agents

• 用途：查询今日当前排队、正被接听或是发生告警事件的宏观坐席指标。