ChatLink Server

ChatLink 聊天服务器 — 为 ChatLink Minecraft 客户端 Mod 提供聊天域管理和消息转发服务。

基于原生 Java TCP Socket，无外部框架依赖，轻量级运行，支持 Windows 和 Linux。

使用说明

快速开始

• Java 21+

1. 下载 最新版本 的 chatlink-server-*.jar
2. 运行：

java -jar chatlink-server-1.0.1.jar --port 25565

Windows 用户可直接双击 start.bat。

命令行参数

参数	说明	默认值
--port <端口>	监听端口	25565
--web-port <端口>	Web 管理面板端口	8080

控制台指令

指令	说明
help	显示帮助
list	列出在线玩家
domains	列出所有域
kick <玩家名>	踢出指定玩家
status	查看服务器状态
save	手动保存数据
stop / exit / quit	停止服务器

Web 管理面板

启动服务器后访问 http://localhost:8080 查看实时仪表盘，包含：

• 服务器状态（版本、在线玩家数、域数量）
• 域列表（含玩家详情）
• 在线玩家列表
• 每 10 秒自动刷新

功能特性

• 聊天域管理 — 创建、加入、离开、删除聊天域，支持公开/私密设置
• 多域同时在线 — 玩家可同时加入多个域，自由切换
• 私聊 — 玩家间私密消息，不经过域
• 域内角色 — 创建者/管理员/成员三级角色，禁言和踢人
• 域描述 — 域创建者可设置描述信息
• 消息历史 — 每个域保留最近 50 条消息，玩家加入时自动推送
• 消息转发 — 域内广播，不经过 Minecraft 服务器
• 用户认证 — 基于 Minecraft UUID + 玩家名
• 心跳保活 — 30 秒心跳间隔，90 秒超时检测
• 数据持久化 — 域数据和消息历史自动保存到 JSON 文件，重启不丢失
• Web 管理面板 — 内嵌 HTTP 仪表盘，实时查看服务器状态
• 控制台管理 — 查看在线玩家、域列表、踢出玩家等
• 自动清理 — 域中无玩家时自动删除，玩家断开时自动离开所有域

架构概览

基于原生 Java TCP Socket，共 6 个核心类，无外部框架依赖。

类	职责
ChatLinkServer	主入口，管理 ServerSocket、会话列表、持久化、Web 服务器
ClientSession	每个客户端连接对应一个实例，读线程、认证状态、消息路由
DomainManager	聊天域管理，多域支持，角色管理，禁言管理，消息历史
MessageProtocol	JSON 消息的类型常量、解析、构建（基于 Gson）
PersistenceManager	数据持久化，域和消息历史的 JSON 文件读写
WebServer	内嵌 HTTP 服务器，管理面板仪表盘和 REST API

后台线程

• Accept 线程 — 持续接受新连接
• TimeoutCheck 线程 — 每 30s 检测心跳超时（90s 超时）
• Console 线程 — 读取服务器控制台指令
• Web 线程池 — 处理 HTTP 请求（4 线程）

通信协议

客户端与服务器通过 TCP 长连接通信，消息格式为 JSON（以 \n 分隔）。

消息格式

{"type": "<类型>", "data": { ... }}

响应格式：

{"type": "<类型>", "status": "ok|error", "data": { ... }, "error": "错误信息"}

消息类型

类型	方向	说明
auth	客户端→服务端	认证（UUID + 用户名），认证后分配 8 位 session_id
heartbeat	双向	心跳（30s 间隔），服务端返回 server_time
list_domains	客户端→服务端	查询公开域列表
create_domain	客户端→服务端	创建域（自动加入），域 ID 为 4 位数字
join_domain	客户端→服务端	加入域（不再自动离开旧域）
leave_domain	客户端→服务端	离开域
chat_message	双向	域内聊天消息广播
delete_domain	客户端→服务端	删除域（仅创建者可删）
player_joined	服务端推送	玩家加入域通知
player_left	服务端推送	玩家离开域通知
private_message	双向	私聊消息
private_message_sent	服务端→客户端	私聊发送确认
message_history	服务端→客户端	消息历史推送
set_role	客户端→服务端	设置角色（CREATOR/ADMIN/MEMBER）
kick_player	客户端→服务端	踢出玩家
mute_player	客户端→服务端	禁言玩家
unmute_player	客户端→服务端	解除禁言
set_description	客户端→服务端	设置域描述
domain_description	服务端推送	域描述变更通知
domain_joined_list	服务端推送	已加入域列表

心跳机制

• 任何消息到达都会刷新心跳时间
• 后台线程每 30s 检查一次
• 超过 90s 无心跳则断开连接
• 域中无玩家时自动删除
• 玩家断开时自动离开所有域

数据持久化

• 域数据保存在 data/domains.json
• 消息历史保存在 data/messages.json
• 启动时自动加载，域变更时实时保存
• 定期保存（每 60 秒）

详细 JSON 格式见客户端项目的 protocol-spec.md。

构建

git clone https://github.com/AlsoLate/chatlink-server.git
cd chatlink-server
./gradlew build

编译产物：

• build/libs/chatlink-server-1.0.1.jar（fat jar，含所有依赖）
• build/distributions/chatlink-server-1.0.1.tar / .zip（分发包）

反馈

QQ 群：950162690

许可证

MIT License

作者

星渡