跳到主要内容

可自定义通知消息

概览​

OPL 数据空间允许管理员向已登录用户展示自定义通知消息。它适合发布公告、系统告警、维护通知以及其他高可见度消息。

通知消息默认是持久显示的，也可以配置为允许用户手动关闭。你可以通过两种方式管理：

  1. 管理面板
  2. 环境变量 WEBUI_BANNERS

适用场景​

通知消息适合这类短消息：

  • 计划维护和停机窗口
  • 故障或降级通知
  • 策略提醒，例如可接受使用规范、数据保留规则
  • 重大功能变更、模型更新或 UI 调整
  • 指向内部状态页、支持群或公告渠道的链接

建议把通知消息写短，并链接到更详细的说明页面。

配置方式​

方式 1：管理面板​

  1. 以管理员身份登录
  2. 前往 管理面板 → 设置 → 通用
  3. 找到 公告横幅
  4. 点击 + 新增通知消息
  5. 点击 保存

每条通知消息可配置：

  • 类型：信息、成功、警告、错误
  • 标题：标题
  • 内容：正文，仅支持 HTML
  • 是否记住关闭状态：是否允许用户关闭

关闭行为说明​

通知消息的关闭状态保存在 用户浏览器本地，因此：

  • 清除浏览器站点数据后可能重新出现
  • 换浏览器或换设备也会重新出现
  • 关闭状态按通知消息 id 区分，id 变了就会被视为新通知消息

如果你希望所有人都持续看到它，请将 dismissible 设为 false。

方式 2：环境变量 WEBUI_BANNERS​

自动化部署或 GitOps 场景下，可以直接通过环境变量配置。它的值必须是一个 JSON 字符串，内容是通知消息对象数组。

示例：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - 'WEBUI_BANNERS=[{"id":"maintenance-2026-03","type":"warning","title":"Maintenance","content":"A maintenance window is planned this week. <a href=\"https://intranet.example.com/status\" target=\"_blank\">See status page</a>.","dismissible":true,"timestamp":1772500000}]'

通知消息对象字段​

每个通知消息对象支持：

  • id：唯一标识，必填
  • type：info、success、warning、error
  • title：可选标题
  • content：正文，必填，仅支持 HTML
  • dismissible：是否允许关闭
  • timestamp：配置中可存在，但前端当前不会用它控制展示时间

id 建议​

  • 稳定 id：用于小改文案，例如 policy-reminder
  • 版本化 id：用于强制所有人重新看到，例如 incident-2026-03-06-v2
  • 按时间分桶：适用于周期性事件，例如 maintenance-2026-03

如果用户已经关闭某条通知消息，而你希望更新后再次展示给他们，请修改 id。

支持的内容格式​

通知消息的 title 和 content 只支持 HTML，不支持 Markdown。

可用内容包括：

  • 文本样式：<b>、<strong>、<i>、<em>、<u>、<code> 等
  • 结构元素：<br>、<hr>、<details><summary>...
  • 链接和图片：<a>、<img>
  • 允许的内联样式：例如 style="color: #b91c1c;"

不建议使用：

  • 标题标签 <h1> 到 <h6>
  • 列表
  • 表格
  • blockquote
  • Markdown 语法

常见坑​

1. HTML 换行导致通知消息过高​

通知消息会把原始 HTML 中的换行也当作换行展示。不要把内容写得过于稀疏，必要时手动用 <br> 控制。

2. 链接写坏​

推荐使用这种形式：

<a href="https://example.com" target="_blank">Open link</a>

注意：

  • 必须闭合 </a>
  • target="_blank" 中要有下划线
  • 带查询参数的 URL 要把 & 写成 &amp;

3. WEBUI_BANNERS 的 JSON / YAML 转义问题​

常见错误包括：

  • JSON 内双引号没转义
  • JSON 字符串中途被换行
  • 误用了智能引号

上线前建议先用 JSON 校验器检查内容。

4. 过度使用 <small>​

<small> 适合辅助说明，不适合包住整段主文案。

5. 外部图片​

外部图片可能加载失败、尺寸不一致，或带来隐私风险。尽量使用内部静态资源，并固定宽高。