Proxyma Home Server

Ứng dụng một người dùng cho máy không có màn hình - máy chủ gia đình, NAS, VPS nhỏ - truy cập được từ phần còn lại của mạng nội bộ.

Đây chính là ứng dụng desktop, chỉ đóng gói theo cách khác

Vẫn là ứng dụng giống hệt bộ cài đặt cho Windows và gói cài đặt cho Linux: một người, không tài khoản, không đăng nhập. Nhà cung cấp AI, bộ kết nối và cấp phép hoạt động như tài liệu hướng dẫn bản desktop mô tả. Trang này nói về cài đặt, ai được phép truy cập, và thêm tài liệu - phần hoạt động khác đi ở đây.

Bạn cần gói nào

Bạn muốn	Hãy cài
Dùng Proxyma ngay trên chiếc máy trước mặt bạn	Bản Desktop - bộ cài đặt cho Windows hoặc gói cài đặt cho Linux
Chạy trên một máy không màn hình và dùng nó từ máy tính xách tay của bạn	Trang này
Cấp cho nhiều người những tài khoản riêng	Proxyma Enterprise Server - một sản phẩm khác, được cấp phép trực tiếp cùng chúng tôi

Cả hai gói máy chủ đều chạy trong container. Home Server dành cho một người: không có cơ sở dữ liệu phải vận hành, không tài khoản và không đăng nhập.

Yêu cầu hệ thống

Thành phần	Yêu cầu
Docker Engine	Phiên bản 24 trở lên, kèm phần mở rộng `docker compose`
Bộ nhớ	4 GB cho container
Dung lượng đĩa	20 GB cộng với phần mà tài liệu được lập chỉ mục của bạn cần
CPU	Tối thiểu 2 lõi

Không cần gì thêm: Java, Python, OCR và kho vector đều nằm sẵn trong image. Mọi thứ bản cài đặt lưu giữ đều nằm trong một thư mục bên cạnh tệp compose.

Office Files (profile office, bật sẵn) thêm một container nhỏ được dựng trên máy chủ và cần internet một lần. Hãy bỏ office khỏi COMPOSE_PROFILES trên máy chủ không có internet.

Cài đặt

Hãy chạy các lệnh này trên chính máy sẽ chạy Proxyma, không phải trên máy tính xách tay của bạn:

curl -LO https://github.com/proxyma-ai/proxyma-releases/releases/download/v<version>/proxyma-homeserver-<version>-compose.tar.gz
tar -xzf proxyma-homeserver-<version>-compose.tar.gz
cd proxyma-homeserver-<version>
./install.sh

Lần chạy đầu tiên ghi ra tệp .env rồi dừng lại.
Thiết lập ai được phép truy cập trong .env (phần tiếp theo).
Chạy lại ./install.sh.
Mở Proxyma trong trình duyệt. Không có tài khoản nào phải tạo và không có mật khẩu nào phải đặt.

Để áp dụng mọi thay đổi cấu hình về sau, hãy chạy lại ./install.sh.

Ai được phép truy cập

Không có đăng nhập, bởi vì không có tài khoản

Ai truy cập được cổng này là có mọi tài liệu bạn lập chỉ mục, mọi cuộc trò chuyện, và cả khoản chi cho nhà cung cấp AI của bạn.

Hai thiết lập trong .env quyết định điều này, và cả hai phải khớp nhau:

Thiết lập	Nó làm gì
`BIND_ADDR`	Công bố cổng ra ngoài. `0.0.0.0` đưa cổng ra mạng của bạn; `127.0.0.1` giữ nó trong phạm vi chiếc máy.
`PROXYMA_ALLOWED_HOSTS`	Những tên máy mà Proxyma sẽ trả lời. Để trống nghĩa là chỉ loopback, và đó là mặc định.

PROXYMA_ALLOWED_HOSTS=homeserver.lan
PROXYMA_ALLOWED_HOSTS=homeserver.lan,192.168.1.50
PROXYMA_ALLOWED_HOSTS=*

Công bố cổng mà không khai báo tên máy của bạn thì mọi yêu cầu đều nhận về 403. install.sh in ra cả hai thiết lập ở mỗi lần chạy.

Danh sách này không phải tường lửa: nó chặn tấn công DNS rebinding từ các trang web đang mở trong trình duyệt của bạn. * tắt bước kiểm tra đó - chỉ dùng khi có một thành phần đứng trước Proxyma quyết định ai được đi qua.

Truy cập từ bên ngoài nhà bạn

Một đường hầm (tunnel) (khuyến nghị) - Tailscale, WireGuard, hoặc ssh -L 4246:localhost:4246. Qua ssh -L, không cần thay đổi gì trong .env. Với Tailscale hoặc WireGuard, hãy thêm tên máy hoặc địa chỉ bạn gõ vào PROXYMA_ALLOWED_HOSTS.
Một reverse proxy công khai trên internet. Đặt PROXYMA_ALLOWED_HOSTS là tên miền của bạn. Proxy bắt buộc phải yêu cầu đăng nhập riêng - Proxyma không có đăng nhập, nên thiếu bước đó thì tài liệu của bạn bị công khai.

Hai thứ tự động tắt đi khi máy chủ được công bố ra ngoài

Cả hai đều không bị hạn chế trên loopback và vẫn tắt khi máy chủ trả lời cho bất kỳ tên máy nào khác. Không thứ nào cần thiết để dùng Proxyma từ trình duyệt.

Thiết lập	Bật nó lên sẽ mở ra điều gì
`PROXYMA_EXPOSE_LOCAL_FILE_API`	Trên gói này, chỉ có điểm kết nối dừng Proxyma. Trình duyệt thư mục mà nó bảo vệ trên ứng dụng desktop không được đưa vào, và tài liệu ở đây được tải lên.
`PROXYMA_EXPOSE_MCP`	Điểm kết nối MCP, không cần xác thực: một máy khách AI có được các công cụ của tác nhân (agent), kể cả những công cụ ghi vào Jira, Confluence và Bitbucket bằng thông tin đăng nhập bạn đã lưu, khi giấy phép của bạn có các bộ kết nối đó.

Thêm tài liệu

Không có hộp thoại chọn thư mục. Bạn tải tài liệu lên và Proxyma giữ một bản sao của riêng nó.

Mở Proxyma trong trình duyệt và vào mục Nguồn dữ liệu.
Chọn Kết nối, rồi Tải tệp tin lên.
Kéo thả một tệp hoặc cả một thư mục vào.

Tệp tải lên được lưu và lập chỉ mục dưới ./data/uploads, và được sao lưu cùng ./data.

Xóa một nguồn dữ liệu vẫn giữ lại tệp của nó

Gỡ một nguồn dữ liệu sẽ gỡ nó khỏi chỉ mục. Các tệp đã tải lên vẫn nằm trong data/uploads cho tới khi bạn xóa chúng.

Vận hành hằng ngày

docker compose logs -f proxyma   # xem nhật ký
docker compose ps                # xem trạng thái
docker compose down              # dừng lại
./install.sh                     # áp dụng một thay đổi cấu hình

Sao lưu

./data là toàn bộ bản cài đặt - cơ sở dữ liệu, chỉ mục tìm kiếm, kho vector, các cuộc trò chuyện và các thiết lập.

Dừng container.
Sao chép ./data.
Khởi động lại.

Để chỉ sao chép các thiết lập sang một bản cài đặt khác, hãy dùng Cài đặt → Nhập & Xuất dữ liệu.

Nâng cấp

docker compose pull proxyma
./install.sh

Nếu bạn đã ghim phiên bản trong PROXYMA_IMAGE, hãy đổi nó thành phiên bản mới trước.

Kiểm tra image do Proxyma phát hành

Mọi image của bản phát hành đều được ký. Khi đã cài cosign:

cosign verify --key https://proxyma.ai/keys/cosign-release.pub ghcr.io/proxyma-ai/proxyma-homeserver:<version>

Xử lý sự cố

Mọi yêu cầu đều trả về 403

Tên máy bạn gõ không có trong PROXYMA_ALLOWED_HOSTS. homeserver, homeserver.lan và địa chỉ IP là các tên khác nhau.

Nó trả lời ngay trên máy đó nhưng không trả lời từ nơi khác

Hoặc BIND_ADDR đang là 127.0.0.1, hoặc tường lửa của máy chủ đang chặn cổng. docker compose ps cho biết những cổng nào đang được công bố.

Tìm kiếm không ra kết quả nào, và nhật ký có nhắc tới ChromaDB

Kho vector không khởi động được. Hãy chạy docker compose logs proxyma | grep -i chroma và xem ./data/.local/share/proxyma/logs/chromadb.log. Khi lỗi này còn đó, việc lập chỉ mục trông vẫn thành công nhưng không tìm thấy được gì.

Lần khởi động đầu tiên mất hơn một phút

Bình thường. Kho vector khởi động trước khi cổng web được mở.