# LANChat

**Repository Path**: shiter007/lanchat

## Basic Information

- **Project Name**: LANChat
- **Description**: 局域网内，你所想要的小工具。by cc&codex&trae&qoder&codebuddy,and me.
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-01
- **Last Updated**: 2025-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LANChat - 局域网聊天工具

<div align="center">

![LANChat Logo](https://via.placeholder.com/200x200?text=LANChat)

**一款强大的局域网即时通讯工具**

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0-brightgreen.svg)](https://nodejs.org/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/your-repo/LANChat)

[功能特性](#-功能特性) • [快速开始](#-快速开始) • [文档](#-文档) • [贡献](#-贡献) • [许可证](#-许可证)

</div>

---

## 📖 目录

- [项目简介](#-项目简介)
- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [系统架构](#-系统架构)
- [快速开始](#-快速开始)
- [配置说明](#-配置说明)
- [使用指南](#-使用指南)
- [项目结构](#-项目结构)
- [开发指南](#-开发指南)
- [测试](#-测试)
- [部署](#-部署)
- [文档](#-文档)
- [常见问题](#-常见问题)
- [更新日志](#-更新日志)
- [贡献](#-贡献)
- [许可证](#-许可证)
- [联系方式](#-联系方式)

---

## 🎯 项目简介

LANChat 是一款专为局域网环境设计的轻量级即时通讯工具，提供安全、高效的内网通讯解决方案。无需互联网连接，支持文字聊天、大文件传输（最大100GB）和高质量音视频通话。

### 适用场景

- 🏢 **企业内网通讯**: 保护敏感信息，避免数据外泄
- 🚀 **快速文件分享**: 局域网内高速传输大文件
- 🔒 **离线环境**: 无需互联网，完全私密的通讯方案
- 👥 **团队协作**: 小型团队的即时沟通工具

---

## ✨ 功能特性

### 核心功能

- 💬 **实时消息通讯**
  - 支持文字消息和表情符号
  - 消息实时送达，零延迟
  - 消息历史记录，永久保存
  - 消息去重，防止重复显示
  - 基于 messageId 的唯一性保证

- 📁 **大文件传输**
  - 支持最大 100GB 文件传输
  - 实时进度显示
  - 支持所有文件类型
  - XMLHttpRequest 实时进度跟踪

- 📞 **音视频通话**
  - 高清视频通话
  - 低延迟语音通话
  - 基于 WebRTC P2P 技术
  - 静音和视频开关控制
  - 自动 ICE 候选交换

- 🔍 **自动设备发现**
  - mDNS 自动发现局域网设备
  - UDP 广播备用方案
  - 无需手动配置 IP
  - 3次重试机制，确保连接成功

- 👥 **在线状态管理**
  - 实时显示用户在线状态
  - 在线/离开/离线三种状态
  - 自动心跳检测（30秒周期）
  - 超时断开保护（60秒超时）

### 安全与性能

- 🔒 **安全特性**
  - Electron 安全沙箱（contextIsolation）
  - 消息大小限制（防止恶意攻击）
  - 消息类型白名单验证
  - 文件路径遍历防护
  - 输入验证和消毒

- ⚡ **性能优化**
  - 数据库索引优化
  - 消息去重机制（基于 messageId）
  - 内存泄漏修复
  - WebSocket 连接池管理
  - 事件监听器自动清理

- 📊 **监控与日志**
  - 分级日志系统（error/warn/info/debug）
  - 自动日志轮转（保留7天）
  - 文件和控制台双输出
  - 性能监控指标

### 用户体验

- 🎨 **现代化界面**
  - 简洁直观的 UI 设计
  - 响应式布局
  - 加载状态指示器
  - 友好的错误提示（5秒自动隐藏）
  - 多级错误提示（error/warning/info/success）

- 🌈 **多平台支持**
  - Windows 10/11
  - macOS 10.14+
  - Linux (Ubuntu 18.04+)

---

## 🛠 技术栈

### 后端技术

- **运行环境**: Node.js v14+
- **Web 框架**: Express.js
- **实时通讯**: WebSocket (ws)
- **数据库**: SQLite (better-sqlite3)
- **文件上传**: Multer
- **网络发现**: mDNS (multicast-dns), dgram
- **安全**: Compression, CORS
- **日志**: 自定义 Logger 系统

### 前端技术

- **框架**: React 18
- **桌面框架**: Electron
- **实时通讯**: WebSocket
- **音视频**: WebRTC
- **UI 组件**:
  - emoji-picker-react (表情选择器)
  - 自定义 CSS 组件
- **状态管理**: React Hooks
- **唯一ID生成**: uuid v4

### 开发工具

- **包管理器**: npm
- **代码规范**: ESLint, Prettier (可选)
- **版本控制**: Git
- **构建工具**: Webpack (Electron Builder)

---

## 🏗 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      Client Layer                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   React UI   │  │   Electron   │  │  WebSocket   │  │
│  │  Components  │  │  Main/Render │  │    Client    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│           │                 │                 │          │
│           └─────────────────┴─────────────────┘          │
│                             │                             │
└─────────────────────────────┼─────────────────────────────┘
                              │
                   ┌──────────┴──────────┐
                   │   Network (LAN)     │
                   │   - WebSocket       │
                   │   - HTTP/REST       │
                   │   - mDNS/UDP        │
                   └──────────┬──────────┘
                              │
┌─────────────────────────────┼─────────────────────────────┐
│                      Server Layer                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │   Express    │  │  WebSocket   │  │   Network    │   │
│  │   HTTP API   │  │    Server    │  │  Discovery   │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
│           │                 │                 │           │
│           └─────────────────┴─────────────────┘           │
│                             │                             │
│  ┌──────────────────────────┴────────────────────────┐   │
│  │            Business Logic Layer                   │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────┐  │   │
│  │  │   Message    │  │     File     │  │ Signal │  │   │
│  │  │   Handler    │  │   Transfer   │  │ Server │  │   │
│  │  └──────────────┘  └──────────────┘  └────────┘  │   │
│  └───────────────────────────┬───────────────────────┘   │
│                              │                            │
│  ┌───────────────────────────┴───────────────────────┐   │
│  │            Data Layer (SQLite)                    │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │   │
│  │  │ Messages │  │  Files   │  │   Contacts   │   │   │
│  │  └──────────┘  └──────────┘  └──────────────┘   │   │
│  └───────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────┘
```

### 数据流

1. **消息流**: Client → WebSocket → MessageHandler → Database → Broadcast → Clients
2. **文件流**: Client → HTTP Upload → FileTransferHandler → Storage → HTTP Download → Client
3. **信令流**: Client → WebSocket → SignalingServer → Target Client (WebRTC P2P)

---

## 🚀 快速开始

### 前置要求

确保您的系统已安装：
- Node.js (v14.0 或更高版本)
- npm (通常随 Node.js 一起安装)
- Git (用于克隆仓库)

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://github.com/your-repo/LANChat.git
cd LANChat
```

#### 2. 安装服务器端

```bash
cd server
npm install
```

#### 3. 安装客户端

```bash
cd ../client
npm install
```

#### 4. 启动服务器

```bash
cd ../server
npm start
```

您应该看到类似以下的输出：
```
[INFO] LANChat Server started on port 3000
[INFO] WebSocket server listening on port 3001
[INFO] Network discovery started
```

#### 5. 启动客户端

在新的终端窗口中：
```bash
cd client
npm run dev
```

或者打包成桌面应用：
```bash
npm run build
npm run electron
```

#### 6. 开始使用

- 客户端会自动连接到局域网内的服务器
- 在左侧联系人列表选择用户开始聊天
- 享受即时通讯！

---

## ⚙️ 配置说明

### 服务器配置

在 `server/` 目录下创建 `.env` 文件：

```env
# HTTP 服务端口
PORT=3000

# WebSocket 服务端口
WS_PORT=3001

# 日志级别 (error, warn, info, debug)
LOG_LEVEL=info

# 允许的跨域来源 (多个用逗号分隔)
ALLOWED_ORIGINS=*

# 数据库路径 (可选)
DB_PATH=./lanchat.db

# 日志目录 (可选)
LOG_DIR=./logs
```

### 客户端配置

客户端配置主要在 `client/public/electron.js` 中：

```javascript
// 窗口大小
const mainWindow = new BrowserWindow({
  width: 1200,
  height: 800,
  // ...
});

// 安全配置
webPreferences: {
  nodeIntegration: false,
  contextIsolation: true,
  enableRemoteModule: false,
  // ...
}
```

### 防火墙配置

确保以下端口在防火墙中开放：

**Windows**:
```cmd
netsh advfirewall firewall add rule name="LANChat HTTP" dir=in action=allow protocol=TCP localport=3000
netsh advfirewall firewall add rule name="LANChat WS" dir=in action=allow protocol=TCP localport=3001
```

**macOS/Linux**:
```bash
sudo ufw allow 3000/tcp
sudo ufw allow 3001/tcp
```

---

## 📚 使用指南

### 发送消息

1. 在左侧联系人列表选择一个在线用户
2. 在底部输入框输入消息
3. 按 `Enter` 发送，`Shift+Enter` 换行

### 发送文件

1. 点击输入框旁的 📎 图标
2. 选择要发送的文件
3. 等待上传完成
4. 在右侧文件传输面板查看进度

### 发起通话

- **语音通话**: 点击聊天区域顶部的 🎤 图标
- **视频通话**: 点击聊天区域顶部的 📹 图标

### 在线状态说明

- 🟢 **在线**: 30秒内活跃
- 🟠 **离开**: 5分钟内活跃
- ⚫ **离线**: 超过5分钟无活动

详细使用说明请参考 [用户操作手册](USER_MANUAL.md)。

---

## 📂 项目结构

```
LANChat/
├── client/                    # 客户端代码
│   ├── public/                # 静态资源
│   │   ├── electron.js        # Electron 主进程
│   │   ├── preload.js         # Preload 脚本
│   │   └── index.html         # HTML 入口
│   ├── src/                   # React 源码
│   │   ├── components/        # React 组件
│   │   │   ├── ChatArea.js    # 聊天区域
│   │   │   ├── ContactList.js # 联系人列表
│   │   │   ├── FileTransferPanel.js
│   │   │   └── MediaCallPanel.js
│   │   ├── services/          # 业务逻辑
│   │   │   └── ConnectionManager.js
│   │   ├── App.js             # 主应用组件
│   │   └── index.js           # 入口文件
│   └── package.json
│
├── server/                    # 服务器端代码
│   ├── src/                   # 源码目录
│   │   ├── modules/           # 功能模块
│   │   │   ├── DatabaseManager.js      # 数据库管理
│   │   │   ├── MessageHandler.js       # 消息处理
│   │   │   ├── FileTransferHandler.js  # 文件传输
│   │   │   ├── SignalingServer.js      # WebRTC 信令
│   │   │   └── NetworkDiscovery.js     # 网络发现
│   │   ├── utils/             # 工具类
│   │   │   └── Logger.js      # 日志系统
│   │   └── index.js           # 服务器入口
│   ├── logs/                  # 日志目录
│   ├── uploads/               # 文件上传目录
│   ├── lanchat.db             # SQLite 数据库
│   └── package.json
│
├── docs/                      # 文档目录
│   ├── API.md                 # API 文档
│   ├── DEPLOYMENT.md          # 部署指南
│   └── ARCHITECTURE.md        # 架构文档
│
├── .gitignore                 # Git 忽略文件
├── README.md                  # 本文件
├── USER_MANUAL.md             # 用户手册
├── CHANGELOG.md               # 更新日志
├── COMPLETE_FIXES_SUMMARY.md  # 修复总结
└── LICENSE                    # 许可证
```

---

## 👨‍💻 开发指南

### 环境准备

```bash
# 安装依赖
cd server && npm install
cd ../client && npm install

# 启动开发环境
# 终端 1: 启动服务器
cd server && npm run dev

# 终端 2: 启动客户端
cd client && npm run dev
```

### 代码规范

- 使用 ES6+ 语法
- 组件使用函数式组件和 Hooks
- 遵循单一职责原则
- 添加必要的注释

### 调试技巧

**客户端调试**:
```javascript
// 打开开发者工具
// Windows/Linux: Ctrl+Shift+I
// macOS: Cmd+Option+I
```

**服务器调试**:
```bash
# 启用详细日志
LOG_LEVEL=debug npm start

# 查看实时日志
tail -f logs/app-*.log
```

### 添加新功能

1. 在对应的模块目录创建新文件
2. 实现功能逻辑
3. 添加必要的错误处理
4. 编写测试用例（推荐）
5. 更新相关文档

---

## 🧪 测试

### 功能测试清单

- [ ] 消息发送和接收
- [ ] 文件上传和下载
- [ ] 音视频通话
- [ ] 在线状态同步
- [ ] 自动重连
- [ ] 错误处理

### 性能测试

```bash
# 并发用户测试 (计划)
npm run test:load

# 内存泄漏检测 (计划)
npm run test:memory
```

### 安全测试

- XSS 攻击防护测试
- 超大消息测试
- 路径遍历测试
- SQL 注入测试

---

## 🚢 部署

### 生产环境部署

#### 服务器部署

```bash
# 1. 克隆代码到服务器
git clone https://github.com/your-repo/LANChat.git
cd LANChat/server

# 2. 安装依赖
npm install --production

# 3. 配置环境变量
cp .env.example .env
vim .env

# 4. 使用 PM2 部署（推荐）
npm install -g pm2
pm2 start src/index.js --name lanchat-server
pm2 save
pm2 startup
```

#### 客户端打包

```bash
cd client

# 打包 Windows 应用
npm run build:win

# 打包 macOS 应用
npm run build:mac

# 打包 Linux 应用
npm run build:linux
```

### Docker 部署（计划中）

```bash
# 构建镜像
docker build -t lanchat-server ./server

# 运行容器
docker run -d -p 3000:3000 -p 3001:3001 lanchat-server
```

---

## 📖 文档

- [用户操作手册](USER_MANUAL.md) - 详细的使用指南
- [API 文档](docs/API.md) - REST API 和 WebSocket API 说明
- [部署指南](docs/DEPLOYMENT.md) - 生产环境部署详解
- [架构文档](docs/ARCHITECTURE.md) - 系统架构和设计
- [修复总结](COMPLETE_FIXES_SUMMARY.md) - 已完成的修复列表

---

## ❓ 常见问题

### 无法发现其他用户？

检查所有设备是否在同一局域网，防火墙是否开放相应端口。

### 消息发送失败？

确认网络连接正常，对方用户在线，服务器运行正常。

### 文件传输速度慢？

使用有线连接，关闭其他占用带宽的应用，检查网络质量。

### 通话质量差？

确保网络带宽充足（建议 >2Mbps），降低视频质量或使用语音通话。

更多问题请查看 [用户操作手册](USER_MANUAL.md#6-常见问题)。

---

## 📝 更新日志

### v1.1.0 (2025-10-03)

#### 新增功能
- ✨ 用户在线状态显示（在线/离开/离线）
- ✨ 加载状态指示器
- ✨ 错误通知自动隐藏（5秒）
- ✨ 文件传输进度显示

#### 问题修复
- 🐛 修复事件监听器内存泄漏
- 🐛 修复 WebRTC 连接清理问题
- 🐛 修复文件大小限制不一致（100GB）
- 🐛 修复空值引用错误
- 🐛 优化消息去重逻辑

#### 性能优化
- ⚡ 数据库索引优化
- ⚡ 消息 Map 去重提升性能
- ⚡ WebSocket 连接池管理

#### 安全增强
- 🔒 Electron 安全沙箱
- 🔒 消息大小和类型验证
- 🔒 文件路径遍历防护

查看完整的 [更新日志](CHANGELOG.md)。

---

## 🤝 贡献

欢迎贡献代码、报告问题和提出建议！

### 如何贡献

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献者

感谢所有为本项目做出贡献的开发者！

<a href="https://github.com/your-repo/LANChat/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=your-repo/LANChat" />
</a>

### 行为准则

请阅读并遵守我们的 [行为准则](CODE_OF_CONDUCT.md)。

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

```
MIT License

Copyright (c) 2025 LANChat Development Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## 📞 联系方式

- **项目主页**: https://github.com/your-repo/LANChat
- **问题反馈**: https://github.com/your-repo/LANChat/issues
- **讨论区**: https://github.com/your-repo/LANChat/discussions
- **Email**: support@lanchat.example.com

---

## 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=your-repo/LANChat&type=Date)](https://star-history.com/#your-repo/LANChat&Date)

---

## 🙏 致谢

感谢以下开源项目：

- [React](https://reactjs.org/) - UI 框架
- [Electron](https://www.electronjs.org/) - 桌面应用框架
- [Express](https://expressjs.com/) - Web 框架
- [WebRTC](https://webrtc.org/) - 实时通讯技术
- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) - SQLite 数据库

---

<div align="center">

**[⬆ 回到顶部](#lanchat---局域网聊天工具)**

Made with ❤️ by LANChat Development Team

</div>