局域网安全聊天
& 视频通话

1.1 XteVision SecuChat 是什么？

XteVision SecuChat（xtevision-secuchat v1.0.0）是一个轻量级、本地优先、自托管的聊天服务器和单页网页客户端，用于快速局域网消息传输和点对点视频通话。数据存储在 data.json，界面从 public/ 提供，上传文件保存到 uploads/。设计用于最小化配置——无需外部数据库。

1.2 核心功能

• 账户制用户：通过加盐 scrypt 密码哈希进行注册/登录
• 实时在线状态与消息：通过服务器发送事件（SSE）实现
• 联系人：请求/接受工作流和在线状态更新
• 文件上传：附件和头像（有大小限制）保存到 uploads/
• P2P 视频通话：通过 PeerJS + 本地 PeerServer（端口 5009）
• AI 助手：本地或远程模型集成，用于对话聊天、翻译、摘要、嵌入和内容审核；支持可配置的模型选择和流式响应
• 安全性：由服务器设置 CSP 和常见安全头

1.3 目标用户

• 主要：希望无需云端依赖的私有、局域网聊天和视频通话解决方案的团队和组织
• 次要：注重隐私、希望在本地或自托管环境下使用 AI 助手进行聊天、翻译和审核的用户

2.1 高层架构

┌─────────────────────────────────────────────────────────────────┐
│                         浏览器（单页客户端）                       │
│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐  │
│  │ 登录   │ │ 聊天     │ │ 联系人 │ │ 通话    │ │ AI 助手        │  │
│  └────────┘ └──────────┘ └────────┘ └────────┘ └──────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP / SSE
┌──────────────────────────────┴──────────────────────────────────┐
│                    Node.js 服务器（端口 5008）                     │
│  ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐  │
│  │ 认证      │ │ 消息      │ │ 联系人     │ │ AI 代理（可选）      │  │
│  │(scrypt)   │ │(SSE)      │ │(请求/接受) │ │ → 本地/远程 LLM      │  │
│  │           │ │           │ │           │ └────────────────────┘  │
│  └───────────┘ └──────────┘ └──────────┘                          │
│  ┌───────────┐ ┌───────────────────────────────────────────────┐  │
│  │ 上传       │ │ data.json（用户、消息、联系人）                   │  │
│  │ (uploads/  │ │ public/（提供的界面）                           │  │
│  └───────────┘ └───────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ PeerJS 信令
┌──────────────────────────────┴──────────────────────────────────┐
│                    本地 PeerServer（端口 5009）                      │
│  对等之间的 P2P 媒体连接（视频通话）                                 │
└───────────────────────────────────────────────────────────────────┘

2.2 通信流程

1. 前端 → 服务器：认证、消息、联系人、上传的 HTTP 请求；SSE 订阅以获取实时在线状态和消息
2. 服务器 → data.json：所有用户、消息和联系人状态都持久化在单个 JSON 文件里——无需外部数据库
3. 前端 → PeerServer：P2P 视频通话通过本地 PeerServer（端口 5009）信令，然后媒体点对点流动
4. 前端 → AI 后端：聊天、翻译、摘要、嵌入和审核通过 AI 代理发送到本地（Ollama/MLX）或远程模型

2.3 部署模型

XteVision SecuChat 设计用于自托管、局域网优先的运行方式：

• 作为独立的 Node.js 服务器运行在您自己的硬件上
• 对于仅局域网使用，绑定到私有接口即可
• 对于远程访问，放在反向代理（nginx）后面并启用 HTTPS
• 所有聊天数据都保存在您的本地服务器上——无云端依赖

4.1 prerequisites

• Node.js LTS（例如 16+）
• npm 或 yarn
• PeerServer（可选，仅用于 P2P 回退——见 peerjs/）
• 本地 AI 服务（可选，用于 AI 接口）

4.2 安装

安装依赖项，然后可选择安装用于 P2P 回退的 Peer 服务器。

# 1. 安装服务器依赖
npm install

# 2. （可选）安装 Peer 服务器以用于 P2P 回退
cd peerjs
npm install
cd ..

4.3 访问应用程序

http://您的服务器IP:5008

服务器默认运行在端口 5008。从局域网连接。用于 P2P 视频通话的 PeerServer 使用端口 5009。

4.4 启动服务器

# 开发环境
npm run dev        # 若在 package.json 中定义

# 生产环境
NODE_ENV=production npm start
# 或： node server.js

XteVision 从项目根目录下的 config.json 读取运行时设置。在启动服务器之前，根据您的部署值进行编辑。

5.1 关键部分

5.2 常见环境变量

6.1 目录结构

xtevision-secuchat/
├── server.js                 # 主 Express 服务器：路由、SSE、上传、AI 代理
├── config.json               # 运行时配置（server / ai / client）
├── data.json                 # 用户、消息和联系人（手动编辑前先备份）
├── public/                   # 单页界面（作为静态资源提供）
├── uploads/                  # 附件和头像（服务器端强制执行大小限制）
├── peerjs/                   # 可选的本地 PeerServer，用于 P2P 回退
└── package.json              # 依赖项和脚本

6.2 关键文件

7.1 接口概览

7.2 AI 接口

可选——需要配置的 AI 服务。确切参数名和响应格式请参考服务器代码。

8.1 快速指南

• 本地优先：如果有内部/本地 AI 服务（AI_BASE_URL），将优先使用；请求将按配置通过代理发送到该服务，附带模型和密钥。
• 流式传输：设置 AI_STREAM=true 并使用 Accept: text/event-stream 请求，以接收增量 AI token（SSE）。
• 嵌入：使用 /api/ai/embeddings 获取向量表示，用于搜索或聚类；批处理由 AI_BATCH_EMBEDDINGS 控制。
• 隐私：设置 AI_LOCAL_ONLY=true 以阻止将内容转发到外部服务。API 密钥从环境变量读取，不会被记录。

8.2 示例

聊天（非流式）：

curl -s -X POST http://localhost:5008/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"摘要这条消息： ..."}]}

聊天（流式 SSE）：

curl -N -X POST http://localhost:5008/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"messages":[{"role":"user","content":"用一段话介绍 XteVision。"}]}, "model":"gpt-4o-mini"}

嵌入：

curl -s -X POST http://localhost:5008/api/ai/embeddings \
  -H "Content-Type: application/json" \
  -d '{"texts":["你好","世界"]}

9.1 服务器端安全

• 密码哈希：加盐 scrypt——不存储明文密码
• 内容安全策略（CSP）：CSP 和常见安全头都由服务器设置
• 上传限制：服务器端强制执行——过大上传会被拒绝
• 局域网无需认证：服务器设计用于局域网本地使用；远程访问需添加 HTTPS 和反向代理

9.2 AI 隐私

• AI 密钥（AI_API_KEY）保存在服务器环境中，应按机密对待——服务器不会记录密钥。
• 如果 AI_BASE_URL 指向外部服务，将把内容转发到该服务——在注重隐私的部署中启用 AI_LOCAL_ONLY。
• 速率限制（AI_RATE_LIMIT）有助于防止滥用和意外费用。

10.1 服务器与端口

• 问题：端口冲突
• 解决方案：确保 PORT 空闲，或通过环境变量更改它。

10.2 上传

• 问题：上传错误
• 解决方案：检查 uploads/ 目录的写入权限。

10.3 视频通话

• 问题：对等连接失败
• 解决方案：确保 PeerServer 正在运行且可被客户端访问；检查浏览器控制台中的 WebRTC 错误。

10.4 AI 请求

• 问题：AI 请求失败
• 解决方案：验证 AI_BASE_URL、AI_API_KEY 和模型名称；检查速率限制并适当设置 AI_STREAM_TIMEOUT。如果使用了本地 AI 服务，确保它健康且可访问。