【操作篇】关于vocechat如何实现电话功能

一、关于vocechat

VoceChat是一款使用 Rust(后端)，React(前端)，Fluter(移动端)开发的，开源，支持独立部署的在线聊天服务。

VoceChat 非常轻量，后端服务只有 15MB 的大小，打包的 Docker 镜像文件也只有 61 MB,VoceChat 可部署在任何的服务器上

VoceChat 是一款近年来在私有化部署圈子里备受瞩目的独立即时通讯（IM）服务器端软件。它采用了极其现代化的技术栈：后端基于高并发、内存安全的 Rust 语言编写，前端采用 React，而移动端（iOS/Android）则基于谷歌的 Flutter 跨平台框架构建。

与其他动辄占用几个 G 内存的巨无霸级企业 IM 服务（如其它的开源类 Slack 工具）相比，VoceChat 将“轻量化”发挥到了极致。其后端编译后的可执行文件仅有 15MB 左右，打包成 Docker 镜像后也仅仅只有 61MB。这意味着你甚至可以把它轻松塞进一台 1核1G 的低配云服务器，或者是家里常年开机的低功耗软路由及群晖 NAS 中，完美保障了数据的绝对私密性。

VoceChat具体特点

二、 底层通信原理：为什么自建聊天需要接入声网（Agora）？

很多同学在自建 Web 聊天室时会发现，文字和图片传输非常容易，但只要一开启音视频通话，就会遭遇两端“听不见、看不到”的窘境。

这是因为网页端音视频通常依赖 WebRTC 技术，而 WebRTC 是一种点对点（P2P）通信协议。在复杂的国内家用宽带网络环境下（多数为多层 NAT 架构），两个客户端之间很难直接建立起稳定的连接（需要进行复杂的 STUN/TURN 打洞）。

为了解决这个网络壁垒，最稳妥、延迟最低的方案就是引入行业标准的第三方实时音视频云服务（PaaS）——声网（Agora）。

• 工作逻辑：当我们在 VoceChat 中发起通话时，服务器通过配置好的 Agora App ID 和证书，在云端动态生成一个临时的安全 Token（令牌）。
• 效果：通话双方通过这个 Token 安全地接入声网位于全球的超低延迟实时音视频边缘流媒体网络（SD-RTN™），由声网的服务器协助进行媒体流的转发和 NAT 穿透。针对个人开发者，声网每月免费赠送 10,000 分钟 的时长，这对于个人、家庭或小团队的私有聊天室来说，几乎等于完全免费！

三、如何部署

鉴于博主是使用自己的Synology服务器的套件直接傻瓜式下载部署的，这里便不多介绍了！
具体到docker 部署或者其它方式的部署方案，请大家移步到如下Github地址：

github

四、vocechat电话功能

实现电话功能，首先需要进入到vocechat聊天界面，点击设置--如下图：

进入设置后，点击左侧配置--Agora

进入到Agora后，会看到如下信息：

如何操作配置才可以实现电话功能，官方文档也给出了操作步骤（由于Agora页面有所改版，可能与文档有所不同，大概是一样的步骤），博主主要写几点注意细节如下：

官方文档

1.在获取Agora API时需新建项目，例如博主创建的chatgpt，项目名称随便起即可

2.创建完项目后，根据官方文档取到对应环境值，比如项目ID、url等

3.对于添加秘钥，按照博主如下截图创建新的秘钥配置即可（原教程对于创建秘钥的链接已废）

4.将秘钥填写到对应位置即可

五、 深度实战：摒弃“傻瓜式”，拥抱 Docker-Compose 高阶部署

虽然博主在第三部分提到了使用群晖自带的套件“傻瓜式”部署，但作为一篇硬核的技术教程，我们必须深入探讨一下 Docker-Compose 的部署方式。为什么？因为群晖内置的 Container Manager (原 Docker 套件) 图形界面虽然直观，但在进行跨设备迁移、快速重建、或者配置复杂的环境变量时，往往捉襟见肘。

掌握 Docker-Compose，你就能用一段简单的代码，在任何一台 Linux 服务器（VPS）或 NAS 上瞬间还原你的 VoceChat 聊天帝国。

1. 准备目录结构与挂载点
   首先，我们需要在服务器上创建一个专用的目录，用来存放 VoceChat 的核心数据（这非常重要，如果不挂载出来，一旦容器重启或更新，你的聊天记录和配置就会全部丢失）。

通过 SSH 登录你的群晖或 Linux 服务器，执行以下命令：

# 创建 vocechat 根目录及数据子目录
mkdir -p /volume1/docker/vocechat/data
# 进入目录
cd /volume1/docker/vocechat

2. 编写 docker-compose.yml 文件
   在刚才创建的目录中，使用 vim 或 nano 创建一个 docker-compose.yml 文件：

   nano docker-compose.yml

   将以下经过博主深度优化的配置代码粘贴进去：

   version: '3.8'
   
   services:
     vocechat-server:
    image: privoce/vocechat-server:latest
    container_name: vocechat-server
    restart: always # 意外崩溃或服务器重启时自动拉起
    ports:
      - "3000:3000" # 左侧是宿主机端口（可自行修改），右侧是容器内固定端口
    environment:
      # 这里可以强制指定你的外网访问域名，非常关键！
      - VOCECHAT_ORIGIN=https://chat.yourdomain.com
    volumes:
      # 冒号左侧为你刚才创建的宿主机物理路径，右侧为容器内部路径
      - /volume1/docker/vocechat/data:/home/vocechat-server/data

3. 一键启动服务
   保存文件后，在当前目录下执行：

docker-compose up -d

稍等片刻，看到绿色的 done 提示后，你就可以通过 http://你的服务器IP:3000 访问 VoceChat 的初始化界面了。这种部署方式，数据和环境完全剥离，后期想要升级，只需执行 docker-compose pull && docker-compose up -d 即可无损更新，简直不要太爽！

六、 决定音视频生死的核心关卡：HTTPS 与反向代理配置

我们在配置好声网（Agora）参数后，很多水友兴冲冲地去网页端点击拨打视频电话，却发现浏览器弹出了一个冷冰冰的错误提示：“无法获取麦克风和摄像头权限”，或者根本就不弹授权框。

这绝对不是 VoceChat 的 Bug，也不是声网的问题，而是现代浏览器的安全策略（安全沙盒机制）在作祟！

1. 为什么必须配置 HTTPS？
   无论是 Chrome、Edge 还是 Safari，处于对用户隐私的绝对保护，它们在底层代码中写死了一条铁律：WebRTC 相关的 API（即调用本地麦克风和摄像头的权限），只能在 localhost（本地主机）或者经过 SSL 证书加密的 HTTPS 协议下才能被触发。

如果你使用 http://192.168.1.x:3000 或者未加密的 http://chat.yourdomain.com 访问，浏览器会直接掐断 WebRTC 的底层调用，你的音视频功能自然彻底瘫痪。

2. Nginx 反向代理与 WebSocket 升级配置 (硬核干货)
   为了解决这个问题，我们需要配置一个反向代理（Nginx），并为域名套上 SSL 证书。如果你使用的是宝塔面板或群晖自带的反代功能，可以直接在图形界面申请证书。

但这里有一个极其容易踩坑的盲区：VoceChat 是一款强依赖 WebSocket (ws/wss) 协议进行实时消息推送的应用。
普通的 Nginx 反代配置只能转发常规的 HTTP 网页请求，如果不配置 Upgrade 协议头，你的 VoceChat 就会出现“消息发不出去”、“无法实时收到新消息”、“频繁掉线重连”的致命问题。

以下是博主为你整理的、经过真实生产环境检验的 Nginx 完美反代配置段（请添加到你的 Nginx 虚拟主机配置中）：

server {
    listen 80;
    listen 443 ssl http2;
    server_name chat.yourdomain.com; # 替换为你的真实域名

    # SSL 证书路径配置 (请替换为你自己的证书路径)
    ssl_certificate /path/to/your/fullchain.cer;
    ssl_certificate_key /path/to/your/private.key;
    
    # 强制 HTTP 跳转 HTTPS
    if ($server_port !~ 443){
        rewrite ^(/.*)$ https://$host$1 permanent;
    }

    location / {
        proxy_pass http://127.0.0.1:3000; # 指向你本地的 VoceChat 端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # -----------------------------------------------------------
        # 以下三行是保障 WebSocket 实时通信的生命线！绝不能漏掉！
        # -----------------------------------------------------------
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        
        # 调整超时时间，防止长连接被 Nginx 意外切断
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

当你完成了这套完整的反代与 HTTPS 部署后，再次在浏览器中打开 VoceChat 尝试拨打电话，你会看到久违的“允许使用麦克风和摄像头”的弹窗，音视频流的任督二脉才算真正打通。

七、 2026 最新声网 (Agora) 控制台踩坑排雷全指南

在本文的第四部分，我们展示了声网的一些配置截图。但声网作为一个面向企业级的开发者平台，其控制台界面经常改版，很多老旧教程里的按钮早就找不到了。这里博主针对 2026 年最新的声网控制台，手把手教你如何精准提取那三个决定通话成败的核心秘钥参数：App ID、App Certificate 和 RESTful API Key。

1. App ID 与 App Certificate（应用层面的双保险）
   登录声网控制台后，在左侧导航栏找到 【项目管理】 -> 【项目列表】。

点击创建新项目。在弹出的选项中，极度注意：鉴权机制请务必选择“安全模式（APP ID + APP Certificate）”！千万不要选“调试模式（仅 APP ID）”。因为 VoceChat 的后端逻辑是强制要求使用 Certificate 动态生成安全 Token 的，如果选了调试模式，VoceChat 服务器将无法签名，直接导致通话握手失败。

项目创建成功后，点击项目卡片上的“配置”图标，你就能直接复制出第一组核心参数：App ID 和 App Certificate。

2. Customer ID 与 Customer Certificate (全局 RESTful API 秘钥)
   这是无数新手卡壳最久的地方。在老版本的控制台，这玩意叫 Basic Auth 凭证；但在新版中，声网将其统一收编到了全局设置里。

点击控制台右上角的【你的头像/账号名】 -> 在下拉菜单中选择 【RESTful API】。

如果你是新账号，这里大概率是空的。点击 【添加秘钥 (Add Secret)】。

此时系统会为你生成一对全新的参数。左侧是 Customer ID，右侧是 Customer Certificate (或 Customer Secret)。

高能预警：这个 Secret 只在创建的瞬间展示一次！ 一旦你刷新页面，它就会变成 永久隐藏。如果你忘了保存，只能删掉重新生成。

把这 4 个参数（2个应用级参数，2个账号全局级参数）分毫不差地填入 VoceChat 后台的 Agora 配置项中。只要参数无误，当你拨打电话时，VoceChat 的 Rust 后端就会以毫秒级的速度向声网服务器请求 Token，随后你的浏览器就会通过该 Token 顺畅无阻地接入声网的 SD-RTN™ 全球流媒体骨干网中。

八、 移动端 (Flutter) 接入与离线消息推送 (Push) 深度解析

VoceChat 之所以香，很大程度上归功于它不仅有 Web 网页端，还提供了体验极其丝滑的 iOS 和 Android 原生移动端 App。但自建聊天服务器在移动端的痛点，往往在于“如何接收离线消息推送”。

1. 移动端 App 的连接方式
   你可以直接前往 App Store (苹果) 或 Google Play (安卓) 搜索 VoceChat 下载官方客户端。如果你没有海外应用商店账号，也可以在其官网直接下载 APK 安装包。

打开 App 后，第一件事是点击“切换服务器”。

输入你部署并配置好 HTTPS 的独立域名（如 https://chat.yourdomain.com）。

然后使用你在网页端注册的账号密码登录即可，所有数据将与 Web 端无缝双向同步。

2. 离线消息推送的“原罪”与 VoceChat 的妥协方案
   在微信、Telegram 等商业 IM 软件中，即使你把 App 后台彻底杀掉，只要有人发消息，你的手机顶部依然会准时弹出横幅通知。这是因为它们通过官方渠道接入了苹果 APNs (Apple Push Notification service) 和谷歌 FCM (Firebase Cloud Messaging) 系统级别的推送通道。

但对于自建（Self-hosted）应用来说，系统级离线推送是一个几乎无解的死局。
因为苹果和谷歌要求：只有 App 的开发者（包名持有者）利用其私有的开发者证书，才能向这些手机下发推送指令。你部署在自己群晖或 VPS 上的私人服务器，是不可能拥有官方 VoceChat App 的推送权限证书的。

那么，VoceChat 是如何解决这个问题的呢？
目前 VoceChat 采用的是 “后台进程保活（Keep-Alive） + WebSocket 长连接” 的方案。

安卓端 (Android)：只要你不手动去任务管理器里划掉（杀掉）VoceChat App，甚至你在系统电池设置里给它开启了“允许后台高耗电/无限制”，它就能在后台一直维持着与你服务器的连接，实时收到消息并弹出震动通知。

苹果端 (iOS)：由于 iOS 极其严苛的墓碑机制，App 切入后台几分钟后就会被系统强制挂起（冻结网络栈）。因此，iOS 端在完全后台状态下，是无法收到私人服务器消息推送的。你只能依靠定期打开 App 去拉取新消息。

（进阶提示：VoceChat 官方社区曾讨论过推出类似“推送代理网关”的服务，即你的私人服务器将加密消息发给官方服务器，官方服务器再利用官方证书向苹果发起推送。但受限于隐私争议和合规性，目前纯内网自建环境依然只能依赖 App 保持前台或安卓保活。）

九、 高频报错排查与终极运维指南 (FAQ)

在私有化部署即时通讯系统的道路上，绝不可能一帆风顺。博主整理了社区中最常见的几个“天坑”及排障思路，当你的 VoceChat 出现异常时，请按图索骥：

Q1：网页端可以文字聊天，但对方发来的图片和文件一直显示“加载中/破图”？
排查逻辑：99% 是因为你反向代理（Nginx）配置的上传体积限制太小，或者外网访问配置不正确。

解决方案：

打开 Nginx 配置文件，在 http {} 或 server {} 块中加入 client_max_body_size 100M;（放行 100MB 内的文件传输）。

进入 VoceChat 的网页管理员后台 -> 设置 -> 常规 -> 应用配置，检查“服务器 URL (Server URL)” 是否填写了你真实的外网访问 HTTPS 域名。如果不填或者填错，生成的图片链接就是死链。

Q2：声网 Agora 电话打通了，但是双方听不到声音（单向无声/双向无声）？
排查逻辑：WebRTC 需要 UDP 协议来传输高并发的媒体流。声网依靠其服务器做中转。出现无声现象，往往是因为局域网防火墙拦截，或是浏览器的安全降级。

解决方案：

确保你的群晖或 VPS 系统防火墙没有屏蔽出站的 UDP 流量。

尝试切换网络，用手机 4G/5G 流量测试是否正常，排除公司/校园网路由器强力封杀 UDP P2P 报文的可能性。

检查电脑系统的隐私设置，确保浏览器不仅有麦克风权限，且未被第三方杀毒软件（如 360、火绒）的隐私保护模块偷偷拦截。

Q3：我的聊天记录非常宝贵，该如何正确备份 VoceChat 数据？
排查逻辑：VoceChat 使用的是轻量级的 SQLite 关系型数据库。不同于 MySQL，SQLite 的数据完全以单个文件的形式存在硬盘上，这让备份变得极其简单，但也存在文件锁定的风险。

解决方案：
在第五部分我们挂载了 /volume1/docker/vocechat/data 目录。你进入这个目录，会看到一个名为 vocechat.db 的文件，这就是全站的命脉（包含所有用户账号、加密秘钥、文本聊天记录）。

日常冷备：最安全的做法是执行 docker stop vocechat-server 停掉容器，然后把整个 data 文件夹打包压缩（如 .tar.gz 或上传到百度云/群晖 Hyper Backup），再重新启动容器。

关于 WAL 模式：如果你看到旁边还有 vocechat.db-wal 和 vocechat.db-shm 文件，这是 SQLite 的预写日志机制。备份时，必须连同这三个文件一起备份！ 如果只拷走主 db 文件，你会丢失最近几小时内的聊天记录，甚至导致数据库损坏。

Q4：手贱把唯一拥有权限的“管理员（Admin）”账号密码忘了，怎么办？
解决方案：既然是自建，数据库就在我们自己手里，完全可以直接从底层抢回最高权限！

停止 VoceChat 的 Docker 容器。

下载一个本地数据库可视化工具（如 DBeaver 或 SQLiteStudio）。

将服务器上的 vocechat.db 拷贝到电脑上，用软件打开。

找到 users 表，里面会有一列记录用户的密码哈希值。不过 VoceChat 官方为了安全，并没有提供简单的密码重置脚本。

最粗暴有效的解法是：去 users 表里，把你注册的“小号（普通用户）”的 is_admin 字段（如果有，或者类似权限标志位）从 0 改成 1，赋予小号管理员权限。然后保存数据库传回服务器，启动容器。用小号登录后台后，再通过管理员面板强制重置大号的密码！

十、 总结：私有化通信的终极浪漫

折腾 VoceChat 的过程，实际上是一次对于现代 Web 开发技术栈的全景巡礼。从最基础的 Docker 容器化部署，到 Nginx 逆向代理与 WebSocket 协议的升级；从 WebRTC 的原理探究，到声网 PaaS 服务的全套接口对接；甚至还要与 iOS/Android 的系统底层保活机制做长期斗争。

在微信、钉钉等巨头已经彻底统治社交网络的今天，我们为什么还要大费周章地去自建一个私人聊天室？
答案在于四个字：数据主权。

在这个所有的对话、图片、文件都被云端 AI 和审核算法 24 小时凝视的时代，拥有一个完全受自己控制的服务器，数据库躺在自己家里客厅的 NAS 硬盘上，没有任何第三方能够窥探你们的私密对话。这份不被监控的自由，和掌控自己数字资产的绝对安全感，正是每一个技术爱好者不断折腾私有化部署的最极致浪漫所在！

希望本篇高达四千字的硬核部署与排错指南，能帮助大家在搭建 VoceChat 的道路上少走弯路，早日构建出属于你自己的隐秘数字乌托邦。