一款轻量、现代、可自行部署的 Web 即时通讯应用。
XChat 基于 Node.js、React 和 SQLite 构建，面向个人、小型团队与私有化部署场景。它提供私聊、群组、频道、文件共享、实时同步、离线恢复、Web Push 通知和 Bot 接口；所有业务数据均保存在你自己的服务器上。
XChat 目前不提供端到端加密。服务器管理员可以访问数据库、消息和附件，请根据自己的使用场景评估部署方式。
- 私聊、群组和频道
- 回复、编辑、撤回、转发、收藏、置顶与表情回应
- @提及、已读状态、正在输入和在线状态
- 图片、文件、语音消息与音视频附件预览
- 消息搜索、链接预览和群公告
- WebSocket 实时同步、断线重连与离线 outbox
- Web Push 通知和多设备会话管理
- 邀请注册、成员权限、禁言、封禁与管理审计
- Bot 身份、长轮询和签名 Webhook
- 桌面三栏与移动端单栏布局
- 浅色、深色、跟随系统主题，以及中文和英文界面
| 部分 | 技术 |
|---|---|
| 服务端 | Node.js 22、Fastify 5、ESM |
| Web 客户端 | React 19、TypeScript、Vite 6 |
| 状态与缓存 | TanStack Query、Zustand、Dexie |
| 数据库 | SQLite、WAL、better-sqlite3 |
| 实时通信 | WebSocket |
| 媒体处理 | Sharp、ffmpeg / ffprobe |
XChat 采用单机、单 Node 进程的部署模型，不需要单独运行数据库服务。生产环境建议由 Nginx 负责 HTTPS 和反向代理。
- Node.js 22 或更高版本
- pnpm 10.33.0
- ffmpeg / ffprobe（生成音视频预览时需要）
corepack enable
corepack prepare pnpm@10.33.0 --activate
git clone https://github.com/help660vip/XChat.git
cd XChat
pnpm install --frozen-lockfile
pnpm start打开 http://127.0.0.1:18282/setup 完成首位管理员初始化。
未提供 .env 时，应用会以本地开发配置启动：
- 监听地址：
127.0.0.1:18282 - 数据目录：
./data - 初始化 Token：
xchat-development-setup-token
开发默认值只能用于本机测试，生产模式会拒绝使用该初始化 Token。
pnpm dev该命令会同时启动 Node.js watch 服务和 Vite 开发服务器。
完整配置及说明位于 .env.example。生产环境可先复制一份：
cp .env.example .env最重要的配置项如下：
| 配置项 | 说明 |
|---|---|
HOST |
Node.js 监听地址，生产环境建议保持 127.0.0.1 |
PORT |
服务端口，默认 18282 |
NODE_ENV |
生产环境必须设置为 production |
DATA_DIR |
数据库、附件、预览、秘密和备份目录 |
PUBLIC_ORIGIN |
用户实际访问的 HTTPS 地址，不能带末尾斜线 |
SETUP_TOKEN |
首次创建管理员使用的一次性 Token，生产环境至少 32 个字符 |
REGISTRATION_MODE |
注册方式：open、invite 或 closed |
COOKIE_SECURE |
是否仅通过 HTTPS 发送会话 Cookie，生产环境必须为 true |
ACCESS_TOKEN_TTL_SECONDS |
Access Token 有效期，单位为秒 |
REFRESH_TOKEN_TTL_SECONDS |
Refresh Token 有效期，单位为秒 |
MAX_MESSAGE_CHARS |
单条文本消息允许的最大字符数 |
MAX_IMAGE_BYTES |
单张图片大小上限 |
MAX_FILE_BYTES |
单个普通文件大小上限 |
VIDEO_PREVIEW_ENABLED |
是否生成视频预览 |
FFMPEG_PATH |
ffmpeg 可执行文件的绝对路径 |
FFPROBE_PATH |
ffprobe 可执行文件的绝对路径 |
WEB_PUSH_PUBLIC_KEY |
可选的固定 VAPID 公钥，留空时自动生成 |
WEB_PUSH_PRIVATE_KEY |
与 VAPID 公钥配套的私钥，必须妥善保管 |
EVENT_RETENTION_DAYS |
实时同步事件的保留天数 |
LOG_LEVEL |
Pino 日志级别 |
TRUST_PROXY |
部署在 Nginx 等反向代理后时设置为 true |
生产环境启动前，XChat 会检查 HTTPS、Cookie、公开地址和初始化 Token 等安全配置。配置不符合要求时会直接拒绝启动。
不要将 .env、DATA_DIR、数据库、附件、Token 或备份提交到 Git。
仓库提供了 Debian 11 和 Debian 12 可用的部署示例：
deploy/xchat.service：systemd 服务deploy/nginx-xchat.conf：Nginx HTTPS 与 WebSocket 反向代理deploy/install-node22.sh：Node.js 22 安装脚本
推荐的目录布局：
/opt/xchat # 应用代码，只读
/var/lib/xchat # 数据目录，可写
/etc/xchat/xchat.env # 生产环境配置
部署前至少完成以下检查：
pnpm install --frozen-lockfile
pnpm check然后将 .env.example 复制为 /etc/xchat/xchat.env，修改域名、数据目录和初始化 Token，再安装仓库内的 systemd 与 Nginx 示例配置。
启动后可检查服务状态：
curl --fail http://127.0.0.1:18282/health/live
curl --fail http://127.0.0.1:18282/health/ready预期就绪响应：
{ "status": "ready", "database": "ok" }首次部署完成后，访问 https://你的域名/setup，使用 SETUP_TOKEN 创建管理员。初始化成功后，该接口会永久关闭。
- 同一个数据目录只能由一个 XChat 进程写入。
- 不要将活动中的 SQLite 数据库放在网络文件系统上。
- 公网部署必须使用 HTTPS。
- 反向代理需要正确转发
Host、X-Forwarded-Proto和 WebSocket Upgrade 请求头。 - 调整附件大小限制时，需要同步修改 Nginx 的
client_max_body_size。
更新前先创建备份：
pnpm backup恢复备份必须在 XChat 服务停止后执行：
pnpm restore -- --from /path/to/backup --yes恢复脚本会先检查备份清单和 SQLite 完整性，并保留恢复前的数据目录副本。备份中可能包含消息、附件和 Web Push 私钥，应存放在权限受控、加密且与应用主机隔离的位置。
管理员无法登录时，可以在停止服务后重置密码：
pnpm admin:reset-password -- --username admin重置成功后，该账号已有的设备会话将全部失效。
| 命令 | 用途 |
|---|---|
pnpm start |
启动应用 |
pnpm dev |
启动前后端开发环境 |
pnpm build |
构建 Web 客户端 |
pnpm test |
运行服务端和客户端测试 |
pnpm typecheck |
执行 TypeScript 类型检查 |
pnpm lint |
执行代码与文档约束检查 |
pnpm format:check |
检查代码格式 |
pnpm check |
运行完整质量检查 |
pnpm smoke |
执行真实服务冒烟测试 |
pnpm stats |
查看源码规模统计 |
pnpm backup |
创建在线备份 |
xchat/
├── main.js # 生产入口
├── client/ # React 客户端源码和构建产物
├── server/ # HTTP、领域服务、数据库与实时通信
├── shared/ # 前后端共用协议常量
├── migrations/ # SQLite 数据库迁移
├── scripts/ # 开发、检查、备份和恢复脚本
├── deploy/ # systemd、Nginx 与部署脚本
└── docs/ # API 与扩展文档
运行后还可以通过以下地址获取 OpenAPI 文档：
GET /api/v1/openapi.json
XChat 当前主要面向单机自托管场景，暂不提供：
- 端到端加密
- 音视频通话
- 多节点集群部署
- 分片或断点续传式大文件上传
如果你的场景需要承载大量并发连接或超大规模历史消息，请先进行针对性压测，并评估数据库和实时事件架构的扩展方案。
请不要在公开 Issue 中披露尚未修复的安全漏洞。报告方式、受支持版本和部署安全边界请参阅 SECURITY.md。
XChat 使用 MIT License 开源。