flyrain-kb/
├── backend/        # Django 后端（apps: users/knowledge/application/chat/model_provider/common）
├── frontend/       # Vue3 前端
└── deploy/         # docker-compose / nginx

快速开始（npm 一键脚手架）

已发布到 npm，无需克隆仓库：

# 生成完整项目（后端 + 前端 + docker-compose）
npx flyrain-kb init my-kb
cd my-kb

# 编辑 backend/.env 填入真实模型密钥（init 已自动从 .env.example 生成）
#   DEFAULT_LLM_API_KEY / DEFAULT_LLM_BASE_URL / DEFAULT_EMBEDDING_MODEL

# 拉起全栈（postgres / redis / backend / worker / frontend）
npx flyrain-kb up

# 创建管理员
npx flyrain-kb seed-admin --username admin --password admin123

也可全局安装后直接使用 flyrain-kb 命令：

npm i -g flyrain-kb
flyrain-kb --help

CLI 命令

命令	说明
`init [目录]`	生成完整项目源码（默认目录 `flyrain-kb`），`--force` 覆盖非空目录
`up [目录]`	`docker compose up -d --build` 启动全栈
`down [目录]`	停止并移除容器
`logs [目录]`	跟踪查看容器日志
`seed-admin [目录]`	创建管理员，`--username` / `--password`
`-v, --version` / `-h, --help`	版本 / 帮助

CLI 零运行时依赖，仅需 Node.js >= 18；up 系列命令需本机已安装并启动 Docker。

快速开始（已有源码，直接 Docker）

cd deploy
docker compose up -d --build

前端控制台：http://localhost:8080
后端 API：http://localhost:8000

本地开发

后端：

cd backend
python -m venv .venv && source .venv/Scripts/activate
pip install .
cp .env.example .env   # 修改 DEFAULT_LLM_API_KEY
python manage.py migrate
python manage.py runserver 0.0.0.0:8000
celery -A celery_app worker -l info

前端：

cd frontend
npm install
npm run dev

核心流程

新建知识库 → 上传 PDF/DOCX/TXT/MD/XLSX
Celery 异步解析 + 分块 + 向量化入库
创建 AI 应用，绑定知识库与 Prompt
对话页提问，混合检索（向量+关键词）召回资料，LLM 经 SSE 流式作答

角色与权限（RBAC）

系统内置三类角色，按写操作最小权限控制：

角色	说明	可写资源
admin（管理员）	最高权限	知识库 / 文档 / AI 应用 / 模型配置 / 用户
editor（知识库维护）	内容维护	知识库 / 文档 / AI 应用
user（普通用户）	只读使用者	仅查看与对话，无写权限

后端通过 apps/common/rbac.py 的 RoleRequiredMixin 在 perform_create/update/destroy 及 upload 动作中做角色校验，越权返回 403。
前端路由守卫（router/index.ts）按 meta.roles 限制 /model（仅 admin）、/apps（admin/editor）；布局菜单与菜单项、各页「新建/上传」按钮按当前角色显隐。
自注册（/users/register/）仅生成 user 角色，管理员使用种子命令创建：

python manage.py seed_admin --username admin --password admin123

用户管理页（admin 专属）

路由 /users（meta.roles: ['admin']），左侧菜单「用户管理」仅 admin 可见。
后端 UserViewSet（apps/users/views.py）仅 admin 可读写：GET/POST /api/users/、GET/PUT/DELETE /api/users/<pk>/。
支持：新建用户（含密码/角色/租户）、修改角色、删除用户。
安全护栏（后端强制）：
- 不可删除当前登录账号；
- 不可删除或降级唯一一名管理员（至少保留一名 admin）；
- 角色选择限定 admin / editor / user 三档。
新建/改角色走 AdminUserWriteSerializer，密码仅写入不回显。

向量检索索引优化（IVFFlat）

Paragraph.vector 字段已建立 pgvector ivfflat 索引（vector_cosine_ops），与检索使用的余弦距离（CosineDistance，底层 <=> 运算符）自动匹配，大幅提升大规模向量的相似度查询性能。

迁移文件：apps/knowledge/migrations/0002_paragraph_vector_ivfflat.py
lists = 100 为经验默认值，建议按「预期行数 / 1000」调整（范围 1~1000）；数据量显著增长后执行 REINDEX INDEX knowledge_paragraph_vector_ivfflat_idx;
检索前可在会话中设置探针数提升召回：SET ivfflat_probes = 10;（默认 probes=1）

分段命中高亮（KnowledgeDetail）

知识库详情页的「分段预览」对话框支持关键词高亮：

检索模式下：自动用检索词对命中分段做 <mark> 高亮；
任意分段预览下：顶部「高亮」输入框可手动输入关键词（空格分隔多个词）实时高亮；
实现要点：先对文档内容做 HTML 转义再包裹高亮标签（highlight() 函数），避免文档内容造成 XSS。

本地 Docker 联调

cd deploy
# 1) 配置真实模型 Key（必须，否则 embedding/对话会失败）
cp ../backend/.env.example ../backend/.env
#    编辑 .env 设置 DEFAULT_LLM_API_KEY / DEFAULT_LLM_BASE_URL / DEFAULT_EMBEDDING_MODEL
# 2) 构建并启动全部服务（postgres / redis / backend / worker / frontend）
docker compose up -d --build
# 3) 创建管理员账户
docker compose exec backend python manage.py seed_admin --username admin --password admin123