راهنمای نصب و اجرای Octop به صورت Self-hosted با Docker

Octop چیست و چرا باید آن را به صورت self-hosted اجرا کنید

Octop یک دستیار هوش مصنوعی self-hosted برای یک خانواده یا یک تیم کوچک است. دلیل اصلی برای اجرای Octop به جای استفاده از یک رابط کاربری ساده چت، تفکیک کاربران از یکدیگر است. Open WebUI یک رابط مرورگر در اختیار شما می‌گذارد که در مقابل یک مدل قرار می‌گیرد. Octop قابلیت تعریف حساب‌های کاربری با نقش مدیر، فضای کاری اختصاصی و مجموعه‌ای از اعتبارنامه‌ها برای هر کاربر، و همچنین کتابخانه‌ای از عامل‌های (agent) تخصصی را اضافه می‌کند که هر کاربر می‌تواند برای هر وظیفه بین آن‌ها جابه‌جا شود. این همان تفاوتی است که اجازه می‌دهد یک VPS به جای یک نفر، به پنج نفر سرویس‌دهی کند.

این پروژه در github.com/TencentCloud/Octop قرار دارد. این برنامه یک پردازش واحد است که یک داشبورد وب، رابط خط فرمان، کانال‌های چت (Feishu، DingTalk، QQ، Discord، WeCom) و وظایف زمان‌بندی‌شده را ارائه می‌دهد که همگی توسط یک دیتابیس SQLite در مسیر ~/.octop/ پشتیبانی می‌شوند. تمام مطالب زیر بر اساس تگ v0.9.19 نوشته شده است که در تاریخ 5 آگوست 2026 منتشر شد. اگر هنوز در حال تصمیم‌گیری بین پلتفرم‌های مختلف هستید، مقایسه جایگزین‌های Open WebUI که می‌توانید روی یک VPS اجرا کنید حوزه وسیع‌تری را پوشش می‌دهد.

یک نکته که باید پیش از صرف وقت برای آن روشن باشد: Octop نرم‌افزاری پیش از نسخه 1.0 است که توسط سازمان GitHub یک فروشنده منتشر شده و تا آگوست 2026 حدود 900 ستاره دریافت کرده است. این پروژه به سرعت در حال تغییر است، شماره نسخه‌ها گویای این موضوع هستند و هیچ‌کدام از مطالب اینجا تضمینی برای یک مسیر ارتقای پایدار نیست. یک تگ را ثابت (pin) کنید، changelog را بخوانید و از داده‌ها نسخه پشتیبان تهیه کنید.

پیش‌نیازهای شروع کار

• یک سرور مجازی (VPS) با سیستم‌عامل Ubuntu 24.04 که Docker Engine و افزونه Compose روی آن نصب شده باشد. اگر با Compose آشنا نیستید، با مبانی Docker Compose برای VPS شروع کنید.
• git، زیرا قرار است به جای دریافت (pull) یک image، یک release tag را checkout کنید.
• یک نام دامنه که به VPS اشاره می‌کند، زیرا قصد دارید از TLS (امنیت لایه انتقال) در مقابل این سرویس استفاده کنید.
• یک مدل backend که از OpenAI API پشتیبانی کند: یک نمونه محلی Ollama، یک gateway شخصی‌سازی‌شده (self-hosted) یا یک کلید API پولی.

Octop به خودی خود سبک است. این برنامه یک پردازش Python و یک فایل SQLite است. بار اصلی بر دوش مدل backend است؛ بنابراین اگر قصد دارید مدل را روی همان سرور اجرا کنید، منابع سرور را متناسب با نیاز مدل انتخاب کنید.

چرا استفاده از نصب‌کننده curl را توصیه نمی‌کنیم

فایل README با یک دستور نصب تک‌خطی شروع می‌شود:

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

ما استفاده از این روش را روی سروری که برایتان اهمیت دارد توصیه نمی‌کنیم؛ دلیل آن مشخص است: این اسکریپت در مخزن (repository) پروژه قرار ندارد. این فایل از یک bucket در Tencent Cloud Object Storage سرویس‌دهی می‌شود. هیچ‌کدام از بخش‌های آن تحت پوشش git tag یا commit نیست، بنابراین نمی‌توانید اسکریپت امروز را با نسخه هفته گذشته مقایسه (diff) کنید و هیچ تاریخچه‌ای برای توضیح تغییرات وجود ندارد. این bucket می‌تواند فردا بایت‌های متفاوتی را ارائه دهد و هیچ بخشی از پروژه آن را ثبت نمی‌کند. همچنین، ارسال مستقیم خروجی به bash به این معناست که ماشین، اسکریپت را پیش از آنکه حتی یک خط از آن را خوانده باشید، اجرا می‌کند.

این نصب‌کننده همچنین به جای استفاده از container، مستقیماً روی میزبان (host) می‌نویسد. این ابزار از uv برای دریافت Python 3.12 و ساخت محیطی استفاده می‌کند که مدیریت بسته (package manager) سیستم شما هیچ اطلاعی از آن ندارد؛ بنابراین حذف آن در آینده یک کار دستی خواهد بود.

دو گزینه بهتر وجود دارد. اسکریپت را دریافت کنید، آن را بخوانید و سپس اجرا کنید که تنها 30 ثانیه زمان می‌برد: ابتدا curl -fsSL <url> -o install.sh، سپس less install.sh و در نهایت bash install.sh. یا از Docker استفاده کنید که موضوع باقی این راهنماست. بسته PyPI (pip install octop) حداقل یک artifact نسخه‌بندی‌شده است که می‌توانید آن را روی یک release خاص ثابت (pin) کنید.

استقرار Octop با Docker Compose، نسخه v0.9.19

تا آگوست 2026 هیچ ایمیج منتشرشده‌ای برای دریافت (pull) وجود ندارد. فایل Compose ارائه‌شده، ایمیج را از مخزن (repository) می‌سازد، بنابراین ثابت نگه‌داشتن نسخه به معنای checkout کردن یک git tag است. این کار یک مرحله بیشتر از اکثر پروژه‌های self-hosted است، زیرا چیزی مانند یک فضای کاری AFFiNE خودمیزبان به یک تگ ایمیج منتشرشده متصل می‌شود و هرگز چیزی را روی VPS شما نمی‌سازد. روال clone، checkout و build در ادامه، همان روالی است که راهنمای استقرار openGym طی می‌کند، بنابراین اگر قبلاً آن را تنظیم کرده‌اید، با ساختار آن آشنا هستید.

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

این سرویسی است که فایل تعریف می‌کند، که به بخش‌های مهم محدود شده است:

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: توجه کنید. image: octop:latest نامی است که build شما دریافت می‌کند، نه یک ارجاع به registry، بنابراین latest در اینجا به معنای هر چیزی است که اخیراً کامپایل کرده‌اید. مسیر داده (data path) را به جای رها کردن در حالت پیش‌فرض، روی یک مسیر مشخص تنظیم کنید و پیش از اولین راه‌اندازی، یک رمز عبور واقعی برای حساب کاربری مدیر تعیین کنید. این موارد را در docker/.env قرار دهید:

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

یک تله در اینجا وجود دارد که از بقیه فایل مهم‌تر است. Compose فایل docker/.env را فقط برای جایگذاری (interpolate) متغیرهای ${...} در YAML می‌خواند. کلیدی که به آن فایل اضافه می‌کنید، تا زمانی که در بخش environment: در فایل Compose لیست نشود، به container نمی‌رسد. افزودن OCTOP_ACCESS_TOKEN_TTL به .env به تنهایی هیچ کاری انجام نمی‌دهد و هیچ خطایی هم نمی‌دهد. جایگزین آن، نوشتن همان کلیدها در ~/.octop/env داخل دایرکتوری داده‌های mount شده است که Octop هنگام شروع بارگذاری می‌کند. راهنمای فایل‌های env و secrets در Docker Compose توضیح می‌دهد که چرا این دو مکانیزم یکسان نیستند.

آن را بسازید و اجرا کنید:

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) سالم به بررسی سلامت (health check) با {"status":"ok","version":"..."} پاسخ می‌دهد. در صورت دریافت هر پاسخ دیگری، پیش از باز کردن مرورگر، docker compose -f docker/docker-compose.yml logs -f octop را بخوانید.

حالا به ایمیجی که ساخته‌اید یک نام معنادار بدهید، زیرا --build بعدی، octop:latest را بازنویسی می‌کند و دیگر راهی برای تشخیص این دو از هم نخواهید داشت:

docker image tag octop:latest octop:0.9.19

اولین راه‌اندازی، octop init را اجرا کرده و اعتبارنامه‌های اولیه را در volume داده می‌نویسد:

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

مقادیر پیش‌فرض admin / octop هستند و فقط در اولین مقداردهی اولیه (init) اعمال می‌شوند. این همان مکانیزمی است که پاسخ سوالی است که مردم دائماً می‌پرسند: تغییر OCTOP_DEFAULT_PASSWORD پس از اینکه container یک بار اجرا شده است، هیچ تغییری ایجاد نمی‌کند، زیرا حساب کاربری از قبل وجود دارد. رمز عبور را از داخل داشبورد تغییر دهید.

پورت 8088 را منتشر نکنید

خط ports: در بالا، تمام رابط‌های شبکه روی VPS را به این پورت متصل می‌کند. به محض شروع کانتینر، داشبورد با رمز عبور پیش‌فرض و بدون رمزنگاری روی اینترنت عمومی در دسترس قرار می‌گیرد. مقدار پیش‌فرض OCTOP_BIND_HOST در خود Octop برابر با 127.0.0.1 است؛ فایل Compose آن را به 0.0.0.0 تغییر می‌دهد زیرا پردازش باید ترافیک را از خارج از فضای نام شبکه خود بپذیرد. این تغییر صحیح است، اما بخشی که شما را در معرض خطر قرار می‌دهد، انتشار پورت (published port) است.

خط ports: را در docker/docker-compose.yml ویرایش کنید تا نگاشت فقط روی loopback گوش دهد:

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

سعی نکنید این مورد را با یک فایل override ساده اصلاح کنید. Compose لیست‌های ports را از چندین فایل به هم می‌چسباند (concatenate) و جایگزین نمی‌کند؛ بنابراین در نهایت هر دو نگاشت منتشر می‌شوند و دومی در اتصال به پورت شکست می‌خورد. اگر می‌خواهید فایل اصلی بدون تغییر باقی بماند، از تگ !override روی دنباله استفاده کنید که روش مستند برای جایگزینی به‌جای الحاق است. توضیح نحوه ادغام چندین فایل توسط Compose سایر قوانین ادغام را پوشش می‌دهد.

اتصال به loopback همچنین مشکلی را که در غیر این صورت با فایروال داشتید، حل می‌کند. Docker قوانین پورت‌های منتشرشده خود را در جدول nat پیش از زنجیره‌هایی که ufw مدیریت می‌کند می‌نویسد، بنابراین ufw deny 8088 جلوی پورت کانتینر منتشرشده را نمی‌گیرد. پورتی که به 127.0.0.1 متصل شده باشد، فارغ از تنظیمات ufw، هرگز از خارج قابل دسترسی نیست و به همین دلیل این راهکار، بهترین روش اصلاح است.

قرار دادن TLS در مقابل با استفاده از reverse proxy

Caddy کوتاه‌ترین مسیر است، زیرا گواهی را به‌طور خودکار از طریق ACME (محیط مدیریت خودکار گواهی) درخواست می‌کند و بدون نیاز به تنظیمات اضافی، WebSockets را پروکسی می‌کند:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx به دقت بیشتری نیاز دارد، زیرا Octop چت را از طریق 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;
    }
}

هر خط در اینجا وظیفه‌ای دارد. چت روی WS /agents/{id}/chat/ws اجرا می‌شود، بنابراین بدون proxy_http_version 1.1 و دو هدر upgrade، nginx به تلاش برای ارتقا با 400 Bad Request پاسخ می‌دهد: داشبورد به‌طور عادی بارگذاری می‌شود اما هر پیامی که ارسال می‌کنید برای همیشه معلق می‌ماند، بدون اینکه خطایی در صفحه نمایش داده شود. proxy_buffering off اهمیت دارد زیرا endpoint مربوط به resume در human-in-the-loop مقدار text/event-stream را برمی‌گرداند و SSE (رویدادهای ارسال‌شده از سمت سرور) که در بافر پروکسی نگه داشته شده‌اند، به‌جای استریم شدن، در انتها به‌صورت یکجا دریافت می‌شوند. proxy_read_timeout اجرای طولانی ابزارها را پوشش می‌دهد، زیرا مقدار پیش‌فرض 60 ثانیه باعث قطع شدن عامل در میانه کار و ثبت خطای upstream timed out (110: Connection timed out) در لاگ‌ها می‌شود.

نحوه عملکرد احراز هویت JWT پشت پروکسی

Octop با استفاده از توکن bearer احراز هویت می‌کند، نه کوکی. POST /api/auth/login مقدار {access_token, role, user, ...} را برمی‌گرداند و فراخوانی‌های بعدی شامل Authorization: Bearer <access_token> هستند. برای یک reverse proxy، این خبر خوبی است: هیچ دامنه کوکی، پرچم Secure یا قانون SameSite برای اشتباه کردن وجود ندارد، بنابراین نشست (session) که روی http://127.0.0.1:8088 کار می‌کرد، روی https://octop.example.com نیز به همان شکل عمل می‌کند.

پیش از آنکه کاربران واقعی را به آن منتقل کنید، دانستن دو پیامد زیر ضروری است.

وب‌سوکت (WebSocket) توکن را در URL حمل می‌کند. نقطه پایانی WS /agents/{id}/chat/ws?token=<jwt> است، زیرا JavaScript مرورگر نمی‌تواند هدر Authorization را در handshake وب‌سوکت تنظیم کند. TLS از این توکن در حین انتقال محافظت می‌کند، اما آن را در برابر لاگ‌های خودتان محافظت نمی‌کند: nginx به‌طور پیش‌فرض کل خط درخواست، شامل query string را در access_log می‌نویسد، بنابراین توکن فعال یک کاربر واقعی در یک فایل متنی ساده روی سرور ذخیره می‌شود. مسیر را بدون آرگومان‌ها لاگ کنید. $uri مسیر نرمال‌شده‌ای است که query string از آن حذف شده است، بنابراین آن را در بلوک http قرار دهید و از سرور به آن ارجاع دهید:

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;

امکان خروج (logout) برای هر نشست وجود ندارد. مقدار پیش‌فرض OCTOP_ACCESS_TOKEN_TTL برابر با 86400 است، بنابراین توکن تا 24 ساعت پس از ورود معتبر باقی می‌ماند. تنها روش مستند برای باطل کردن توکن، octop admin rotate-jwt-secret است که کلید امضای ذخیره‌شده در ~/.octop/secrets/jwt_secret را تغییر می‌دهد و تمام توکن‌های موجود را بلافاصله برای همه باطل می‌کند. بنابراین وقتی کسی تیم را ترک می‌کند، ترتیب کار به این صورت است: حذف کاربر، تغییر secret، و سپس درخواست از سایر کاربران برای ورود مجدد. اگر این روش سنگین به نظر می‌رسد، طول عمر توکن را کاهش دهید و به یاد داشته باشید که متغیر را به لیست environment: و همچنین .env اضافه کنید:

OCTOP_ACCESS_TOKEN_TTL=28800

حملات brute force مدیریت شده‌اند: مقدار پیش‌فرض OCTOP_LOGIN_MAX_ATTEMPTS برابر با 5 تلاش ناموفق و OCTOP_LOGIN_LOCKOUT_SECONDS برابر با 900 ثانیه است، بنابراین کاربری که دسترسی‌اش قفل شده، به‌جای مواجهه با یک نصب خراب، فقط 15 دقیقه منتظر می‌ماند. Octop دارای مخزن کاربری اختصاصی خود است و در نسخه v0.9.19 از OIDC پشتیبانی نمی‌کند، بنابراین اگر به Single Sign-On واقعی نیاز دارید، باید یک پروکسی احراز هویت در مقابل آن قرار دهید، که این دقیقاً همان کاری است که یک سرور Authentik خودمیزبان برای آن طراحی شده است.

تنظیم Octop برای استفاده از یک مدل backend

ارائه‌دهندگان (Providers) برای هر عامل (agent) در داشبورد پیکربندی می‌شوند و octop provider list تنظیمات فعلی را به شما نشان می‌دهد. Octop به‌صورت پیش‌فرض از APIهای سازگار با OpenAI، DashScope (Qwen) و Ollama پشتیبانی می‌کند و اعتبارنامه‌ها در جدول providers در پایگاه‌داده SQLite خودتان ذخیره می‌شوند. انتخاب شما تعیین می‌کند که چه هزینه‌ای بپردازید و چه داده‌ای از سرور خارج شود.

استفاده از مدل محلی با Ollama. در این حالت هیچ داده‌ای از سرور خارج نمی‌شود و هزینهٔ شما به‌جای توکن، مصرف RAM است. نکتهٔ فنی که معمولاً باعث سردرگمی می‌شود این است که یک کانتینر نمی‌تواند به Ollama میزبان در 127.0.0.1:11434 دسترسی پیدا کند، زیرا این آدرس، loopback خودِ کانتینر است. برای رفع این مشکل، یک host gateway به سرویس اضافه کنید:

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

سپس base URL ارائه‌دهنده را روی http://host.docker.internal:11434/v1 تنظیم کنید که مسیر سازگار با OpenAI در Ollama است. در فیلد API key هر رشتهٔ غیرخالی وارد کنید؛ Ollama آن را نادیده می‌گیرد اما کلاینت‌های OpenAI از ارسال فیلد خالی خودداری می‌کنند. برای عملکرد صحیح، Ollama باید فراتر از loopback گوش دهد که این کار مستلزم OLLAMA_HOST=0.0.0.0:11434 در فایل systemd unit آن است. این بخش ریسک دارد: Ollama احراز هویت ندارد، بنابراین باز بودن پورت 11434 روی یک IP عمومی به این معناست که هر کسی که آن را اسکن کند، به سرور مدل شما دسترسی رایگان خواهد داشت. فقط محدودهٔ خصوصی Docker یعنی sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp را مجاز کنید و بقیه را مسدود نمایید. مقالهٔ اجرای Ollama روی VPS به بررسی ابعاد مدل می‌پردازد و مقایسه Ollama و vLLM توضیح می‌دهد که چه زمانی Ollama دیگر گزینهٔ مناسبی نیست.

یک هشدار دیگر دربارهٔ مدل‌های محلی: موردی وجود دارد که شبیه باگ در Octop به نظر می‌رسد اما باگ نیست. عامل‌ها با فراخوانی ابزارها کار می‌کنند و prompt سیستم به همراه تعریف ابزارها و تاریخچه، یک prompt حجیم ایجاد می‌کند. Ollama مدل‌ها را با یک پنجرهٔ context پیش‌فرض محدود ارائه می‌دهد، بنابراین ابتدای prompt که محل قرارگیری تعریف ابزارهاست، از پنجره خارج می‌شود. در نتیجه مدل یا فراخوانی ابزارها را متوقف می‌کند یا ابزارهایی اختراع می‌کند که وجود ندارند. مقدار num_ctx را به 16k یا 32k افزایش دهید و مدلی انتخاب کنید که در فراخوانی توابع (function calling) عملکرد خوبی داشته باشد. اگر پاسخ‌ها در میانهٔ جمله قطع می‌شوند، مشکل مربوط به تنظیم دیگری به نام num_predict است؛ بنابراین اگر پاسخ‌ها ناقص هستند، پیش از مقصر دانستن عامل، بررسی کنید که num_predict کجا تنظیم شده و done_reason چه مقداری دارد. اگر ترجیح می‌دهید به‌جای لیست کوتاه، از یک کاندیدای خاص شروع کنید، Nemotron 3.5 Lightning ارزش امتحان کردن را دارد و آن مستندات، تگ دقیق برای pull کردن، میزان RAM مورد نیاز و اینکه آیا اجرای آن فقط با CPU پاسخگوست یا خیر را مشخص کرده است.

استفاده از gateway خود-میزبانی‌شده. با قرار دادن یک gateway LiteLLM خود-میزبانی‌شده بین Octop و سایر سرویس‌ها، شما یک base URL واحد، کلیدهای مجزا برای هر کاربر، محدودیت‌های هزینه و لاگ متمرکز خواهید داشت. همچنین می‌توانید مدل پشت آن را بدون نیاز به ویرایش هیچ‌چیزی در Octop تغییر دهید.

استفاده از API پولی. بهترین کیفیت با یک بده‌بستان صادقانه: محتوای گفتگو از سرور شما خارج شده و به ارائه‌دهنده می‌رسد، که این دقیقاً همان چیزی است که self-hosting برای جلوگیری از آن انجام می‌شود. کلید در docker/.env به عنوان OPENAI_API_KEY وارد می‌شود که فایل Compose از قبل آن را عبور می‌دهد.

هر کدام را که انتخاب کنید، فایل Compose شامل OCTOP_LANGFUSE_ENABLED، LANGFUSE_PUBLIC_KEY، LANGFUSE_SECRET_KEY و LANGFUSE_BASE_URL نیز هست؛ بنابراین می‌توانید traceها را به نمونهٔ Langfuse خودتان ارسال کنید و به‌جای حدس زدن از روی پنجرهٔ چت، ببینید عامل‌ها واقعاً چه کاری انجام می‌دهند.

کاربران، نقش‌ها و کتابخانه مشترک عامل‌ها

حساب کاربری مدیر که در اولین راه‌اندازی ایجاد می‌شود، وظیفه مدیریت سایر کاربران را بر عهده دارد. هر کاربر عامل‌ها، فضای کاری و اعتبارنامه‌های اختصاصی خود را دارد و این جداسازی از طریق توکنی که در مرورگر ذخیره می‌شود، اعمال می‌گردد. در کنار این موارد، مجموعه‌ای مشترک از مهارت‌ها و زیر-عامل‌ها وجود دارد که همه کاربران به آن دسترسی دارند؛ این همان قابلیتی است که استفاده از این سیستم را برای خانواده‌ها ارزشمند می‌کند: یک نفر عامل پژوهشی کارآمدی را می‌سازد و دیگر نیازی نیست سایرین دوباره آن را طراحی کنند.

در استفاده از ابزارها دقت کنید. Octop قابلیت تأیید ابزارها و محافظت از دستورات shell را ارائه می‌دهد و هر دو مورد واقعی هستند، اما عاملی که دستورات shell را اجرا می‌کند، این کار را درون کانتینر Octop و با mount شدن volume داده‌های شما انجام می‌دهد. این محافظ‌ها تنها اثرات یک دستور ناخواسته یا اشتباه را کاهش می‌دهند. آن‌ها یک محیط ایزوله (sandbox) امن نیستند؛ بنابراین برای هر کسی که حاضر نیستید دسترسی مستقیم shell به او بدهید، قابلیت تأیید ابزارها را فعال نگه دارید. اگر در حال مقایسه این گزینه با سایر موارد هستید، بررسی جامع عامل‌های هوش مصنوعی self-hosted نحوه مدیریت این موضوع در هر کدام را مقایسه کرده است.

ارتقای پروژه‌ای که با این سرعت منتشر می‌شود

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

این‌ها تاریخ‌های تگ‌های مخزن هستند که تا 7 اوت 2026 محاسبه شده‌اند. 4 نسخه تگ‌شده در نه روز منتشر شده‌اند، با فاصله‌ای به کوتاهی 1 روز، و نسخه v0.9.19 که 3 روز پس از تگ قبلی خود رسیده است. این سرعت انتشار نشانه خوبی برای پروژه است اما دلیل بدی برای اجرای بی‌محابای latest محسوب می‌شود. پیش از اعمال تغییرات، آن‌ها را مطالعه کنید:

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"

همیشه ابتدا نسخه پشتیبان تهیه کنید، زیرا migrationهای دیتابیس در زمان راه‌اندازی اجرا می‌شوند و یک migration ناموفق در پروژه‌ای که هنوز به نسخه 1.0 نرسیده، مشکلی است که حل آن بر عهده خودتان خواهد بود:

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

سپس تگ جدید را checkout کرده و با استفاده از docker compose -f docker/docker-compose.yml up -d --build بازسازی (rebuild) کنید. اگر مشکلی پیش آمد، checkout کردن تگ قدیمی و بازسازی مجدد، کد را بازمی‌گرداند، اما فقط فایل tarball می‌تواند دیتابیس را بازیابی کند.

آن فایل tarball شامل octop.db، config.json، کلید امضای JWT و credential.txt است، بنابراین به اندازه خود سرور حساس است. دسترسی آن را روی 600 تنظیم کنید و یک نسخه از آن را خارج از سرور نگهداری کنید. برای نصب‌های بزرگ‌تر، این پروژه docker/docker-compose.postgres.yml را نیز ارائه می‌دهد که به جای SQLite، از PostgreSQL به همراه pgvector استفاده می‌کند.

حالت‌های شکست و پیام‌های مربوط به آن‌ها

بررسی سلامت (health check) هرگز پاسخ نمی‌دهد. curl http://127.0.0.1:8088/api/health متوقف می‌شود یا پاسخ نمی‌دهد. docker compose -f docker/docker-compose.yml logs -f octop را مطالعه کنید. کانتینری که در اولین راه‌اندازی خارج می‌شود، معمولاً نمی‌تواند در دایرکتوری داده بنویسد؛ بنابراین مالکیت مسیری که به OCTOP_DATA اختصاص داده‌اید را بررسی کنید.

داشبورد بارگذاری می‌شود اما چت متوقف می‌ماند. هیچ خطایی در صفحه نمایش داده نمی‌شود و پاسخی دریافت نمی‌شود. کنسول مرورگر را باز کنید و به دنبال اتصال ناموفق به wss://octop.example.com/agents/.../chat/ws بگردید. پروکسی در حال انتقال (forward) درخواست upgrade نیست. proxy_http_version 1.1 و هدرهای Upgrade و Connection را اضافه کنید.

کل پاسخ به‌صورت یکجا و با تأخیر چند ثانیه‌ای ظاهر می‌شود. استریمینگ کار می‌کند اما بافرینگ فعال است. مقدار proxy_buffering off را تنظیم کنید.

bind: address already in use. یک سرویس دیگر پورت 8088 را اشغال کرده است. sudo ss -tlnp | grep 8088 نام آن سرویس را مشخص می‌کند. اگر به‌جای ویرایش فایل اصلی، یک ورودی ports دوم در فایل override اضافه کرده باشید، همین خطا را دریافت خواهید کرد.

رمز عبور صحیح رد می‌شود. پنج تلاش ناموفق باعث قفل شدن 900 ثانیه‌ای می‌شود. به‌جای نصب مجدد، منتظر بمانید تا زمان قفل تمام شود.

رمز عبور جدید در .env تأثیری نداشت. آن اعتبارنامه‌ها فقط در اولین راه‌اندازی اعمال می‌شوند. رمز عبور را از داخل داشبورد تغییر دهید.

ایجنت پاسخ می‌دهد اما هیچ ابزاری را اجرا نمی‌کند. این مشکل تقریباً همیشه مربوط به مدل محلی است: پنجره کانتکست برای تعاریف ابزار بسیار کوچک است یا مدل در فراخوانی توابع ضعیف عمل می‌کند. مقدار num_ctx را افزایش دهید و از مدلی استفاده کنید که برای استفاده از ابزارها ساخته شده است.

FAQ

آیا Octop جایگزینی برای Open WebUI است؟

تنها در صورتی که به قابلیت‌های اضافه‌شدهٔ آن نیاز داشته باشید. Open WebUI یک رابط کاربری چت برای مدل‌های زبانی است و این وظیفه را برای یک نفر یا یک خانوادهٔ قابل‌اعتماد به‌خوبی انجام می‌دهد. Octop امکاناتی نظیر حساب‌های کاربری با نقش مدیر، فضای کاری و اعتبارنامه‌های اختصاصی برای هر کاربر، و کتابخانه‌ای از عوامل (agents) تخصصی با قابلیت جابه‌جایی را اضافه می‌کند؛ بنابراین چندین نفر می‌توانند بدون اشتراک‌گذاری تاریخچهٔ چت، از یک سرور استفاده کنند. اگر یک حساب کاربری برای شما کافی است، Open WebUI گزینهٔ ساده‌تر و بسیار بالغ‌تری محسوب می‌شود.

چرا نباید از اسکریپت نصب curl برای Octop استفاده کنم؟

این اسکریپت از یک باکت Tencent Cloud Object Storage ارائه می‌شود و نه از مخزن اصلی، بنابراین تحت پوشش هیچ git tag یا commit خاصی نیست. شما نمی‌توانید عملکرد امروز آن را با عملکرد هفتهٔ گذشته مقایسه کنید و ارسال مستقیم آن به bash باعث می‌شود پیش از آنکه آن را بخوانید، اجرا شود. همچنین این اسکریپت، برنامه را با محیط Python 3.12 اختصاصی خود و خارج از مدیریت بسته (package manager) سیستم شما نصب می‌کند. ابتدا آن را دانلود و مطالعه کنید، یا با استفاده از Docker Compose و یک tag مشخص، آن را مستقر کنید.

آیا Octop می‌تواند به‌جای APIهای پولی از مدل‌های محلی استفاده کند؟

بله. Octop از APIهای سازگار با OpenAI پشتیبانی می‌کند و دارای یک پیش‌تنظیم برای Ollama است؛ بنابراین پس از افزودن extra_hosts: ["host.docker.internal:host-gateway"] به کانتینر و تنظیم OLLAMA_HOST=0.0.0.0:11434 روی میزبان، اتصال آن به http://host.docker.internal:11434/v1 به‌درستی کار می‌کند. پورت 11434 را روی محدودهٔ آدرس‌های Docker فایروال کنید، زیرا Ollama به‌صورت پیش‌فرض احراز هویت ندارد. انتظار داشته باشید که num_ctx در Ollama را به 16k یا بیشتر افزایش دهید، زیرا پرامپت‌های عوامل (agent prompts) همراه با تعاریف ابزارها، از پنجرهٔ کانتکست پیش‌فرض فراتر می‌روند و در نتیجه مدل از فراخوانی ابزارها باز می‌ماند.

آیا به reverse proxy نیاز دارم یا می‌توانم پورت 8088 را باز بگذارم؟

شما به proxy نیاز دارید. فایل Compose ارائه‌شده توسط Octop، پورت 8088 را بدون TLS روی تمام اینترفیس‌ها منتشر می‌کند؛ بنابراین رمزهای عبور و bearer tokenها به‌صورت متن ساده (cleartext) در اینترنت جابه‌جا خواهند شد. پورت انتشار را به 127.0.0.1:8088:8088 تغییر دهید و Caddy یا nginx را با یک گواهی معتبر در مقابل آن قرار دهید. در nginx، هدرهای WebSocket upgrade را فوروارد کنید و proxy_buffering off را تنظیم نمایید، در غیر این صورت صفحه بارگذاری می‌شود اما چت پاسخی نخواهد داد.

آیا Octop برای محیط عملیاتی (production) آماده است؟

این پروژه هنوز به نسخه 1.0 نرسیده و تا اوت 2026 چندین نسخه (release) در هفته منتشر می‌کند، بنابراین آن را به‌عنوان یک پروژهٔ امیدوارکننده در نظر بگیرید، نه یک محصول نهایی و تثبیت‌شده. اگر یک tag دقیق را ثابت کنید، پیش از هر ارتقا لاگ commitها را بخوانید و قبل از هر بازسازی (rebuild) از volume داده‌ها نسخه پشتیبان تهیه کنید، استفاده از آن برای یک خانواده یا تیم کوچک داخلی مناسب است. آن را روی latest اجرا نکنید و هنوز داده‌های مشتریان را در آن قرار ندهید.