安装指南

XSwitch 以 Docker 镜像方式提供，需要先下载一些安装脚本，安装脚本在安装过程中需要从 XSwitch 官网上下载镜像及需要的资源文件，请保持网络畅通。在没有公网的环境下安装，请参考 离线安装。

以下步骤将安装最新的 XSwitch v6.4.0 稳定版, 此版本分为 2 种镜像，分别基于 Debian 12 与 Debian 13 最新基础镜像（20250929）编译。

如果你有 wget，可以通过如下命令下载：

社区版（Debian 12）

wget https://xswitch.cn/download/xswitch-community-6.4.0.tar.gz --user xswitch --password password

或直接 点击这里下载社区版；

企业版（Debian 12）

wget https://xswitch.cn/download/xswitch-6.4.0.tar.gz --user xswitch --password password

企业版不提供镜像下载，如果需要下载使用，可联系客服人员。

如果系统没有安装 wget，也可以通过系统自带的 curl 命令进行下载

curl -u xswitch:password -O https://xswitch.cn/download/xswitch-community-6.4.0.tar.gz
curl -u xswitch:password -O https://xswitch.cn/download/xswitch-6.4.0.tar.gz

XSwitch 可以安装到任意有权限的目录。我们推荐将 XSwitch 安装到以下位置（任选其一）：

• /usr/local/xswitch-community-6.4.0
• /opt/xswitch-community-6.4.0
• /root/xswitch-community-6.4.0
• /home/yourname/xswitch-community-6.4.0

下列命令将 XSwitch 安装到 /usr/local/xswitch-community-6.4.0 目录下，请确保有写入权限，如果使用企业版则修改相应的目录。

tar zxvf xswitch-community-6.4.0.tar.gz -C /usr/local

cd /usr/local/xswitch-community-6.4.0

大家也可以尝鲜，享受使用 Debian 13 系统编译的 XSwitch 镜像。以下是下载地址：

社区版（Debian 13）

wget https://xswitch.cn/download/xswitch-community-6.4.0-trixie.tar.gz --user xswitch --password password

上述命令需要你有对应目录（/usr/local）的写权限，如果没有权限，你也可以忽略 -C 以及后面的参数，直接解压到当前目录。

请严格按照以下步骤执行。

make setup

执行此命令会自动从 XSwitch 官网下载声音文件和生成 .env 文件，.env 里的参数为 Docker 容器运行时的环境变量。

注意：.env 文件在 Linux 下默认是个隐藏文件，可以使用 ls -la 或 find . -name .env、cat .env 等命令显示，详见 Docker 关于 .env 文件的相关说明。

打开 .env 文件，修改如下几个参数：

EXT_IP=22.22.2.2     # 这是外网地址（如果是内网使用，填写内网地址即可）
LOCAL_IP=192.168.1.1 # 这是内网地址（如果是内网使用，填写内网地址即可），如果是 Mac 则无此参数
FREESWITCH_DOMAIN=demo.xswitch.cn # 这是填写域的地方（用户或分机的域，可根据需要自行设置，也可以设成 IP 地址）

特别注意：FREESWITCH_DOMAIN 若是修改域名，会导致页面登录提示密码错误，需要执行 bash update.sh 命令。

NGINX_PROXY_IP=192.168.1.1 # 和 LOCAL_IP 填写相同内网地址即可，如果是 Mac 无需改动
HTTP_PORT=8080             # HTTP 网址访问的端口（比如设置了 8080，访问时输入 http://ip: 8080）

以下参数基本不用改动

DSN=postgresql://xui:xui@127.0.0.1/xui # 数据库连接地址，Mac 下路径稍有不同
SIP_PORT=7060                          # UDP 注册端口号
SIP_TLS_PORT=7061                      # TLS 注册端口号
SIP_PUBLIC_PORT=7080                   # public 对应端口号，用于网关对接等
SIP_PUBLIC_TLS_PORT=7081               # TLS Public 对应端口号
VERTO_WS_PORT=8081                     # Verto WS 对应端口号
VERTO_WSS_PORT=8082                    # Verto WSS 对应端口号
RTP_START=10000                        # RTP 媒体允许使用的最小端口
RTP_END=10099                          # RTP 媒体允许使用的最大端口
ESL_PORT=8021                          # ESL 对应端口

注意，如果在 NAT 环境下（非 host 网络，在 macOS 上必须使用 NAT）RTP 端口段不要开得太大，否则会影响效率。如果在生产环境中使用，请咨询 XSwitch 系统支持工程师获取最佳配置方案。

目前测试能够支持 bookworm 镜像的最低 docker-ce 版本是 20.10.10，同时它还与 libseccomp 版本有关，如果低版本 docker 不想升级，或者由于系统版本过低，不能升级。可以通过添加参数 --security-opt seccomp=unconfined，禁用内核安全配置来解决这个问题。 docker-compose.yml 中禁用 seccomp 的办法。

    security_opt:
      - seccomp:unconfined

make up

启动系统。首次运行会自动拉取镜像。启动后，可以通过 http://你的服务器IP:8081 访问 Web 界面。默认用户名是 admin，默认密码获取请关注 小樱桃科技微信公众号，关注成功后，输入 admin 即可获取新版本密码。

如果使用 NATS 功能，使用以下命令可以启动/关闭 nats。默认端口：4222。调用地址：nats://xswitch-nats: 4222 或 nats://127.0.0.1:4222。

make nats

make down-nats

注意，WARN [0000] /usr/local/xswitch-community-6.4.0/docker-compose.yml: version is obsolete; 启动时，如有上述警告，可将 docker-compose.yml 文件第一行注释掉或删除。

在 Windows 上安装 XSwitch 有两种方法，一种是在 Windows 上通过 Docker Desktop 运行 XSwitch，另一种是在 WSL 2 内部的 Linux 系统中通过 Docker Engine 运行 XSwitch 。这两种方式都需要你安装 WSL 2。

下面，我们分别介绍这两种方法。你可以选择一种方式安装和运行 XSwitch，也可以根据情况切换。

首先你需要安装 WSL 2（适用于 Linux 的 Windows 子系统）和 Docker Desktop。

WSL 2 可以让你在 Windows 计算机上运行 Linux 环境，而无需单独的虚拟机或双引导。

Docker Desktop 可以让你在 Windows 上运行 Docker 。

点击这里查看 Docker Desktop 和 WSL 2 的安装方式。

以下命令要在 Windows Terminal 中运行。

curl -u xswitch:password "https://xswitch.cn/download/xswitch-community-6.4.0.tar.gz" --output xswitch-community-6.4.0.tar.gz

tar zxvf xswitch-community-6.4.0.tar.gz

cd xswitch-community-6.4.0
.\build.cmd setup

用 sublime text 或 vscode 等编辑器打开 .env 文件，将 EXT_IP 的值修改为 Windows 的 IP 地址，如果想修改其他配置参数可以参考 XSwitch 官方文档 。

.\build.cmd start

等待服务启动，首次启动需要拉取镜像，根据网络状况大概需要 2 - 5 分钟时间。

进入 XSwitch 容器

.\build.cmd bash

进入 XSwitch Cli 控制台

.\build.cmd cli

实时查看 XSwitch 日志

.\build.cmd logs

停止服务

.\build.cmd stop

WSL 2 有两种网络模式，默认模式为 NAT 模式，还有一种叫镜像模式网络。

这里我们推荐使用镜像模式网络，因为 NAT 模式下想要让局域网内的设备访问 XSwitch 的服务，需要在 Windows 上做端口代理，而官方给的代理方案是用 netsh interface portproxy，这种代理仅支持 TCP 协议，而 XSwitch 的媒体传输协议是 UDP ，所以局域网内的终端与 XSwitch 的媒体是不通的。

需要启用镜像模式网络，点击查看镜像模式启用方法 。

在 Windows Terminal 中输入 wsl 进入 Linux 环境。

安装 XSwitch 的方法与 如何在 Linux 和 Mac OS 上安装 XSwitch 相同 。

在自己的 Windows 上访问 XSwitch ，可以通过 localhost 或者 Windows 的 IP 地址访问。

从局域网访问 XSwitch，需要 关闭 Windows 的防火墙 或者给所有用到的端口 添加相应的入站出站规则，然后访问 Windows 的 IP 地址即可。

通过执行 docker ps 可查看 docker 服务是否已正常启动。

如果有服务启动出错，可通过执行 docker logs -f xswitch 查看 xswitch 容器相关日志（xswitch 为容器名）。

通过执行 make bash 进入 xswitch 容器内部，然后输入 fs_cli 可以连接控制台查看系统运行情况。