{"id":50481127,"url":"https://github.com/however-yir/nebula-kb","last_synced_at":"2026-06-01T17:32:11.454Z","repository":{"id":349746335,"uuid":"1202993466","full_name":"however-yir/nebula-kb","owner":"however-yir","description":"Local-first knowledge asset lifecycle platform — ingestion, governance, retrieval, feedback loops \u0026 ops dashboard. Built with Django, PostgreSQL (pgvector), Redis.","archived":false,"fork":false,"pushed_at":"2026-05-22T08:13:45.000Z","size":86786,"stargazers_count":22,"open_issues_count":19,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T12:41:09.984Z","etag":null,"topics":["agent-platform","django","knowledge-base","llm","local-ai","postgresql","rag","redis"],"latest_commit_sha":null,"homepage":"https://however-yir.github.io/projects/nebula-kb/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/however-yir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T16:03:09.000Z","updated_at":"2026-05-22T08:09:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/however-yir/nebula-kb","commit_stats":null,"previous_names":["however-yir/lzkb","however-yir/nebula-kb"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/however-yir/nebula-kb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/however-yir%2Fnebula-kb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/however-yir%2Fnebula-kb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/however-yir%2Fnebula-kb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/however-yir%2Fnebula-kb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/however-yir","download_url":"https://codeload.github.com/however-yir/nebula-kb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/however-yir%2Fnebula-kb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33786896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-platform","django","knowledge-base","llm","local-ai","postgresql","rag","redis"],"created_at":"2026-06-01T17:32:10.637Z","updated_at":"2026-06-01T17:32:11.446Z","avatar_url":"https://github.com/however-yir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NebulaKB - 知识资产生命周期平台 | Knowledge Operations Hub\n\n[![Build](https://github.com/however-yir/nebula-kb/actions/workflows/build-and-push.yml/badge.svg)](https://github.com/however-yir/nebula-kb/actions/workflows/build-and-push.yml)\n[![Tests](https://github.com/however-yir/nebula-kb/actions/workflows/nebulakb-tests.yml/badge.svg)](https://github.com/however-yir/nebula-kb/actions/workflows/nebulakb-tests.yml)\n[![Docs](https://img.shields.io/badge/docs-文档-0A7EFA)](./docs/)\n[![License](https://img.shields.io/badge/license-GPL--3.0-16A34A)](./LICENSE)\n[![Status](https://img.shields.io/badge/status-active-2563EB)](https://github.com/however-yir/nebula-kb)\n\n\u003e **Matrix role:** `nebula-kb` owns the knowledge asset lifecycle: ingestion, governance, retrieval quality, feedback loops, and operations dashboards. For the Spring AI backend platform layer, see [`knowledgeops-agent`](https://github.com/however-yir/knowledgeops-agent).\n\u003e\n\u003e Status: `active`\n\u003e\n\u003e Matrix: [knowledgeops-agent](https://github.com/however-yir/knowledgeops-agent) · [tianji-ai-agent](https://github.com/however-yir/tianji-ai-agent) · [nebula-kb](https://github.com/however-yir/nebula-kb) · [forgepilot-studio](https://github.com/however-yir/forgepilot-studio) · [however-microservices-lab](https://github.com/however-yir/however-microservices-lab)\n\n**NebulaKB** is a local-first knowledge asset lifecycle platform for teams that need measurable knowledge quality — combining document ingestion, semantic indexing (pgvector), retrieval-augmented Q\u0026A, human feedback loops, and an operations dashboard. Built with Django, PostgreSQL, and Redis. For the enterprise Spring AI RAG backend, see [knowledgeops-agent](https://github.com/however-yir/knowledgeops-agent).\n\nNebulaKB 面向知识运营团队，不是泛泛的知识库或 RAG 示例，而是把知识资产的入库、治理、检索、反馈、回看和运营后台串成一条可演示、可测试、可度量的工作流。\n\n\u003e 定位一句话：NebulaKB 负责让知识资产持续变好，knowledgeops-agent 负责提供 Spring AI 企业后端工程基线。\n\n![NebulaKB demo](docs/assets/screenshots/demo.gif)\n\n## 项目快照\n\n- 定位：知识资产生命周期平台，而不是通用聊天工作台。\n- 亮点：Django + PostgreSQL + Redis、多模型接入、知识资产生命周期、检索链路可观测、质量评测闭环。\n- 最短运行路径：`python apps/manage.py migrate \u0026\u0026 python main.py dev web`\n- 作品矩阵角色：`NebulaKB` 负责知识资产运营层，和企业 RAG 后端、业务 Agent、AI 工程执行平台、云原生微服务实验室形成互补。\n- 证据索引：[docs/evidence/README.md](docs/evidence/README.md)\n\n## 与 knowledgeops-agent 的边界\n\n| 维度 | NebulaKB | knowledgeops-agent |\n|---|---|---|\n| 主定位 | 知识资产生命周期平台 | 企业级 Spring AI RAG 后端平台 |\n| 关键用户 | 知识运营、客服质检、内容治理、业务管理员 | 后端工程师、AI 平台工程师、架构负责人 |\n| 关键链路 | 文档入库、解析、切片、索引、检索问答、反馈闭环、低质答案回看 | Spring AI 接入、租户隔离、异步任务、鉴权审计、可观测、部署基线 |\n| 产品表面 | 运营后台、知识库列表、文档入库、问答反馈、质量指标 | API、Spring Boot 服务、鉴权、队列、向量库、监控栈 |\n| 成功标准 | 知识命中率提升、低质答案率下降、未命中问题可治理 | 后端能力完整、接口稳定、部署和观测可验证 |\n\n## 产品截图\n\n![Knowledge Health Dashboard](docs/assets/screenshots/knowledge-health-dashboard.svg)\n\n| 运营后台 | 知识库列表 |\n|---|---|\n| ![运营后台截图](docs/assets/screenshots/admin-dashboard.svg) | ![知识库列表截图](docs/assets/screenshots/knowledge-base-list.svg) |\n\n| 文档入库 | 问答反馈 |\n|---|---|\n| ![文档入库截图](docs/assets/screenshots/document-ingestion.svg) | ![问答反馈截图](docs/assets/screenshots/qa-feedback.svg) |\n\n## 生命周期验证资产\n\n| 阶段 | 平台能力 | 验证资产 |\n|---|---|---|\n| 入库 | 文件上传、来源登记、知识库归属、租户边界 | `demo-data/knowledge-sample/`、`apps/knowledge/tests.py` |\n| 治理 | 解析状态、失败原因、切片结果、待更新标记 | `apps/knowledge/services/asset_lifecycle_demo.py` |\n| 检索 | 命中排序、引用返回、空结果兜底 | `scripts/demo_lifecycle.py` |\n| 反馈 | 人工评分、低质答案沉淀、闭环状态 | `docs/demo-script.md` |\n| 运营 | 知识命中率、低质答案率、未命中问题、热门知识、待更新知识 | `docs/observability.md` |\n\n## 矩阵角色\n\nNebulaKB 是 however-yir AI 工程作品矩阵中的“知识运营中枢”，负责展示知识资产从文档接入、解析、切片、索引、检索，到问答反馈、低质答案回看和知识质量优化的生命周期闭环。完整项目矩阵见 [docs/project-matrix.md](docs/project-matrix.md)。\n\n## 同系列相关项目\n\n| Repo | 角色 | 与 NebulaKB 的关系 |\n|---|---|---|\n| [`local-ai-hub`](https://github.com/however-yir/local-ai-hub) | 本地 AI 工作台与统一入口 | 更偏模型接入、本地工具台和团队日常使用入口 |\n| `yourrag` | 企业 RAG / Agent 交付参考 | 更偏私有化交付方案和 RAG + Agent 组合实践，核心引擎内嵌于 [`engines/yourrag/`](engines/yourrag/) |\n\n## 目录\n\n- [1. 项目概述](#1-项目概述)\n- [2. 目标与场景](#2-目标与场景)\n- [3. 核心能力](#3-核心能力)\n- [4. 技术栈](#4-技术栈)\n- [5. 仓库结构](#5-仓库结构)\n- [6. Quick Start](#6-quick-start)\n- [7. 配置建议](#7-配置建议)\n- [8. 开发与测试](#8-开发与测试)\n- [9. 协作与发布](#9-协作与发布)\n- [10. 路线图](#10-路线图)\n- [11. 贡献指南](#11-贡献指南)\n- [12. License](#12-license)\n\n## 1. 项目概述\n\n本仓库围绕知识资产生命周期组织代码和文档：知识进入系统后，要能被解析、切片、索引、检索、反馈、回看和持续治理。它的价值不只是“能问答”，而是把知识命中率、低质答案、待更新知识和运营后台放到同一条可演示链路里。\n\n## 2. 目标与场景\n\n适用场景：\n\n- 作为业务功能开发与验证的基础仓库。\n- 作为团队内部协作与知识沉淀的载体。\n- 作为后续扩展和二次开发的起点。\n\n相对主作品矩阵与同系列项目的职责边界：\n\n- `NebulaKB` 更像知识入库、知识治理、检索问答与质量反馈闭环平台。\n- `knowledgeops-agent` 更偏企业级 Spring AI RAG 后端、安全治理与可观测基线。\n- `tianji-ai-agent` 更偏业务 Agent 流程、Tool Calling、多智能体路由和课程业务闭环。\n- `forgepilot-studio` 更偏 AI 工程执行、任务编排、审计回放和团队工作台。\n- `however-microservices-lab` 更偏云原生微服务、多语言服务治理、Kubernetes 和 AI 服务集成。\n- `local-ai-hub` 与 `yourrag` 作为同系列相关项目，分别偏本地 AI 工作台和企业 RAG/Agent 交付参考。\n\n## 3. 核心能力\n\n- 支持知识入库、索引、检索与问答闭环。\n- 支持本地化部署与可控的数据边界。\n- 支持持续扩展知识源与应用场景。\n- **安全加固**：SECRET_KEY 生产环境强制校验、DRF 速率限制、SSO (OIDC/SAML) 接入、审计日志脱敏、安全响应头。\n- **可观测性**：Prometheus 指标暴露、OpenTelemetry 链路追踪、Grafana 预置仪表盘、Celery Flower 监控。\n- **数据库运维**：自动化备份（Celery 任务 + cron 脚本）、PgBouncer 连接池、HNSW 索引可调参数。\n- **CI/CD**：60% 覆盖率门禁、Vitest 前端测试、Helm Chart、Docker 非 root 运行。\n- **性能优化**：检索结果缓存、Gunicorn 可配 workers/threads、Celery 并发可配、LLM Fallback 降级。\n- **API 版本化**：`/api/v1/` 前缀路由、知识版本管理、批量导入导出。\n\n### 3.1 典型用例\n\n| 场景 | 主要模块 | 目标结果 |\n|---|---|---|\n| 文档入库与解析 | `apps/knowledge` | 把资料转为可检索知识资产 |\n| 检索问答与运营 | `apps/chat`, `ui/` | 形成知识问答与后台运营闭环 |\n| 模型接入与切换 | `apps/models_provider`, `apps/local_model` | 对接本地或远端模型 |\n| 安装与部署 | `installer/` | 本地快速起服与依赖初始化 |\n| 应用扩展 | `apps/application`, `appstore/nebula.json` | 面向后续插件化或应用化拓展 |\n\n### 3.2 模块职责矩阵\n\n| 路径 | 角色 |\n|---|---|\n| `apps/knowledge` | 知识库核心、入库与检索相关能力 |\n| `apps/chat` | 问答交互与知识调用入口 |\n| `apps/models_provider` | 模型提供方接入层 |\n| `apps/common` / `apps/system_manage` | 平台公共与系统管理能力 |\n| `installer/` | 本地部署、数据库与 Redis 启动辅助 |\n| `ui/` | 管理后台与问答前端（Vue 3 + Vite + TypeScript + Ant Design） |\n\n## 4. 技术栈\n\n- **后端**：Python 3.11 · Django 5.2 · DRF · Celery · django-prometheus\n- **数据**：PostgreSQL + pgvector · Redis · django-redis 缓存\n- **AI/LLM**：LangChain · LangGraph · OpenAI / Anthropic / DeepSeek / Ollama / DashScope 等多模型接入\n- **前端**：Vue 3 · Vite · Vitest\n- **部署**：Docker · Helm (Kubernetes) · PgBouncer · Gunicorn\n- **CI/CD**：GitHub Actions · coverage 60% 门禁 · pip-audit 依赖审计 · Helm lint\n\n## 5. 仓库结构\n\n建议优先阅读：\n\n- `README.md`：项目入口与整体说明。\n- `README_CN.md`：更细化的中文交付说明。\n- `apps/`、`ui/`：后端与界面主目录。\n- `installer/`：安装、初始化与部署辅助脚本。\n\n## 6. Quick Start\n\n1. 克隆仓库并进入目录：\n\n```bash\ngit clone https://github.com/however-yir/nebula-kb.git\ncd nebula-kb\n```\n\n2. 安装依赖并初始化：\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -U pip\n[ -f requirements.txt ] \u0026\u0026 pip install -r requirements.txt\n[ -f pyproject.toml ] \u0026\u0026 pip install -e .\npython apps/manage.py migrate\n```\n\n3. 启动开发环境：\n\n```bash\npython main.py dev web\n```\n\n### 启动前端\n\n```bash\ncd ui\nnpm ci\nnpm run dev      # 管理后台 (http://localhost:5173)\nnpm run chat     # 问答界面 (http://localhost:5174)\n```\n\n### 6.1 本地依赖一键准备（PostgreSQL / Redis / 可选 Ollama）\n\n首次启动建议先执行：\n\n```bash\ncp .env.example .env\n# 修改 .env 中所有 CHANGE_ME_* 密码\n\n./scripts/bootstrap-local.sh --start\n# 如需一起拉起 Ollama:\n# ./scripts/bootstrap-local.sh --start --with-ollama\n```\n\n该脚本会：\n\n1. 校验 `.env` 是否存在并阻止占位密码直接启动；\n2. 按 `docker-compose.dev.yml` 拉起 PostgreSQL / Redis；\n3. 自动确保 `pgvector` 扩展已启用；\n4. 可选拉起本地 Ollama，降低首次联调门槛。\n\n### 6.2 极速安装脚本（macOS / Windows）\n\nmacOS:\n\n```bash\n./scripts/quick-install-mac.sh\n# 如需一起拉起 Ollama:\n# ./scripts/quick-install-mac.sh --with-ollama\n```\n\nWindows (PowerShell):\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\quick-install-win.ps1\n# 如需一起拉起 Ollama:\n# powershell -ExecutionPolicy Bypass -File .\\scripts\\quick-install-win.ps1 -WithOllama\n```\n\n快速脚本会自动完成：\n\n1. 初始化 `.env` 并替换 `CHANGE_ME_*` 占位密钥；\n2. 创建 `.venv` 并安装 Python 依赖；\n3. 拉起 PostgreSQL / Redis（可选 Ollama）并确保 `pgvector`；\n4. 执行数据库迁移。\n\n## 7. 配置建议\n\n建议按 `dev / staging / prod` 分层配置，并将密钥类信息放入环境变量或密钥管理系统。\n\n### 7.1 部署形态矩阵\n\n| 形态 | 入口 | 适合场景 |\n|---|---|---|\n| 开发模式 | `python main.py dev web` | 本地功能开发 |\n| 一键本地启动 | `installer/start-all.sh` | 演示与快速验证 |\n| 分组件启动 | `installer/start-postgres.sh` / `installer/start-redis.sh` / `installer/start-maxkb.sh` | 更接近生产的联调环境 |\n| 可运维分离部署 | `docker compose -f deploy/docker-compose.operational.yml up -d` | web / worker / scheduler / PostgreSQL / Redis / object storage 独立部署 |\n\n运维部署、环境变量契约、健康检查、备份恢复和回滚流程见 [docs/ops/operability.md](docs/ops/operability.md) 与 [docs/ops/postgres-backup-restore.md](docs/ops/postgres-backup-restore.md)。\n\n## 8. 开发与测试\n\n推荐流程：\n\n1. 基于默认分支创建功能分支。\n2. 小步提交并保持提交目标单一。\n3. 本地完成构建与测试后再推送。\n4. 通过 Pull Request 完成评审与合并。\n\n本地验证入口：\n\n```bash\npython apps/manage.py check\npython apps/manage.py test apps.knowledge\ncd ui \u0026\u0026 npm ci \u0026\u0026 npm test \u0026\u0026 npm run type-check \u0026\u0026 npm run build\nbash scripts/quality-gate.sh all          # 覆盖率 + lint + 结构检查\nhelm lint deploy/helm/nebula-kb           # Helm Chart 校验\npython scripts/demo_lifecycle.py\n```\n\n### 8.1 评测与验收路径\n\n建议把以下链路作为最小验收闭环：\n\n1. 导入一组真实文档并验证索引完成。\n2. 对同一问题做检索命中检查与答案可解释性检查。\n3. 验证不同模型提供方下的响应一致性与延迟。\n4. 校验后台管理入口、知识集管理与权限边界是否稳定。\n\n## 9. 协作与发布\n\n建议使用语义化版本，发布说明应包含新增、修复与兼容性说明。\n\n## 10. 路线图\n\n### 已完成 (v2.0.0)\n\n- [x] SECRET_KEY 生产环境强制校验\n- [x] DRF 速率限制 (Anon/User/KnowledgeSearch)\n- [x] SSO 框架 (OIDC/SAML Provider 模型)\n- [x] 审计日志中间件（敏感字段脱敏）\n- [x] 安全响应头中间件\n- [x] django-prometheus 指标暴露\n- [x] OpenTelemetry 链路追踪中间件\n- [x] Grafana 预置仪表盘 + 数据源配置\n- [x] Celery Flower 服务\n- [x] 自动化备份任务 + cron 脚本\n- [x] PgBouncer 连接池服务\n- [x] HNSW 索引参数可配置\n- [x] CI 覆盖率门禁 60%\n- [x] Vitest 前端测试框架\n- [x] Helm Chart (Kubernetes 部署)\n- [x] Docker 非 root 用户运行\n- [x] 检索结果缓存\n- [x] Gunicorn workers/threads 可配置\n- [x] Celery 并发可配置\n- [x] LLM Fallback 降级管理器\n- [x] API v1 路由前缀\n- [x] 知识版本管理序列化器\n- [x] 批量导入导出序列化器\n\n### 后续规划\n\n1. 稳定主流程与关键接口。\n2. 优化模块边界与可观测性。\n3. 完善自动化测试与文档体系。\n\n## 11. 贡献指南\n\n提交建议包含：变更背景、实现说明、验证结果、风险评估。\n\n## 12. License\n\n请以仓库内现有 License 文件为准。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhowever-yir%2Fnebula-kb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhowever-yir%2Fnebula-kb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhowever-yir%2Fnebula-kb/lists"}