├── .gitignore ├── Makefile ├── README.md ├── build.cmd ├── docker-compose.yml └── env.example /.gitignore: -------------------------------------------------------------------------------- 1 | conf 2 | .env 3 | 4 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | SHELL = /bin/bash 2 | 3 | all: 4 | @echo Hi 5 | 6 | setup: 7 | if [[ ! -f .env ]]; then \ 8 | cp env.example .env; \ 9 | fi 10 | 11 | run: 12 | docker-compose up -d 13 | 14 | start: 15 | docker-compose up 16 | 17 | bash: 18 | docker exec -it xswitch-free bash 19 | 20 | cli: 21 | docker exec -it xswitch-free fs_cli 22 | 23 | logs: 24 | docker logs -f --tail=100 xswitch-free 25 | 26 | stop: 27 | docker stop xswitch-free 28 | 29 | pull: 30 | docker pull ccr.ccs.tencentyun.com/xswitch/xswitch-free 31 | 32 | .PHONY conf: 33 | docker cp xswitch-free:/usr/local/freeswitch/conf . 34 | 35 | eject: conf 36 | @echo conf copied to local dir, please edit docker-compose.yml to use it 37 | 38 | get-sounds: 39 | wget -O sounds.zip https://xswitch.cn/download/sounds.zip 40 | unzip sounds.zip 41 | @echo "edit docker-compose.yml to use it" 42 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # xswitch-free 2 | 3 | `xswitch-free`是一个Docker镜像，与同款，有删减。本镜像一般都基于FreeSWITCH最新的版本，有一些我们自己的补丁。我们绝大多数的补丁都已经合并到了上游的FreeSWITCH仓库中，其它的一些补丁也会逐步开源出来。 4 | 5 | 很多朋友想试用FreeSWITCH，但是从源代码安装比较复杂。FreeSWITCH虽然有相应的安装包，但用起来也不那么方便。 6 | 7 | 现在，Docker已经成了事实上的部署方式，我们xswitch.cn早已采用Docker容器化部署。为了大家更容易使用，我们做了这一镜像，希望对大家有用。 8 | 9 | # 环境准备 10 | 11 | 首先，你要有一个Docker环境，如何安装Docker超出了本文的范围，您可以参阅以下链接，或自行查找相关资料安装。安装时注意有选择国内镜像站点的一些设置比较有用，在以后使用的时候可以节省一些下载镜像的时间。 12 | 13 | * https://www.runoob.com/docker/windows-docker-install.html 14 | * https://www.runoob.com/docker/ubuntu-docker-install.html 15 | * https://www.runoob.com/docker/macos-docker-install.html 16 | * https://yq.aliyun.com/articles/625403 17 | * https://docs.microsoft.com/zh-cn/windows/wsl/tutorials/wsl-containers （WSL2上的Docker远程容器安装入门） 18 | 19 | Docker Compose也需要安装，但不是必须的，只是安装了能更方便些，下面的命令大都依赖于Docker Compose。 20 | 21 | 本镜像支持在Linux、Mac、Windows宿主机上运行。 22 | 23 | # 快速上手 24 | 25 | 很简单，先看命令： 26 | 27 | ``` 28 | git clone https://github.com/rts-cn/xswitch-free.git 29 | cd xswitch-free 30 | make setup # 可选，生成.env，修改生成的.env里的环境变量 31 | make start 32 | ``` 33 | 34 | 首先，Clone本项目，然后进入`xswitch-free`目录，`make setup`会生成`.env`，里面是相关的环境变量，可以根据情况修改（一般至少要将EXT_IP改为你自己宿主机的IP）。最后`make start`会以NAT方式启动容器。 35 | 36 | 启动后，你就可以用你称手的软电话注册到FreeSWITCH的IP上（默认端口5060），**用户名和密码任意**，打电话可以看到日志，注册两个不同的号码可以互拨，试一把看爽不爽。 37 | 38 | 如果想进入控制台，可以打开另一个终端，执行`make cli`。 39 | 40 | # 环境变量 41 | 42 | 以下环境变量，有相关的默认值 43 | 44 | * `SIP_PORT`：默认SIP端口 45 | * `SIP_TLS_PORT`：SIP TLS端口 46 | * `SIP_PUBLIC_PORT` SIP `public` Profile端口 47 | * `SIP_PUBLIC_TLS_PORT`：SIP `public` Profile TLS端口 48 | * `RTP_START`：起始RTP端口 49 | * `RTP_END`：结束RTP端口 50 | * `EXT_IP`：宿主机IP，或公网IP，默认SIP Profile中的`ext-sip-ip`及`ext-rtp-ip`会用到它。 51 | * `FREESWITCH_DOMAIN`：默认的FreeSWITCH域 52 | * `LOCAL_NETWORK_ACL`：默认为`x`，在`host`网络模式下可以关闭。 53 | 54 | # 配置 55 | 56 | 本镜像没有使用FreeSWITCH的默认配置。FreeSWITCH的默认配置为了展示FreeSWITCH各种强大的功能设计，复杂且初学者难以理解，所以，我们使用了最小化的配置，目标是让使用者快速上手，并进一步细化打造自己的镜像和容器。 57 | 58 | 以下配置接受任何注册和打电话。也就是说，你可以用软电话。 59 | 60 | ```xml 61 | 62 | 63 | ``` 64 | 65 | 如果没有配置`EXT_IP`环境变量，需要将配置中如下内容注释掉。 66 | 67 | ```xml 68 | 69 | 70 | ``` 71 | 72 | # 常用命令 73 | 74 | 常用命令都在Makefile中，看起来也很直观。如果你的环境中没有`make`，也可以直接运行相关的命令。 75 | 76 | * `make setup`：初始化环境，如果`.env`不存在，会从`env.example`复制。 77 | * `make start`：启动镜像。 78 | * `make run`：启动镜像并进入后台模式。 79 | * `make cli`：进入容器并进入`fs_cli`。 80 | * `make bash`：进入容器并进入`bash` Shell环境。可以进一步执行`fs_cli`等。 81 | * `make stop`：停止容器。 82 | * `make pull`：更新镜像，更新后可以用。 83 | * `make get-sounds`：下载声音文件到本地，需要有`wget`工具。 84 | 85 | 如果没有安装Docker Compose，也可以直接使用Docker命令启动容器，如： 86 | 87 | ```bash 88 | docker run --rm --name xswitch-free \ 89 | -p 5060:5060/udp \ 90 | -p 2000-2020:2000-2020/udp \ 91 | -e ext_ip=192.168.7.7 \ 92 | -e sip_port=5060 \ 93 | -e sip_public_port=5080 \ 94 | -e rtp_start=2000 \ 95 | -e rtp_end=2010 \ 96 | ccr.ccs.tencentyun.com/xswitch/xswitch-free 97 | ``` 98 | 99 | 可以看出，这样需要输入很多参数，所以，还是使用Docker Compose比较方便。 100 | 101 | # 修改配置 102 | 103 | 可以直接进入容器修改配置，并在终端上`reload xml`或重载相关模块使之生效。但在容器重启后修改会丢失。 104 | 105 | 如果想保持自己的修改，那就需要把配置文件放到宿主机上。通过以下命令可以生成默认的配置文件。 106 | 107 | `make eject` 108 | 109 | 然后修改`docker-compose.yml`，取消掉以下行的注释： 110 | 111 | ```yaml 112 | volumes: 113 | - ./conf/:/usr/local/freeswitch/conf:cached 114 | ``` 115 | 116 | 修改后需要重启镜像： 117 | 118 | ```bash 119 | make stop 120 | make start 121 | ``` 122 | 123 | # 增加声音文件 124 | 125 | 本镜像为了压缩空间，没有将声音文件打包到镜像内。如果需要挂载声音文件，可以先执行`make get-sounds`命令下载声音文件，然后修改`docker-compose.yml`的`volumes`配置，增加挂载： 126 | 127 | ```yaml 128 | volumes: 129 | - ./sounds/:/usr/local/freeswitch/sounds:cached 130 | ``` 131 | 132 | # `host`模式网络 133 | 134 | 典型的Docker容器运行方式是NAT型的网络，有时候，使用`host`模式网络会比较方便（因为少了一层NAT）。本镜像不需要特殊的配置就可以使用`host`网络，只需要在`docker-compose.yml`中启用即可。 135 | 136 | 如果环境变量中没有`EXT_IP`，则可能无法启动Sofia Profile，请禁掉`default.xml`和`public.xml`中的`ext-sip-ip`和`ext-rtp-ip`参数。 137 | 138 | 默认的配置是NAT模式，我们在Profile中启动了如下配置： 139 | 140 | ```xml 141 | 142 | ``` 143 | 144 | 注意，该环境变量默认为`x`，它实际上是一个不存在的ACL，所以FreeSWITCH对任何来源IP都会认为它在NAT后面。 145 | 146 | 如果在`host`网络模式下可以在`.env`中注释掉这个环境变量，让它使用默认的`localnet.auto`。 147 | 148 | # 制作自己的镜像 149 | 150 | 你在本镜像的基础上制作自己的镜像。 151 | 152 | # 测试号码 153 | 154 | 默认配置可以拨打如下测试号码： 155 | 156 | ``` 157 | 9196 回音测试Echo 158 | 888 XSWITCH技术服务电话 159 | 3000 进入会议 160 | 其它号码，查找本地注册用户并桥接 161 | ``` 162 | 163 | # 报告问题 164 | 165 | 如果你发现有任何问题，请给我们提一个Issue。 166 | 167 | 欢迎提Pull Request。 168 | 169 | # 关于我们 170 | 171 | 我们是背后的团队。 172 | 173 | # FAQ 174 | 175 | * Q：本镜像是否适合在生产使用？ 176 | * A：我们就是在生产上使用的，所以，没有任何问题。只是，我们默认的配置是为了帮助大家学习和入门，没有过多考虑安全性，如果在生产上使用，需要仔细配置。另外，也强烈推荐使用我们有商业技术支持的版本，参见 。 177 | 178 | * Q：我可以安装其它软件吗？ 179 | * A：本镜像基于Debian Bullseye制作，你可以使用`apt-get update`以及`apt-get install xxxx`安装任何其它软件。 180 | 181 | * Q：在实际使用中，我们发现在Mac上，在使用UDP向FreeSWITCH注册的情况下，隔很短的时间注册就会失效，导致无法呼通终端，重新注册后能通。有什么好的解决方案吗？ 182 | * A：这可能跟Docker的NAT实现有关，使用TCP注册没有该问题。 183 | 184 | * Q：xswitch-free跑起来后，在Docker里面跑`ps`发现有两个freeswitch的进程，这个是正常的吗？ 185 | * A：是的，这是一个Feature。一个进程监控另一个，如果你Kill掉pid大的那一个进程，或者那个freeswitch进程崩溃了，监控进程就会重启一个。永远不死，生生不息。 186 | -------------------------------------------------------------------------------- /build.cmd: -------------------------------------------------------------------------------- 1 | @echo off 2 | setlocal 3 | 4 | if ""%1"" == ""setup"" goto doSetup 5 | if ""%1"" == ""run"" goto doRun 6 | if ""%1"" == ""start"" goto doStart 7 | if ""%1"" == ""bash"" goto doBash 8 | if ""%1"" == ""cli"" goto docli 9 | if ""%1"" == ""logs"" goto doLogs 10 | if ""%1"" == ""stop"" goto doStop 11 | if ""%1"" == ""pull"" goto doPull 12 | if ""%1"" == ""PHONY"" goto doPHONY 13 | if ""%1"" == ""eject"" goto doEject 14 | 15 | echo Usage: build ( commands ...) 16 | echo commands: 17 | echo setup make .env file from the env.example if it not exist 18 | echo run use docker-compose command to start the xswitch-free container with detached running 19 | echo start use docker-compose command to start the xswitch-free container with foreground running 20 | echo bash go into the xswitch-free container with bash 21 | echo cli go into the xswitch-free container with fs_cli 22 | echo logs catch the xswitch-free container logs 23 | echo stop stop xswitch-free container 24 | echo pull get the xswitch-free image 25 | echo PHONY get the xswitch-free container's config 26 | echo eject tips 27 | goto end 28 | 29 | :doSetup 30 | if not exist .env ( 31 | copy env.example .env 32 | ) 33 | goto end 34 | :doRun 35 | docker-compose up -d 36 | goto end 37 | 38 | :doStart 39 | docker-compose up 40 | goto end 41 | 42 | :doBash 43 | docker exec -it xswitch-free bash 44 | goto end 45 | 46 | :docli 47 | docker exec -it xswitch-free fs_cli 48 | goto end 49 | 50 | :doLogs 51 | docker logs -f --tail=100 xswitch-free 52 | goto end 53 | 54 | :doStop 55 | docker stop xswitch-free 56 | goto end 57 | 58 | :doPull 59 | docker pull ccr.ccs.tencentyun.com/xswitch/xswitch-free 60 | goto end 61 | 62 | :doPHONY 63 | docker cp xswitch-free:/usr/local/freeswitch/conf . 64 | goto end 65 | 66 | :doEject 67 | echo conf copied to local dir, please edit docker-compose.yml to use it 68 | goto end 69 | :end -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: "3.3" 2 | 3 | services: 4 | 5 | xswitch: 6 | container_name: xswitch-free 7 | image: ccr.ccs.tencentyun.com/xswitch/xswitch-free 8 | environment: 9 | - FREESWITCH_DOMAIN=free.xswitch.cn 10 | env_file: .env 11 | # command: ["bash"] 12 | # stdin_open: true 13 | # tty: true 14 | # network_mode: host 15 | ports: 16 | - "${RTP_START:-2000}-${RTP_END:-2100}:${RTP_START:-2000}-${RTP_END:-2100}/udp" 17 | - "${SIP_PORT:-5060}:${SIP_PORT:-5060}/udp" 18 | - "${SIP_PORT:-5060}:${SIP_PORT:-5060}/tcp" 19 | - "${SIP_PUBLIC_PORT:-5080}:${SIP_PUBLIC_PORT:-5080}/udp" 20 | - "${SIP_PUBLIC_PORT:-5080}:${SIP_PUBLIC_PORT:-5080}/tcp" 21 | # - "${VERTO_WS_PORT}:${VERTO_WS_PORT}" 22 | # - "${VERTO_WSS_PORT}:${VERTO_WSS_PORT}" 23 | # cap_add: 24 | # - SYS_PTRACE 25 | # - NET_ADMIN # for iptables to work 26 | # volumes: 27 | # - ./conf/:/usr/local/freeswitch/conf:cached 28 | -------------------------------------------------------------------------------- /env.example: -------------------------------------------------------------------------------- 1 | SIP_PORT=5060 2 | SIP_TLS_PORT=5061 3 | SIP_PUBLIC_PORT=5080 4 | SIP_PUBLIC_TLS_PORT=5081 5 | VERTO_WS_PORT=8081 6 | VERTO_WSS_PORT=8082 7 | RTP_START=10000 8 | RTP_END=10059 9 | ESL_PORT=8021 10 | EXT_IP=192.168.7.7 11 | FREESWITCH_DOMAIN=free.xswitch.cn 12 | # Comment out in host mode, and set to x in NAT mode 13 | LOCAL_NETWORK_ACL=x 14 | #FREESWITCH_DEFAULT_PASSWORD=1234 15 | #FREESWITCH_EVENT_SOCKET_PASSWORD=1234 16 | --------------------------------------------------------------------------------