LinkX 文档

企业级即时通讯与协同平台完整指南，涵盖产品介绍、功能说明、快速上手、技术架构与常见问题。

产品概述

LinkX 是一套前后端分离的企业级即时通讯（IM）解决方案，由桌面客户端、运营管理后台与单体后端服务组成，适用于团队内部沟通、协同办公与后台运营场景。

客户端支持 Windows、macOS、Linux 桌面端（Electron），Android 与 iOS 移动端正在规划中。团队可通过单聊、群聊、音视频会议、文件网盘与运营后台，完成从日常沟通到组织管理的完整闭环。

linkx-client

跨平台桌面 IM 客户端，基于 Vue 3、Electron、Pinia 与 Naive UI，提供统一 Design Token 与现代化交互体验。

linkx-admin

Web 运营管理后台，支持 RBAC 权限、内容审核、风控策略、统计大屏与系统监控。

linkx-server

Spring Boot 3.5 单体后端，集成 Netty WebSocket 实时推送、MyBatis-Flex 持久化与 MinIO 对象存储。

通信通道

REST API（默认 http://localhost:8080/api）处理业务请求；WebSocket（默认 ws://localhost:8081/ws）负责消息推送、在线状态与通话信令。

快速开始

以下步骤可在约 10 分钟内完成本地联调环境搭建。

1. 获取代码

git clone https://gitee.com/yangleduo7788/link-x.git
cd link-x

2. 启动中间件

cd linkx-server
docker-compose up -d

等待 MySQL、Redis、MinIO 健康检查通过后继续。

3. 配置并启动后端

# Windows
copy .env.local.example .env.local

# Linux / macOS
cp .env.local.example .env.local

mvn spring-boot:run
必填环境变量

JWT_SECRET（≥ 32 字符）、数据库连接、Redis 与 MinIO 配置。密钥禁止写入 application.yml，请通过 .env.local 注入。

4. 启动客户端

cd linkx-client
npm install
npm run dev

浏览器访问 Vite 开发地址（默认 5173），或使用 npm run electron:dev 启动桌面客户端。

5. 登录使用

  1. 在登录页输入账号与密码，完成滑块验证码。
  2. 首次使用可点击注册，按提示设置账号、密码与昵称。
  3. 登录后左侧为导航栏，中间为会话列表，右侧为聊天区域。
  4. 通过 LinkX ID 添加好友，即可开始单聊或创建群聊。

即时消息

LinkX 提供完整的单聊与群聊能力，满足团队日常沟通需求。

消息类型

  • 文本与表情：支持富文本输入、Emoji 与常用表情。
  • 图片与文件：可发送本地图片、文档等附件，支持预览与下载。
  • 语音消息：按住录音发送，对方可在线播放。
  • 引用回复：长按或右键消息选择引用，上下文清晰可追溯。

消息操作

  • 编辑：发送后可修改文字内容（显示已编辑标记）。
  • 撤回：限时撤回自己发送的消息。
  • 转发：将消息转发到其他单聊或群聊会话。
  • 收藏：重要消息可收藏，便于后续查阅。

群聊能力

支持创建群聊、邀请成员、设置群公告、群管理员与成员管理。群主可发布群公告，成员在群资料页查看。

实时推送

LinkX 采用 HTTP + WebSocket 双通道架构，兼顾历史消息拉取与实时推送性能。

通道 地址 用途
HTTP REST /api 认证、拉取历史消息、好友/群聊/文件等业务接口
WebSocket /ws 新消息推送、在线状态同步、通话与会议信令

客户端登录后自动建立 WebSocket 长连接，收到新消息时毫秒级推送到界面。离线期间的消息在重新连接后通过 HTTP 增量同步，确保多端消息一致。

音视频会议

基于 WebRTC 实现点对点音视频通话与多人 Mesh 会议，通话信令通过 WebSocket 实时下发。

单聊通话

在单聊会话中点击语音或视频按钮即可发起通话。对方收到来电提示，可选择接听或拒绝。通话过程中支持静音、关闭摄像头与挂断。

多人会议

支持创建多人 Mesh 会议（无 SFU 中转），适合小团队快速协作。参会者通过会议邀请加入，音视频流在参与者之间直连传输。

网络要求

音视频通话对网络质量敏感，建议在稳定网络环境下使用。若无法建立连接，请检查防火墙与 NAT 穿透配置。

文件与网盘

LinkX 将聊天文件、群文件/群相册与个人网盘统一接入 MinIO 对象存储，团队资料集中沉淀、随时取用。

聊天文件

在会话中发送的文件自动存储至 MinIO，支持在线预览（图片、PDF 等）与下载。文件记录与会话消息关联，可在聊天记录中检索。

群文件与群相册

群聊内提供群文件空间与群相册，成员可上传共享资料。群主与管理员可管理文件与成员权限。

个人网盘

每位用户拥有独立网盘空间，可上传、分类管理个人文件，并生成带提取码的分享链接供他人下载。

协作工具

除文件外，LinkX 还提供友链动态、日历日程、笔记与收藏等协作工具，与 IM 能力深度整合。

管理运营

linkx-admin 运营管理后台为团队提供一站式的后台管理能力。

  • 用户与权限：RBAC 角色权限模型，细粒度控制菜单与操作权限。
  • 内容审核：敏感词过滤、消息审核与违规内容处理。
  • 风控策略：登录风控、操作频率限制与异常行为监测。
  • 统计大屏：用户活跃、消息量、在线趋势等数据可视化（ECharts）。
  • 系统监控：服务健康检查、操作审计日志与系统配置管理。

管理端默认开发端口为 5174，生产环境建议通过反向代理接入并启用 HTTPS。

技术架构

LinkX 采用经典三层架构：展现层（客户端/管理端）→ 接入层（HTTP/WebSocket）→ 服务层（Spring Boot 单体）→ 数据层（MySQL/Redis/MinIO）。

组件 版本 说明
JDK21后端编译与运行
Spring Boot3.5.0后端框架
Vue3.5客户端与管理端 UI
Electron33桌面客户端壳
Netty4.1.115WebSocket 实时通信
MySQL8.4业务数据持久化
Redis7.2Token、缓存、在线状态
MinIO8.5.7文件与网盘对象存储

安全设计

  • 双 Token 鉴权（Access Token + Refresh Token）
  • 图形验证码与登录风控
  • 敏感词过滤与操作审计
  • Electron 渲染进程不开启 nodeIntegration，仅通过 Preload 暴露有限 API

部署说明

环境要求

端口 服务
3306MySQL
6379Redis
9000 / 9001MinIO API / Console
8080后端 HTTP API
8081IM WebSocket

生产构建

# 后端
cd linkx-server && mvn clean package -DskipTests

# 客户端桌面版
cd linkx-client && npm run build:electron

# 管理端
cd linkx-admin && npm run build

生产环境请配置 .env.prod，设置强随机 JWT_SECRET、数据库密码与 CORS_ALLOWED_ORIGINS 白名单。禁止将密钥提交至版本库。

常见问题

消息会同步吗？

会。登录后 WebSocket 建立实时连接，历史消息通过 HTTP 拉取。多设备登录同一账号时，消息在各端同步推送。

连不上或消息发不出怎么办？

请检查：1）后端服务与 WebSocket 端口是否正常；2）客户端 API 地址配置是否正确；3）网络防火墙是否拦截 WebSocket；4）Token 是否过期，尝试重新登录。

忘记密码怎么办？

在登录页使用找回密码流程，或联系管理员在后台重置密码。

如何提交问题反馈？

可在客户端「设置 → 关于」中提交 Bug 或建议，也可前往 Gitee Issues 创建工单。