Octop kendi sunucunuzda nasıl kurulur ve yapılandırılır

Octop nedir ve neden kendi sunucunuzda barındırmalısınız

Octop, bir hane veya küçük bir ekip için tasarlanmış, kendi sunucunuzda barındırabileceğiniz bir yapay zeka asistanıdır. Octop'u basit bir sohbet arayüzü yerine kendi sunucunuzda barındırmanızın temel nedeni, kullanıcıları birbirinden izole etmesidir. Open WebUI, bir modelin önünde size bir tarayıcı arayüzü sunar. Octop ise buna yönetici rolüne sahip hesaplar, her kullanıcı için özel bir çalışma alanı ve kimlik bilgisi seti ile her kullanıcının görev bazında geçiş yapabileceği uzman aracı kütüphaneleri ekler. Tek bir VPS'in bir kişi yerine beş kişiye hizmet vermesini sağlayan fark budur.

Proje github.com/TencentCloud/Octop adresinde yer almaktadır. Web paneli, komut satırı arayüzü, sohbet kanalları (Feishu, DingTalk, QQ, Discord, WeCom) ve zamanlanmış görevleri sunan tek bir süreçtir ve tamamı ~/.octop/ altındaki tek bir SQLite veritabanı tarafından desteklenir. Aşağıdaki her şey 5 Ağustos 2026 tarihinde yayınlanan v0.9.19 etiketi baz alınarak yazılmıştır. Platformlar arasında hala karar verme aşamasındaysanız, bir VPS üzerinde çalıştırabileceğiniz Open WebUI alternatiflerinin karşılaştırması daha geniş bir alanı kapsamaktadır.

Vakit ayırmadan önce netleştirilmesi gereken bir husus vardır. Octop, bir satıcının GitHub organizasyonu tarafından yayınlanan, 1.0 sürümü öncesi bir yazılımdır ve Ağustos 2026 itibarıyla yaklaşık 900 yıldıza sahiptir. Sürüm numaralarından da anlaşılacağı üzere hızla gelişmektedir ve buradaki hiçbir bilgi, kararlı bir yükseltme yolunun garantisi değildir. Bir etiketi sabitleyin, değişiklik günlüğünü okuyun ve yedeklerinizi alın.

Başlamadan önce gerekenler

• Docker Engine ve Compose eklentisi kurulu bir Ubuntu 24.04 VPS. Compose konusunda yeniyseniz, VPS için Docker Compose temelleri ile başlayın.
• git, çünkü bir imajı çekmek yerine bir sürüm etiketini (release tag) kullanacaksınız.
• VPS'e yönlendirilmiş bir alan adı, çünkü ön tarafta TLS (transport layer security) kullanmak isteyeceksiniz.
• OpenAI API ile uyumlu bir model arka ucu: yerel bir Ollama, kendi barındırdığınız bir ağ geçidi veya ücretli bir anahtar.

Octop kendi başına hafiftir. Bir Python süreci ve bir SQLite dosyasından oluşur. Yük, model arka ucundan kaynaklanır; bu nedenle modeli aynı sunucuda çalıştırmayı planlıyorsanız, sunucuyu modelin gereksinimlerine göre boyutlandırın.

curl yükleyicisini neden önermiyoruz

README dosyası tek satırlık bir kurulum komutuyla başlar:

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

Önem verdiğiniz bir sunucuda bunu önermiyoruz, bunun somut bir nedeni var: söz konusu betik depoda yer almıyor. Bu betik, bir Tencent Cloud Object Storage bucket üzerinden sunulmaktadır. Betikle ilgili hiçbir şey bir git etiketi veya commit ile güvence altına alınmamıştır; bu nedenle bugünkü betiği geçen haftakiyle karşılaştıramazsınız ve yapılan değişikliği açıklayan bir geçmiş kaydı bulunmamaktadır. Söz konusu bucket yarın farklı veriler sunabilir ve projedeki hiçbir şey bunu kayıt altına almaz. Çıktıyı doğrudan bash komutuna yönlendirmek, betiğin tek bir satırını bile okumadan makinede çalıştırılması anlamına gelir.

Yükleyici ayrıca bir container yerine doğrudan ana makineye (host) yazma yapar. Python 3.12 sürümünü getirmek ve paket yöneticinizin hakkında hiçbir bilgiye sahip olmadığı bir ortam oluşturmak için uv kullanır; bu nedenle daha sonra kaldırmak manuel bir işlem gerektirir.

İki daha iyi seçenek mevcuttur. Betiği indirin, okuyun ve ardından çalıştırın; bu size otuz saniyenize mal olur: curl -fsSL <url> -o install.sh, ardından less install.sh ve son olarak bash install.sh. Veya bu kılavuzun geri kalanında anlatılan Docker yöntemini kullanın. PyPI paketi (pip install octop), en azından bir sürüme sabitleyebileceğiniz sürüm kontrollü bir yapıdır.

Docker Compose ile Octop kurulumu, v0.9.19 sürümüne sabitleme

Ağustos 2026 itibarıyla çekilebilecek yayınlanmış bir imaj bulunmamaktadır. Sunulan Compose dosyası imajı depodan derlediği için, bir sürümü sabitlemek git etiketi üzerinden işlem yapmayı gerektirir. Bu, çoğu self-hosted projenin istediğinden bir adım fazladır; çünkü self-hosted bir AFFiNE çalışma alanı gibi projeler yayınlanmış bir imaj etiketine sabitlenir ve VPS üzerinde herhangi bir derleme yapmaz. Aşağıdaki klonlama, checkout ve derleme rutini openGym kurulum rehberi ile aynıdır; dolayısıyla bu işlemi daha önce yaptıysanız sürece aşinasınız demektir.

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

Dosyanın tanımladığı servis, önemli kısımları tutularak aşağıda gösterilmiştir:

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

build: bloğuna dikkat edin. image: octop:latest, bir kayıt defteri referansı değil, kendi derlemenizin aldığı isimdir; bu nedenle buradaki latest, en son derlediğiniz sürümü ifade eder. Veri yolunu varsayılan değerlere bırakmak yerine açık bir dizin olarak ayarlayın ve ilk başlatmadan önce yönetici hesabına gerçek bir parola atayın. Bu ayarları docker/.env içine yerleştirin:

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

Buradaki bir tuzak, dosyanın geri kalanından daha önemlidir. Compose, docker/.env dosyasını yalnızca YAML içindeki ${...} yer tutucularını doldurmak için okur. O dosyaya eklediğiniz bir anahtar, Compose dosyasındaki environment: altında listelenmediği sürece container içine ulaşmaz. OCTOP_ACCESS_TOKEN_TTL değerini yalnızca .env içine eklerseniz, hiçbir işlem yapılmaz ve hata mesajı da oluşmaz. Alternatif yöntem, aynı anahtarları Octop'un başlangıçta yüklediği, mount edilmiş veri dizini içindeki ~/.octop/env dosyasına yazmaktır. Docker Compose'da env dosyaları ve sırlar rehberi, bu iki mekanizmanın neden aynı olmadığını açıklamaktadır.

Derleyin ve başlatın:

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

Sağlıklı bir örnek, sağlık kontrolüne {"status":"ok","version":"..."} yanıtını verir. Başka bir sonuç alırsanız, tarayıcıyı açmadan önce docker compose -f docker/docker-compose.yml logs -f octop kayıtlarını inceleyin.

Şimdi, az önce derlediğiniz imaja anlamlı bir isim verin; çünkü bir sonraki --build işlemi octop:latest üzerine yazacaktır ve bu durumda ikisini birbirinden ayırt edemezsiniz:

docker image tag octop:latest octop:0.9.19

İlk başlatma octop init işlemini çalıştırır ve başlangıç kimlik bilgilerini veri birimine yazar:

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

Varsayılan değerler admin / octop şeklindedir ve bunlar yalnızca ilk başlatmada uygulanır. İnsanların sürekli sorduğu bir sorunun nedeni budur: Container bir kez başlatıldıktan sonra OCTOP_DEFAULT_PASSWORD değerini değiştirmek hiçbir şeyi etkilemez, çünkü hesap zaten oluşturulmuştur. Parolayı panel üzerinden değiştirin.

8088 numaralı portu dış dünyaya açmayın

Yukarıdaki ports: satırı, VPS üzerindeki tüm ağ arayüzlerini dinlemeye başlar. Container başladığı anda, dashboard varsayılan bir parola ile açık metin (cleartext) üzerinden internete açılır. Octop'un kendi OCTOP_BIND_HOST varsayılanı 127.0.0.1 değerindedir; Compose dosyası, sürecin kendi ağ ad alanı dışından gelen trafiği kabul etmesi gerektiği için bunu 0.0.0.0 olarak geçersiz kılar (override). Bu geçersiz kılma işlemi doğrudur. Sizi savunmasız bırakan kısım, portun dış dünyaya açılmış (published) olmasıdır.

docker/docker-compose.yml dosyasındaki ports: satırını, eşleştirme yalnızca loopback üzerinde dinleyecek şekilde düzenleyin:

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

Bunu basit bir geçersiz kılma (override) dosyası ile düzeltmeye çalışmayın. Compose, ports listelerini değiştirmek yerine birden fazla dosyadan birleştirir; bu durumda her iki eşleştirme de yayınlanır ve ikincisi bağlanamadığı için hata verir. Eğer orijinal dosyayı değiştirmeden bırakmak istiyorsanız, diziler için belgelenmiş yöntem olan ve ekleme yapmak yerine değiştirme sağlayan !override etiketini kullanın. Compose'un birden fazla dosyayı nasıl birleştirdiğine dair açıklama, bu birleştirme kurallarının geri kalanını kapsamaktadır.

Loopback adresine bağlanmak, aksi takdirde güvenlik duvarı ile yaşayacağınız bir sorunu da çözer. Docker, yayınlanan port kurallarını ufw tarafından yönetilen zincirlerin önüne, nat tablosuna yazar; bu nedenle ufw deny 8088 komutu, dış dünyaya açılmış bir container portunu engellemez. 127.0.0.1 adresine bağlanan bir port, ufw'nin durumundan bağımsız olarak dışarıdan asla erişilemez; bu yüzden bu yöntem, ikinci en iyi seçenek yerine kullanılması gereken doğru çözümdür.

TLS katmanını bir reverse proxy ile öne alın

Caddy, sertifikayı ACME (otomatik sertifika yönetim ortamı) üzerinden kendiliğinden talep ettiği ve WebSockets trafiğini ek bir yapılandırma gerektirmeden proxy üzerinden ilettiği için en kısa yoldur:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx daha fazla dikkat gerektirir, çünkü Octop sohbet akışını bir WebSocket üzerinden iletir:

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

Buradaki her satır belirli bir işlevi yerine getirir. Sohbet WS /agents/{id}/chat/ws üzerinden çalıştığı için, proxy_http_version 1.1 ve iki upgrade başlığı olmadan nginx, yükseltme isteğine 400 Bad Request ile yanıt verir: dashboard normal şekilde yüklenir ancak gönderdiğiniz her mesaj sayfada hata vermeden sonsuza kadar askıda kalır. proxy_buffering off önemlidir, çünkü human-in-the-loop resume uç noktası text/event-stream döndürür ve bir proxy arabelleğinde tutulan SSE (sunucu tarafından gönderilen olaylar), akış halinde iletilmek yerine sonunda tek bir blok halinde ulaşır. proxy_read_timeout, uzun süren araç çalıştırma işlemlerini kapsar; çünkü 60 saniyelik varsayılan süre, bir ajanı görevin ortasında keser ve upstream timed out (110: Connection timed out) hatasını günlüğe kaydeder.

JWT kimlik doğrulamasının proxy arkasındaki davranışı

Octop, çerez yerine bearer token ile kimlik doğrulaması yapar. POST /api/auth/login, {access_token, role, user, ...} değerini döndürür ve sonraki çağrılar Authorization: Bearer <access_token> başlığını taşır. Bir reverse proxy için bu iyi bir haberdir: yanlış yapılandırılabilecek bir çerez domaini, Secure bayrağı veya SameSite kuralı yoktur; bu nedenle http://127.0.0.1:8088 üzerinde çalışan bir oturum, https://octop.example.com üzerinde de aynı şekilde davranır.

Gerçek kullanıcıları sisteme dahil etmeden önce bilinmesi gereken iki sonuç vardır.

WebSocket, token bilgisini URL içinde taşır. Uç nokta WS /agents/{id}/chat/ws?token=<jwt> şeklindedir, çünkü tarayıcı JavaScript'i bir WebSocket el sıkışmasında Authorization başlığı ayarlayamaz. TLS, bu token bilgisini iletim sırasında korur. Ancak kendi günlük kayıtlarınızdan korumaz: nginx, varsayılan olarak tüm istek satırını ve sorgu dizisini access_log dosyasına yazar; bu nedenle gerçek bir kullanıcıya ait geçerli bir token, sunucudaki düz metin bir dosyada saklanmış olur. Günlük kaydını argümanlar olmadan, yalnızca yol bilgisiyle tutun. $uri, sorgu dizisi temizlenmiş normalleştirilmiş yoldur; bu nedenle bunu http bloğuna yerleştirin ve sunucu yapılandırmasından referans verin:

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;

Oturum bazlı bir çıkış işlemi yoktur. OCTOP_ACCESS_TOKEN_TTL varsayılan olarak 86400 değerindedir, bu nedenle bir token girişten sonra 24 saat boyunca geçerli kalır. Bir token'ı geçersiz kılmanın belgelenmiş tek yolu octop admin rotate-jwt-secret işlemidir; bu işlem ~/.octop/secrets/jwt_secret konumunda saklanan imzalama anahtarını döndürür ve herkes için mevcut tüm token'ları anında geçersiz kılar. Bu nedenle bir ekip üyesi ayrıldığında izlenmesi gereken sıra şöyledir: kullanıcıyı silin, gizli anahtarı döndürün ve ardından kalan kullanıcılardan tekrar giriş yapmalarını isteyin. Eğer bu süreç ağır geliyorsa, değişkeni .env dosyasının yanı sıra environment: listesine de eklemeyi unutmadan token ömrünü kısaltın:

OCTOP_ACCESS_TOKEN_TTL=28800

Brute force saldırıları yönetilmiştir: OCTOP_LOGIN_MAX_ATTEMPTS varsayılan olarak 5 başarısız denemeye, OCTOP_LOGIN_LOCKOUT_SECONDS ise 900 saniyeye ayarlıdır; bu sayede hesabı kilitlenen bir kullanıcı, bozuk bir kurulumla karşılaşmak yerine sadece on beş dakika bekler. Octop kendi kullanıcı deposuna sahiptir ve v0.9.19 sürümünde belgelenmiş bir OIDC desteği bulunmamaktadır. Bu nedenle gerçek bir tek oturum açma (SSO) çözümüne ihtiyacınız varsa, önüne bir kimlik doğrulama proxy'si koymanız gerekir; kendi kendine barındırılan bir Authentik sunucusu bunun için kullanılır.

Octop'u bir model arka ucuna yönlendirme

Sağlayıcılar panel üzerinden her bir aracı (agent) için ayrı ayrı yapılandırılır ve octop provider list size nelerin ayarlandığını gösterir. Octop, OpenAI uyumlu API'ler, DashScope (Qwen) ve Ollama için hazır ayarlar sunar; kimlik bilgileri ise kendi SQLite veritabanınızdaki providers tablosunda saklanır. Yapılan seçim, ödeyeceğiniz ücreti ve sunucudan dışarı çıkan veriyi belirler.

Ollama ile yerel bir model. Hiçbir veri sunucudan dışarı çıkmaz ve token yerine RAM harcarsınız. İnsanların gözünden kaçan bağlantı detayı şudur: Bir container, 127.0.0.1:11434 adresindeki ana makine (host) Ollama'sına erişemez; çünkü bu adres container'ın kendi loopback arayüzüdür. Servise bir host gateway girişi ekleyin:

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

Ardından sağlayıcı temel URL'sini, Ollama'nın OpenAI uyumlu yolu olan http://host.docker.internal:11434/v1 olarak ayarlayın. API anahtarı alanına boş olmayan herhangi bir karakter dizisi girin; Ollama bunu görmezden gelir ancak OpenAI istemcileri boş anahtar gönderilmesini reddeder. Bunun çalışması için Ollama'nın yalnızca loopback üzerinde değil, dışarıdan da dinleme yapması gerekir; bu da systemd birim dosyasında OLLAMA_HOST=0.0.0.0:11434 ayarını gerektirir. Buradaki riskli nokta şudur: Ollama kimlik doğrulama içermez, bu nedenle herkese açık bir IP üzerinde 11434 numaralı portu açık bırakmak, tarama yapan herkesin ücretsiz model sunucunuza erişmesine neden olur. Yalnızca Docker'ın özel IP aralığı olan sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp adresine izin verin ve geri kalanını engelleyin. VPS üzerinde Ollama çalıştırma rehberi model boyutlandırmayı, Ollama ve vLLM karşılaştırması ise Ollama'nın ne zaman yetersiz kalacağını açıklar.

Yerel modellerle ilgili bir uyarı daha; bu durum Octop'ta bir hata gibi görünse de aslında değildir. Aracılar araçları (tools) çağırarak çalışır; sistem istemi (system prompt), araç tanımları ve geçmiş birleştiğinde ortaya büyük bir istem çıkar. Ollama, modelleri varsayılan olarak mütevazı bir bağlam penceresi (context window) ile sunar; bu nedenle araç tanımlarının bulunduğu istemin baş kısmı pencerenin dışında kalır. Model daha sonra araç çağırmayı bırakır veya var olmayan araçlar uydurur. num_ctx değerini 16k veya 32k seviyesine yükseltin ve fonksiyon çağırma konusunda gerçekten başarılı bir model seçin. Yanıtın cümle ortasında kesilmesi ise farklı bir sorundur ve num_predict ayarı ile ilgilidir; bu nedenle yanıtlar kesik geliyorsa, aracı suçlamadan önce num_predict değerinin nerede ayarlandığını ve done_reason değerinin ne olduğunu kontrol etmek faydalıdır. Kısa bir liste yerine belirli bir adaydan başlamayı tercih ederseniz, Nemotron 3.5 Lightning denemeye değerdir; ilgili yazı, çekilecek etiketi, ihtiyaç duyulan RAM miktarını ve yalnızca CPU ile çalışıp çalışmayacağını belirtir.

Self-hosted bir ağ geçidi. Octop ile diğer her şey arasına self-hosted bir LiteLLM ağ geçidi yerleştirirseniz; tek bir temel URL, kullanıcı başına ayrı anahtar, harcama limitleri ve tek bir günlük kaydı elde edersiniz. Ayrıca Octop üzerinde hiçbir şeyi düzenlemeden arka plandaki modeli değiştirebilirsiniz.

Ücretli bir API. En yüksek kaliteyi sunar ancak dürüst bir takas gerektirir: Konuşma içeriği sunucunuzdan çıkar ve sağlayıcıya ulaşır; bu da self-hosting amacının büyük bir kısmını devre dışı bırakır. Anahtar, Compose dosyası tarafından zaten aktarılan OPENAI_API_KEY değişkeni olarak docker/.env içine girilir.

Hangisini seçerseniz seçin, Compose dosyası OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY ve LANGFUSE_BASE_URL değişkenlerini de taşır; böylece izleme verilerini kendi Langfuse örneğinize gönderebilir ve sohbet penceresinden tahmin yürütmek yerine aracıların gerçekte ne yaptığını görebilirsiniz.

Kullanıcılar, roller ve paylaşılan aracı kütüphanesi

İlk kurulumda oluşturulan yönetici hesabı, diğer hesapları oluşturur ve yönetir. Her kullanıcı kendi aracısına, çalışma alanına ve kimlik bilgilerine sahiptir; bu izolasyon, tarayıcıda tutulan token ile sağlanır. Bunun yanı sıra, herkesin kullanabileceği paylaşılan bir yetenek ve alt aracı havuzu bulunur; bu özellik, sistemin bir aile için kullanılmasını değerli kılan unsurdur: Bir kişi iyi bir araştırma aracısı oluşturduğunda, diğerlerinin bunu tekrar oluşturmasına gerek kalmaz.

Araç kullanımı konusunda dikkatli olun. Octop, araç onayı ve shell komutu koruma mekanizmaları sunar; bunlar gerçek özelliklerdir ancak shell komutlarını çalıştıran bir aracı, bu komutları veri biriminizin (data volume) mount edildiği Octop container'ı içerisinde yürütür. Koruma mekanizmaları, dikkatsizce yazılmış bir istemin (prompt) verebileceği zararı azaltır. Bunlar bir sandbox sınırı değildir; bu nedenle, shell erişimi vermeyeceğiniz hiç kimse için araç onayını devre dışı bırakmayın. Eğer bu sistemi diğer seçeneklerle kıyaslıyorsanız, self-hosted yapay zeka aracıları karşılaştırması her birinin bu durumu nasıl yönettiğini göstermektedir.

Bu kadar hızlı sürüm yayınlayan bir projeyi yükseltmek

[
  {
    "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
  }
]

Bunlar, 7 Ağustos 2026 itibarıyla depodaki etiket tarihleridir. Dokuz gün içinde 4 adet etiketli sürüm yayınlanmıştır; sürümler arasındaki en kısa süre 1 gün olup, v0.9.19 sürümü bir önceki etiketten 3 gün sonra gelmiştir. Bu yayın temposu proje için iyi bir işaret olsa da latest komutunu çalıştırmak için kötü bir nedendir. Değişiklikleri uygulamadan önce mutlaka okuyun:

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"

Her seferinde önce yedek alın; çünkü veritabanı migrasyonları başlangıçta çalışır ve 1.0 öncesi bir projede başarısız olan bir migrasyonu düzeltmek sizin sorumluluğunuzdadır:

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

Ardından yeni etikete geçin ve docker compose -f docker/docker-compose.yml up -d --build ile yeniden derleyin. Bir şeyler ters giderse, eski etikete dönüp yeniden derlemek kodu geri getirir ancak veritabanını yalnızca tarball dosyası ile geri yükleyebilirsiniz.

Bu tarball dosyası octop.db, config.json, JWT imzalama anahtarı ve credential.txt verilerini içerir; bu nedenle sunucunun kendisi kadar hassastır. Dosyayı 600 izin modunda tutun ve bir kopyasını sunucu dışında saklayın. Daha büyük kurulumlar için proje, SQLite yerine pgvector ile PostgreSQL çalıştıran docker/docker-compose.postgres.yml bileşenini de sunmaktadır.

Hata modları ve karşılaşacağınız dizgeler

Sistem sağlık kontrolü yanıt vermiyor. curl http://127.0.0.1:8088/api/health takılıyor veya bağlantıyı reddediyor. docker compose -f docker/docker-compose.yml logs -f octop kısmını okuyun. İlk başlatma sırasında kapanan bir container genellikle veri dizinine yazma yapamıyordur; bu nedenle OCTOP_DATA değerine atadığınız yolun sahiplik izinlerini kontrol edin.

Dashboard yükleniyor ancak sohbet takılıyor. Sayfada hata yok ancak yanıt da gelmiyor. Tarayıcı konsolunu açın ve wss://octop.example.com/agents/.../chat/ws adresine yönelik başarısız bir bağlantı olup olmadığını kontrol edin. Proxy, yükseltme (upgrade) isteğini iletmiyor. proxy_http_version 1.1 ayarını ekleyin ve Upgrade ile Connection başlıklarını yapılandırın.

Tüm yanıt bir anda, birkaç saniye gecikmeli geliyor. Akış (streaming) çalışıyor ancak arabelleğe alma (buffering) açık. proxy_buffering off ayarını yapılandırın.

bind: address already in use. 8088 numaralı port halihazırda başka bir süreç tarafından kullanılıyor. sudo ss -tlnp | grep 8088 komutu bu süreci tanımlar. Orijinal dosyayı düzenlemek yerine geçersiz kılma (override) dosyasına ikinci bir ports girdisi eklediğinizde de bu hatayı alırsınız.

Doğru parola reddediliyor. Beş hatalı deneme, 900 saniyelik bir kilitlenmeyi tetikler. Yeniden kurulum yapmak yerine sürenin dolmasını bekleyin.

.env içindeki yeni parolanın bir etkisi olmadı. Bu kimlik bilgileri yalnızca ilk başlatma sırasında geçerlidir. Parolayı dashboard üzerinden değiştirin.

Ajan yanıt veriyor ancak hiçbir aracı çalıştırmıyor. Bu neredeyse her zaman yerel model kaynaklı bir sorundur: bağlam penceresi (context window) araç tanımları için çok küçüktür veya model fonksiyon çağırma konusunda yetersizdir. num_ctx değerini yükseltin ve araç kullanımı için optimize edilmiş bir model deneyin.

FAQ

Octop, Open WebUI'nin yerini tutar mı?

Yalnızca sunduğu ek özelliklere ihtiyacınız varsa tutar. Open WebUI, bir modelin önünde yer alan bir sohbet arayüzüdür ve bu işi tek bir kullanıcı veya güvene dayalı bir hane halkı için gayet iyi yapar. Octop ise yönetici rolüne sahip hesaplar, kullanıcı bazlı çalışma alanları ve kimlik bilgileri ile değiştirilebilir uzman temsilci kütüphanesi ekler; böylece birden fazla kişi tek bir geçmişi paylaşmadan aynı sunucuyu kullanabilir. Tek bir hesap sizin için yeterliyse, Open WebUI daha basit ve çok daha olgun bir tercihtir.

Neden Octop curl kurulum betiğini kullanmamalıyım?

Betiğin sunumu depodan değil, bir Tencent Cloud Object Storage paketinden yapılır; bu nedenle herhangi bir git etiketi veya commit ile ilişkilendirilmemiştir. Bugün yaptığı işlemin geçen hafta yaptığıyla aynı olup olmadığını doğrulayamazsınız ve betiği doğrudan bash komutuna yönlendirmek, içeriğini okumadan çalıştırmanıza neden olur. Ayrıca betik, paket yöneticinizin dışında, kendi Python 3.12 ortamıyla ana makineye kurulum yapar. Betiği önce indirin ve inceleyin ya da kontrol edilmiş bir etiket üzerinden Docker Compose ile dağıtın.

Octop, ücretli bir API yerine yerel bir model kullanabilir mi?

Evet. Octop, OpenAI uyumlu API'leri destekler ve bir Ollama ön ayarı ile gelir. Bu nedenle, http://host.docker.internal:11434/v1 adresine yönlendirme yapmak, konteynere extra_hosts: ["host.docker.internal:host-gateway"] eklediğinizde ve ana makinede OLLAMA_HOST=0.0.0.0:11434 ayarını yaptığınızda çalışır. Ollama'nın kendi kimlik doğrulama mekanizması bulunmadığından, güvenlik duvarında 11434 numaralı portu Docker'ın adres aralığına göre kısıtlayın. Ollama'nın num_ctx değerini 16k veya daha yüksek bir seviyeye çıkarmayı planlayın; çünkü araç tanımlarını içeren temsilci istemleri varsayılan bağlam penceresini aşar ve model araç çağırmayı durdurur.

Bir reverse proxy kullanmam gerekiyor mu, yoksa 8088 numaralı portu açabilir miyim?

Proxy kullanmanız gerekir. Octop ile gelen Compose dosyası, 8088 numaralı portu TLS olmadan tüm arayüzlerde yayınlar; bu da şifrelerin ve taşıyıcı belirteçlerin (bearer tokens) internet üzerinden açık metin olarak iletilmesine neden olur. Yayınlanan portu 127.0.0.1:8088:8088 olarak değiştirin ve önüne bir sertifika ile Caddy veya nginx yerleştirin. nginx kullanıyorsanız, WebSocket yükseltme başlıklarını iletin ve proxy_buffering off ayarını yapın; aksi takdirde sayfa yüklenir ancak sohbet yanıt vermez.

Octop üretime hazır mı?

Ağustos 2026 itibarıyla 1.0 sürümü öncesindedir ve haftada birkaç etiketli sürüm yayınlanmaktadır; bu nedenle ürünü yerleşik bir çözümden ziyade gelecek vadeden bir yazılım olarak değerlendirin. Belirli bir etiketi sabitlediğiniz, her yükseltme öncesinde commit günlüğünü okuduğunuz ve her yeniden oluşturma işleminden önce veri biriminin yedeğini aldığınız sürece, bir aile veya küçük bir iç ekip için kullanılabilir durumdadır. Yazılımı latest üzerinde çalıştırmayın ve henüz müşteri verilerini içine aktarmayın.