LinkX 文档

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

产品概述

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

当前已发布 Windows 桌面端（v1.0.1）。下一版 1.1.0 计划交付 Linux 桌面端与 Android 移动端；再下一版 1.2.0 将聚焦灵伴知识库与 Agent 策略、本地搜索与消息同步优化、短视频推荐与运营后台。macOS 与 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。

灵伴 Agent

LinkX 1.0.1 起，客户端内置「灵伴」AI 助手，并支持 Agent 代操模式：在 LLM 返回函数调用时，由客户端在本地执行导航、打开会话、发送消息等操作（需用户授权与全局开关开启）。

能力范围

  • 会话与导航：切换导航、打开指定聊天、搜索联系人等。
  • 消息代发：在已确认上下文中代为输入并发送消息（受权限与风控约束）。
  • 设置与偏好：读取或调整部分客户端设置（如通知开关）。

管理端策略

运营人员可在管理端配置灵伴 Agent 全局开关、群聊 AI 默认接入策略，并在「系统设置 → 灵伴」中统一管理。企业可按需关闭代操能力，仅保留对话问答。

安全提示

Agent 代操在客户端沙箱内执行，不会直接暴露服务端密钥；敏感操作仍需用户确认。生产环境请结合 RBAC 与风控规则审慎开放。

技术架构

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

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

安全设计

  • 双 Token 鉴权（Access Token + Refresh Token）
  • 图形验证码与登录风控
  • 敏感词过滤与操作审计
  • Electron 渲染进程不开启 nodeIntegration，仅通过 Preload 暴露有限 API
  • 可选消息落库加密（AES-256-GCM，默认关闭，非端到端加密）

消息落库加密

LinkX 服务端支持将 IM 消息等内容在写入 MySQL 前使用 AES-256-GCM 加密存储。该能力默认关闭，对客户端透明：客户端仍通过 HTTPS / WSS 传输，无需改动。

加密范围

  • 单聊 / 群聊消息正文与引用内容（im_message）
  • 朋友圈动态正文与位置、评论内容（moments_*）

与端到端加密（E2EE）的区别

落库加密由服务端持有密钥并在应用层加解密，属于存储层保护，不是端到端加密。管理端的敏感词过滤、内容审核、举报与审计等能力在开启后仍可正常工作。

部署者须知

密钥（MESSAGE_KEK）须与 JWT_SECRET 独立配置并离线备份；丢失密钥将导致历史密文无法恢复。完整环境变量与 KEK 轮换说明见仓库 README「8.4 消息落库加密」。

如何开启（自托管）

在 linkx-server/.env.prod 或 .env.local 中配置：

MESSAGE_CONTENT_ENCRYPT_ENABLED=true
MESSAGE_KEK=<openssl rand -base64 32 生成的值>
MESSAGE_KEK_KEY_ID=default

重启后端后，Snail Job 会分批将历史明文转为密文；KEK 轮换可通过 MESSAGE_KEK_LEGACY_MAP 保留旧密钥用于解密。

版本与更新

LinkX 桌面客户端支持启动时自动检查更新。版本信息与更新说明由管理端「版本发布」维护，客户端通过 GET /app/version 拉取，无需在客户端硬编码文案。

管理端发布流程

  1. 在管理端「版本发布」创建草稿，填写版本号、渠道、平台与更新说明（releaseNotes）。
  2. 上传 Windows 安装包（或填写 MinIO / CDN 下载地址与 SHA-256）。
  3. 发布后立即对客户端生效；旧版同平台记录自动归档。
  4. 官网下载：配置 site-config.js 的 apiBaseUrl 后，通过 GET /app/version 获取 R2 公网直链。

客户端行为

  • 有新版本：Electron 在后台静默下载安装包；可选更新下载完成后提示「立即安装」，强制更新则自动静默安装并重启。
  • 已是最新：若当前版本有发布说明且用户未读过，展示「本次更新」弹窗（currentReleaseNotes）。
  • 手动检查：设置 → 关于 →「检查更新」，或侧栏更多菜单中的检查更新入口。

自托管发布脚本

仓库提供 linkx-client/scripts/publish-release.mjs，可在打包后自动上传安装包并调用管理端 API 创建/发布版本记录。详见仓库 README「9.2 桌面客户端」。

部署说明

环境要求

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

生产构建

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

# 客户端桌面版（须先配置 .env.electron）
cd linkx-client && npm run electron:build

# 管理端
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 或 GitHub Issues 创建工单。

消息在数据库里是明文吗？

默认情况下消息以应用层可读形式落库；自托管部署者可选择开启 AES-256-GCM 落库加密（见上文「消息落库加密」）。无论是否开启，传输层均使用 HTTPS / WSS；落库加密不是端到端加密，服务端在业务需要时仍可解密内容用于审核与审计。

客户端如何获取新版本？

桌面端启动时会自动请求 /app/version 检查更新并后台下载；也可在「设置 → 关于」手动检查。更新说明由管理端版本发布填写，官网 changelog 与客户端弹窗内容应保持一致。