跳到主要内容

可自定义横幅

概述​

Open WebUI 允许管理员向已登录用户显示自定义横幅（Banners）。横幅对于发布公告、系统级警报、维护通知和其他重要消息非常有用。

横幅是持久显示的，并且可以选择允许用户关闭。您可以通过以下两种方式配置横幅：

  1. Admin Panel（推荐用于快速编辑和测试）
  2. 环境变量 (WEBUI_BANNERS)（推荐用于自动化 / GitOps 风格的部署）

何时使用横幅​

横幅最适合用于简短、高可见度的消息，例如：

  • 计划维护和计划停机时间窗口
  • 故障通知（性能下降、部分服务中断）
  • 政策提醒（合理使用、数据处理、留存政策）
  • 重大变更（新模型、功能上线、UI 变更）
  • 指向您内部沟通渠道的链接，以便获取更新和进行问答

提示： 保持横幅内容简短，并链接到更详细的信息（状态页面、发布日志、支持渠道）。

配置横幅​

选项 1：使用 Admin Panel​

这是管理横幅最直接的方法：

  1. 以管理员身份登录您的 Open WebUI 实例。
  2. 导航至 Admin Panel → Settings → General。
  3. 找到 Banners 部分。
  4. 点击 + 图标以添加新横幅。
  5. 点击 Save 以应用更改。

您可以为每个横幅配置以下选项：

  • Type： 横幅的颜色和样式：
    • info（蓝色）
    • success（绿色）
    • warning（黄色）
    • error（红色）
  • Title： 横幅的主标题。
  • Content： 主要消息（仅限 HTML）。
  • Dismissible： 如果启用，用户可以关闭该横幅。

关闭状态是如何工作的​

已被用户关闭的横幅信息会存储在用户的浏览器中（客户端）。这意味着：

  • 如果用户清除了网站数据 / 缓存，已被关闭的横幅可能会重新出现
  • 在不同的设备或浏览器上，已被关闭的横幅可能会重新出现
  • 关闭状态是基于横幅的 id 的（如果 id 发生变化，该横幅将被视为新横幅）

如果您需要横幅对所有人始终保持可见，请设置 dismissible: false。

选项 2：使用环境变量 (WEBUI_BANNERS)​

对于自动化部署，请使用 WEBUI_BANNERS 环境变量来配置横幅。该值必须是一个表示横幅对象列表（数组）的 JSON 字符串。

环境变量：

  • WEBUI_BANNERS
    • 类型： string（包含 JSON 对象列表）
    • 默认值： []
    • 描述： 要向用户显示的横幅对象列表

示例 (Docker Compose)​

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - 'WEBUI_BANNERS=[{"id":"maintenance-2026-03","type":"warning","title":"维护通知","content":"本周计划进行系统维护。预计会有短暂的服务中断。<a href=\"https://intranet.example.com/status\" target=\"_blank\">查看状态页面</a>。","dismissible":true,"timestamp":1772500000}]'

注意：因为 WEBUI_BANNERS 是 YAML 内部的 JSON 字符串，您必须确保它保持为合法的 JSON 格式（参见下面的“常见陷阱”）。

每个横幅对象支持以下属性：

  • id (string，必填)：横幅的唯一标识符。用于跟踪用户是否已将其关闭。
  • type (string，必填)：横幅样式。必须是以下之一：info、success、warning、error。
  • title (string，可选)：标题文本。
  • content (string，必填)：横幅主消息（仅限 HTML）。
  • dismissible (boolean，必填)：用户是否可以关闭横幅。
  • timestamp (integer，必填)：存在于配置中，但目前前端未使用它来控制显示时机。

选择能够支持安全更新并避免意外重新显示或永久隐藏的 id 格式：

  • 稳定 id，适用于微小的文本编辑：policy-reminder
  • 版本化 id，适用于“向所有人重新显示”的更新：incident-2026-03-06-v2
  • 按时间段划分的 id，适用于周期性事件：maintenance-2026-03

如果用户已经关闭了某个横幅，而您希望他们看到更新后的消息，请更改其 id。

支持的内容格式（仅限 HTML）​

横幅的 title 和 content 仅支持 HTML 子集 —— 不会渲染 Markdown 语法。不支持的标签可能会渲染为纯文本或破坏布局。

文本格式​

HTML效果
<b> / <strong>加粗
<i> / <em>斜体
<u>下划线
<s> / <del>删除线
<mark>高亮突出
<small>字号稍小的文本
<sub> / <sup>下标 / 上标
<code> / <kbd>等宽行内代码
<abbr title="提示信息">悬停工具提示

结构​

HTML效果
<br> 或字面换行符换行
<hr>水平分割线
<details><summary>点击展开</summary>...</details>可折叠区域
HTML效果
<a href="..." target="_blank">可点击链接
<img src="..." width="16" height="16">行内图片

自定义样式​

在允许的标签上支持内联样式（Inline styles）：

<span style="color: #b91c1c;">彩色文本</span>
<span style="font-weight: 600;">更粗的字重</span>
<span style="background: linear-gradient(90deg,#e0f2fe,#fef9c3);">渐变背景</span>

尽量保持样式极简。过大的 padding、字体大小或复杂的布局可能会导致横幅过高，或在不同主题之间显得视觉不一致。

不支持的内容​

横幅中不支持以下内容，它们可能会渲染为纯文本或破坏布局：

  • 标题标签 (<h1>–<h6>)
  • 列表标签 (<ul>, <ol>)
  • 表格
  • 块引用 (Blockquotes)
  • Markdown 语法

如果您需要“列表式”内容，请使用由 <br> 分隔的简短行。

常见陷阱（以及如何避免它们）​

1) 字面换行符导致的意外间距​

横幅内容会将字面换行符视为换行。如果您粘贴了包含许多换行符且格式优美/缩进整齐的 HTML，横幅的高度可能会比预期的要高得多。

建议：

  • 有意识地使用 <br>，并保持原始 HTML 相对紧凑。
  • 除非您确实需要额外的间距，否则避免添加空行。

2) 横幅内容中的损坏链接​

如果链接看起来“损坏”或横幅的其余部分也变成了可点击状态，这通常是由于无效的 HTML 引起的。

请使用以下确切模式：

<a href="https://example.com" target="_blank">打开链接</a>

建议：

  • 始终使用 </a> 关闭锚点标签。
  • 使用 target="_blank"（包含下划线）。
  • 如果您的 URL 包含查询参数，请在 href 属性中将 & 转义为 &amp;： 
    <a href="https://example.com/page?x=1&amp;y=2" target="_blank">示例</a>
  • 如果您需要确保下划线效果，请用 <u> 包裹链接文本： 
    <a href="https://example.com" target="_blank"><u>支持</u></a>

3) WEBUI_BANNERS 中的 JSON/YAML 转义问题​

使用 WEBUI_BANNERS 时，您是在 YAML 字符串（或 Shell 字符串）中嵌入 JSON。常见问题包括：

  • JSON 内部未转义的双引号
  • JSON 字符串中插入了换行符
  • 复制/粘贴了“智能引号”（排版引号）而不是普通的 "

建议：

  • 在部署前，先在 JSON 验证器中验证该 JSON。
  • 保持 content 字符串简单；避免未转义的 " 字符。
  • 如果需要，优先在 JSON 字符串中使用 \" 作为引号。
  • 如果横幅未显示，请检查服务器日志。

4) 过度使用 <small>​

<small> 适用于次要文本，但将横幅的大部分内容都包裹在 <small> 中会使内容难以阅读。

建议： 对主要消息使用普通文本，将 <small> 留给不那么重要的细节。

5) 外部图片​

可以通过 <img> 嵌入图片，但外部图片可能会：

  • 由于网络限制而加载失败
  • 如果没有加以约束，会在不同设备上产生不一致的尺寸
  • 如果从第三方域名加载，会引入隐私/安全问题

建议：

  • 尽可能优先使用内部/静态资源。
  • 始终设置显式的 width 和 height。
  • 保持图标细小（例如 16×16），以避免增加横幅高度。

可复用模式（复制/粘贴代码片段）​

<b>公告</b><br>
服务更新：<a href="https://example.com/status" target="_blank"><u>状态页面</u></a>

模式：紧凑型“标签”徽章（日期/影响标记）​

<span style="display:inline-block;background:#fff3cd;color:#664d03;padding:2px 8px;border-radius:999px;">
  已计划
</span>

模式：可折叠详情（保持横幅简短）​

<b>计划内更新</b><br>
<details>
  <summary>更多详情</summary>
  <br>
  本次更新可能会在部署窗口期内导致短暂的服务中断。
</details>

运营最佳实践​

保持横幅易于浏览​

一个好的横幅通常包含：

  • 简短的标题
  • 用一句话描述情况
  • 一个用于查看详情的链接和一个用于提问的链接（如有需要）

一致地使用横幅类型​

为了减少警报疲劳，可以考虑进行一致的类型映射：

  • info：一般公告
  • success：已完成的更改 / 已解决的故障
  • warning：计划内的维护或部分性能下降
  • error：正在发生的故障 / 服务中断

及时移除过期的横幅​

如果您不断添加新横幅而不移除旧横幅，用户可能会选择忽略它们。在事件结束后，请移除或替换横幅。

故障排除​

  • 确保 WEBUI_BANNERS 是一个有效的 JSON 对象数组（而不是单个对象）。
  • 检查服务器日志中与 WEBUI_BANNERS 相关的解析错误。
  • 如果使用 Admin Panel，请确认您已点击 Save。
  • 验证 dismissible 是否设置为 true。
  • 如果 dismissible 为 false，则该横幅故意设置为始终可见。
  • 从原始 HTML 中移除额外的空行和缩进。
  • 避免使用不支持的 HTML（列表、表格、标题）。
  • 减少激进的内联样式（大 padding、大 font-size）。

常见问题​

我可以在横幅内容中使用 Markdown 吗？​

不能。横幅内容仅支持 HTML。不会渲染 Markdown 语法。

timestamp 会控制横幅的显示时间吗？​

不会。前端目前未使用 timestamp 字段来控制是否显示横幅。如果您需要基于时间的行为，请通过您的部署自动化（按计划添加/删除横幅）进行管理。

我可以显示多种语言的内容吗？​

可以。您可以在 content 中包含多种语言。如果您想保持横幅简短，请将第二语言放入 <details> 块中。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.