PureChat

把你的 AI 助手接入微信和 QQ。

面向中文用户和小团队的开源自托管 AI 工作台，支持多模型、联网搜索、文件处理和私有部署。

在线体验（正式主站） · Vercel 备用站（功能受限） · Vercel 部署（Gateway 功能受限） · Docker 自托管 · 文档站 · 讨论区

目录

• 项目简介
• 特性
• 快速开始
• 部署
• 环境变量
• 项目结构
• 常用命令
• 文档
• 参与贡献
• License

项目简介

PureChat（仓库名：PureChatNext）让同一个 AI 助手同时服务于 Web、微信和 QQ。你可以先使用正式主站，也可以在主备共享数据库、密钥和必要依赖的前提下使用 Vercel 备用站；也可把数据库、模型密钥、文件和聊天记录完整部署在自己的环境中。Vercel 备用站不运行持久 Channel Gateway，因此不支持微信持久连接、QQ 扫码或 WebSocket，仅支持 QQ Webhook。

与通用 ChatGPT Clone 相比，PureChat 优先解决中文用户的三个具体问题：

• 聊天入口不必迁移：通过微信和 QQ Channel Gateway，在已有通讯工具中直接使用 AI
• 数据与成本可控：支持自托管、自备模型 API Key、免费额度账本与用量明细
• 能力可以组合：多模型、联网搜索、文件解析、Agent 和消息渠道共用一套工作台

技术栈：

• 前端：Vite + React Router SPA，开发时运行在 5174 端口
• 服务端：Next.js 16 BFF，负责 API、认证和生产环境的 SPA HTML 壳
• 数据层：PostgreSQL + Drizzle ORM，可使用 Supabase、Neon 或本地 Docker
• AI 能力：Vercel AI SDK，支持 OpenAI、DeepSeek、PureChat / AI Gateway 等 Provider

生产环境以单个 Next.js 项目部署，SPA 静态资源与 API 共用同一域名。

flowchart LR
  WeChat[微信] --> Gateway[Channel Gateway]
  QQ[QQ] --> Gateway
  Web[Web SPA] --> Next[Next.js BFF]
  Gateway --> Next
  Next --> PG[(PostgreSQL)]
  Next --> LLM[OpenAI / DeepSeek / Gateway]

特性

微信与 QQ 渠道

在微信或 QQ 里扫码绑定后，即可私聊或群内 @ 助手，不必再打开单独的网页。

• 微信 iLink 扫码连接，并由 Channel Gateway 持续接收与回复消息
• QQ 扫码、WebSocket 与 Webhook 多种连接方式
• 渠道可选择 Agent、模型与 Provider，复用 Web 端能力
• 支持 /agents、/new、/stop、/help 等会话指令

配置说明见 微信渠道 与 QQ 渠道。

多模型对话

• 流式输出与 Tool Calling
• 通过环境变量切换模型 Provider、API Key 和代理地址
• 支持 OpenAI、DeepSeek 等常用模型服务

用户认证

• 邮箱密码注册与登录
• 邮箱验证、魔法链接（需配置邮件服务）
• GitHub、Google、Apple、微信、飞书等 OAuth / SSO
• 个人资料、密码和关联账号管理

认证与邮件配置见 邮箱服务与验证。

联网搜索与文件处理

• 搜索聚合：SearXNG、Search1API、Google、Brave 等
• 网页抓取：naive、Firecrawl、Tavily、Jina、Browserless 等
• 文档解析：PDF、DOCX、PPTX、Excel 等

详细配置见 联网搜索与爬虫。

模块化 Monorepo

项目使用 pnpm workspace，将共享能力拆分为 @pure/* 包，便于复用、测试和独立演进。核心包包括环境变量、数据库、模型目录、文件加载、网页爬虫、SSRF 安全请求和聊天渠道适配器。

快速开始

前置要求

• Node.js ≥ 20
• pnpm 10（版本见 package.json）
• Bun（开发脚本和部分迁移脚本使用）
• PostgreSQL；也可以使用项目提供的 Docker 依赖

1. 安装并配置

git clone https://github.com/Hyk260/PureChatNext.git
cd PureChatNext

pnpm install
cp .env.example .env.local

编辑 .env.local，至少准备：

# 本地必须指向 SPA 端口；CORS 默认允许该地址，不必再配相同的 ALLOWED_ORIGINS
APP_URL=http://localhost:5174

# 数据库（云数据库也可以）
DATABASE_DRIVER=neon
DATABASE_URL=postgresql://user:password@host:5432/database

# 生成方式见 .env.example
KEY_VAULTS_SECRET=your-random-secret
AUTH_SECRET=your-random-secret
JWKS_KEY='{"keys":[...]}'

# 至少配置一个可用的模型 Provider
OPENAI_API_KEY=your-api-key

密钥生成和完整变量说明见 .env.example 与 环境变量配置。

2. 执行数据库迁移

pnpm db:migrate

3. 启动开发环境

# 推荐：并发启动 Next API / BFF（3000）与 Vite SPA（5174）
pnpm dev

打开 http://localhost:5174。3000 端口只提供 API / BFF，不是开发时的主 UI 入口。

如果需要使用 Alt+Shift 点击页面元素跳转源码：

pnpm dev:inspect

也可以分开启动：

pnpm dev:next  # Next API / BFF → http://localhost:3000
pnpm dev:spa   # Vite SPA → http://localhost:5174

使用 Docker 启动本地依赖

安装 Docker Desktop 后，可以一次启动 PostgreSQL、Redis、RustFS 和 SearXNG：

pnpm docker:setup:dev
pnpm dev:docker
pnpm db:migrate
pnpm dev

本地 Docker 连接信息会写入 docker-compose/dev/.env，并可按需同步到 .env.local。日常停止和重置：

pnpm dev:docker:down   # 停止，保留数据卷
pnpm dev:docker:reset  # 确认后删除开发数据并重建

部署

Vercel

点击下方按钮克隆并创建 Vercel 项目，然后按环境变量文档补齐数据库、认证与模型配置：

项目按单个 Next.js 项目部署，仓库已包含 vercel.json。配置以下内容后即可上线：

1. 安装命令：pnpm install
2. 构建命令：pnpm build:vercel（先迁移数据库再构建；vercel.json 已写入）
3. 配置生产环境变量，至少包含数据库、认证密钥、APP_URL 和模型 Provider 密钥
4. 生产前后端同域时不必再配 ALLOWED_ORIGINS；有额外前端域名时再设置，不要使用 *
5. 将 DATABASE_URL（及云托管时的 DATABASE_DRIVER=neon）勾选到 Production / Preview 的 Build，不要设成仅 Runtime

构建流程为迁移 → build:spa → 复制 SPA 产物 → next build。迁移失败则部署失败。部署后的静态资源位于 /_spa/**，未匹配的 UI 路径会回退到 SPA HTML 壳。

Docker 自托管

pnpm docker:setup:deploy

# 修改 docker-compose/deploy/.env 后，一条命令构建并启动
pnpm docker:deploy

首次生成配置后，请修改正式域名和模型密钥。生产 Compose 会在应用启动前自动执行数据库迁移，健康检查地址为 /api/health。

云服务器在线安装（拉 GHCR，无需本机打包）：

curl -fsSL https://raw.githubusercontent.com/Hyk260/PureChatNext/main/docker-compose/deploy/install-online.sh \
  | sudo APP_URL=https://chat.example.com bash

不便拉镜像时，改用离线包：

# 首次安装
pnpm docker:pack
pnpm docker:upload -- --install --app-url https://chat.example.com   # 首次
# 日后升级（自动重新打包并上传）
pnpm docker:pack:upgrade

完整说明见 Docker 自托管。云服务器与 1Panel 见 云服务器部署。

环境变量

环境变量由 packages/env 统一校验。常用配置如下：

变量	用途	说明
APP_URL	当前部署的对外地址	本地使用 http://localhost:5174；主站为 https://app.purechat.cn，Vercel 备用站使用 https://next.purechat.cn；CORS 默认允许该地址
SITE_CANONICAL_URL	公开页面的 SEO 主域	可选；备用站设置为 https://app.purechat.cn，认证回调仍由 APP_URL 决定
ALLOWED_ORIGINS	CORS 额外来源	可选；省略时使用 APP_URL。不要使用 *
DATABASE_DRIVER	数据库连接模式	云数据库使用 neon；本地 / Docker PostgreSQL 使用 node
DATABASE_URL	PostgreSQL 连接字符串	Supabase、Neon 或本地 PostgreSQL 均可
KEY_VAULTS_SECRET	敏感配置加密密钥	渠道凭证与用户服务商密钥；使用随机高强度密钥
AUTH_SECRET / JWKS_KEY	认证与 JWT 密钥	生成方式见 .env.example
OPENAI_API_KEY / DEEPSEEK_API_KEY	模型 Provider 密钥	网页聊天可选兜底；微信 / QQ 需在设置页保存用户密钥
SEARCH_PROVIDERS / CRAWLER_IMPLS	搜索与爬虫链	不需要联网搜索时可以不配置
REDIS_URL	缓存与队列	使用 Docker 或托管 Redis 时配置
S3_*	文件对象存储	使用 RustFS、MinIO、S3 等兼容服务时配置

完整变量列表、认证、邮件、对象存储和联网搜索配置请查看 环境变量详解。

项目结构

PureChatNext/
├── apps/
│   ├── desktop/               # Electron 桌面应用
│   └── docs/                  # 独立 Next.js + Fumadocs 文档站
├── packages/                  # @pure/* 工作区包
│   ├── database/              # Drizzle Schema、Model 与迁移
│   ├── env/                   # 环境变量校验
│   ├── model-bank/            # 模型目录与定价
│   ├── file-loaders/          # PDF、DOCX、PPTX、Excel 等文档加载
│   ├── web-crawler/           # 网页爬虫实现
│   └── chat-adapter/          # QQ / 微信渠道适配器
├── src/
│   ├── spa/                   # Vite SPA 入口与 Router
│   ├── features/              # 业务 UI
│   ├── app/api/               # Next API 路由
│   ├── server/                # 服务端业务与搜索聚合
│   ├── libs/                  # 认证、中间件与工具
│   └── components/            # 通用 React 组件
├── docs/                      # 文档站与 GitHub 共用的公开 Markdown 内容源
└── scripts/                   # 开发、构建、迁移与 Docker 脚本

常用命令

# 开发
pnpm dev
pnpm dev:inspect
pnpm dev:next
pnpm dev:spa
pnpm dev:docs

# 构建与运行
pnpm build
pnpm build:docs
pnpm start

# 数据库
pnpm db:check
pnpm db:generate
pnpm db:migrate
pnpm db:studio

# 质量检查与测试
pnpm lint
pnpm exec vitest run --silent='passed-only'

# Docker
pnpm docker:validate
pnpm docker:deploy
pnpm dev:docker
pnpm dev:docker:down

文档

文档	内容
公开文档站	可搜索的正式文档、目录和页面导航
文档索引	全部公开文档与维护规范
快速开始	云数据库与本地开发配置
开发指南	数据库、质量检查与样式约定
自托管指南	部署、基础设施、功能与消息渠道
开发约定	AI Agent 与项目开发指南

参与贡献

欢迎提交 Issue、参与 Discussion 或发起 Pull Request。开始前请阅读 贡献指南 与 安全政策。提交前请运行：

pnpm lint
pnpm exec vitest run --silent='passed-only'

如果修改了环境变量，请同步更新 packages/env 和 .env.example，并补充对应文档。

License

本项目基于 MIT License 开源。

Copyright © 2025–2026 Hyk260.