企业知识库问答系统 #

前后端分离的企业知识库助手：React 19 + Ant Design 6 + FastAPI + LangChain / LangGraph + PostgreSQL（pgvector + pg_jieba）。

系统定位：带权限、带记忆、带引用、可护栏 的企业 FAQ / 制度 / 工单助手。模型负责理解与组织语言；检索、部门 ACL、审计、危险操作与审批由后端代码保证。

详细需求见 企业知识库需求文档.md，分步计划见 企业知识库开发计划.md（Step 01～28 已实现）。

目录 #

• 系统能力一览
• 架构概览
• 目录结构
• 前置条件
• 快速开始
• 如何使用系统（用户手册）
• 角色与权限
• 测试账号
• 环境变量
• 后端 API 参考
• CLI 工具
• 测试与 CI
• 生产部署
• 相关文档
• 常见问题

系统能力一览 #

架构概览 #

一轮问答路由逻辑（thread_turn）：

1. 命中「查单 / 计算 / 建工单 / 发信 / 记住…」等意图 → Agent 工具链
2. 开启多 Agent 且非强制单 Agent → 路由器 + 无历史子专家
3. 默认 → 固定 RAG（预检索 → 生成 → 拒答句）
4. RAG 无检索命中 → 回退 Agent（保留多轮记忆，不预检索）

流式与非流式共用同一套逻辑，最终 answer / refused / citations 一致。

目录结构 #

langrag/
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── api/routes/          # auth、me、users、org、workbench、notifications、
│   │   │                        # documents、tickets、orders、approvals、admin…
│   │   ├── services/            # RAG、Agent、工单状态机、订单、通知、治理、发信
│   │   ├── cli/                 # kb-serve、kb-user-passwd、kb-golden-report…
│   │   └── db/                  # SQLAlchemy 模型、迁移、checkpointer / store
│   ├── migrations/              # 001～012：扩展、种子、会话、审批、IAM、工单、
│   │                            # 治理、订单、通知、存量回填
│   ├── tests/                   # pytest（含黄金集 golden_v0）
│   ├── scripts/                 # export_openapi.py、smoke_productized.py
│   └── openapi.json
├── frontend/                    # React SPA（见 frontend/README.md）
│   └── src/
│       ├── api/                 # REST 客户端 + OpenAPI 类型
│       ├── pages/               # Home、Chat、Tickets、Orders、Approvals、
│       │                        # Documents、OpsDashboard、Users、Profile、Login
│       ├── components/          # 通知铃铛、工单时间线、工作台卡片…
│       └── layouts/AppLayout.tsx
├── deploy/
│   ├── nginx.conf.example       # 生产反代（含 SSE）
│   └── backup_pg.ps1            # PostgreSQL 备份脚本
├── docs/                        # SSE 契约、MVP 清单、生产 runbook
├── docker/                      # pg-search 镜像（pgvector + pg_jieba）
├── .github/workflows/ci.yml
├── docker-compose.yml
└── .env.example

前置条件 #

快速开始 #

以下命令均在 PowerShell 下执行；路径以仓库根目录 D:\forever\docs\langrag 为例。

第 1 步：配置环境变量 #

Copy-Item .env.example .env
# 编辑 .env，至少填写：
#   DEEPSEEK_API_KEY
#   DASHSCOPE_API_KEY
#   DATABASE_URL（默认与 docker-compose 一致即可）

必填项缺失时，后端启动会 ValidationError 并拒绝启动（避免运行中静默 401）。

第 2 步：启动数据库 #

docker compose up --build -d
docker compose ps

期望看到 enterprise-kb-postgres 状态为 healthy，端口 5432:5432。

国内 Docker Hub 超时：项目已默认使用 DaoCloud 镜像源构建基础镜像。若仍失败，见 常见问题 — Docker 拉取失败。

第 3 步：数据库迁移 #

Set-Location backend
uv sync
uv run python -m app.db.migrate up
# 等价：uv run kb-migrate up

回滚最近一次迁移：uv run python -m app.db.migrate down

第 4 步：启动后端 #

Set-Location backend
uv run kb-serve

等价命令：

# 热重载模式下 uvicorn 会自己切好事件循环，可直接用
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

启动时自动完成：数据库校验 → 嵌入维度校验 → 账号口令引导 → 审批阈值加载 → LangGraph checkpointer/store → 异步摄入 worker → TTL 定时清扫 → 邮件出站投递 worker。

Windows 单进程启动：kb-serve --no-reload 会自动切到 SelectorEventLoop。若你绕过 kb-serve 直接跑 uvicorn app.main:app --no-reload，uvicorn 在 Windows 单进程下会用 ProactorEventLoop，psycopg 的异步连接池不兼容，服务会一直无法就绪。

第 5 步：启动前端 #

新开一个终端：

Set-Location frontend
npm install
npm run dev

浏览器打开：http://localhost:5173

开发环境下，Vite 将 /api 代理到 http://127.0.0.1:8000（见 frontend/vite.config.ts）。

第 6 步：登录 #

使用 测试账号 登录，例如知识管理员 `kbadmin@example.com/Kb@Init2026`。首次登录会被要求先改密码，改完即可使用各功能模块。

如何使用系统（用户手册） #

1. 登录与工作台（/） #

1. 访问 http://localhost:5173 ，未登录会跳转 /login，并记住原来要去的路径（分享的工单 / 订单链接登录后能回来）。
2. 输入邮箱与密码（初始口令见 测试账号）。登录页会展示当前的密码强度要求（来自公开接口 GET /auth/password-policy）。开发环境登录页提供快捷填充邮箱（密码仍需手输）。
3. 首次登录必须改密：带 must_change_password 的账号在登录页当场改密，改完才进系统。若绕过登录页，除「我的档案」外都会被拦回档案页的「账号安全」表单。
4. 连续输错 AUTH_MAX_FAILED_ATTEMPTS（默认 5）次会锁定 AUTH_LOCK_MINUTES（默认 15）分钟，接口返回 403 并说明剩余锁定时间；解锁需等待或由系统管理员在 /admin/users 手动解锁。账号停用同样是 403；邮箱或密码错误是 401。
5. 登录后进入 工作台，按角色聚合当天要干的事（卡片数字随工单 / 审批 / 治理写操作自动刷新）：

工作台还会展示需要关注的工单（点击行直接打开 /tickets?ticket= 详情抽屉）、最近会话、近 7 天解决量与平均满意度。系统健康检查（pgvector / pg_jieba / 嵌入维度 / 模型 ping）在运维看板，工作台只放业务待办。

6. 侧栏按角色分组显示：工作台、智能问答、服务与审批（工单 / 订单查询 / 退款申请 / 待我审批）、知识库运营、系统管理、个人。顶栏「修改密码」进入档案页账号安全表单。
7. 顶栏铃铛每 30 秒拉一次未读站内通知，点击条目直接跳到对应工单或审批。

2. 知识问答（/chat、/chat/:threadId） #

问答页是系统的核心入口，支持 SSE 流式 与 多轮会话。

基本操作 #

期望行为 #

引用与拒答 #

• 回答中的 [1]、[2] 与下方 引用卡片 对应，含来源文件名、页码等。
• refused=true 时前端以警告样式展示，便于与正常回答区分。

错误提示 #

3. 工单（/tickets） #

权限：访客不可用（后端返回 403）；员工仅看本人工单；客服 / 知识管理员 / 系统管理员可看全部并可流转。

待办视图 #

页面顶部按角色给出待办页签，URL 带 ?scope= 可直接分享：

还支持按状态（多选）、类别、优先级、紧急度、关键词（工单号 / 标题 / 摘要）筛选，以及「仅看 SLA 已超时」。详情抽屉用 ?ticket=<id>，可直接分享。

状态机 #

工单号形如 TK-001234，状态流转由后端强制校验，非法流转返回 409 并列出当前可选项：

优先级与 SLA #

紧急度自动映射优先级（高→P1、中→P2、低→P3），下单即按优先级算出 sla_due_at；列表与详情用标签区分 正常 / 即将到期 / 已超时，超时工单会进入客服工作台的「SLA 已超时」待办。

交互 #

问答 Agent 建的单与手工建单写入同一张表，在工单页刷新即可看到。工单被指派、有新回复、被解决或重新打开时，当事人会收到站内通知（配置了发信服务时同时发邮件）。

3.1 订单查询（/orders） #

权限：访客不可用；客服 / 知识管理员 / 系统管理员可查全部客户，其余角色只看与本人账号关联的订单。没有系统账号的外部客户（如种子数据里的「李四」）只能由客服代客查单。

问答里的 lookup_order 工具查的就是这张表（仅客服及以上角色装载该工具），不再是写死的示例数据。

4. 我的档案（/me/profile） #

管理账号信息与 跨会话长期记忆（PostgresStore）：

Agent 工具 remember_note / recall_notes 与页面数据同源。问答中口头告知的偏好会在回合结束后由 after_agent 从 Human 消息抽取并合并档案。

5. 审批工作台（/approvals） #

权限：approver、support、kb_admin、sys_admin 均可打开此页。工作台「待我审批」卡片目前只给 approver 与 sys_admin；客服 / 知识管理员从侧栏「待我审批」进入。

1. 客服在问答中触发 send_email → 进入 待审批 列表。
2. 审批人查看 明文收件人（不对 email 做 PII 脱敏，避免无法发信）。
3. 批准 → 调用 POST /threads/{id}/resume 继续 Agent 图；驳回 → 不发送。
4. interrupt_id 与 thread_id 不匹配时返回 409（防串会话）。

6. 退款审批流（/approvals/flows） #

权限：员工及以上可提交并查看自己提交的申请；approver / support / kb_admin / sys_admin 可审批。

金额分级（确定性节点，非模型决策） #

阈值存在数据库里，系统管理员可直接在页面上改，改完立即对新申请生效，并记录修改人与修改时间：

一级 / 二级的职位名也可配置，页面与时间线上的文案会跟着变。

提交与校验 #

• 必须挂在一张真实工单上（下拉给出本人的退款类工单）。
• 可选关联订单号；填了订单号时后端会按 orders.refundable_amount 校验，超过可退余额直接 400 拒绝并说明差额。
• 必须填申请原因（≥2 字）。
• 表单会实时预览这笔金额会走哪一档。

审批 #

页面展示 Steps 可视化与中文审批日志；支持批准、改额、驳回：

• 驳回与改额必须填审批意见，意见会落进审批日志与申请人的通知里。
• 批准可选填意见。
• 打款仅在批准后的独立 payout 节点执行。
• 审批出结果时申请人收到站内通知。

7. 知识库治理（/kb/documents） #

权限：kb_admin、sys_admin。

摄入 #

上传参数：space_id（如 space_faq）、dept（如 public）、title。上传人默认成为该文档的责任人。

治理 #

文档不再是「上传即永久有效」，而是带责任人与有效期的知识资产：

列表支持按审阅状态、责任人（含「无责任人」）、复审到期情况、生效状态筛选，URL 可分享。

8. 用户与权限（/admin/users） #

权限：sys_admin。

命令行也可改密：uv run kb-user-passwd --email <email> --generate（默认要求下次登录改密）。

9. 运维看板（/kb/ops） #

权限：kb_admin、sys_admin。

发信说明：业务事务只把邮件写进 app.email_outbox，真正投递由后台 worker 按 NOTIFY_OUTBOX_INTERVAL_SECONDS 轮询完成 —— 邮件服务挂了不会拖慢工单和审批接口。未配置 SMTP_HOST 时邮件只留台账并标记「仅记录」，不会真的发出去。

角色与权限 #

系统内置 6 种角色（见 app.users.role）：

部门 ACL：检索结果按 JWT 中的 depts 过滤（含 public）。例如 HR 文档仅 hr 部门用户可见；非 HR 用户问「年假有几天」应 0 命中（黄金集门禁校验）。

账号状态校验：每次请求都会带缓存地核对数据库里的账号状态与角色。账号被停用、锁定，或角色被改动时，旧令牌最长在 AUTH_STATUS_CACHE_SECONDS（默认 30 秒）后失效，不必等 JWT 过期。

前端路由守卫（RoleRoute、KbAdminRoute）仅为体验优化；真实权限以后端为准。

测试账号 #

密码不再写在代码里。首次启动时，AUTH_BOOTSTRAP_PASSWORDS=true（默认）会给所有还没有密码哈希的账号写入 AUTH_INITIAL_PASSWORD（默认 Kb@Init2026）并打上「必须改密」标记，首次登录后会被强制要求改密。

生产环境务必把 AUTH_BOOTSTRAP_PASSWORDS 设为 false，改用 uv run kb-user-passwd --email <email> --generate 逐个下发口令。

种子数据还包含：

• 知识空间 space_faq（公开）、space_hr（人事）、space_support（客服）
• 演示订单 A1001～A1005，覆盖已发货 / 运输中 / 已签收 / 退款中 / 已取消，其中 A1001～A1003 属于张三，A1004/A1005 属于没有系统账号的外部客户「李四」（只能客服代查）

环境变量 #

复制 .env.example 为 .env。下表列出常用项；完整注释见 .env.example。

必填 #

应用与鉴权 #

通知与发信 #

模型 #

文档与检索 #

功能开关 #

观测（可选） #

后端 API 参考 #

所有业务接口前缀：/api/v1。除 healthz、readyz、auth/login、auth/password-policy 外均需 Header：

Authorization: Bearer <access_token>

健康检查 #

鉴权与用户 #

工作台与通知 #

账号管理（sys_admin） #

知识库与摄入 #

检索与问答 #

多轮会话 #

工单 #

订单 #

审批 #

管理与审计 #

Agent 工具一览 #

MCP 启用后额外挂载 ticket_* 前缀工具（需另开 kb-mcp-ticket）。

CLI 工具 #

在 backend/ 目录下执行：

API 调用示例（PowerShell） #

# 登录
$token = (Invoke-RestMethod http://127.0.0.1:8000/api/v1/auth/login `
  -Method POST -ContentType 'application/json' `
  -Body '{"email":"kbadmin@example.com","password":"Kb@Init2026"}').access_token
$headers = @{ Authorization = "Bearer $token" }

# 上传文档
curl.exe -X POST http://127.0.0.1:8000/api/v1/documents `
  -H "Authorization: Bearer $token" `
  -F "file=@backend/tests/fixtures/refund.md" `
  -F "space_id=space_faq" `
  -F "dept=public" `
  -F "title=退换货政策"

# 创建会话并提问
$thread = Invoke-RestMethod http://127.0.0.1:8000/api/v1/threads `
  -Method POST -Headers $headers -ContentType 'application/json' -Body '{}'
Invoke-RestMethod "http://127.0.0.1:8000/api/v1/threads/$($thread.thread_id)/messages" `
  -Method POST -Headers $headers -ContentType 'application/json' `
  -Body '{"content":"多少天内可以无理由退货？"}'

测试与 CI #

后端 #

Set-Location backend
uv run pytest -q
# 黄金集（需 PostgreSQL）
uv run pytest tests/test_golden_v0.py tests/test_eval_gates.py -q
uv run kb-golden-report --out artifacts/golden_report.json --fail-on-gate

前端 #

Set-Location frontend
npm run lint
npm run build
npm run openapi:types   # 生成 src/api/schema.d.ts

GitHub Actions：.github/workflows/ci.yml（pytest + golden 门禁 + 前端 build）。

生产部署 #

构建前端 #

Set-Location frontend
npm run build
# 产物 → frontend/dist/

运行后端 #

Set-Location backend
# 生产建议使用 gunicorn + uvicorn worker；Windows 单进程请用 kb-serve，
# 不要直接 `uvicorn ... --no-reload`（ProactorEventLoop 与 psycopg 不兼容）
uv run kb-serve --no-reload --host 0.0.0.0 --port 8000

Nginx 同域 #

参考 deploy/nginx.conf.example：

• 静态资源：/ → dist/
• API：/api/ → 后端
• SSE：必须 proxy_buffering off、proxy_read_timeout 足够长

运维 #

生产环境请更换 APP_SECRET_KEY、数据库密码与 API Key；把 AUTH_BOOTSTRAP_PASSWORDS 设为 false，不要用统一初始口令当生产认证。

相关文档 #

常见问题 #

后端启动报 ValidationError #

检查项目根目录 .env 是否包含 DATABASE_URL、DEEPSEEK_API_KEY、DASHSCOPE_API_KEY。

数据库未就绪 / readyz 503 #

docker compose ps          # 确认 healthy
uv run python -m app.db.migrate up

前端无法访问 API #

• 开发：确认后端在 8000 端口，且 Vite dev server 已启动（代理仅 dev 生效）。
• 生产：配置 Nginx 或设置 VITE_API_BASE_URL 为完整 API 前缀。

Docker Hub 拉取失败 #

国内无法访问 auth.docker.io 时，项目 已默认 使用 DaoCloud 基础镜像：

docker compose up --build -d

若仍失败，在 Docker Desktop → Settings → Docker Engine 添加：

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

保存并 Restart Docker 后重试。海外环境可改用官方镜像：

docker compose build --build-arg PGVECTOR_IMAGE=pgvector/pgvector:pg16

5432 端口被占用 #

修改 docker-compose.yml 端口映射（如 5433:5432），并同步更新 .env 中 DATABASE_URL。

问答显示「模型超时」但模型正常 #

若 PostgreSQL 短暂不可用，旧版本可能将审计写入失败误报为模型超时；当前版本已降级处理。请同时检查 readyz 与数据库连接。

Windows 下 kb-serve --no-reload 一直无法就绪 #

psycopg 异步连接池不能跑在 Windows 默认的 ProactorEventLoop 上。请用 uv run kb-serve --no-reload（会切到 SelectorEventLoop），不要绕过它直接 uvicorn app.main:app --no-reload。带 --reload 的开发模式不受影响。

员工无法查单 / 发信 #

符合设计：仅 support、kb_admin、sys_admin 拥有 lookup_order / send_email 工具。访客访问 /orders、/tickets 会得到 403。

演示速查（5 分钟） #

1. S1 知识问答：`zhang@example.com` → 问「多少天内可以无理由退货？」→ 有引用；问「食堂几点开饭？」→ 拒答。
2. S2 知识库：`kbadmin@example.com→/kb/documents上传refund.md` → 等待 succeeded → 问答验证；可改责任人 / 生效期，过期文档不再被检索。
3. S5 Agent：`support@example.com` → 问「查 A1001」「算 12+8」「帮我建工单投诉物流」→ 工具步骤可见；员工账号问查单会提示需要客服权限。
4. HITL：`support@example.com→ 问答请求发信 →approver@example.com→/approvals` 批准。
5. 工单生命周期：员工提单 → 客服认领 / 回复 / 内部备注 → 员工在顶栏看到通知 → 解决后评分关闭。
6. 订单与退款：/orders 打开 A1001 → 发起退款（超额会被可退余额拦截）→ 审批人在 /approvals/flows 处理。

联调冒烟（需后端已启动）：uv run python scripts/smoke_productized.py。

更多场景见 docs/MVP_SCENARIOS.md。