配置参考

配置

运行时配置从 apps/callout-server/config.json 读取。

• server.host / server.port：callout HTTP API 监听地址。

• auth.enabled / auth.sessionTtlSeconds：管理 API 鉴权开关和会话有效期。config.json 默认 enabled: true，本地联调可用 CALLOUT_AUTH_ENABLED=false 关闭。启用后会自动创建引导管理员账号（可用 CALLOUT_AUTH_BOOTSTRAP_ADMIN_USERNAME / CALLOUT_AUTH_BOOTSTRAP_ADMIN_PASSWORD 覆盖）。

• scheduler.enabled / scheduler.intervalMs / scheduler.batchSize：后台派发器开关、轮询间隔和每轮活动批次大小。只有 running 状态的活动会被自动派发。

• liveMonitor.defaultCapacity / liveMonitor.presenceTtlMs：每个活跃盯屏用户的默认通话容量（默认 5）与页面在线租约时长；也可用 CALLOUT_LIVE_MONITOR_CAPACITY / CALLOUT_LIVE_MONITOR_PRESENCE_TTL_MS 覆盖。

• lifecycleReconcile.enabled / lifecycleReconcile.intervalMs / lifecycleReconcile.stuckAfterMs：通话生命周期补偿任务配置，用于清理长期停留在 dialing / submitted 的联系人。

• conferenceReconcile.enabled / conferenceReconcile.intervalMs / conferenceReconcile.graceMs：转人工会议对账任务配置（默认每 30s 一轮，graceMs 60s 宽限期）。用 FreeSWITCH 实时成员数收尾「库里 active、FS 里已无成员」的僵尸会议会话；FreeSWITCH 不可达时整轮跳过，绝不误关。

• agentRegistrationReconcile.enabled / agentRegistrationReconcile.intervalMs：坐席注册对账任务配置（默认开启、每 30s 一轮）。用 FreeSWITCH show registrations 把「DB 在线 / 空闲但分机未注册」的坐席降级为 offline（记 agent_registration_offline 运行事件）。只降级不升级、busy 不动；仅当 agentDialStringTemplate 按 user/ 分机拨打时生效，FreeSWITCH 不可达时整轮跳过。

• emotionAnalysis.enabled / endpoint / timeoutMs / intervalMs / maxConcurrency / retryIntervalMs / maxRetries：通话后情绪分析 worker 配置，把已完成的呼叫尝试排队发往 onnx-platform/emotion-analysis-server 的 POST /analyze，结果写回 call_attempts.emotionResult。

• notifications.webhookUrl / notifications.minLevel / notifications.timeoutMs：运行事件告警 webhook。当前 payload 兼容常见文本 webhook，并附带结构化 level/type/message/payload 字段。

• internalApi.callResultToken：callflow-esl 回写 /api/call-results 的共享令牌。为空时兼容本地联调；生产环境建议配置，并让 callflow-esl 请求头带 X-Callout-Internal-Token。也可用 CALLOUT_INTERNAL_CALL_RESULT_TOKEN 覆盖。

• nlu.capabilitiesEndpoint / nlu.authToken / nlu.timeoutMs：统一 NLU 能力发现地址、内部 token 和代理超时。管理前端只访问 callout-server 的 GET /api/nlu/capabilities，不会获得 NLU 凭据；可分别用 CALLOUT_NLU_CAPABILITIES_ENDPOINT、CALLOUT_NLU_AUTH_TOKEN、CALLOUT_NLU_TIMEOUT_MS 覆盖。

• chat.capabilitiesEndpoint / chat.authToken / chat.timeoutMs：Chat profile 能力发现地址、内部 token 和代理超时。管理前端只访问 GET /api/chat/capabilities；可分别用 CALLOUT_CHAT_CAPABILITIES_ENDPOINT、CALLOUT_CHAT_AUTH_TOKEN、CALLOUT_CHAT_TIMEOUT_MS 覆盖。

• callflowEsl.baseUrl / callflowEsl.authToken：浏览器软电话会话代理的 callflow-esl HTTP 地址（其 http-server 端口，仓库配置 http://127.0.0.1:9912）与共享令牌（对应 callflow-esl http-server.authToken，代理请求放在 token 头）。可用 CALLOUT_CALLFLOW_ESL_BASE_URL / CALLOUT_CALLFLOW_ESL_AUTH_TOKEN 覆盖。多 FS 部署时按 cell 配置（见 cells），顶层值作为 cell 省略字段的默认值。

• softphone.serviceNumber：浏览器 SIP 软电话实际拨打的业务号（代码默认 8800，仓库配置 5020），需在 FreeSWITCH / callflow 侧路由到 browser-softphone-assist-business；见 docs/softphone-sip.md。可用 CALLOUT_SOFTPHONE_SERVICE_NUMBER 覆盖。

• media.freeswitchRecordingBaseUrl / media.emotionAudioBaseUrl：前端拼接媒体播放 URL 的前缀，通过 GET /api/media/config 下发。响应同时包含 freeswitchRecordingBaseUrlsByCell；前端与情绪分析 worker 按 attempt.cellId 选择录音前缀，只有历史空归属使用默认值，失效非空 cell 不生成 URL。

• freeswitchEvents.enabled / freeswitchEvents.reconnectIntervalMs：FreeSWITCH inbound ESL 事件监听配置，用于接听、挂机事件兜底同步。每个 cell 一个监听器；由 Redis 租约（callout:esl-listener:{cellId}，TTL 取 redis.lockTtlMs）保证每个 cell 只有一个消费者，持有实例崩溃后租约到期自动被其他实例接管。

• redis：必选依赖，服务启动时主动连接并执行 PING，失败则拒绝启动。连接字段为 host、port、username、password、db；keyPrefix 用于隔离 key，lockTtlMs 控制分布式锁和租约时长。不再支持 enabled 或 CALLOUT_REDIS_ENABLED 开关。

• db.url：PostgreSQL URL；callout 会从中派生 callout 与 callflow schema 客户端。

• cells：FS cell 列表，每项 = 一台 FreeSWITCH + 与之配对的 callflow-esl 实例，是多 FS 部署时并发额度、事件监听、软电话路由的分片单元。至少一项：

  • cells[].id：cell 稳定标识（必填且全局唯一，缺失或重复会阻止启动）；后续会写入活动/呼叫记录做归属关联，配置后不要变更。
  • cells[].freeswitch.host / port / password：本 cell 的 FreeSWITCH inbound ESL 连接信息。
  • cells[].freeswitch.callbackHost / callbackPort：FreeSWITCH 可访问的、与本 cell 配对的 callflow-esl outbound socket 地址。
  • cells[].freeswitch.originateDialStringTemplate：包含 的拨号串模板。
  • cells[].freeswitch.agentDialStringTemplate：坐席软电话呼出时使用的坐席分机拨号模板，默认 user/。
  • cells[].freeswitch.commandTimeoutMs：inbound ESL 命令超时。
  • cells[].callflowEsl.baseUrl / authToken：本 cell 配对 callflow-esl 的 HTTP API 地址与令牌。
  • cells[].media.freeswitchRecordingBaseUrl：本 cell 的录音播放 URL 前缀。
  • cells[].maxConcurrency：本 cell 允许的最大并发通话数，0 表示不限制。

  cell 中省略的字段逐字段继承顶层 freeswitch / callflowEsl / media.freeswitchRecordingBaseUrl（含对应环境变量覆盖后的值）；cell 显式写出的字段不再被环境变量覆盖。

• 单 FS 兼容：不配置 cells 时，顶层 freeswitch / callflowEsl / media 会被自动包装成唯一的 default cell，存量部署零改动。运行时顶层 config.freeswitch / config.callflowEsl / config.media.freeswitchRecordingBaseUrl 始终是 cells[0] 的镜像，供尚未按 cell 路由的存量代码使用。

带 CALLOUT_ 前缀的环境变量可以覆盖这些值，包括 CALLOUT_FREESWITCH_HOST、CALLOUT_FREESWITCH_PORT、 CALLOUT_FREESWITCH_PASSWORD、CALLOUT_FREESWITCH_CALLBACK_HOST、 CALLOUT_FREESWITCH_CALLBACK_PORT 和 CALLOUT_ORIGINATE_DIAL_STRING_TEMPLATE。注意 CALLOUT_FREESWITCH_* / CALLOUT_CALLFLOW_ESL_* 作用于顶层默认值：未配置 cells 时即生效于唯一 cell；配置了 cells 时只影响各 cell 省略的继承字段。

HTTP 层默认对浏览器全局返回 Access-Control-Allow-Origin: *。这不会放宽登录、Bearer Token、 内部 X-Callout-Internal-Token 等现有鉴权逻辑，只是取消来源白名单限制。

可选回铃音检测功能也提供环境变量（CALLOUT_RINGBACK_DETECTION_*）；见 回铃音检测。