帮助手册与协议规范

欢迎查阅弹幕服务器 (Danmaku Server) 的官方使用文档。本指南将协助您快速部署服务器，并公开所有底层通信标准，以便第三方业务侧接入。

技术定位声明： 本服务端是一个独立的基础通信网络设施。本指南对外公布了服务所使用的数据封包规范。目前，ZWPlayer 已基于该标准进行了通信适配。

1. 下载安装与启动

推荐采用 Docker 容器环境快速热部署，也可以通过传统编译环境包直接挂载服务：

Docker 环境部署

docker pull hysoft/danmaku-server:latest
docker run -d -p 8080:8080 --name danmaku-srv hysoft/danmaku-server

Windows 物理机部署

# 解压压缩包后以管理员身份执行
cd d:/wschat
./wschat.exe -i   # 安装服务
net start iAVCastLBLService  # 启动服务
net stop iAVCastLBLService   # 停止服务

2. 全局配置与参数环境

无论部署方式如何，服务端的启动参数或配置文件 conf/lblserver.conf 分布如下：

port=3000: 服务引擎绑定的网络端口号，控制 WebSocket 入口。
ssl=0: 是否由内部引擎支持 SSL 握手。通常建议在公网中设为0，经由 Nginx 等外层网关配置 wss 代理。

3. 开源通信协议 (JSON API)

服务端数据上报与接收的网关入口统一为：ws://serverhost.com:3000/ 或由代理后的 wss://...。以下信道交互流程中：
👉 c 代表 Client (发起端, 如各种播放器客户端)
👉 s 代表 Server (弹幕接收处理服务器)

3.1 握手与标识派发

客户端基于 WebSocket API 成功连入服务端信道后，服务器会主动下发该长连接对应的连接标识 (UID) 以分配句柄：

// s → c
{
  "type": "setuserid",
  "uid": 1412956275600,
  "ip": "192.168.1.202"
}

收到句柄后，客户端必须立刻回传一条 hello 心跳报文作为网络通路双端探测验证：

// c → s (心跳触发)
{ "type": "hello" }

// s → c (准入登记确认)
{
  "type": "hello",
  "server": "Huayi Live Chat Server Version 1.0",
  "uid": 1412956275600,
  "ip": "192.168.1.202"
}

3.2 房间进出管道管理

对于存在“分区房间”概念的业务场景（例如多路视频流并行的直播间），使用专用信道分组命令：

// c → s (申请进房)
{
  "type": "join",
  "room": "videoroom_001"
}

// s → c (全房间广播进房通知，让所有客户端获悉热频变动)
{
  "type": "event",
  "event": "joinroom",
  "uid": 1412956275600,
  "userscount": 1,
  "loginedcount": 0,
  "ip": "192.168.1.202"
}

注：退出房间时发送报文 {"type": "leave"}，服务端会拦截并向剩余端广推 leaveroom 的事件响应。

3.3 弹幕广播接口

弹幕广播轨道是本系统中并发量较大的通信接口，采用轻量级数据包设计：

// c → s (发射源上报)
{
  "type": "danmu",
  "text": "测试发送弹幕"
}

// s → c (服务器补全状态并全网广播下推)
{
  "type": "danmu",
  "text": "测试发送弹幕",
  "uid": "1412956275600",
  "avatar": "http://img.com/a.png",
  "username": "User_221"
}

3.4 用户鉴权体系注册

若要执行诸如带富媒体头像、房管禁言等高阶指令，需提前向控制台登记客户端信息库态：

// c → s (鉴权登入凭据上报)
{
  "type": "login",
  "uname": "用户61396",
  "avatar": "https://img.com/avatar.png",
  "loginid": "uid61396",
  "info": "这家伙很懒..."
}

若经授权通过，服务器将优先利用单播甩回 result: "success" 的操作回调，并于毫秒级内向房间级发派 event: "login" 的热更新流，带出 time (登入时间) 等全局缓存数据。

3.5 在线用户列表游标同步

客户端可随时发起列表请求同步状态树（自带服务器熔断截断策略，防御大体量 DDOS 或内存泄漏）：

// c → s
{ "type": "userlist" }

// s → c
{
  "type": "userlist",
  "users": [
    {
      "uid": "1412956275248",
      "ip": "x.x.x.x",
      "avatar": "...",
      "username": "用户31935"
    }   // ....最大限制内列队
  ],
  "count": 2
}

3.6 群体文字会话系统

与全屏乱窜的 "type": "danmu" 的渲染信道进行了纯代码分离，便于构建诸如侧边栏直播间弹框的数据回显：

// c → s
{
  "type": "text",
  "text": "我要聊天"
}

下行推送时的 type 对齐也为 text，若属访客匿名信标请求，结构里 username 则缺省为隐秘空串。

3.7 端到端私域管道路由透传

如果您要实现管理员定向预警指令或 P2P 的私密悄悄话隔离穿层，可以在 text 旁挂载受限路由群 touids：

// c → s (向特定 UID 并发多端消息路由，不在公房内广播)
{
  "type": "sendto",
  "text": "私信：注意你的发言规范",
  "touids": ["1412956275248", "1412956275228"]
}

3.8 服务器级脏词拦截机制

系统内核基于 Aho-Corasick 高效敏感引擎，有权通过管理员指令热重挂载匹配脏树，无需反复重启 C++ 宿主堆栈。

// c → s (指令串必须由特定报文头搭载换行符构成)
setbadwords:\r\n
禁词1=掩盖替换词1\r\n
恶言脏字词2=\r\n

该操作录入后，所有发送向服务端的带有匹配命中的弹幕流或消息源都会遭到自动和谐掩盖或物理层阻断。