# 内网聊天软件

**Repository Path**: apache1992/internal-chat-software

## Basic Information

- **Project Name**: 内网聊天软件
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Internal Communication

内网聊 是一个基于 Electron + TypeScript 的局域网即时通讯桌面应用，面向同一局域网设备之间的轻量即时通信场景。

当前版本：0.0.3

## 功能概览

- 局域网自动发现（UDP 广播）
- 点对点消息收发（WebSocket）
- 文本消息 + 文件消息（图片预览）
- 聊天历史持久化（JSONL）
- FTS 倒排索引搜索（基于持久化 token 索引快照）
- 文件消息“拆文件体”存储（附件落盘，历史仅存引用）
- 文件消息支持打开文件/打开所在目录
- 历史联系人常驻列表（在线/离线分组）
- 同 IP 联系人合并，降低重复联系人
- 离线联系人右键删除历史
- 未读红点、托盘闪烁、新消息提示音
- 主进程与渲染进程隔离（Preload 最小 API 暴露）

## 技术栈总览

### 运行时与语言

- Electron 41
- Node.js Runtime（Electron Main/Preload）
- TypeScript 6（主进程与预加载编译）
- 原生 HTML + CSS + JavaScript（渲染层）

### 网络与通信

- node:dgram（UDP 设备发现）
- ws（WebSocket P2P 消息传输）
- Electron IPC（ipcMain/ipcRenderer，进程通信）
- contextBridge（隔离渲染层与 Node 能力）

### 本地存储

- JSONL（chat-history.jsonl）作为主历史存储
- profile.json 存储用户资料
- 设备 ID 文件存储稳定 peerId
- 附件目录 chat-attachments 存储文件消息二进制实体
- FTS 索引快照 chat-history.fts.json 存储倒排索引

### 桌面能力与系统集成

- BrowserWindow（主窗口）
- Tray（系统托盘）
- Menu（上下文菜单）
- shell.openPath / shell.showItemInFolder（打开文件与目录）
- nativeImage（应用/托盘图标）

### 构建与发布

- tsc（TypeScript 编译）
- electron-builder（Windows 打包：NSIS）
- PowerShell 自动化脚本（图标生成、打包、EXE 图标补丁）
- png-to-ico（PNG -> ICO 转换）

## 架构设计

### 进程架构

项目采用 Electron 典型三层进程模型：

1. Main 进程（src/main）
负责窗口管理、托盘、网络通信、历史存储、IPC 处理与系统能力调用。

2. Preload 层（src/preload）
作为安全边界层，仅通过 contextBridge 暴露最小可用 API 给渲染层。

3. Renderer 层（src/renderer）
负责界面渲染、交互行为与状态展示，不直接访问 Node 高危能力。

### 模块分层

- src/main/main.ts：应用启动、窗口/托盘、IPC 注册、路由协调
- src/main/services/DiscoveryService.ts：UDP 设备发现
- src/main/services/MessageService.ts：WebSocket 连接管理与消息收发
- src/main/services/ChatHistoryStore.ts：历史持久化、FTS 索引、附件拆分
- src/main/services/ProfileStore.ts：用户资料持久化
- src/main/services/Logger.ts：结构化日志输出
- src/shared/types.ts：主进程/预加载/渲染层共享协议类型

### 数据与消息流

1. 设备发现流
- DiscoveryService 周期广播本机在线包
- 收到他人广播后更新 Peer 状态
- Main 进程通过 IPC 推送到渲染层刷新联系人列表

2. 消息收发流
- Renderer 调用 Preload API 发送文本/文件
- Main 进程经 MessageService 通过 WebSocket 发送
- 收到消息后落历史并推送给 Renderer 实时展示

3. 历史与搜索流
- 历史主数据写入 chat-history.jsonl
- 启动时加载历史并恢复或重建倒排索引
- 搜索优先命中倒排索引，再做二次匹配过滤

4. 文件消息存储流
- 传输层仍可使用 dataUrl/base64 载荷
- 入库前拆分文件体，落盘至 chat-attachments
- 历史仅保存附件相对路径引用，减小主历史体积

## 安全与稳定性策略

- contextIsolation 开启，nodeIntegration 关闭
- 仅通过 Preload 白名单 API 访问主进程能力
- 附件路径访问做相对路径与目录越界校验
- 单实例锁避免多实例冲突
- 发现协议与消息协议带版本号，便于兼容升级
- 文件与网络异常尽量降级处理，避免主流程中断

## 存储设计

应用运行后会在 Electron userData 目录写入本地数据。

常见 Windows 路径：

- C:/Users/<用户名>/AppData/Roaming/<应用名>
- 可在资源管理器地址栏输入 %APPDATA% 后进入

主要文件与目录：

- device-id.txt：本机稳定设备 ID
- profile.json：本机昵称、头像、主题
- chat-history.jsonl：聊天历史主存储（JSONL）
- chat-history.fts.json：倒排索引快照
- chat-attachments/：文件消息实体存储目录

## IPC 接口概览

以下为主要 IPC 通道能力分类：

- 设备与资料：self:get、profile:get、profile:update、peers:list
- 历史：history:list、history:search、history:delete
- 消息：message:sendText、message:sendFile
- 托盘：tray:setUnreadCount
- 附件：attachment:openFile、attachment:showInFolder
- 交互菜单：context:showOfflinePeerMenu

## 目录结构

```text
src/
  main/
    main.ts
    services/
      ChatHistoryStore.ts
      DiscoveryService.ts
      Logger.ts
      MessageService.ts
      ProfileStore.ts
  preload/
    preload.ts
  shared/
    types.ts
  renderer/
    index.html
    renderer.js
    styles.css
assets/
  icon.ico
  icon-chat-people.png
  icon-chat-people.svg
scripts/
  generate-icon.ps1
  package-win.ps1
  patch-exe-icon.ps1
```

## 环境要求

- Windows 10/11
- Node.js 18+
- npm 9+

## 快速开始

1. 安装依赖

```bash
npm install
```

2. 运行应用（先编译 TypeScript，再启动 Electron）

```bash
npm run start
```

3. 可选：仅执行编译检查

```bash
npx tsc -p tsconfig.json
```

## 打包发布

1. Windows 便携版

```bash
npm run pack:win
```

产物通常包括：

- release/InternalCommunication-<version>/
- release/InternalCommunication-<version>.zip
- release/内网聊-<version>-x64.exe

2. Windows 安装版（NSIS）

```bash
npm run dist:win
```

说明：部分环境可能遇到 winCodeSign 解压符号链接权限问题（Windows 权限策略相关）。

## 主要脚本

- npm run start：编译并启动应用
- npm run pack:win：打包便携版
- npm run dist:win：打包安装版