Jak samodzielnie hostować Octop na własnym VPS

Czym jest Octop i dlaczego warto hostować go samodzielnie

Octop to samodzielnie hostowany asystent AI dla gospodarstwa domowego lub małego zespołu. Powodem, dla którego warto hostować Octop zamiast zwykłego interfejsu czatu, jest izolacja użytkowników. Open WebUI zapewnia interfejs przeglądarkowy dla modelu. Octop dodaje konta z rolą administratora, prywatną przestrzeń roboczą i zestaw poświadczeń dla każdego użytkownika oraz bibliotekę wyspecjalizowanych agentów, między którymi użytkownik może przełączać się w zależności od zadania. Jest to różnica, która pozwala jednemu VPS obsłużyć pięć osób zamiast jednej.

Projekt znajduje się pod adresem github.com/TencentCloud/Octop. Jest to pojedynczy proces obsługujący pulpit nawigacyjny WWW, interfejs wiersza poleceń, kanały czatu (Feishu, DingTalk, QQ, Discord, WeCom) oraz zaplanowane zadania, a wszystko to wspierane przez pojedynczą bazę danych SQLite w ~/.octop/. Całość poniżej została przygotowana dla wersji v0.9.19, wydanej 5 sierpnia 2026 roku. Jeśli nadal wybierasz między platformami, porównanie alternatyw Open WebUI, które można uruchomić na VPS obejmuje szerszy zakres rozwiązań.

Jedna kwestia wymaga wyjaśnienia, zanim poświęcisz na to wieczór. W momencie pisania tego przewodnika Octop był oprogramowaniem w wersji przed 1.0, opublikowanym przez organizację dostawcy na GitHubie, posiadającym około 900 gwiazdek w sierpniu 2026 roku. Od tego czasu, 14 września 2026 roku, oznaczono wersję v1.0.0, a według stanu na 20 października 2026 roku najnowszym tagiem jest v1.0.2 – stabilne wydanie opublikowane 18 października 2026 roku po serii wersji beta 1.0.2, z repozytorium posiadającym około 10 400 gwiazdek. Poniższe kroki zostały przygotowane dla wersji v0.9.19 i nie były ponownie testowane na wersji 1.x. Projekt rozwija się szybko, co potwierdzają numery wersji, a zawarte tu informacje nie stanowią gwarancji stabilnej ścieżki aktualizacji. Przypinaj wersje (tagi), czytaj dziennik zmian i wykonuj kopie zapasowe.

Wymagania wstępne

• Serwer VPS z systemem Ubuntu 24.04, silnikiem Docker Engine oraz wtyczką Compose. Jeśli nie znasz Compose, zacznij od podstaw Docker Compose dla VPS.
• git, ponieważ zamiast pobierać obraz, sprawdzisz konkretną wersję (tag) wydania.
• Nazwa domeny wskazująca na serwer VPS, ponieważ wymagane jest zabezpieczenie TLS (transport layer security) przed usługą.
• Backend modelu obsługujący API OpenAI: lokalna instancja Ollama, własna bramka lub płatny klucz API.

Sam Octop jest lekki. To proces w języku Python oraz plik bazy danych SQLite. Obciążenie wynika z backendu modelu, więc jeśli planujesz uruchomić model na tej samej maszynie, dobierz parametry serwera do wymagań modelu.

Dlaczego nie zalecamy instalatora curl

Plik README rozpoczyna się od instalacji jednowierszowej:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

Nie zalecamy tego rozwiązania na serwerach produkcyjnych z jednego konkretnego powodu: skrypt ten nie znajduje się w repozytorium. Jest on serwowany z zasobnika Tencent Cloud Object Storage. Żaden jego element nie jest objęty tagiem git ani commitem, więc nie można porównać dzisiejszej wersji skryptu z wersją sprzed tygodnia, a historia zmian nie istnieje. Zasobnik może jutro serwować inną zawartość, a projekt nie odnotuje tego faktu. Przekierowanie wyniku bezpośrednio do bash oznacza również, że maszyna wykonuje skrypt, zanim użytkownik przeczyta choćby jedną jego linię.

Instalator zapisuje również dane bezpośrednio w systemie hosta, zamiast w kontenerze. Używa uv do pobrania Python 3.12 i zbudowania środowiska, o którym menedżer pakietów nie posiada żadnych informacji, przez co późniejsze usunięcie instalacji wymaga ręcznej pracy.

Istnieją dwie lepsze opcje. Pobranie skryptu, przeczytanie go, a następnie uruchomienie, co zajmuje trzydzieści sekund: curl -fsSL <url> -o install.sh, następnie less install.sh, a potem bash install.sh. Można również użyć Docker, co stanowi przedmiot dalszej części tego przewodnika. Pakiet PyPI (pip install octop) jest przynajmniej wersjonowanym artefaktem, który można przypiąć do konkretnego wydania.

Wdrożenie Octop przy użyciu Docker Compose, wersja v0.9.19

Plik Compose dostarczony w wersji v0.9.19 buduje obraz z repozytorium, dlatego w tym przewodniku przypięcie wersji oznacza sprawdzenie tagu git. Opublikowane obrazy istnieją. Drzewo v0.9.19 zawiera już workflow docker-publish.yml, dodany w wersji v0.9.8 w dniu 15 lipca 2026, który buduje obraz i przesyła go do Docker Hub dla każdego tagu v*. Od 20 października 2026 projekt publikuje również w rejestrze kontenerów GitHub (docker pull ghcr.io/tencentcloud/octop:1.0.2). Budowanie z pobranego tagu jest nadal bezpieczniejszym przypięciem, ponieważ kompilowany jest dokładnie ten kod, który został przejrzany, zamiast polegać na tagu z rejestru. Jest to krok dalej niż w przypadku większości projektów self-hosted, ponieważ na przykład własna instancja AFFiNE przypina się do tagu opublikowanego obrazu i nie buduje niczego na VPS. Procedura klonowania, checkoutu i budowania poniżej jest taka sama, jak ta, którą opisuje przewodnik wdrożenia openGym, więc jeśli konfiguracja ta została już wykonana, jej schemat jest znany.

git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19

Oto usługa zdefiniowana w pliku, ograniczona do istotnych elementów:

services:
  octop:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: octop:latest
    container_name: octop
    restart: unless-stopped
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
    environment:
      - HOME=/data
      - OCTOP_BIND_HOST=0.0.0.0
      - OCTOP_PORT=${OCTOP_PORT:-8088}
      - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
      - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

Zwróć uwagę na blok build:. image: octop:latest to nazwa, którą otrzymuje własna kompilacja, a nie odniesienie do rejestru, więc latest oznacza tutaj to, co zostało skompilowane jako ostatnie. Ustaw ścieżkę danych na konkretną lokalizację zamiast pozostawiać wartość domyślną i nadaj kontu administratora rzeczywiste hasło przed pierwszym uruchomieniem. Umieść to w docker/.env:

OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-data

Jedna pułapka jest warta więcej uwagi niż reszta pliku. Compose odczytuje docker/.env tylko w celu interpolacji symboli zastępczych ${...} w pliku YAML. Klucz dodany do tego pliku nie trafi do kontenera, chyba że zostanie również wymieniony w sekcji environment: w pliku Compose. Dodanie OCTOP_ACCESS_TOKEN_TTL tylko do .env nie przyniesie żadnego efektu, bez żadnego komunikatu. Alternatywą jest wpisanie tych samych kluczy do ~/.octop/env wewnątrz zamontowanego katalogu danych, który Octop wczytuje przy starcie. Przewodnik po plikach env i sekretach w Docker Compose wyjaśnia, dlaczego te dwa mechanizmy nie są tożsame.

Zbuduj i uruchom:

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/health

Poprawnie działająca instancja odpowiada na health check obiektem JSON w formacie {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0}. W przypadku innego wyniku, przed otwarciem przeglądarki sprawdź docker compose -f docker/docker-compose.yml logs -f octop.

Teraz nadaj właśnie zbudowanemu obrazowi znaczącą nazwę, ponieważ następne polecenie --build nadpisze octop:latest i nie będzie możliwości rozróżnienia tych dwóch elementów:

docker image tag octop:latest octop:0.9.19

Pierwsze uruchomienie wykonuje octop init i zapisuje początkowe dane uwierzytelniające w wolumenie danych:

docker exec -it octop cat /data/.octop/credential.txt

Wartości domyślne to admin / octop i są one stosowane tylko przy pierwszej inicjalizacji. Jest to mechanizm stojący za często zadawanym pytaniem: zmiana OCTOP_DEFAULT_PASSWORD po pierwszym uruchomieniu kontenera nie przynosi efektu, ponieważ konto już istnieje. Hasło należy zmienić w panelu administracyjnym.

Nie publikuj portu 8088

Linia ports: powyżej wiąże usługę ze wszystkimi interfejsami na VPS. W momencie uruchomienia kontenera pulpit nawigacyjny jest dostępny w publicznym Internecie przez nieszyfrowane połączenie, z domyślnym hasłem. Domyślna wartość OCTOP_BIND_HOST w Octop to 127.0.0.1; plik Compose nadpisuje ją na 0.0.0.0, ponieważ proces musi akceptować ruch spoza własnej przestrzeni nazw sieciowych. To nadpisanie jest poprawne. Częścią wystawiającą usługę na zewnątrz jest publikacja portu.

Edytuj linię ports: w pliku docker/docker-compose.yml, aby mapowanie nasłuchiwało wyłącznie na interfejsie zwrotnym (loopback):

    ports:
      - "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

Nie próbuj naprawiać tego za pomocą zwykłego pliku nadpisującego (override). Compose łączy listy ports z wielu plików zamiast je zastępować, co skutkuje publikacją obu mapowań, a drugie z nich nie zostanie powiązane z portem. Jeśli chcesz zachować oryginalny plik dostawcy w niezmienionej formie, użyj znacznika !override przy sekwencji, co jest udokumentowanym sposobem na zastąpienie, a nie dołączenie danych. Wyjaśnienie sposobu łączenia wielu plików przez Compose zawiera szczegóły tych reguł.

Powiązanie z interfejsem zwrotnym rozwiązuje również problem, który w przeciwnym razie wystąpiłby w konfiguracji firewalla. Docker zapisuje reguły publikowanych portów w tablicy nat przed łańcuchami zarządzanymi przez ufw, dlatego ufw deny 8088 nie blokuje portu opublikowanego kontenera. W Docker Engine 28.0.0 lub nowszym port powiązany z 127.0.0.1 nie jest osiągalny z zewnątrz, niezależnie od konfiguracji ufw, co czyni to rozwiązanie właściwym, a nie tylko alternatywnym. Starsze wersje Engine pozwalają hostom w tym samym segmencie L2, na przykład innym maszynom w przełączniku dostawcy, na dostęp do portów opublikowanych na localhost, dlatego uruchom docker version i zaktualizuj oprogramowanie, jeśli serwer zgłasza wersję niższą niż 28.

Wdrożenie TLS za pomocą reverse proxy

Caddy stanowi najkrótszą drogę, ponieważ samodzielnie żąda certyfikatu za pośrednictwem ACME (automatic certificate management environment) i obsługuje proxy dla WebSockets bez dodatkowej konfiguracji:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx wymaga większej uwagi, ponieważ Octop przesyła czat przez WebSocket:

server {
    listen 443 ssl;
    server_name octop.example.com;

    ssl_certificate     /etc/letsencrypt/live/octop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Każda linia w tym bloku pełni określoną funkcję. Czat działa przez WS /api/agents/{id}/chat/ws, więc bez proxy_http_version 1.1 oraz dwóch nagłówków upgrade, nginx odpowiada na próbę aktualizacji połączenia błędem 400 Bad Request: pulpit nawigacyjny ładuje się poprawnie, ale każda wysłana wiadomość zawiesza się bez wyświetlenia błędu na stronie. proxy_buffering off jest istotne, ponieważ punkt końcowy wznawiania z udziałem człowieka (human-in-the-loop) zwraca text/event-stream, a zdarzenia SSE (server-sent events) przetrzymywane w buforze proxy docierają jako jeden blok danych na końcu, zamiast być przesyłane strumieniowo. proxy_read_timeout obejmuje długotrwałe uruchomienia narzędzi, ponieważ domyślny limit 60 sekund przerywa działanie agenta w trakcie zadania i powoduje zapisanie w logach upstream timed out (110: Connection timed out).

Zachowanie uwierzytelniania JWT za proxy

Octop uwierzytelnia się za pomocą tokena typu bearer, a nie pliku cookie. POST /api/auth/login zwraca {access_token, role, user, ...}, a kolejne wywołania zawierają Authorization: Bearer <access_token>. Dla reverse proxy jest to korzystne: nie występuje domena cookie, flaga Secure ani reguła SameSite, które można błędnie skonfigurować, więc sesja działająca na http://127.0.0.1:8088 zachowuje się identycznie na https://octop.example.com.

Przed udostępnieniem usługi użytkownikom warto znać dwa następstwa tego rozwiązania.

WebSocket przenosi token w adresie URL. Punktem końcowym jest WS /api/agents/{id}/chat/ws?token=<jwt>, ponieważ JavaScript w przeglądarce nie może ustawić nagłówka Authorization podczas nawiązywania połączenia WebSocket. TLS chroni ten token w trakcie przesyłania. Nie chroni go jednak przed własnymi logami: nginx domyślnie zapisuje pełną linię żądania, w tym ciąg zapytania, do access_log, więc działający token rzeczywistego użytkownika trafia do pliku tekstowego na serwerze. Należy logować ścieżkę bez argumentów. $uri to znormalizowana ścieżka z usuniętym ciągiem zapytania, dlatego należy umieścić ją w bloku http i odwołać się do niej z poziomu serwera:

log_format octop_noargs '$remote_addr [$time_local] '
                        '"$request_method $uri $server_protocol" '
                        '$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;

Brak wylogowania dla pojedynczej sesji. OCTOP_ACCESS_TOKEN_TTL domyślnie wynosi 86400, więc token pozostaje ważny przez 24 godziny od momentu zalogowania. Jedynym udokumentowanym sposobem na unieważnienie tokena jest octop admin rotate-jwt-secret, co powoduje rotację klucza podpisywania przechowywanego w ~/.octop/secrets/jwt_secret i natychmiastowe unieważnienie wszystkich aktywnych tokenów dla każdego użytkownika. W przypadku odejścia członka zespołu procedura wygląda następująco: usunięcie użytkownika, rotacja klucza, a następnie polecenie pozostałym użytkownikom ponownego zalogowania się. Jeśli jest to zbyt uciążliwe, należy skrócić czas życia tokena, pamiętając o dodaniu zmiennej zarówno do listy environment:, jak i .env:

OCTOP_ACCESS_TOKEN_TTL=28800

Ataki typu brute force są obsługiwane: OCTOP_LOGIN_MAX_ATTEMPTS domyślnie wynosi 5 nieudanych prób, a OCTOP_LOGIN_LOCKOUT_SECONDS 900, więc zablokowany użytkownik czeka piętnaście minut, zamiast widzieć niedziałającą instalację. Octop posiada własną bazę użytkowników i w wersji v0.9.19 nie wspiera OIDC, więc w przypadku potrzeby wdrożenia pełnego SSO należy umieścić przed nim proxy uwierzytelniające, do czego służy samodzielnie hostowany serwer Authentik.

Skierowanie Octop na backend modelu

Dostawcy są konfigurowani dla każdego agenta w panelu sterowania, a octop provider list wskazuje aktualne ustawienia. Octop dostarcza gotowe presety dla API zgodnych z OpenAI, DashScope (Qwen) oraz Ollama, a dane uwierzytelniające są przechowywane w tabeli providers własnej bazy danych SQLite. Wybór ten wpływa na koszty oraz na to, jakie dane opuszczają serwer.

Model lokalny z Ollama. Żadne dane nie opuszczają serwera, a koszt stanowi zużycie pamięci RAM zamiast opłat za tokeny. Szczegół konfiguracyjny, który często sprawia trudności: kontener nie może połączyć się z usługą Ollama na hoście pod adresem 127.0.0.1:11434, ponieważ adres ten jest pętlą zwrotną (loopback) samego kontenera. Należy dodać wpis host gateway do usługi:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Następnie należy ustawić bazowy adres URL dostawcy na http://host.docker.internal:11434/v1, który jest ścieżką Ollama zgodną z OpenAI, oraz wprowadzić dowolny niepusty ciąg znaków w polu klucza API. Ollama ignoruje to pole, jednak klienci OpenAI odmawiają wysłania żądania z pustym kluczem. Aby to zadziałało, Ollama musi również nasłuchiwać poza interfejsem loopback, co wymaga dodania OLLAMA_HOST=0.0.0.0:11434 do jednostki systemd. Jest to ryzykowne rozwiązanie: Ollama nie posiada wbudowanego uwierzytelniania, więc otwarcie portu 11434 na publicznym adresie IP udostępnia serwer modelu każdemu, kto go przeskanuje. Należy zezwolić wyłącznie na ruch z prywatnej podsieci Dockera, sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp, a pozostały ruch blokować. Artykuł Uruchamianie Ollama na VPS omawia dobór rozmiaru modelu, a porównanie Ollama i vLLM wyjaśnia, kiedy Ollama przestaje być odpowiednim serwerem.

Dodatkowe ostrzeżenie dotyczące modeli lokalnych, ponieważ problem ten często bywa błędnie uznawany za błąd w Octop. Agenci działają poprzez wywoływanie narzędzi, a prompt systemowy wraz z definicjami narzędzi i historią tworzą długi prompt. Ollama obsługuje modele z niewielkim domyślnym oknem kontekstowym, przez co początek promptu, gdzie znajdują się definicje narzędzi, wypada poza okno. W rezultacie model przestaje wywoływać narzędzia lub wymyśla nieistniejące. Należy zwiększyć num_ctx do 16k lub 32k i wybrać model, który dobrze radzi sobie z wywoływaniem funkcji (function calling). Odpowiedź urywająca się w połowie zdania to inny problem, związany z ustawieniem num_predict. Jeśli odpowiedzi są ucinane, warto sprawdzić, gdzie ustawiono num_predict oraz co zwraca done_reason, zanim wina zostanie przypisana agentowi. Jeśli wolisz zacząć od konkretnego kandydata zamiast krótkiej listy, warto wypróbować Nemotron 3.5 Lightning; wspomniany opis zawiera dokładny tag do pobrania, wymagania dotyczące pamięci RAM oraz informację, czy praca na samym procesorze (CPU) jest wystarczająca.

Własna bramka (gateway). Umieszczenie własnej bramki LiteLLM między Octop a resztą usług pozwala uzyskać jeden bazowy adres URL, osobne klucze dla każdego użytkownika, limity wydatków oraz centralne logowanie. Można również zmieniać model w tle bez edycji jakichkolwiek ustawień w Octop.

Płatne API. Najwyższa jakość przy uczciwym kompromisie: treść konwersacji opuszcza serwer i trafia do dostawcy, co jest przeciwieństwem głównego celu self-hostingu. Klucz należy umieścić w docker/.env jako OPENAI_API_KEY, co jest już obsługiwane przez plik Compose.

Niezależnie od wyboru, plik Compose przekazuje również OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY oraz LANGFUSE_BASE_URL, dzięki czemu można wysyłać ślady (traces) do własnej instancji Langfuse i obserwować rzeczywiste działania agentów, zamiast zgadywać na podstawie okna czatu.

Użytkownicy, role i współdzielona biblioteka agentów

Konto administratora utworzone podczas pierwszego uruchomienia zarządza pozostałymi kontami. Każdy użytkownik otrzymuje własnych agentów, przestrzeń roboczą oraz poświadczenia, a izolacja jest utrzymywana za pomocą tokena przechowywanego w przeglądarce. Obok nich znajduje się wspólna pula umiejętności i podagentów dostępna dla wszystkich użytkowników. Jest to funkcja, która uzasadnia wdrożenie rozwiązania w środowisku domowym: jedna osoba tworzy skutecznego agenta badawczego, a pozostali użytkownicy nie muszą powtarzać tego procesu.

Należy zachować ostrożność w kwestii narzędzi. Octop oferuje funkcje zatwierdzania narzędzi oraz mechanizmy ochronne dla poleceń powłoki. Obie funkcje działają zgodnie z przeznaczeniem, jednak agent wykonujący polecenia powłoki uruchamia je wewnątrz kontenera Octop z zamontowanym wolumenem danych użytkownika. Mechanizmy ochronne ograniczają skutki nieprzemyślanych zapytań, ale nie stanowią pełnej izolacji typu sandbox. Z tego względu należy pozostawić włączoną funkcję zatwierdzania narzędzi dla każdego użytkownika, któremu nie powierzono by bezpośredniego dostępu do powłoki systemowej. W przypadku porównywania tego rozwiązania z innymi opcjami, zestawienie samodzielnie hostowanych agentów AI przedstawia sposób, w jaki poszczególne narzędzia radzą sobie z tym zagadnieniem.

Aktualizacja projektu o tak szybkim cyklu wydawniczym

[
  {
    "version": "v0.9.16",
    "days_since_previous_release": 2
  },
  {
    "version": "v0.9.17",
    "days_since_previous_release": 3
  },
  {
    "version": "v0.9.18",
    "days_since_previous_release": 1
  },
  {
    "version": "v0.9.19",
    "days_since_previous_release": 3
  }
]

Powyższe daty tagów pochodzą z repozytorium i są aktualne na dzień 7 sierpnia 2026. W ciągu dziewięciu dni opublikowano 4 wersji, przy czym najkrótsza przerwa między nimi wyniosła 1 dzień, a wersja v0.9.19 pojawiła się 3 dni po poprzednim tagu. Takie tempo świadczy o dobrej kondycji projektu, ale jest złym powodem do uruchamiania latest. Przed pobraniem zmian należy zapoznać się z listą modyfikacji:

cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"

Przed przełączeniem się na konkretny tag należy sprawdzić, co faktycznie zawiera $NEW_TAG, ponieważ projekt oznacza wersje beta, takie jak v1.0.2b9, na równi ze stabilnymi wydaniami. Na dzień 20 października 2026 najnowszym tagiem jest stabilne wydanie v1.0.2, opublikowane 18 października 2026. Przeskok z wersji v0.9.19 obejmuje wydanie v1.0.0 z 14 września 2026, więc dziennik zmian jest długi i wymaga dokładnej analizy.

Zawsze należy najpierw wykonać kopię zapasową, ponieważ migracje bazy danych uruchamiane są przy starcie, a nieudana migracja w projekcie o tak szybkim cyklu wydawniczym wymaga ręcznej naprawy:

docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml start

Następnie należy przełączyć się na nowy tag i przebudować projekt za pomocą docker compose -f docker/docker-compose.yml up -d --build. W razie niepowodzenia powrót do starego tagu i ponowna kompilacja przywróci kod, ale tylko archiwum tarball pozwoli odzyskać bazę danych.

Archiwum to zawiera octop.db, config.json, klucz podpisywania JWT oraz credential.txt, dlatego jest równie wrażliwe jak sam serwer. Należy ustawić uprawnienia na 600 i przechowywać kopię poza serwerem. W przypadku większych instalacji projekt udostępnia również docker/docker-compose.postgres.yml, który uruchamia PostgreSQL z rozszerzeniem pgvector zamiast SQLite.

Tryby awarii i towarzyszące im komunikaty

Kontrola stanu nie odpowiada. curl http://127.0.0.1:8088/api/health zawiesza się lub odrzuca połączenie. Należy zapoznać się z docker compose -f docker/docker-compose.yml logs -f octop. Kontener, który kończy działanie podczas pierwszej inicjalizacji, zazwyczaj nie ma uprawnień do zapisu w katalogu danych, dlatego należy sprawdzić właściciela ścieżki wskazanej w OCTOP_DATA.

Panel ładuje się, ale czat zawiesza. Brak błędów na stronie, brak odpowiedzi. Należy otworzyć konsolę przeglądarki i sprawdzić, czy wystąpił błąd połączenia z wss://octop.example.com/api/agents/.../chat/ws. Proxy nie przekazuje żądania upgrade. Należy dodać proxy_http_version 1.1 oraz nagłówki Upgrade i Connection.

Cała odpowiedź pojawia się naraz, z kilkusekundowym opóźnieniem. Streaming działa, ale włączone jest buforowanie. Należy ustawić proxy_buffering off.

bind: address already in use. Port 8088 jest już zajęty. sudo ss -tlnp | grep 8088 wskazuje proces, który go używa. Taki sam komunikat pojawia się w przypadku dodania drugiego wpisu ports w pliku override zamiast edycji oryginału.

Poprawne hasło jest odrzucane. Pięć nieudanych prób powoduje blokadę na 900 sekund. Należy odczekać czas blokady zamiast reinstalować usługę.

Nowe hasło w .env nie przyniosło efektu. Te dane uwierzytelniające mają zastosowanie tylko podczas pierwszej inicjalizacji. Hasło należy zmienić z poziomu panelu.

Agent odpowiada, ale nie uruchamia narzędzia. Jest to niemal zawsze problem z lokalnym modelem: okno kontekstowe jest zbyt małe dla definicji narzędzi lub model słabo radzi sobie z wywoływaniem funkcji (function calling). Należy zwiększyć num_ctx i przetestować model stworzony do obsługi narzędzi.

FAQ

Czy Octop zastępuje Open WebUI?

Tylko jeśli potrzebujesz funkcji, które dodaje. Open WebUI to interfejs czatu dla modelu, który sprawdza się w przypadku jednej osoby lub zaufanego gospodarstwa domowego. Octop dodaje konta z rolą administratora, obszary robocze i poświadczenia dla poszczególnych użytkowników oraz bibliotekę specjalistycznych agentów, dzięki czemu kilka osób może korzystać z jednego serwera bez współdzielenia historii. Jeśli jedno konto jest wystarczające, Open WebUI jest prostszym i znacznie bardziej dojrzałym wyborem.

Dlaczego nie należy używać skryptu instalacyjnego curl dla Octop?

Skrypt jest udostępniany z zasobnika Tencent Cloud Object Storage, a nie z repozytorium, więc nie jest objęty żadnym tagiem ani commitem git. Nie można porównać jego obecnego działania z tym sprzed tygodnia, a przesyłanie go potokiem do bash uruchamia go przed przeczytaniem. Ponadto instaluje się on na hoście we własnym środowisku Python 3.12, poza menedżerem pakietów. Należy go pobrać i przeczytać przed uruchomieniem lub wdrożyć za pomocą Docker Compose z pobranego tagu.

Czy Octop może korzystać z modelu lokalnego zamiast płatnego API?

Tak. Octop obsługuje API zgodne z OpenAI i zawiera gotowe ustawienia dla Ollama, więc wskazanie na http://host.docker.internal:11434/v1 zadziała po dodaniu extra_hosts: ["host.docker.internal:host-gateway"] do kontenera i ustawieniu OLLAMA_HOST=0.0.0.0:11434 na hoście. Należy ograniczyć port 11434 firewallem do zakresu adresów Docker, ponieważ Ollama nie posiada własnego mechanizmu uwierzytelniania. Należy zwiększyć num_ctx w Ollama do 16k lub więcej, ponieważ prompty agentów z definicjami narzędzi przekraczają domyślne okno kontekstowe, co powoduje, że model przestaje wywoływać narzędzia.

Czy potrzebuję reverse proxy, czy mogę otworzyć port 8088?

Potrzebujesz proxy. Dostarczony plik Compose dla Octop publikuje port 8088 na wszystkich interfejsach bez TLS, co oznacza, że hasła i tokeny bearer byłyby przesyłane przez Internet otwartym tekstem. Zmień publikowany port na 127.0.0.1:8088:8088 i umieść przed nim Caddy lub nginx z certyfikatem. W przypadku nginx należy przekazać nagłówki WebSocket upgrade i ustawić proxy_buffering off, w przeciwnym razie strona się załaduje, ale czat nie będzie odpowiadał.

Czy Octop jest gotowy do pracy produkcyjnej?

Przed wersją 1.0 projekt publikował kilka otagowanych wydań tygodniowo (stan na sierpień 2026). Wersja v1.0.0 została otagowana 14 września 2026, a następnie wydano serię bet v1.0.2 przed stabilną wersją v1.0.2 w dniu 18 października 2026. Tempo rozwoju jest nadal wysokie, więc należy traktować oprogramowanie jako obiecujące, a nie ustabilizowane. Jest to akceptowalne dla rodziny lub małego zespołu wewnętrznego, pod warunkiem przypięcia konkretnego tagu, czytania logów commitów przed każdą aktualizacją oraz wykonywania kopii zapasowej wolumenu danych przed każdą przebudową. Nie należy uruchamiać go na latest ani przechowywać w nim danych klientów.