Skip to content

111pointer111/mini-chat

BranchesTags

Repository files navigation

Mini-Chat

一款面向个人和小团队的全栈聊天应用，集成了实时私聊、AI 对话、知识库问答和定时推送能力。项目采用前后端分离架构，包含 Web 前端和 Android 原生客户端，适合本地开发、Docker 部署和二次开发。

License Node TypeScript Flutter Dart

功能概览

即时通讯

  • 用户注册、登录、重置密码（支持邮箱、手机号、Google OAuth）
  • 好友搜索、发起申请、接受申请
  • 基于 Socket.io 的实时 1v1 聊天
  • 在线状态感知
  • 图片消息支持

群组

  • 创建/管理群组
  • 群成员管理（owner/admin/member 角色）
  • 群消息实时推送
  • @AI 助手触发群内 AI 回答
  • 群组独立知识库

AI 对话

  • 支持接入 OpenAI 兼容格式的大模型服务
  • 多轮会话管理
  • 流式输出
  • Markdown / 代码块渲染
  • 图片理解（多模态）
  • Agent ReAct 循环（多轮工具调用）
  • MCP 工具集成
  • 管理员可在后台维护 AI Provider

知识库

  • 支持上传本地文档或导入网页链接
  • 文档解析、分块、向量化、RAG 问答
  • 支持将聊天模型和 embedding 模型拆分配置
  • 前端展示上传状态、失败原因和知识库问答来源
  • 群组独立知识库管理

MCP 工具管理

  • 支持 Streamable HTTP 和 SSE 两种传输方式
  • Bearer Token 和自定义 Header 认证
  • 工具发现与缓存
  • 工具测试与执行
  • 与 AI 对话深度集成

定时任务

  • GitHub Trending、每日诗词、每日英语等预设任务
  • 自定义定时推送任务
  • BullMQ + Redis 驱动后台任务
  • 多时区支持
  • 推送历史去重

监控告警

  • 内存滑动窗口指标收集（5 分钟窗口，30 秒清理）
  • HTTP 请求自动采集：状态码、响应延迟、错误率
  • 告警状态机：normal → pending → firing → resolved（防抖动）
  • 通知渠道：前端实时弹窗（Socket.IO）、邮件（SMTP）、控制台
  • 前端监控面板：请求数、错误率、P95 延迟、内存、Socket 连接数
  • 健康检查端点：/health（存活）、/api/ready（依赖检查：MongoDB、Redis、PostgreSQL）

技术栈

层级 技术
Web 前端 React 19, TypeScript 5.9, Vite 7, MUI 7, Zustand 5, TanStack Query 5, Tailwind CSS 4, Socket.io Client, Framer Motion, React Hook Form, React Markdown
Android 客户端 Flutter 3.x, Dart 3.5, Riverpod 2, Dio, Socket.IO Client, GoRouter, Flutter Markdown
后端 Node.js 18+, Express 5, TypeScript 5.9, Socket.io 4, Mongoose 9, BullMQ 5, Helmet, Express Rate Limit
主数据 MongoDB
队列 / 缓存 Redis
知识库向量存储 PostgreSQL + pgvector
AI 集成 OpenAI SDK, LangChain, @modelcontextprotocol/sdk
文档解析 textract, Tesseract.js, Cheerio
监控 自研指标收集器 + 告警状态机 + 邮件/WebSocket 通知
部署 Docker, Docker Compose, Nginx, GitHub Actions

项目结构

mini-chat/
├── .agent/skills/               # AI Agent 技能库
├── .github/workflows/           # CI/CD 自动部署
├── .mcp.json                    # MCP 配置
├── AGENTS.md                    # OpenCode Agent 指令
├── CLAUDE.md                    # Claude Code 指令
├── backend/                     # Express + TypeScript API
│   ├── src/
│   │   ├── controllers/        # 路由控制器
│   │   ├── middleware/          # JWT 认证中间件
│   │   ├── models/             # MongoDB 模型
│   │   ├── routes/             # Express 路由
│   │   ├── services/           # AI、知识库、任务、MCP 等业务逻辑
│   │   ├── socket/             # Socket.io 实时通讯
│   │   ├── workers/            # BullMQ 后台任务入口
│   │   ├── monitoring/         # 指标收集、告警管理、通知渠道
│   │   ├── scripts/            # 初始化脚本
│   │   └── utils/              # PostgreSQL / Redis / schema 工具
│   ├── scripts/                # 种子用户脚本
│   └── Dockerfile
├── frontend/                    # React + Vite 前端
│   ├── src/components/
│   ├── src/layouts/
│   ├── src/pages/
│   ├── src/services/
│   ├── src/store/              # Zustand 状态管理
│   └── Dockerfile
├── mobile/                      # Flutter Android 客户端 (BoltChat)
│   ├── lib/
│   │   ├── core/               # 常量、主题、路由
│   │   ├── data/               # API 层、数据模型、Socket 服务
│   │   ├── providers/          # Riverpod 状态管理
│   │   ├── features/           # 各功能页面
│   │   └── shared/             # 通用组件和工具
│   ├── android/                # Android 原生配置
│   └── pubspec.yaml
├── docs/                        # 路线图和设计文档
├── docker-compose.yml           # 开发环境依赖
├── docker-compose.prod.yml      # 生产环境编排
└── README.md

运行前准备

基础环境

  • Node.js 18+
  • npm 9+
  • Docker / Docker Compose

外部服务

  • MongoDB：主业务数据
  • Redis：任务队列、验证码限流、缓存
  • PostgreSQL + pgvector：知识库文档和向量索引

AI 相关准备

  • 聊天功能需要至少一个可用的 AI Provider
  • 知识库问答额外需要可用的 embedding provider
  • 推荐方案：
    • 聊天：MiniMax / DeepSeek / OpenAI 兼容服务
    • Embedding：DashScope text-embedding-v2

快速开始

1. 克隆项目

git clone https://github.com/111pointer111/mini-chat.git
cd mini-chat

2. 启动本地依赖

开发环境使用 docker-compose.yml 启动 MongoDB、Redis 和 PostgreSQL：

docker compose up -d

默认端口：

  • MongoDB: 27017
  • Redis: 6379
  • PostgreSQL: 5432

3. 配置后端

cd backend
cp .env.example .env
npm install
npm run dev

后端默认运行在 http://localhost:5000。 定时任务需要另开一个终端启动 Worker：

npm run dev:worker

4. 配置前端

cd frontend
npm install
npm run dev

前端默认运行在 http://localhost:5173。

如果 5173 已被占用，可以改端口：

npm run dev -- --port 5174

5. 构建 Android 客户端 (BoltChat)

cd mobile
flutter pub get
flutter run          # 调试模式
flutter build apk    # 构建 Release APK

Android 客户端功能与 Web 前端一致，包括：

  • 实时 1v1 / 群聊
  • AI 对话（流式输出 + Markdown）
  • 定时任务管理
  • 知识库
  • MCP 工具管理

APK 输出路径：mobile/build/app/outputs/flutter-apk/app-release.apk

6. 访问应用

  • Web 前端：http://localhost:5173
  • Android 客户端：安装 APK 后配置服务器地址
  • 后端健康检查：http://localhost:5000/health

环境变量

后端 .env

项目已提供 backend/.env.example 作为开发模板。

关键配置如下：

PORT=5000
MONGODB_URI=mongodb://admin:password@localhost:27017/mini-chat?authSource=admin
JWT_SECRET=replace_me_in_production

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=minichat

AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
AI_EMBEDDING_BASE_URL=
AI_EMBEDDING_API_KEY=
AI_EMBEDDING_MODEL=
AI_EMBEDDING_DIMENSIONS=

ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
ADMIN_EMAIL=admin@minichat.com

ALIYUN_ACCESS_KEY_ID=
ALIYUN_ACCESS_KEY_SECRET=
ALIYUN_SMS_SIGN_NAME=
ALIYUN_SMS_TEMPLATE_CODE=

# 知识库 embedding 批处理大小（可选）
KB_EMBEDDING_BATCH_SIZE=2

# CORS 源（逗号分隔，可选）
CORS_ORIGINS=http://localhost:5173,http://localhost:5174,http://localhost:5175

# 告警邮件接收人（通过 GitHub Secrets 注入，不写在文件里）
# ALERT_EMAIL=admin@example.com
ALERT_MIN_SEVERITY=warning
ALERT_ERROR_RATE_PERCENT=2
ALERT_LATENCY_P95_MS=800
ALERT_MEMORY_MB=350
ENABLE_MONITORING_TEST_ROUTES=false
MONITORING_TEST_TOKEN=

# 运行环境（production 时强制要求 JWT_SECRET）
NODE_ENV=development

AI Provider 配置说明

管理员可在后台维护 AI Provider。当前实现支持：

  • Base URL：聊天模型接口地址
  • 模型名称：聊天模型名
  • Embedding API Key：独立 embedding API Key，留空则复用聊天模型 API Key
  • Embedding Base URL：独立 embedding 接口地址
  • Embedding 模型：embedding 模型名
  • Embedding 维度：可选，适用于 DashScope text-embedding-v4 等需显式维度的模型

如果你使用：

  • MiniMax 负责聊天
  • DashScope 负责知识库 embedding

推荐配置：

  • Chat Base URL：MiniMax OpenAI 兼容地址
  • Chat 模型名称：你当前使用的 MiniMax 模型
  • Embedding API Key：DashScope API Key
  • Embedding Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
  • Embedding 模型：text-embedding-v2
  • Embedding 维度：留空

默认管理员账号

开发环境下，如果数据库中还没有管理员账号，系统会自动初始化：

  • 用户名：admin
  • 密码：admin123

对应逻辑见 backend/src/scripts/initAdmin.ts。

强烈建议在生产环境中通过环境变量显式设置：

  • ADMIN_USERNAME
  • ADMIN_PASSWORD
  • ADMIN_EMAIL

知识库说明

知识库链路包括：

  1. 文档上传或网页导入
  2. 文本提取
  3. 文本分块
  4. 调用 embedding provider 生成向量
  5. 写入 PostgreSQL + pgvector
  6. 提问时检索相关片段，再交给聊天模型生成回答

当前支持情况：

  • 支持的本地文件类型：txt, md, json, csv, pdf, doc/docx, ppt/pptx, xls/xlsx, 常见图片
  • 纯文本文件优先直接读取
  • PDF / Office 文档依赖系统解析组件
  • 图片走 OCR

如果只配置聊天模型，没有配置 embedding 能力，知识库上传会在向量化阶段失败。

生产环境部署

1. 准备环境变量

复制模板：

cp .env.production.example .env.production

按需填写：

  • DOCKERHUB_USERNAME
  • JWT_SECRET
  • MONGO_USER / MONGO_PASSWORD
  • POSTGRES_*
  • AI_*
  • ADMIN_*

2. 构建并推送镜像

# 后端
cd backend
docker build -t your_dockerhub_username/minichat-backend:latest .
docker push your_dockerhub_username/minichat-backend:latest

# 前端
cd ../frontend
docker build -t your_dockerhub_username/minichat-frontend:latest .
docker push your_dockerhub_username/minichat-frontend:latest

3. 配置 GitHub Secrets

push 到 main 分支会自动触发 CI（类型检查）和部署（构建镜像 + SSH 部署）。

需要在 repo → Settings → Secrets → Actions 中配置：

Secret 说明
DOCKERHUB_USERNAME Docker Hub 用户名
DOCKERHUB_TOKEN Docker Hub Access Token
SERVER_HOST 服务器 IP / 域名
SERVER_USER SSH 用户名
SERVER_SSH_KEY SSH 私钥
JWT_SECRET JWT 签名密钥
MONGO_USER / MONGO_PASSWORD MongoDB 凭据
ALIYUN_SMTP_PASS 阿里云 SMTP 密码
ALERT_EMAIL 告警邮件接收人
AI_BASE_URL / AI_API_KEY / AI_MODEL AI Provider 配置
ALIYUN_* 短信服务配置（可选）

4. 使用生产编排启动

docker compose -f docker-compose.prod.yml --env-file .env.production up -d

生产环境编排包括：

  • MongoDB
  • Redis
  • PostgreSQL + pgvector
  • 后端 API
  • Nginx 托管的前端

API 概览

以下仅列出主要路由，完整逻辑请参考 backend/src/routes/。

认证

  • POST /api/auth/register
  • POST /api/auth/login
  • GET /api/auth/me
  • POST /api/auth/send-code
  • POST /api/auth/register-phone
  • POST /api/auth/login-phone
  • POST /api/auth/bind-phone
  • POST /api/auth/reset-password-phone

用户 / 好友 / 消息

  • GET /api/users/search
  • GET /api/friends
  • POST /api/friends/request
  • GET /api/friends/requests/pending
  • PUT /api/friends/request/:requestId/accept
  • GET /api/messages/:userId

群组

  • GET /api/groups
  • POST /api/groups
  • GET /api/groups/:groupId/members
  • POST /api/groups/:groupId/members
  • GET /api/groups/:groupId/messages
  • GET /api/groups/:groupId/kb/documents
  • POST /api/groups/:groupId/kb/documents/upload
  • POST /api/groups/:groupId/kb/documents/url
  • DELETE /api/groups/:groupId/kb/documents/:documentId

AI 对话

  • POST /api/ai-chat
  • GET /api/ai-chat/conversations
  • POST /api/ai-chat/conversations
  • PUT /api/ai-chat/conversations/:conversationId
  • DELETE /api/ai-chat/conversations/:conversationId

AI Provider

  • GET /api/ai-providers
  • GET /api/ai-providers/user
  • PUT /api/ai-providers/user
  • GET /api/ai-providers/admin
  • POST /api/ai-providers/admin

定时任务

  • GET /api/scheduled-tasks
  • GET /api/scheduled-tasks/conversations
  • POST /api/scheduled-tasks/custom
  • PUT /api/scheduled-tasks/custom/:taskId
  • DELETE /api/scheduled-tasks/custom/:taskId

知识库

  • GET /api/kb/documents
  • POST /api/kb/documents/upload
  • POST /api/kb/documents/url
  • GET /api/kb/search

知识库问答能力已合并到 AI 助手和群聊小助手中，不再提供独立的 /api/kb/chat 入口。

MCP 工具管理

  • GET /api/mcp/servers
  • POST /api/mcp/servers
  • PUT /api/mcp/servers/:id
  • DELETE /api/mcp/servers/:id
  • POST /api/mcp/servers/:id/test
  • POST /api/mcp/servers/:id/refresh-tools
  • GET /api/mcp/tools

文件上传

  • POST /api/upload

监控

  • GET /health — 存活检查（无认证）
  • GET /api/ready — 就绪检查（无认证，检查 MongoDB、Redis、PostgreSQL）
  • GET /api/metrics — 指标快照（admin）
  • GET /api/alerts — 告警规则状态（admin）
  • GET /api/test/ok|slow|error — 监控测试端点（默认关闭，需 ENABLE_MONITORING_TEST_ROUTES=true 和 X-Monitoring-Test-Token）

生产环境告警测试建议只打 /api/test/*，不要压登录、短信、AI 等真实业务接口：

wrk -t1 -c5 -d30s -H "X-Monitoring-Test-Token: <token>" https://mini-chat.cn/api/test/ok
wrk -t1 -c5 -d60s -H "X-Monitoring-Test-Token: <token>" "https://mini-chat.cn/api/test/slow?ms=1000"
wrk -t1 -c5 -d40s -H "X-Monitoring-Test-Token: <token>" "https://mini-chat.cn/api/test/error?status=500"

当前已知情况

  • 没有配置测试框架（test: echo "Error: no test specified"），验证方式为 npm run build + npm run lint + CI
  • 后端 Dockerfile 安装了系统依赖用于文档解析（antiword, catdoc, poppler-utils, unrtf），这些是知识库功能所需的
  • 生产环境必须设置 JWT_SECRET，否则服务启动失败
  • 告警阈值支持通过环境变量配置；测试端点默认关闭，生产测试后应及时关闭

开发建议

  • 知识库首选小文件和纯文本文件验证链路
  • 如果使用 DashScope text-embedding-v4，建议同时显式设置 Embedding 维度 = 1536
  • 如果只需要稳定上线知识库，优先选择 text-embedding-v2

路线图

详细规划请参考：

贡献

欢迎提交 Issue 和 PR。建议在提交前至少完成：

cd backend && npm run build
cd ../frontend && npm run build

如果你的改动涉及知识库，请附带：

  • 使用的 provider 配置方式
  • 测试文件类型
  • 上传 / 检索 / 问答结果

Commit 信息规范

提交信息采用 Conventional Commits 风格，描述使用中文：

<type>(<scope>): <中文描述>

常用 type：

  • feat：新增功能
  • fix：修复问题
  • docs：文档更新
  • refactor：重构，不改变外部行为
  • style：格式或样式调整
  • test：测试相关
  • chore：构建、依赖、配置、脚手架等杂项

示例：

feat(group): 新增群知识库管理面板
fix(kb): 修复 pgvector 向量写入格式
docs(readme): 补充提交信息规范

如果存在破坏性变更，在 type 或 scope 后加 !，并在正文或页脚说明影响：

feat(api)!: 调整知识库问答入口

BREAKING CHANGE: 移除独立的 /api/kb/chat，改由 AI 助手统一触发 RAG。

License

本项目使用 ISC License，详见 LICENSE。

About

全栈实时聊天平台 — 1v1 私聊、群组、AI 智能助手（OpenAI 兼容）、知识库 RAG、定时任务推送、MCP 工具集成

mini-chat.cn/

Topics

ai-chat

Resources

Readme

License

ISC license

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

1.0.0 Latest
May 8, 2026

Packages

 
 
 

Contributors

Languages