LAN Chat System 局域网全平台实时通信系统
开源项目详解：LAN Chat System 局域网全平台实时通信系统
大家好，我是夏木。今天给大家带来我最新开源的项目——LAN Chat System 局域网通信系统。这是一套专为局域网环境打造的、开箱即用的全平台实时通信解决方案，彻底解决了内网环境下跨设备消息互通、文件传输的痛点，无需公网服务器、无需复杂配置，一键部署即可实现多终端互联互通。本文将从项目初衷、系统架构、技术选型、功能实现、部署教程等多个维度，为大家完整拆解这个项目。
一、项目开发背景与核心解决的痛点
在日常办公、家庭内网、机房运维、展会现场等无公网/公网受限的场景中，我们经常会遇到这些问题：
- 手机和电脑互传文件，需要借助微信、QQ等公网工具，不仅限速严重，还会消耗流量，大文件传输体验极差
- 内网多设备之间的临时消息沟通，没有轻量化的工具，需要搭建复杂的企业通信系统
- 涉密/内网环境不允许数据上公网，传统通信工具无法使用
- 现有局域网工具大多仅支持单平台，无法实现Android、Windows、macOS、Linux多端互通
基于以上痛点，我开发了这套LAN Chat System，它完全运行在局域网内，数据全程不经过公网，兼顾了安全性、易用性和跨平台兼容性，同时做到了轻量化部署，零基础也能快速上手。
二、系统核心功能特性
本项目覆盖了局域网通信的全场景需求，核心功能如下：
- 实时双向消息通信：基于WebSocket的低延迟消息收发，支持文本消息实时推送，附带精准时间戳与发送者信息，全端消息实时同步
- 全类型文件传输能力：支持任意格式、任意大小的文件上传与下载，图片、视频、文档、压缩包均可完美支持；图片类文件支持在线预览，无需下载即可查看
- 局域网自动服务器发现：移动端无需手动输入服务器IP地址，APP启动后自动扫描局域网内的可用服务节点，一键完成连接，零基础用户也能快速上手
- 统一化用户头像系统：由服务端集中管理用户头像资源，支持用户自主更换头像，更换后全平台实时同步，所有客户端显示一致的头像信息
- 在线用户实时管理：实时展示当前在线的所有用户列表与在线人数，用户上下线实时广播通知，基于IP地址实现用户身份唯一识别
- 微信风格现代化UI：Web端与移动端均采用了用户熟悉的IM类软件交互逻辑，UI设计贴合主流使用习惯，无需学习成本即可快速上手
- 多终端全平台兼容：一套服务端，同时支持Web浏览器、Android移动端两大客户端，Windows、macOS、Linux设备可直接通过浏览器接入，无需安装额外软件
三、系统架构与数据流设计
本系统采用经典的中心化C/S（客户端-服务端）架构，所有节点均处于同一局域网内，通过WiFi/有线网络完成数据交互，无任何公网依赖，整体架构如下：
┌─────────────────────────────────────────────────────────────────────┐
│ 局域网通信系统 整体架构 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ PC Web 客户端 │ │ Node.js 服务端 │ │ 移动端APP │ │
│ │ (浏览器原生) │◄────►│ 消息/文件中枢 │◄────►│ (Flutter) │ │
│ └────────────────┘ └────────────────┘ └──────────────┘ │
│ │ │ │ │
│ └────────────────────────┼────────────────────────┘ │
│ 局域网WiFi/有线网络 │
└─────────────────────────────────────────────────────────────────────┘3.1 核心数据流设计
- 消息通信流：客户端通过Socket.io与服务端建立长连接，发送消息时将消息体+发送者信息+时间戳推送到服务端，服务端校验后通过广播机制推送给所有在线客户端，实现全端消息同步
- 文件传输流：客户端通过HTTP POST协议将文件分片上传至服务端，服务端通过Multer中间件完成文件接收、存储、元信息记录，生成唯一可访问的下载链接，再通过消息广播将文件信息推送给所有客户端
- 用户状态流：客户端连接/断开时，服务端自动触发上下线事件，更新在线用户列表，并将最新的用户状态广播给所有在线节点，实现用户在线状态的实时同步
- 服务发现流：服务端启动后，通过UDP广播在局域网内周期性发布自身的IP地址与端口信息；移动端APP启动后，监听对应端口的广播包，自动解析服务端地址，完成自动连接，无需用户手动输入IP
四、全栈技术选型与实现细节
本项目在技术选型上，兼顾了开发效率、运行性能、跨平台兼容性与轻量化部署要求，全栈技术栈与实现细节如下：
4.1 服务端技术栈
服务端基于Node.js生态开发，核心目标是轻量化、高并发、易部署，单文件即可完成核心服务的启动，具体技术选型如下：
| 技术框架/库 | 版本要求 | 核心作用与实现细节 |
|---|---|---|
| Node.js | v16.0 及以上 | 服务端运行时，基于事件驱动的非阻塞I/O模型，完美适配WebSocket长连接场景，单进程即可支撑数百个客户端同时在线 |
| Express | 最新稳定版 | 轻量级Web服务框架，负责HTTP服务搭建、静态资源托管、文件上传接口、RESTful API开发，代码极简，性能优异 |
| Socket.io | 最新稳定版 | 核心双向通信库，基于WebSocket封装，兼容低版本HTTP协议，自带断线重连、房间广播、消息确认机制，是实现实时消息的核心 |
| Multer | 最新稳定版 | Express生态的文件上传中间件，负责处理客户端的multipart/form-data文件请求，支持文件大小限制、扩展名过滤、自定义存储路径、文件名重命名防冲突 |
| CORS | 最新稳定版 | 跨域资源共享中间件，解决Web端、移动端与服务端的跨域请求问题，适配不同终端的访问需求 |
| Node-os-utils | 最新稳定版 | 系统信息获取库，用于获取服务端所在设备的局域网IP地址，实现服务启动时的IP自动展示与广播 |
服务端核心实现亮点：
- 单入口文件设计，核心逻辑全部集成在
server.js中，无需数据库，无复杂配置，开箱即用 - 文件自动归档机制，上传的文件按日期自动分类存储在
uploads目录，便于管理与清理 - 内置静态资源托管，Web前端代码全部托管在服务端的
public目录，服务启动后即可通过浏览器直接访问 - 头像资源统一管理，内置默认头像库，用户更换的头像统一存储在
xo目录，全端同步访问 - 基于IP的用户身份识别，无需注册登录，同一局域网内的设备通过IP地址即可完成身份标识，自动分配唯一用户名
4.2 移动端技术栈
移动端基于Google Flutter跨平台框架开发，一套代码即可编译生成Android APK，未来可快速适配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全版本的文件系统，实现任意类型文件的选择与上传 |
移动端核心实现亮点：
- 全自动服务发现，无需手动输入IP地址，APP启动后自动扫描局域网内的可用服务，一键连接
- 微信风格的聊天界面，包含消息列表、输入框、图片预览、文件下载等完整功能，贴合用户使用习惯
- 断线自动重连机制，网络切换、锁屏唤醒后自动重新连接服务端，无需用户手动操作
- 后台保活优化，针对Android系统做了后台保活适配，保证APP在后台时也能正常接收消息通知
- 全文件类型支持，可选择手机内任意格式的文件进行上传，支持大文件分片上传，避免内存溢出
4.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前端核心实现亮点：
- 零依赖、零编译，服务端启动后，任意设备只要在同一局域网，通过浏览器访问IP+端口即可使用，无需安装任何软件
- 全响应式设计，完美适配PC、平板、手机浏览器，不同尺寸设备均有优秀的显示效果
- 图片在线预览，支持图片消息的放大查看、缩放、下载，无需额外的预览软件
- 消息本地缓存，浏览器本地存储历史消息，刷新页面后不会丢失历史记录
- 键盘快捷发送，PC端支持Enter键发送消息，Ctrl+Enter换行，贴合办公场景使用习惯
五、项目目录结构详解
项目整体采用模块化目录设计，服务端、移动端、Web前端完全分离，便于后续维护与二次开发，完整目录结构与作用说明如下：
lan-chat-system/
├── server/ # 服务端核心目录（Node.js）
│ ├── server.js # 服务端主入口文件，包含HTTP服务、Socket.io逻辑、文件上传接口全部核心代码
│ ├── package.json # Node.js项目依赖配置文件，包含所有依赖库与启动脚本
│ ├── public/ # Web前端静态资源托管目录
│ │ ├── index.html # Web前端主页面，聊天界面的完整HTML结构
│ │ ├── css/ # 样式文件目录，包含主样式、响应式样式、深色模式样式
│ │ └── js/ # 前端逻辑脚本目录，包含Socket.io通信、消息处理、文件上传等全部JS逻辑
│ ├── uploads/ # 文件上传目录，服务端自动生成，存储用户上传的所有文件，按日期分类
│ └── xo/ # 头像资源目录，存储系统默认头像与用户上传的自定义头像
│
├── mobile-app/ # 移动端应用目录（Flutter）
│ ├── lib/ # Flutter核心源码目录，90%以上的业务代码在此处
│ │ ├── main.dart # 应用主入口文件，APP初始化、全局状态管理、路由配置
│ │ ├── models/ # 数据模型目录，定义消息模型、用户模型、文件模型等数据结构
│ │ ├── screens/ # 页面目录，包含聊天页面、连接页面、设置页面等全部UI页面
│ │ ├── services/ # 服务层目录，封装Socket.io通信、网络请求、文件操作、权限处理等核心逻辑
│ │ ├── theme/ # 主题目录，定义APP全局配色、字体、样式规范，实现主题统一管理
│ │ └── widgets/ # 组件目录，封装消息气泡、输入框、用户列表项、文件卡片等可复用UI组件
│ ├── android/ # Android原生配置目录，包含AndroidManifest.xml、应用图标、权限配置、原生代码
│ ├── ios/ # iOS原生配置目录（预留，后续可快速适配iOS平台）
│ └── pubspec.yaml # Flutter项目配置文件，包含依赖库、应用名称、版本号、资源配置等
│
├── .gitignore # Git忽略文件配置，排除node_modules、构建产物、临时文件等
├── LICENSE # 项目开源许可证，采用MIT开源协议
└── README.md # 项目说明文档，包含快速开始、功能介绍、部署教程等核心信息六、完整部署与使用教程
6.1 服务端部署（Windows/Linux/macOS通用）
第一步：环境准备
首先在需要部署服务端的设备上安装Node.js环境，要求版本为v16.0及以上，下载地址：Node.js官方网站，安装完成后，在终端执行以下命令验证安装是否成功：
# 验证Node.js版本
node -v
# 验证npm版本
npm -v第二步：下载项目源码
通过Git克隆项目源码，或者直接从Gitee仓库下载ZIP压缩包到本地：
# Git克隆项目
git clone https://gitee.com/xmosai/lan-chat-system.git
# 进入项目根目录
cd lan-chat-system第三步：安装服务端依赖
进入服务端目录，执行npm命令安装所有依赖库：
# 进入服务端目录
cd server
# 安装项目依赖
npm install第四步：启动服务端
依赖安装完成后，执行启动命令即可一键启动服务：
# 启动服务端
npm start启动成功后，终端会显示服务运行信息，包括服务访问地址、局域网IP地址、端口号，同时会自动打开默认浏览器进入Web聊天界面。服务默认运行在3000端口，如需修改端口，可编辑server.js文件中的端口配置项：
// 服务端口配置，可修改为任意未被占用的端口
const port = 3000;第五步：防火墙与网络配置
为了保证其他设备能正常访问服务，需要在部署服务端的设备上开放对应端口的防火墙权限：
- Windows系统：在Windows Defender防火墙中，添加3000端口的入站规则，允许局域网访问
- Linux系统：通过ufw/iptables开放3000端口，示例：
sudo ufw allow 3000 - macOS系统：在系统设置-网络-防火墙中，允许Node.js接收传入连接
6.2 客户端使用教程
Web端使用（Windows/macOS/Linux通用）
- 确保设备与服务端处于同一局域网（连接同一个WiFi/同一个交换机）
- 打开任意现代浏览器（Chrome、Edge、Firefox、Safari等）
- 在地址栏输入服务端显示的局域网IP+端口号，例如：
http://192.168.1.100:3000 - 回车即可进入聊天界面，自动分配用户名，无需注册登录，直接开始使用
Android移动端使用
- 从Gitee仓库的Releases页面下载最新的APK安装包，安装到Android手机中
- 确保手机与服务端连接同一个WiFi，处于同一局域网
- 打开APP，APP会自动扫描局域网内的可用服务，扫描到后点击即可连接
- 若自动扫描失败，可在APP内手动输入服务端的IP地址与端口号，点击连接即可
- 首次打开APP时，根据提示授予网络、存储、文件访问权限，保证功能正常使用
6.3 从源码构建移动端APK
如果你想基于源码自定义修改，自行构建APK，可按照以下步骤操作：
- 安装Flutter SDK，要求版本3.0及以上，配置好Flutter环境变量与Android SDK
- 进入项目的移动端目录：
cd mobile-app - 执行命令安装Flutter依赖：
flutter pub get - 执行构建命令，生成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及以上版本需要单独申请媒体文件与文件管理权限。
八、开源协议与项目地址
本项目采用 MIT 开源协议，你可以自由地使用、修改、分发本项目的代码，无论是个人非商用还是商业使用，均无额外限制，仅需保留原作者的版权声明即可。
项目已完整开源至Gitee，欢迎大家Star、Fork，也欢迎提交PR一起完善项目，如果你在使用过程中遇到问题，可在仓库的Issues中提交反馈，我会及时回复。
🔗 项目开源仓库地址：https://gitee.com/xmosai/lan-chat-system
作者：夏木 (XiaMu)
本文首发于我的个人网站，转载请注明出处与项目开源地址。
阅读剩余
版权声明：
作者：夏木
链接：https://xmosai.com/archives/121
文章版权归作者所有，未经允许请勿转载。
THE END
