17.4 · 版本与变更日志（Versioning and Changelog）

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

项目Open WebUI 章节17.4 状态全文译文模块界面与交互、测试、发布与运维、检索、召回与知识系统、接口与服务契约

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Versioning and Changelog 上一章17.3 下一章18

源码线索

.github/workflows/build-release.yml
.github/workflows/docker-build.yaml
.github/workflows/format-backend.yaml
.github/workflows/format-build-frontend.yaml
.github/workflows/release-pypi.yml
CHANGELOG.md
hatch_build.py
package-lock.json
package.json
src/app.css

模块标签

界面与交互
测试、发布与运维
检索、召回与知识系统
接口与服务契约
频道、笔记与协作

中文译文

版本与变更日志（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/17.4-versioning-and-changelog

翻译时间：2026-06-09T16:12:14.754Z

翻译模型：deepseek-chat

原文字符数：9521

项目：Open WebUI (open-webui)

---

版本管理与变更日志

目的与范围

本文档记录了 Open WebUI 的版本管理策略、变更日志维护规范以及发布流程。内容涵盖语义化版本方案、变更日志格式与结构、版本号在代码库中的存储位置，以及负责向 GitHub、Docker Hub 和 PyPI 发布的自动化 CI/CD 工作流。

---

版本管理策略

Open WebUI 遵循 CHANGELOG.md:6 中记录的语义化版本 2.0.0 规范。版本格式为 MAJOR.MINOR.PATCH：

MAJOR：不兼容的 API 变更。
MINOR：以向后兼容的方式新增功能（例如，v0.9.2 中引入的 PaddleOCR-vl 文档提取或 Firecrawl v2 API 支持 CHANGELOG.md:12-13）。
PATCH：向后兼容的缺陷修复（例如，v0.9.2 中解决的 Docker ARM64 可靠性或 MCP 任务取消稳定性问题 CHANGELOG.md:28-31）。

当前版本存储位置

版本号在代码库的多个位置维护，以确保前端、后端和包管理器之间的一致性：

位置	用途	示例
`package.json`	前端应用版本和构建元数据	`"version": "0.9.2"` `package.json:3`
`package-lock.json`	依赖锁定和项目版本	`"version": "0.9.2"` `package-lock.json:3`
`CHANGELOG.md`	带发布说明的版本历史	`## [0.9.2] - 2026-04-24` `CHANGELOG.md:8`

版本元数据流转

下图展示了 package.json 中的版本字符串如何通过自动化发布流水线传播到各个分发平台。

graph TD
    subgraph "真相源"
        [package.json] -- "version: 0.9.2" --> [Build_Release_WF]
    end

    subgraph "CI/CD 自动化"
        [Build_Release_WF] -- "jq -r .version" --> [Release_Logic]
        [Release_Logic] -- "触发" --> [Docker_Build_WF]
        [Release_Logic] -- "触发" --> [PyPI_Release_WF]
    end

    subgraph "分发点"
        [GitHub_Release]
        [Docker_Hub_GHCR]
        [PyPI_Package]
    end

    [Release_Logic] -- "gh release create v{version}" --> [GitHub_Release]
    [Docker_Build_WF] -- "tags: type=semver" --> [Docker_Hub_GHCR]
    [PyPI_Release_WF] -- "python -m build" --> [PyPI_Package]

来源： package.json:1-4、.github/workflows/build-release.yml:23-28、.github/workflows/docker-build.yaml:61-71、.github/workflows/release-pypi.yml:30-34

---

变更日志格式与结构

变更日志遵循 Keep a Changelog 1.1.0 格式 CHANGELOG.md:5。它是自动化 GitHub Release 创建过程中发布说明的主要来源。

条目结构

每个版本条目都使用标准分类进行组织，以提高用户和开发者的可读性：

Added：新增功能，例如 自定义 API 密钥头 支持 CHANGELOG.md:15 或 OAuth 会话断开 端点 CHANGELOG.md:16。
Fixed：缺陷修复，例如 异步数据库驱动迁移 到 psycopg v3 CHANGELOG.md:30 或 取消响应流清理 CHANGELOG.md:38。
Changed：对现有功能的修改，例如用 psycopg v3 异步驱动 替换 asyncpg 的迁移 CHANGELOG.md:47-49。

自动提取

build-release.yml 工作流使用 awk 根据 package.json 中的版本字符串，以编程方式从 CHANGELOG.md 中提取最新条目。提取的文本保存到 /tmp/release-notes.md，并用作 GitHub Release 的正文 build-release.yml:29-33, 38-40。

---

发布流程与 CI/CD

发布流程通过 GitHub Actions 高度自动化，由推送到 main 分支或特定标签触发。

1. 发布触发与版本管理

build-release.yml 工作流启动该流程：

变更检测：验证 package.json 是否已被修改 build-release.yml:16-21。
版本获取：使用 jq 提取版本号 build-release.yml:26。
创建 Release：创建以 v{version} 为标签的 GitHub Release，并附加提取的变更日志说明 build-release.yml:38-41。

2. Docker 镜像分发

一旦 Release 被标记，docker-build.yaml 工作流即被触发。它会构建多平台镜像（linux/amd64、linux/arm64）docker-build.yaml:21-29。

构建变体：生成标准镜像和用于 GPU 支持的 cuda 变体 docker-build.yaml:192-207。
元数据：镜像使用版本号、主次版本号和 latest（如果在 main 分支上）进行标记 docker-build.yaml:66-73。
构建参数：BUILD_HASH 被传入 Docker 构建过程，以标识特定的 git 提交 docker-build.yaml:100, 205。

3. PyPI 分发

release-pypi.yml 工作流处理 Python 包的分发：

构建：使用 python -m build . 创建源码分发包和 wheel 分发包 release-pypi.yml:34。
发布：使用 pypa/gh-action-pypi-publish 操作将包上传到 PyPI release-pypi.yml:36。
前端集成：hatch_build.py 脚本确保在 Python 构建过程中执行 npm install 和 npm run build，以便将编译后的前端包含在 PyPI 包中 hatch_build.py:10-21。

---

代码质量与格式化

通过 CI 流水线中的强制格式化和 lint 步骤，确保各版本之间的一致性。

质量门禁

前端：format-build-frontend.yaml 工作流运行 npm run format、npm run i18n:parse 和 npm run build format-build-frontend.yaml:37-47。它还执行 Vitest 单元测试 format-build-frontend.yaml:65。
后端：format-backend.yaml 工作流运行 ruff format --check 以确保 Python 代码符合样式指南 format-backend.yaml:45-46。

格式化配置

前端：在 package.json 中配置为使用 Prettier，并包含 Svelte、CSS 和 Markdown 插件 package.json:17, 41-42。
后端：使用 ruff format 进行 Python 格式化，排除虚拟环境 package.json:18。

sequenceDiagram
    participant Dev as "开发者"
    participant CI as "GitHub Actions"
    participant Repo as "仓库"

    Dev->>Repo: git push (main)
    Repo->>CI: 触发前端/后端 CI
    par 前端质量检查
        CI->>CI: npm run format
        CI->>CI: npm run i18n:parse
        CI->>CI: npm run build
        CI->>CI: npm run test:frontend
    and 后端质量检查
        CI->>CI: ruff format --check
    end
    Note over CI: 仅当质量门禁通过后才触发发布工作流

来源： package.json:13-22、.github/workflows/format-build-frontend.yaml:23-66、.github/workflows/format-backend.yaml:23-46

---

运行时版本展示

应用程序通过 Vite 配置和 Svelte 组件处理版本特定的渲染和构建元数据。

构建元数据注入

vite.config.ts 文件在构建过程中将版本信息注入到前端应用程序中：

APP_VERSION：从 npm_package_version 注入 vite.config.ts:20。
APP_BUILD_HASH：从环境变量注入，默认为 dev-build vite.config.ts:21。

内容渲染

应用程序使用 marked 解析 Markdown src/lib/components/common/RichTextInput.svelte:2, 6-30，并使用 DOMPurify 确保安全 src/lib/components/common/RichTextInput.svelte:3。系统在 HTML 和 Markdown 之间的转换过程中，使用 TurndownService 专门处理任务列表和 GFM 表格 src/lib/components/common/RichTextInput.svelte:32-107。

---

贡献者最佳实践

同步更新：提交功能时，在同一 Pull Request 中更新 CHANGELOG.md。
引用可追溯性：在变更日志条目中包含 GitHub Issue 或 PR 链接（例如，#23945 CHANGELOG.md:12）。
格式化：在推送前本地运行 npm run format 和 npm run lint，以确保 CI 通过 package.json:13, 17。
依赖管理：确保新依赖同时添加到 package.json 和 Python 构建配置中（例如，迁移到 psycopg v3 CHANGELOG.md:30）。

来源： package.json:13-18、CHANGELOG.md:1-40、vite.config.ts:19-22