# Knowly **Repository Path**: synthly/knowly ## Basic Information - **Project Name**: Knowly - **Description**: Knowly 是基于 DeepSeek 大模型的知识库智能问答组件（Knowledge Q&A Widget）：开箱即用、可独立部署、iframe 一键嵌入，让你的产品、文档和网站在一分钟内拥有专属智能问答助手。 - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-09 - **Last Updated**: 2026-08-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Knowly · 知识库智能问答组件 **Knowly** 是基于 DeepSeek 大模型的知识库智能问答组件（Knowledge Q&A Widget）：开箱即用、可独立部署、iframe 一键嵌入，让你的产品、文档和网站在一分钟内拥有专属智能问答助手。 ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg) ![Version](https://img.shields.io/badge/version-0.1.0-4D6BFE.svg) ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg) ![Powered by DeepSeek](https://img.shields.io/badge/powered%20by-DeepSeek-4D6BFE.svg) ![Gitee stars](https://gitee.com/synthly/knowly/badge/star.svg?theme=dark) ![Gitee forks](https://gitee.com/synthly/knowly/badge/fork.svg?theme=dark) Knowly 是 [Synthly AI](https://gitee.com/synthly)推出的开源知识库问答产品。它基于 DeepSeek 大模型构建 RAG（检索增强生成）对话，答案严格来源于你上传的知识库，拒绝凭空编造。 - 仓库地址：https://gitee.com/synthly/knowly - 开源协议：MIT --- ## 目录 - [功能特性](#功能特性) - [技术栈](#技术栈) - [目录结构](#目录结构) - [快速开始](#快速开始) - [嵌入使用](#嵌入使用) - [API 概览](#api-概览) - [数据库](#数据库) - [常见问题](#常见问题) - [参与贡献](#参与贡献) - [开源协议与商业支持](#开源协议与商业支持) ## 功能特性 - **智能问答** — 基于知识库的 RAG 对话，答案严格来源于知识库，杜绝幻觉 - **知识库管理** — 支持 TXT / Markdown / PDF / DOCX / CSV 文档上传，自动解析入库；支持手动增删改 - **管理后台** — 仪表盘、对话记录、知识库维护、系统设置（API Key、模型、品牌等） - **一键嵌入** — `/widget` 页面提供纯净对话窗口，通过 iframe 嵌入任意网站 - **品牌可定制** — 系统名称、助手名称、欢迎语、快捷问题均可配置 - **数据自主可控** — SQLite 本地存储，独立部署，业务数据不出域 - **响应式设计** — 全页面适配移动端与桌面端 ## 技术栈 | 分类 | 技术 | |------|------| | 框架 | Next.js 15（App Router） | | UI | React 19 | | 语言 | TypeScript（strict） | | 数据库 | SQLite（better-sqlite3） | | AI | DeepSeek API + LangChain | | 文档解析 | pdf-parse（PDF）、mammoth（DOCX） | | 认证 | bcryptjs + jose（JWT） | | 样式 | CSS Modules + CSS Variables | | Markdown 渲染 | react-markdown + remark-gfm | ## 目录结构 ``` knowly/ ├── public/ │ └── template/ # 知识库导入模板 ├── src/ │ ├── app/ # Next.js App Router 页面 │ │ ├── page.tsx # 首页（产品介绍 & 嵌入指南） │ │ ├── layout.tsx # 根布局 │ │ ├── globals.css # 全局样式 │ │ ├── widget/ # 可嵌入的对话窗口 │ │ ├── admin/ # 管理后台 │ │ │ ├── login/ # 登录页 │ │ │ ├── dashboard/ # 仪表盘 │ │ │ ├── knowledge/ # 知识库管理 │ │ │ ├── chats/ # 对话日志 │ │ │ └── settings/ # 系统设置 │ │ └── api/ # API 路由 │ │ ├── auth/ # 认证接口 │ │ ├── chat/ # 问答接口 │ │ ├── chats/ # 对话记录接口 │ │ ├── config/ # 公开配置接口 │ │ ├── dashboard/ # 仪表盘数据接口 │ │ ├── knowledge/ # 知识库 CRUD 接口 │ │ ├── settings/ # 设置读写接口 │ │ └── upload/ # 文档上传 & 解析接口 │ ├── components/ # 共享组件 │ │ ├── ChatWidget.tsx # 对话窗口核心组件 │ │ ├── ChatMessage.tsx # 消息气泡 │ │ ├── ChatInput.tsx # 输入框 │ │ ├── ChatHistoryList.tsx │ │ ├── AdminSidebar.tsx # 管理后台侧边栏 │ │ ├── KnowledgeForm.tsx │ │ ├── KnowledgeList.tsx │ │ ├── FileUpload.tsx │ │ └── SettingsForm.tsx │ └── lib/ │ ├── ai/ # AI 层 │ │ ├── deepseek.ts # DeepSeek API 调用 │ │ ├── embeddings.ts # 文本向量化 │ │ └── rag.ts # RAG 检索 + 回答生成 │ ├── auth.ts # JWT 认证工具 │ ├── chatService.ts # 对话服务 │ ├── db.ts # SQLite 数据库初始化 & 读写 │ └── types.ts # TypeScript 类型定义 ├── data/ # SQLite 数据库文件（运行时生成，勿提交） ├── .env.example # 环境变量模板 ├── next.config.ts ├── tsconfig.json ├── package.json ├── CONTRIBUTING.md # 贡献指南 ├── LICENSE └── README.md ``` ## 快速开始 ### 前置要求 - **Node.js** >= 20 - **pnpm** >= 9（项目统一使用 pnpm，请勿使用 npm / yarn） ### 环境变量 在项目根目录创建 `.env` 文件（或直接设置系统环境变量）： ```bash # DeepSeek API 配置（必填） DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxx # DeepSeek API 地址（可选，默认 https://api.deepseek.com） DEEPSEEK_API_ENDPOINT=https://api.deepseek.com # DeepSeek 模型（可选，默认 deepseek-v4-flash） DEEPSEEK_MODEL=deepseek-v4-flash # 管理后台初始密码（可选，默认 admin123，生产环境务必修改） QA_ADMIN_PASSWORD=your-secure-password # JWT 签名密钥（可选，生产环境务必修改为随机字符串） QA_JWT_SECRET=your-random-secret-string ``` > **注意：** `.env` 文件已被 `.gitignore` 忽略，请勿提交到版本控制。仓库中仅提交不含敏感值的 `.env.example` 模板。 ### 安装依赖 ```bash pnpm install ``` ### 启动开发服务器 ```bash pnpm dev ``` 默认端口为 **3040**，如需修改可在 `package.json` 的 `dev` 脚本中调整 `--port` 参数。 启动后可访问： | 页面 | 地址 | |------|------| | 产品首页 | http://localhost:3040/ | | 对话窗口 | http://localhost:3040/widget | | 管理后台 | http://localhost:3040/admin/login | ### 管理后台登录 - 默认用户名：`admin` - 默认密码：由环境变量 `QA_ADMIN_PASSWORD` 设置（未设置则为 `admin123`） - 登录后可在「系统设置」中修改密码 ### 类型检查 ```bash pnpm typecheck ``` ### 构建生产版本 ```bash pnpm build pnpm start ``` ## 嵌入使用 将 `/widget` 页面通过 iframe 嵌入任意网页： ```html ``` 对话窗口会自动从 `/api/config` 拉取系统名称、助手名称、欢迎语和快捷问题等品牌配置。 ## API 概览 ### 公开接口 | 方法 | 路径 | 说明 | |------|------|------| | POST | `/api/chat` | 发送问答请求 | | GET | `/api/config` | 获取公开的品牌配置 | ### 管理后台接口（需认证） | 方法 | 路径 | 说明 | |------|------|------| | POST | `/api/auth/login` | 管理员登录 | | GET | `/api/auth/verify` | 验证登录状态 | | GET | `/api/dashboard` | 仪表盘统计数据 | | GET | `/api/knowledge` | 获取知识库列表 | | POST | `/api/knowledge` | 新增知识条目 | | PUT | `/api/knowledge` | 更新知识条目 | | DELETE | `/api/knowledge` | 删除知识条目 | | POST | `/api/upload` | 上传文档并解析入库 | | GET | `/api/settings` | 获取系统设置 | | PUT | `/api/settings` | 更新系统设置 | | GET | `/api/chats` | 获取对话记录列表 | | DELETE | `/api/chats/[id]` | 删除单条对话记录 | ### 请求示例 ```bash # 发送问答 curl -X POST http://localhost:3040/api/chat \ -H "Content-Type: application/json" \ -d '{"question": "产品支持哪些功能？"}' ``` ## 数据库 项目使用 SQLite（`better-sqlite3`），数据库文件自动创建在 `data/knowly.db`（已加入 `.gitignore`，不会被提交）。 Schema 包含四张表： - **knowledge** — 知识条目（标题、内容、分类） - **settings** — 系统设置键值对 - **users** — 管理员账号 - **chat_logs** — 对话记录（问题、答案、时间） 首次启动时自动建表并初始化默认管理员账号和系统设置。 ## 常见问题 **Q：如何修改服务端口？** A：修改 `package.json` 中 `dev` 脚本的 `--port` 参数；生产环境部署时，可通过环境变量 `PORT` 指定（Next.js 原生支持）。 **Q：忘记管理后台密码怎么办？** A：停止服务后删除 `data/knowly.db` 文件，重启服务会自动重新初始化默认管理员账号（用户名 `admin`，密码为 `QA_ADMIN_PASSWORD` 或默认 `admin123`）。注意：删除数据库会同时清空知识库和对话记录，操作前请做好备份。 **Q：可以更换为其他大模型吗？** A：当前版本 AI 层基于 DeepSeek API 构建（见 `src/lib/ai/`），支持在管理后台配置 API Key、接口地址与模型名称；接入其他兼容 OpenAI 协议的模型可自行扩展。 **Q：部署到生产环境需要注意什么？** A：务必设置强密码 `QA_ADMIN_PASSWORD`、随机 `QA_JWT_SECRET`，并配置正确的 `DEEPSEEK_API_KEY`；建议在反向代理层启用 HTTPS。 ## 参与贡献 欢迎提交 Issue 和 Pull Request，一起让 Knowly 变得更好： 1. **Fork** 本仓库到你的账号下 2. 新建分支：`git checkout -b feat-xxx`（功能）或 `fix-xxx`（修复） 3. 提交代码并推送：`git push origin feat-xxx` 4. 在 Gitee 上发起 **Pull Request**，描述清楚改动内容与动机 详细规范（提交信息格式、代码风格、测试要求等）请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 开源协议与商业支持 Knowly 基于 MIT 协议开源，可自由使用、修改与分发。同时，Synthly AI（LAPUS 乐普软件旗下 AI 产品品牌）提供完整的商业化服务： - **品牌定制部署** — 系统名称、助手形象、品牌视觉与域名定制，打造你的专属问答产品 - **私有化部署** — 面向企业内网/私有云环境的部署交付与运维支持 - **企业级定制** — 知识库导入、多模型接入、多租户、权限体系等深度定制开发 - **技术支持** — 专属技术对接与响应服务，保障业务稳定运行 欢迎通过邮箱联系 Synthly AI 团队：**help@lapus.cn** ## License 本项目基于 [MIT](./LICENSE) 协议开源，Copyright © 2026 Synthly AI。详见 [LICENSE](./LICENSE)。