LAN Chat System 局域网全平台实时通信系统

2026年2月22日实用的小工具夏木

开源更新 | LAN Chat System v1.2.0 局域网全平台实时通信系统完整解析

作者：夏木 · 首发于 https://xmosai.com · 转载请注明出处与项目地址

大家好，我是夏木。距离上一次发布LAN Chat System 1.0版本，我收到了很多朋友的反馈与优化建议，今天给大家带来项目的全新大版本更新——LAN Chat System v1.2.0。

这是一套专为局域网环境打造的、开箱即用的全平台实时通信解决方案，彻底解决了内网环境下跨设备消息互通、文件传输的痛点，无需公网服务器、无需复杂配置，一键部署即可实现多终端互联互通。本文将从版本更新亮点、系统架构、技术选型、功能实现、完整部署教程等多个维度，为大家完整拆解这个项目的最新版本。

项目已完整开源至Gitee，持续迭代维护，本文所有内容均基于v1.2.0最新版本编写，零基础也能跟着教程完成部署。

🔗 项目开源仓库地址：https://gitee.com/xmosai/lan-chat-system

本文首发于我的个人网站：https://xmosai.com，转载请注明出处与项目地址。

一、v1.2.0 版本核心更新亮点

相较于1.0基础版本，v1.2.0完成了从「临时匿名聊天工具」到「完整可商用的内网通信系统」的全面升级，核心更新如下：

新增 完整账号体系：支持用户注册/登录，密码采用bcrypt单向加密存储，登录状态持久化，告别1.0版本的IP匿名临时身份
新增 超级管理员系统：内置ADMIN超级管理员账号，支持用户管理、违规用户封禁、历史消息清理、文件管理等高级权限，更适合团队/办公场景使用
新增 数据持久化能力：内置轻量本地数据库，用户信息、历史聊天消息均可长期存储，服务重启后数据不丢失
新增 全平台一键部署脚本：Windows双击bat一键启动、Linux/macOS一键脚本部署，支持后台常驻运行，零基础也能快速上手
优化 UI与交互全面优化：Web端与移动端UI全新升级，新增Emoji表情包支持、智能时间格式化、深色模式适配、消息撤回等高频功能
优化 移动端体验全面升级：适配完整账号体系，优化Android 13+权限模型，新增后台保活、断线自动重连、离线消息补发等能力
安全 安全性全面提升：新增接口权限校验、文件上传权限管控、操作日志记录，杜绝越权访问与违规操作

二、项目开发背景与核心解决的痛点

在日常办公、家庭内网、机房运维、展会现场等无公网/公网受限的场景中，我们经常会遇到这些问题：

手机和电脑互传文件，需要借助微信、QQ等公网工具，不仅限速严重，还会消耗流量，大文件传输体验极差
内网多设备之间的临时消息沟通，没有轻量化的工具，需要搭建复杂的企业通信系统
涉密/内网环境不允许数据上公网，传统通信工具无法使用
现有局域网工具大多仅支持单平台，无法实现Android、Windows、macOS、Linux多端互通
同类工具部署复杂，需要数据库、中间件等依赖，新手难以快速上手

基于以上痛点，我开发了这套LAN Chat System，它完全运行在局域网内，数据全程不经过公网，兼顾了安全性、易用性和跨平台兼容性，同时做到了轻量化部署，零基础也能快速上手。

三、v1.2.0 完整核心功能特性

本项目覆盖了局域网通信的全场景需求，核心功能如下：

实时双向消息通信：基于WebSocket的低延迟消息收发，支持文本消息、Emoji表情包实时推送，附带精准时间戳与发送者信息，全端消息实时同步，支持消息撤回功能
全类型文件传输能力：支持任意格式、任意大小的文件上传与下载，图片、视频、文档、压缩包均可完美支持；图片类文件支持在线预览，无需下载即可查看；文件自动按日期归档存储，便于管理
局域网自动服务器发现：移动端无需手动输入服务器IP地址，APP启动后自动扫描局域网内的可用服务节点，一键完成连接，零基础用户也能快速上手
完整账号与权限体系：支持用户注册/登录，密码加密存储，登录状态持久化；内置超级管理员账号，支持用户管理、数据清理、权限管控，适配团队场景使用
统一化用户头像系统：由服务端集中管理用户头像资源，支持用户自主更换头像，更换后全平台实时同步，所有客户端显示一致的头像信息
在线用户实时管理：实时展示当前在线的所有用户列表与在线人数，用户上下线实时广播通知，支持离线用户展示
微信风格现代化UI：Web端与移动端均采用了用户熟悉的IM类软件交互逻辑，UI设计贴合主流使用习惯，支持深色模式适配，无需学习成本即可快速上手
多终端全平台兼容：一套服务端，同时支持Web浏览器、Android移动端两大客户端，Windows、macOS、Linux设备可直接通过浏览器接入，无需安装额外软件
数据持久化存储：内置轻量本地数据库，用户信息、历史消息均可长期保存，服务重启不丢失，支持历史消息回溯

四、系统架构与数据流设计

本系统采用经典的中心化C/S（客户端-服务端）架构，所有节点均处于同一局域网内，通过WiFi/有线网络完成数据交互，无任何公网依赖，整体架构如下：

┌─────────────────────────────────────────────────────────────────────┐
│ 局域网通信系统整体架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ PCWeb 客户端 │ │ Node.js 服务端 │ │ 移动端APP │ │
│ │ (浏览器原生) │◄────►│ 消息/文件中枢 │◄────►│ (Flutter) │ │
│ └────────────────┘ └────────────────┘ └──────────────┘ │
│ │ │ │ │
│ └────────────────────────┼────────────────────────┘ │
│ 局域网 WiFi/有线网络 │
└─────────────────────────────────────────────────────────────────────┘

4.1 核心数据流设计

账号认证流：客户端提交注册/登录请求 → 服务端校验账号密码 → 生成登录凭证 → 返回用户信息 → 客户端建立Socket长连接，完成身份认证
消息通信流：客户端通过Socket.io与服务端建立长连接，发送消息时将消息体+发送者信息+时间戳推送到服务端，服务端校验后通过广播机制推送给所有在线客户端，实现全端消息同步
文件传输流：客户端通过HTTP POST协议将文件上传至服务端，服务端通过Multer中间件完成文件接收、存储、元信息记录，生成唯一可访问的下载链接，再通过消息广播将文件信息推送给所有客户端
用户状态流：客户端连接/断开时，服务端自动触发上下线事件，更新在线用户列表，并将最新的用户状态广播给所有在线节点，实现用户在线状态的实时同步
服务发现流：服务端启动后，通过UDP广播在局域网内周期性发布自身的IP地址与端口信息；移动端APP启动后，监听对应端口的广播包，自动解析服务端地址，完成自动连接，无需用户手动输入IP

五、全栈技术选型与实现细节

本项目在技术选型上，兼顾了开发效率、运行性能、跨平台兼容性与轻量化部署要求，全栈技术栈与实现细节如下：

5.1 服务端技术栈

服务端基于Node.js生态开发，核心目标是轻量化、高并发、易部署，单文件即可完成核心服务的启动，具体技术选型如下：

技术框架/库	版本要求	核心作用与实现细节
Node.js	v16.0及以上	服务端运行时，基于事件驱动的非阻塞I/O模型，完美适配WebSocket长连接场景，单进程即可支撑数百个客户端同时在线
Express	最新稳定版	轻量级Web服务框架，负责HTTP服务搭建、静态资源托管、文件上传接口、RESTful API开发，代码极简，性能优异
Socket.io	最新稳定版	核心双向通信库，基于WebSocket封装，兼容低版本HTTP协议，自带断线重连、房间广播、消息确认机制，是实现实时消息的核心
Multer	最新稳定版	Express生态的文件上传中间件，负责处理客户端的multipart/form-data文件请求，支持文件大小限制、扩展名过滤、自定义存储路径、文件名重命名防冲突
NeDB	最新稳定版	轻量嵌入式文档数据库，API与MongoDB兼容，无需额外安装服务，开箱即用，实现用户信息、历史消息的持久化存储
bcryptjs	最新稳定版	密码加密库，实现用户密码的单向哈希加密，不存储明文密码，保障账号安全
CORS	最新稳定版	跨域资源共享中间件，解决Web端、移动端与服务端的跨域请求问题，适配不同终端的访问需求
cross-spawn	最新稳定版	跨平台命令执行库，适配Windows/Linux/macOS的一键部署脚本，实现环境自动校验与依赖自动安装
Node-os-utils	最新稳定版	系统信息获取库，用于获取服务端所在设备的局域网IP地址，实现服务启动时的IP自动展示与广播

5.2 移动端技术栈

移动端基于Google Flutter跨平台框架开发，一套代码即可编译生成Android APK，预留iOS适配目录，未来可快速适配iOS平台，核心技术选型如下：

技术框架/库	核心作用与实现细节
Flutter SDK	跨平台UI开发框架，采用Dart语言，自带渲染引擎，保证Android全版本的UI一致性，性能接近原生应用
Socket.io Client Dart	Dart版Socket.io客户端，与服务端Socket.io完美兼容，实现与服务端的长连接建立、消息收发、断线重连
Provider	Flutter官方推荐的状态管理库，轻量级、易上手，实现全局用户状态、消息列表、在线用户列表的状态管理与UI响应式更新
Cached Network Image	网络图片缓存库，实现头像、图片消息的本地缓存，减少重复网络请求，提升图片加载速度，节省局域网带宽
Flutter Animate	Flutter动画库，为消息收发、页面切换、状态变化提供流畅的动画效果，提升用户交互体验
Permission Handler	权限管理库，适配Android不同版本的权限申请机制，统一处理网络、存储、WiFi状态等必要权限的申请与校验
Network Info Plus	网络信息获取库，用于获取手机当前连接的局域网网段，实现服务端地址的自动扫描与发现
File Picker	文件选择库，适配Android全版本的文件系统，实现任意类型文件的选择与上传

5.3 Web前端技术栈

Web前端采用原生Web技术开发，无任何前端框架依赖，极致轻量化，无需编译，直接通过浏览器即可运行，适配所有现代浏览器，核心技术如下：

技术	核心作用与实现细节
HTML5	页面结构搭建，语义化标签，适配移动端与PC端浏览器的响应式布局
CSS3	页面样式与UI渲染，采用Flex弹性布局，实现全设备响应式适配，微信风格的UI设计，自带深色模式适配
原生JavaScript (ES6+)	前端交互逻辑开发，无需Vue/React等框架，代码极简，加载速度极快，零依赖
Socket.io Client	浏览器端Socket.io客户端，实现与服务端的长连接，完成消息收发、状态同步
Fetch API	原生HTTP请求接口，实现账号注册登录、文件上传、头像更换、文件下载等HTTP请求
FileReader API	本地文件读取接口，实现图片选择后的本地预览，无需上传即可查看图片内容

六、项目目录结构详解

项目整体采用模块化目录设计，服务端、移动端、Web前端完全分离，新增全平台部署脚本，便于后续维护与二次开发，完整目录结构与作用说明如下：

lan-chat-system/
├── server/                 # 服务端核心目录（Node.js） 
│   ├── server.js          # 服务端主入口文件，包含HTTP服务、Socket.io逻辑、账号体系、文件上传接口全部核心代码 
│   ├── package.json       # Node.js项目依赖配置文件，包含所有依赖库与启动脚本 
│   ├── deploy.js          # 跨平台一键部署脚本核心逻辑
│   ├── public/            # Web前端静态资源托管目录 
│   │   ├── index.html     # Web前端主页面，包含登录/注册/聊天/管理员面板完整HTML结构 
│   │   ├── css/           # 样式文件目录，包含主样式、响应式样式、深色模式样式 
│   │   └── js/            # 前端逻辑脚本目录，包含账号认证、Socket.io通信、消息处理、文件上传等全部JS逻辑 
│   ├── uploads/           # 文件上传目录，服务端自动生成，存储用户上传的所有文件，按日期分类 
│   ├── xo/                # 头像资源目录，存储系统默认头像与用户上传的自定义头像 
│   └── data/              # 数据库持久化目录，服务端自动生成，存储用户信息、历史消息数据
│
├── mobile-app/            # 移动端应用目录（Flutter） 
│   ├── lib/               # Flutter核心源码目录，90%以上的业务代码在此处 
│   │   ├── main.dart      # 应用主入口文件，APP初始化、全局状态管理、路由配置、登录状态校验 
│   │   ├── models/        # 数据模型目录，定义消息模型、用户模型、文件模型等数据结构 
│   │   ├── screens/       # 页面目录，包含登录/注册、聊天页面、连接页面、个人设置、管理员面板等全部UI页面 
│   │   ├── services/      # 服务层目录，封装账号认证、Socket.io通信、网络请求、文件操作、权限处理等核心逻辑 
│   │   ├── theme/         # 主题目录，定义APP全局配色、字体、样式规范，实现主题统一管理 
│   │   └── widgets/       # 组件目录，封装消息气泡、输入框、用户列表项、文件卡片、Emoji选择器等可复用UI组件 
│   ├── android/           # Android原生配置目录，包含AndroidManifest.xml、应用图标、权限配置、原生代码 
│   ├── ios/               # iOS原生配置目录（预留，后续可快速适配iOS平台） 
│   └── pubspec.yaml       # Flutter项目配置文件，包含依赖库、应用名称、版本号、资源配置等 
│
├── start.bat              # Windows一键启动脚本，双击即可完成环境校验、依赖安装、服务启动
├── start.ps1              # Windows PowerShell部署脚本，兼容PowerShell环境，支持后台运行
├── start.sh               # Linux/macOS前台启动脚本，一键完成环境校验、依赖安装、服务启动
├── start-background.sh    # Linux后台常驻启动脚本，基于screen实现SSH断开后服务仍正常运行
├── status.sh              # Linux服务状态查看脚本，一键查看后台服务运行状态与日志
├── stop.sh                # Linux后台服务停止脚本，一键停止后台运行的服务
├── .gitignore             # Git忽略文件配置，排除node_modules、构建产物、临时文件等 
├── LICENSE                # 项目开源许可证，采用MIT开源协议 
└── README.md              # 项目说明文档，包含快速开始、功能介绍、部署教程等核心信息

七、超详细部署与使用教程

v1.2.0版本大幅降低了部署门槛，全平台支持一键启动，零基础也能快速完成部署，以下是完整的教程：

7.1 前置条件

服务端设备需安装 Node.js v16.0及以上版本（Node.js官网可直接下载安装，一路下一步即可）
所有客户端设备与服务端设备，必须连接同一局域网/同一WiFi
服务端设备防火墙需开放3000端口（默认端口，可自行修改）

7.2 Windows 一键部署（新手首选，零命令操作）

前往项目Gitee仓库，下载v1.2.0最新版本的ZIP压缩包，解压到本地任意目录
进入解压后的项目根目录，找到 start.bat 文件
双击运行 start.bat 脚本，脚本会自动完成环境校验、依赖安装、数据库初始化、服务启动全流程
启动成功后，终端会显示服务运行信息，同时自动打开默认浏览器进入Web端登录界面

局域网内其他设备，只需在浏览器输入服务端终端显示的局域网IP+端口号（例如 http://192.168.1.100:3000），即可访问使用。

7.3 Linux/macOS 部署教程

7.3.1 前台启动（调试/临时使用）

# 1. 克隆项目仓库
git clone https://gitee.com/xmosai/lan-chat-system.git

# 2. 进入项目根目录
cd lan-chat-system

# 3. 给脚本添加执行权限
chmod +x *.sh

# 4. 一键启动服务
./start.sh

7.3.2 后台常驻启动（服务器/NAS长期部署）

基于screen终端复用器实现后台常驻，SSH断开连接后服务仍正常运行，适合长期部署使用：

# 1. 克隆项目并进入目录，添加脚本执行权限（同上）
git clone https://gitee.com/xmosai/lan-chat-system.git
cd lan-chat-system
chmod +x *.sh

# 2. 后台常驻启动
./start-background.sh

# 配套运维命令
./status.sh          # 查看服务运行状态
./stop.sh            # 停止后台服务
tail -f server/server.log  # 查看服务实时日志

7.4 客户端使用教程

Web端使用（Windows/macOS/Linux通用）

确保设备与服务端处于同一局域网（连接同一个WiFi/同一个交换机）
打开任意现代浏览器（Chrome、Edge、Firefox、Safari等）
在地址栏输入服务端的局域网IP+端口号，例如： http://192.168.1.100:3000
注册账号并登录，即可进入聊天界面开始使用

Android移动端使用

从Gitee仓库的Releases页面下载v1.2.0最新版本的APK安装包，安装到Android手机中
确保手机与服务端连接同一个WiFi，处于同一局域网
打开APP，APP会自动扫描局域网内的可用服务，扫描到后点击即可连接
若自动扫描失败，可在APP内手动输入服务端的IP地址与端口号，点击连接即可
注册账号并登录，即可开始使用，首次打开APP时，根据提示授予网络、存储、文件访问权限，保证功能正常使用

7.5 从源码构建移动端APK

如果你想基于源码自定义修改，自行构建APK，可按照以下步骤操作：

# 1. 安装Flutter SDK，要求版本3.0及以上，配置好Flutter环境变量与Android SDK
# 2. 进入项目的移动端目录
cd mobile-app

# 3. 安装Flutter依赖
flutter pub get

# 4. 构建release版本APK
flutter build apk --release

构建完成后，终端会显示APK文件的输出路径，安装到手机即可使用。

八、常见问题与解决方案

Q：服务端启动成功，其他设备无法访问？
A：优先检查防火墙是否开放了对应端口，其次确认所有设备处于同一局域网，没有开启AP隔离、访客网络等限制局域网设备互通的功能。
Q：移动端APP扫描不到服务端？
A：确认手机与服务端在同一WiFi，关闭路由器的AP隔离；可尝试在APP中手动输入IP地址连接；检查服务端设备的防火墙是否拦截了UDP广播包。
Q：文件上传失败，提示大小超限？
A：服务端默认限制了单文件最大上传大小，可在 server.js 中修改Multer的配置，调整文件大小限制。
Q：服务端启动提示端口被占用？
A：修改 server.js 中的端口号，更换为未被占用的端口，或者关闭占用3000端口的其他程序。
Q：Android 13+设备无法选择文件？
A：在APP的系统权限设置中，开启存储与文件访问权限，Android 13及以上版本需要单独申请媒体文件与文件管理权限。
Q：Linux后台启动后，无法访问服务？
A：执行 ./status.sh 查看服务是否正常运行，检查防火墙是否开放了对应端口，确认screen会话是否正常存活。
Q：忘记管理员密码怎么办？
A：停止服务后，删除 server/data/ 目录下的用户数据库文件，重启服务后会自动重新初始化默认管理员账号。

九、开源协议与项目地址

项目已完整开源至Gitee，欢迎大家Star、Fork，也欢迎提交PR一起完善项目，如果你在使用过程中遇到问题，可在仓库的Issues中提交反馈，我会及时回复。

🔗 项目开源仓库地址： https://gitee.com/xmosai/lan-chat-system

📢 作者：夏木 · 本文首发于 https://xmosai.com

开发这个项目的初衷，是为了解决自己在内网环境下的跨设备沟通与文件传输痛点，也希望能给有同样需求的朋友提供一个开箱即用的解决方案。v1.2.0版本的更新，离不开各位朋友的反馈与建议，后续我也会持续维护更新，迭代更多实用功能，感谢大家的支持与关注。

—— 夏木 · 转载请注明出处与项目地址 ——

作者：夏木

链接：https://xmosai.com/archives/121

文章版权归作者所有，未经允许请勿转载。