การแก้ปัญหา

เริ่มจากชั้นที่เกิดปัญหา ได้แก่ เบราว์เซอร์ ส่วนหน้า แบ็กเอนด์ Ollama ปลั๊กอินผู้ให้บริการ หรือเครือข่ายของระบบที่ติดตั้งใช้งาน

ตรวจสอบอย่างรวดเร็ว

# 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

ระหว่างการพัฒนา ส่วนหน้ามักทำงานที่ http://localhost:5173 และแบ็กเอนด์ทำงานที่ http://localhost:3001 ส่วนขั้นตอนแบบแพ็กเกจด้วย npx libre-webui จะให้บริการแอปที่ http://localhost:8080

Libre WebUI เริ่มทำงานไม่ได้

ตรวจสอบ Node และ dependency

node --version
npm install
npm run dev

ต้องใช้ Node.js 22.22 หรือใหม่กว่า

พอร์ตถูกใช้งานอยู่แล้ว

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

หยุดกระบวนการเดิมหรือกำหนดพอร์ตอื่น

แบ็กเอนด์เขียนข้อมูลไม่ได้

เมื่อกำหนด DATA_DIR แบ็กเอนด์จะเก็บข้อมูลไว้ภายใต้ตำแหน่งนั้น มิฉะนั้นจะเก็บไว้ที่ backend/data การเริ่มทำงานจากซอร์สจะตีความ DATA_DIR แบบสัมพัทธ์จากไดเรกทอรีแบ็กเอนด์ ไม่ใช่ไดเรกทอรีปัจจุบันของเชลล์ ดังนั้น DATA_DIR=./data จะเลือก backend/data ส่วน DATA_DIR=./backend/data ซึ่งรองรับมาแต่เดิมจะเลือก backend/backend/data ตรวจสอบว่าไดเรกทอรีที่เลือกสามารถเขียนได้ หากไม่ได้ตั้ง DATA_DIR Libre จะคงใช้ไดเรกทอรีเดิมเมื่อมีที่เก็บข้อมูลอยู่เพียงแห่งเดียว หากทั้งสองตำแหน่งมีข้อมูล ให้หยุด Libre สำรองข้อมูลทั้งสองแห่ง แล้วเลือกหรือย้ายข้อมูลอย่างตั้งใจ Libre จะไม่รวมหรือคัดลอกฐานข้อมูลที่แตกต่างกันเอง

ปลายทางตรวจสอบสถานะจะแยกกระบวนการที่กำลังทำงานออกจากแอปพลิเคชันที่พร้อมใช้งานโดยตั้งใจ:

/health และ /health/live จะคืนค่า 200 ตราบใดที่กระบวนการแบ็กเอนด์ยังให้บริการ HTTP ได้ ผู้ให้บริการโมเดลที่ไม่บังคับไม่มีผลต่อสถานะการทำงาน
/health/ready จะคืนค่า 503 เมื่อฐานข้อมูล สคีมา พื้นที่จัดเก็บ หรือการพึ่งพาแพลตฟอร์ม ที่ลงทะเบียนและจำเป็นไม่พร้อมใช้งาน โดยไม่รอผู้ให้บริการโมเดลที่ไม่บังคับ คำตอบสาธารณะ จะไม่เปิดเผยข้อความข้อผิดพลาดและรายละเอียดภายใน
/health/deep ตรวจสอบความสมบูรณ์และคีย์นอกของ SQLite ในเวิร์กเกอร์ที่จำกัดขอบเขต พร้อมรวมผลตรวจผู้ให้บริการระดับเซิร์ฟเวอร์ที่ไม่บังคับ เช่น Ollama หากผู้ให้บริการเสริม ใช้งานไม่ได้ ระบบจะแสดงคำเตือนโดยไม่ทำให้การพึ่งพาที่จำเป็นเปลี่ยนเป็นไม่พร้อมใช้งาน ปลายทางนี้ต้องใช้โทเค็น bearer ของผู้ดูแลระบบที่ยังใช้ได้ และไม่เหมาะกับการตรวจสอบถี่ ๆ โดยระบบประสานงาน

curl -H "Authorization: Bearer $LIBRE_ADMIN_TOKEN" \
  http://localhost:3001/health/deep

เบราว์เซอร์เข้าถึงแบ็กเอนด์ไม่ได้

สำหรับการพัฒนาภายในเครื่อง ส่วนหน้าจะใช้ VITE_API_BASE_URL เมื่อตั้งค่าไว้ มิฉะนั้นจะใช้แบ็กเอนด์สำหรับการพัฒนาเป็นค่าทดแทน

ตัวอย่าง .env ของส่วนหน้า:

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

VITE_WS_BASE_URL ไม่บังคับ แต่เมื่อตั้งค่าแล้วจะเป็นฐานร่วมสำหรับซ็อกเก็ตของ Chat และ เทอร์มินัล Work ใช้ URL แบบเต็มที่เป็น ws: หรือ wss: โดยรองรับคำนำหน้าเส้นทาง เช่น wss://example.com/libre อย่าใส่ข้อมูลรับรอง พารามิเตอร์คำค้น หรือส่วนย่อย หลังเปลี่ยน ตัวแปร Vite ให้เริ่มส่วนหน้าใหม่หรือสร้างส่วนหน้าใหม่

ตัวอย่าง .env ของแบ็กเอนด์:

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

หากเข้าถึงจากโทรศัพท์ LAN หรือ Tailscale อย่าให้เบราว์เซอร์บนโทรศัพท์ชี้ไปที่ localhost ให้ใช้ IP ของแล็ปท็อปบน LAN หรือ Tailscale และเรียกใช้เซิร์ฟเวอร์พัฒนาโดยผูกกับโฮสต์:

npm run dev:host

คำสั่งนี้จะให้บริการส่วนหน้าที่พอร์ต 8080 และพร็อกซีทราฟฟิก API และ WebSocket ไปยังแบ็กเอนด์ในเครื่องที่พอร์ต 3001 อุปกรณ์อีกเครื่องต้องเข้าถึงได้เฉพาะพอร์ต 8080 เท่านั้น หากตั้งค่า VITE_API_BASE_URL หรือ VITE_WS_BASE_URL ไว้ใน frontend/.env ให้ตรวจสอบว่า URL เหล่านั้นเข้าถึงได้จากอุปกรณ์อีกเครื่อง หรือลบออกเพื่อใช้พร็อกซีของเซิร์ฟเวอร์พัฒนาแทน

การสนทนาไม่สตรีมหลังผ่านพร็อกซีย้อนกลับ

อาการทั่วไปคือส่งข้อความได้แต่ไม่มีคำตอบแสดงขึ้นมา และคอนโซลของเบราว์เซอร์รายงานว่า เชื่อมต่อ WebSocket ไม่สำเร็จ ตรวจสอบว่าพร็อกซีอนุญาตให้อัปเกรด WebSocket และไม่ปิด การเชื่อมต่อที่ทำงานเป็นเวลานาน

เมื่อตั้งค่าค่าใดค่าหนึ่ง การอัปเกรดจากเบราว์เซอร์ที่ส่งส่วนหัว Origin จะถูกตรวจเทียบกับ CORS_ORIGIN และ BASE_URL สำหรับการติดตั้งใช้งานระยะไกล ให้ตั้งค่าอย่างน้อยหนึ่งรายการ หากไม่ตั้งทั้งสองรายการ ตัวกรอง Origin จะยังผ่อนปรนสำหรับการพัฒนาภายในเครื่อง Electron และไคลเอนต์อื่นที่ไม่ใช่เบราว์เซอร์อาจไม่ส่ง Origin แต่ยังต้องแลกส่วนหัว Authorization เป็นบัตรผ่านอายุสั้นที่ใช้ได้ครั้งเดียวก่อน วางแบ็กเอนด์ไว้หลัง TLS และใช้การควบคุมการเข้าถึง เครือข่ายหรือพร็อกซีย้อนกลับแบบเดียวกับ HTTP API

สำหรับชื่อโฮสต์สาธารณะ ให้อนุญาตต้นทางของเบราว์เซอร์นั้นในบริการ Libre WebUI:

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

ตัวอย่าง nginx และ Caddy ด้านล่างถือว่าพร็อกซีทำงานบนโฮสต์ Docker ซึ่งการตั้งค่า Compose ของที่เก็บจะเผยแพร่ Libre WebUI ที่พอร์ต 8080 หากพร็อกซีเข้าร่วมเครือข่าย Compose แทน ให้ใช้ libre-webui:3001 เป็นที่อยู่ต้นทาง

nginx

nginx ต้องส่งต่อส่วนหัวการอัปเกรดอย่างชัดเจน ระยะหมดเวลาอ่านที่ยาวขึ้นจะช่วยเปิด การเชื่อมต่อสนทนาที่ไม่มีกิจกรรมไว้ระหว่างโมเดลกำลังทำงาน

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;
}

โหลด nginx ใหม่หลังตรวจสอบการกำหนดค่าด้วย nginx -t

Caddy

reverse_proxy ของ Caddy รองรับ WebSocket มาให้แล้ว จึงไม่ต้องใช้ส่วนหัวการอัปเกรด:

chat.example.com {
    reverse_proxy 127.0.0.1:8080
}

Traefik

Traefik รองรับการอัปเกรด WebSocket โดยค่าเริ่มต้นเช่นกัน เมื่อผู้ให้บริการ Docker ของ Traefik ใช้เครือข่ายร่วมกับ Libre WebUI จะต้องใช้เพียงป้ายกำกับเราเตอร์และบริการตามปกติ ตัวอย่างเช่น:

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'

หากสตรีมเชื่อมต่อได้แต่หลุดในภายหลัง ให้ตรวจสอบระยะหมดเวลาเมื่อไม่มีกิจกรรมของพร็อกซี หรือตัวกระจายโหลดที่อยู่หน้า Traefik หาก Traefik เป็นผู้บังคับใช้ขีดจำกัดเอง ให้ปรับการตั้งค่า transport.respondingTimeouts ของจุดเข้าใช้งาน

ตรวจไม่พบ Ollama

ยืนยันว่า Ollama กำลังทำงาน

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

กำหนด URL Ollama เอง

.env ของแบ็กเอนด์:

OLLAMA_BASE_URL=http://localhost:11434

หาก Libre WebUI ทำงานใน Docker และ Ollama ทำงานบนโฮสต์ ให้ใช้ไฟล์ Compose สำหรับ Ollama ภายนอก หรือชี้ OLLAMA_BASE_URL ไปยังที่อยู่โฮสต์ที่คอนเทนเนอร์เข้าถึงได้

ปัญหาการดาวน์โหลดโมเดล

ดาวน์โหลดจากเทอร์มินัลก่อน

ollama pull gemma4:12b

หากดาวน์โหลดจากเทอร์มินัลไม่สำเร็จ แสดงว่าปัญหาอยู่นอก Libre WebUI

โมเดลคลาวด์

ใช้ตัวกรองคลาวด์ใน Model Manager สำหรับโมเดล Ollama Cloud Libre WebUI จะปรับส่วนต่อท้ายคลาวด์ที่จำเป็นให้เป็นรูปแบบมาตรฐานผ่านขั้นตอนนี้ ผู้ใช้จึงไม่ต้องเติม :cloud เองสำหรับรายการคลาวด์ที่รองรับ

ผู้ใช้ดาวน์โหลดโมเดลไม่ได้

ผู้ดูแลระบบสามารถปิดไม่ให้ผู้ใช้ทั่วไปดาวน์โหลดโมเดลได้ หากผู้ใช้ที่ไม่ใช่ผู้ดูแลระบบดูโมเดลได้แต่ติดตั้งไม่ได้ ให้ตรวจสอบการตั้งค่าของผู้ดูแลระบบ

แชตช้าหรือล้มเหลว

ใช้โมเดลที่เล็กลง
ตรวจสอบโมเดลที่โหลดอยู่ด้วย ollama ps
ลดความยาวบริบท
ลดจำนวนโทเค็นสูงสุดสำหรับคำตอบที่ยาวมาก
ยืนยันว่าโมเดลมีขนาดพอดีกับ RAM หรือ VRAM
สำหรับปลั๊กอินผู้ให้บริการ ให้ตรวจสอบ API key และโควตาของผู้ให้บริการ

การสร้างรูปภาพ OpenAI ไม่พร้อมใช้งาน

เปิดใช้ผู้ให้บริการ OpenAI ที่มีมาให้ บันทึก API key สำหรับผู้ใช้ปัจจุบัน หรือกำหนด OPENAI_API_KEY ในสภาพแวดล้อมเป็นค่าทดแทนสำหรับผู้ให้บริการที่มีมาให้และเชื่อถือได้
เปิดการตั้งค่า Image Generation เปิดใช้การสร้างรูปภาพ แล้วเลือกโมเดล GPT Image ที่แสดงไว้
ควรใช้ gpt-image-2 ID ของ GPT Image รุ่นเก่ายังคงมีไว้เพื่อให้เข้ากันได้กับการตั้งค่าเดิมเท่านั้น และผู้ให้บริการต้นทางเลิกแนะนำให้ใช้แล้ว
เว้นค่าที่กำหนดทับ image_endpoint ของ OpenAI ไว้ให้ว่าง เว้นแต่คุณจะดูแลปลายทางรูปภาพ ที่เข้ากันได้ ปลายทาง Chat /responses หรือ /chat/completions ไม่สามารถประมวลผลคำขอ Image API ได้
หาก OpenAI ปฏิเสธคำขอ GPT Image แม้คีย์และโควตาถูกต้อง ให้ยืนยันว่าองค์กร API มีสิทธิ์ใช้โมเดล GPT Image

ระบบประเมินความพร้อมของรูปภาพด้วยข้อมูลรับรองที่ผู้ใช้ปัจจุบันบันทึกไว้ หรือค่าทดแทนจาก สภาพแวดล้อมของผู้ให้บริการที่มีมาให้และเชื่อถือได้ คีย์ที่บันทึกไว้เฉพาะในการตั้งค่าของผู้ใช้อื่น จะไม่ทำให้โมเดลรูปภาพปรากฏ

ปัญหาปลายทางของผู้ให้บริการ

หากผู้ให้บริการที่เข้ากันได้กับ OpenAI ได้รับคำขอผ่านเส้นทางที่ผิด ให้ตรวจสอบการตั้งค่าภายใต้ Settings → Plugins:

เลือก Chat Completions สำหรับข้อมูลคำขอแบบ /chat/completions หรือ Responses สำหรับข้อมูลคำขอแบบ /responses
ป้อนราก API เช่น https://provider.example/v1 เป็น Base URL
เว้น API Path ว่างไว้เพื่อใช้ค่าเริ่มต้นของโหมด หรือป้อนเส้นทางจากผู้ให้บริการที่ขึ้นต้นด้วยเครื่องหมายทับ
ปลายทางแบบเต็มรุ่นเก่าที่กำหนดเองจริงจะมีลำดับความสำคัญสูงสุดโดยตั้งใจ จึงต้องล้างค่าเมื่อ เปลี่ยนกลับไปใช้ Base URL และ API Path ค่าที่จัดเก็บไว้ซึ่งเพียงตรงกับค่าเริ่มต้นเก่าของไฟล์กำหนด ที่มีมาให้จะถูกละเว้นโดยอัตโนมัติหลังอัปเกรด เมื่อปลายทางกำหนดเองลงท้ายด้วย /chat/completions หรือ /responses ส่วนต่อท้ายนั้นจะกำหนดรูปแบบคำขอด้วย เพื่อไม่ให้ค่าที่กำหนดทับ ได้รับข้อมูลคำขอผิดรูปแบบ

JSON ของปลั๊กอินที่นำเข้ารองรับผู้ให้บริการซึ่งใช้รูปแบบการสื่อสารที่เข้ากันได้กับ OpenAI Chat Completions, OpenAI Responses, Anthropic หรือ Gemini หากผู้ให้บริการใช้รูปแบบข้อมูลคำขอ เหตุการณ์สตรีม การเรียกใช้เครื่องมือ หรือคำตอบเฉพาะของตน จะต้องมีอะแดปเตอร์ฝั่งแบ็กเอนด์ การเปลี่ยนเพียงปลายทางไม่สามารถแปลงรูปแบบนั้นได้

URL ของผู้ให้บริการใช้ HTTP หรือ HTTPS ได้ HTTP จะส่งข้อมูลรับรองและข้อมูลที่รับส่งกับผู้ให้บริการ โดยไม่มีการเข้ารหัสระหว่างส่ง จึงควรสงวนไว้สำหรับเกตเวย์ที่โฮสต์เองบนเครือข่ายที่เชื่อถือได้ และเลือก HTTPS เมื่อมี TLS ห้าม Base URL มีสตริงคำค้นหรือส่วนย่อย และห้ามเส้นทาง API แบบสัมพัทธ์ มีส่วนการไล่ระดับไดเรกทอรีแบบตรงหรือเข้ารหัสซ้ำ สตริงคำค้น หรือส่วนย่อย ระบบจะปฏิเสธการเข้ารหัส มากเกินไปหากยังไม่คงที่ภายในขอบเขตการตรวจสอบ

การรีเฟรชโมเดลจะแทนที่ส่วนต่อท้ายการดำเนินการที่รู้จัก รวมถึง /responses ด้วย /models การเปิดใช้ การรีเฟรชโดยตรง และค่าการเชื่อมต่อที่บันทึกไว้ใช้ปลายทางและ API key ของผู้ใช้ปัจจุบัน การบันทึกหรือลบ API key ของผู้ใช้นั้น รวมถึงการรีเซ็ตค่าการเชื่อมต่อ จะรีเฟรชรายการด้วย แต่พารามิเตอร์การสร้างผลลัพธ์ที่ไม่เกี่ยวข้องจะไม่ทำเช่นนั้น ID ที่ค้นพบจะเก็บแยกตามผู้ใช้และไม่เขียนทับ JSON ของปลั๊กอินที่ใช้ร่วมกัน หากผู้ให้บริการไม่รองรับเส้นทางที่ระบบกำหนด ให้ระบุ ID โมเดลเองใน model_map ของปลั๊กอิน

คำขอถึงผู้ให้บริการจะไม่ติดตามการเปลี่ยนเส้นทาง HTTP โดยตั้งใจ ไม่ว่าจะเป็นการค้นหาโมเดล Chat Work การสร้างรูปภาพ การฝังข้อมูล หรือการแปลงข้อความเป็นเสียง กำหนด URL ปลายทางสุดท้าย แทน URL ที่เปลี่ยนเส้นทาง พฤติกรรมที่ปฏิเสธไว้ก่อนนี้ช่วยป้องกันไม่ให้ส่วนหัวการอนุญาตถูกส่งต่อ ไปยังปลายทางที่ยังไม่ได้ตรวจสอบ

หาก Work รายงานว่าเส้นทางของผู้ให้บริการเปลี่ยนระหว่างการทำงาน ให้เริ่มงานใหม่หลังอัปเดต การตั้งค่าผู้ให้บริการเสร็จ Work จะหยุดก่อนส่งคำขอถัดไปโดยตั้งใจ เพื่อไม่ให้สถานะเครื่องมือเดิม ถูกเล่นซ้ำไปยังโหมด ปลายทาง หรือขอบเขตการยืนยันตัวตนด้วย API key ที่ต่างออกไป

คำขอมาจากแบ็กเอนด์ ดังนั้นเมื่อแบ็กเอนด์ทำงานในคอนเทนเนอร์ localhost จะหมายถึงคอนเทนเนอร์ Libre WebUI ไม่ใช่เครื่องโฮสต์โดยอัตโนมัติ สำหรับการติดตั้งใช้งานด้วย Compose หรือ Kubernetes ให้ใช้ชื่อ DNS ของบริการเกตเวย์ เช่น http://ai-gateway:8080/v1 ใช้ http://host.docker.internal:8080/v1 เฉพาะเมื่อระบบคอนเทนเนอร์เปิดเผยชื่อแทนของโฮสต์นั้น ข้อมูล HTTP ยังคงเป็นข้อความล้วนแม้ชื่อจะถูกแปลงเป็นที่อยู่ส่วนตัว

ระบบจะเลือกความพร้อมของโมเดลรูปภาพ ค่าปลายทางที่กำหนดทับ และ API key ตามผู้ใช้ปัจจุบันเช่นกัน หากคำขอรูปภาพดูเหมือนใช้การตั้งค่าผู้ให้บริการของบัญชีอื่น ให้ตรวจสอบว่าคำขอยืนยันตัวตนเป็นผู้ใช้ที่คาดไว้

กฎด้านความปลอดภัยและความเป็นเจ้าของต่อไปนี้มีผลด้วย:

ลงชื่อเข้าใช้ในฐานะผู้ดูแลระบบเพื่อเปลี่ยนเส้นทางผู้ให้บริการ ข้อกำหนดปลั๊กอินและฟิลด์การเชื่อมต่อ เป็นการตั้งค่าที่จัดการระดับระบบ ผู้ใช้ทั่วไปยังบันทึกการตั้งค่าการสร้างผลลัพธ์ ข้อมูลรับรอง และสถานะ การเปิดใช้ของตนเองได้
เมื่อใช้ค่า endpoint หรือ api_url แบบเดิมที่กำหนดทับ ให้ป้อน URL ปลายทาง API แบบเต็ม รวมถึงเส้นทางการดำเนินการ เช่น https://provider.example/v1/chat/completions ป้อนราก API เฉพาะใน base_url โดยใช้ร่วมกับ api_mode และ api_path ซึ่งไม่บังคับ
ยอมรับ URL ปลายทาง HTTP และ HTTPS แบบเต็ม ใช้ HTTP เฉพาะกับเกตเวย์ที่โฮสต์เองบนเครือข่าย ที่เชื่อถือได้ เพราะมิฉะนั้น API key พรอมต์ และคำตอบจะถูกส่งโดยไม่มีการเข้ารหัสระหว่างส่ง
ค่าที่กำหนดทับซึ่งเว้นว่างจะใช้ปลายทางที่มีมาในข้อกำหนดปลั๊กอิน ระบบจะปฏิเสธค่าที่ระบุชัดแต่ มีรูปแบบผิดหรือไม่ปลอดภัย Libre WebUI จะไม่ส่งคำขอนั้นไปยังปลายทางของผู้ให้บริการที่มีมาให้ โดยไม่แจ้ง
คีย์จากสภาพแวดล้อมของระบบที่ติดตั้งใช้งานจะใช้ได้เฉพาะเมื่อข้อกำหนดที่มีมาให้ซึ่งไม่ถูกบดบัง ยังคงปลายทางรากที่เชื่อถือได้ ฟิลด์ยืนยันตัวตน ปลายทางและตัวเลือกความสามารถ รวมถึงค่าเริ่มต้น ของตัวแปรกำหนดเส้นทาง ข้อกำหนดที่นำเข้า ข้อกำหนดที่เขียนได้ซึ่งนำ ID ที่มีมาให้กลับมาใช้ และเส้นทางกำหนดเองที่ผู้ดูแลระบบบันทึก ต้องใช้ข้อมูลรับรองที่บัญชีเดียวกันบันทึกไว้ หากมีเพียงคีย์ จากสภาพแวดล้อม Libre WebUI จะรายงานว่าผู้ให้บริการไม่พร้อมใช้งานและข้ามการค้นหาโดยตั้งใจ
ข้อกำหนดกำหนดเองก่อนอัปเกรดจะถูกกักไว้ เพราะรุ่นเก่าไม่ได้บันทึกที่มาจากผู้ดูแลระบบ ให้นำเข้า JSON ใหม่ในฐานะผู้ดูแลระบบ แล้วให้ผู้ใช้แต่ละรายเปิดใช้อีกครั้ง การแก้ JSON ของปลั๊กอินที่อนุมัติแล้ว โดยตรงจะทำให้ถูกกักอีกครั้ง ให้ใช้ขั้นตอนติดตั้งหรืออัปเดตของผู้ดูแลระบบเพื่อบันทึกเส้นทางต้นทางและ แฮชของข้อกำหนด
ข้อมูลรับรองที่บันทึกไว้จะผูกกับเส้นทาง ข้อกำหนดการยืนยันตัวตน ข้อกำหนดปลั๊กอิน และต้นทางที่มีผล ตอนป้อนข้อมูล หลังเปลี่ยนปลายทางหรือข้อกำหนด ให้บันทึกข้อมูลรับรองของบัญชีนั้นอีกครั้ง ข้อมูลรับรอง เก่าที่ยังไม่ผูกจะย้ายโดยอัตโนมัติเฉพาะบนเส้นทางที่มีมาให้ซึ่งยึดตรงกันทุกประการ
ปลั๊กอินที่นำเข้าอาจใช้ api_url เป็นชื่อแทนเดิมสำหรับ URL การดำเนินการแบบเต็ม หากตั้งทั้งสองฟิลด์ endpoint จะมีลำดับก่อน หากการค้นหาโมเดลอยู่ที่อื่น ให้ตั้ง URL รายการโมเดลแบบเต็มใน models_endpoint ระบบจะตรวจสอบ URL นี้และไม่ติดตามการเปลี่ยนเส้นทาง
เปิดใช้ปลั๊กอินหลังบันทึกปลายทางและข้อมูลรับรอง การเปิดใช้จะสร้าง URL /models จากปลายทาง แบบเต็มที่บันทึกไว้ และใช้ข้อมูลรับรองของผู้ใช้ที่เปิดใช้เพื่อค้นหาโมเดล เว้นแต่จะตั้ง models_endpoint การบันทึกหรือรีเซ็ตฟิลด์การเชื่อมต่อเหล่านี้จะรีเฟรชการค้นหาด้วย คำขอจะรอ ให้การค้นหาเสร็จก่อนส่วนติดต่อผู้ใช้โหลดรายการปลั๊กอินใหม่ การเปิดใช้เป็นค่าเฉพาะบัญชี ผู้ใช้อื่น จึงต้องเปิดใช้ปลั๊กอินที่ใช้ร่วมกันรายการเดียวกันแยกต่างหาก
ใน Settings → Plugins เลือกผู้ให้บริการแล้วเลือก Refresh models เพื่อตรวจสอบรายการ โดยตรง ตารางโมเดลเป็นแบบอ่านอย่างเดียวและแสดง ID ที่กำหนดหรือค้นพบสำหรับบัญชีปัจจุบัน หากการค้นหาล้มเหลวชั่วคราว ระบบจะเก็บรายการที่ค้นพบก่อนหน้าไว้ หรือใช้ model_map สำรองของ ปลั๊กอินเมื่อไม่มีผลก่อนหน้า ดังนั้นการตรวจสอบที่เสร็จสิ้นเพียงอย่างเดียวไม่ได้พิสูจน์ว่าปลายทาง ระยะไกลทำงานเป็นปกติ
การค้นหาอัตโนมัติต้องใช้อาร์เรย์ data ของ ID โมเดลที่เข้ากันได้กับ OpenAI รายการที่ค้นหา สำเร็จจะเก็บแยกตามผู้ใช้โดยไม่เปลี่ยน JSON ของปลั๊กอินที่ใช้ร่วมกัน การเปิดใช้ตามปกติจะเก็บ รายการเดิมของผู้ใช้ไว้เมื่อค้นหาไม่ได้ การเปลี่ยนหรือรีเซ็ตฟิลด์การเชื่อมต่อจะล้างรายการล้าสมัย ก่อน ดังนั้นหากรีเฟรชล้มเหลวจะใช้ model_map ที่มีอยู่ของปลั๊กอิน กำหนด ID โมเดลสำรองเหล่านั้น ใน JSON ของปลั๊กอินเมื่อจำเป็น
ระบบจะเลือกความพร้อมของโมเดลรูปภาพ ค่าปลายทางที่กำหนดทับ และ API key ตามผู้ใช้ปัจจุบันด้วย หากคำขอรูปภาพดูเหมือนใช้การตั้งค่าผู้ให้บริการของบัญชีอื่น ให้ตรวจสอบว่าคำขอยืนยันตัวตนเป็นผู้ใช้ที่คาดไว้
หากบัญชีที่ไม่ใช่ผู้ดูแลระบบซึ่งอัปเกรดแล้วเคยบันทึกค่ากำหนดเส้นทาง ให้ใช้ Reset สำหรับปลั๊กอินนั้น ค่ารุ่นเก่าที่ถูกละเว้นจะถูกลบเพื่อไม่ให้กลับมาใช้งานหลังเปลี่ยนบทบาทภายหลัง การบันทึกหรือรีเซ็ตเส้นทาง จะล้างโมเดลที่ค้นพบของบัญชีนั้นด้วย เพื่อไม่ให้รายการล้าสมัยตามเส้นทางเก่า
คำขอมาจากแบ็กเอนด์ เมื่อ Libre WebUI ทำงานในคอนเทนเนอร์ localhost จะหมายถึงคอนเทนเนอร์นั้น ไม่ใช่เครื่องโฮสต์โดยอัตโนมัติ
คำขอถึงผู้ให้บริการจะไม่ติดตามการเปลี่ยนเส้นทาง ให้กำหนด URL การดำเนินการสุดท้ายที่ผ่านการตรวจสอบโดยตรง

แชตใช้ผู้ให้บริการผิดหรือแสดงว่าไม่พร้อมใช้งาน

ID โมเดลเดียวกันอาจมีอยู่ทั้งใน Ollama และปลั๊กอินมากกว่าหนึ่งรายการ เซสชัน Chat ปัจจุบันและ การตั้งค่าโมเดลเริ่มต้นจะบันทึกทั้งผู้ให้บริการที่เลือกและ ID โมเดลดิบ รายการที่ชื่อคล้ายกันจึงเป็น ตัวเลือกอิสระจากกัน

หากตัวเลือกระบุว่าผู้ให้บริการไม่พร้อมใช้งาน ให้เปิดใช้หรือติดตั้งปลั๊กอินรายการนั้นใหม่ และยืนยันว่า รายการโมเดลของปลั๊กอินยังมี ID โมเดลที่บันทึกไว้
หากตั้งใจลบผู้ให้บริการหรือโมเดล ให้เลือกตัวแทนอย่างชัดเจน Libre WebUI จะไม่เปลี่ยนเส้นทาง ตัวเลือกที่บันทึกไว้อย่างเจาะจงไปยังโมเดลชื่อเดียวกันของผู้ให้บริการอื่น
เซสชันและค่ากำหนดรุ่นเก่าอาจไม่มีข้อมูลกำกับผู้ให้บริการ ระเบียนเหล่านั้นจะยังใช้การกำหนดเส้นทาง แบบเดิมที่อิงเฉพาะชื่อ เพราะ Libre WebUI ไม่สามารถอนุมานผู้ให้บริการเดิมได้ ตัวเลือกโมเดลจะแสดง ว่า "ไม่ได้บันทึกผู้ให้บริการ" เลือกรายการ Ollama หรือปลั๊กอินที่ต้องการอีกครั้ง เพื่อผูกคำขอในอนาคต ไว้กับรายการนั้น
รายการ Persona ยังมีป้าย persona:<id> Persona ที่เลือกใหม่จะบันทึก Ollama เป็นผู้ให้บริการเบื้องหลัง ส่วนเซสชัน Persona เดิมที่ไม่มีข้อมูลผู้ให้บริการยังเข้ากันได้กับการกำหนดเส้นทางแบบเก่า

ปัญหา Work

ไม่พบ Work หรือสภาพแวดล้อมการทำงานไม่พร้อมใช้งาน

Work ต้องใช้บัญชีที่ยืนยันตัวตนอยู่ในขณะนั้นและมีสิทธิ์เข้าถึง Work ได้แก่ผู้ดูแลระบบ หรือผู้ใช้ ที่เปิดใช้อยู่เมื่อผู้ดูแลระบบเปิด Work ให้ผู้ใช้ทุกคนจากแท็บ User Management ใน Settings แล้ว สภาพแวดล้อม คอนเทนเนอร์ของ Work ต้องพร้อมให้แบ็กเอนด์ Libre WebUI ใช้งาน:

docker info
docker version

สำหรับแบ็กเอนด์ Docker เริ่มต้น ให้ยืนยันว่า Docker กำลังทำงานและผู้ใช้ระบบปฏิบัติการที่เรียกใช้ Libre WebUI สามารถเรียก WORK_DOCKER_COMMAND ที่กำหนดไว้ได้ การติดตั้ง Libre WebUI ด้วย npx ไม่ได้ติดตั้ง Docker หากไม่มีสภาพแวดล้อมการทำงาน Libre WebUI จะยังเปิดส่วนอื่นของ แอปพลิเคชันให้ใช้งาน และจะไม่เปลี่ยนไปเรียกคำสั่งของโมเดลบนโฮสต์

ไฟล์ Compose ในที่เก็บเปิดใช้ Work โดยเมานต์ซ็อกเก็ต Docker ของโฮสต์ สำหรับ Kubernetes ให้เปิด สภาพแวดล้อม Pod/PVC แบบเนทีฟด้วยค่า Helm work.enabled=true อย่าเมานต์ซ็อกเก็ตระบบของโหนด หากการติดตั้งใช้งานด้วย Compose ยังรายงาน Runtime unavailable หน้า Work จะระบุว่าเกิดจากกรณีใด:

ข้อความ	สาเหตุและวิธีแก้
`The "docker" CLI is not installed…`	อิมเมจกำหนดเองไม่มี `docker-cli` ให้ใช้อิมเมจทางการ หรือชี้ `WORK_DOCKER_COMMAND` ไปยัง CLI
`No Docker daemon is reachable…`	เมานต์ซ็อกเก็ตถูกนำออก หรือดีมอนของโฮสต์หยุดทำงาน คืนค่าเมานต์ในไฟล์ Compose แล้วเริ่ม Docker
`The Docker socket is mounted but…cannot open`	กลุ่มของซ็อกเก็ตต่างจากของคอนเทนเนอร์ ตั้ง `DOCKER_GID` ใน `.env` (ดูด้านล่าง) แล้วสร้างคอนเทนเนอร์ใหม่
หน้าจอ/เสียงของ Work ปิดด้วย WebSocket `1006` และบันทึก `screen is unreachable`	แบ็กเอนด์ในคอนเทนเนอร์กำลังเรียก loopback ของตัวเอง บน Docker Desktop ให้ใช้ `WORK_DOCKER_PUBLISHED_HOST=host.docker.internal` ที่มาพร้อมกับระบบ ส่วนบน Docker Engine แบบเนทีฟให้ตั้ง `WORK_PREVIEW_BIND` เป็นเกตเวย์ของ Docker bridge ที่ไม่เปิดสาธารณะเพิ่มด้วย แล้วสร้างคอนเทนเนอร์ Libre WebUI ใหม่

อ่านกลุ่มของซ็อกเก็ตผ่านคอนเทนเนอร์ เพราะโฮสต์ macOS รายงานค่าต่างจากค่าที่คอนเทนเนอร์เห็น:

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

ซ็อกเก็ตนี้ให้สิทธิ์ควบคุมโฮสต์ Docker เทียบเท่าผู้ใช้ root โปรดอ่าน Work: พื้นที่ทำงานแบบแยก เพื่อทำความเข้าใจผลต่อระบบที่ติดตั้งของคุณ

โมเดลไม่รองรับเครื่องมือ

Work ต้องใช้โมเดลสนทนาที่รองรับเครื่องมือ สำหรับ Ollama ให้เลือกโมเดลที่ติดตั้งแล้วและรายงาน ความสามารถซึ่งรวม tools สำหรับโมเดลที่ทำงานผ่านปลั๊กอิน:

ยืนยันว่าปลั๊กอินสนทนาหรือสร้างคำตอบเปิดใช้อยู่
ยืนยันว่าโมเดลที่เลือกอยู่ในรายการโมเดลที่กำหนดของปลั๊กอินนั้น
ยืนยันว่ามี API key สำหรับผู้ดูแลระบบปัจจุบัน
ยืนยันว่าผู้ให้บริการรองรับการเรียกใช้เครื่องมือสำหรับโมเดลนั้นโดยเฉพาะ

Libre WebUI จะไม่เปลี่ยนเส้นทางงาน Work ที่ล้มเหลวไปยังผู้ให้บริการอื่นโดยไม่แจ้ง

คำขอ Work ส่งกลับ HTTP 429

ระบบถึงขีดจำกัดการรับงานหรือสภาพแวดล้อมการทำงานที่เปิดใช้อยู่ โดยค่าเริ่มต้น Libre WebUI อนุญาตงานที่ใช้คอนเทนเนอร์และกำลังทำงานพร้อมกันได้สองงานทั่วทั้งระบบ และหนึ่งงานต่อผู้ใช้ ตัวอย่างที่กำลังทำงานก็ใช้ความจุของสภาพแวดล้อมเช่นกัน ให้รอการดำเนินการอื่นเสร็จ หยุดตัวอย่าง ที่ไม่ได้ใช้ หรือให้ผู้ดูแลตรวจสอบการตั้งค่า WORK_MAX_ACTIVE_RUNTIMES_* และ WORK_MAX_TASKS_*

ติดตั้งแพ็กเกจหรือเข้าถึงเครือข่ายล้มเหลว

งาน Work ใหม่ใช้เครือข่ายบริดจ์ของ Docker เพื่อให้โครงการที่สร้างขึ้นดาวน์โหลดแพ็กเกจและเริ่ม ตัวอย่างได้ ตรวจสอบ DNS ของ Docker การกำหนดค่าพร็อกซี ความพร้อมของรีจิสทรี และผลลัพธ์คำสั่ง ใน Activity Libre WebUI จะไม่เมานต์คีย์ SSH ของโฮสต์ ข้อมูลรับรองคลาวด์ โปรไฟล์เบราว์เซอร์ หรือซ็อกเก็ต Docker เข้าไปในคอนเทนเนอร์ของงาน

ตัวอย่าง Work เริ่มไม่ได้

ตรวจสอบว่าเซิร์ฟเวอร์ผูกกับ 0.0.0.0 บน WORK_PREVIEW_PORT (ค่าเริ่มต้นคือ 4173)
เว้นคำสั่งที่ไม่บังคับให้ว่าง เพื่อให้ตรวจหาสคริปต์ dev ใน package.json หรือ index.html แบบธรรมดาโดยอัตโนมัติ รวมถึงแอปที่ซ้อนอยู่หนึ่งระดับ
หาก Work รายงานว่ามีหลายแอปหรือไม่พบจุดเริ่มต้นที่รองรับ ให้ป้อนคำสั่งพัฒนาของโครงการ อย่างชัดเจนในฟิลด์คำสั่งที่ไม่บังคับ คำสั่งจะเริ่มใน /workspace ดังนั้นให้ใช้ cd <app-directory> && ... สำหรับแอปที่ซ้อนอยู่
ขยายรายละเอียดข้อผิดพลาดที่ส่งกลับเพื่อตรวจสอบผลลัพธ์การเริ่มทำงาน
หยุดตัวอย่างที่มีอยู่ก่อนเริ่มคำสั่งอื่นซึ่งต้องใช้คอนเทนเนอร์

URL ตัวอย่างใช้พอร์ตย้อนกลับที่กำหนดแบบไดนามิก เบราว์เซอร์และแบ็กเอนด์ Libre WebUI จึงต้อง ทำงานบนเครื่องเดียวกัน เบราว์เซอร์ที่เชื่อมต่อแบ็กเอนด์ระยะไกลจะเข้าถึงตัวอย่างผ่านวงรอบภายใน ของแบ็กเอนด์นั้นไม่ได้ และหน้า HTTPS อาจบล็อกตัวอย่าง HTTP ธรรมดาเพราะเป็นเนื้อหาแบบผสม

เปิดหรือบันทึกไฟล์พื้นที่ทำงานไม่ได้

API ไฟล์ของ Work รับไฟล์ข้อความ UTF-8 ขนาดไม่เกิน 2 MB หากไฟล์เปลี่ยนหลังจากคุณเปิด ให้โหลด ใหม่ก่อนบันทึกเพื่อไม่ให้เขียนทับรุ่นที่ใหม่กว่า การจัดรูปแบบจำกัดเฉพาะชนิดไฟล์ที่รองรับซึ่งมีอักขระ น้อยกว่า 100,000 ตัวและไม่เกิน 4,000 บรรทัด การเน้นไวยากรณ์จะหยุดชั่วคราวสำหรับไฟล์ขนาดใหญ่ เพื่อให้การแก้ไขยังตอบสนองได้ดี

การแก้ไขที่ยังไม่บันทึกจะเก็บเป็นฉบับร่างในเบราว์เซอร์ปัจจุบัน แต่ไม่สามารถใช้แทนการบันทึกลง พื้นที่ทำงานแบบคงอยู่ได้

งานหรือตัวอย่างถูกหยุด

การหยุดงาน หยุดตัวอย่าง หรือเริ่ม Libre WebUI ใหม่จะหยุดกระบวนการคอนเทนเนอร์แบบใช้แล้วทิ้ง แต่ยังเก็บวอลุ่มพื้นที่ทำงานที่ตั้งชื่อของงานไว้ ให้เปิดงานอีกครั้งแล้วเริ่มตัวอย่างใหม่ การลบงานต่างออกไป เมื่อยืนยันแล้ว ระบบจะลบงานและพื้นที่ทำงานของงานนั้นอย่างถาวร

ปัญหาการเข้าสู่ระบบและสมัคร

ผู้ใช้คนแรกไม่ใช่ผู้ดูแลระบบ

เฉพาะบัญชีแรกที่สร้างในฐานข้อมูลใหม่เท่านั้นที่จะเป็นผู้ดูแลระบบ ฐานข้อมูลเดิมจะคงผู้ใช้และบทบาทปัจจุบันไว้

ข้อผิดพลาด JWT

ตั้งค่าความลับที่คงที่ในระบบใช้งานจริง:

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

การเปลี่ยน JWT_SECRET จะทำให้เซสชันที่มีอยู่ใช้การไม่ได้

Turnstile บล็อกการสมัครใช้งาน

Turnstile จะเปิดใช้งานเมื่อมีคีย์ทั้งสองรายการเท่านั้น:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...

หากสมัครใช้งานไม่ได้กะทันหัน ให้ยืนยันว่าคีย์ของเว็บไซต์ตรงกับโดเมนและคีย์ลับยังใช้ได้

การเปลี่ยนเส้นทาง OAuth ล้มเหลว

ตั้งค่า URL เรียกกลับทั้งในแดชบอร์ดของผู้ให้บริการและ .env ของแบ็กเอนด์:

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

ปัญหาแชตกับเอกสาร

Libre WebUI รับไฟล์ PDF, Office (DOCX/PPTX/XLSX), Markdown, HTML, โค้ด และ CSV ขนาดไม่เกิน 10 MB

หากการค้นหาทั่วไปทำงานแต่การเรียกคืนเชิงความหมายไม่ทำงาน:

ติดตั้งโมเดลการฝังข้อมูล เช่น nomic-embed-text
เปิดใช้การฝังข้อมูลใน Settings
สร้างการฝังข้อมูลใหม่จากการตั้งค่าเอกสารหรือ API

ollama pull nomic-embed-text

การค้นหาด้วยคำสำคัญยังทำงานต่อเมื่อปิดใช้การฝังข้อมูล

ปัญหาตัวอย่างอาร์ติแฟกต์

สำหรับเกมหรือ HTML แบบโต้ตอบ ให้ขอให้โมเดลสร้างไฟล์ HTML ที่สมบูรณ์และทำงานได้ในตัวหนึ่งไฟล์ พร้อม CSS และ JavaScript แบบฝังในไฟล์

หากชิ้นงานต้องรับข้อมูลจากแป้นพิมพ์:

คลิกภายในตัวอย่างก่อน
ใช้ปุ่ม Open เพื่อเรียกใช้ในแท็บเบราว์เซอร์แยก
หลีกเลี่ยงการพึ่งพาไฟล์ภายในเครื่องที่ไม่ได้รวมอยู่ในคำตอบ

Libre WebUI สามารถรวมบล็อกโค้ด index.html + CSS + JavaScript ที่ใช้ทั่วไปได้ แต่ HTML ที่ทำงานได้ในตัวยังคงเป็นผลลัพธ์ที่เชื่อถือได้มากที่สุด

ปัญหา Docker

คอนเทนเนอร์เข้าถึง Ollama ไม่ได้

ใช้ไฟล์ Compose สำหรับ Ollama ภายนอกเมื่อ Ollama ไม่ได้อยู่ในชุด Compose เดียวกัน:

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

ข้อมูลไม่คงอยู่

เมานต์วอลุ่มข้อมูลแบบคงอยู่และตั้ง DATA_DIR หากจำเป็น คีย์เข้ารหัสจะถูกเก็บในพื้นที่จัดเก็บแบบคงอยู่เมื่อใช้ DATA_DIR หรือโหมด Docker

รีเซ็ตข้อมูลในเครื่อง

หยุดแอปก่อน จากนั้นสำรองและลบไดเรกทอรีข้อมูลที่ใช้อยู่ โดยค่าเริ่มต้นข้อมูลสำหรับการพัฒนาจะอยู่ภายใต้ backend/data

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

เริ่มแบ็กเอนด์ใหม่แล้วสร้างบัญชีใหม่

ยังแก้ไม่ได้

เปิดรายงานปัญหาพร้อมข้อมูลต่อไปนี้:

รุ่นและคอมมิตของ Libre WebUI
วิธีติดตั้ง
ระบบปฏิบัติการ
รุ่น Node.js
รุ่น Ollama
รุ่น Docker และผลลัพธ์ docker info สำหรับปัญหา Work
บันทึกแบ็กเอนด์ในช่วงที่เกิดปัญหา
ข้อผิดพลาดในคอนโซลเบราว์เซอร์
โมเดลหรือผู้ให้บริการที่ใช้อยู่โดยเจาะจง
ผลลัพธ์ Work Activity เมื่องานหรือตัวอย่างล้มเหลว

ตรวจสอบอย่างรวดเร็ว​

Libre WebUI เริ่มทำงานไม่ได้​

เบราว์เซอร์เข้าถึงแบ็กเอนด์ไม่ได้​

การสนทนาไม่สตรีมหลังผ่านพร็อกซีย้อนกลับ​

nginx​

Caddy​

Traefik​

ตรวจไม่พบ Ollama​

ปัญหาการดาวน์โหลดโมเดล​

แชตช้าหรือล้มเหลว​

การสร้างรูปภาพ OpenAI ไม่พร้อมใช้งาน​

ปัญหาปลายทางของผู้ให้บริการ​

แชตใช้ผู้ให้บริการผิดหรือแสดงว่าไม่พร้อมใช้งาน​

ปัญหา Work​

ไม่พบ Work หรือสภาพแวดล้อมการทำงานไม่พร้อมใช้งาน​

โมเดลไม่รองรับเครื่องมือ​

คำขอ Work ส่งกลับ HTTP 429​

ติดตั้งแพ็กเกจหรือเข้าถึงเครือข่ายล้มเหลว​

ตัวอย่าง Work เริ่มไม่ได้​

เปิดหรือบันทึกไฟล์พื้นที่ทำงานไม่ได้​

งานหรือตัวอย่างถูกหยุด​

ปัญหาการเข้าสู่ระบบและสมัคร​

ปัญหาแชตกับเอกสาร​

ปัญหาตัวอย่างอาร์ติแฟกต์​

ปัญหา Docker​

รีเซ็ตข้อมูลในเครื่อง​

ยังแก้ไม่ได้​