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

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目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 页面https://deepwiki.com/HKUDS/LightRAG/4.6-authentication-and-security

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

认证与安全

认证机制

该服务器支持三种主要的认证方式，通过 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 依赖项如何解析不同的认证信号。

认证解析逻辑

LightRAG · 认证数据流 · 图 1

来源： 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

代码实体关系

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

安全架构映射

LightRAG · 代码实体关系 · 图 2

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