跳到主要内容

理解 Open WebUI 日志记录 🪵

日志记录对于调试、监控和理解 Open WebUI 的行为至关重要。本指南解释了日志记录如何在浏览器客户端（前端）和应用服务器/后端中工作。

🖥️ 浏览器客户端日志记录（前端）​

对于前端开发和调试，Open WebUI 利用标准的浏览器控制台日志记录。这意味着你可以直接在你的网络浏览器的内置开发者工具中查看日志。

如何访问浏览器日志

  1. 打开开发者工具： 在大多数浏览器中，你可以通过以下方式打开开发者工具

    • 在 Open WebUI 页面的任意位置右键单击并选择“检查”或“检查元素”。
    • 按下 F12 键（在 macOS 上是 Cmd+Opt+I）。

  2. 导航到“控制台”选项卡： 在开发者工具面板中，找到并单击“控制台”选项卡。

浏览器日志的类型

Open WebUI 主要使用 JavaScript 的 console.log() 进行客户端日志记录。你会在控制台中看到各种类型的消息，包括

  • 信息性消息： 应用的一般流程和状态。
  • 警告： 潜在问题或非关键错误。
  • 错误： 可能影响功能的问题。

各浏览器特定的开发者工具

不同的浏览器提供的开发者工具略有不同，但它们都提供一个控制台用于查看 JavaScript 日志。以下是流行浏览器的文档链接

⚙️ 应用服务器/后端日志记录 (Python)​

Open WebUI 的后端使用 Python 的内置 logging 模块记录服务器端的事件和信息。这些日志对于理解服务器行为、诊断错误和监控性能至关重要。

关键概念

  • Python logging 模块： Open WebUI 利用标准的 Python logging 库。如果你熟悉 Python 日志记录，你会发现本节内容很容易理解。（更多详细信息，请参阅 Python 日志记录文档）。
  • 控制台输出： 默认情况下，后端日志发送到控制台（标准输出），使它们在你的终端或 Docker 容器日志中可见。
  • 日志级别： 日志级别控制日志的详细程度。你可以根据这些级别配置 Open WebUI 显示更详细或更少的信息。

🚦 日志级别说明​

Python 日志记录使用一个级别层次结构来按严重程度对日志消息进行分类。以下是各级别的细分，从最严重到最不严重：

级别数值描述用例
CRITICAL (严重)50可能导致应用终止的严重错误。灾难性故障，数据损坏。
ERROR (错误)40表明存在问题但应用可能仍能运行的错误。可恢复错误，失败的操作。
WARNING (警告)30应调查的潜在问题或意外情况。弃用警告，资源限制。
INFO (信息)20关于应用操作的一般信息性消息。启动消息，关键事件，正常操作流程。
DEBUG (调试)10供开发者使用的详细调试信息。函数调用，变量值，详细执行步骤。
NOTSET (未设置)0所有消息都被记录。（如果未设置，通常默认为 WARNING）。用于捕获所有信息，通常用于非常具体的调试。

默认级别： Open WebUI 的默认日志级别是 INFO。

🌍 全局日志级别 (GLOBAL_LOG_LEVEL)​

你可以使用 GLOBAL_LOG_LEVEL 环境变量更改整个 Open WebUI 后端的全局日志级别。这是控制整体日志详细程度最直接的方法。

工作原理

设置 GLOBAL_LOG_LEVEL 会配置 Python 的根日志记录器，影响 Open WebUI 中的所有日志记录器以及可能使用 basicConfig 的某些第三方库。它使用 logging.basicConfig(force=True)，这意味着它将覆盖任何现有的根日志记录器配置。

示例：设置为 DEBUG

  • Docker 参数

    --env GLOBAL_LOG_LEVEL="DEBUG"

  • Docker Compose (docker-compose.yml)

    environment:
      - GLOBAL_LOG_LEVEL=DEBUG

影响： 将 GLOBAL_LOG_LEVEL 设置为 DEBUG 将产生最详细的日志，包括有助于开发和故障排除的详细信息。对于生产环境，INFO 或 WARNING 可能更适合以减少日志量。

⚙️ 应用/后端特定日志级别​

为了更精细地控制，Open WebUI 提供了环境变量来为特定的后端组件设置日志级别。日志记录是一项正在进行中的工作，但使用这些环境变量可以获得一定程度的控制。这些变量允许你为应用的不同部分微调日志记录。

可用环境变量

环境变量组件/模块描述
AUDIO_LOG_LEVEL音频处理与音频转录 (faster-whisper)、文本转语音 (TTS) 和音频处理相关的日志记录。
COMFYUI_LOG_LEVELComfyUI 集成如果你使用此集成，则记录与 ComfyUI 的交互。
CONFIG_LOG_LEVEL配置管理与加载和处理 Open WebUI 配置文件相关的日志记录。
DB_LOG_LEVEL数据库操作 (Peewee)使用 Peewee ORM（对象关系映射器）进行数据库交互的日志记录。
IMAGES_LOG_LEVEL图像生成 (AUTOMATIC1111/Stable Diffusion)用于图像生成任务的日志记录，尤其是在使用 AUTOMATIC1111 Stable Diffusion 集成时。
MAIN_LOG_LEVEL主应用执行（根日志记录器）来自主应用入口点和根日志记录器的日志记录。
MODELS_LOG_LEVEL模型管理与加载、管理和交互语言模型 (LLMs) 相关的日志记录，包括认证。
OLLAMA_LOG_LEVELOllama 后端集成用于与 Ollama 后端通信和交互的日志记录。
OPENAI_LOG_LEVELOpenAI API 集成用于与 OpenAI API 交互的日志记录（例如，对于 GPT 等模型）。
RAG_LOG_LEVEL检索增强生成 (RAG)用于 RAG 流水线的日志记录，包括 Chroma 向量数据库和 Sentence-Transformers。
WEBHOOK_LOG_LEVEL认证 Webhook用于认证 Webhook 功能的扩展日志记录。

如何使用

你可以使用与设置 GLOBAL_LOG_LEVEL 相同的方式设置这些环境变量（Docker 参数、Docker Compose 的 environment 部分）。例如，为了获取更详细的 Ollama 交互日志，你可以设置

environment:
  - OLLAMA_LOG_LEVEL=DEBUG

重要提示： 与 GLOBAL_LOG_LEVEL 不同，这些应用特定的变量可能不会影响来自所有第三方模块的日志记录。它们主要控制 Open WebUI 代码库内部的日志记录。

通过理解和利用这些日志记录机制，你可以有效地监控、调试并深入了解你的 Open WebUI 实例。