4.6 · 认证与安全（Authentication and Security）

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

项目LightRAG 章节4.6 状态全文译文模块认证、权限与安全、文档对象与元数据、测试、发布与运维、存储与持久化

项目要点页2.5 参考项目项目章节目录LightRAG DeepWiki 原始章节Authentication and Security 上一章4.5 下一章5

源码线索

SECURITY.md
lightrag/api/auth.py
lightrag/api/gunicorn_config.py
lightrag/api/passwords.py
lightrag/api/run_with_gunicorn.py
lightrag/tools/hash_password.py
lightrag_webui/public/logo.svg
tests/test_auth.py

模块标签

认证、权限与安全
文档对象与元数据
测试、发布与运维
存储与持久化
界面与交互

中文译文

认证与安全（中文译文）

此页面内容来自 DeepWiki 重组后的对应页面（来源：6-3.zh.md）

翻译时间：2026-05-27T12:17:56.006Z

翻译模型：deepseek-chat

项目：LightRAG (lightrag)

---

认证与安全

认证机制

该服务器支持三种主要的认证方式，通过 combined_auth 依赖项进行管理。

1. 基于 JWT 的认证（OAuth2）

LightRAG 使用 JSON Web 令牌（JWT）管理用户会话。这是 WebUI 使用的主要认证方式。

AuthHandler：负责令牌生命周期管理的核心类，包括创建和校验 lightrag/api/auth.py:25-161。
TokenPayload：定义 JWT 结构的 Pydantic 模型，包含 sub（用户名）、exp（过期时间）、role（角色）和 metadata（元数据）lightrag/api/auth.py:18-22。
OAuth2 密码流程：用户通过 /login 端点进行认证以获取令牌。系统支持两种角色：user（用户，默认）和 guest（访客）lightrag/api/auth.py:86-118。

2. X-API-Key 请求头

为支持程序化访问和持续集成/持续部署（CI/CD）集成，LightRAG 支持静态 API 密钥。

通过 LIGHTRAG_API_KEY 环境变量进行配置 env.example:91。
客户端必须在 X-API-Key HTTP 请求头中包含该密钥 lightrag/api/utils_api.py:116-118。

3. 白名单支持

某些路径可以通过 WHITELIST_PATHS 豁免认证要求 env.example:92。

支持精确匹配和前缀匹配（使用 /* 语法）lightrag/api/utils_api.py:72-85。
常见的白名单路径包括用于负载均衡器健康检查的 /health lightrag/api/utils_api.py:37-41。

认证数据流

下图展示了 combined_auth 依赖项如何解析不同的认证信号。

认证解析逻辑

graph TD
    subgraph "请求入口"
        REQ["FastAPI 请求"]
    end

    subgraph "combined_dependency [lightrag/api/utils_api.py]"
        WHITE{"路径是否在白名单中？"}
        TOKEN_CHK{"是否提供了 JWT 令牌？"}
        API_CHK{"是否提供了 X-API-Key？"}

        VAL_TOKEN["auth_handler.validate_token"]
        VAL_API["与 LIGHTRAG_API_KEY 比较"]

        RENEW["令牌自动续期逻辑"]
        FAIL["401 未授权"]
        SUCCESS["允许访问"]
    end

    REQ --> WHITE
    WHITE -- "是" --> SUCCESS
    WHITE -- "否" --> TOKEN_CHK

    TOKEN_CHK -- "是" --> VAL_TOKEN
    TOKEN_CHK -- "否" --> API_CHK

    VAL_TOKEN -- "有效" --> RENEW
    VAL_TOKEN -- "无效" --> FAIL

    API_CHK -- "是" --> VAL_API
    API_CHK -- "否" --> FAIL

    VAL_API -- "匹配" --> SUCCESS
    VAL_API -- "不匹配" --> FAIL

    RENEW --> SUCCESS

来源： lightrag/api/utils_api.py:91-218，lightrag/api/auth.py:120-160

令牌管理与续期

LightRAG 实现了"滑动窗口"过期策略，以改善活跃会话的用户体验。

滑动窗口续期

如果启用了 TOKEN_AUTO_RENEW，当当前令牌的剩余生命周期低于阈值时，服务器会自动签发新的 JWT lightrag/api/utils_api.py:145-175。

TOKEN_RENEW_THRESHOLD：默认值为 0.5（剩余 50% 时间时续期）env.example:81。
X-New-Token 请求头：当令牌被续期时，新的 JWT 会通过此响应请求头返回。客户端（WebUI）必须使用此新令牌更新其本地存储 lightrag/api/utils_api.py:202-211。
速率限制：每个用户每 60 秒最多续期一次，以防止请求头开销过大 lightrag/api/utils_api.py:30-31。

排除路径

为防止高频轮询时产生不必要的续期，以下路径被排除在续期逻辑之外：

/documents/paginated（WebUI 文档列表轮询）lightrag/api/utils_api.py:39。
/documents/pipeline_status（状态指示器轮询）lightrag/api/utils_api.py:40。

来源： lightrag/api/utils_api.py:26-41，lightrag/api/utils_api.py:141-211，env.example:71-87

安全校验与强制

系统在启动时会执行严格的校验，以防止不安全的配置。

安全强制规则

特性	强制规则	来源
JWT 密钥	如果设置了 `AUTH_ACCOUNTS`，则 `TOKEN_SECRET` 不能使用默认值。	`lightrag/api/config.py:159-168`
JWT 算法	严格禁止使用 `none` 算法，以防止绕过攻击。	`lightrag/api/auth.py:39-44`
密码哈希	支持明文（用于开发环境）或 `{bcrypt}` 前缀的哈希值（用于生产环境）。	`lightrag/api/passwords.py:13-27`

密码处理

AUTH_ACCOUNTS 中的密码可以存储为 bcrypt 哈希值。服务器使用 verify_password 函数，根据 {bcrypt} 前缀判断存储的字符串是哈希值还是明文 lightrag/api/passwords.py:15-16。

提供了一个实用工具来生成这些哈希值：

lightrag.tools.hash_password：一个命令行工具，接收用户名和密码，返回一个可直接用于 .env 文件的字符串 lightrag/tools/hash_password.py:23-35。

来源： lightrag/api/auth.py:27-64，lightrag/api/passwords.py:3-27，lightrag/tools/hash_password.py:1-40

代码实体关系

下图将安全概念映射到实现这些概念的具体代码实体。

安全架构映射

graph LR
    subgraph "配置空间"
        ENV[".env / env.example"]
        G_ARGS["global_args [lightrag/api/config.py]"]
    end

    subgraph "逻辑空间"
        AH["AuthHandler [lightrag/api/auth.py]"]
        PW["passwords.py"]
        U_API["utils_api.py"]
    end

    subgraph "FastAPI 空间"
        DEP["combined_auth_dependency"]
        LOG_R["/login [lightrag_server.py]"]
    end

    ENV -- "AUTH_ACCOUNTS" --> G_ARGS
    ENV -- "TOKEN_SECRET" --> G_ARGS

    G_ARGS -- "初始化" --> AH

    AH -- "使用" --> PW
    PW -- "bcrypt.checkpw" --> PW

    AH -- "validate_token" --> U_API
    U_API -- "Depends" --> DEP

    LOG_R -- "调用" --> AH

来源： lightrag/api/lightrag_server.py:67，lightrag/api/auth.py:25-34，lightrag/api/utils_api.py:91-101