agentic_huge_data_base / wiki
页面 LightRAG · 8.3 测试框架·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 8.3

8.3 · 测试框架（Testing Framework）

轻量图谱增强检索 · 本章是 LightRAG DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目LightRAG 章节8.3 状态全文译文 模块测试、发布与运维、检索、召回与索引、图谱与关系、安装与启动
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Testing Framework 上一章8.2 下一章8.4
源码线索
  • .github/CONTRIBUTING.md
  • .github/workflows/copilot-setup-steps.yml
  • .github/workflows/linting.yaml
  • .github/workflows/pypi-publish.yml
  • .github/workflows/stale.yaml
  • .github/workflows/tests.yml
  • examples/modalprocessors_example.py
  • examples/raganything_example.py
  • tests/README_WORKSPACE_ISOLATION_TESTS.md
  • tests/__init__.py
模块标签
  • 测试、发布与运维
  • 检索、召回与索引
  • 图谱与关系
  • 安装与启动
  • 存储与持久化

中文译文

多站点与离线部署（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/HKUDS/LightRAG/8.3-multi-site-and-offline-deployment
翻译时间：2026-05-27T08:45:17.357Z
翻译模型：deepseek-chat
原文字符数：7563
项目：LightRAG (lightrag)

---

多站点与离线部署

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • docs/FrontendBuildGuide.md
  • docs/MultiSiteDeployment.md
  • docs/OfflineDeployment.md
  • lightrag_webui/.env.development
  • lightrag_webui/README.md
  • lightrag_webui/env.development.smaple
  • lightrag_webui/env.local.sample
  • lightrag_webui/src/components/ui/Badge.tsx
  • lightrag_webui/src/components/ui/Button.tsx
  • lightrag_webui/src/components/ui/Command.tsx
  • lightrag_webui/src/components/ui/UserPromptInputWithHistory.tsx
  • lightrag_webui/src/vite-env.d.ts
  • pyproject.toml
  • requirements-offline-llm.txt
  • requirements-offline-storage.txt
  • requirements-offline.txt
  • tests/test_path_prefixes.py
  • uv.lock

本节介绍 LightRAG 的高级部署模式，重点关注网络受限环境（气隙环境）的生产部署、高密度托管需求（多站点）以及本地推理集成。

多站点部署

LightRAG 支持使用"一次构建，多处部署"的架构在单台服务器上托管多个隔离实例 docs/MultiSiteDeployment.md:24-31。这是通过运行时配置注入实现的，允许同一 WebUI 构建版本在任何 URL 前缀下工作而无需重新编译。

运行时前缀注入

FastAPI 服务器使用自定义类 SmartStaticFiles 来拦截对 WebUI 的 index.html 的请求 lightrag/api/lightrag_server.py:37-44。它会将占位符注释 <!-- __LIGHTRAG_RUNTIME_CONFIG__ --> 替换为包含动态 window.__LIGHTRAG_CONFIG__ 对象的 <script> 标签 docs/MultiSiteDeployment.md:37-44。

关键配置变量：

变量默认值作用
LIGHTRAG_API_PREFIX""反向代理使用的路径前缀（例如 /site01）。作为 root_path 传递给 FastAPI docs/MultiSiteDeployment.md:74-76。
LIGHTRAG_WEBUI_PATH/webui前端资源的内部挂载点 docs/MultiSiteDeployment.md:78-79。
数据流：多站点反向代理

下图展示了单个 Nginx 实例如何使用基于路径的路由将流量分发到两个隔离的 LightRAG 容器。

多站点路由架构

graph TD
    subgraph "公共互联网"
        User["浏览器"]
    end

    subgraph "主机服务器（Nginx）"
        Proxy["Nginx 反向代理"]
    end

    subgraph "Docker 网络"
        Instance1["LightRAG 容器 1<br/>（LIGHTRAG_API_PREFIX=/site01）"]
        Instance2["LightRAG 容器 2<br/>（LIGHTRAG_API_PREFIX=/site02）"]
    end

    User -- "GET /site01/webui/" --> Proxy
    User -- "GET /site02/webui/" --> Proxy

    Proxy -- "proxy_pass（移除 /site01）" --> Instance1
    Proxy -- "proxy_pass（移除 /site02）" --> Instance2

    Instance1 -- "注入 {apiPrefix: '/site01'}" --> User
    Instance2 -- "注入 {apiPrefix: '/site02'}" --> User

来源：docs/MultiSiteDeployment.md:45-64，docs/MultiSiteDeployment.md:131-158

离线部署

LightRAG 提供分层依赖模型以方便在气隙环境中部署。这可以防止系统在运行时尝试使用 pipmaster 进行动态包安装 docs/OfflineDeployment.md:18-22。

依赖组

依赖项在 pyproject.toml 中按类别划分，以实现最小化安装 pyproject.toml:103-133：

  • lightrag-hku[api]：核心服务器和文档解析器（pypdf、python-docx 等）pyproject.toml:54-101。
  • lightrag-hku[offline-storage]：Redis、Neo4j、Milvus、MongoDB 和 PostgreSQL 的驱动程序 pyproject.toml:104-114。
  • lightrag-hku[offline-llm]：兼容 OpenAI 的 API、Ollama、Anthropic 和 LlamaIndex 的绑定 pyproject.toml:116-128。
  • lightrag-hku[offline]：上述所有依赖的完整捆绑包 pyproject.toml:130-133。
Tiktoken 缓存管理

TiktokenTokenizer 需要通常从 OpenAI 的 CDN 下载的 BPE 模型文件。对于离线使用，必须预先缓存这些文件 docs/OfflineDeployment.md:114-116。

  1. 下载：在在线环境中使用 lightrag-download-cache CLI 工具 docs/OfflineDeployment.md:120-131。
  2. 传输：将生成的目录（默认为 ~/.tiktoken_cache）移动到离线服务器 docs/OfflineDeployment.md:143-155。
  3. 配置：设置 TIKTOKEN_CACHE_DIR 环境变量 docs/OfflineDeployment.md:146-147。
使用 vLLM 进行本地推理

对于完全离线的检索增强生成（RAG），LightRAG 集成了本地推理服务器，例如 vLLM 或 Ollama。这些服务器充当 LLM_BINDING 和 EMBEDDING_BINDING docs/OfflineDeployment.md:26-29。

离线组件关联

graph LR
    subgraph "代码实体空间"
        LR["class LightRAG"]
        API["lightrag_server.py"]
        TK["class TiktokenTokenizer"]
    end

    subgraph "基础设施（离线）"
        VLLM["vLLM / Ollama 服务器"]
        DISK["本地存储（NetworkX/NanoVectorDB）"]
        CACHE["TIKTOKEN_CACHE_DIR"]
    end

    LR -- "大语言模型（LLM）/嵌入向量请求" --> VLLM
    LR -- "持久化图/向量" --> DISK
    TK -- "加载 BPE 模型" --> CACHE
    API -- "提供 WebUI 服务" --> LR

来源：docs/OfflineDeployment.md:114-155，lightrag/api/lightrag_server.py:1-20，pyproject.toml:154-160

气隙环境的 WebUI 构建指南

WebUI 是一个 React 单页应用（SPA），必须在可以使用 bun 或 npm 的环境中构建后才能部署 lightrag_webui/README.md:5-29。

构建流程
  1. 环境准备：在 lightrag_webui 目录中，使用 bun install --frozen-lockfile 安装依赖 lightrag_webui/README.md:17-19。
  2. 生产构建：运行 bun run build lightrag_webui/README.md:21-27。
  3. 制品位置：构建过程将静态资源输出到 lightrag/api/webui/。这些资源随后通过 package-data 包含在 Python 包中 pyproject.toml:177-178。
气隙传输

如果目标服务器无法运行构建过程：

  1. 在持续集成/持续部署（CI/CD）运行器或开发机器上构建 UI。
  2. 归档 lightrag/api/webui/ 目录。
  3. 将归档文件解压到生产服务器上的 LightRAG 安装路径中。
  4. FastAPI 服务器的 SmartStaticFiles 会自动检测并提供这些文件 docs/MultiSiteDeployment.md:37-44。
开发模拟

要在开发过程中测试多站点配置而无需完整的 Nginx 设置，可以在 WebUI 的 .env.development 文件中使用 VITE_DEV_API_PREFIX lightrag_webui/src/vite-env.d.ts:29-31。这会指示 Vite 开发服务器模拟反向代理的路径剥离行为 lightrag_webui/env.local.sample:24-27。

来源：lightrag_webui/README.md:1-40，lightrag_webui/env.local.sample:5-20，pyproject.toml:171-178