agentic_huge_data_base / wiki
页面 Open WebUI · 6.7 可观测性与审计日志·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 6.7

6.7 · 可观测性与审计日志（Observability and Audit Logging）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节6.7 状态全文译文 模块接口与服务契约、可观测性与治理、认证、权限与安全、工具、记忆与模型调用
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Observability and Audit Logging 上一章6.6 下一章7
源码线索
  • backend/open_webui/config.py
  • backend/open_webui/constants.py
  • backend/open_webui/env.py
  • backend/open_webui/main.py
  • backend/open_webui/routers/auths.py
  • backend/open_webui/routers/tasks.py
  • backend/open_webui/utils/audit.py
  • backend/open_webui/utils/auth.py
  • backend/open_webui/utils/logger.py
  • backend/open_webui/utils/oauth.py
模块标签
  • 接口与服务契约
  • 可观测性与治理
  • 认证、权限与安全
  • 工具、记忆与模型调用
  • 检索、召回与知识系统

中文译文

可观测性与审计日志（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/6.7-observability-and-audit-logging
翻译时间：2026-06-09T16:09:03.275Z
翻译模型：deepseek-chat
原文字符数：7935
项目：Open WebUI (open-webui)

---

可观测性与审计日志

相关源文件

本 Wiki 页面基于以下文件生成：

  • backend/open_webui/config.py
  • backend/open_webui/constants.py
  • backend/open_webui/env.py
  • backend/open_webui/main.py
  • backend/open_webui/routers/auths.py
  • backend/open_webui/routers/tasks.py
  • backend/open_webui/utils/audit.py
  • backend/open_webui/utils/auth.py
  • backend/open_webui/utils/logger.py
  • backend/open_webui/utils/oauth.py
  • backend/open_webui/utils/task.py
  • backend/open_webui/utils/telemetry/logs.py

Open WebUI 实现了一套完整的可观测性栈，专为生产环境监控、合规性和安全审计而设计。该系统集成了 OpenTelemetry（OTel）用于分布式追踪和指标收集，同时包含结构化的审计日志管道，用于捕获敏感的管理操作和数据修改行为。

1. 结构化日志系统

后端使用 Loguru 进行内部日志记录，配置为拦截标准 Python logging 调用，并通过统一管道重定向。

实现与格式

日志系统支持两种主要格式，由 LOG_FORMAT 环境变量控制 backend/open_webui/env.py:107-116：

  1. 标准/控制台格式：通过 stdout_format 格式化的人类可读日志，包含时间戳和颜色编码的日志级别 backend/open_webui/utils/logger.py:26-45。
  2. JSON 格式：单行结构化 JSON 对象，针对日志聚合器（如 ELK、Datadog）优化，在 _json_sink 函数中实现 backend/open_webui/utils/logger.py:48-69。

env.py 中的 JSONFormatter 类提供了当 Loguru 不是主要接收器时的标准日志回退机制 backend/open_webui/env.py:85-104。

来源： backend/open_webui/utils/logger.py:26-69，backend/open_webui/env.py:85-116

日志拦截

为确保应用程序及其依赖项之间的一致性，InterceptHandler 捕获来自标准库和 Uvicorn 的记录，并将其重定向到 Loguru backend/open_webui/utils/logger.py:71-93。如果启用了 OpenTelemetry，它还会将 trace_id 和 span_id 注入到日志上下文中 backend/open_webui/utils/logger.py:99-110。

来源： backend/open_webui/utils/logger.py:71-110，backend/open_webui/utils/logger.py:184-193

---

2. 审计日志管道

审计日志系统提供重要系统事件的不可变记录，专门针对数据修改型 HTTP 方法和认证端点。

数据流图：审计拦截

下图展示了 AuditLoggingMiddleware backend/open_webui/utils/audit.py:115-141 如何在 FastAPI 生命周期中捕获请求和响应数据。

审计中间件请求周期

sequenceDiagram
    participant U as "客户端"
    participant M as "AuditLoggingMiddleware"
    participant C as "AuditContext"
    participant A as "FastAPI 应用"
    participant L as "AuditLogger (Loguru)"

    U->>M: "HTTP 请求 (POST/PUT/DELETE)"
    M->>M: "_should_skip_auditing()"
    M->>C: "初始化上下文 (MAX_BODY_LOG_SIZE)"
    M->>A: "调用 App 并传入 receive_wrapper"
    A->>M: "receive() 数据块"
    M->>C: "add_request_chunk()"
    A->>A: "处理请求逻辑"
    A->>M: "send() 响应数据块"
    M->>C: "add_response_chunk()"
    M->>A: "响应完成"
    M->>M: "_get_authenticated_user()"
    M->>L: "write(AuditLogEntry)"
    L->>L: "file_format (JSON 序列化)"
    M->>U: "最终 HTTP 响应"

来源： backend/open_webui/utils/audit.py:115-185，backend/open_webui/utils/audit.py:187-196

配置级别

审计详细程度通过 AUDIT_LOG_LEVEL 管理 backend/open_webui/utils/audit.py:52-57：

  • METADATA：记录用户 ID、IP、URI 和 HTTP 方法 backend/open_webui/utils/audit.py:37-44。
  • REQUEST：包含请求体（上限为 MAX_BODY_LOG_SIZE）backend/open_webui/utils/audit.py:46。
  • REQUEST_RESPONSE：同时包含请求体和响应体 backend/open_webui/utils/audit.py:48-49。
关键实体
  • AuditLogEntry：定义审计事件模式的冻结数据类 backend/open_webui/utils/audit.py:35-50。
  • AuditContext：在 ASGI 请求/响应流期间聚合数据块的对象 backend/open_webui/utils/audit.py:89-114。
  • AuditLogger：围绕 loguru 的包装器，绑定 auditable=True 标志 backend/open_webui/utils/audit.py:59-87。

来源： backend/open_webui/utils/audit.py:35-114，backend/open_webui/utils/logger.py:169-180

---

3. OpenTelemetry 集成

Open WebUI 支持 OpenTelemetry 进行分布式追踪和日志记录，使管理员能够监控系统性能并跨服务关联事件。

追踪与上下文注入

系统使用 opentelemetry SDK 管理可观测性数据。追踪上下文自动从当前 span 中获取，并通过 InterceptHandler 注入到日志中 backend/open_webui/utils/logger.py:103-110。

实体映射：OTel 到代码

graph TD
    subgraph "自然语言空间"
        Trace["分布式追踪"]
        Span["操作 Span"]
        Logs["关联日志"]
    end

    subgraph "代码实体空间"
        OTelSDK["opentelemetry.trace"]
        IH["InterceptHandler (utils/logger.py)"]
        ALM["AuditLoggingMiddleware (utils/audit.py)"]
        TC["trace.get_current_span()"]
        OH["otel_handler (telemetry/logs.py)"]
    end

    Trace --> OTelSDK
    Span --> TC
    TC --> IH
    IH --> Logs
    IH --> OH
    ALM -- "使用" --> OTelSDK

来源： backend/open_webui/utils/logger.py:94-110，backend/open_webui/utils/telemetry/logs.py:24-53

---

4. 安全与合规功能

OAuth 会话审计

系统追踪 OAuth 会话以满足合规性和安全监控需求。

  • 加密：敏感客户端数据在存储前使用 FERNET 实例进行静态加密 backend/open_webui/utils/oauth.py:178-202。
  • 会话管理：OAuth 会话存储时包含 expires_at 时间戳和关联的 user_id backend/open_webui/utils/oauth.py:148-175。
速率限制

为防止对认证端点的暴力攻击，登录流程应用了基于 Redis 的 RateLimiter，默认允许每 3 分钟尝试 15 次 backend/open_webui/routers/auths.py:97-98。

来源： backend/open_webui/utils/oauth.py:148-202，backend/open_webui/routers/auths.py:97-98

---

5. 存储与轮转

审计日志与通用应用日志分开存储，以便实施严格的访问控制和长期保留。

功能实现
存储路径由 AUDIT_LOGS_FILE_PATH 定义 backend/open_webui/utils/logger.py:11
轮转由 AUDIT_LOG_FILE_ROTATION_SIZE 触发 backend/open_webui/utils/logger.py:12
压缩自动压缩为 .zip 文件 backend/open_webui/utils/logger.py:175
格式通过 file_format 实现结构化 JSON backend/open_webui/utils/logger.py:113-139
过滤仅 extra["auditable"] == True 的记录写入审计接收器 backend/open_webui/utils/logger.py:177

来源： backend/open_webui/utils/logger.py:113-180，backend/open_webui/utils/audit.py:68