企业级AI知识库
企业级全栈 AI 知识库平台，集成了现代化的内容管理、深度 AI 智能问答与极致的用户交互体验。
English | 简体中文
如果这个项目对你有帮助，请点击右上角 ⭐ Star 支持一下，这是对开发者最大的鼓励！
- 🌐 文档站点上线: 集成了全新的 VitePress 文档站点 (2026-01-18)
- 📝 多语言对齐: 重新对齐了中英文 README 说明
- 🔧 架构清理: 优化了项目目录结构和 Docker 配置
- ✅ 开箱即用: Docker Compose 一键启动，自动初始化数据库和演示数据
- ✅ 双端架构: 独立的管理后台和客户端，职责清晰
- ✅ 类型安全: 前后端全面使用 TypeScript 和 Pydantic，类型安全有保障
- ✅ 现代技术栈: FastAPI + Next.js 14 + SQLAlchemy 2.0，使用最新技术
- ✅ AI 集成: 内置 AI 智能问答，基于 Vercel AI SDK
- ✅ 热更新: 开发环境支持前后端代码热更新
- ✅ 自动生成 SDK: 后端 API 变更后自动生成 TypeScript SDK
- ✅ 完善的文档: 详细的 API 文档和使用指南
运营概览 |
文档管理 |
用户管理 |
系统设置 |
AI 智能问答 - 基于知识库内容的智能对话助手，支持上下文理解
- 📝 富文本编辑: 基于 Markdown 的文档编辑器，支持实时预览
- 🗂️ 文档管理: 层级目录结构，支持拖拽排序
- 👥 用户管理: 完整的用户权限和角色管理
- 🌐 多站点支持: 支持创建和管理多个独立的知识库站点
- 🤖 AI 配置: 灵活的 AI 模型和机器人配置
- 🔍 智能搜索: 快速查找所需文档和内容
- 🤖 AI 问答: 基于知识库内容的智能对话助手
- 📱 响应式设计: 完美适配桌面端和移动端
- 🎨 现代化 UI: 使用 shadcn/ui 构建的优雅界面
- 框架: FastAPI
- 数据库: PostgreSQL + SQLAlchemy 2.0
- 迁移工具: Alembic
- 包管理: uv (高性能 Python 包管理器)
- 身份认证: JWT + PassLib
- Python 版本: >= 3.10
- 框架: Next.js 14 (App Router)
- 语言: TypeScript 5.3+
- 样式: Tailwind CSS
- 组件库: shadcn/ui (基于 Radix UI)
- 状态管理: React Hooks
- 包管理: pnpm
- 拖拽排序: @dnd-kit/core + @dnd-kit/sortable (管理后台)
- Markdown 编辑: md-editor-rt (管理后台)
- AI 集成: Vercel AI SDK (ai + @ai-sdk/react) (客户端)
- Markdown 渲染: streamdown (客户端)
- 通知系统: Sonner (前端通用)
catWiki/
├── backend/ # 🐍 FastAPI 后端服务
│ ├── app/
│ │ ├── api/ # API 路由 (Admin/Client)
│ │ ├── core/ # 核心配置、中间件、工具
│ │ ├── crud/ # 数据库 CRUD 操作
│ │ ├── models/ # SQLAlchemy ORM 模型
│ │ ├── schemas/ # Pydantic 验证模式
│ │ └── main.py # 应用入口
│ ├── scripts/ # 工具脚本（同步 SDK、初始化数据）
│ ├── Dockerfile.dev # 开发环境镜像
│ └── pyproject.toml # 依赖管理（uv）
│
├── frontend/
│ ├── admin/ # 🎯 管理后台 (Next.js, 8001)
│ ├── client/ # 💬 客户端 (Next.js, 8002)
│ └── docs/ # 📚 文档站点 (VitePress, 8003)
│
├── deploy/ # 🚀 生产环境部署
├── docker-compose.dev.yml # 开发环境一键启动
├── Makefile # 项目管理脚本
└── README.md # 项目主文档
| 目录 | 说明 | 技术栈 |
|---|---|---|
backend/ |
后端 API 服务 | FastAPI + PostgreSQL + SQLAlchemy |
frontend/admin/ |
管理后台（内部使用） | Next.js 14 + shadcn/ui + Tailwind |
frontend/client/ |
客户端（对外展示） | Next.js 14 + AI 问答 + 搜索 |
frontend/docs/ |
文档站点（项目说明） | VitePress + Markdown |
# 克隆项目
git clone https://github.com/bulolo/CatWiki.git
cd catWiki
# 1. 初始化配置
make dev-init
# 2. 修改配置 (重要!)
# 编辑 backend/.env 填入 OpenAI API Key 等信息
# vim backend/.env
# 3. 启动开发环境
make dev-upWarning
关于 make dev-init: 它会重新从模板复制 .env 文件，这会覆盖您已有的配置。
- 第一次运行: 请务必先运行
make dev-init，然后修改配置文件。 - 后续开发: 请直接使用
make dev-up。
等待 2-3 分钟，所有服务启动完成后，访问：
- 🎯 管理后台: http://localhost:8001 (admin@example.com / admin123)
- 💬 客户端: http://localhost:8002/medical
- 📚 文档站点: http://localhost:8003 (离线阅读此 README 及其它详细指南)
- 🛡️ API 文档: http://localhost:3000/docs
就这么简单！🎉
- Docker >= 20.10
- Docker Compose >= 2.0
- Make (系统自带或通过包管理器安装)
本项目根目录提供了 Makefile 工具，将复杂的 Docker 维护命令封装为简单的指令。
| 命令 | 说明 |
|---|---|
make gen-sdk |
生成 SDK：触发后端 API 自动生成前端 SDK |
make help |
预览命令：显示所有可用指令及其说明 |
| 命令 | 说明 |
|---|---|
make dev-init |
初始化环境配置：清理并重新从 .env.example 复制配置文件 |
make dev-up |
开发启动：构建镜像并在前台启动，实时查看所有服务日志 |
make dev-down |
优雅停止：停止并移除容器，保留数据库存储卷 |
make dev-restart |
快捷重启：仅重启后端应用容器 |
make dev-logs |
实时日志：查看后端核心服务的实时运行日志 |
make dev-db-migrate m="msg" |
生成迁移脚本：生成新的数据库迁移脚本（需提供备注 m） |
make dev-db-psql |
数据库终端：进入 PostgreSQL 交互式终端 |
make dev-clean |
深度重置：停止容器并删除所有数据卷（清空数据库和存储， |
| 命令 | 说明 |
|---|---|
make prod-init |
生产初始化：初始化生产环境配置文件模板 |
make prod-up |
生产启动：在后台启动生产环境所有服务 |
make prod-down |
生产停止：停止并移除生产环境容器 |
make prod-restart |
重启后端：仅重启生产环境后端应用容器 |
make prod-logs |
实时日志：查看生产环境容器日志 |
make prod-clean |
深度重置：停止容器并删除生产所有数据卷（ |
项目采用 独立初始化容器 (backend-init) 模式：
- 自我检测: 启动时自动检查数据库版本。
- 自动迁移: 自动执行 Alembic 脚本。
- 预置数据: 自动创建管理员 (
admin@example.com/admin123) 及医学演示站点。
后端 API 变更后，只需一行命令即可更新前端 SDK：
make gen-sdk项目提供了标准化的生产环境部署流程，通过 make prod-xxx 系列命令即可快速管理。
# 生成生产环境配置文件模板 (位于 deploy/docker/ 目录)
make prod-init编辑以下文件，填入正式的域名、数据库密码、JWT 密钥等：
deploy/docker/.env.backenddeploy/docker/.env.admindeploy/docker/.env.client
# 在后台启动所有生产环境容器
make prod-upImportant
详细的安全配置建议（如证书配置、对象存储对接等）请参考： 👉 生产环境完整部署指南 (deploy/docker/README.md)
Tip
遇到问题时，通常 make dev-clean + make dev-up 能解决 90% 的本地环境异常。
A: 请确认是否运行了 make dev-init。如果数据库已损坏，请使用 make dev-clean 重置。
Q: 如何修改默认服务端口？
A: 直接在根目录的 docker-compose.dev.yml 中修改对应的 ports 映射即可。
Q: 客户端 API 报 404？
A: 确保你的访问路径包含站点域名后缀，例如：http://localhost:8002/medical。
- � 环境配置指南 - 开发和生产环境的完整配置说明
- 🚀 开发快速开始 - 5 分钟上手开发环境
- 🔌 API 架构细节 - Admin API 和 Client API 设计原则
- 📦 RustFS 使用指南 - 文件上传、下载、对象存储详解
- 🎯 SDK 使用指南 - 前端如何调用后端 API
本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。
- ✅ 自由使用: 你可以自由使用、修改和分发本软件
- ✅ 开源要求: 你必须以相同的许可证开源你的修改
- ✅ 网络服务: 如果你通过网络提供服务，也必须开源你的代码
- ✅ 商业使用: 允许商业使用，但需要遵守相同的开源要求
这意味着如果你：
- 🔧 修改了代码: 必须开源修改后的代码
- 🌐 提供 SaaS 服务: 必须向用户提供完整源代码
- 💼 商业化运营: 可以，但必须保持开源
详见 LICENSE 文件获取完整许可证文本。
我们选择 AGPL-3.0 是为了：
- 保护开源社区的利益，防止闭源商业化
- 确保所有改进都能回馈给社区
- 即使是网络服务形式，用户也能获得源代码
- 💬 问题反馈: 通过 GitHub Issues 提交
- 📧 商务合作: 82607314@qq.com/ bulolo(微信)
- 🌐 官方网站: http://catwiki.cn
⭐ 如果这个项目对您有帮助，请给我们一个 Star！
Made with ❤️ by CatWiki Team