# teahouse

**Repository Path**: tqgl/teahouse

## Basic Information

- **Project Name**: teahouse
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<p><b>简体中文</b> · <a href="README.en.md">English</a></p>

<img src="build/icons/pantry-logo-icon.png" alt="茶话间 Logo" width="120" height="120" />

<h1>茶话间 &nbsp;·&nbsp; Teahouse</h1>

<p><b>不用连外网、不用架服务器，局域网里聊天和传文件</b></p>

<p>
  <a href="https://github.com/skyjt/teahouse/releases/latest">
    <img src="https://img.shields.io/github/v/release/skyjt/teahouse?style=flat-square&label=%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC&color=3D8B6B&logo=github&logoColor=white" alt="最新版本" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/License-GPL--3.0--only-3D8B6B?style=flat-square" alt="GPL-3.0-only" />
  </a>
  <a href="https://github.com/skyjt/teahouse/releases">
    <img src="https://img.shields.io/badge/%E5%B9%B3%E5%8F%B0-Windows%207%2B%20%7C%20Linux%20%7C%20macOS-0366d6?style=flat-square" alt="平台" />
  </a>
  <img src="https://img.shields.io/badge/Electron-22-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron 22" />
</p>

<p>
  <a href="#为什么做这个">为什么做</a>
  &nbsp;·&nbsp;
  <a href="#特性">特性</a>
  &nbsp;·&nbsp;
  <a href="#平台支持">平台支持</a>
  &nbsp;·&nbsp;
  <a href="#安装">安装</a>
  &nbsp;·&nbsp;
  <a href="#使用">使用</a>
  &nbsp;·&nbsp;
  <a href="#工作原理">工作原理</a>
  &nbsp;·&nbsp;
  <a href="#安全性">安全性</a>
  &nbsp;·&nbsp;
  <a href="#参与开发">参与开发</a>
</p>

</div>

---

同一个局域网里，每台电脑启动茶话间，就能自动看见彼此，点开就能发消息、传文件。全程不碰外网、不依赖任何服务器，数据只在内网里走。适合公司内网、隔离网、实验室这类不方便、或者根本不允许连外网的环境。

## 为什么做这个

内网里传个文件、说句话，本该是小事，可挑来挑去没一个顺手的：

- **飞鸽**这类好用的，要花钱；
- **内网通**只有 Windows 版，我们这边还有一批国产 UOS 和 Mac，根本装不上；
- **iptux** 免费又跨平台，可大部分同事打开那个界面，不知道从哪下手。

干脆自己写一个：不要钱、从 Windows 7 到国产 UOS 再到 Mac 都能跑、打开就会用。这就是茶话间。

## 特性

- **打开就用，不用配置** —— UDP 广播自动发现同网段在线的人，节点之间直连，不装服务器、不填地址。
- **聊天** —— 单聊和讨论组，文本、图片、表情、截图粘贴、窗口震动都有；消息带送达状态，对方离线先存着、上线自动补发，能撤回、转发、群里 @ 人；记录存在本地，可导出、换机能迁移。
- **传文件** —— TCP 点对点直传，跑满内网带宽；单文件、整个文件夹、拖进窗口就发，断了能续传，留传输记录。
- **只在内网里跑** —— 不连外网、不上报数据、不自动检查更新，跟联网有关的行为默认全关。
- **撑老机器和国产系统** —— 最低支持 Windows 7 SP1、Debian 10、UOS 20；一套代码，Windows / Linux / macOS 一致体验。

## 平台支持

| 平台 | 支持范围 | 架构 | 安装包 | 真机实测 |
|---|---|---|---|---|
| Windows | 7 SP1 起（含 8 / 8.1 / 10 / 11） | x64 / 32 位（ia32） | NSIS 安装包、便携版 | ✅ Windows 7 x64；32 位构建支持 |
| 统信 UOS（信创） | UOS 20 及以上，深度安装器 | x64 / arm64 | .deb | ✅ UOS 20 x64；arm64 构建支持 |
| macOS | 12（Monterey）起 | Apple Silicon | .dmg、.zip | ✅ macOS 26 |
| Debian / Ubuntu 等 | Debian 10（buster）起 | x64 / arm64 | .deb、AppImage | 构建支持 |

> 「真机实测」这列标 ✅ 的，是真在那台系统上装好、跑通收发的组合，不是只在 CI 里编译过。
>
> 为了同时撑住 Windows 7 和较老的 Linux，整个应用焊死在 **Electron 22**——它是最后一个支持 Win7 的大版本，一套二进制覆盖所有目标平台。这条约束带来的开发红线见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 安装

前往 [**Releases**](https://github.com/skyjt/teahouse/releases) 下载对应平台的安装包。

**Windows** — 根据系统架构选择 x64 或 ia32（32 位）NSIS 安装包，也可直接使用对应便携版。Windows 7 需安装 **SP1**；若启用了代码签名，未打补丁的 Win7 需先安装系统更新 KB4474419。

**Linux** — `.deb` 适用于 Debian / Ubuntu / UOS 等；其他发行版可用 `AppImage`（`chmod +x` 后运行）。

**macOS** — 打开 `.dmg` 拖入「应用程序」。内网分发若未签名 / 公证，首次打开需在「系统设置 → 隐私与安全性」中允许，或执行：

```bash
xattr -dr com.apple.quarantine /Applications/Teahouse.app
```

## 使用

1. 同一局域网内的设备各自启动茶话间，会**自动相互发现**并出现在用户列表中。
2. 点击用户即可开始单聊，或新建讨论组群聊；把文件拖入聊天窗即可发送。
3. **跨网段**时 UDP 广播通常不可达，可在设置中手动添加对端 IP，或指定网段探测；已保存的扫描网段会在在线同事间低频自动分享，也可在主界面左侧点击刷新按钮扫描全部已保存网段并查看进度。
4. 首次运行时操作系统防火墙可能提示放行端口，请允许（默认 UDP / TCP `17878` / `17879`）。

## 工作原理

每个客户端都是对等节点，整个系统**没有服务器**：

```
渲染进程（UI）—— 用户列表 / 聊天窗 / 文件传输列表
   │  仅通过 contextBridge 暴露的 IPC 与主进程通信
主进程
   ├─ 网络层：UDP 发现与心跳、UDP+ACK / TCP 消息通道、TCP 文件传输
   ├─ 存储层：SQLite（消息历史、联系人、传输记录）
   └─ 系统集成：托盘、桌面通知、开机自启
```

| 通道 | 传输方式 | 默认端口 | 用途 |
|---|---|---|---|
| 发现 | UDP 广播 | 17878 | 上线 / 下线广播、在线应答、心跳 |
| 消息 | UDP + ACK 重传，长消息走 TCP | 17878 / 17879 | 文本消息、状态变更 |
| 文件 | TCP 直连 | 17879 | 文件 / 文件夹传输，分块 + 校验 |

协议思路参考 IP Messenger（上线广播 → 各端应答以建立在线列表），但不直接兼容老协议。

## 安全性

- **网络边界** —— 所有通信仅发生在局域网内；应用不访问外网、不上报任何数据、不自动检查更新。
- **最小攻击面** —— 渲染进程只加载本地资源、永不加载远程网页；开启 `contextIsolation` + `sandbox`、关闭 `nodeIntegration`；拦截一切窗口内导航与 `window.open`；严格 CSP；所有来自网络的报文都按不可信输入做白名单校验。
- **文件接收** —— 仅落到用户指定目录，文件名做清洗（防路径穿越），不做覆盖式写入。
- **不做传输层加密** —— 信任内网边界，沿用 ipmsg / iptux 的明文做法。如需机密性，请在受信任的网络中使用。

## 参与开发

想自己编译、改代码，或在本机多开几个实例联调，都看 **[CONTRIBUTING.md](CONTRIBUTING.md)**——源码构建、开发红线、调试方法都在里面。

想读懂代码结构、各模块职责、二次开发从哪下手，看 **[DEVELOPMENT.md](DEVELOPMENT.md)**——项目架构与扩展点都在里面。

完整文档导航与英文版本见 **[docs/README.md](docs/README.md)**。

如遇问题或有功能建议，请在 [Issues](https://github.com/skyjt/teahouse/issues) 提交。

## 参考项目

- [IP Messenger](https://ipmsg.org/) — ipmsg，内网 IM 协议鼻祖
- [iptux](https://github.com/iptux-src/iptux) — Linux 下的 ipmsg 兼容实现
- 飞秋（FeiQ）、内网通 — Windows 平台流行的内网 IM，产品形态参考

## 第三方资源

渲染层的标准表单、搜索与常规操作组件使用 [Naive UI](https://github.com/tusen-ai/naive-ui) 2.43.2（本地构建，MIT）；内置头像与 emoji 兼容渲染使用 [Twemoji](https://github.com/jdecked/twemoji) SVG 图形子集（本地打包，CC-BY 4.0）。完整声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

## License

Copyright © 2026 skyjt。

从 0.37.0 起，茶话间自身的源码与二进制分发采用 [GNU General Public License v3.0 only](LICENSE)（SPDX：`GPL-3.0-only`）。0.36.8 及更早版本已经授予的 MIT 权利继续有效。第三方组件与图形资源仍遵循 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中列出的各自许可证。