XSwitch用户手册

xtra_config 参数详解 {#xtra-config}

xTra 是 XSwitch XUI 的底层 REST 框架，使用 Lua 语言开发，我们未来将开源核心的框架，也会开放相关的框架文档。在此，我们仅讨论xtra_config.lua配置文件中的参数。

xtra_config.lua是一个标准的 Lua 文件，导出一个config Table，是 xTra 框架的全局配置。修改配置文件会立即生效。基本配置格式为：

local config = {}
config.key = "value"
return config

xtra_config.lua配置文件的搜索顺序优先级如下：

  • /etc/xtra/
  • vendor的上一层目录
  • vendor目录

其中，vendor是 xTra 框架的目录，一般建议放到vendor的上层目录。目前，vendor在 XUI 代码内容，XUI 代码安装位置默认位于 FreeSWITCH 安装目录下，如/usr/local/freeswitch/xui。如果你拿到的是 XSwitch 发行版的 Docker，xtra_config.lua一般位于宿主机上，以便在 Docker 容器停止后修改过的内容不失效。可以将该文件挂载到 Docker 容器内上述任意目录。

配置文件中有些参数已没有实际使用，但由于历史原因而存在。有些参数的值也不能改动。总的原则是，如果你不知道参数的细节，就保持原来的默认值。

下面是该配置文件的默认值及解释，先参数，后解释。在 Lua 中，--代表注释。

-- config.file = debug.getinfo(1).source

该参数是只读的，用于记录xtra_config.lua文件的实际路径，方便调试。如在同时有多个文件的情况下，可以打印出该路径以判断哪个是实际生效的。该参数在使用luac编译后的 Lua 中不能正确获取文件路径，可以使用指定的字符串，如：

config.file = '/etc/xtra.lua'

该参数对 XUI 实际运行无影响。

config.dsn = os.getenv("DSN")

配置数据库连接字符串。XUI 早期的版本支持 SQLite，新的版本已不支持，上述配置中从环境变量中获取连接参数，因而你可以使用在.env中指定的环境变量。

该参数取值如下，推荐使用最后一种：

-- SQLite连接字符串
config.dsn = "sqlite://xui"
-- ODBC连接，需要配置odbc.ini
config.dsn = "odbc://xui:xui:xui"
-- 原始PostgreSQL连接字符串
config.dsn = "pgsql://host=xswitch-pg dbname=xui user=xui password='xui' "
-- 现代PostgreSQL连接字符串，需要PostgreSQL 9以上版才支持
-- config.dsn = "pgsql://postgresql://用户名:密码@主机名/数据库名"
config.dsn = "pgsql://postgresql://xui:xui@xswitch-pg/xui"

-- config.check_permissions = true

无效。

config.redis_host = "xswitch-redis"
config.redis_port = 6379
-- config.redis_pass = nil

Redis 连接参数。XSwitch 支持连接 Redis，可以用作用户登录鉴权的 Session 存储，也可以支持 XSwitch 内部的并发控制等。

config.db_auto_connect = true

是否自动连接数据库，必须为true。

config.auto_record = false

是否自动录音。目前仅对cti有效。

config.auto_log = false

是否自动写日志。如果打开，所有的增、删、改等 REST 操作将会写到数据库中，可以在 XUI 上的日志菜单中查看。

config.base_dir = "/usr/local/freeswitch"

FreeSWITCH 安装目录。

config.sounds_dir = config.base_dir .. "/sounds"

系统声音文件目录（只读）。

config.storage_dir = config.base_dir .. "/storage"

系统存储目录。该目录中存储可变的内容，如通话过程中产生的录音等。该目录应该是可写的，在 Docker 容器中应该挂载宿主机上的目录以支持持久化存储。

config.recording_path = config.base_dir .. "/storage/recordings"

录音存储路径。

config.fiforecord_path = config.base_dir .. "/recordings"

mod_fifo录音存储路径。

config.callcenterrecord_path = config.base_dir .. "/recordings"

mod_callcenter录音存储路径。

config.upload_path = config.base_dir .. "/storage/upload"

上传媒体文件存储路径。

config.block_path = config.base_dir .. "/storage/blocks"

积木脚本存储路径。

config.xui_path = config.base_dir .. "/xui"

XUI 后台脚本存储路径。

config.audio_extension = "wav"

录音文件默认扩展名。可以是wav或mp3。

config.video_extension = "mp4"

录像文件默认扩展名。目前仅支持mp4。

config.ivr_greeting = "ivr/ivr-generic_greeting.wav"
config.ivr_invalid = "ivr/ivr-that_was_an_invalid_entry.wav"

IVR 相关语音。

config.audio_codec = "G722,PCMU,PCMA,GSM,G729,iLBC"
config.video_codec = "VP8,H264,G722,PCMU,PCMA,GSM,G729,iLBC"

外呼是使用的默认的音视频编码，目前仅针对会议自动外呼有效。

config.openvpn_path =  "/root/keys"

OpenVPN 相关配置。

config.switch_domain = "xswitch.cn"

外呼时使用的域。目前仅对会议有效。

config.switch_port = "8000"

外呼时使用的端口号。目前仅对会议有效。

config.abnormal_instant_conference_timeout = "120"

会议相关。

config.auth = "hash" -- or true | file | hash | redis

HTTP 认证鉴权 Session 的存储方式。

  • hash：存在 FreeSWITCH 内部哈希表中，重启后浏览器端所有用户都需要重新登录。
  • true：跟hash一致。
  • file：存储到文件中，可以持久化，FreeSWITCH 重启后无需重新登录。
  • redis：存储到 Redis 中，比file更高效，而且可以多台 FreeSWITCH 共享。
config.session_path = "/tmp"

如果开启file Session 存储，设置 Session 文件的路径。

config.force_domain = 'xswitch.cn'

强制用户的域都是该值。FreeSWITCH 是一个多租户系统，但是在小型应用中使用起来会很复杂。开启该选项后所有用户都属于同一个域。

config.record_answer = true

应答后录音，如果设置为否，录音时则从振铃开始就录音

-- config.password_use_a1_hash = true

是否开启 A1 哈希加密支持。如果不开启则密码是明文的。A1 哈希跟域有关，如果开启后，以后改变域时必须让所有用户修改密码。

config.view_path = config.base_dir .. "/xui/lua/xui/view"

xTra 是一个 MVC 框架，该选项配置 View 的路径。XUI 是前后端分离的，前后端数据交互使用 JSON 格式，不使用 View。

config.leg_timeout = "50"

呼叫超时设置，目前仅针对呼叫本地分机及本地分机中无应答转接时的超时时长

-- config.prefix_table = "gw"

Todo.

-- config.httpFifoNotificationURL="http://localhost:9999"

特殊应用。在呼叫中心应用中，用于简单的来电弹屏通知。

config.tz = 8

时区，东八区为北京时间。

-- config.cross_domain="http://192.168.3.119:8081"
-- config.cross_domain="*"

配置 HTTP 跨域支持（CORS），*代表接受所有来源（Referer）。

-- config.conferenceForceMatchCID = true

会议安全选项，呼叫会议的主叫号码必须匹配到一个预置的成员才能呼入，详细见会议相关文档。

config.wechat_base_url = "http://example.com"
config.wechat_realm = "xyt"
config.template_id = "Mu6mySnQiCRdCa5QmJSCBOSIkAxjgm3CuUpp6FqTCnA"
-- config.wechat = {}
-- config.wechat.xyt = {APPID = 'wx', APPSEC = ''}
-- config.ticket_type_wechat_default = 'TICKET_TYPE_0' -- default ticket type from wechat

微信公众号集成，支持简单的工单集成。

config.allow_change_ip = false

是否允许在界面上修改 IP 地址。在 Docker 中不允许。

-- config.qywechat = {}
-- config.qywechat.CorpID = ''
-- config.qywechat.CorpSecret = ''
-- config.qywechat.AgentID = 10001
-- config.xui_url = "https://xswitch.cn"
-- config.qywechat_webhookkey = 'f588ba02xxxxxxxxx'

企业微信集成。

-- config.callcenter_bridge_failed_to_break = true

Callcenter 相关设置。

-- config.conference_use_pin = true

会议是否使用密码。

config.upload_max_size = os.getenv("UPLAOD_MAX_SIZE") or "100M"

最大上传文件大小。

config.node_subject_prefix = os.getenv("NODE_SUBJECT_PREFIX") or "cn.xswitch.node"

通过配合mod_xcc模块使用，默认订阅前缀

config.cc_track_on = true -- track callcenter

签入Callcenter队列的空闲或示忙状态下坐席外呼时，XSwitch不再向其分配新呼叫。默认关闭。

config.cc_track_hangup_unavail_agent = true

不允许非签入状态下的坐席发起外呼，与config.cc_track_on = true同时使用才生效。默认关闭。

config.cc_fire_agent_state = true

当坐席状态发生改变时，产生Event-Name为CUSTOM，Event-Subclass为agent_state的ESL事件。默认关闭。

config.cc_support_acw = true

Callcenter坐席开启acw话后处理功能。修改配置完成后，需将目标坐席重新签入、签出一次。默认关闭。

config.cc_record_template = "$${base_dir}/storage/recordings/${strftime(%Y%m%d)}/cc-${strftime(%H%M%S)}-${caller_id_number}-${destination_number}-${uuid}.mp3"

签入Callcenter坐席发起外呼时自动录音，与config.cc_track_on = true同时使用才生效。默认关闭。

-- config.enable_stereo = true

是否为立体声录音，默认为单声道

-- config.record_file_replace_prefix = "http://yd.xswitch.cn"  -- url or directory

录音文件前缀，暂时不启用

config.custom_about = "xyt"

是否显示关于页面中的系统版本等信息，如果不显示则随意修改为其他值即可

-- config.cluster = true  -- Kamailio <-> FS cluster
-- config.cluster_ik_gateway = "internal_kamailio"  -- the gateway name to internal Kamailio
-- config.cluster_gk_gateway = "gateway_kamailio"  -- the gateway name to gateway Kamailio
-- token to send http rpc request to kamailio
-- config.with_kamailio = true
-- config.kamailio_servers = os.getenv("KAMAILIO_LIST")
-- config.kamailio_servers = 'gw-kam:9060'
--config.kam_http_token = os.getenv("KAM_HTTP_TOKEN")
--config.kam_http_token = 'Bearer ' .. os.getenv("KAM_HTTP_TOKEN")

集群相关设置，与 Kamailio 配合部署。

config.forget_password = true

是否允许自助找回密码。

config.free_register = true

是否允许自动注册。

config.register_audit = true

注册是否需要审核。

config.callback_gateway = "callback"

回呼是使用的网关。

config.codec_list = "PCMA,PCMU,G729,G722,OPUS,VP8"
-- config.codec_list = os.getenv("GW_CODECS") or "PCMU,PCMA,G729,G722,OPUS,VP8,H264"

默认的编解码列表。

-- config.tts_engine = "tts_baidu"
-- config.tts_voice = 'ting-ting'

TTS 相关设置，默认 TTS 引擎。

-- config.with_opensips = true

与 OpenSIPS 配合使用。

-- config.force_jwt = true

接口开启 JWT Token。如果开启，则会强制生成 JWT Token。

config.jwt_secret = 'secret'

JWT token 的密钥。

config.session_expires = 3600 * 24

XUI Web Cookie 有效的最长空闲时间（即两次请求的间隔时长）或 Rest API 接口 Token 的有效时长，单位是秒。

config.check_contacts = true

呼入时是否检测通讯录，如果设置为 true，那么呼入号码会去通讯录中检查是否存在该用户，如果存在，则修改为通讯录中的名称显示

config.with_nginx = false

和媒体文件录音文件播放有关，如果与 Nginx 配合使用，可设置为true。该参数主要是启用 Nginx 的sendfile支持。

config.dtmf_cdr = false

是否在话单中显示 DTMF 按键结果，默认不显示。

-- config.uas_url = "ws://127.0.0.1:9090/stream"

连接 UAS 的 Websocket 地址，该参数仅针对特殊的会议集群使用。

config.short_nbr = false

是否开启会议中短号功能，默认不开启。改为 true 后，则在创建预约会议时则会显示短号功能。

config.provision = false

是否开启话机自动配置，默认不开启。改为 true 后，则可使用话机自动配置功能。

config.captcha_png_path = "/tmp"

图形验证码存储位置

config.captcha = false

登录页面是否启用图形验证码，默认不开启，设置为 true 后，登录页面失败两次则会出现图形验证码页面。

-- config.captcha_fail_limit = 2

开启图形验证码后，根据此参数设置的次数决定登录页面何时出现图形验证码，比如默认登录失败 2 次才显示图形验证码。

config.secure_password = false

是否开启强密码功能，默认不开启，设置为 true 后，用户和分机则会开启强密码验证。

-- config.media_file_types = "wav,mp3,mp4"

该参数限制系统媒体页面上传文件类型，如果开启了，则只有设置的这几种类型文件才可以上传

config.login_with_rsa = false

系统登录是否启用 rsa

config.rsa_private_key = xxxxx

rsa 私钥

config.rsa_public_key = xxx

rsa 公钥

与其它系统对接
外呼管理