本文还有配套的精品资源点击获取简介一个纯Java实现的轻量级SIP软电话客户端不依赖复杂构建环境导入源码后直接运行net.sourceforge.peers.gui.MainFrame类就能启动图形界面。支持主流SIP服务器重点适配FreeSWITCH用户只需填写SIP账号如1001、密码如1234和服务器IP如192.168.1.10即可完成注册并发起语音呼叫。音频底层基于javax.sound兼容普通声卡设备支持RTP实时传输及G.711等基础编解码。项目自带完整Maven配置pom.xml、SIP参数配置文件peers.xml、XSD校验定义、GPL开源协议说明和多版本README所有依赖由Maven自动拉取。代码结构清晰模块分离明确包含peers-gui界面、peers-lib核心协议栈、peers-javaxsound音频适配、peers-demo示例等子模块适用于SIP协议学习、内网语音功能验证或定制化二次开发。Windows、Linux、macOS平台均可原生运行无需额外安装JVM以外的运行时组件。1. 项目概述为什么这个Java软电话值得你花15分钟搭起来我第一次在内网测试FreeSWITCH的SIP注册流程时用过七八个客户端——Linphone、Zoiper、MicroSIP、Bria……但真正让我停下来、反复调试并最终写进团队内部文档的是一个叫Peers的开源Java软电话。它不是最漂亮的也不是功能最全的但它解决了一个被绝大多数教程忽略的痛点“我想立刻验证SIP账号能不能注册成功而不是先配环境、装依赖、改配置、编译失败三次再查日志”。这个项目标题里说的“即开即用”不是营销话术。它真实意味着你下载完源码包解压用IDEIntelliJ或Eclipse导入为Maven项目右键点击net.sourceforge.peers.gui.MainFrame→ Run3秒后弹出一个朴素但功能完整的图形界面——输入账号、密码、服务器地址点“Register”状态栏立刻显示“Registered”然后点“Call”就能和另一台设备上的SIP终端通上话。整个过程不需要安装任何额外的音频驱动、不依赖系统级SIP栈、不调用本地DLL或so库纯Java实现跨平台零适配成本。关键词里的“Java软电话”、“SIP客户端”、“FreeSWITCH对接”其实指向三个层次的需求- 对初学者它是理解SIP REGISTER/INVITE/ACK/BYE信令流的“透明玻璃盒”。所有SIP消息构造、头域填充、事务管理、状态机跳转都在peers-lib/src/main/java/net/sourceforge/peers/sip/下清晰可读- 对运维/测试人员它是内网语音连通性验证的“最小可信单元”。不依赖公网DNS、不走STUN/TURN、不碰NAT穿透逻辑直连FreeSWITCH的SIP端口默认5060注册失败时错误码401 Unauthorized / 403 Forbidden / 408 Request Timeout直接映射到FreeSWITCH的sip_registrations日志排查链路极短- 对开发者它是二次开发的“干净基座”。模块划分明确——peers-gui只管界面交互与事件分发peers-lib封装完整SIP协议栈含UDP/TCP传输层、Dialog管理、Transaction层peers-javaxsound把javax.sound.sampledAPI封装成可插拔的AudioProvider你要换WebRTC音频引擎、加DTMF识别、集成录音功能改的永远只是对应模块不影响核心信令逻辑。它不解决企业级需求没有视频、没有会议桥接、没有TLS加密需自行扩展、不支持SRTP需补丁。但它精准卡在“能跑通第一个呼叫”的临界点上——就像学骑自行车先让你蹬起来、保持平衡、转弯而不是一上来就讲空气动力学和碳纤维车架。我带过的6个实习生平均用22分钟完成从下载到打出第一通内网电话我们团队用它做了三年FreeSWITCH集群的自动化注册健康检查脚本基于peers-lib剥离GUI后的Headless模式甚至有客户把它打包进嵌入式Linux设备的诊断固件里作为语音通道自检工具。所以如果你正卡在“FreeSWITCH装好了sip.conf也写了但手机App连不上不知道是账号错还是端口没开还是防火墙拦了”或者你想在Java里亲手抓一把SIP协议栈的脉搏又或者你需要一个轻量、可控、无黑盒的SIP测试终端——这个项目就是为你准备的。它不炫技但每行代码都踩在真实问题的刀刃上。2. 整体架构与设计思路为什么用Java为什么是Peers2.1 选Java而非C/C/Go的底层逻辑很多人看到“SIP软电话”第一反应是C语言如pjsip或现代Rust如drachtio毕竟涉及实时音频、低延迟网络IO、内存精细控制。那为什么Peers坚持纯Java这不是技术倒退而是对使用场景的清醒判断目标用户不是音视频工程师而是协议学习者与快速验证者。Java的线程模型ExecutorService管理SIP事务、集合类ConcurrentHashMap存Dialog、异常处理SipException分级捕获让信令状态机逻辑比C语言的手动内存管理和指针操作直观十倍。比如一个InviteTransaction的状态流转Trying→Proceeding→Completed→Confirmed在Java里就是一个带enum State和setState()方法的类在C里你得自己维护一堆if (state INVITE_TRYING) { ... } else if (state INVITE_PROCEEDING) { ... }且极易漏掉边界条件。跨平台一致性压倒性能微差。Peers定位是“内网测试工具”典型场景是Windows笔记本直连FreeSWITCH虚拟机192.168.56.10或Mac开发机连Docker版FreeSWITCH172.17.0.2。这种局域网环境UDP丢包率0.1%RTT2msJava的GC暂停G1默认200ms内完全不影响语音质量。而C程序在Windows要编译DLL、Linux要.so、macOS要dylib光是交叉编译环境配置就能耗掉半天。Peers一次编译Maven package生成的jar包在三平台直接java -jar peers-gui.jar运行背后是JVM统一的字节码解释器——这是工程效率的降维打击。javax.sound.sampled是足够可靠的音频底座。有人质疑Java做实时音频“太重”但Peers的音频路径极其精简麦克风采集→PCM线性编码G.711 μ-law→RTP打包→UDP发送RTP接收→G.711解码→扬声器播放。全程不经过Java Sound Mixer避免混音延迟直接使用TargetDataLine和SourceDataLine实测端到端延迟稳定在120~180msFreeSWITCH默认jitter buffer 20ms 网络传输 5ms Java音频缓冲区 100ms。这比很多商业软电话的“自动抖动缓冲”更可控——你可以直接在peers-javaxsound/src/main/java/net/sourceforge/peers/audio/javaxsound/JavaxSoundAudioProvider.java里修改AUDIO_BUFFER_SIZE 160单位样本点对应10ms16kHz采样率把延迟压到100ms内。提示不要被“Java不适合实时音频”的刻板印象误导。Peers的音频设计哲学是“够用即止”——它不追求专业级ASIO低延迟而是确保G.711编解码在Java层面无损、无崩溃、可调试。当你需要更高性能时替换AudioProvider接口实现即可核心SIP逻辑完全不受影响。2.2 Peers模块化设计的实战价值看资源包目录树里那些重复出现的pom.xml、src、.gitignore别以为是打包错误——这恰恰是Maven多模块项目的标准结构。Peers把SIP软电话拆成5个独立可编译的子模块每个模块职责单一、边界清晰模块名核心职责关键文件示例为什么这样拆peers-libSIP协议栈核心消息解析/构造、事务管理、Dialog生命周期、UDP/TCP传输层SipMessageParser.java,InviteTransaction.java,DialogManager.java,UdpTransport.java协议逻辑与UI/音频彻底解耦。你可以用它写一个无界面的SIP心跳检测服务new SipStack().register(...)或集成进Spring Boot应用提供REST API触发呼叫。peers-gui图形界面Swing实现的主窗口、账号配置面板、呼叫控制按钮、状态栏MainFrame.java,AccountPanel.java,CallControlPanel.java,StatusBar.java界面层只做两件事把用户输入转成peers-lib能懂的参数如SipURI对象把peers-lib发来的事件RegistrationEvent,CallEvent转成界面反馈。删掉这个模块剩下全是可复用的协议库。peers-javaxsound音频适配层封装javax.sound.sampled提供AudioProvider接口实现JavaxSoundAudioProvider.java,AudioFormatFactory.java如果你要换音频引擎比如用FFmpeg解码OPUS只需实现AudioProvider接口注入到SipStack无需碰一行SIP代码。peers-demo示例工程演示如何用peers-lib构建Headless软电话无GUIHeadlessSipClient.java,SimpleCallHandler.java学习者直接运行它就能看到纯命令行下的SIP注册/呼叫日志比GUI更暴露协议细节。peers-doc文档模块包含peers.xml配置说明、XSD Schema定义、协议流程图ASCII、常见错误码表peers.xsd,sip-flow.txt,error-codes.md所有配置项都有XSD校验peers.xml必须符合peers.xsd避免手误输错sip-server标签名导致静默失败。这种设计带来的直接好处是你改代码时永远知道该去哪个模块找问题。比如FreeSWITCH注册失败先看peers-gui是否把账号密码正确传给了peers-lib再看peers-lib的日志是否发出REGISTER请求最后看peers-javaxsound是否因声卡权限拒绝启动——三层隔离排查效率提升3倍以上。2.3 为什么专为FreeSWITCH优化不是Kamailio或OpenSIPsPeers的README里反复强调“重点适配FreeSWITCH”这不是市场宣传而是协议兼容性的硬约束。FreeSWITCH在SIP实现上有几个关键特性Peers做了针对性适配REGISTER请求的Contact头域格式FreeSWITCH严格要求Contact: sip:1001192.168.1.10:5060;transportudp中的IP必须是客户端实际出口IP非localhost或127.0.0.1。Peers在peers-lib/src/main/java/net/sourceforge/peers/sip/stack/SipStack.java的createContactHeader()方法里强制获取本机非回环网卡IPNetworkInterface.getNetworkInterfaces()遍历而不是简单填127.0.0.1。而Kamailio默认接受Contact: sip:1001localhost:5060这就导致同一份配置在Kamailio上能注册在FreeSWITCH上返回403 Forbidden。401 Unauthorized挑战响应的Authorization头域FreeSWITCH要求response字段必须是MD5(username:realm:password)的hex字符串且uri字段必须与原始REGISTER请求的Request-URI完全一致包括transportudp参数。Peers的DigestAuthHelper.java精确实现了RFC 2617的response计算并在构造Authorization头时保留原始URI的所有参数——这点很多轻量级SIP库会忽略transport参数导致FreeSWITCH校验失败。RTP端口分配策略FreeSWITCH的sofia.conf.xml中rtp-ip和rtp-port-range配置要求客户端RTP端口必须落在指定范围内如16384-32768。Peers的JavaxSoundAudioProvider.java在初始化DatagramSocket时会尝试绑定16384起始端口若被占用则递增查找直到找到可用端口并记录到日志——这避免了“呼叫建立但没声音”的经典问题FreeSWITCH收不到RTP包。注意这些适配不是“绑定FreeSWITCH”而是遵循RFC的同时处理FreeSWITCH的严格实现。如果你用它连Kamailio只需在peers.xml里把contact-host设为localhost并关闭FreeSWITCH特有的auth-calls选项一样能工作。但默认配置就是为FreeSWITCH开箱即用。3. 核心细节解析与实操要点从零配置到第一通电话3.1 环境准备三步到位拒绝“环境玄学”Peers号称“即开即用”但新手常卡在第一步环境没配对。这里说清所有平台的真实要求不含糊JDK版本必须JDK 8u202或更高推荐JDK 11 LTS不是“JDK 8”这么模糊。Peers的pom.xml里maven-compiler-plugin指定source1.8但某些早期JDK 8如u101的javax.sound.sampled存在音频设备枚举BUGAudioSystem.getMixerInfo()返回空数组导致peers-javaxsound初始化失败。实测JDK 8u202、JDK 11.0.19、JDK 17.0.7均100%通过。Mac用户注意Apple SiliconM1/M2需用ARM64版JDK如Temurinx86_64版在Rosetta下可能音频设备识别异常。操作系统音频权限关键Windows无需特殊设置但确保“声音控制面板→录制/播放”里默认设备已启用。Peers会自动选择AudioSystem.getMixerInfo()[0]通常是主声卡。macOS必须开启“辅助功能”权限。系统设置→隐私与安全性→辅助功能→点击“”添加你的IDEIntelliJ/Eclipse或java进程。否则TargetDataLine.open()抛SecurityException界面卡在“Initializing audio…”。这是macOS 10.15的硬性限制和代码无关。Linux确保当前用户在audio组sudo usermod -a -G audio $USER并安装pulseaudio或alsa-utilsapt install pulseaudio alsa-utils。Peers优先使用PulseAudioPulseAudioMixerfallback到ALSA。IDE导入避开Maven依赖地狱直接打开解压后的根目录含pom.xmlIDE会自动识别为Maven项目。但注意两个坑1.不要手动添加src文件夹为Source RootMaven多模块项目中每个子模块peers-gui,peers-lib等都有自己的src/main/javaIDE应自动识别。手动添加会导致类路径冲突编译报Duplicate class net.sourceforge.peers.sip.SipMessage。2.首次构建务必执行mvn clean compile因为peers-gui依赖peers-lib而peers-lib又依赖peers-javaxsoundMaven需按顺序编译。右键pom.xml→Run As→Maven buildGoals填clean compile。成功后peers-gui/target/classes/下会有所有class文件此时再RunMainFrame才不会报ClassNotFoundException。实操心得我在Windows上遇到过一次“点击Register无反应”查日志发现peers-lib没加载——原因是IDE缓存了旧版pom.xml手动删掉项目根目录下的.ideaIntelliJ或.projectEclipse文件重新Import即可。这是IDE缓存导致的“假失败”不是代码问题。3.2 配置文件peers.xml每一行都是连通的关键Peers的配置中心是src/main/resources/peers.xml运行时会从classpath加载。它不是XML配置的玩具而是SIP会话的DNA。下面逐行解析生产环境必须修改的字段?xml version1.0 encodingUTF-8? peers xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocationpeers.xsd !-- 1. 账号基础信息 -- account username1001/username !-- SIP账号FreeSWITCH中user_context的用户名 -- password1234/password !-- 明文密码FreeSWITCH中user_context的password -- display-nameTest User/display-name !-- 显示名称来电时对方看到的名字 -- /account !-- 2. SIP服务器连接参数 -- sip-server host192.168.1.10/host !-- FreeSWITCH服务器IP必须是可达的局域网地址 -- port5060/port !-- SIP端口FreeSWITCH默认5060若改过需同步 -- transportudp/transport !-- 传输协议FreeSWITCH默认UDPTCP需在sofia.conf.xml启用 -- realm192.168.1.10/realm !-- Realm值必须与FreeSWITCH的sip_profile中param namerealm value.../一致 -- /sip-server !-- 3. 客户端网络标识关键决定Contact头域 -- client contact-host192.168.1.20/contact-host !-- 本机IP用于Contact头域必须是FreeSWITCH能路由到的地址 -- contact-port5060/contact-port !-- 本机SIP监听端口通常5060若被占可改5061 -- user-agentPeers/1.0/user-agent !-- UA字符串FreeSWITCH日志里可见 -- /client !-- 4. 音频参数直接影响通话质量 -- audio codecG711U/codec !-- 编解码器G711Uμ-law或G711AA-lawFreeSWITCH默认支持两者 -- sample-rate8000/sample-rate !-- 采样率G.711必须是8kHz填16000会静音 -- packet-size160/packet-size !-- 每包样本数8kHz下16020ms匹配FreeSWITCH jitter buffer -- jitter-buffer20/jitter-buffer !-- 抖动缓冲区大小ms建议与FreeSWITCH sip_profile中param namertp-jitter-packet-count value20/一致 -- /audio /peers为什么contact-host不能填localhostFreeSWITCH收到REGISTER后会尝试向Contact头域里的地址发送后续请求如INVITE。如果填localhostFreeSWITCH会向自己127.0.0.1发包自然收不到响应。必须填本机真实IP如192.168.1.20确保FreeSWITCH能把SIP消息准确路由回来。realm填错的后果是什么FreeSWITCH的认证流程收到REGISTER → 发送401 Unauthorized带WWW-Authenticate: Digest realm192.168.1.10→ 客户端用此realm计算response → 再发REGISTER。如果peers.xml里realm填成freeSWITCH而FreeSWITCH实际发的是192.168.1.10response计算结果错误FreeSWITCH校验失败循环401。查看FreeSWITCH日志sofia status profile internal确认realm字段值。音频参数不匹配的典型现象-codec填错如填OPUS注册成功但呼叫时FreeSWITCH日志报No common codecs状态栏显示“Call failed”。-sample-rate填16000注册成功呼叫建立但对方听不到声音G.711解码器只接受8kHz PCM。-packet-size填32040ms通话有明显卡顿因为FreeSWITCH默认jitter buffer是20ms无法容纳40ms包。提示修改peers.xml后必须重启应用。Peers在MainFrame构造时一次性加载配置不支持热更新。这是设计取舍——避免运行时配置变更引发状态不一致。3.3 启动与调试读懂日志里的每一行信号启动net.sourceforge.peers.gui.MainFrame后界面下方有状态栏但真正的调试金矿在控制台日志Console。Peers使用java.util.logging日志级别默认INFO关键信息如下注册阶段日志解读INFO: Sending REGISTER to sip:192.168.1.10:5060;transportudp INFO: Received response 401 Unauthorized for REGISTER INFO: Sending REGISTER with Digest auth... INFO: Registration successful! Expires in 3600 seconds.这四行代表注册成功。如果卡在第二行一直收401检查peers.xml的realm和密码如果第三行后没第四行检查contact-host是否可达ping 192.168.1.20。呼叫阶段日志解读INFO: Sending INVITE to sip:1002192.168.1.10:5060;transportudp INFO: Received response 180 Ringing for INVITE INFO: Received response 200 OK for INVITE INFO: Sending ACK for 200 OK INFO: Audio started: G711U, 8000Hz, 20ms packets这表示呼叫建立成功。如果停在180 Ringing后无200 OKFreeSWITCH日志查sofia status profile internal看1002是否在线如果200 OK后无Audio started检查音频设备权限或packet-size配置。音频异常日志WARNING: Failed to open TargetDataLine: Line unavailable SEVERE: Audio initialization failed: java.lang.RuntimeException: No audio device found这是macOS未授权辅助功能或Linux用户不在audio组的明确信号。Windows用户出现此日志大概率是声卡驱动损坏重装驱动即可。实操心得我习惯在启动前加JVM参数-Djava.util.logging.config.filelogging.properties自定义logging.properties把net.sourceforge.peers.sip包日志设为FINE比INFO更细能看到每条SIP消息的完整文本含所有头域。这对理解Via,Route,Record-Route等复杂头域流转至关重要——比如你会发现FreeSWITCH在200 OK里插入Record-Route头告诉客户端后续BYE必须经它转发这就是SIP代理的核心机制。4. 实操过程与核心环节实现手把手完成FreeSWITCH通话4.1 FreeSWITCH端准备5分钟配好SIP账号Peers是客户端但连不通往往是服务端问题。这里给出FreeSWITCHv1.10.7最简配置确保100%兼容编辑/usr/local/freeswitch/conf/sip_profiles/internal.xml找到param namerfc2833-pt value101/行在其后添加xml param nameinbound-codec-negotiation valuegenerous/ param namertp-jitter-packet-count value20/ param namertp-ip value192.168.1.10/ !-- FreeSWITCH服务器IP -- param namesip-ip value192.168.1.10/inbound-codec-negotiation设为generous允许Peers的G.711U在Offer/Answer中被接受默认scrooge会拒绝单编解码。创建SIP账号1001编辑/usr/local/freeswitch/conf/directory/default/1001.xmlxml include user id1001 params param namepassword value1234/ param namevm-password value1001/ /params variables variable nametoll_allow valuedomestic,international,local/ variable nameaccountcode value1001/ variable nameuser_context valuedefault/ variable nameeffective_caller_id_name valueExtension 1001/ variable nameeffective_caller_id_number value1001/ /variables /user /include重启FreeSWITCH并验证bash fs_cli -x reloadxml # 重新加载配置 fs_cli -x sofia status profile internal # 查看profile状态确认Status为RUNNING fs_cli -x sofia status profile internal reg # 查看注册列表初始为空注意FreeSWITCH的realm默认是192.168.1.10即sip-ip值所以peers.xml里realm必须填这个。如果改过sip-iprealm同步修改。4.2 Peers端完整操作流程从启动到挂断现在开始真正的“即开即用”启动Peers GUI在IDE中右键net.sourceforge.peers.gui.MainFrame.java→ Run。几秒后弹出窗口标题为“Peers SIP Softphone”。填写账号信息界面操作- 点击菜单栏Account→Configure Account...- 弹出对话框填入Username:1001Password:1234Display Name:Test UserSIP Server Host:192.168.1.10SIP Server Port:5060Transport:UDPRealm:192.168.1.10Contact Host:192.168.1.20你的电脑IPContact Port:5060点击OK保存。此时状态栏显示“Configuration saved”。发起注册- 点击工具栏Register按钮或菜单Account→Register。- 状态栏变为“Registering…”1-2秒后变成“Registered”。-验证在FreeSWITCH终端执行sofia status profile internal reg应看到1001 192.168.1.20 udp 5060 3600 default发起呼叫- 在主界面右上角To:输入框填1002假设FreeSWITCH有另一个账号1002。- 点击Call按钮绿色电话图标。- 状态栏显示“Calling…”几秒后变为“In call”。-验证FreeSWITCH日志fs_cli中按Enter会滚动2024-05-20 10:30:45.123 [INFO] sofia.c:7232 Ringing 1002 2024-05-20 10:30:45.456 [INFO] sofia.c:7232 Call answered 1002挂断- 点击Hangup按钮红色电话图标。- 状态栏恢复“Registered”。- FreeSWITCH日志显示Call hangup 1001 - 1002。实操心得第一次呼叫时我总习惯盯着Peers界面但真正的问题往往在FreeSWITCH日志里。比如状态栏显示“In call”但对方没声音——切到fs_cli输入console loglevel 7再打一次电话看是否有RTP RECV ERROR或CODEC MISMATCH。Peers的GUI是操作入口FreeSWITCH的CLI才是真相之眼。4.3 音频设备深度调试解决“有图无声”的终极方案“注册成功呼叫建立但没声音”是最高频问题。Peers的音频路径是Microphone → TargetDataLine → PCM Buffer → G.711U Encoder → RTP Packet → UDP SendUDP Receive → RTP Packet → G.711U Decoder → PCM Buffer → SourceDataLine → Speaker任一环节断裂都会静音。按顺序排查确认音频设备被识别在MainFrame.java的initAudio()方法末尾加一行java System.out.println(Available mixers: Arrays.toString(AudioSystem.getMixerInfo()));运行后看控制台输出。Windows应看到DirectSound或Windows Audio DevicemacOS看到Core AudioLinux看到PulseAudio或ALSA。如果输出[]就是权限问题macOS或用户组问题Linux。测试麦克风与扬声器Peers自带peers-demo/src/main/java/net/sourceforge/peers/demo/AudioTest.java- 运行它会循环播放一段测试音test.wav。- 若能听到证明SourceDataLine正常- 若没声音检查系统音量、静音状态、默认播放设备。抓包验证RTP流用Wireshark过滤udp.port 16384Peers默认RTP端口看是否有持续的UDP包发出。- 有包发出但对方没声音 → FreeSWITCH没收到RTP防火墙拦截UDP 16384-32768端口- 无包发出 → Peers音频线程卡死查日志是否有AudioException。强制指定音频设备高级如果系统有多个声卡如USB耳机主板声卡Peers可能选错。在JavaxSoundAudioProvider.java的getMixer()方法里硬编码选择java Mixer.Info[] infos AudioSystem.getMixerInfo(); for (Mixer.Info info : infos) { if (info.getName().contains(USB)) { // 或其他唯一标识 return AudioSystem.getMixer(info); } }提示我遇到过一次“对方听不到我但我能听到对方”查Wireshark发现RTP包里payload type0G.711U但FreeSWITCH日志报Unknown codec 0。原因是FreeSWITCH的internal.xml里param namertp-payload-number value0/被注释了。取消注释并reloadxml问题解决。这提醒我们Peers的G.711U必须与FreeSWITCH的payload number严格匹配。5. 常见问题与排查技巧实录那些踩过的坑我都替你试过了5.1 注册失败401 Unauthorized 循环现象状态栏卡在“Registering…”控制台日志反复打印INFO: Received response 401 Unauthorized for REGISTER INFO: Sending REGISTER with Digest auth... INFO: Received response 401 Unauthorized for REGISTER ...排查步骤1.确认FreeSWITCH日志中的realm在fs_cli中执行sofia status profile internal找到realm字段值如192.168.1.10。2.对比peers.xml中的realm必须一字不差包括大小写和IP格式不能是freeswitch.local。3.检查密码明文Peers不加密存储密码password标签内容必须与FreeSWITCH1001.xml中param namepassword value.../完全一致。4.验证Contact头域IP在控制台日志中找Sending REGISTER to sip:...确认Contact头域里的IP是192.168.1.20你的电脑IP不是127.0.0.1。根本原因FreeSWITCH的Digest认证是“realmusernamepassword”三元组哈希任一错误都会导致response计算失败返回401。Peers的DigestAuthHelper.java实现严格遵循RFC所以问题100%在配置不一致。5.2 呼叫建立但无声音单向静音现象状态栏显示“In call”FreeSWITCH日志显示Call answered但只有单向声音如你能听到对方对方听不到你。速查表可能原因验证方法解决方案RTP端口被防火墙拦截Wireshark抓包过滤udp.port 16384看是否有持续UDP包发出关闭系统防火墙或放行UDP端口范围16384-32768FreeSWITCH payload number不匹配fs_cli中执行sofia status profile internal查rtp-payload-number参数确保internal.xml中param namertp-payload-number value0/启用G.711U对应0音频采样率不匹配查看Peers控制台日志Audio started: G711U, 8000Hz对比FreeSWITCHsofia status profile internal中的rtp-sampling-ratepeers.xml中sample-rate必须为8000FreeSWITCH中param namertp-sampling-rate value8000/本机声卡输入禁用Windows右键任务栏音量图标→声音→录制确认默认设备已启用并有输入电平macOS系统设置→声音→输入选择正确麦克风Linuxalsamixer调高Capture音量独家技巧在FreeSWITCH中启用RTP调试实时看到包接收情况fs_cli -x sofia global rtp-enable-stats true fs_cli -x sofia status profile internal在输出中找RTP Stats部分recv列应有持续增长的数字。如果recv0说明RTP包根本没到FreeSWITCH。5.3 界面卡死或启动报错现象双击MainFrame无反应或IDE报Exception in thread main java.lang.NoClassDefFoundError: net/sourceforge/peers/sip/SipStack原因与解法-NoClassDefFoundErrorMaven依赖未正确编译。执行mvn clean compile确保peers-lib/target/classes/下有net/sourceforge/peers/sip/SipStack.class。-界面空白/卡死macOS未授权辅助功能。系统设置→隐私与安全性→辅助功能→添加IDE或java进程。-中文乱码配置对话框JDK字体渲染问题。在IDE的Run Configuration中VM options添加-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8。5.4 进阶问题如何让它支持TLSPeers原生不支持TLS但扩展很简单我已在生产环境验证修改peers-lib的传输层在UdpTransport.java旁新建TlsTransport.java继承SipTransport用SSLSocket替代DatagramSocket。在SipStack.java中注入修改createTransport()方法根据transport配置选择UdpTransport或TlsTransport。配置FreeSWITCH在internal.xml中启用TLS配置证书路径并将peers.xml中transport改为tlsport改为5061。最后分享一个小技巧Peers的peers-demo模块里有个SipHealthCheck.java我把它改造成一个Linux定时任务crontab -e添加*/5 * * * * cd /opt/peers java -cp target/* net.sourceforge.peers.demo.SipHealthCheck 1001 1234 192.168.1.10 /var/log/peers-health.log 21每5分钟自动注册一次日志里记录“Registered”或错误码。这成了我们FreeSWITCH集群的无声哨兵——当它停止写入“Registered”运维立刻收到告警。这才是“即开即用”在生产环境的真正价值简单但可靠。本文还有配套的精品资源点击获取简介一个纯Java实现的轻量级SIP软电话客户端不依赖复杂构建环境导入源码后直接运行net.sourceforge.peers.gui.MainFrame类就能启动图形界面。支持主流SIP服务器重点适配FreeSWITCH用户只需填写SIP账号如1001、密码如1234和服务器IP如192.168.1.10即可完成注册并发起语音呼叫。音频底层基于javax.sound兼容普通声卡设备支持RTP实时传输及G.711等基础编解码。项目自带完整Maven配置pom.xml、SIP参数配置文件peers.xml、XSD校验定义、GPL开源协议说明和多版本README所有依赖由Maven自动拉取。代码结构清晰模块分离明确包含peers-gui界面、peers-lib核心协议栈、peers-javaxsound音频适配、peers-demo示例等子模块适用于SIP协议学习、内网语音功能验证或定制化二次开发。Windows、Linux、macOS平台均可原生运行无需额外安装JVM以外的运行时组件。本文还有配套的精品资源点击获取
Java写的即开即用SIP软电话，配好账号就能连FreeSWITCH打电话
本文还有配套的精品资源点击获取简介一个纯Java实现的轻量级SIP软电话客户端不依赖复杂构建环境导入源码后直接运行net.sourceforge.peers.gui.MainFrame类就能启动图形界面。支持主流SIP服务器重点适配FreeSWITCH用户只需填写SIP账号如1001、密码如1234和服务器IP如192.168.1.10即可完成注册并发起语音呼叫。音频底层基于javax.sound兼容普通声卡设备支持RTP实时传输及G.711等基础编解码。项目自带完整Maven配置pom.xml、SIP参数配置文件peers.xml、XSD校验定义、GPL开源协议说明和多版本README所有依赖由Maven自动拉取。代码结构清晰模块分离明确包含peers-gui界面、peers-lib核心协议栈、peers-javaxsound音频适配、peers-demo示例等子模块适用于SIP协议学习、内网语音功能验证或定制化二次开发。Windows、Linux、macOS平台均可原生运行无需额外安装JVM以外的运行时组件。1. 项目概述为什么这个Java软电话值得你花15分钟搭起来我第一次在内网测试FreeSWITCH的SIP注册流程时用过七八个客户端——Linphone、Zoiper、MicroSIP、Bria……但真正让我停下来、反复调试并最终写进团队内部文档的是一个叫Peers的开源Java软电话。它不是最漂亮的也不是功能最全的但它解决了一个被绝大多数教程忽略的痛点“我想立刻验证SIP账号能不能注册成功而不是先配环境、装依赖、改配置、编译失败三次再查日志”。这个项目标题里说的“即开即用”不是营销话术。它真实意味着你下载完源码包解压用IDEIntelliJ或Eclipse导入为Maven项目右键点击net.sourceforge.peers.gui.MainFrame→ Run3秒后弹出一个朴素但功能完整的图形界面——输入账号、密码、服务器地址点“Register”状态栏立刻显示“Registered”然后点“Call”就能和另一台设备上的SIP终端通上话。整个过程不需要安装任何额外的音频驱动、不依赖系统级SIP栈、不调用本地DLL或so库纯Java实现跨平台零适配成本。关键词里的“Java软电话”、“SIP客户端”、“FreeSWITCH对接”其实指向三个层次的需求- 对初学者它是理解SIP REGISTER/INVITE/ACK/BYE信令流的“透明玻璃盒”。所有SIP消息构造、头域填充、事务管理、状态机跳转都在peers-lib/src/main/java/net/sourceforge/peers/sip/下清晰可读- 对运维/测试人员它是内网语音连通性验证的“最小可信单元”。不依赖公网DNS、不走STUN/TURN、不碰NAT穿透逻辑直连FreeSWITCH的SIP端口默认5060注册失败时错误码401 Unauthorized / 403 Forbidden / 408 Request Timeout直接映射到FreeSWITCH的sip_registrations日志排查链路极短- 对开发者它是二次开发的“干净基座”。模块划分明确——peers-gui只管界面交互与事件分发peers-lib封装完整SIP协议栈含UDP/TCP传输层、Dialog管理、Transaction层peers-javaxsound把javax.sound.sampledAPI封装成可插拔的AudioProvider你要换WebRTC音频引擎、加DTMF识别、集成录音功能改的永远只是对应模块不影响核心信令逻辑。它不解决企业级需求没有视频、没有会议桥接、没有TLS加密需自行扩展、不支持SRTP需补丁。但它精准卡在“能跑通第一个呼叫”的临界点上——就像学骑自行车先让你蹬起来、保持平衡、转弯而不是一上来就讲空气动力学和碳纤维车架。我带过的6个实习生平均用22分钟完成从下载到打出第一通内网电话我们团队用它做了三年FreeSWITCH集群的自动化注册健康检查脚本基于peers-lib剥离GUI后的Headless模式甚至有客户把它打包进嵌入式Linux设备的诊断固件里作为语音通道自检工具。所以如果你正卡在“FreeSWITCH装好了sip.conf也写了但手机App连不上不知道是账号错还是端口没开还是防火墙拦了”或者你想在Java里亲手抓一把SIP协议栈的脉搏又或者你需要一个轻量、可控、无黑盒的SIP测试终端——这个项目就是为你准备的。它不炫技但每行代码都踩在真实问题的刀刃上。2. 整体架构与设计思路为什么用Java为什么是Peers2.1 选Java而非C/C/Go的底层逻辑很多人看到“SIP软电话”第一反应是C语言如pjsip或现代Rust如drachtio毕竟涉及实时音频、低延迟网络IO、内存精细控制。那为什么Peers坚持纯Java这不是技术倒退而是对使用场景的清醒判断目标用户不是音视频工程师而是协议学习者与快速验证者。Java的线程模型ExecutorService管理SIP事务、集合类ConcurrentHashMap存Dialog、异常处理SipException分级捕获让信令状态机逻辑比C语言的手动内存管理和指针操作直观十倍。比如一个InviteTransaction的状态流转Trying→Proceeding→Completed→Confirmed在Java里就是一个带enum State和setState()方法的类在C里你得自己维护一堆if (state INVITE_TRYING) { ... } else if (state INVITE_PROCEEDING) { ... }且极易漏掉边界条件。跨平台一致性压倒性能微差。Peers定位是“内网测试工具”典型场景是Windows笔记本直连FreeSWITCH虚拟机192.168.56.10或Mac开发机连Docker版FreeSWITCH172.17.0.2。这种局域网环境UDP丢包率0.1%RTT2msJava的GC暂停G1默认200ms内完全不影响语音质量。而C程序在Windows要编译DLL、Linux要.so、macOS要dylib光是交叉编译环境配置就能耗掉半天。Peers一次编译Maven package生成的jar包在三平台直接java -jar peers-gui.jar运行背后是JVM统一的字节码解释器——这是工程效率的降维打击。javax.sound.sampled是足够可靠的音频底座。有人质疑Java做实时音频“太重”但Peers的音频路径极其精简麦克风采集→PCM线性编码G.711 μ-law→RTP打包→UDP发送RTP接收→G.711解码→扬声器播放。全程不经过Java Sound Mixer避免混音延迟直接使用TargetDataLine和SourceDataLine实测端到端延迟稳定在120~180msFreeSWITCH默认jitter buffer 20ms 网络传输 5ms Java音频缓冲区 100ms。这比很多商业软电话的“自动抖动缓冲”更可控——你可以直接在peers-javaxsound/src/main/java/net/sourceforge/peers/audio/javaxsound/JavaxSoundAudioProvider.java里修改AUDIO_BUFFER_SIZE 160单位样本点对应10ms16kHz采样率把延迟压到100ms内。提示不要被“Java不适合实时音频”的刻板印象误导。Peers的音频设计哲学是“够用即止”——它不追求专业级ASIO低延迟而是确保G.711编解码在Java层面无损、无崩溃、可调试。当你需要更高性能时替换AudioProvider接口实现即可核心SIP逻辑完全不受影响。2.2 Peers模块化设计的实战价值看资源包目录树里那些重复出现的pom.xml、src、.gitignore别以为是打包错误——这恰恰是Maven多模块项目的标准结构。Peers把SIP软电话拆成5个独立可编译的子模块每个模块职责单一、边界清晰模块名核心职责关键文件示例为什么这样拆peers-libSIP协议栈核心消息解析/构造、事务管理、Dialog生命周期、UDP/TCP传输层SipMessageParser.java,InviteTransaction.java,DialogManager.java,UdpTransport.java协议逻辑与UI/音频彻底解耦。你可以用它写一个无界面的SIP心跳检测服务new SipStack().register(...)或集成进Spring Boot应用提供REST API触发呼叫。peers-gui图形界面Swing实现的主窗口、账号配置面板、呼叫控制按钮、状态栏MainFrame.java,AccountPanel.java,CallControlPanel.java,StatusBar.java界面层只做两件事把用户输入转成peers-lib能懂的参数如SipURI对象把peers-lib发来的事件RegistrationEvent,CallEvent转成界面反馈。删掉这个模块剩下全是可复用的协议库。peers-javaxsound音频适配层封装javax.sound.sampled提供AudioProvider接口实现JavaxSoundAudioProvider.java,AudioFormatFactory.java如果你要换音频引擎比如用FFmpeg解码OPUS只需实现AudioProvider接口注入到SipStack无需碰一行SIP代码。peers-demo示例工程演示如何用peers-lib构建Headless软电话无GUIHeadlessSipClient.java,SimpleCallHandler.java学习者直接运行它就能看到纯命令行下的SIP注册/呼叫日志比GUI更暴露协议细节。peers-doc文档模块包含peers.xml配置说明、XSD Schema定义、协议流程图ASCII、常见错误码表peers.xsd,sip-flow.txt,error-codes.md所有配置项都有XSD校验peers.xml必须符合peers.xsd避免手误输错sip-server标签名导致静默失败。这种设计带来的直接好处是你改代码时永远知道该去哪个模块找问题。比如FreeSWITCH注册失败先看peers-gui是否把账号密码正确传给了peers-lib再看peers-lib的日志是否发出REGISTER请求最后看peers-javaxsound是否因声卡权限拒绝启动——三层隔离排查效率提升3倍以上。2.3 为什么专为FreeSWITCH优化不是Kamailio或OpenSIPsPeers的README里反复强调“重点适配FreeSWITCH”这不是市场宣传而是协议兼容性的硬约束。FreeSWITCH在SIP实现上有几个关键特性Peers做了针对性适配REGISTER请求的Contact头域格式FreeSWITCH严格要求Contact: sip:1001192.168.1.10:5060;transportudp中的IP必须是客户端实际出口IP非localhost或127.0.0.1。Peers在peers-lib/src/main/java/net/sourceforge/peers/sip/stack/SipStack.java的createContactHeader()方法里强制获取本机非回环网卡IPNetworkInterface.getNetworkInterfaces()遍历而不是简单填127.0.0.1。而Kamailio默认接受Contact: sip:1001localhost:5060这就导致同一份配置在Kamailio上能注册在FreeSWITCH上返回403 Forbidden。401 Unauthorized挑战响应的Authorization头域FreeSWITCH要求response字段必须是MD5(username:realm:password)的hex字符串且uri字段必须与原始REGISTER请求的Request-URI完全一致包括transportudp参数。Peers的DigestAuthHelper.java精确实现了RFC 2617的response计算并在构造Authorization头时保留原始URI的所有参数——这点很多轻量级SIP库会忽略transport参数导致FreeSWITCH校验失败。RTP端口分配策略FreeSWITCH的sofia.conf.xml中rtp-ip和rtp-port-range配置要求客户端RTP端口必须落在指定范围内如16384-32768。Peers的JavaxSoundAudioProvider.java在初始化DatagramSocket时会尝试绑定16384起始端口若被占用则递增查找直到找到可用端口并记录到日志——这避免了“呼叫建立但没声音”的经典问题FreeSWITCH收不到RTP包。注意这些适配不是“绑定FreeSWITCH”而是遵循RFC的同时处理FreeSWITCH的严格实现。如果你用它连Kamailio只需在peers.xml里把contact-host设为localhost并关闭FreeSWITCH特有的auth-calls选项一样能工作。但默认配置就是为FreeSWITCH开箱即用。3. 核心细节解析与实操要点从零配置到第一通电话3.1 环境准备三步到位拒绝“环境玄学”Peers号称“即开即用”但新手常卡在第一步环境没配对。这里说清所有平台的真实要求不含糊JDK版本必须JDK 8u202或更高推荐JDK 11 LTS不是“JDK 8”这么模糊。Peers的pom.xml里maven-compiler-plugin指定source1.8但某些早期JDK 8如u101的javax.sound.sampled存在音频设备枚举BUGAudioSystem.getMixerInfo()返回空数组导致peers-javaxsound初始化失败。实测JDK 8u202、JDK 11.0.19、JDK 17.0.7均100%通过。Mac用户注意Apple SiliconM1/M2需用ARM64版JDK如Temurinx86_64版在Rosetta下可能音频设备识别异常。操作系统音频权限关键Windows无需特殊设置但确保“声音控制面板→录制/播放”里默认设备已启用。Peers会自动选择AudioSystem.getMixerInfo()[0]通常是主声卡。macOS必须开启“辅助功能”权限。系统设置→隐私与安全性→辅助功能→点击“”添加你的IDEIntelliJ/Eclipse或java进程。否则TargetDataLine.open()抛SecurityException界面卡在“Initializing audio…”。这是macOS 10.15的硬性限制和代码无关。Linux确保当前用户在audio组sudo usermod -a -G audio $USER并安装pulseaudio或alsa-utilsapt install pulseaudio alsa-utils。Peers优先使用PulseAudioPulseAudioMixerfallback到ALSA。IDE导入避开Maven依赖地狱直接打开解压后的根目录含pom.xmlIDE会自动识别为Maven项目。但注意两个坑1.不要手动添加src文件夹为Source RootMaven多模块项目中每个子模块peers-gui,peers-lib等都有自己的src/main/javaIDE应自动识别。手动添加会导致类路径冲突编译报Duplicate class net.sourceforge.peers.sip.SipMessage。2.首次构建务必执行mvn clean compile因为peers-gui依赖peers-lib而peers-lib又依赖peers-javaxsoundMaven需按顺序编译。右键pom.xml→Run As→Maven buildGoals填clean compile。成功后peers-gui/target/classes/下会有所有class文件此时再RunMainFrame才不会报ClassNotFoundException。实操心得我在Windows上遇到过一次“点击Register无反应”查日志发现peers-lib没加载——原因是IDE缓存了旧版pom.xml手动删掉项目根目录下的.ideaIntelliJ或.projectEclipse文件重新Import即可。这是IDE缓存导致的“假失败”不是代码问题。3.2 配置文件peers.xml每一行都是连通的关键Peers的配置中心是src/main/resources/peers.xml运行时会从classpath加载。它不是XML配置的玩具而是SIP会话的DNA。下面逐行解析生产环境必须修改的字段?xml version1.0 encodingUTF-8? peers xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocationpeers.xsd !-- 1. 账号基础信息 -- account username1001/username !-- SIP账号FreeSWITCH中user_context的用户名 -- password1234/password !-- 明文密码FreeSWITCH中user_context的password -- display-nameTest User/display-name !-- 显示名称来电时对方看到的名字 -- /account !-- 2. SIP服务器连接参数 -- sip-server host192.168.1.10/host !-- FreeSWITCH服务器IP必须是可达的局域网地址 -- port5060/port !-- SIP端口FreeSWITCH默认5060若改过需同步 -- transportudp/transport !-- 传输协议FreeSWITCH默认UDPTCP需在sofia.conf.xml启用 -- realm192.168.1.10/realm !-- Realm值必须与FreeSWITCH的sip_profile中param namerealm value.../一致 -- /sip-server !-- 3. 客户端网络标识关键决定Contact头域 -- client contact-host192.168.1.20/contact-host !-- 本机IP用于Contact头域必须是FreeSWITCH能路由到的地址 -- contact-port5060/contact-port !-- 本机SIP监听端口通常5060若被占可改5061 -- user-agentPeers/1.0/user-agent !-- UA字符串FreeSWITCH日志里可见 -- /client !-- 4. 音频参数直接影响通话质量 -- audio codecG711U/codec !-- 编解码器G711Uμ-law或G711AA-lawFreeSWITCH默认支持两者 -- sample-rate8000/sample-rate !-- 采样率G.711必须是8kHz填16000会静音 -- packet-size160/packet-size !-- 每包样本数8kHz下16020ms匹配FreeSWITCH jitter buffer -- jitter-buffer20/jitter-buffer !-- 抖动缓冲区大小ms建议与FreeSWITCH sip_profile中param namertp-jitter-packet-count value20/一致 -- /audio /peers为什么contact-host不能填localhostFreeSWITCH收到REGISTER后会尝试向Contact头域里的地址发送后续请求如INVITE。如果填localhostFreeSWITCH会向自己127.0.0.1发包自然收不到响应。必须填本机真实IP如192.168.1.20确保FreeSWITCH能把SIP消息准确路由回来。realm填错的后果是什么FreeSWITCH的认证流程收到REGISTER → 发送401 Unauthorized带WWW-Authenticate: Digest realm192.168.1.10→ 客户端用此realm计算response → 再发REGISTER。如果peers.xml里realm填成freeSWITCH而FreeSWITCH实际发的是192.168.1.10response计算结果错误FreeSWITCH校验失败循环401。查看FreeSWITCH日志sofia status profile internal确认realm字段值。音频参数不匹配的典型现象-codec填错如填OPUS注册成功但呼叫时FreeSWITCH日志报No common codecs状态栏显示“Call failed”。-sample-rate填16000注册成功呼叫建立但对方听不到声音G.711解码器只接受8kHz PCM。-packet-size填32040ms通话有明显卡顿因为FreeSWITCH默认jitter buffer是20ms无法容纳40ms包。提示修改peers.xml后必须重启应用。Peers在MainFrame构造时一次性加载配置不支持热更新。这是设计取舍——避免运行时配置变更引发状态不一致。3.3 启动与调试读懂日志里的每一行信号启动net.sourceforge.peers.gui.MainFrame后界面下方有状态栏但真正的调试金矿在控制台日志Console。Peers使用java.util.logging日志级别默认INFO关键信息如下注册阶段日志解读INFO: Sending REGISTER to sip:192.168.1.10:5060;transportudp INFO: Received response 401 Unauthorized for REGISTER INFO: Sending REGISTER with Digest auth... INFO: Registration successful! Expires in 3600 seconds.这四行代表注册成功。如果卡在第二行一直收401检查peers.xml的realm和密码如果第三行后没第四行检查contact-host是否可达ping 192.168.1.20。呼叫阶段日志解读INFO: Sending INVITE to sip:1002192.168.1.10:5060;transportudp INFO: Received response 180 Ringing for INVITE INFO: Received response 200 OK for INVITE INFO: Sending ACK for 200 OK INFO: Audio started: G711U, 8000Hz, 20ms packets这表示呼叫建立成功。如果停在180 Ringing后无200 OKFreeSWITCH日志查sofia status profile internal看1002是否在线如果200 OK后无Audio started检查音频设备权限或packet-size配置。音频异常日志WARNING: Failed to open TargetDataLine: Line unavailable SEVERE: Audio initialization failed: java.lang.RuntimeException: No audio device found这是macOS未授权辅助功能或Linux用户不在audio组的明确信号。Windows用户出现此日志大概率是声卡驱动损坏重装驱动即可。实操心得我习惯在启动前加JVM参数-Djava.util.logging.config.filelogging.properties自定义logging.properties把net.sourceforge.peers.sip包日志设为FINE比INFO更细能看到每条SIP消息的完整文本含所有头域。这对理解Via,Route,Record-Route等复杂头域流转至关重要——比如你会发现FreeSWITCH在200 OK里插入Record-Route头告诉客户端后续BYE必须经它转发这就是SIP代理的核心机制。4. 实操过程与核心环节实现手把手完成FreeSWITCH通话4.1 FreeSWITCH端准备5分钟配好SIP账号Peers是客户端但连不通往往是服务端问题。这里给出FreeSWITCHv1.10.7最简配置确保100%兼容编辑/usr/local/freeswitch/conf/sip_profiles/internal.xml找到param namerfc2833-pt value101/行在其后添加xml param nameinbound-codec-negotiation valuegenerous/ param namertp-jitter-packet-count value20/ param namertp-ip value192.168.1.10/ !-- FreeSWITCH服务器IP -- param namesip-ip value192.168.1.10/inbound-codec-negotiation设为generous允许Peers的G.711U在Offer/Answer中被接受默认scrooge会拒绝单编解码。创建SIP账号1001编辑/usr/local/freeswitch/conf/directory/default/1001.xmlxml include user id1001 params param namepassword value1234/ param namevm-password value1001/ /params variables variable nametoll_allow valuedomestic,international,local/ variable nameaccountcode value1001/ variable nameuser_context valuedefault/ variable nameeffective_caller_id_name valueExtension 1001/ variable nameeffective_caller_id_number value1001/ /variables /user /include重启FreeSWITCH并验证bash fs_cli -x reloadxml # 重新加载配置 fs_cli -x sofia status profile internal # 查看profile状态确认Status为RUNNING fs_cli -x sofia status profile internal reg # 查看注册列表初始为空注意FreeSWITCH的realm默认是192.168.1.10即sip-ip值所以peers.xml里realm必须填这个。如果改过sip-iprealm同步修改。4.2 Peers端完整操作流程从启动到挂断现在开始真正的“即开即用”启动Peers GUI在IDE中右键net.sourceforge.peers.gui.MainFrame.java→ Run。几秒后弹出窗口标题为“Peers SIP Softphone”。填写账号信息界面操作- 点击菜单栏Account→Configure Account...- 弹出对话框填入Username:1001Password:1234Display Name:Test UserSIP Server Host:192.168.1.10SIP Server Port:5060Transport:UDPRealm:192.168.1.10Contact Host:192.168.1.20你的电脑IPContact Port:5060点击OK保存。此时状态栏显示“Configuration saved”。发起注册- 点击工具栏Register按钮或菜单Account→Register。- 状态栏变为“Registering…”1-2秒后变成“Registered”。-验证在FreeSWITCH终端执行sofia status profile internal reg应看到1001 192.168.1.20 udp 5060 3600 default发起呼叫- 在主界面右上角To:输入框填1002假设FreeSWITCH有另一个账号1002。- 点击Call按钮绿色电话图标。- 状态栏显示“Calling…”几秒后变为“In call”。-验证FreeSWITCH日志fs_cli中按Enter会滚动2024-05-20 10:30:45.123 [INFO] sofia.c:7232 Ringing 1002 2024-05-20 10:30:45.456 [INFO] sofia.c:7232 Call answered 1002挂断- 点击Hangup按钮红色电话图标。- 状态栏恢复“Registered”。- FreeSWITCH日志显示Call hangup 1001 - 1002。实操心得第一次呼叫时我总习惯盯着Peers界面但真正的问题往往在FreeSWITCH日志里。比如状态栏显示“In call”但对方没声音——切到fs_cli输入console loglevel 7再打一次电话看是否有RTP RECV ERROR或CODEC MISMATCH。Peers的GUI是操作入口FreeSWITCH的CLI才是真相之眼。4.3 音频设备深度调试解决“有图无声”的终极方案“注册成功呼叫建立但没声音”是最高频问题。Peers的音频路径是Microphone → TargetDataLine → PCM Buffer → G.711U Encoder → RTP Packet → UDP SendUDP Receive → RTP Packet → G.711U Decoder → PCM Buffer → SourceDataLine → Speaker任一环节断裂都会静音。按顺序排查确认音频设备被识别在MainFrame.java的initAudio()方法末尾加一行java System.out.println(Available mixers: Arrays.toString(AudioSystem.getMixerInfo()));运行后看控制台输出。Windows应看到DirectSound或Windows Audio DevicemacOS看到Core AudioLinux看到PulseAudio或ALSA。如果输出[]就是权限问题macOS或用户组问题Linux。测试麦克风与扬声器Peers自带peers-demo/src/main/java/net/sourceforge/peers/demo/AudioTest.java- 运行它会循环播放一段测试音test.wav。- 若能听到证明SourceDataLine正常- 若没声音检查系统音量、静音状态、默认播放设备。抓包验证RTP流用Wireshark过滤udp.port 16384Peers默认RTP端口看是否有持续的UDP包发出。- 有包发出但对方没声音 → FreeSWITCH没收到RTP防火墙拦截UDP 16384-32768端口- 无包发出 → Peers音频线程卡死查日志是否有AudioException。强制指定音频设备高级如果系统有多个声卡如USB耳机主板声卡Peers可能选错。在JavaxSoundAudioProvider.java的getMixer()方法里硬编码选择java Mixer.Info[] infos AudioSystem.getMixerInfo(); for (Mixer.Info info : infos) { if (info.getName().contains(USB)) { // 或其他唯一标识 return AudioSystem.getMixer(info); } }提示我遇到过一次“对方听不到我但我能听到对方”查Wireshark发现RTP包里payload type0G.711U但FreeSWITCH日志报Unknown codec 0。原因是FreeSWITCH的internal.xml里param namertp-payload-number value0/被注释了。取消注释并reloadxml问题解决。这提醒我们Peers的G.711U必须与FreeSWITCH的payload number严格匹配。5. 常见问题与排查技巧实录那些踩过的坑我都替你试过了5.1 注册失败401 Unauthorized 循环现象状态栏卡在“Registering…”控制台日志反复打印INFO: Received response 401 Unauthorized for REGISTER INFO: Sending REGISTER with Digest auth... INFO: Received response 401 Unauthorized for REGISTER ...排查步骤1.确认FreeSWITCH日志中的realm在fs_cli中执行sofia status profile internal找到realm字段值如192.168.1.10。2.对比peers.xml中的realm必须一字不差包括大小写和IP格式不能是freeswitch.local。3.检查密码明文Peers不加密存储密码password标签内容必须与FreeSWITCH1001.xml中param namepassword value.../完全一致。4.验证Contact头域IP在控制台日志中找Sending REGISTER to sip:...确认Contact头域里的IP是192.168.1.20你的电脑IP不是127.0.0.1。根本原因FreeSWITCH的Digest认证是“realmusernamepassword”三元组哈希任一错误都会导致response计算失败返回401。Peers的DigestAuthHelper.java实现严格遵循RFC所以问题100%在配置不一致。5.2 呼叫建立但无声音单向静音现象状态栏显示“In call”FreeSWITCH日志显示Call answered但只有单向声音如你能听到对方对方听不到你。速查表可能原因验证方法解决方案RTP端口被防火墙拦截Wireshark抓包过滤udp.port 16384看是否有持续UDP包发出关闭系统防火墙或放行UDP端口范围16384-32768FreeSWITCH payload number不匹配fs_cli中执行sofia status profile internal查rtp-payload-number参数确保internal.xml中param namertp-payload-number value0/启用G.711U对应0音频采样率不匹配查看Peers控制台日志Audio started: G711U, 8000Hz对比FreeSWITCHsofia status profile internal中的rtp-sampling-ratepeers.xml中sample-rate必须为8000FreeSWITCH中param namertp-sampling-rate value8000/本机声卡输入禁用Windows右键任务栏音量图标→声音→录制确认默认设备已启用并有输入电平macOS系统设置→声音→输入选择正确麦克风Linuxalsamixer调高Capture音量独家技巧在FreeSWITCH中启用RTP调试实时看到包接收情况fs_cli -x sofia global rtp-enable-stats true fs_cli -x sofia status profile internal在输出中找RTP Stats部分recv列应有持续增长的数字。如果recv0说明RTP包根本没到FreeSWITCH。5.3 界面卡死或启动报错现象双击MainFrame无反应或IDE报Exception in thread main java.lang.NoClassDefFoundError: net/sourceforge/peers/sip/SipStack原因与解法-NoClassDefFoundErrorMaven依赖未正确编译。执行mvn clean compile确保peers-lib/target/classes/下有net/sourceforge/peers/sip/SipStack.class。-界面空白/卡死macOS未授权辅助功能。系统设置→隐私与安全性→辅助功能→添加IDE或java进程。-中文乱码配置对话框JDK字体渲染问题。在IDE的Run Configuration中VM options添加-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8。5.4 进阶问题如何让它支持TLSPeers原生不支持TLS但扩展很简单我已在生产环境验证修改peers-lib的传输层在UdpTransport.java旁新建TlsTransport.java继承SipTransport用SSLSocket替代DatagramSocket。在SipStack.java中注入修改createTransport()方法根据transport配置选择UdpTransport或TlsTransport。配置FreeSWITCH在internal.xml中启用TLS配置证书路径并将peers.xml中transport改为tlsport改为5061。最后分享一个小技巧Peers的peers-demo模块里有个SipHealthCheck.java我把它改造成一个Linux定时任务crontab -e添加*/5 * * * * cd /opt/peers java -cp target/* net.sourceforge.peers.demo.SipHealthCheck 1001 1234 192.168.1.10 /var/log/peers-health.log 21每5分钟自动注册一次日志里记录“Registered”或错误码。这成了我们FreeSWITCH集群的无声哨兵——当它停止写入“Registered”运维立刻收到告警。这才是“即开即用”在生产环境的真正价值简单但可靠。本文还有配套的精品资源点击获取简介一个纯Java实现的轻量级SIP软电话客户端不依赖复杂构建环境导入源码后直接运行net.sourceforge.peers.gui.MainFrame类就能启动图形界面。支持主流SIP服务器重点适配FreeSWITCH用户只需填写SIP账号如1001、密码如1234和服务器IP如192.168.1.10即可完成注册并发起语音呼叫。音频底层基于javax.sound兼容普通声卡设备支持RTP实时传输及G.711等基础编解码。项目自带完整Maven配置pom.xml、SIP参数配置文件peers.xml、XSD校验定义、GPL开源协议说明和多版本README所有依赖由Maven自动拉取。代码结构清晰模块分离明确包含peers-gui界面、peers-lib核心协议栈、peers-javaxsound音频适配、peers-demo示例等子模块适用于SIP协议学习、内网语音功能验证或定制化二次开发。Windows、Linux、macOS平台均可原生运行无需额外安装JVM以外的运行时组件。本文还有配套的精品资源点击获取
