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

Khắc phục sự cố

Hãy bắt đầu từ lớp đang gặp lỗi: trình duyệt, frontend, backend, Ollama, plugin nhà cung cấp hoặc mạng triển khai.

Kiểm tra nhanh​

# App branch and local changes
git status

# Backend process liveness
curl http://localhost:3001/health/live

# Backend dependency readiness (SQLite, schema, and writable data storage)
curl http://localhost:3001/health/ready

# Ollama health
curl http://localhost:11434/api/tags

# Installed Ollama models
ollama list

Trong môi trường phát triển, frontend thường chạy tại http://localhost:5173 và backend tại http://localhost:3001. Quy trình đóng gói npx libre-webui phục vụ ứng dụng tại http://localhost:8080.

Libre WebUI không khởi động​

Kiểm tra Node và các phần phụ thuộc

node --version
npm install
npm run dev

Cần Node.js 22.22 trở lên.

Cổng đã được sử dụng

lsof -i :3001
lsof -i :5173
lsof -i :8080

Dừng tiến trình cũ hoặc cấu hình cổng khác.

Backend không thể ghi dữ liệu

Backend lưu dữ liệu trong DATA_DIR nếu được đặt, nếu không là backend/data. Khi chạy từ nguồn, DATA_DIR tương đối được phân giải từ thư mục backend chứ không phải thư mục hiện tại của shell. Vì vậy DATA_DIR=./data chọn backend/data, còn DATA_DIR=./backend/data được hỗ trợ từ trước chọn backend/backend/data. Hãy đảm bảo thư mục đã chọn có thể ghi. Nếu không đặt DATA_DIR, Libre giữ thư mục cũ khi đó là kho duy nhất hiện có. Nếu cả hai vị trí đều có dữ liệu, hãy dừng Libre, sao lưu cả hai rồi chủ động chọn hoặc di chuyển; Libre không bao giờ hợp nhất hay sao chép các cơ sở dữ liệu khác nhau.

Các endpoint kiểm tra tình trạng được chủ ý tách biệt giữa một tiến trình đang chạy và một ứng dụng thực sự sẵn sàng sử dụng:

  • /health và /health/live trả 200 khi tiến trình backend có thể phục vụ HTTP. Nhà cung cấp mô hình tùy chọn không ảnh hưởng đến tình trạng hoạt động này.
  • /health/ready trả 503 khi cơ sở dữ liệu, lược đồ, hệ thống lưu trữ hoặc phần phụ thuộc nền tảng bắt buộc đã đăng ký không khả dụng. Endpoint này không chờ nhà cung cấp mô hình tùy chọn. Phản hồi công khai không chứa thông báo lỗi hoặc chi tiết nội bộ.
  • /health/deep kiểm tra tính toàn vẹn và khóa ngoại SQLite trong một worker có giới hạn, đồng thời tổng hợp các phép kiểm tra nhà cung cấp tùy chọn ở cấp máy chủ như Ollama. Sự cố với nhà cung cấp tùy chọn xuất hiện dưới dạng cảnh báo và không làm mất trạng thái sẵn sàng của phần phụ thuộc bắt buộc. Endpoint này cần bearer token hiện tại của quản trị viên và không phù hợp để hệ thống điều phối thăm dò thường xuyên.
curl -H "Authorization: Bearer $LIBRE_ADMIN_TOKEN" \
  http://localhost:3001/health/deep

Trình duyệt không truy cập được backend​

Trong quá trình phát triển cục bộ, frontend dùng VITE_API_BASE_URL nếu biến này được đặt; nếu không, nó dùng backend phát triển mặc định.

Ví dụ .env frontend:

VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_BASE_URL=ws://localhost:3001

VITE_WS_BASE_URL là tùy chọn, nhưng khi được đặt sẽ làm URL cơ sở chung cho socket Chat và terminal Work. Dùng URL ws: hoặc wss: tuyệt đối; tiền tố đường dẫn như wss://example.com/libre được hỗ trợ. Không đưa thông tin xác thực, tham số truy vấn hoặc mảnh URL vào giá trị này. Hãy khởi động lại hoặc dựng lại frontend sau khi đổi biến Vite.

Ví dụ .env backend:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Để truy cập bằng điện thoại qua LAN hoặc Tailscale, đừng trỏ trình duyệt trên điện thoại đến localhost; hãy dùng địa chỉ IP LAN hoặc Tailscale của máy tính xách tay và chạy máy chủ phát triển ở chế độ liên kết với máy chủ:

npm run dev:host

Lệnh này phục vụ frontend trên cổng 8080 và chuyển tiếp lưu lượng API và WebSocket đến backend cục bộ trên cổng 3001. Chỉ cổng 8080 cần được truy cập từ thiết bị khác. Nếu VITE_API_BASE_URL hoặc VITE_WS_BASE_URL được đặt trong frontend/.env, hãy đảm bảo các URL đó có thể truy cập được từ thiết bị khác, hoặc xóa chúng để sử dụng proxy của máy chủ phát triển.

Trò chuyện không truyền dữ liệu theo luồng sau proxy ngược​

Triệu chứng thường gặp là tin nhắn được gửi nhưng không bao giờ hiển thị phản hồi, trong khi bảng điều khiển của trình duyệt báo lỗi kết nối WebSocket. Hãy xác nhận proxy cho phép nâng cấp kết nối WebSocket và không đóng các kết nối tồn tại lâu.

Khi một trong hai giá trị được cấu hình, các yêu cầu nâng cấp từ trình duyệt có gửi tiêu đề Origin sẽ được đối chiếu với CORS_ORIGIN và BASE_URL. Với bản triển khai từ xa, hãy đặt ít nhất một trong hai biến; nếu cả hai đều chưa được cấu hình, bộ lọc Origin vẫn cho phép linh hoạt để phục vụ phát triển cục bộ. Electron và các ứng dụng khách không phải trình duyệt có thể không gửi Origin, nhưng trước tiên chúng vẫn phải đổi tiêu đề Authorization lấy một vé dùng một lần có thời hạn ngắn. Hãy đặt backend sau TLS và áp dụng cùng các biện pháp kiểm soát truy cập mạng hoặc proxy ngược đang dùng cho HTTP API.

Với tên máy chủ công khai, hãy cho phép origin của trình duyệt đó trong dịch vụ Libre WebUI:

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://chat.example.com
      BASE_URL: https://chat.example.com

Các ví dụ nginx và Caddy dưới đây giả định proxy chạy trên máy chủ Docker, nơi cấu hình Compose của kho mã công bố Libre WebUI ở cổng 8080. Nếu proxy tham gia mạng Compose, hãy dùng libre-webui:3001 làm địa chỉ máy chủ đầu nguồn.

nginx​

nginx yêu cầu chuyển tiếp rõ ràng các tiêu đề nâng cấp. Thời gian chờ đọc dài hơn giúp duy trì kết nối trò chuyện vốn đang nhàn rỗi trong lúc mô hình xử lý.

location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

Sau khi xác thực cấu hình bằng nginx -t, hãy nạp lại nginx.

Caddy​

reverse_proxy của Caddy hỗ trợ WebSocket ngay khi cài đặt nên không cần tiêu đề nâng cấp:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik​

Traefik cũng xử lý việc nâng cấp WebSocket theo mặc định. Khi nhà cung cấp Docker của Traefik dùng chung mạng với Libre WebUI, bạn chỉ cần các nhãn bộ định tuyến và dịch vụ thông thường, ví dụ:

labels:
  - 'traefik.enable=true'
  - 'traefik.http.routers.libre-webui.rule=Host(`chat.example.com`)'
  - 'traefik.http.routers.libre-webui.entrypoints=websecure'
  - 'traefik.http.routers.libre-webui.tls=true'
  - 'traefik.http.services.libre-webui.loadbalancer.server.port=3001'

Nếu luồng kết nối được nhưng ngắt sau đó, hãy kiểm tra thời gian chờ khi nhàn rỗi trên mọi proxy hoặc bộ cân bằng tải đặt trước Traefik. Khi chính Traefik áp dụng giới hạn này, hãy điều chỉnh cài đặt transport.respondingTimeouts của điểm vào.

Không phát hiện Ollama​

Xác nhận Ollama đang chạy

curl http://localhost:11434/api/tags

Cấu hình URL Ollama tùy chỉnh

Tệp .env của backend:

OLLAMA_BASE_URL=http://localhost:11434

Nếu Libre WebUI chạy trong Docker còn Ollama chạy trên máy chủ, hãy dùng tệp Compose dành cho Ollama bên ngoài hoặc trỏ OLLAMA_BASE_URL đến địa chỉ máy chủ mà vùng chứa có thể truy cập.

Sự cố tải mô hình​

Trước tiên hãy tải mô hình từ dòng lệnh

ollama pull gemma4:12b

Nếu thao tác tải từ dòng lệnh thất bại, sự cố nằm ngoài Libre WebUI.

Mô hình đám mây

Dùng bộ lọc đám mây trong Trình quản lý mô hình cho các mô hình Ollama Cloud. Libre WebUI tự chuẩn hóa những hậu tố đám mây bắt buộc trong quy trình này, vì vậy người dùng không cần tự thêm :cloud cho các mục đám mây được hỗ trợ.

Người dùng không thể tải mô hình

Quản trị viên có thể tắt quyền tải mô hình đối với người dùng thông thường. Hãy kiểm tra cài đặt quản trị nếu người dùng không phải quản trị viên có thể duyệt mô hình nhưng không thể cài đặt.

Trò chuyện chậm hoặc thất bại​

  • Dùng mô hình nhỏ hơn.
  • Kiểm tra các mô hình đã nạp bằng ollama ps.
  • Giảm độ dài ngữ cảnh.
  • Giảm số token tối đa cho các phản hồi rất dài.
  • Xác nhận mô hình vừa với dung lượng RAM/VRAM.
  • Với plugin nhà cung cấp, hãy xác nhận khóa API và hạn mức của nhà cung cấp.

Tạo hình ảnh OpenAI không khả dụng​

  • Kích hoạt nhà cung cấp OpenAI tích hợp sẵn. Lưu khóa API cho người dùng hiện tại hoặc cấu hình cơ chế dùng biến môi trường OPENAI_API_KEY dự phòng của nhà cung cấp tích hợp sẵn đáng tin cậy.
  • Mở cài đặt Image Generation, bật tính năng tạo hình ảnh và chọn một trong các mô hình GPT Image được công bố.
  • Ưu tiên gpt-image-2. Các ID GPT Image cũ hơn chỉ còn khả dụng để tương thích với cấu hình hiện có và đã bị nhà cung cấp đầu nguồn đánh dấu không còn khuyến nghị.
  • Để trống giá trị ghi đè image_endpoint của OpenAI trừ khi bạn vận hành một endpoint hình ảnh tương thích. Endpoint Chat /responses hoặc /chat/completions không thể xử lý yêu cầu Image API.
  • Nếu OpenAI từ chối yêu cầu GPT Image dù khóa và hạn mức đều hợp lệ, hãy xác nhận tổ chức API đủ điều kiện sử dụng các mô hình GPT Image.

Tính khả dụng của mô hình hình ảnh được đánh giá bằng thông tin xác thực đã lưu của người dùng hiện tại hoặc cơ chế dùng biến môi trường dự phòng của nhà cung cấp tích hợp sẵn đáng tin cậy. Khóa chỉ được lưu trong cài đặt của người dùng khác sẽ không làm các mô hình hình ảnh xuất hiện.

Sự cố endpoint nhà cung cấp​

Nếu nhà cung cấp tương thích OpenAI nhận yêu cầu tại đường dẫn không đúng, hãy kiểm tra cài đặt của nhà cung cấp trong Settings → Plugins:

  • Chọn Chat Completions cho dữ liệu gửi đến /chat/completions hoặc Responses cho dữ liệu gửi đến /responses.
  • Nhập gốc API, chẳng hạn https://provider.example/v1, làm Base URL.
  • Để trống API Path để dùng đường dẫn mặc định của chế độ hoặc nhập đường dẫn do nhà cung cấp cung cấp và bắt đầu bằng dấu gạch chéo.
  • Endpoint đầy đủ kiểu cũ thực sự tùy chỉnh được chủ ý đặt ở mức ưu tiên cao nhất, vì vậy hãy xóa giá trị đó khi chuyển lại sang Base URL và API Path. Sau khi nâng cấp, những giá trị đã lưu chỉ trùng với mặc định cũ trong manifest tích hợp sẵn sẽ tự động bị bỏ qua. Khi endpoint tùy chỉnh kết thúc bằng /chat/completions hoặc /responses, hậu tố đó cũng xác định định dạng yêu cầu để giá trị ghi đè không nhận nhầm dữ liệu.

JSON plugin được nhập hỗ trợ nhà cung cấp dùng định dạng giao tiếp tương thích với OpenAI Chat Completions, OpenAI Responses, Anthropic hoặc Gemini. Nếu nhà cung cấp dùng cấu trúc dữ liệu, sự kiện truyền luồng, lệnh gọi công cụ hoặc định dạng phản hồi độc quyền, nhà cung cấp đó cần một bộ điều hợp ở backend; chỉ thay đổi endpoint không thể chuyển đổi giao thức.

URL của nhà cung cấp có thể dùng HTTP hoặc HTTPS. HTTP gửi thông tin xác thực và lưu lượng nhà cung cấp mà không mã hóa khi truyền, vì vậy chỉ dành HTTP cho cổng tự lưu trữ trên mạng tin cậy và ưu tiên HTTPS bất cứ khi nào có TLS. Base URL không được chứa chuỗi truy vấn hoặc mảnh URL; đường dẫn API tương đối cũng không được chứa phân đoạn duyệt thư mục ở dạng nguyên văn hoặc được mã hóa lặp lại, chuỗi truy vấn hay mảnh URL. Hệ thống từ chối dữ liệu được mã hóa quá mức nếu dữ liệu đó không ổn định trong giới hạn xác thực.

Khi làm mới mô hình, Libre WebUI thay các hậu tố thao tác đã biết, gồm /responses, bằng /models. Hoạt động kích hoạt, làm mới rõ ràng và giá trị ghi đè kết nối đã lưu đều dùng endpoint cùng khóa API của người dùng hiện tại. Việc lưu hoặc xóa khóa API của người dùng đó và đặt lại giá trị ghi đè kết nối cũng làm mới danh sách; các tham số tạo sinh không liên quan thì không. ID được phát hiện được lưu riêng theo từng người dùng và không bao giờ ghi đè JSON plugin dùng chung. Nếu nhà cung cấp không hỗ trợ tuyến được suy ra, hãy cấu hình thủ công ID mô hình trong model_map của plugin.

Các yêu cầu nhà cung cấp được chủ ý thiết kế không đi theo chuyển hướng HTTP, gồm khám phá mô hình, Chat, Work, tạo hình ảnh, embedding và chuyển văn bản thành giọng nói. Hãy cấu hình URL đích cuối thay vì URL chuyển hướng. Cơ chế từ chối an toàn này ngăn tiêu đề ủy quyền chuyển sang một đích chưa được xác thực.

Nếu Work báo tuyến nhà cung cấp đã thay đổi trong khi đang chạy, hãy hoàn tất việc cập nhật cài đặt nhà cung cấp rồi bắt đầu lượt chạy mới. Work chủ ý dừng trước yêu cầu nhà cung cấp tiếp theo để trạng thái công cụ trước đó không bị phát lại sang một chế độ, endpoint hoặc ranh giới xác thực khóa API khác.

Yêu cầu bắt nguồn từ backend, vì vậy khi backend chạy trong vùng chứa, localhost chỉ vùng chứa Libre WebUI chứ không tự động chỉ máy chủ. Với bản triển khai Compose hoặc Kubernetes, hãy dùng tên DNS dịch vụ của cổng, ví dụ http://ai-gateway:8080/v1. Chỉ dùng http://host.docker.internal:8080/v1 khi môi trường chạy vùng chứa cung cấp bí danh máy chủ đó. Lưu lượng HTTP vẫn là văn bản thuần ngay cả khi tên được phân giải trong mạng riêng.

Tính khả dụng của mô hình hình ảnh, giá trị ghi đè endpoint và khóa API cũng được xác định theo người dùng hiện tại. Nếu yêu cầu hình ảnh có vẻ dùng cài đặt nhà cung cấp của tài khoản khác, hãy xác minh yêu cầu đã được xác thực dưới đúng người dùng mong đợi.

Các quy tắc bảo mật và quyền sở hữu sau cũng được áp dụng:

  • Đăng nhập với tư cách quản trị viên để thay đổi tuyến nhà cung cấp. Định nghĩa plugin và các trường kết nối là cấu hình được quản lý ở cấp phiên bản triển khai; người dùng thông thường vẫn có thể lưu cài đặt tạo sinh, thông tin xác thực và trạng thái kích hoạt của riêng mình.
  • Khi dùng giá trị ghi đè endpoint hoặc api_url kiểu cũ, hãy nhập URL endpoint API đầy đủ, gồm cả đường dẫn thao tác (ví dụ https://provider.example/v1/chat/completions). Chỉ nhập gốc API vào base_url, kết hợp với api_mode và api_path tùy chọn.
  • Hệ thống chấp nhận URL endpoint HTTP và HTTPS tuyệt đối. Chỉ dùng HTTP cho cổng tự lưu trữ trên mạng tin cậy vì nếu không, khóa API, câu lệnh và phản hồi sẽ được gửi mà không mã hóa khi truyền.
  • Giá trị ghi đè để trống sẽ dùng endpoint tích hợp trong định nghĩa plugin. Giá trị ghi đè sai định dạng hoặc không an toàn được khai báo rõ ràng sẽ bị từ chối; Libre WebUI không âm thầm gửi yêu cầu đó đến endpoint nhà cung cấp tích hợp sẵn.
  • Khóa trong môi trường triển khai chỉ được dùng khi định nghĩa tích hợp sẵn không bị che khuất vẫn giữ nguyên endpoint gốc đáng tin cậy, các trường xác thực, endpoint và bộ chọn khả năng, cùng giá trị mặc định của biến định tuyến. Định nghĩa được nhập, định nghĩa có thể ghi dùng lại ID tích hợp sẵn và tuyến tùy chỉnh do quản trị viên lưu đều yêu cầu thông tin xác thực do chính tài khoản đó lưu. Libre WebUI chủ ý báo nhà cung cấp không khả dụng và bỏ qua khám phá nếu chỉ có khóa môi trường.
  • Định nghĩa tùy chỉnh có từ trước khi nâng cấp bị cách ly vì các bản phát hành cũ không ghi lại nguồn gốc quản trị viên. Hãy nhập lại JSON với tư cách quản trị viên, rồi yêu cầu từng người dùng kích hoạt lại. Việc sửa trực tiếp JSON plugin đã được phê duyệt sẽ khiến plugin bị cách ly lần nữa; hãy dùng quy trình cài đặt hoặc cập nhật dành cho quản trị viên để ghi lại đường dẫn nguồn và hàm băm định nghĩa.
  • Thông tin xác thực đã lưu được liên kết với tuyến, hợp đồng xác thực, định nghĩa và nguồn đang có hiệu lực tại thời điểm nhập. Sau khi thay đổi endpoint hoặc định nghĩa, hãy lưu lại thông tin xác thực của tài khoản đó. Thông tin xác thực cũ chưa được liên kết chỉ tự động di chuyển trên một tuyến tích hợp sẵn khớp chính xác với điểm neo tin cậy.
  • Plugin được nhập có thể dùng api_url làm bí danh kiểu cũ cho URL thao tác đầy đủ. endpoint được ưu tiên khi cả hai trường đều có giá trị. Nếu khám phá mô hình nằm ở nơi khác, hãy đặt URL danh sách mô hình đầy đủ trong models_endpoint; URL này được xác thực và hệ thống không đi theo chuyển hướng.
  • Kích hoạt plugin sau khi lưu endpoint và thông tin xác thực. Hoạt động kích hoạt suy ra URL /models từ endpoint đầy đủ đã lưu và dùng thông tin xác thực của người kích hoạt để khám phá, trừ khi models_endpoint đã được đặt. Việc lưu hoặc đặt lại bất kỳ trường kết nối nào trong số này cũng làm mới quá trình khám phá. Yêu cầu sẽ chờ khám phá hoàn tất trước khi giao diện tải lại danh sách plugin. Việc kích hoạt áp dụng riêng cho từng tài khoản, vì vậy người dùng khác phải tự kích hoạt cùng plugin dùng chung.
  • Trong Settings → Plugins, hãy chọn nhà cung cấp rồi chọn Refresh models để kiểm tra rõ ràng danh mục. Bảng mô hình chỉ cho phép đọc và hiển thị các ID được cấu hình hoặc phát hiện cho tài khoản hiện tại. Lỗi khám phá tạm thời sẽ giữ lại danh mục đã phát hiện trước đó hoặc model_map dự phòng của plugin nếu chưa có kết quả cũ; vì vậy việc kiểm tra hoàn tất tự nó không chứng minh endpoint từ xa đang hoạt động tốt.
  • Khám phá tự động yêu cầu mảng data tương thích OpenAI chứa các ID mô hình. Danh mục thành công được lưu riêng theo từng người dùng mà không thay đổi JSON plugin dùng chung. Hoạt động kích hoạt thông thường giữ lại danh mục trước đó của người dùng khi khám phá không khả dụng. Việc thay đổi hoặc đặt lại trường kết nối sẽ xóa danh mục lỗi thời trước, vì vậy lần làm mới thất bại sẽ dùng model_map hiện có của plugin; hãy cấu hình các ID mô hình dự phòng này trong JSON plugin khi cần.
  • Tính khả dụng của mô hình hình ảnh, giá trị ghi đè endpoint và khóa API cũng được xác định theo người dùng hiện tại. Nếu yêu cầu hình ảnh có vẻ dùng cài đặt nhà cung cấp của tài khoản khác, hãy xác minh yêu cầu đã được xác thực dưới đúng người dùng mong đợi.
  • Nếu một tài khoản không phải quản trị viên từng lưu giá trị định tuyến trước khi nâng cấp, hãy dùng Reset cho plugin đó. Giá trị cũ đang bị bỏ qua sẽ bị xóa để không thể hoạt động sau lần thay đổi vai trò trong tương lai. Việc lưu hoặc đặt lại tuyến cũng xóa các mô hình đã phát hiện của tài khoản đó để danh mục cũ không đi theo tuyến trước.
  • Yêu cầu bắt nguồn từ backend. Khi Libre WebUI chạy trong vùng chứa, localhost chỉ vùng chứa đó chứ không tự động chỉ máy chủ.
  • Yêu cầu nhà cung cấp không đi theo chuyển hướng. Hãy cấu hình trực tiếp URL thao tác cuối đã được xác thực.

Trò chuyện dùng sai nhà cung cấp hoặc báo nhà cung cấp không khả dụng​

Cùng một ID mô hình có thể tồn tại trong Ollama và nhiều plugin. Phiên Chat hiện tại cùng tùy chọn mô hình mặc định lưu cả nhà cung cấp đã chọn lẫn ID mô hình nguyên bản, nên các mục có tên giống nhau vẫn là những lựa chọn độc lập.

  • Nếu bộ chọn báo nhà cung cấp không khả dụng, hãy kích hoạt lại hoặc cài đặt lại chính plugin đó và xác nhận bản đồ mô hình vẫn chứa ID mô hình đã lưu.
  • Nếu nhà cung cấp hoặc mô hình được chủ ý xóa, hãy chọn rõ ràng một mục thay thế. Libre WebUI sẽ không chuyển hướng lựa chọn chính xác đã lưu sang mô hình cùng tên của nhà cung cấp khác.
  • Phiên và tùy chọn cũ có thể không chứa siêu dữ liệu nhà cung cấp. Các bản ghi này tiếp tục dùng tuyến kiểu cũ chỉ dựa trên tên vì Libre WebUI không thể suy ra nhà cung cấp ban đầu. Chúng xuất hiện dưới dạng "provider not recorded" trong bộ chọn mô hình. Hãy chọn lại mục Ollama hoặc plugin mong muốn để ghim các yêu cầu sau này vào mục đó.
  • Các mục Persona vẫn mang nhãn persona:<id>. Persona mới chọn sẽ ghi Ollama làm nhà cung cấp nền; những phiên Persona lịch sử không có siêu dữ liệu nhà cung cấp vẫn tương thích với tuyến kiểu cũ.

Sự cố Work​

Thiếu Work hoặc môi trường chạy được báo là không khả dụng​

Work yêu cầu một tài khoản đang được xác thực và có quyền truy cập Work — tức quản trị viên, hoặc bất kỳ người dùng đang hoạt động nào sau khi quản trị viên mở Work cho mọi người từ tab User Management trong Settings. Môi trường chạy vùng chứa của Work phải khả dụng đối với backend Libre WebUI:

docker info
docker version

Với backend Docker mặc định, hãy xác nhận Docker đang chạy và tài khoản hệ điều hành chạy Libre WebUI có thể gọi WORK_DOCKER_COMMAND đã cấu hình. Cài Libre WebUI bằng npx không cài Docker. Nếu thiếu môi trường chạy, Libre WebUI vẫn giữ phần còn lại của ứng dụng khả dụng và không chuyển sang thực thi lệnh của mô hình trên máy chủ.

Các tệp Compose trong kho mã kích hoạt Work bằng cách gắn socket Docker của máy chủ. Trên Kubernetes, hãy bật môi trường chạy Pod/PVC gốc bằng giá trị Helm work.enabled=true; không gắn socket môi trường chạy của nút. Khi bản triển khai Compose vẫn báo Runtime unavailable, trang Work sẽ nêu trường hợp nào sau đây đang xảy ra:

Thông báoNguyên nhân và cách khắc phục
The "docker" CLI is not installed…Image Docker tùy chỉnh không có docker-cli. Hãy dùng image chính thức hoặc trỏ WORK_DOCKER_COMMAND đến một CLI.
No Docker daemon is reachable…Socket đã bị gỡ khỏi vùng chứa hoặc daemon trên máy chủ đã dừng. Khôi phục cấu hình gắn trong tệp Compose rồi khởi động Docker.
The Docker socket is mounted but…cannot openNhóm của socket khác với nhóm trong vùng chứa. Đặt DOCKER_GID trong .env (xem bên dưới) rồi tạo lại vùng chứa.
Màn hình/âm thanh Work đóng với WebSocket 1006 và ghi log screen is unreachableBackend chạy trong vùng chứa đang gọi tới loopback của chính nó. Trên Docker Desktop hãy dùng WORK_DOCKER_PUBLISHED_HOST=host.docker.internal có sẵn; trên Docker Engine thuần hãy đặt thêm WORK_PREVIEW_BIND thành gateway cầu nối Docker không công khai, rồi tạo lại Libre WebUI.

Đọc nhóm của socket từ bên trong vùng chứa vì máy chủ macOS báo một giá trị khác với giá trị vùng chứa nhìn thấy:

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

Socket đó cấp quyền kiểm soát tương đương root đối với máy chủ Docker; hãy xem Work: Không gian làm việc cô lập để hiểu ý nghĩa đối với bản triển khai của bạn.

Mô hình không hỗ trợ công cụ​

Work yêu cầu mô hình trò chuyện có khả năng dùng công cụ. Với Ollama, hãy chọn mô hình đã cài đặt có danh sách khả năng chứa tools. Với mô hình do plugin cung cấp:

  • Xác nhận plugin trò chuyện hoặc hoàn tất đang hoạt động.
  • Xác nhận mô hình đã chọn nằm trong danh sách mô hình được cấu hình của plugin đó.
  • Xác nhận quản trị viên hiện tại có khóa API khả dụng.
  • Xác nhận nhà cung cấp hỗ trợ lệnh gọi công cụ cho chính mô hình đó.

Libre WebUI không âm thầm định tuyến lượt chạy Work thất bại sang nhà cung cấp khác.

Yêu cầu Work trả HTTP 429​

Phiên bản triển khai đã đạt giới hạn tiếp nhận tác vụ hoặc môi trường chạy đang hoạt động. Theo mặc định, Libre WebUI cho phép hai tác vụ đang hoạt động có vùng chứa hỗ trợ trên toàn phiên bản và một tác vụ cho mỗi người dùng. Bản xem trước đang chạy cũng chiếm dung lượng môi trường chạy. Hãy chờ thao tác khác hoàn tất, dừng bản xem trước không dùng đến hoặc yêu cầu người vận hành xem lại các cài đặt WORK_MAX_ACTIVE_RUNTIMES_* và WORK_MAX_TASKS_*.

Cài gói hoặc truy cập mạng thất bại​

Tác vụ Work mới dùng mạng cầu nối Docker để dự án được tạo có thể tải gói và khởi động bản xem trước. Hãy kiểm tra DNS của Docker, cấu hình proxy, tính khả dụng của kho đăng ký và đầu ra lệnh trong Activity. Libre WebUI không gắn khóa SSH của máy chủ, thông tin xác thực đám mây, hồ sơ trình duyệt hoặc socket Docker vào vùng chứa tác vụ.

Bản xem trước Work không khởi động​

  • Đảm bảo máy chủ lắng nghe tại 0.0.0.0 trên WORK_PREVIEW_PORT (mặc định là 4173).
  • Để trống lệnh tùy chọn để hệ thống tự phát hiện script dev trong package.json hoặc tệp index.html thuần, kể cả khi có một ứng dụng lồng duy nhất.
  • Nếu Work báo có nhiều ứng dụng hoặc không có điểm vào được hỗ trợ, hãy nhập rõ lệnh phát triển của dự án trong trường lệnh tùy chọn. Lệnh bắt đầu tại /workspace, vì vậy hãy dùng cd <app-directory> && ... cho ứng dụng lồng.
  • Mở rộng chi tiết lỗi được trả về để kiểm tra đầu ra khởi động.
  • Dừng bản xem trước hiện có trước khi bắt đầu lệnh khác cần dùng vùng chứa.

URL bản xem trước dùng cổng loopback được cấp phát động. Do đó, trình duyệt và backend Libre WebUI cần chạy trên cùng một máy. Trình duyệt kết nối đến backend từ xa không thể truy cập bản xem trước loopback của backend đó, và trang HTTPS có thể chặn bản xem trước dùng HTTP thuần vì đây là nội dung hỗn hợp.

Không thể mở hoặc lưu tệp không gian làm việc​

API tệp của Work chấp nhận tệp văn bản UTF-8 có dung lượng tối đa 2 MB. Nếu tệp thay đổi sau khi bạn mở, hãy tải lại trước khi lưu để không ghi đè phiên bản mới hơn. Việc định dạng chỉ áp dụng cho các loại tệp được hỗ trợ có dưới 100.000 ký tự và 4.000 dòng; tính năng tô sáng cú pháp sẽ tạm dừng với tệp lớn để trình chỉnh sửa luôn phản hồi nhanh.

Các chỉnh sửa chưa lưu được giữ dưới dạng bản nháp trong trình duyệt hiện tại. Chúng không thay thế cho việc lưu vào không gian làm việc bền vững.

Tác vụ hoặc bản xem trước đã bị dừng​

Việc dừng lượt chạy, dừng bản xem trước hoặc khởi động lại Libre WebUI sẽ dừng các tiến trình vùng chứa dùng một lần nhưng vẫn giữ volume không gian làm việc có tên của tác vụ. Hãy mở lại tác vụ và khởi động lại bản xem trước. Xóa tác vụ là thao tác khác: sau khi xác nhận, thao tác này xóa vĩnh viễn tác vụ cùng không gian làm việc.

Sự cố đăng nhập và đăng ký​

Người dùng đầu tiên không phải quản trị viên

Chỉ tài khoản đầu tiên được tạo trong cơ sở dữ liệu mới trở thành quản trị viên. Cơ sở dữ liệu hiện có giữ nguyên người dùng và vai trò hiện tại.

Lỗi JWT

Đặt một khóa bí mật ổn định trong môi trường sản xuất:

JWT_SECRET=replace-with-a-long-random-secret

Việc thay đổi JWT_SECRET sẽ vô hiệu hóa các phiên hiện có.

Turnstile chặn đăng ký

Turnstile chỉ được bật khi có đủ cả hai khóa:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

Nếu đăng ký đột ngột thất bại, hãy xác nhận khóa trang web khớp với tên miền và khóa bí mật hợp lệ.

Chuyển hướng OAuth thất bại

Đặt URL gọi lại trong cả bảng điều khiển của nhà cung cấp và tệp .env của backend:

BASE_URL=https://your-domain.example
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

Sự cố trò chuyện với tài liệu​

Libre WebUI chấp nhận tệp PDF, Office (DOCX/PPTX/XLSX), Markdown, HTML, mã nguồn và CSV có dung lượng tối đa 10 MB.

Nếu tìm kiếm hoạt động nhưng truy xuất ngữ nghĩa không hoạt động:

  1. Cài đặt mô hình embedding như nomic-embed-text.
  2. Bật embedding trong Settings.
  3. Tạo lại embedding từ cài đặt tài liệu hoặc API.
ollama pull nomic-embed-text

Tìm kiếm theo từ khóa vẫn hoạt động khi embedding bị tắt.

Sự cố xem trước tạo tác​

Với trò chơi hoặc HTML tương tác, hãy yêu cầu mô hình tạo một tệp HTML hoàn chỉnh, độc lập, có CSS và JavaScript nội tuyến.

Nếu tạo tác cần nhập từ bàn phím:

  • Trước tiên, nhấp vào bên trong bản xem trước.
  • Dùng nút Open để chạy tạo tác trong tab trình duyệt riêng.
  • Tránh phụ thuộc vào các tệp cục bộ không được đưa vào phản hồi.

Libre WebUI có thể đóng gói các khối mã index.html + CSS + JavaScript thường gặp, nhưng HTML độc lập vẫn là đầu ra đáng tin cậy nhất.

Sự cố Docker​

Vùng chứa không thể kết nối tới Ollama

Hãy dùng tệp Compose dành cho Ollama bên ngoài khi Ollama không nằm trong cùng ngăn xếp Compose:

docker compose -f docker-compose.external-ollama.yml up -d

Dữ liệu không được lưu bền vững

Gắn volume dữ liệu bền vững và đặt DATA_DIR nếu cần. Khóa mã hóa được lưu trong bộ nhớ bền vững khi dùng DATA_DIR hoặc chế độ Docker.

Đặt lại dữ liệu cục bộ​

Trước tiên hãy dừng ứng dụng. Sau đó sao lưu và xóa thư mục dữ liệu đang dùng. Theo mặc định, dữ liệu phát triển nằm trong backend/data.

cp -R backend/data backend/data.backup
rm -rf backend/data

Khởi động lại backend và tạo tài khoản mới.

Vẫn chưa giải quyết được​

Hãy mở một issue và cung cấp:

  • Phiên bản cùng commit của Libre WebUI
  • Phương thức cài đặt
  • Hệ điều hành
  • Phiên bản Node.js
  • Phiên bản Ollama
  • Phiên bản Docker và kết quả docker info đối với sự cố Work
  • Nhật ký backend tại thời điểm xảy ra lỗi
  • Lỗi trong bảng điều khiển trình duyệt
  • Chính xác mô hình hoặc nhà cung cấp đang dùng
  • Đầu ra Work Activity khi tác vụ hoặc bản xem trước thất bại