Chuyển tới nội dung chính

🧪 Hướng dẫn nhánh phát triển

Nhánh dev chứa các cải tiến và tính năng thử nghiệm trước khi vào main.

Phần mềm thử nghiệm

Nhánh dev có thể chứa lỗi, tính năng chưa hoàn chỉnh hoặc thay đổi phá vỡ tương thích.

🎯 Nhánh Dev là gì?​

  • Tính năng mới
  • Sửa lỗi đang kiểm tra
  • Cải tiến giao diện
  • Tối ưu hiệu năng

🚀 Dùng nhánh Dev​

Docker (khuyến nghị)​

Compose gắn socket Docker host để Work hoạt động. Trên Linux đặt DOCKER_GID trong .env; xác nhận vùng chứa bằng docker ps.

# 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
# 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

Từ mã nguồn​

# 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

Vite có thể sẵn sàng trước khi backend hoàn tất các bước kiểm tra khởi động. Với backend cục bộ, proxy phát triển chờ tối đa 10 giây để bắt được listener trước khi chuyển tiếp một yêu cầu API. Nó chỉ chuyển tiếp mỗi yêu cầu một lần, kể cả yêu cầu ghi; nó không phát lại các yêu cầu thất bại. Nếu backend vẫn không sẵn sàng, proxy trả về HTTP 503 kèm gợi ý thử lại. Các tệp frontend tĩnh vẫn dùng được trong lúc chờ.

Chat tiếp tục kết nối lại sau những gián đoạn tạm thời của backend, với độ trễ tối đa 30 giây. Kết nối thành công sẽ đặt lại độ trễ; đăng xuất sẽ hủy các lần thử đang chờ. Lỗi xác thực sẽ dừng việc tự động kết nối lại.

Kiểm tra Work​

  1. Xác nhận docker info.
  2. Chạy npm run dev.
  3. Đăng nhập quản trị viên.
  4. Chọn mô hình có công cụ.
npm run test:work

Xem Work để biết ranh giới đầy đủ.

🔄 Cập nhật​

# 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

🐛 Báo lỗi​

Trước khi báo​

  1. Tìm GitHub Issues.
  2. Thử bản ổn định.
  3. Xác nhận tái hiện được.

Cách báo​

🐛 Báo lỗi

**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]

Lấy mã commit​

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

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

🏆 Đóng góp và ghi nhận​

Ghi nhận người đóng góp​

Người đóng góp hiện tại​

Đóng góp mã​

  1. Fork kho.
  2. git checkout -b feature/amazing-feature dev
  3. Thay đổi.
  4. Gửi Pull Request đến dev.

Xem hướng dẫn và Community Charter.

Kiểm tra Pull Request​

Mọi pull request, kể cả pull request xếp chồng vào một nhánh feature hoặc fix trung gian, đều chạy workflow Format & Lint. Các job độc lập của workflow này kiểm tra định dạng, lint frontend và backend, kiểu TypeScript, kiểm thử gói và kiểm thử hồi quy, cùng bộ kiểm thử trình duyệt Playwright. Chromium chạy toàn bộ bộ kiểm thử trình duyệt. WebKit và Firefox cũng chạy các luồng quan trọng: xác thực, streaming, hộp thoại, tab, tự động hóa, lưu trữ, Work và phát giọng nói. Mỗi engine trình duyệt chạy trong một job CI riêng, và các lần chạy thất bại tải lên kết quả kiểm thử riêng.

Tarball npm đã kiểm thử được cài vào một thư mục người dùng mới trên Linux, macOS và Windows, với cả Node 22.22 và Node 24. Các bước kiểm tra này cài dependency production thật, không mượn node_modules của bản checkout, rồi xác minh việc khởi động CLI, trạng thái sẵn sàng, việc phục vụ frontend và dữ liệu sau khi khởi động lại. Để chạy cùng bước kiểm tra này trên máy, sau npm run build hãy chạy npm run test:package-install; truyền vào một tarball hoặc một thư mục chứa đúng một tarball để kiểm thử một artifact cụ thể. Bản cài sạch cần truy cập registry và các điều kiện build native module thông thường của nền tảng khi không có dependency dựng sẵn.

Một job Work Computer riêng dựng image GUI từ base đã ghim của runtime và chạy bài kiểm thử hồi quy tương tác thật. TEST_WORK_COMPUTER=1 khiến việc thiếu Docker daemon hoặc image làm bước kiểm tra thất bại thay vì bỏ qua. Để tái hiện trên máy, đặt cờ đó và đặt WORK_COMPUTER_TEST_IMAGE thành một image kiểm thử được dựng riêng, rồi chạy npm run test:work-computer. Khi không bật chế độ bắt buộc, lần chạy trên máy vẫn báo bỏ qua nếu thiếu fixture GUI tùy chọn.

Ma trận này thêm bước kiểm tra cho các bề mặt được hỗ trợ; nó không bật các tổ hợp không được hỗ trợ. Thông tin xác thực CLI cục bộ trên node vẫn không khả dụng với worker nhóm bên ngoài.

CodeQL bao phủ mã JavaScript/TypeScript, Python và workflow trên mọi pull request. Các server nhà cung cấp Python thực thi được trong examples/ được phân loại rõ là mã trong .gitattributes, nên tính năng nhận diện ngôn ngữ của GitHub có tính đến chúng. Thiết lập Code Quality được quản lý riêng nên bao gồm cả JavaScript/TypeScript và Python. Nếu phát hiện cũ vẫn còn sau khi đã sửa, hãy kiểm tra revision đã được phân tích và phạm vi ngôn ngữ, rồi làm mới phân tích tương ứng sau khi phát hành thay đổi. Đừng bỏ qua các phát hiện hợp lệ hay thay đổi hành vi bất đồng bộ đúng đắn chỉ để cải thiện điểm hiển thị.

Workflow Electron Dev Build cũng đóng gói artifact cho macOS, Windows và Linux. Bản dựng pull request trên macOS giữ chữ ký ad-hoc không cần thông tin xác thực của dự án để có thể xác minh ứng dụng đã đóng gói trước khi tải lên. Workflow pull request không nhận thông tin xác thực Developer ID hay notarization.

Workflow Docker Build Test and Push dựng image amd64 và arm64 cho mọi pull request, kể cả pull request xếp chồng vào nhánh trung gian. Bản dựng pull request không đăng nhập vào container registry, không đẩy image digest và không phát hành manifest đa kiến trúc.

Chạy cùng các bước kiểm tra cấp ứng dụng trên máy trước khi mở pull request:

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

⚠️ Lưu ý​

An toàn dữ liệu​

  • Sao lưu trước khi chuyển dev.
  • Volume Work libre-work-* cần sao lưu riêng.
  • Dùng volume riêng: 
    # 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

Vấn đề có thể xảy ra​

  • Thay đổi phá vỡ tương thích
  • Tính năng chưa hoàn chỉnh
  • Hiệu năng/giao diện thay đổi

Khi dùng bản ổn định​

Quay lại main khi cần độ tin cậy:

# 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

🌟 Cộng đồng​

Cảm ơn bạn đã thử nghiệm và đóng góp!