# RAGMaster

**Repository Path**: lobyliang/ragmaster

## Basic Information

- **Project Name**: RAGMaster
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库大师 (RAGMaster)

> Dify 风格的多租户知识库平台，由**软件工坊 v10.0** 编排开发（需求 → 设计 → 开发 → 测试 → 部署）。

## 一句话

支持 Dify 全部知识库与切片类型、知识库群/领域 L0/L1 分层摘要与智能路由召回、LLM/Embedding/Rerank 模型供应商管理、召回测试与双层回测、chunk 附件与多格式预览、可插拔权限（默认钉钉）、用户 Key + MCP/REST 全量开放接口。

## 技术栈

| 层 | 选型 |
|---|---|
| 后端 | Python 3.12 · FastAPI · SQLAlchemy 2.0 (async) · Pydantic v2 · Alembic |
| 任务 | 进程内线程池 + DB 任务表（**不使用 Celery**） |
| 前端 | Next.js 15 · React · TypeScript · Tailwind CSS v4 · shadcn/ui |
| 关系库 | PostgreSQL 16（多租户 `tenant_id` 行级隔离） |
| 向量库 | Weaviate（抽象 `VectorStore`，可替换；chunk 全文 PG 与 Weaviate 双写） |
| 缓存 | Redis 7（限流/锁/进度） |

## 目录

```
project-docs/                 # 工坊数据与产物
  model/model.json            # 唯一真相源（SSOT）
  state.json                  # 工坊阶段状态
  requirements/               # 需求原始输入/模块清单/假设/裁决/默认参数
  drafts/                     # 各阶段子 agent 草稿（落库前）
  reports/                    # SRS 等报告
docs/
  research/                   # Dify / OpenViking 调研报告
  design/architecture.md      # 系统架构设计
scripts/                      # 编排器脚本（种子/落库/SRS）
.dsh/skills/software-workshop # 软件工坊 v10.0 skill
```

## 工坊流程（当前进度）

已完成 **48/55 阶段**，推进到 `shipping`（代码与测试全绿）：

- 需求 → 设计 → WBS/测试用例 → 5 个硬门禁 → 后端（M01–M11）→ 前端（31 页）→ E2E → 评审/加固
- 验证：后端 **533 tests**、前端 **84 tests**、E2E **37/37**、契约 **155/155**、端点存活 175/175、DB schema 44/44 表
- `known_issues` 已全部关闭（修复或经用户接受），`dod_gate` 无 BLOCKING

## 部署

```bash
cp .env.deploy.example .env.deploy   # 中间件开关（PG/REDIS/MINIO/WEAVIATE_ENABLED）
cp .env.example backend/.env         # 填写 JWT_SECRET / CREDENTIAL_ENCRYPTION_KEY / 模型 Key
./deploy.sh                          # 构建 + 建库 + 迁移 + 启动 + 健康检查
./local.sh                           # 本地开发（热重载，复用本机中间件）
./local.sh status                    # 查询后端/前端运行状态
./local.sh stop                      # 停止由 local.sh 启动的后端/前端
./local.sh stop --force              # 连同占用端口的其它实例一起停止
                                     # （未显式指定 BACKEND_PORT 时不会动默认 8100）
./local.sh restart                   # 先停止再启动
./local.sh clean                     # 停止并清理 web/.next 缓存（修复静态资源 404）
```

容器编排见 `docker-compose.yml`；默认复用本机已有中间件，开关置 `true` 时由编排自带。
部署/回滚/发布策略见 `docs/deploy/`。

### 首次初始化（首启向导）

全新部署（无租户/无平台管理员）时，打开前端会自动跳转到 `/setup` 初始化向导，
创建**第一个租户 + 平台超级管理员**；该账号 `is_platform_admin=true` 且为租户 `owner`，
创建后自动登录。初始化完成后向导自动关闭，`POST /api/v1/system/bootstrap` 返回 403。

- 判定依据是持久化标志 `system_configs['platform.initialized_at']`（只置位不清除），
  因此即使停用唯一租户/管理员，也不会重新开放初始化。
- 命令行初始化（可选，等价于向导）：`cd backend && UV_CACHE_DIR=$PWD/.uv-cache uv run --no-sync python scripts/seed_admin.py`
- 清空业务数据回到未初始化（保留表结构/迁移/平台级配置）：
  `cd backend && UV_CACHE_DIR=$PWD/.uv-cache uv run --no-sync python scripts/reset_business_data.py --yes`


查看当前阶段：

```bash
cat project-docs/state.json
bash .dsh/skills/software-workshop/sw context_builder.py context --stage <stage> --module <Mxx>
```

## 关键数据规模

- 模块：11（M01–M11）
- 角色：7
- EARS 需求：56
- 数据表：40
- 契约：11 份 / 149 个 API
- ADR：10
- 已确认裁决：30 条（RUL-01..30）

## 开发约定（详见 `docs/design/architecture.md`）

- 契约优先：契约与代码不一致时默认改代码；改契约须人工确认（工坊宪章 C1）。
- 数据入口：模型数据读写只经 `context_builder.py` / `model_manager.py`。
- 多租户：所有业务表含 `tenant_id`，仓储层强制注入。
- 请求追踪：统一 `request_id`。
- 权限：知识库为最小授权单位，知识库群目录式继承；主体 = 用户/部门/角色。

## 基础设施（复用本机现有服务，不重复安装）

本机已运行 Dify 的中间件（来源：`/home/ubuntu/scode/lincontrol-dify/docker/docker-compose.yaml`），RAGMaster **直接复用**，不新建实例：

| 服务 | 地址 | 说明 |
|---|---|---|
| PostgreSQL 15 | `localhost:5432` | 在其中新建独立库 `ragmaster`（与 `dify` / `dify_plugin` 隔离） |
| Redis 6 | `localhost:6379` | 使用 `db 1`，避免与 Dify 的 `db 0` 冲突；带密码 |
| Weaviate 1.27 | `localhost:8080` | 开启 API Key 鉴权；RAGMaster 使用独立 class 命名空间（含 tenant_id） |

连接信息见 `backend/.env`，机器可读的服务引用见 `infra/services.yaml`。
`scripts/check_config_consistency.py` 会校验 `.env ↔ Settings ↔ infra/services.yaml` 三者一致。

```bash
# 无需 docker compose up；本机服务应已在运行
cd backend
export UV_CACHE_DIR=$PWD/.uv-cache
uv run --no-sync alembic upgrade head          # 在 ragmaster 库建 42 张表
uv run --no-sync uvicorn app.main:app --port 8100
```

> 注意：Weaviate 的 RAGMaster class 统一以 `ragmaster_` 前缀 + `tenant_id` 命名，避免与 Dify 既有 class 冲突。