12.2 · 服务端认证与安全（Server Authentication and Security）

服务端认证与安全

服务器认证与安全

相关源文件

本章引用的主要源码文件：

• docs/open-source/features/rest-api.mdx
• examples/graph-db-demo/alice-memories.png
• examples/graph-db-demo/memgraph-example.ipynb
• server/.env.example
• server/Dockerfile
• server/Makefile
• server/README.md
• server/dev.Dockerfile
• server/docker-compose.yaml
• server/main.py
• server/requirements.txt
• tests/test_server_auth.py
• tests/test_server_params.py

Mem0 自托管服务器采用"默认安全"的设计理念。它实现了一个多层认证系统，支持通过 JWT 进行交互式仪表盘会话、通过每个用户的 API 密钥进行程序化访问，以及一个遗留的管理员覆盖机制。

认证概述

服务器的认证逻辑集中在 auth.py 中，并通过 server/main.py 中的 FastAPI 依赖项强制执行。系统按特定优先级顺序评估凭证：

1. AUTH_DISABLED 标志：如果设置为 true，则绕过所有安全检查（仅限本地开发）server/main.py:89-90。
2. Bearer JWT：用于 Mem0 仪表盘上的交互式会话 docs/open-source/features/rest-api.mdx:133-133。
3. X-API-Key（每个用户）：用于程序化 SDK/API 访问，作用域限定为特定仪表盘用户 docs/open-source/features/rest-api.mdx:134-134。
4. X-API-Key（遗留管理员）：使用 ADMIN_API_KEY 环境变量的全局覆盖机制 docs/open-source/features/rest-api.mdx:135-135。

安全状态流

下图说明了请求如何通过 verify_auth 依赖项进行验证。

请求认证流程

来源：server/main.py:139-146, server/main.py:89-98, docs/open-source/features/rest-api.mdx:127-138

基于 JWT 的仪表盘认证

交互式认证通过 server/routers/auth.py 中的 auth_router 进行管理 server/main.py:29。该系统为内置仪表盘提供安全的登录、注册和令牌刷新功能。

关键组件

• JWT_SECRET：一个必需的环境变量，用于签署令牌。如果启用认证时缺少此变量，服务器将无法启动 server/main.py:83-87。
• 访问令牌：短生命周期的令牌，用于认证对受保护路由的请求 docs/open-source/features/rest-api.mdx:133-133。
• 刷新令牌：长生命周期的令牌，用于获取新的访问令牌，而无需重新输入凭证 docs/open-source/features/rest-api.mdx:169-169。

实现细节

服务器使用 passlib 配合 bcrypt 进行密码哈希处理，并使用 python-jose 进行 JWT 操作 server/requirements.txt:17-19。

来源：server/main.py:29, server/requirements.txt:17-19, docs/open-source/features/rest-api.mdx:131-134

API 密钥管理

对于程序化访问，服务器支持 X-API-Key 请求头。这些密钥通过 api_keys_router 进行管理 server/main.py:30。

每个用户的 API 密钥

用户可以通过仪表盘生成多个 API 密钥。这些密钥具有以下特性：

• 作用域限定：继承创建用户的权限和作用域 docs/open-source/features/rest-api.mdx:185-186。
• 安全：仅在创建时显示一次 docs/open-source/features/rest-api.mdx:173-174。
• 可撤销：可以通过 DELETE /api-keys/{id} 端点删除，以立即终止访问 docs/open-source/features/rest-api.mdx:185-185。

遗留管理员 API 密钥

ADMIN_API_KEY 环境变量充当"超级密钥"。它旨在与较旧的 Mem0 部署保持向后兼容，并且不需要数据库中的用户记录。

• 验证：如果 X-API-Key 请求头与 ADMIN_API_KEY 环境变量匹配，则该请求被授权为管理操作 docs/open-source/features/rest-api.mdx:187-194。
• 安全警告：如果密钥长度少于 16 个字符，服务器会在启动时记录一条警告 server/main.py:41, server/main.py:91-95。

来源：server/main.py:30, server/main.py:41-41, docs/open-source/features/rest-api.mdx:171-186

安全配置与请求头

AUTH_DISABLED 标志

对于本地开发，在 .env 文件中设置 AUTH_DISABLED=true 会绕过所有安全检查 server/.env.example:17。

• 行为：verify_auth 依赖项被绕过，服务器会记录一条警告 server/main.py:89-90。
• 生产环境警告：绝不应在生产环境中使用此标志，因为它会将所有内存操作（CRUD）暴露给公共网络 docs/open-source/features/rest-api.mdx:195-197。

安全请求头

Mem0 仪表盘强制执行多个安全请求头，以防止常见的 Web 攻击：

• X-Frame-Options: DENY：通过禁止仪表盘嵌入 iframe 来防止点击劫持 server/README.md:117-117。
• Content-Security-Policy: frame-ancestors 'none'：X-Frame-Options 的现代替代方案 server/README.md:118-118。
• X-Content-Type-Options: nosniff：防止浏览器"嗅探"响应的 MIME 类型 server/README.md:119-119。
• Referrer-Policy: strict-origin-when-cross-origin：限制随请求发送的引用者信息量 server/README.md:120-120。

CORS 配置

服务器将跨域请求限制为环境变量中定义的 DASHBOARD_URL server/main.py:153-160。

来源：server/main.py:89-90, server/README.md:113-122, server/.env.example:17-17, server/main.py:153-160

数据流：安全上下文关联

此图映射了认证实体与核心内存处理逻辑之间的关系。

认证实体映射

来源：server/main.py:16-34, server/models.py:27-27, server/server_state.py:34-34

安全环境变量总结

来源：server/main.py:83-160, server/.env.example:14-18