跳到主要内容

身份验证

Frigate将用户信息存储在其数据库中。密码哈希使用行业标准的PBKDF2-SHA256算法生成，迭代次数为600,000次。成功登录后，会签发带有过期日期的JWT令牌并设置为Cookie。该Cookie在需要时会自动刷新。该JWT令牌也可以通过Authorization标头作为Bearer令牌传递。

用户管理可在用户界面的设置 > 用户下进行。

以下端口可用于访问Frigate的Web用户界面。

端口描述
8971已认证的UI和API。反向代理应使用此端口。
5000内部未认证的UI和API访问。应限制对此端口的访问。该端口计划在Docker网络内使用，供与Frigate集成但不支持身份验证的服务使用。

初始设置​

启动时，系统会自动生成管理员用户和密码并打印在日志中。建议首次登录后在"设置 > 用户"中为管理员账户设置新密码。

重置管理员密码​

如果您被锁定在实例之外，可以通过配置文件中设置 reset_admin_password 参数，让 Frigate 在下次启动时重置管理员密码并打印到日志中。

auth:
  reset_admin_password: true

登录失败速率限制​

为限制暴力破解攻击风险，系统提供基于 SlowApi 的登录失败速率限制功能。有效值的字符串格式说明详见文档。

例如 1/second;5/minute;20/hour 表示当失败次数超过以下阈值时将触发速率限制：

  • 每秒1次
  • 每分钟5次
  • 每小时20次

重启 Frigate 会重置速率限制计数器。

如果在代理后运行 Frigate，需设置 trusted_proxies ，否则速率限制将作用于上游代理IP地址。这可能导致暴力攻击会暂时锁定其他设备的登录尝试。为确保速率限制仅作用于真实请求来源IP地址，需要列出可信的上游网络。系统会通过检查 X-Forwarded-For 头来验证请求来源IP。

如果您在与 Frigate 相同的 Docker Compose 文件中运行反向代理，以下是认证配置示例：

auth:
  failed_login_rate_limit: "1/second;5/minute;20/hour"
  trusted_proxies:
    - 172.19.0.0/24 # <---- this is the subnet for the internal Docker Compose network

JWT 令牌密钥​

JWT 令牌密钥必须安全保管。任何持有该密钥的人员均可生成有效的 JWT 令牌进行认证。密钥应为至少 64 位的加密随机字符串。

可通过以下 Python 命令生成密钥（使用 secrets 库）：

python3 -c 'import secrets; print(secrets.token_hex(64))'

Frigate 按以下顺序查找 JWT 密钥：

  1. 环境变量 FRIGATE_JWT_SECRET
  2. 在 /run/secrets/ 中名为 FRIGATE_JWT_SECRET 的 Docker 机密文件
  3. Home Assistant 插件配置中的 jwt_secret 参数
  4. 配置目录中的 .jwt_secret 文件

若启动时未检测到密钥，Frigate 将自动生成并保存到配置目录的 .jwt_secret 文件。

修改密钥将使当前所有令牌失效。

代理配置​

Frigate 支持与上游认证代理（如 Authelia、Authentik、oauth2_proxy 或 traefik-forward-auth）集成。

若使用代理认证：需禁用 Frigate 原生认证功能， 若代理与 Frigate 间通信处于非可信网络，在 proxy 配置中设置 auth_secret 密钥，配置代理通过 X-Proxy-Secret 请求头传递该密钥. 配置 TLS 证书 防止密钥被截获。

示例配置（禁用认证并限制代理访问）：

auth:
  enabled: False

proxy:
  auth_secret: <some random long string>

你可以使用以下命令生成安全随机密钥的命令：

python3 -c 'import secrets; print(secrets.token_hex(64))'

请求头映射​

若已禁用 Frigate 认证且您的代理支持传递携带认证用户名/角色的请求头，可通过 header_map 配置指定请求头名称实现信息透传。例如以下配置将映射 X-Forwarded-User 和 X-Forwarded-Role 的值（请求头名称不区分大小写）：

proxy:
  ...
  header_map:
    user: x-forwarded-user
    role: x-forwarded-role

Frigate 支持 admin 和 viewer （查看者）两种角色（详见下文）。当使用 8971, 端口时，Frigate 会验证这些请求头，后续请求将使用 remote-user 和 remote-role 请求头进行授权验证。

端口权限说明​

认证端口 (8971)

  • 完整支持请求头映射。
  • 通过 remote-role 请求头确定用户权限：
    • admin → 完全访问权限（用户管理、配置修改）。
    • viewer → 只读访问权限。
  • 需确保代理同时发送用户和角色请求头以实现权限控制。

非认证端口 (5000)

  • 权限控制相关请求头将被忽略。
  • 所有请求均视为匿名访问。
  • remote-role 值被覆盖为管理员权限。
  • 此设计专为可信网络内免认证的内部使用场景。

默认仅允许以下预定义请求头：

Remote-User
Remote-Groups
Remote-Email
Remote-Name
X-Forwarded-User
X-Forwarded-Groups
X-Forwarded-Email
X-Forwarded-Preferred-Username
X-authentik-username
X-authentik-groups
X-authentik-email
X-authentik-name
X-authentik-uid

如需扩展允许的请求头，可通过 Docker 绑定挂载覆盖默认配置文件 /usr/local/nginx/conf/proxy_trusted_headers.conf 。默认配置文件格式请参考源代码。

登录页重定向​

Frigate 提供标准的登录页重定向机制，兼容多数认证代理方案。当反向代理在 401、 302, 或 307 未授权响应中返回 Location 头部时，前端将自动检测并跳转至指定 URL。

自定义注销网址​

若反向代理配置了专用注销端点，可通过 logout_url 配置项指定。此设置将同步更新 UI 界面中的 Logout 链接地址。

用户角色体系​

Frigate 通过角色机制控制 UI/API 功能访问权限（如用户管理、配置修改等）。角色可通过数据库分配或由代理请求头传递，在认证端口 (8971) 访问时生效。

支持角色​

  • admin: 完整权限：用户管理、配置修改等所有功能。
  • viewer: 只读权限：可查看摄像头画面、审核项和历史录像 （无法访问配置编辑器和设置界面）。

权限验证逻辑​

  • 认证端口 (8971)。通过 JWT 令牌或代理请求头（如 remote-role)）验证角色。

  • 非认证端口 (5000)。权限验证完全禁用，所有请求视为匿名访问，默认获得管理员级无限制权限。

要实现基于角色的访问控制，必须通过认证端口 (8971) 直连或经反向代理访问。

UI 角色显示​

  • 通过 8971 端口登录时，账户菜单（右下角）显示用户名和角色。
  • 通过 5000 端口访问时，始终显示 "anonymous / admin"。

角色管理操作​

  1. 通过 8971 端口以 admin 身份登录。
  2. 进入 设置 > 用户管理。
  3. 通过下拉菜单修改用户角色（admin/viewer）