1. 项目定位与核心能力

rag-web-ui 是一个面向 RAG（Retrieval-Augmented Generation，检索增强生成）场景的开源 Web 应用，提供从「文档上传 → 知识库构建 → 问答交互」的一站式能力。仓库同时提供中英两份 README，说明其面向多语种用户的设计意图 资料来源：README.md:1-30 资料来源：README.zh-CN.md:1-30。

核心项目括：

• 多源文档支持：用户可在前端上传文件，由后端解析、切片、向量化后存入向量库。
• 可插拔的模型提供方：通过 .env 中的 CHAT_PROVIDER、EMBEDDINGS_PROVIDER 字段切换不同 LLM 与 Embedding 后端，例如 OpenAI 兼容 API、HuggingFace Embeddings 等。
• 独立的多租户隔离：每个用户拥有独立的知识库与聊天记录（issue #49 提示多租户能力正在被持续强化）。
• 基于 LangChain 的检索链：问答时使用 LangChain 的 Runnable 组合，将「检索上下文 + 用户问题」组装为 Prompt 后送入 LLM（issue #70 中可看到 RunnableParallel<answer> 的运行链路）。

2. 整体系统架构

系统整体采用「前后端分离 + 容器化编排」的结构，运行依赖由 Docker Compose 统一声明 资料来源：docker-compose.yml:1-80。

flowchart LR
    User[浏览器用户] --> FE[Frontend<br/>React/Next.js]
    FE -- HTTP/SSE --> BE[Backend<br/>FastAPI]
    BE -- Embeddings --> EP[Embeddings Provider<br/>OpenAI / HuggingFace]
    BE -- LLM Chat --> CP[Chat Provider<br/>OpenAI 兼容]
    BE -- 向量存取 --> VDB[(ChromaDB)]
    BE -- 文件下载 --> S3[(S3 Compatible<br/>对象存储)]
    VDB -- 检索上下文 --> BE

部署形态上，仓库使用容器间网络通信：当 extra_hosts: host.docker.internal 注入后，容器内可访问宿主机服务（例如本机 LLM 端点），这对 Linux 上的 Docker 用户尤其重要 资料来源：docker-compose.yml:30-60 资料来源：docker-compose.dev.yml:1-50。

3. 后端核心模块

后端基于 FastAPI 构建，并通过统一的 lifespan 管理向量库等全局资源 资料来源：backend/app/main.py:1-80。主要组成如下：

issue #83 指出 auth.py 与 security.py 中存在 get_current_user 重复定义，建议将实现收敛在 core/security.py 并在 auth.py 中复用，这是后端代码组织层面需要关注的可维护性问题 资料来源：backend/app/api/api_v1/auth.py:1-40 资料来源：backend/app/core/security.py:1-60。

4. 数据流：从上传到问答

数据流贯穿文档处理、检索和生成三个阶段：

1. 上传与暂存：前端上传文件到后端，后端将原始文件作为临时对象写入 S3 兼容存储以便后续重试和并发消费（issue #82 中出现的 NoSuchKey 错误即发生在该环节）。
2. 解析与量化：后端拉取临时文件 → 按策略切片 → 调用 EMBEDDINGS_PROVIDER 生成向量 → 写入 ChromaDB。issue #54 提示「文档量化失败后无法重试/删除」的恢复能力是关键改进点。
3. 问答检索：用户消息经 RunnableParallel 同时调度「向量检索」与「答案生成」，检索结果作为 context 注入 Prompt，再交由 CHAT_PROVIDER 调用 LLM 完成回答 资料来源：backend/app/api/api_v1/api.py:1-50。

模型层面，v0.8.0 起 EMBEDDINGS_PROVIDER 已支持 huggingface，通过 sentence-transformers 在本地加载任意 HF Embedding 模型，与 LLM 端点的配置完全解耦 资料来源：backend/app/core/config.py:1-120。issue #71 进一步提出对接 Groq/Cerebras 等云端推理服务的需求，规划通过与 OpenAI 兼容的 VLLM 服务器协议接入。

5. 已知边界与社区关注点

综合社区反馈可归纳出当前架构上的几个常见痛点：

• 链路错误可见性：issue #70 中 KeyError('context') 暴露出检索失败时整条链直接报错，前端体验受影响；需在链内做容错回退。
• 前端渲染压力：issue #69 报告长响应下 Maximum update depth exceeded，说明对话组件在高频更新场景下需要拆分渲染粒度。
• 文档处理幂等性：issue #54 要求对量化失败的文档提供重试/删除入口，避免脏数据长期滞留。
• 部署健壮性：issue #73 反映 rag-web-ui-frontend unhealthy，通常与健康检查脚本、容器启动顺序有关，参见 deploy-local.md 排查。
• 扩展性建议：issue #84 提议引入 LangGraph 把「直接 HTTP 调用后端」升级为基于图的工作流，从而支持多步检索与工具调用。

以上反馈共同指向一个演进方向：在保持「FastAPI + LangChain + ChromaDB + S3」这一稳固主干的同时，提升链路容错、文档处理幂等以及多 Provider 适配的扩展性。

资料来源：backend/Dockerfile:1-50

1. 概览与整体职责

rag-web-ui 的后端采用典型的 FastAPI 分层架构，整体入口由 backend/app/main.py 启动并挂载两套 API 路由：受保护的 api_v1 内部接口与无需登录的 openapi 公共接口。前端通过 api_v1 完成知识库、会话、API Key 等敏感操作，通过 openapi 完成跨租户共享的问答与知识检索。资料来源：backend/app/main.py 资料来源：backend/app/api/api_v1/auth.py 资料来源：backend/app/api/openapi/api.py

后端核心系统承担三类关键职责：

• 接口编排：聚合 auth、chat、knowledge_base、api_keys 等子路由，统一鉴权与异常处理。
• 数据建模：通过 schemas/ 下的 Pydantic 模型定义用户、知识库、文档、会话、消息等实体的入参与出参。
• 服务实现：在 services/ 与 core/ 中封装 LangChain 链、向量库检索、文件存储、密码哈希等可复用逻辑。

2. API 路由层

2.1 内部路由 `api_v1`

api_v1 是登录后的受保护接口集合，统一通过 Depends(get_current_user) 完成身份校验：

• auth.py：注册、登录、获取当前用户。社区 #83 指出该文件与 core/security.py 中存在重复的 get_current_user，建议保留 core/security.py 作为唯一定义并由 auth.py 复用导入，以降低维护风险。资料来源：backend/app/api/api_v1/auth.py 资料来源：backend/app/core/security.py
• chat.py：基于 LangChain RunnableParallel 实现检索增强问答，社区 #70 中出现的 KeyError('context') 即源于该链路在缺少 context 字段时未做兜底。资料来源：backend/app/api/api_v1/chat.py
• knowledge_base.py：知识库的创建、列表、上传、删除及文档量化状态查询，承载社区 #54、#72、#82 中关于上传失败、S3 NoSuchKey 与量化重试等问题的处理路径。资料来源：backend/app/api/api_v1/knowledge_base.py
• api_keys.py：用户级别的 LLM/Embedding 凭据管理，配合 CHAT_PROVIDER 与 EMBEDDINGS_PROVIDER 环境变量切换 OpenAI、HuggingFace 等后端（v0.8.0 起支持 HuggingFace）。资料来源：backend/app/api/api_v1/api_keys.py

2.2 公共路由 `openapi`

openapi/api.py 与 openapi/knowledge.py 提供免登录的问答入口，主要用于跨租户共享、嵌入式集成或外部 webhook 场景，鉴权依赖 API Key 而非用户会话。

2.3 请求流转示意

flowchart LR
  FE[前端/外部客户端] -->|登录态| APIv1[/api/v1/*/]
  FE -->|API Key| OPEN[/openapi/*/]
  APIv1 --> Sec[core/security.py 鉴权]
  OPEN --> KeyAuth[API Key 校验]
  Sec --> Svc[services/ 业务逻辑]
  KeyAuth --> Svc
  Svc --> LLM[LLM / Embeddings]
  Svc --> VDB[ChromaDB / 向量库]
  Svc --> S3[(对象存储)]

3. 数据模型层

schemas/ 下的 Pydantic 模型承担两类作用：

• 入参校验：例如登录请求、文档上传元数据、问答请求体，强制字段类型与必填约束，避免脏数据进入服务层。
• 出参序列化：例如知识库列表、文档量化状态、消息流式响应，保证前端拿到结构稳定的 JSON。

设计上，模型层不持有数据库会话，只做字段映射与转换；持久化逻辑交由 services/ 完成，从而保持“薄模型、厚服务”的边界。

4. 服务层与认证安全

services/ 目录封装了与外部系统交互的逻辑：LangChain 链组装（解决 #70 context 缺失问题需要在此层注入默认 context）、向量库的读写（应对 #54 量化失败的重试/删除）、S3/本地混合存储（应对 #82 的 NoSuchKey）。

core/security.py 集中了认证原语：

• get_password_hash / verify_password：自 v0.7.5 起改用 bcrypt.hashpw 与 bcrypt.checkpw 直接实现，移除 passlib 并固定 BCrypt 4.0.1，确保跨平台哈希一致。资料来源：backend/app/core/security.py
• get_current_user：从 JWT 解析用户身份，建议作为唯一实现，被 api_v1/auth.py 等路由复用（参见 #83）。
• create_access_token：基于配置签发带过期的令牌。

社区已知问题与本系统直接相关：多租户隔离（#49）需要在服务层查询时按 user_id 过滤；DNS 解析失败（#36）通常发生在 httpx 调用 LLM 时，应在服务层加入重试与超时配置；上传链路（#72）的 ChromaDB 连接错误提示需结合 services/ 中的客户端初始化排查。

1. 整体职责与设计目标

rag-web-ui 的后端把"对话生成（LLM）"、"文本向量化（Embedding）"以及"向量库检索（Vector Store）"三件最容易更换实现的事，统统收敛到 backend/app/services/ 下的三个工厂模块。这种"工厂 + 抽象基类"的设计，让上层 RAG 链路（检索 → 拼装 prompt → 调用 LLM → 流式输出）只依赖统一接口，而具体后端（OpenAI、HuggingFace、ChromaDB、Qdrant 等）可以由环境变量按需切换。

这套机制直接回应了社区里出现频次较高的诉求：

• 在 v0.8.0 发布中加入了 HuggingFace Embedding 支持（#77），用户希望 LLM 和 Embedding 能各自独立指定 provider，不再被绑死在同一个 OpenAI 端点上。
• 在 Issue #71 中，社区希望接入 Groq Cloud、Cerebras 等云模型；维护者表示通过 VLLM 的 OpenAI 兼容服务即可继续复用本套工厂。
• 在 Issue #70 的 KeyError('context') 报错中，错误的根因是 LangChain Chain 在没有命中向量库时把 context 字段漏传，这也说明"检索 → 上下文注入"这条链路对工厂实现的一致性非常敏感。

2. LLM 工厂：对话模型的选择入口

LLMFactory 位于 backend/app/services/llm/llm_factory.py，其职责是根据 CHAT_PROVIDER（如 openai、vllm 等）返回 LangChain 兼容的 BaseChatModel 实例。它读取以下关键配置：

• CHAT_PROVIDER：决定走 OpenAI 协议还是其它兼容协议
• OPENAI_API_KEY、OPENAI_API_BASE：通用鉴权与端点
• OPENAI_MODEL：具体模型名

由于使用 OpenAI 兼容协议，任何暴露 /v1/chat/completions 的服务（自建 vLLM、OneAPI、以及未来的 Groq/Cerebras 代理）都可以直接接入，无需改业务代码。资料来源：backend/app/services/llm/llm_factory.py:1-80

3. Embedding 工厂：可独立切换的向量化后端

EmbeddingFactory 位于 backend/app/services/embedding/embedding_factory.py，其与 LLM 工厂解耦，通过 EMBEDDINGS_PROVIDER 独立路由：

设计要点在于：LLM 和 Embedding 的 *_PROVIDER、*_API_BASE、*_MODEL 全部是分开的，调用方不会假设两者来自同一家服务。这正好解决了 Issue #77 中"OpenAI 只有一个端点"的痛点。资料来源：backend/app/services/embedding/embedding_factory.py:1-120

4. 向量库工厂：检索后端的统一抽象

向量检索是 RAG 质量的关键，仓库用"基类 + 多个实现 + 顶层工厂"的分层方式来组织。

4.1 抽象基类

backend/app/services/vector_store/base.py 定义了所有向量库必须实现的接口，覆盖：集合/库的创建与删除、文档写入（带 embedding）、相似度检索、删除文档等。这样上层 RAG 逻辑只面向 VectorStoreBase，对具体后端无感知。资料来源：backend/app/services/vector_store/base.py:1-90

4.2 工厂路由

backend/app/services/vector_store/factory.py 读取 VECTOR_STORE_PROVIDER（如 chroma、qdrant），返回对应的实现单例。工厂内通常会缓存实例，避免每个请求都重建客户端连接。资料来源：backend/app/services/vector_store/factory.py:1-60

4.3 ChromaDB 实现

backend/app/services/vector_store/chroma.py 是默认实现，封装了 Chroma 的 PersistentClient/HttpClient 两种模式，并负责把 LangChain 的 Document 转换成 Chroma 的 add/query 调用。需要注意：社区中 Issue #70 出现的 KeyError('context') 往往发生在 Chroma 检索返回为空、上下文键未被注入 prompt 模板时，需在调用层做空结果兜底。资料来源：backend/app/services/vector_store/chroma.py:1-150

4.4 Qdrant 实现

backend/app/services/vector_store/qdrant.py 提供 Qdrant 客户端封装，支持集合的 recreate_collection、点（point）写入以及基于 search 的相似度检索。当用户希望使用自有部署的 Qdrant 时，只需在 .env 中切换 provider 即可，业务侧无感知。资料来源：backend/app/services/vector_store/qdrant.py:1-150

5. 三者协作：从查询到回答

下面是请求在三个工厂之间流转的简化时序：

sequenceDiagram
    participant U as 用户/前端
    participant API as RAG API
    participant LLM as LLMFactory
    participant EMB as EmbeddingFactory
    participant VS as VectorStoreFactory
    participant DB as 向量库(Chroma/Qdrant)
    U->>API: 发送问题
    API->>EMB: embed_query(问题)
    EMB-->>API: 向量
    API->>VS: similarity_search(vector, top_k)
    VS->>DB: 查询近邻
    DB-->>VS: 命中文档
    VS-->>API: 上下文片段
    API->>LLM: invoke(prompt = 上下文 + 问题)
    LLM-->>API: 流式回答
    API-->>U: SSE 流式响应

阅读这张图时建议结合社区反馈：例如 Issue #54 提到的"文档处理失败后无法重试/删除"，根因是 vector_store 的写入与"知识库元数据"在 Document 维度上未完全对齐，导致 UI 拿不到处理失败文档的句柄——这正是后续在 base.py 与上层服务间需要补齐"幂等写入 + 失败回滚"的地方。资料来源：backend/app/services/vector_store/base.py:30-90、backend/app/services/vector_store/factory.py:1-60、backend/app/services/embedding/embedding_factory.py:40-120、backend/app/services/llm/llm_factory.py:30-80

6. 选型与扩展建议

• 优先沿用 OpenAI 协议：除非有强隐私要求，LLM 与 Embedding 都建议走 OpenAI 兼容服务，可最快复用现有 provider 路由。
• 本地 Embedding：v0.8.0 起支持 HuggingFace provider，适合在没有外网的环境（如内网部署）启用，但要注意首次加载模型耗时与内存占用。
• 向量库选型：开发/小规模用 Chroma 即可；如需分布式、过滤检索或更大规模，可切到 Qdrant，二者通过 VECTOR_STORE_PROVIDER 切换，业务代码无需改动。
• 关注社区演进方向：Issue #84 提出未来使用 LangGraph 改造检索流程，届时本套工厂抽象将作为节点（Node）继续复用。

1. 部署架构总览

项目通过 docker-compose.yml 统一编排前端、后端以及 ChromaDB 三个核心服务，以容器网络互通的方式提供完整 RAG 体验：

docker-compose.dev.yml 在生产编排之上增加了开发期的卷挂载、热重载与调试端口，使开发者可以直接编辑源码而无需重建镜像。资料来源：docker-compose.yml:1-40 资料来源：docker-compose.dev.yml:1-30

在 v0.7.3 版本中，编排文件针对 Linux Docker 主机兼容性进行了修复：所有服务均显式声明 extra_hosts: host.docker.internal:host-gateway，以便容器内能够解析宿主机的本地服务（如本地 LLM 端点）。资料来源：docker-compose.yml:host.docker.internal 配置块 同时，backend/Dockerfile 与 backend/Dockerfile.dev 显式安装了 curl，用于健康检查与端点探测。资料来源：backend/Dockerfile:curl 安装步骤 资料来源：backend/Dockerfile.dev:curl 安装步骤

2. 前端服务：Next.js 容器化

前端基于 Next.js 构建，产物由 frontend/Dockerfile 进行多阶段构建：先在 builder 阶段执行依赖安装与 next build，再在 runner 阶段仅保留 .next 产物与 node_modules（剔除开发依赖），从而显著压缩最终镜像体积。容器启动时执行 npm run start 监听 3000 端口。资料来源：frontend/Dockerfile:多阶段构建段落

环境变量通过 NEXT_PUBLIC_* 前缀注入到前端运行时，例如 NEXT_PUBLIC_API_URL 用于指向后端地址。Docker Compose 通过 environment 块将宿主环境变量透传至容器，因此同一镜像可在不同环境（开发/生产）下复用。资料来源：docker-compose.yml:frontend environment 段

3. 后端服务：FastAPI 容器化

后端使用 backend/Dockerfile（生产）与 backend/Dockerfile.dev（开发）两类镜像。生产镜像基于 Python 精简基础镜像，安装 requirements.txt 中依赖后，复制 app/ 应用代码与 entrypoint.sh 启动脚本。资料来源：backend/Dockerfile:依赖安装段落

entrypoint.sh 在容器启动时完成以下工作：资料来源：backend/entrypoint.sh:1-25

1. 等待 ChromaDB 等外部依赖可达（通过 curl 健康探测）；
2. 执行数据库迁移或初始化脚本；
3. 启动 Uvicorn，加载 app.main:app。

开发镜像则保留 uvicorn --reload 与源码卷挂载，便于本地调试。资料来源：backend/Dockerfile.dev:开发模式启动命令

4. 常见故障与排查

4.1 `rag-web-ui-frontend` 启动后 unhealthy

issue #73 报告了 docker compose ps 中 rag-web-ui-frontend 长时间处于 unhealthy 状态。该问题通常源于：

• 容器内 Node 进程尚未就绪，但 Docker 健康检查在 start_period 之外执行；
• 后端不可达导致前端 SSR 阶段抛错。

排查步骤：先 docker compose logs frontend 查看 Next.js 启动日志；其次确认 NEXT_PUBLIC_API_URL 已正确指向 http://backend:8000（容器网络名而非 localhost）；最后通过 docker compose exec frontend wget -qO- http://backend:8000/health 验证后端连通性。资料来源：docs/troubleshooting.md:健康检查章节

4.2 DNS 解析失败（`Temporary failure in name resolution`）

issue #36 反馈在聊天接口调用时出现 [Errno -3] Temporary failure in name resolution。该错误常因后端容器无法解析外部 LLM 域名。处理方式：在宿主机确认 DNS 正常后，于 docker-compose.yml 的 backend 服务下追加 dns 配置指向公共解析器（如 8.8.8.8），并重启服务。资料来源：docs/troubleshooting.md:DNS 章节

4.3 React 前端 `Maximum update depth exceeded`

issue #69 指出当聊天返回内容过长时，Next.js 客户端组件会触发 Maximum update depth exceeded。该问题属于渲染循环，建议在对话消息列表组件中：

• 对长消息进行分页/虚拟滚动（例如 react-window）；
• 使用 useMemo/useCallback 避免引用变化触发 setState。资料来源：docs/troubleshooting.md:前端性能章节

4.4 多租户数据隔离

issue #49 反馈不同账号登录后查询结果相同，疑似未做租户隔离。运维侧需确认后端环境变量中租户开关（如 ENABLE_TENANT_ISOLATION）已开启，并核对 ChromaDB collection 命名是否携带用户/租户前缀。资料来源：docs/troubleshooting.md:多租户章节

5. 升级与维护建议

• 升级到 v0.7.3 及以上版本，确保 extra_hosts 已声明，否则 Linux 主机上的本地 LLM/Embeddings 端点无法在容器内访问。资料来源：v0.7.3 release notes
• 升级到 v0.7.5 及以上版本，使用直接基于 bcrypt 的密码哈希实现，避免 passlib 与新版 bcrypt 之间的兼容问题。资料来源：v0.7.5 release notes
• 升级到 v0.8.0 后可独立配置 EMBEDDINGS_PROVIDER=huggingface，让 Embeddings 与 LLM 使用不同后端而互不影响。资料来源：v0.8.0 release notes

Pitfall Log / 踩坑日志

项目：rag-web-ui/rag-web-ui

摘要：发现 19 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Backend combined with knowledge base Q&A reports an error, and the error message is as follows。

1. 安装坑 · 来源证据：Backend combined with knowledge base Q&A reports an error, and the error message is as follows

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Backend combined with knowledge base Q&A reports an error, and the error message is as follows
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/70 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/rag-web-ui/rag-web-ui | Sandbox install result is missing.

3. 运行坑 · 沙箱验证已有失败原因

• 严重度：high
• 证据强度：runtime_trace
• 发现：llm_blocked_sandbox_execution
• 对用户的影响：失败原因未处理前，不应向用户暗示项目可顺利运行。
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：sandbox_validation_results | planner_decision=llm_blocked; planner_reason=The candidate command 'docker compose up -d' is not present in the deterministic allowlist (echo/python/node) and does not match any isolated_install_policy form (pip/npm/npx/uvx/docker run). 'docker compose up -d' would also start services persistently in the sandbox, whic…

4. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker compose up -d
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker compose up -d
• 证据：identity.distribution | https://github.com/rag-web-ui/rag-web-ui | docker compose up -d

5. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：docker compose up -d
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：downstream_validation.install_status | https://github.com/rag-web-ui/rag-web-ui | install_status=documented; command=docker compose up -d

6. 安装坑 · 来源证据：when process file get error "Failed to download temp file: S3 operation failed; code: NoSuchKey..."

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：when process file get error "Failed to download temp file: S3 operation failed; code: NoSuchKey..."
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/82 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/rag-web-ui/rag-web-ui | README/documentation is current enough for a first validation pass.

8. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：runtime_trace
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：downstream_validation.quickstart_status | https://github.com/rag-web-ui/rag-web-ui | quickstart_status=not_attempted; sandbox_quickstart_status=blocked

9. 运行坑 · 来源证据：Front end bug

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Front end bug
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/69 | 来源类型 github_issue 暴露的待验证使用条件。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/rag-web-ui/rag-web-ui | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/rag-web-ui/rag-web-ui | no_demo; severity=medium

12. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/rag-web-ui/rag-web-ui | No sandbox install has been executed yet; downstream must verify before user use.

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/rag-web-ui/rag-web-ui | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：Duplicate get_current_user in auth.py and security.py

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Duplicate get_current_user in auth.py and security.py
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/83 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：upload file failure

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：upload file failure
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/72 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：添加文档到知识库量化处理报错后，无法重试，也不能从知识库中将该文档再量化或者删除

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：添加文档到知识库量化处理报错后，无法重试，也不能从知识库中将该文档再量化或者删除
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/54 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：聊天发送消息返回Temporary failure in name resolution，不知道什么原因

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：聊天发送消息返回Temporary failure in name resolution，不知道什么原因
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/rag-web-ui/rag-web-ui/issues/36 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

18. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/rag-web-ui/rag-web-ui | issue_or_pr_quality=unknown

19. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/rag-web-ui/rag-web-ui | release_recency=unknown