LobeChat – Hướng dẫn triển khai self-hosted trên Ubuntu với Docker Compose

LobeChat được định nghĩa là một “khung ứng dụng chat AI mã nguồn mở, với thiết kế hiện đại” (open-source, modern design AI chat framework). Đây không chỉ là một giao diện người dùng (UI) đơn thuần để trò chuyện với các mô hình ngôn ngữ lớn (LLM), mà là một nền tảng toàn diện, hiệu suất cao và có khả năng mở rộng. Nền tảng này cho phép các nhà phát triển và người dùng cá nhân dễ dàng triển khai một ứng dụng chat riêng tư, mạnh mẽ, hỗ trợ các nhà cung cấp AI hàng đầu như OpenAI (GPT-4o), Anthropic (Claude 3.5), Google (Gemini), cũng như các mô hình mã nguồn mở chạy cục bộ thông qua Ollama.

Cốt lõi của LobeChat là triết lý trao quyền cho cá nhân, hay “Super Individual”. Thay vì chỉ cung cấp một công cụ AI chung chung, LobeChat cho phép người dùng xây dựng và tùy chỉnh các “Agent” (trợ lý AI) chuyên biệt. Mỗi Agent có thể được thiết kế để giải quyết các thách thức cụ thể, từ đó nâng cao năng suất và thúc đẩy sự sáng tạo trong công việc, học tập và các dự án cá nhân. Cách tiếp cận này đánh dấu một sự chuyển dịch quan trọng: từ việc sử dụng AI như một công cụ thụ động sang việc tạo ra một “đội ngũ” AI được cá nhân hóa, làm việc song hành cùng người dùng.

LobeChat là một sản phẩm của LobeHub, một nhóm các kỹ sư-thiết kế (design-engineers) với mục tiêu cung cấp các công cụ và thành phần giao diện hiện đại cho lĩnh vực Trí tuệ Nhân tạo Tạo sinh (AIGC). Tinh thần mã nguồn mở này được thể hiện rõ nét qua một hệ sinh thái các dự án liên quan, bao gồm thư viện giao diện Lobe UI, bộ sưu tập Lobe Icons, và các chỉ mục (index) công khai cho Agent và Plugin, thúc đẩy sự tương tác, chia sẻ và đổi mới trong cộng đồng.

Kiến trúc và các thành phần chính

Giao diện người dùng (UI/UX)

Một trong những điểm mạnh nổi bật của LobeChat là giao diện người dùng được thiết kế tinh xảo và trải nghiệm trò chuyện mượt mà. Nền tảng này hỗ trợ đầy đủ cú pháp Markdown, cho phép hiển thị các định dạng văn bản phức tạp, bao gồm các khối mã (code block) với tính năng tô sáng cú pháp, công thức toán học LaTex, và sơ đồ Mermaid. Hơn nữa, LobeChat được xây dựng như một Progressive Web App (PWA), cho phép người dùng “cài đặt” ứng dụng lên máy tính hoặc thiết bị di động để có trải nghiệm liền mạch và gần giống với một ứng dụng gốc.

Framework linh hoạt

Về mặt kiến trúc, LobeChat hoạt động như một framework linh hoạt, cho phép tích hợp với nhiều nhà cung cấp mô hình AI khác nhau. Nền tảng này hỗ trợ các tương tác đa phương thức (multimodal) và có thể dễ dàng mở rộng chức năng thông qua một hệ thống plugin mạnh mẽ dựa trên cơ chế Function Calling.

Hai chế độ lưu trữ dữ liệu

LobeChat cung cấp hai kiến trúc lưu trữ dữ liệu riêng biệt, đáp ứng các nhu cầu sử dụng khác nhau:

1. Cơ sở dữ liệu phía Client (Client-Side Database): Ở chế độ mặc định này, toàn bộ dữ liệu hội thoại và cấu hình được lưu trữ cục bộ trong trình duyệt của người dùng thông qua IndexedDB. Ưu điểm của chế độ này là cực kỳ dễ triển khai, phù hợp cho người mới bắt đầu hoặc nhu cầu sử dụng cá nhân. Tuy nhiên, nó có hạn chế lớn là dữ liệu không thể đồng bộ hóa giữa các thiết bị và không hỗ trợ các tính năng nâng cao như Knowledge Base (Cơ sở tri thức).
2. Cơ sở dữ liệu phía Server (Server-Side Database): Đây là chế độ nâng cao, sử dụng PostgreSQL làm cơ sở dữ liệu trung tâm. Chế độ này cho phép đồng bộ hóa dữ liệu liền mạch trên nhiều thiết bị, quản lý người dùng thông qua các nhà cung cấp SSO (Single Sign-On), và kích hoạt các tính năng mạnh mẽ như tải tệp và RAG. Mặc dù việc triển khai phức tạp hơn, đây là lựa chọn bắt buộc cho các môi trường làm việc nhóm hoặc khi cần lưu trữ dữ liệu lâu dài và an toàn.

Đánh giá so sánh: LobeChat trong bối cảnh các giao diện AI self-hosted

Thị trường giao diện AI tự host (self-hosted) đang ngày càng trở nên đa dạng, với nhiều lựa chọn phục vụ các mục đích khác nhau. Việc lựa chọn nền tảng phù hợp ngay từ đầu là một quyết định chiến lược, ảnh hưởng trực tiếp đến khả năng, chi phí và mức độ phức tạp trong quá trình vận hành. Các nền tảng này không còn chỉ là giao diện chat đơn thuần mà đã phát triển thành các hệ sinh thái chuyên biệt. LobeChat tập trung vào trải nghiệm người dùng và hệ sinh thái mở rộng. Open WebUI tập trung vào quản lý LLM cục bộ. AnythingLLM chuyên về RAG. LibreChat nhắm đến môi trường doanh nghiệp. Sự phân hóa này cho thấy thị trường self-hosted LLM đang trưởng thành, đòi hỏi người dùng phải lựa chọn công cụ dựa trên trường hợp sử dụng cụ thể (use-case-specific) thay vì tìm kiếm một giải pháp “tất cả trong một”.

Bảng dưới đây so sánh LobeChat với các đối thủ cạnh tranh phổ biến khác để cung cấp một cái nhìn tổng quan, giúp người dùng đưa ra lựa chọn sáng suốt.

Table 1: So sánh LobeChat và các Giao diện Chat AI Self-Hosted Phổ biến

Hỗ trợ da nhà cung cấp mô hình (Multi-Provider Support)

Khả năng kết nối linh hoạt

Một trong những lợi thế cạnh tranh lớn nhất của LobeChat là khả năng kết nối với một danh sách đa dạng các nhà cung cấp mô hình AI. Nền tảng này hỗ trợ các tên tuổi lớn như OpenAI, Anthropic (Claude), Google (Gemini), DeepSeek, Qwen và nhiều nhà cung cấp khác có API tương thích với OpenAI. Sự linh hoạt này giải phóng người dùng khỏi tình trạng bị “khóa chân” vào một nhà cung cấp duy nhất (vendor lock-in), cho phép họ tự do lựa chọn và chuyển đổi giữa các mô hình để tìm ra giải pháp tối ưu nhất về hiệu suất và chi phí cho từng tác vụ cụ thể.

Tích hợp LLM cục bộ với Ollama

LobeChat đã tích hợp sâu với Ollama, một framework mạnh mẽ cho phép chạy các mô hình ngôn ngữ lớn ngay trên phần cứng của người dùng. Đây là một tính năng mang tính đột phá, đáp ứng nhu cầu ngày càng tăng về quyền riêng tư và bảo mật dữ liệu tuyệt đối. Bằng cách sử dụng biến môi trường

OLLAMA_PROXY_URL, người dùng có thể dễ dàng kết nối LobeChat với một instance Ollama đang chạy, cho phép thực hiện các cuộc trò chuyện hoàn toàn ngoại tuyến và bảo mật.

Tùy chỉnh danh sách mô hình

Để tăng cường khả năng kiểm soát, LobeChat cho phép người dùng tùy chỉnh danh sách mô hình hiển thị trên giao diện. Thông qua các biến môi trường như OPENAI_MODEL_LIST, người dùng có thể thêm các mô hình tùy chỉnh, ẩn đi các mô hình không sử dụng, hoặc đặt lại tên hiển thị cho các mô hình để phù hợp hơn với quy ước của tổ chức.

Năng lực đa phương thức (Multimodal Capabilities)

Thị giác máy tính (Vision)

LobeChat hỗ trợ các mô hình có khả năng nhận dạng hình ảnh, điển hình là gpt-4-vision của OpenAI. Tính năng này cho phép người dùng tải lên hoặc kéo thả hình ảnh trực tiếp vào khung chat. Trợ lý AI sau đó có thể “nhìn” và phân tích nội dung hình ảnh, từ đó tham gia vào các cuộc hội thoại thông minh và trực quan hơn.

Tổng hợp và nhận dạng giọng nói (TTS & STT)

Nền tảng tích hợp sẵn công nghệ chuyển văn bản thành giọng nói (Text-to-Speech – TTS) và chuyển giọng nói thành văn bản (Speech-to-Text – STT). Điều này cho phép người dùng tương tác với trợ lý AI thông qua giọng nói một cách tự nhiên. LobeChat cung cấp nhiều tùy chọn giọng đọc chất lượng cao từ các dịch vụ như OpenAI Audio và Microsoft Edge Speech, đáp ứng sở thích của người dùng từ nhiều khu vực khác nhau.

Tạo sinh hình ảnh (Text-to-Image)

Thông qua hệ thống plugin, LobeChat có thể gọi các công cụ tạo sinh hình ảnh mạnh mẽ như DALL-E 3 và MidJourney. Người dùng có thể yêu cầu trợ lý AI tạo ra hình ảnh dựa trên mô tả văn bản ngay trong cuộc trò chuyện, biến ý tưởng thành hình ảnh một cách liền mạch.

Hệ thống plugin và thị trường Agent (Agent Market)

Mở rộng chức năng với Plugin

Hệ thống plugin là một phần mở rộng quan trọng của LobeChat, giúp nâng cao đáng kể tính thực tiễn và linh hoạt của các trợ lý AI. Bằng cách kích hoạt plugin, trợ lý có thể tương tác với các dịch vụ và API bên ngoài để thực hiện các tác vụ như tìm kiếm thông tin thời gian thực trên web, truy vấn dữ liệu tài chính hoặc thông tin game, và nhiều chức năng khác.

Cơ chế Function Calling

LobeChat sử dụng cơ chế “Function Calling” để kích hoạt các plugin. Khi người dùng đưa ra một yêu cầu, mô hình LLM sẽ phân tích ý định, xác định xem có cần gọi một công cụ bên ngoài hay không. Nếu có, nó sẽ tạo ra một yêu cầu Function Call với các tham số cần thiết ở định dạng JSON. LobeChat sau đó sẽ gửi yêu cầu API này đến máy chủ plugin tương ứng để xử lý và nhận lại kết quả.

Thị trường Agent (Agent Market)

LobeChat cung cấp một “thị trường” (Agent Market) với hơn 505 Agent được tạo sẵn, chuyên biệt cho nhiều lĩnh vực và tác vụ khác nhau như lập trình, viết lách học thuật, học ngoại ngữ, và giải trí. Người dùng có thể dễ dàng tìm kiếm, khám phá và thêm các agent này vào danh sách của mình chỉ với một cú nhấp chuột.

Tùy chỉnh Agent

Ngoài việc sử dụng các agent có sẵn, người dùng có toàn quyền tạo ra các agent tùy chỉnh. LobeChat cung cấp một trình soạn thảo trực quan cho phép người dùng định nghĩa hành vi của agent thông qua các chỉ dẫn hệ thống (system prompt), cấu hình các tham số của mô hình (như nhiệt độ, top_p), và lựa chọn các plugin cần thiết để trang bị cho agent những kỹ năng cụ thể.

Cơ sở tri thức (Knowledge Base) và RAG

Xây dựng Chatbot trên dữ liệu riêng

Tính năng Cơ sở tri thức (Knowledge Base) là một trong những tính năng nâng cao mạnh mẽ nhất của LobeChat, cho phép người dùng tải lên các tài liệu của riêng mình để xây dựng một chatbot có khả năng trả lời các câu hỏi dựa trên nội dung độc quyền đó. Tính năng này được hiện thực hóa thông qua kỹ thuật Retrieval-Augmented Generation (RAG).

Kiến trúc RAG của LobeChat

Kiến trúc RAG trong LobeChat được thiết kế theo dạng module, bao gồm các thành phần cốt lõi sau:

1. Lưu trữ tệp (File Storage): Các tệp gốc mà người dùng tải lên (ví dụ: PDF, DOCX) được lưu trữ trong một dịch vụ lưu trữ đối tượng tương thích với S3, chẳng hạn như MinIO khi tự host.
2. Xử lý và Vector hóa (Processing & Vectorization): Các tài liệu được phân đoạn (chunking) thành các mẩu văn bản nhỏ hơn. Sau đó, các đoạn văn bản này được chuyển đổi thành các vector nhúng (embeddings) – là các biểu diễn số của ngữ nghĩa – thông qua các mô hình embedding. LobeChat mặc định sử dụng text-embedding-3-small của OpenAI nhưng cũng hỗ trợ các mô hình embedding cục bộ qua Ollama.
3. Lưu trữ và Truy vấn Vector (Vector Storage & Retrieval): Các vector nhúng này được lưu trữ và lập chỉ mục trong một cơ sở dữ liệu PostgreSQL đã được cài đặt extension pgvector. Extension này cho phép thực hiện các truy vấn tìm kiếm tương đồng ngữ nghĩa (semantic search) hiệu quả, giúp tìm ra các đoạn văn bản liên quan nhất đến câu hỏi của người dùng.

Các định dạng tệp được hỗ trợ

LobeChat hỗ trợ tải lên “tất cả các loại tệp” và cung cấp khả năng xem trước trực tuyến cho nhiều định dạng phổ biến như PDF, Excel, Word, PPT, TXT, và Markdown. Điều này mang lại sự tiện lợi lớn cho người dùng khi quản lý và tương tác với tài liệu của họ. Đối với các định dạng tài liệu phức tạp hơn, hệ thống có thể cần đến công cụ xử lý tài liệu phi cấu trúc như Unstructured.io.

Việc LobeChat tách biệt các thành phần của kiến trúc RAG (lưu trữ tệp qua S3, cơ sở dữ liệu vector qua Postgres, và dịch vụ embedding) là một quyết định thiết kế quan trọng. Một mặt, nó mang lại sự linh hoạt tối đa, cho phép người dùng có kinh nghiệm thay thế từng thành phần để phù hợp với hạ tầng hiện có (ví dụ: sử dụng Amazon S3 thay vì MinIO). Mặt khác, điều này làm tăng đáng kể độ phức tạp khi triển khai self-hosted so với các giải pháp RAG “tất cả trong một” như AnythingLLM. Điều này tạo ra một rào cản kỹ thuật nhất định cho người dùng không chuyên và nhấn mạnh sự khác biệt giữa triển khai LobeChat ở chế độ “cơ bản” và “nâng cao”. Do đó, người dùng muốn tận dụng tính năng RAG cần có kiến thức vững chắc về DevOps, cơ sở dữ liệu, và lưu trữ đối tượng.

Toàn quyền kiểm soát dữ liệu và bảo mật

Xu hướng tự host (self-hosting) các ứng dụng LLM không chỉ là một phong trào kỹ thuật mà còn là một phản ứng chiến lược trước những lo ngại ngày càng tăng về quyền riêng tư, chi phí leo thang và sự phụ thuộc vào các ông lớn công nghệ. LobeChat, với khả năng hỗ trợ cả API đám mây và LLM cục bộ, được định vị một cách hoàn hảo để phục vụ cho xu hướng “AI lai” (hybrid AI) này. Người dùng có thể bắt đầu với API của OpenAI để có hiệu suất cao nhất, sau đó chuyển dần sang các mô hình tự host khi nhu cầu về quyền riêng tư và kiểm soát chi phí tăng lên, tất cả trên cùng một giao diện quen thuộc.

Quyền riêng tư tuyệt đối

Khi tự host LobeChat, đặc biệt khi kết hợp với các mô hình ngôn ngữ lớn (LLM) chạy cục bộ qua Ollama, toàn bộ dữ liệu—từ các câu lệnh (prompts), nội dung hội thoại, đến các tệp được tải lên—không bao giờ rời khỏi hạ tầng của người dùng. Điều này mang lại quyền riêng tư tuyệt đối, loại bỏ hoàn toàn nguy cơ các nhà cung cấp dịch vụ đám mây sử dụng dữ liệu của người dùng để huấn luyện các mô hình AI của họ.

Tuân thủ quy định (Compliance)

Việc nắm giữ và kiểm soát hoàn toàn dữ liệu giúp các tổ chức, đặc biệt là trong các lĩnh vực nhạy cảm như y tế và tài chính, dễ dàng tuân thủ các quy định nghiêm ngặt về bảo vệ dữ liệu như GDPR của Châu Âu hay HIPAA của Hoa Kỳ.

Bảo mật nâng cao

Tự host giúp giảm thiểu bề mặt tấn công (attack surface) và nguy cơ rò rỉ dữ liệu qua các API của bên thứ ba. Người dùng có thể chủ động triển khai các lớp bảo mật của riêng mình, chẳng hạn như tường lửa, mã hóa toàn diện, và thậm chí là các mạng cô lập (air-gapped environments) cho các ứng dụng cực kỳ nhạy cảm.

Tùy biến và linh hoạt tối đa

Tùy chỉnh không giới hạn

Với mã nguồn mở, người dùng có toàn quyền sửa đổi mọi khía cạnh của LobeChat, từ giao diện người dùng, luồng làm việc cho đến việc tích hợp các mô hình và dịch vụ độc quyền của riêng họ. Khả năng tùy biến này là điều mà các dịch vụ đám mây đóng không thể cung cấp.

Tinh chỉnh (Fine-tuning) mô hình

Self-hosting mở ra khả năng tinh chỉnh (fine-tuning) các mô hình mã nguồn mở trên các bộ dữ liệu chuyên biệt. Điều này cho phép các tổ chức tạo ra các LLM có hiệu suất vượt trội cho các tác vụ đặc thù, mang lại lợi thế cạnh tranh đáng kể.

Tránh bị khóa bởi nhà cung cấp (Vendor Lock-in)

Người dùng không còn bị phụ thuộc vào lộ trình phát triển sản phẩm, chính sách giá cả, hay quyết định “ngừng hỗ trợ” các phiên bản mô hình cũ của một nhà cung cấp duy nhất. Họ có thể tự do chuyển đổi giữa các mô hình và nhà cung cấp để luôn có được công nghệ tốt nhất.

Phân tích hiệu quả chi phí dài hạn

Chi phí ban đầu và chi phí vận hành

Việc tự host đòi hỏi một khoản đầu tư ban đầu không nhỏ cho phần cứng, đặc biệt là các GPU mạnh mẽ, cùng với các chi phí vận hành liên tục như tiền điện và bảo trì.

So sánh với chi phí API

Các dịch vụ API thường tính phí dựa trên số lượng token được xử lý. Với khối lượng sử dụng lớn, chi phí này có thể tăng lên nhanh chóng và trở nên khó dự đoán. Một phân tích đã chỉ ra rằng việc tự host có thể giúp giảm chi phí tới hơn 95% đối với các ứng dụng có lưu lượng sử dụng rất cao.

Điểm hòa vốn

Việc tự host chỉ thực sự hiệu quả về mặt chi phí khi khối lượng sử dụng đạt đến một ngưỡng nhất định, ví dụ như trên một triệu yêu cầu mỗi tháng. Đối với các cá nhân hoặc nhóm nhỏ có nhu cầu không thường xuyên, việc sử dụng các dịch vụ API trả theo dung lượng vẫn có thể là lựa chọn kinh tế hơn.

Tối ưu hiệu suất và giảm thiểu độ trễ

Độ trễ thấp hơn

Khi triển khai tại chỗ (on-premise) hoặc trên một máy chủ riêng, dữ liệu không cần phải di chuyển qua lại trên Internet đến các trung tâm dữ liệu ở xa. Điều này giúp giảm đáng kể độ trễ (latency), mang lại thời gian phản hồi gần như tức thì, một yếu tố cực kỳ quan trọng đối với các ứng dụng tương tác thời gian thực.

Tính sẵn sàng và độ tin cậy

Người dùng có toàn quyền kiểm soát thời gian hoạt động (uptime) của dịch vụ. Họ không bị ảnh hưởng bởi các sự cố ngừng hoạt động hoặc bảo trì từ các nhà cung cấp đám mây bên ngoài, đảm bảo tính liên tục cho các ứng dụng quan trọng.

Không giới hạn tốc độ (Rate Limits)

Việc tự host loại bỏ các rào cản về giới hạn số lượng yêu cầu mỗi phút hoặc mỗi ngày (rate limits) thường thấy ở các nhà cung cấp API. Người dùng có thể khai thác tối đa năng lực phần cứng của mình mà không bị giới hạn nhân tạo.

Yêu cầu hệ thống (System Requirements)

Việc lựa chọn cấu hình phần cứng phù hợp là bước đầu tiên và quan trọng nhất, quyết định đến hiệu suất và chi phí của toàn bộ hệ thống self-hosted. Có sự khác biệt đáng kể về yêu cầu tài nguyên giữa các chế độ triển khai của LobeChat. Các tài liệu chính thức và báo cáo từ cộng đồng cho thấy sự mâu thuẫn nhất định, ví dụ, một số nguồn đề xuất RAM tối thiểu chỉ 1GB, trong khi các nguồn khác yêu cầu 4GB và người dùng thực tế báo cáo mức sử dụng lên tới 5GB. Sự khác biệt này bắt nguồn từ việc các yêu cầu này áp dụng cho các kịch bản khác nhau. Yêu cầu thấp dành cho chế độ “client-side” đơn giản, trong khi yêu cầu cao hơn áp dụng cho chế độ “server-side” đầy đủ với cơ sở dữ liệu và các dịch vụ đi kèm. Bảng dưới đây cung cấp một ước tính thực tế hơn để giúp người dùng lập kế hoạch chính xác.

Yêu cầu tài nguyên hệ thống ước tính

LƯU Ý:
Yêu cầu VRAM được ước tính dựa trên các quy tắc chung và thực nghiệm. Việc fine-tuning đòi hỏi nhiều VRAM hơn so với chỉ chạy suy luận (inference).

Cài đặt Docker Engine trên Ubuntu

Để đảm bảo một môi trường triển khai ổn định và tương thích, việc cài đặt Docker Engine theo phương pháp chính thức là rất quan trọng.

1. Gỡ cài đặt các phiên bản cũ: Trước khi bắt đầu, hãy gỡ bỏ bất kỳ gói Docker không chính thức nào có thể đã được cài đặt từ kho lưu trữ mặc định của Ubuntu để tránh xung đột:

sudo apt-get remove docker docker-engine docker.io containerd runc

2. Thiết lập kho lưu trữ Docker:

Cập nhật chỉ mục gói apt và cài đặt các gói cần thiết để apt có thể sử dụng kho lưu trữ qua HTTPS.

sudo apt-get update sudo apt-get install ca-certificates curl gnupg

Thêm khóa GPG chính thức của Docker để xác thực các gói tải về.

sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg

Thêm kho lưu trữ Docker vào danh sách nguồn của APT.

echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3. Cài đặt Docker Engine: Cài đặt phiên bản mới nhất của Docker Engine cùng các thành phần liên quan.

sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4. Cấu hình sau cài đặt: Để có thể thực thi các lệnh Docker mà không cần sudo, hãy thêm người dùng hiện tại vào nhóm docker.

sudo usermod -aG docker $USER

Lưu ý: Bạn cần đăng xuất và đăng nhập lại để thay đổi này có hiệu lực.

5. Xác minh cài đặt: Chạy container hello-world để kiểm tra xem Docker đã được cài đặt và hoạt động chính xác chưa.

docker run hello-world

Cài đặt Docker Compose

Kể từ các phiên bản Docker gần đây, Docker Compose được tích hợp dưới dạng một plugin (docker compose) thay vì một tệp nhị phân độc lập (docker-compose). Lệnh cài đặt Docker Engine ở trên đã bao gồm cả plugin này.

Để xác minh Docker Compose đã sẵn sàng, hãy chạy lệnh:

docker compose version

Bạn sẽ thấy thông tin phiên bản được hiển thị, ví dụ: Docker Compose version v2.27.0.

Giới thiệu Chế độ Client-Side

Đây là phương pháp triển khai nhanh chóng và đơn giản nhất, lý tưởng cho những người muốn nhanh chóng trải nghiệm LobeChat hoặc chỉ có nhu cầu sử dụng cá nhân trên một thiết bị duy nhất. Ở chế độ này, tất cả dữ liệu hội thoại và cấu hình của bạn sẽ được lưu trữ trực tiếp trong cơ sở dữ liệu IndexedDB của trình duyệt. Cần lưu ý những hạn chế của chế độ này: dữ liệu không được đồng bộ hóa giữa các máy tính hay trình duyệt khác nhau, và các tính năng nâng cao như Cơ sở tri thức (Knowledge Base) sẽ không khả dụng.

Cấu trúc thư mục và tệp docker-compose.yml

Để bắt đầu, hãy tạo một thư mục cho dự án của bạn và tạo một tệp docker-compose.yml bên trong.

1. Tạo và di chuyển vào thư mục dự án:

mkdir ~/lobe-chat-basic && cd ~/lobe-chat-basic

2. Tạo tệp docker-compose.yml bằng trình soạn thảo văn bản yêu thích của bạn (ví dụ: nano docker-compose.yml) với nội dung sau:YAMLversion: '3.8' services: lobe-chat: image: lobehub/lobe-chat:latest container_name: lobe-chat-basic restart: always ports: - '3210:3210' environment: - OPENAI_API_KEY=sk-xxxxxx - ACCESS_CODE=your-strong-password

version: '3.8'
services:
  lobe-chat:
    image: lobehub/lobe-chat:latest
    container_name: lobe-chat-basic
    restart: always
    ports:
      - '3210:3210'
    environment:
      - OPENAI_API_KEY=sk-xxxxxx
      - ACCESS_CODE=your-strong-password

Giải thích các biến môi trường cơ bản

• OPENAI_API_KEY: (Bắt buộc) Đây là khóa API từ tài khoản OpenAI của bạn. LobeChat cần khóa này để có thể gửi yêu cầu đến các mô hình của OpenAI. Bạn phải thay thế sk-xxxxxx bằng khóa API thực của mình.
• ACCESS_CODE: (Tùy chọn nhưng rất khuyến khích) Đây là mật khẩu để truy cập vào dịch vụ LobeChat của bạn. Việc đặt một mật khẩu mạnh giúp bảo vệ khóa API của bạn khỏi bị lạm dụng và ngăn chặn truy cập trái phép. Bạn cũng có thể cung cấp một danh sách các mật khẩu, phân tách nhau bằng dấu phẩy (ví dụ: code1,code2,code3).
• OPENAI_PROXY_URL: (Tùy chọn) Nếu bạn ở trong một khu vực mạng không thể truy cập trực tiếp API của OpenAI, bạn có thể sử dụng biến này để chỉ định URL của một máy chủ proxy.

Khởi chạy và truy cập

1. Từ bên trong thư mục ~/lobe-chat-basic, chạy lệnh sau để khởi động container ở chế độ nền: docker compose up -d
2. Kiểm tra trạng thái của container để đảm bảo nó đang chạy: docker compose ps
3. Để xem log và theo dõi quá trình khởi động hoặc gỡ lỗi, sử dụng lệnh: docker compose logs -f lobe-chat
4. Sau khi container khởi động thành công, hãy mở trình duyệt và truy cập vào địa chỉ http://<your-server-ip>:3210. Bạn sẽ được yêu cầu nhập ACCESS_CODE đã thiết lập để bắt đầu sử dụng LobeChat.

Triển khai nâng cao (Server-Side Database)

Để kích hoạt các tính năng nâng cao như đồng bộ hóa dữ liệu đa thiết bị, quản lý người dùng, và Cơ sở tri thức (RAG), việc triển khai một kiến trúc full-stack là bắt buộc. Kiến trúc này phức tạp hơn đáng kể so với chế độ cơ bản và bao gồm nhiều dịch vụ phối hợp với nhau:

• LobeChat (Image: lobehub/lobe-chat-database): Đây là container chính của ứng dụng, được xây dựng đặc biệt để hoạt động ở chế độ server, kết nối với các dịch vụ backend khác.
• PostgreSQL (Image: pgvector/pgvector:pg16): Cơ sở dữ liệu quan hệ, đóng vai trò là nơi lưu trữ trung tâm cho dữ liệu người dùng, lịch sử hội thoại, và quan trọng nhất là các vector nhúng (embeddings) cho tính năng RAG. Việc sử dụng image pgvector đảm bảo extension cần thiết cho tìm kiếm vector đã được cài đặt sẵn.
• MinIO (Image: minio/minio): Một dịch vụ lưu trữ đối tượng (object storage) tương thích với Amazon S3. MinIO được sử dụng để lưu trữ các tệp mà người dùng tải lên, chẳng hạn như hình ảnh, tài liệu PDF, Word, v.v., phục vụ cho tính năng RAG.
• Nhà cung cấp SSO (Image: logto/logto hoặc casdoor/casdoor): Một dịch vụ xác thực và quản lý định danh người dùng tập trung (Single Sign-On). Nó xử lý việc đăng nhập, đăng ký, và quản lý người dùng, tách biệt logic này ra khỏi ứng dụng LobeChat chính.

Hướng dẫn cấu hình với docker-compose.yml và .env

Sử dụng Script cài đặt tự động

LobeChat cung cấp một script cài đặt (setup.sh) để tự động hóa việc tạo các tệp cấu hình ban đầu, bao gồm docker-compose.yml, .env, và init_data.json. Script này cung cấp ba chế độ hoạt động:

• local (chỉ truy cập cục bộ)
• port (truy cập qua IP và cổng)
• domain (truy cập qua tên miền với reverse proxy)

Đây là cách nhanh nhất để bắt đầu, nhưng để hiểu sâu về hệ thống, việc cấu hình thủ công được khuyến khích.

Cấu hình thủ công

Dưới đây là một tệp docker-compose.yml mẫu, hoàn chỉnh, thể hiện cách các dịch vụ kết nối với nhau. Tệp này được tổng hợp từ nhiều nguồn tài liệu và ví dụ thực tế.

# docker-compose.yml
version: '3.9'

services:
  lobe-chat:
    image: lobehub/lobe-chat-database:latest
    container_name: lobe-chat-server
    restart: always
    ports:
      - "3210:3210"
    env_file:
      -.env
    depends_on:
      - postgres
      - minio
    networks:
      - lobe-network

  postgres:
    image: pgvector/pgvector:pg16
    container_name: postgres
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5432:5432" # Chỉ mở port này nếu cần truy cập DB từ bên ngoài
    networks:
      - lobe-network

  minio:
    image: minio/minio:latest
    container_name: minio
    restart: always
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"  # S3 API Port
      - "9001:9001"  # MinIO Console Port
    volumes:
      - minio_data:/data
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    networks:
      - lobe-network

volumes:
  postgres_data:
    driver: local
  minio_data:
    driver: local

networks:
  lobe-network:
    driver: bridge

Tệp .env và các biến Môi trường

Việc cấu hình sai các biến môi trường là nguyên nhân hàng đầu gây ra lỗi khi triển khai. Bảng dưới đây cung cấp một tham chiếu chi tiết về các biến quan trọng nhất.

Các biến môi trường cốt lõi cho triển khai nâng cao

Bảo mật truy cập với Nginx Reverse Proxy và Let’s Encrypt

Tại sao cần Reverse Proxy

Sử dụng một reverse proxy như Nginx mang lại nhiều lợi ích thiết thực:

• Hợp nhất dịch vụ: Cho phép truy cập nhiều dịch vụ (LobeChat, MinIO Console, Logto) thông qua các tên miền phụ (subdomain) khác nhau trên cùng một địa chỉ IP và cổng 80/443.
• Quản lý SSL/TLS tập trung: Dễ dàng cấu hình và tự động gia hạn chứng chỉ SSL/TLS từ Let’s Encrypt cho tất cả các dịch vụ tại một nơi duy nhất.
• Tăng cường bảo mật: Thêm một lớp bảo vệ giữa Internet và các container ứng dụng của bạn.

Cài đặt Nginx và Certbot

1. Cài đặt Nginx: sudo apt update && sudo apt install nginx
2. Cài đặt Certbot và plugin cho Nginx: sudo apt install certbot python3-certbot-nginx

Cấu hình Nginx

Tạo một tệp cấu hình mới cho LobeChat trong /etc/nginx/sites-available/.

Nginx

# /etc/nginx/sites-available/lobechat.conf
server {
    listen 80;
    server_name chat.yourdomain.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name chat.yourdomain.com;

    # Đường dẫn SSL sẽ được Certbot tự động thêm vào
    # ssl_certificate /etc/letsencrypt/live/chat.yourdomain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/chat.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3210;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Kích hoạt cấu hình: sudo ln -s /etc/nginx/sites-available/lobechat.conf /etc/nginx/sites-enabled/

Kiểm tra cú pháp Nginx: sudo nginx -t

Khởi động lại Nginx: sudo systemctl restart nginx

Lấy chứng chỉ SSL

Chạy Certbot để tự động lấy chứng chỉ và cấu hình Nginx sử dụng HTTPS:

sudo certbot --nginx -d chat.yourdomain.com

Lặp lại quy trình trên cho các dịch vụ khác như MinIO Console (minio.yourdomain.com) và Logto (auth.yourdomain.com), trỏ proxy_pass đến các cổng tương ứng (9001 cho MinIO Console, cổng của Logto cho Logto).

Một điểm kỹ thuật quan trọng thường bị bỏ qua, dẫn đến các lỗi chuyển hướng và đăng nhập ⁷⁶, là việc ứng dụng backend cần biết URL công khai mà người dùng đang truy cập. Do đó, việc cấu hình các header

X-Forwarded-For và X-Forwarded-Proto trong Nginx là cực kỳ quan trọng. Đồng thời, các biến môi trường như APP_URL trong tệp .env của LobeChat phải được đặt thành URL công khai đầy đủ với https (ví dụ: https://chat.yourdomain.com), chứ không phải địa chỉ cục bộ như http://localhost:3210.

Quy trình nâng cấp an toàn (Upgrading)

Việc giữ cho LobeChat được cập nhật là rất quan trọng để nhận các bản vá bảo mật và tính năng mới. Quy trình nâng cấp an toàn cho một hệ thống triển khai bằng Docker Compose bao gồm các bước sau:

1. Sao lưu (Backup): Luôn luôn thực hiện sao lưu toàn bộ hệ thống trước khi tiến hành bất kỳ hoạt động nâng cấp nào.
2. Kéo (Pull) Image Mới: Di chuyển đến thư mục chứa tệp docker-compose.yml của bạn và chạy lệnh sau. Lệnh này sẽ kiểm tra và tải về các phiên bản image mới nhất cho tất cả các dịch vụ được định nghĩa trong tệp compose (LobeChat, Postgres, MinIO, v.v.): docker compose pull
3. Dừng và khởi động lại Container:
   • Sử dụng docker compose down để dừng và xóa các container cũ. Thao tác này không xóa các volume dữ liệu của bạn. Sau đó, sử dụng docker compose up -d để khởi động lại toàn bộ hệ thống với các image mới vừa được kéo về. Docker Compose sẽ tự động tạo lại các container và gắn chúng vào các volume dữ liệu hiện có.

docker compose down
docker compose up -d

4. Dọn dẹp Image cũ (Tùy chọn): Sau khi xác nhận hệ thống hoạt động ổn định, bạn có thể xóa các image Docker cũ không còn được sử dụng để giải phóng dung lượng đĩa.

docker image prune

LobeChat cũng cung cấp một script tự động cập nhật, có thể được tích hợp vào crontab để thực hiện các bước trên một cách định kỳ. Tuy nhiên, cần đảm bảo script có đủ quyền và có thể tìm thấy lệnh docker và docker compose một cách chính xác, thường bằng cách sử dụng đường dẫn tuyệt đối.

Chiến lược backup và restore toàn diện

Một chiến lược sao lưu và phục hồi đáng tin cậy là nền tảng cho sự ổn định của bất kỳ dịch vụ tự host nào.

Sao lưu cấu hình

Sao lưu các tệp docker-compose.yml và .env. Đây là những tệp văn bản nhỏ nhưng cực kỳ quan trọng, chứa toàn bộ “bản thiết kế” của hệ thống và các thông tin nhạy cảm như khóa API và mật khẩu.

Sao lưu cơ sở dữ liệu PostgreSQL

Phương pháp được khuyến nghị là tạo một bản sao lưu logic (dump) của cơ sở dữ liệu bằng tiện ích pg_dump. Bản sao lưu này có định dạng văn bản (SQL) và không phụ thuộc vào phiên bản PostgreSQL hay kiến trúc hệ điều hành, giúp việc phục hồi trở nên linh hoạt hơn.

Lệnh sao lưu:

docker exec -t postgres pg_dumpall -c -U ${POSTGRES_USER} > dump_$(date +%F).sql

Lệnh này sẽ kết nối vào container postgres và tạo một tệp dump.sql chứa toàn bộ dữ liệu và cấu trúc của cơ sở dữ liệu trong thư mục hiện tại của máy chủ host.

Sao lưu dữ liệu MinIO

Dữ liệu của MinIO (các tệp người dùng tải lên) được lưu trữ trong một Docker volume.

• Phương pháp an toàn nhất (khuyến nghị): Sử dụng MinIO Client (mc) để thực hiện mirror (sao chép đồng bộ) toàn bộ bucket sang một vị trí lưu trữ khác (ví dụ: một máy chủ backup khác hoặc một dịch vụ lưu trữ đám mây).
• Phương pháp thay thế (yêu cầu dừng dịch vụ):
  1. Dừng container MinIO: docker compose stop minio.
  2. Nén toàn bộ thư mục volume của MinIO (ví dụ: ~/lobe-chat-advanced/volumes/minio) thành một tệp .tar.gz.
  3. Khởi động lại container: docker compose start minio.

Việc sao chép trực tiếp volume khi container đang chạy có thể dẫn đến dữ liệu không nhất quán hoặc bị hỏng.

Quy trình restore

1. Trên một máy chủ mới, cài đặt Docker và Docker Compose.
2. Khôi phục các tệp cấu hình docker-compose.yml và .env.
3. Chạy docker compose up -d để tạo lại cấu trúc container và các volume trống.
4. Phục hồi cơ sở dữ liệu PostgreSQL từ tệp sao lưu: cat dump_YYYY-MM-DD.sql | docker exec -i postgres psql -U ${POSTGRES_USER}
5. Phục hồi dữ liệu MinIO bằng cách giải nén tệp sao lưu vào đúng thư mục volume hoặc sử dụng mc mirror để sao chép dữ liệu trở lại.
6. Khởi động lại toàn bộ stack: docker compose restart.

Giám sát và ghi log (Monitoring & Logging)

• Giám sát tài nguyên cơ bản: Sử dụng lệnh docker stats để xem mức sử dụng CPU, RAM, và mạng của các container đang chạy theo thời gian thực.
• Kiểm tra Log: Lệnh docker compose logs -f <tên_dịch_vụ> là công cụ không thể thiếu để theo dõi log của một dịch vụ cụ thể (ví dụ: docker compose logs -f lobe-chat). Nó rất hữu ích cho việc gỡ lỗi khi một dịch vụ không khởi động được hoặc hoạt động bất thường.
• Công cụ nâng cao: Đối với các môi trường sản xuất đòi hỏi khả năng giám sát chuyên sâu hơn, có thể xem xét triển khai các công cụ như Portainer (giao diện quản lý Docker), hoặc một stack giám sát hoàn chỉnh bao gồm cAdvisor, Prometheus và Grafana.

Các lỗi thường gặp

Lỗi xác thực và chuyển hướng (Authentication & Redirect Issues)

• Vấn đề: Sau khi cấu hình reverse proxy (ví dụ: Nginx), người dùng gặp lỗi “Redirect URI mismatch” khi cố gắng đăng nhập, hoặc bị chuyển hướng sai về localhost thay vì tên miền công khai.
• Nguyên nhân: LobeChat (ứng dụng Next.js) và nhà cung cấp SSO (Casdoor/Logto) không nhận được thông tin chính xác về URL mà người dùng đang truy cập. Chúng cần biết URL công khai để tạo ra các liên kết chuyển hướng và callback một cách chính xác.
• Giải pháp:
  1. Kiểm tra lại cấu hình Nginx. Đảm bảo rằng các header proxy_set_header X-Forwarded-Proto $scheme; và proxy_set_header Host $host; đã được thiết lập đúng. Các header này thông báo cho ứng dụng backend biết giao thức (http/https) và tên miền gốc của yêu cầu.
  2. Trong tệp .env của LobeChat, hãy chắc chắn rằng biến APP_URL và các biến liên quan đến auth (ví dụ: AUTH_LOGTO_ISSUER) được đặt thành URL công khai đầy đủ, bao gồm cả https:// (ví dụ: https://chat.yourdomain.com), không phải là địa chỉ cục bộ.

Sự cố kết nối giữa các Container

• Vấn đề: Log của LobeChat báo lỗi “Connection refused” hoặc “Timeout” khi cố gắng kết nối đến PostgreSQL hoặc MinIO.
• Nguyên nhân: Các container không nằm trên cùng một mạng Docker (Docker network), hoặc tên dịch vụ (hostname) trong các chuỗi kết nối (ví dụ: DATABASE_URL) không khớp với tên dịch vụ được định nghĩa trong docker-compose.yml.
• Giải pháp:
  1. Trong tệp docker-compose.yml, đảm bảo tất cả các dịch vụ (lobe-chat, postgres, minio,…) đều được khai báo thuộc cùng một networks (ví dụ: lobe-network).
  2. Trong tệp .env, khi định nghĩa DATABASE_URL hoặc S3_ENDPOINT, hãy sử dụng tên của service làm hostname, không phải localhost hay 127.0.0.1. Ví dụ: DATABASE_URL=postgresql://user:pass@postgres:5432/lobedb (ở đây postgres là tên của service PostgreSQL).

Lỗi khi tải lên tệp hoặc sử dụng Knowledge Base

• Vấn đề: Người dùng gặp lỗi “File content is empty” khi tải tệp lên, hoặc lỗi InvalidProviderAPIKey trong quá trình vector hóa tài liệu.
• Nguyên nhân: Đây là một lỗi phức tạp, thường do một trong các nguyên nhân sau: (a) Cấu hình S3/MinIO giữa LobeChat và dịch vụ Auth không đồng bộ; (b) Khóa API cho dịch vụ embedding (mặc định là OpenAI) bị thiếu, sai, hoặc không có quyền truy cập mô hình embedding.
• Giải pháp:
  1. Kiểm tra cấu hình S3/MinIO: Xác minh lại toàn bộ chuỗi cấu hình. Đảm bảo Access Key và Secret Key trong tệp .env của LobeChat khớp chính xác với thông tin đăng nhập của MinIO. Kiểm tra cấu hình S3 provider trong giao diện quản trị của Casdoor/Logto. Đảm bảo bucket đã được tạo trên MinIO và có chính sách (policy) cho phép truy cập.
  2. Kiểm tra API Key Embedding: Đảm bảo biến OPENAI_API_KEY trong tệp .env là chính xác và có đủ quyền để truy cập mô hình embedding (ví dụ: text-embedding-3-small).

Vấn đề về hiệu suất và tài nguyên

• Vấn đề: Ứng dụng chạy rất chậm, giao diện bị treo hoặc không phản hồi trên các máy chủ ảo (VPS) có cấu hình thấp.
• Nguyên nhân: Thiếu tài nguyên hệ thống, đặc biệt là RAM và CPU, khi chạy toàn bộ stack nâng cao.
• Giải pháp:
  1. Tham khảo lại Bảng 2 về yêu cầu hệ thống và xem xét nâng cấp máy chủ của bạn.
  2. Sử dụng lệnh docker stats để xác định container nào đang tiêu thụ nhiều tài nguyên nhất.
  3. Giảm tải bằng cách tắt các plugin không cần thiết trong cài đặt của LobeChat.

Lỗi Casdoor/Logto không khởi động hoặc tự động tắt

• Vấn đề: Container của dịch vụ xác thực (Casdoor hoặc Logto) tự động thoát ngay sau khi khởi động hoặc sau một thời gian ngắn.
• Nguyên nhân: Có hai nguyên nhân chính: (a) Thiếu chỉ thị restart: always trong định nghĩa service của Casdoor/Logto trong tệp docker-compose.yml, đặc biệt là với các tệp được tạo bởi các phiên bản script cài đặt cũ; (b) Lỗi cấu hình kết nối đến cơ sở dữ liệu PostgreSQL.
• Giải pháp:
  1. Mở tệp docker-compose.yml và thêm dòng restart: always vào dưới định nghĩa service của Casdoor/Logto.
  2. Kiểm tra log của container Casdoor/Logto (docker compose logs -f casdoor) để xem có thông báo lỗi chi tiết nào liên quan đến việc kết nối database không. Đảm bảo chuỗi kết nối trong cấu hình của Casdoor/Logto là chính xác.