Jinsi ya kujiendeshea Octop kwa Docker Compose

Octop ni nini, na kwa nini unapaswa kujiendeshea (self-host) mwenyewe

Octop ni msaidizi wa AI anayejiendeshea (self-hosted) kwa ajili ya kaya au timu ndogo. Sababu ya kujiendeshea Octop badala ya kutumia kiolesura cha kawaida cha chat ni kwamba inatenganisha watumiaji. Open WebUI inakupa kiolesura cha kivinjari mbele ya model. Octop inaongeza akaunti zenye nafasi ya admin, nafasi ya kazi binafsi (private workspace), seti ya vitambulisho kwa kila mtumiaji, na maktaba ya mawakala maalum ambao kila mtumiaji anaweza kubadilishana nao kulingana na kazi. Hiyo ndiyo tofauti inayoruhusu VPS moja kuhudumia watu watano badala ya mmoja.

Mradi huu unapatikana katika github.com/TencentCloud/Octop. Ni mchakato mmoja unaohudumia dashibodi ya wavuti, kiolesura cha mstari wa amri (CLI), njia za chat (Feishu, DingTalk, QQ, Discord, WeCom) na kazi zilizopangwa, zote zikiwa na hifadhi ya database moja ya SQLite chini ya ~/.octop/. Kila kitu hapa chini kimeandikwa kulingana na tag v0.9.19, iliyotolewa tarehe 5 Agosti 2026. Ikiwa bado unaamua kati ya majukwaa, ulinganisho wa njia mbadala za Open WebUI unazoweza kuendesha kwenye VPS unashughulikia uwanja mpana zaidi.

Jambo moja la kuwa wazi kabla ya kutumia jioni yako kwa ajili ya hili. Wakati mwongozo huu ukiandikwa, Octop ilikuwa programu ya kabla ya 1.0 iliyochapishwa kutoka shirika la GitHub la muuzaji, ikiwa na takriban nyota 900 kufikia Agosti 2026. Tangu wakati huo imetoa tag v1.0.0 mnamo 14 Septemba 2026, na kufikia 20 Oktoba 2026 tag mpya zaidi ni v1.0.2, toleo thabiti lililochapishwa mnamo 18 Oktoba 2026 baada ya mfululizo wa tag za beta za 1.0.2, huku hazina (repository) ikiwa na takriban nyota 10,400. Hatua zilizo hapa chini ziliandikwa kulingana na v0.9.19 na hazijajaribiwa upya kwenye 1.x. Inakwenda kwa kasi, namba za toleo zinasema hivyo, na hakuna kitu hapa kinachotoa ahadi ya njia thabiti ya kuboresha (upgrade path). Funga (pin) tag, soma changelog, na weka backups.

Unachohitaji kabla ya kuanza

• VPS inayoendesha Ubuntu 24.04 ikiwa na Docker Engine na Compose plugin. Je, hujawahi kutumia Compose? Anza na Misingi ya Docker Compose kwa VPS.
• git, kwa sababu utaangalia release tag badala ya kuvuta image.
• Jina la domain linaloelekeza kwenye VPS, kwa sababu unataka TLS (transport layer security) iwe mbele ya huduma hii.
• Model backend inayotumia OpenAI API: Ollama ya ndani, gateway uliyoji-host, au key ya kulipia.

Octop yenyewe ni nyepesi. Ni process ya Python na file la SQLite. Mzigo unatokana na model backend, hivyo ikiwa unapanga kuendesha model kwenye mashine hiyo hiyo, chagua ukubwa wa mashine unaotosha model.

Kwa nini hatupendekezi installer ya curl

README inaanza na usakinishaji wa mstari mmoja:

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

Hatuipendekezi kwenye seva unayoithamini kwa sababu moja iliyo wazi: script hiyo haipo kwenye repository. Inatolewa kutoka kwenye bucket ya Tencent Cloud Object Storage. Hakuna sehemu yake inayodhibitiwa na git tag au commit, kwa hiyo huwezi kulinganisha script ya leo na ya wiki iliyopita, wala hakuna historia inayoeleza mabadiliko. Bucket inaweza kutoa bytes tofauti kesho, bila mradi kurekodi mabadiliko hayo. Kupeleka matokeo moja kwa moja kwenye bash pia kunamaanisha mashine inaendesha script hiyo kabla hujasoma hata mstari mmoja.

Installer hiyo pia huandika moja kwa moja kwenye host badala ya container. Inatumia uv kupakua Python 3.12 na kujenga environment ambayo package manager wako haijui, kwa hiyo kuiondoa baadaye ni kazi ya mikono.

Kuna chaguo mbili bora. Pakua script, isome, kisha uiendeshe. Hilo linachukua sekunde thelathini tu: curl -fsSL <url> -o install.sh, kisha less install.sh, halafu bash install.sh. Au tumia Docker, ambalo ndilo linaloelezwa katika mwongozo huu uliobaki. Package ya PyPI (pip install octop) ni artifact yenye version angalau, na unaweza kuifunga kwenye release.

Kutumia Octop kwa Docker Compose, ukiwa umefunga toleo la v0.9.19

Faili ya Compose iliyosafirishwa katika toleo la v0.9.19 hujenga image kutoka kwenye repository, kwa hivyo katika mwongozo huu, kufunga toleo kunamaanisha kuchagua git tag husika. Image zilizochapishwa zipo. Mti wa v0.9.19 tayari una docker-publish.yml workflow, iliyoongezwa katika v0.9.8 mnamo 15 Julai 2026, ambayo hujenga image na kuisukuma kwenye Docker Hub kwa kila v* tag. Kufikia 20 Oktoba 2026, mradi huu pia huchapisha kwenye container registry ya GitHub (docker pull ghcr.io/tencentcloud/octop:1.0.2). Kujenga kutoka kwenye tag uliyochagua ndiyo njia bora zaidi ya kufunga toleo, kwa sababu unakusanya (compile) msimbo uleule unaousoma badala ya kuamini tag ya registry. Hiyo ni hatua moja zaidi kuliko miradi mingi ya self-hosted inavyohitaji, kwa kuwa kitu kama workspace ya AFFiNE ya self-hosted hufunga toleo kwenye image tag iliyochapishwa na haijengi chochote kwenye VPS yako. Utaratibu wa clone, checkout na build hapa chini ni uleule ambao mwongozo wa deployment wa openGym unauelezea, kwa hivyo ikiwa umewahi kuweka mfumo huo mara moja, tayari unajua jinsi unavyofanya kazi.

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

Hii ndiyo huduma ambayo faili inafafanua, ikiwa imepunguzwa ili kubaki na sehemu muhimu pekee:

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

Angalia block ya build:. image: octop:latest ni jina ambalo build yako inalipata, si rejeleo la registry, kwa hivyo latest hapa inamaanisha chochote ulichokikusanya hivi karibuni. Weka njia ya data (data path) mahali dhahiri badala ya kuiacha kwenye chaguo-msingi, na upe akaunti ya admin nenosiri halisi kabla ya boot ya kwanza. Weka hili kwenye docker/.env:

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

Mtego mmoja hapa una umuhimu zaidi kuliko sehemu nyingine zote za faili. Compose husoma docker/.env ili tu kuingiza (interpolate) placeholders za ${...} kwenye YAML. Ufunguo (key) unaoongeza kwenye faili hiyo hauufikii container isipokuwa kama pia umeorodheshwa chini ya environment: katika faili ya Compose. Ukiongeza OCTOP_ACCESS_TOKEN_TTL kwenye .env pekee, haitafanya kazi yoyote, kimya kimya. Njia mbadala ni kuandika funguo zilezile kwenye ~/.octop/env ndani ya saraka ya data iliyopachikwa (mounted), ambayo Octop huipakia wakati wa kuanza. Mwongozo wa faili za env na siri katika Docker Compose unaelezea kwa nini mifumo hii miwili si kitu kimoja.

Jenga na uanzishe:

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

Instance yenye afya hujibu ukaguzi wa afya (health check) kwa JSON object inayofanana na {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0}. Kwa jambo lingine lolote, soma docker compose -f docker/docker-compose.yml logs -f octop kabla ya kugusa kivinjari.

Sasa ipe image uliyojenga jina lenye maana, kwa sababu --build inayofuata itafuta octop:latest na hutakuwa na njia ya kuvitofautisha:

docker image tag octop:latest octop:0.9.19

Boot ya kwanza huendesha octop init na kuandika vitambulisho vya kuanzia kwenye data volume:

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

Chaguo-msingi ni admin / octop, na hutumika tu wakati wa init ya kwanza. Huo ndio utaratibu nyuma ya swali ambalo watu huuliza kila mara: kubadilisha OCTOP_DEFAULT_PASSWORD baada ya container kuanza mara moja hakubadilishi chochote, kwa sababu akaunti tayari ipo. Badilisha nenosiri kwenye dashboard badala yake.

Usichapishe port 8088

Mstari wa ports: hapo juu unafunga kila interface kwenye VPS. Mara tu container inapoanza, dashboard inakuwa kwenye mtandao wa umma kwa cleartext, ikiwa na password chaguo-msingi. OCTOP_BIND_HOST ya Octop yenyewe ni 127.0.0.1; faili la Compose linabadilisha hilo kuwa 0.0.0.0 kwa sababu mchakato lazima ukubali trafiki kutoka nje ya network namespace yake. Badiliko hilo ni sahihi. Port iliyochapishwa ndiyo sehemu inayokuweka hatarini.

Hariri mstari wa ports: katika docker/docker-compose.yml ili mapping isikilize tu kwenye loopback:

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

Usijaribu kurekebisha hili kwa faili la kawaida la override. Compose huunganisha orodha za ports kutoka kwenye faili nyingi badala ya kuzibadilisha, kwa hivyo utaishia kuchapisha mappings zote mbili na ya pili itashindwa kufunga. Ikiwa unataka kuacha faili la upstream bila kuguswa, tumia tag ya !override kwenye sequence, ambayo ndiyo njia iliyoelekezwa ya kubadilisha badala ya kuongeza. Ufafanuzi wa jinsi Compose inavyounganisha faili nyingi inashughulikia sheria nyingine za uunganishaji.

Kufunga kwenye loopback pia kunatatua tatizo ambalo ungekutana nalo na firewall. Docker huandika sheria zake za published-port kwenye nat table mbele ya chains ambazo ufw inasimamia, kwa hivyo ufw deny 8088 haizuii port ya container iliyochapishwa. Kwenye Docker Engine 28.0.0 au mpya zaidi, port iliyofungwa kwenye 127.0.0.1 haifikiki kutoka nje bila kujali ufw inavyofikiri, ndiyo maana hii ndiyo suluhisho sahihi badala ya suluhisho la pili bora. Matoleo ya zamani ya Engine huruhusu hosts kwenye L2 segment moja, kama vile mashine nyingine kwenye switch ya mtoa huduma wako, kufikia ports zilizochapishwa kwenye localhost, kwa hivyo endesha docker version na ufanye upgrade ikiwa seva inaripoti toleo lolote chini ya 28.

Weka TLS mbele kwa kutumia reverse proxy

Caddy ndiyo njia ya haraka zaidi, kwa sababu huomba cheti kupitia ACME (automatic certificate management environment) yenyewe na hufanya proxy ya WebSockets bila kuhitaji usanidi wa ziada:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx inahitaji uangalifu zaidi, kwa sababu Octop hutiririsha gumzo kupitia 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;
    }
}

Kila mstari hapo una kazi yake. Gumzo hutumia WS /api/agents/{id}/chat/ws, kwa hivyo bila proxy_http_version 1.1 na vichwa viwili vya upgrade, nginx hujibu jaribio la upgrade kwa 400 Bad Request: dashibodi hupakia kawaida lakini kila ujumbe unaotuma hukwama milele bila kutoa kosa lolote kwenye ukurasa. proxy_buffering off ni muhimu kwa sababu endpoint ya resume ya human-in-the-loop hurejesha text/event-stream, na SSE (server-sent events) zinazoshikiliwa kwenye proxy buffer hufika kama fungu moja mwishoni badala ya kutiririka. proxy_read_timeout inashughulikia utekelezaji mrefu wa zana, kwa sababu muda chaguo-msingi wa sekunde 60 hukata wakala katikati ya kazi na kuandika upstream timed out (110: Connection timed out) kwenye logi.

Jinsi uthibitishaji wa JWT unavyofanya kazi nyuma ya proxy

Octop huthibitisha mtumiaji kwa kutumia bearer token, si cookie. POST /api/auth/login hurejesha {access_token, role, user, ...} na maombi yanayofuata hubeba Authorization: Bearer <access_token>. Kwa reverse proxy, hii ni habari njema: hakuna domain ya cookie, hakuna flag ya Secure, na hakuna sheria ya SameSite ya kukosea, kwa hivyo session iliyofanya kazi kwenye http://127.0.0.1:8088 itafanya kazi vilevile kwenye https://octop.example.com.

Kuna matokeo mawili unayopaswa kujua kabla ya kuruhusu watumiaji halisi kuitumia.

WebSocket hubeba token kwenye URL. Endpoint yake ni WS /api/agents/{id}/chat/ws?token=<jwt>, kwa sababu JavaScript ya kivinjari haiwezi kuweka Authorization header kwenye WebSocket handshake. TLS hulinda token hiyo wakati wa usafirishaji. Hata hivyo, haikulindi dhidi ya logi zako mwenyewe: nginx huandika mstari mzima wa ombi, ikiwemo query string, kwenye access_log kwa chaguo-msingi, kwa hivyo token inayofanya kazi ya mtumiaji halisi huishia kwenye faili ya maandishi wazi kwenye seva. Rekodi njia bila hoja zake. $uri ni njia iliyosawazishwa ambayo query string imeshaondolewa, kwa hivyo iweke kwenye block ya http na uirejelee kutoka kwa seva:

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;

Hakuna logout ya kila session. OCTOP_ACCESS_TOKEN_TTL huwa na muda wa 86400 kwa chaguo-msingi, kwa hivyo token hubaki kuwa halali kwa saa 24 baada ya kuingia. Njia pekee iliyoandikwa ya kubatilisha token ni octop admin rotate-jwt-secret, ambayo hubadilisha ufunguo wa kusaini (signing key) uliopo kwenye ~/.octop/secrets/jwt_secret na kubatilisha kila token inayotumika mara moja, kwa kila mtu. Kwa hivyo, mtu anapoondoka kwenye timu, utaratibu ni: futa mtumiaji, badilisha secret, kisha waambie watumiaji waliosalia waingie tena. Ikiwa hii inaonekana kuwa nzito, fupisha muda wa uhalali, ukikumbuka kuongeza variable hiyo kwenye orodha ya environment: pamoja na .env:

OCTOP_ACCESS_TOKEN_TTL=28800

Brute force inadhibitiwa: OCTOP_LOGIN_MAX_ATTEMPTS huwa na kikomo cha makosa 5 na OCTOP_LOGIN_LOCKOUT_SECONDS ni 900, kwa hivyo mtumiaji aliyefungiwa atasubiri dakika kumi na tano badala ya kuona usakinishaji uliovunjika. Octop ina hifadhi yake ya watumiaji na haina msaada wa OIDC uliothibitishwa katika v0.9.19, kwa hivyo ikiwa unahitaji single sign-on ya kweli, weka proxy ya uthibitishaji mbele yake, ambayo ndiyo kazi ya seva ya Authentik inayojiendesha mwenyewe.

Elekeza Octop kwenye backend ya modeli

Providers husanidiwa kwa kila agent kwenye dashboard, na octop provider list hukuonyesha mipangilio iliyowekwa. Octop husafirisha presets za API zinazooana na OpenAI, DashScope (Qwen) na Ollama, na credentials huhifadhiwa kwenye jedwali la providers la database yako ya SQLite. Chaguo hili huamua gharama utakazolipa na data itakayotoka kwenye seva.

Modeli ya ndani yenye Ollama. Hakuna data inayotoka kwenye seva, na unatumia RAM badala ya kulipia tokens. Jambo la usanidi linalowachanganya watu ni hili: container haiwezi kufikia Ollama ya host kupitia 127.0.0.1:11434, kwa sababu anwani hiyo ni loopback ya container yenyewe. Ongeza ingizo la host gateway kwenye service:

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

Kisha weka base URL ya provider kuwa http://host.docker.internal:11434/v1, ambayo ni njia ya Ollama inayooana na OpenAI, na weka string yoyote isiyo tupu kwenye sehemu ya API key, kwa sababu Ollama huipuuza lakini clients za OpenAI hukataa kutuma key tupu. Ollama lazima pia isikilize nje ya loopback ili hii ifanye kazi, jambo linalomaanisha OLLAMA_HOST=0.0.0.0:11434 katika systemd unit yake. Hii ndiyo sehemu hatari: Ollama haina authentication, kwa hiyo 11434 ikiwa wazi kwenye public IP huwa model server ya bure kwa yeyote anayeichanganua kwanza. Ruhusu tu private range ya Docker, sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp, na ukatae nyingine zote. Kuendesha Ollama kwenye VPS kunaeleza ukubwa wa modeli, na ulinganisho wa Ollama na vLLM unaeleza wakati Ollama inapokoma kuwa server inayofaa.

Kuna tahadhari nyingine kuhusu modeli ya ndani, kwa sababu hali hii huonekana kama bug kwenye Octop lakini si bug. Agents hufanya kazi kwa kuita tools, na system prompt pamoja na tool definitions na history huunda prompt kubwa. Ollama huhudumia modeli zenye context window ya kawaida iliyo ndogo, kwa hiyo mwanzo wa prompt, ambako tool definitions zipo, hutoka nje ya window. Kisha modeli huacha kuita tools au hutunga tools ambazo hazipo. Pandisha num_ctx hadi 16k au 32k na uchague modeli ambayo ni nzuri kwa function calling. Jibu linalokatika katikati ya sentensi ni tatizo tofauti lenye setting nyingine, num_predict, kwa hiyo majibu yakirudi yakiwa yamekatwa, inafaa kuangalia num_predict imewekwa wapi na done_reason inasema nini kabla ya kumlaumu agent. Ukipendelea kuanza na candidate maalum badala ya shortlist, Nemotron 3.5 Lightning inafaa kujaribiwa, na maelezo hayo yana tag sahihi ya kuvuta, RAM inayohitajika na kama CPU-only inaendana kwa kasi.

Gateway ya kujihudumia mwenyewe. Weka gateway ya LiteLLM inayojihudumia mwenyewe kati ya Octop na kila kitu kingine, nawe utapata base URL moja, key tofauti kwa kila mtumiaji, mipaka ya matumizi na logi moja. Unaweza pia kubadilisha modeli iliyo nyuma yake bila kuhariri chochote kwenye Octop.

API ya kulipia. Hii hutoa ubora bora, lakini ina tradeoff ya wazi: maudhui ya mazungumzo hutoka kwenye seva yako na kufika kwa provider, jambo linalopingana na sehemu kubwa ya sababu ya self-hosting. Key huwekwa kwenye docker/.env kama OPENAI_API_KEY, na Compose file tayari huipeleka huko.

Chaguo lolote utakalochagua, Compose file pia hubeba OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY na LANGFUSE_BASE_URL, kwa hiyo unaweza kutuma traces kwenye instance yako ya Langfuse na kuona agents wanafanya nini hasa badala ya kukisia kutokana na chat window.

Watumiaji, majukumu na maktaba ya pamoja ya mawakala

Akaunti ya msimamizi kutoka kwenye boot ya kwanza huunda na kudhibiti akaunti nyingine. Kila mtumiaji hupata mawakala, workspace na credentials zake. Utengaji huo unatekelezwa na tokeni inayohifadhiwa na browser. Pamoja na hayo kuna pool ya pamoja ya skills na sub-agents ambayo mtu yeyote anaweza kutumia. Hiki ndicho kinachofanya huduma hii iwe na maana kwa familia: mtu mmoja huunda agent mzuri wa utafiti mara moja, na hakuna mwingine anayehitaji kuujenga upya.

Kuwa mwangalifu unapotumia tooling. Octop inatangaza tool approval na shell command guardrails, na zote mbili ni za kweli. Hata hivyo, agent anayeendesha shell commands huzitekeleza ndani ya Octop container yenye data volume yako ikiwa mounted. Guardrails hupunguza kile ambacho prompt isiyokuwa makini inaweza kufanya. Si mpaka wa sandbox. Kwa hiyo, acha tool approval ikiwa imewashwa kwa mtu yeyote ambaye usingempa shell moja kwa moja. Ikiwa unalinganisha huduma hii na chaguo nyingine, mapitio ya mawakala wa AI wanaojihudumia yanaeleza jinsi kila mmoja anavyoshughulikia hilo.

Kupandisha toleo la mradi unaotoa releases kwa kasi hii

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

Hizo ni tarehe za tag kutoka kwenye repository, zikihesabiwa kufikia tarehe 7 Agosti 2026. 4 releases zilizotolewa ziliingia ndani ya siku tisa, zikiwa na pengo fupi la siku 1, na toleo la v0.9.19 likiwasili siku 3 baada ya tag iliyotangulia. Kasi hiyo ni ishara nzuri kuhusu mradi huu na sababu mbaya ya kuendesha latest. Soma mabadiliko kabla ya kuyachukua:

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"

Hakiki kile ambacho $NEW_TAG kinacho kweli kabla ya kukicheck out, kwa sababu mradi huu huweka tag za beta kama v1.0.2b9 sambamba na releases thabiti. Kufikia tarehe 20 Oktoba 2026, tag mpya zaidi ni toleo thabiti la v1.0.2, lililochapishwa tarehe 18 Oktoba 2026, na hatua kutoka v0.9.19 inavuka toleo la v1.0.0 la tarehe 14 Septemba 2026, hivyo logi hiyo ni ndefu na inafaa kusomwa kwa umakini.

Hifadhi nakala (backup) kwanza, kila wakati, kwa sababu database migrations huendeshwa wakati wa kuanza (startup) na migration iliyofeli kwenye mradi unaotoa releases kwa kasi hii ni tatizo lako la kutatua:

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

Kisha check out tag mpya na ujenge upya (rebuild) kwa kutumia docker compose -f docker/docker-compose.yml up -d --build. Ikiwa mambo yataenda vibaya, kurudi kwenye tag ya zamani na kujenga upya kutarejesha code, lakini ni tarball pekee itakayorejesha database.

Tarball hiyo inashikilia octop.db, config.json, siri ya kusaini JWT (JWT signing secret) na credential.txt, kwa hivyo ni nyeti kama seva yenyewe. Iweke katika mode 600 na uweke nakala nje ya seva hiyo. Kwa usakinishaji mkubwa zaidi, mradi huu pia hutoa docker/docker-compose.postgres.yml, ambayo huendesha PostgreSQL na pgvector badala ya SQLite.

Njia za kushindwa, pamoja na ujumbe utakaouona

Health check haijibu kamwe. curl http://127.0.0.1:8088/api/health inakwama au inakataa. Soma docker compose -f docker/docker-compose.yml logs -f octop. Container inayojifunga wakati wa init ya kwanza kwa kawaida inashindwa kuandika kwenye saraka ya data, kwa hivyo hakikisha umiliki wa njia uliyoiweka kwenye OCTOP_DATA.

Dashboard inafunguka lakini chat inakwama. Hakuna kosa kwenye ukurasa, hakuna jibu linalokuja. Fungua console ya kivinjari na utafute muunganisho ulioshindwa kwenye wss://octop.example.com/api/agents/.../chat/ws. Proxy haipeleki upgrade. Ongeza proxy_http_version 1.1 na vichwa vya habari (headers) vya Upgrade na Connection.

Jibu lote linaonekana kwa mara moja, likiwa limechelewa kwa sekunde kadhaa. Streaming inafanya kazi, buffering imewashwa. Weka proxy_buffering off.

bind: address already in use. Kuna kitu kingine kinachotumia 8088. sudo ss -tlnp | grep 8088 kitakitaja. Hili pia ndilo unalopata ukiongeza ingizo la pili la ports kwenye faili ya override badala ya kuhariri faili asilia.

Nenosiri sahihi linakataliwa. Majaribio matano mabaya yanasababisha kufungiwa kwa sekunde 900. Subiri muda huo upite badala ya kusakinisha upya.

Nenosiri jipya katika .env halikuwa na athari. Vitambulisho hivyo vinatumika wakati wa init ya kwanza pekee. Badilisha kwenye dashboard.

Agent anajibu lakini haendeshi zana (tool). Hili karibu kila mara ni tatizo la model ya ndani: dirisha la muktadha (context window) ni dogo mno kwa ufafanuzi wa zana, au model ni dhaifu katika kuitisha utendaji (function calling). Ongeza num_ctx na ujaribu model iliyoundwa kwa ajili ya matumizi ya zana.

FAQ

Je, Octop ni mbadala wa Open WebUI?

Ni mbadala ikiwa tu unahitaji vipengele vinavyoongezwa na Octop. Open WebUI ni kiolesura cha gumzo mbele ya model na hufanya kazi hiyo vizuri kwa mtu mmoja au kaya inayotegemeana. Octop huongeza akaunti zenye nafasi ya admin, nafasi za kazi (workspaces) na vitambulisho kwa kila mtumiaji, na maktaba ya mawakala maalum inayoweza kubadilishwa, hivyo watu kadhaa wanaweza kutumia seva moja bila kushiriki historia moja. Ikiwa akaunti moja inakutosha, Open WebUI ni chaguo rahisi na lililokomaa zaidi.

Kwa nini nisitumie script ya usakinishaji ya Octop kupitia curl?

Script hiyo hutolewa kutoka kwenye Tencent Cloud Object Storage badala ya kutoka kwenye repository, hivyo haijafunikwa na git tag au commit yoyote. Huwezi kulinganisha kile inachofanya leo na kile ilichofanya wiki iliyopita, na kuipitisha kwenye bash huifanya ianze kufanya kazi kabla hujaisoma. Pia, inasakinisha kwenye host ikiwa na mazingira yake ya Python 3.12, nje ya package manager yako. Ipakue na uisome kwanza, au iweke kwa kutumia Docker Compose kutoka kwenye tag iliyothibitishwa.

Je, Octop inaweza kutumia model ya ndani badala ya API ya kulipia?

Ndiyo. Octop inatumia API zinazoendana na OpenAI na inakuja na preset ya Ollama, hivyo kuielekeza kwenye http://host.docker.internal:11434/v1 hufanya kazi pindi tu unapoongeza extra_hosts: ["host.docker.internal:host-gateway"] kwenye container na kuweka OLLAMA_HOST=0.0.0.0:11434 kwenye host. Fungua port 11434 kwenye firewall kuelekea kwenye anuwai ya anwani za Docker, kwa sababu Ollama haina uthibitishaji (authentication) wake. Tarajia kuongeza num_ctx ya Ollama hadi 16k au zaidi, kwa sababu maelekezo ya mawakala (agent prompts) yenye ufafanuzi wa zana huzidi ukubwa wa dirisha la muktadha (context window) na model huacha kutumia zana hizo.

Je, nahitaji reverse proxy, au ninaweza kufungua port 8088?

Unahitaji proxy. Faili ya Compose ya Octop huchapisha 8088 kwenye interface zote bila TLS, hivyo nywila na bearer tokens zingepita kwenye mtandao zikiwa wazi (cleartext). Badilisha port iliyochapishwa kuwa 127.0.0.1:8088:8088 na uweke Caddy au nginx mbele yake ikiwa na cheti. Ukitumia nginx, peleka mbele (forward) WebSocket upgrade headers na uweke proxy_buffering off, vinginevyo ukurasa utapakia lakini gumzo halitajibu.

Je, Octop iko tayari kwa matumizi ya uzalishaji (production)?

Ilikuwa kabla ya 1.0 na ilikuwa ikitoa releases kadhaa zilizotambulishwa (tagged) kila wiki kufikia Agosti 2026. Ilitoa v1.0.0 mnamo 14 Septemba 2026, kisha ikatoa mfululizo wa 1.0.2 beta tags kabla ya toleo thabiti la v1.0.2 mnamo 18 Oktoba 2026. Kasi hiyo bado ni kubwa, hivyo ichukulie kama programu yenye matumaini badala ya iliyotulia. Hii inafaa kwa familia au timu ndogo ya ndani ikiwa utafunga (pin) tag kamili, utasoma commit log kabla ya kila upgrade, na kuchukua backup ya data volume kabla ya kila rebuild. Usiiendeshe kwenye latest, na usiweke data za wateja ndani yake kwa sasa.