可定制的横幅

概述

Open WebUI 允许管理员向已登录用户展示自定义横幅。横幅适用于公告、全系统警报、维护通知及其他重要消息。

横幅会持久显示，用户可选择关闭（可配置）。您可以通过两种方式配置横幅：

管理面板（推荐用于快速编辑和试验）
环境变量（WEBUI_BANNERS）（推荐用于自动化/GitOps 风格部署）

横幅的适用场景

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

计划维护和预定停机窗口
故障通知（性能降级、局部中断）
政策提醒（可接受使用、数据处理、保留策略）
重大变更（新模型、功能上线、界面变更）
指向内部通讯频道的链接，用于更新和答疑

提示： 保持横幅简洁，并链接到更详细的信息（状态页面、发布说明、支持频道）。

配置横幅

方式一：使用管理面板

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

以管理员身份登录 Open WebUI 实例。
导航到 管理面板 → 设置 → 通用。
找到横幅部分。
点击 + 图标添加新横幅。
点击保存应用更改。

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

类型： 横幅的颜色和样式：
- info（蓝色）
- success（绿色）
- warning（黄色）
- error（红色）
标题： 横幅的主标题。
内容： 主要消息（仅支持 HTML）。
可关闭： 启用后，用户可以关闭横幅。

关闭横幅的机制

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

如果用户清除站点数据/缓存，已关闭的横幅可能重新出现
在不同设备或浏览器上，已关闭的横幅可能重新出现
关闭状态与横幅 id 绑定（若 id 变更，横幅将被视为新横幅）

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

方式二：使用环境变量（`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（字符串，必填）：横幅的唯一标识符，用于跟踪用户是否已关闭。
type（字符串，必填）：横幅样式，必须为以下之一：info、success、warning、error。
title（字符串，可选）：标题文本。
content（字符串，必填）：横幅主要消息（仅支持 HTML）。
dismissible（布尔值，必填）：用户是否可以关闭横幅。
timestamp（整数，必填）：存在于配置中，但目前前端不使用该字段控制显示时间。

支持的内容格式（仅限 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">`	内联图片

自定义样式

支持在允许的标签上使用内联样式：

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

您也可以将整个消息区域包裹在块级元素中以应用样式：

<div style="background:#f8fafc;border:1px solid #cbd5e1;border-radius:12px;padding:10px 14px;line-height:1.3;display:block;width:100%;box-sizing:border-box;">
  <b>通知标题</b><br>
  简短的辅助消息。
</div>

保持样式有目的性。过大的内边距、字体大小或深度嵌套的布局可能导致横幅过高，或在不同主题下视觉不一致。

设计高效的横幅

当横幅易于扫读、视觉上突出且简短到不打断正常工作，效果最佳。

组织消息结构

采用可预测的结构：

以事件类型或状态开头：维护、故障、政策更新、新功能。
把最重要的信息放在最前：日期、时间、影响或所需操作。
正文保持一两句话。
仅在用户需要更多细节时添加一个链接。

对于较长的通知，使用短分段代替一段长段落。对于多语言通知，使用细 <hr> 分隔语言，或使用可折叠的 <details> 区块。

让严重程度可见

保持 type 的一致用法：

info：中性公告和产品更新。
success：已解决的故障或已完成的变更。
warning：计划维护、降级的服务或即将到来的待办操作。
error：活跃故障或需要紧急处理。

避免对非紧急公告使用 error。当每条消息看起来都"很紧急"时，用户会学会忽略告警。

谨慎使用颜色

颜色应辅助而非争夺横幅的视觉：

对完整消息区域使用柔和背景。
对小标签、强调或左边框使用较强的颜色。
保持文字对比度足够高，以便在明亮房间和暗光屏幕下都可读。
避免在同一条横幅中混用过多无关颜色。

一种有用的模式是柔和背景加上更醒目的左边框：

<div style="background:#f8fafc;color:#334155;border:1px solid #cbd5e1;border-left:6px solid #64748b;border-radius:12px;padding:10px 14px;line-height:1.3;display:block;width:100%;box-sizing:border-box;">
  <b>通知标题</b><br>
  简短的辅助消息。
</div>

让布局自适应

横幅显示在应用布局内，必须在窄屏下仍能正常显示。

对包含标签、日期或徽章的行，优先使用 display:flex;flex-wrap:wrap。
避免使用固定宽度。
对全宽样式块使用 width:100%;box-sizing:border-box。
保持图标和徽章较小，避免增加横幅高度。
在正式使用前，使用窄浏览器窗口测试横幅。

避免意外过高

横幅内容将字面换行视为换行符。如果您显式使用 <br> 标签，请保持原始 HTML 紧凑，避免在横幅内容字段中添加额外的空行或缩进。

如下这种紧凑风格：

<b>通知</b><br>一句简短的话。<br>另一句简短的话。

比含大量换行的格式化 HTML 渲染得更可控。

不支持的内容

以下内容在横幅中不受支持，可能以纯文本显示或破坏布局：

标题（<h1>–<h6>）
列表（<ul>、<ol>）
表格
引用块
Markdown 语法

如果需要"列表式"内容，请使用 <br> 分隔的短行。

常见陷阱（及如何避免）

1）字面换行导致意外间距

横幅内容将字面换行视为换行符。如果您粘贴了格式化/缩进良好的 HTML（含大量换行），横幅可能比预期高得多。

建议：

有意使用 <br>，保持原始 HTML 相对紧凑。
除非确实需要额外间距，否则不要添加空白行。

2）横幅内容中的链接失效

如果链接显示为"失效"或横幅其余部分变为可点击，通常是由于无效的 HTML。

请使用以下精确格式：

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

建议：

始终用 </a> 关闭锚标签。
使用 target="_blank"（含下划线）。

如果 URL 包含查询参数，在 href 属性中将 & 转义为 &：

<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 时，您是在将 JSON 嵌入 YAML 字符串（或 Shell 字符串）中。常见问题包括：

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>

模式：样式化通知块

当整条消息应作为一个公告区域呈现时，使用全宽样式块。粘贴到横幅内容字段时，请保持该 HTML 紧凑，特别是当其中还包含 <br> 标签时。

<div style="background:#f8fafc;color:#334155;border:1px solid #cbd5e1;border-left:6px solid #64748b;border-radius:12px;padding:10px 14px;line-height:1.3;display:block;width:100%;box-sizing:border-box;"><div style="display:flex;flex-wrap:wrap;align-items:center;gap:5px 8px;margin-bottom:5px;"><span style="display:inline-flex;align-items:center;background:#64748b;color:#fff;padding:1px 7px;border-radius:999px;line-height:1.25;font-size:10px;font-weight:700;letter-spacing:.04em;">NOTICE</span><b>通知标题</b><span style="display:inline-flex;align-items:center;background:#fff;color:#334155;padding:1px 8px;border-radius:999px;line-height:1.25;border:1px solid #cbd5e1;">关键信息</span></div><div>简短的辅助消息。</div></div>

此模式使用了：

完整消息区域的柔和背景。
更醒目的左边框以快速识别。
用于事件类型的小型大写标签。
用于最重要元数据的紧凑日期/时间徽章。
flex-wrap 使标题行在窄屏下也能正确显示。

运营最佳实践

保持横幅易于扫读

一个好的横幅通常包含：

简短的标题
一句话描述情况
一个详情链接和一个答疑链接（如有需要）

保持横幅类型的一致性

为减少告警疲劳，建议采用一致的映射：

info：一般公告
success：变更完成/故障已解决
warning：计划维护或局部降级
error：活跃故障/服务中断

移除过期横幅

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

故障排查

横幅未显示

确保 WEBUI_BANNERS 是有效的 JSON 数组（不是单个对象）。
检查服务器日志中与 WEBUI_BANNERS 相关的解析错误。
如果使用管理面板，确认已点击保存。

横幅无法关闭

确认 dismissible 已设为 true。
如果 dismissible 为 false，横幅是故意保持始终可见的。

横幅布局看起来错乱或过高

移除原始 HTML 中多余的空行和缩进。
避免使用不支持的 HTML（列表、表格、标题）。
减少过度的内联样式（过大的 padding、过大的 font-size）。

常见问题

横幅内容可以使用 Markdown 吗？

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

`timestamp` 是否控制横幅何时显示？

不会。timestamp 字段当前并未被前端用于控制横幅是否展示。如果需要按时间触发显示，请通过你的部署自动化来管理（按计划添加/移除横幅）。

可以同时展示多种语言的内容吗？

可以。你可以在 content 中包含多种语言。如果希望横幅保持简短，可以把次要语言放进 <details> 块中。

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议以了解适用条款。

概述​

横幅的适用场景​

配置横幅​

方式一：使用管理面板​

关闭横幅的机制​

方式二：使用环境变量（WEBUI_BANNERS）​

示例（Docker Compose）​

横幅对象属性​

推荐的 id 策略（重要）​

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

文本格式​

结构​

链接与媒体​

自定义样式​

设计高效的横幅​

组织消息结构​

让严重程度可见​

谨慎使用颜色​

让布局自适应​

避免意外过高​

不支持的内容​

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

1）字面换行导致意外间距​

2）横幅内容中的链接失效​

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

4）过度使用 <small>​

5）外部图片​

可复用模式（可复制粘贴的片段）​

模式：带链接的最简两行公告​

模式：紧凑"标签"徽章（日期/影响标签）​

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

模式：样式化通知块​

运营最佳实践​

保持横幅易于扫读​

保持横幅类型的一致性​

移除过期横幅​

故障排查​

横幅未显示​

横幅无法关闭​

横幅布局看起来错乱或过高​

常见问题​

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

timestamp 是否控制横幅何时显示？​

可以同时展示多种语言的内容吗？​

概述

横幅的适用场景

配置横幅

方式一：使用管理面板

关闭横幅的机制

方式二：使用环境变量（`WEBUI_BANNERS`）

示例（Docker Compose）

横幅对象属性

推荐的 `id` 策略（重要）

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

文本格式

结构

链接与媒体

自定义样式

设计高效的横幅

组织消息结构

让严重程度可见

谨慎使用颜色

让布局自适应

避免意外过高

不支持的内容

常见陷阱（及如何避免）

1）字面换行导致意外间距

2）横幅内容中的链接失效

3）`WEBUI_BANNERS` 中的 JSON/YAML 转义问题

4）过度使用 `<small>`

5）外部图片

可复用模式（可复制粘贴的片段）

模式：带链接的最简两行公告

模式：紧凑"标签"徽章（日期/影响标签）

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

模式：样式化通知块

运营最佳实践

保持横幅易于扫读

保持横幅类型的一致性

移除过期横幅

故障排查

横幅未显示

横幅无法关闭

横幅布局看起来错乱或过高

常见问题

横幅内容可以使用 Markdown 吗？

`timestamp` 是否控制横幅何时显示？

可以同时展示多种语言的内容吗？