跳到主要内容

🧪 开发分支指南

想在正式发布前体验最新功能吗？dev 分支包含前沿改进和实验性功能，它们最终会进入主发行版。

实验性软件

dev 分支处于实验阶段，可能包含缺陷、未完成功能或破坏性变更。只有在你能接受潜在的不稳定性并愿意帮助改进 Libre WebUI 时才应使用它。

🎯 什么是 Dev 分支？​

开发分支（dev）用于在新功能合并到稳定的 main 分支之前进行测试。它包括：

  • 尚未进入稳定发行版的最新功能
  • 正在测试的缺陷修复
  • 针对界面和功能的实验性改进
  • 正在开发的性能优化

🚀 如何使用 Dev 分支​

Docker 设置（推荐）​

开发版 Compose 文件会挂载主机 Docker socket，因此在 Docker 可用时，Work 默认即可运行。任务容器在主机守护进程上运行，并会显示在 docker ps 中。在 Linux 上，请先在 .env 中设置 DOCKER_GID。

使用外部 Ollama：

# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui

# Switch to dev branch
git checkout dev

# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d

简单 Docker 方式：

# Use the dev branch image
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

从源代码运行​

# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev

# Install dependencies
npm install

# Start development server
npm run dev

测试 Work​

  1. 启动 Docker，并以运行后端的同一用户确认 docker info 成功。
  2. 使用 npm run dev 从源代码启动 Libre WebUI。
  3. 以管理员身份登录。
  4. 选择 Work，并使用支持工具调用的 Ollama、Ollama Cloud 或已配置的插件模型。

运行专门的后端提供商和容器策略测试：

npm run test:work

这些测试会验证生成的 Docker 策略、路径包含关系、生命周期与容量行为，以及 OpenAI 兼容、Anthropic 和 Gemini 工具适配器。完整运行时边界请参阅 Work：隔离工作区。

🔄 保持更新​

dev 分支更新频繁。获取最新变更：

# Update your local dev branch
git pull origin dev

# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d

# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev

🐛 发现缺陷？帮助我们改进！​

你的缺陷报告非常宝贵！以下是有效报告问题的方法：

报告前​

  1. 检查现有问题：搜索 GitHub Issues，避免重复报告
  2. 尝试稳定版：确认缺陷只存在于 dev，而不在 main 分支中
  3. 稳定复现：能否让缺陷再次出现？

如何报告缺陷​

🐛 在 GitHub 上报告缺陷

请包含以下信息：

**Environment:**

- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]

**Bug Description:**
Clear description of what went wrong

**Steps to Reproduce:**

1. Go to...
2. Click on...
3. See error...

**Expected Behavior:**
What should have happened

**Actual Behavior:**
What actually happened

**Screenshots/Logs:**
[If applicable, add screenshots or error logs]

**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]

获取 Git 提交哈希​

# Find your current dev branch commit
git rev-parse HEAD

# Or get a short version
git rev-parse --short HEAD

🏆 贡献与认可​

使用 dev 分支就意味着你加入了我们的测试社区！贡献者会通过多种方式获得认可：

对贡献者的认可​

  • 列入 CONTRIBUTORS.md
  • 对重大贡献在发行说明中提及
  • 在提交消息中标注共同作者
  • 在项目公告中特别致谢

当前贡献者​

我们出色的社区包括：

  • rob - 项目维护者
  • jm - 网络访问增强
  • **以及更多贡献者！**请查看完整名单

想贡献代码？​

  1. 复刻仓库
  2. 从 dev 创建功能分支：git checkout -b feature/amazing-feature dev
  3. 进行修改
  4. 向 dev 分支提交 Pull Request

详细说明请参阅贡献指南，项目道德准则和治理模式请参阅社区宪章。

Pull Request 检查​

每个 Pull Request 都会运行 Format & Lint 工作流，包括合并到中间功能或修复分支的堆叠式 Pull Request。其独立作业会检查格式、前端和后端 lint、TypeScript 类型、软件包与回归测试，以及 Playwright 浏览器测试套件。浏览器运行失败时会上传 Playwright 结果以供调试。

Electron Dev Build 工作流还会打包 macOS、Windows 和 Linux 产物。macOS Pull Request 构建会保留项目不使用凭据的临时签名，以便在上传前验证打包应用。Pull Request 工作流不会接收 Developer ID 或公证凭据。

Docker Build Test and Push 工作流会为每个 Pull Request 构建 amd64 和 arm64 镜像，包括进入中间分支的堆叠式 Pull Request。Pull Request 构建不会登录容器注册表、推送镜像摘要或发布多架构清单。

打开 Pull Request 前，请在本地运行相同的应用级检查：

npm run format:check
npm run lint
npm run test:package
npm run test:e2e

⚠️ 重要说明​

数据安全​

  • 切换到 dev 分支前请备份数据
  • Work 任务文件位于单独的 libre-work-* Docker 命名卷中。测试破坏性任务或用户生命周期变更前，请将它们与 SQLite 数据目录分开备份。
  • dev 测试请使用单独的 Docker 卷： 
    # Use different volume name for dev
    docker run -d -p 3000:3001 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev

潜在问题​

  • 破坏性变更可能需要更新配置
  • 功能可能尚未完成，或在不另行通知的情况下发生变化
  • 测试优化期间，性能可能有所波动
  • 界面元素可能外观不同或行为异常

何时使用稳定版​

如果存在以下情况，请切回稳定的 main 分支：

  • 重要工作需要可靠性
  • 遇到太多缺陷
  • 希望获得经过测试的稳定体验
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d

🌟 加入社区​

准备好帮助塑造 Libre WebUI 的未来了吗？ 🚀

你在 dev 分支上的测试、反馈和贡献会直接改善所有用户的体验。感谢你成为开发社区的一员！