Skip to main content

معماری کلی GCAT — نسخه هدف (v3)

تاریخ: ۱۴۰۵/۰۹/۰۱ · وضعیت: طرح / ایده‌پردازی (هیچ تغییری اجرا نشده) مبنا: ممیزی واقعی سرور yotta-gcat + تصمیم‌های صریح بنیان‌گذار

تصمیم‌های قطعی‌شده

  • ❌ Swarm حذف (تک‌سرور، Compose کافی است)
  • ❌ Open terminal کلاً خاموش (gateway + شبکه‌ها + volumeها)
  • ❌ code.gcat.ir + سرویس T3 حذف
  • ❌ dsh.gcat.ir + سرویس dsh روی هاست حذف
  • ❌ academia.gcat.ir + کانتینر academia-core حذف (بعد از بکاپ داده)
  • ❌ Panel به Frontend/Backend/DB شکسته نمی‌شود
  • ✅ Engine از Panel جدا می‌شود: دو ایمیج و دو کانتینر، با چرخه انتشار مستقل (مرز جداسازی engine/product است نه FE/BE/DB)
  • ✅ OmniRoute مستقیم از image رسمیِ نسخه‌پین‌شده اجرا می‌شود؛ infra فقط Compose، تنظیمات اجرا و روند ارتقای آن را نگه می‌دارد.
  • 🔄 xray خاموش → 3x-ui جایگزین (بعد از اثبات معادل‌سازی پروکسی)
  • 🔄 ai.gcat.ir → panel.gcat.ir (رابط کاربری پنل)
  • 🆕 api.gcat.ir = تنها endpoint عمومی LLM API (خالص، بدون مسیر پنل)
  • ✅ Grafana به‌عنوان سقف stack نظارتی لاگ‌محور (Loki + Alloy + Prometheus)
  • ✅ Wiki = Docmost (احراز هویت محلی) · مستندات فنی = Fumadocs (static)
  • ✅ CDN = ابرآروان · نام‌گذاری ریپو/ایمیج یکدست و اصولی (بخش ۳)
  • ✅ یافته‌های امنیتی بسته report/ پذیرفته شد: بستن aria2 :6888 · چرخش رازهای plaintext · فایروال nftables+DOCKER-USER · بکاپ از صفر (بخش ۱۰)

۱. نمای کلی

نکته فنی درباره جداسازی engine/panel: امروز روی سرور یک کانتینر (omniroute-panel) هر دو پروسه را با supervisord اجرا می‌کند. جداسازی به دو کانتینر یعنی: آپدیت engine از upstream بدون ری‌بیلد پنل، دیپلوی و rollback مستقل، و限制消费 منابع جدا. هزینه‌اش تقریباً صفر است (همان دو پروسه، فقط در دو کانتینر).

۲. نقشه دامنه → سرویس → پورت (نسخه هدف)

قواعد ثابت nginx:
  • همه vhostها: http2 on + گواهی wildcard معتبر Let’s Encrypt (DNS-01) + snippet مشترک proxy/websocket
  • api.gcat.ir هیچ مسیر پنل/داشبورد ندارد؛ فقط API خالص + rate limit سبک در nginx
  • استاتیک Next هرگز از snapshot هاست سرو نمی‌شود → همیشه پروکسی به خود اپ (درس حادثه 404)
  • real-IP ابرآروان · فقط nginx پورت عمومی · DB/Redis بدون پورت publish
⚠️ وابستگی‌های تغییر دامنه (قبل از سوییچ باید همگی آماده شوند):
  1. رکوردهای DNS جدید در ابرآروان: panel, api (+ حذف code/dsh/academia/oinawofb)
  2. تنظیمات OIDC چت (issuer/redirectها الان auth.gcat.ir هستند) + envهای SSO پنل
  3. کلاینت‌های API موجود که به ai.gcat.ir وصل‌اند → اطلاع‌رسانی + ریدایرکت/alias موقت
  4. گواهی wildcard جدید باید قبل از سوییچ صادر شده باشد

۳. ریپوها و نام‌گذاری (org: G-CAT-Devs)

قرارداد نام‌گذاری

  • ریپو: kebab-case، کوتاه، بدون پیشوند تکراری (org خودش namespace است)
  • ایمیج: ghcr.io/g-cat-devs/<repo>:<git-sha> — نام ایمیج = نام ریپو؛ هرگز latest در production
  • پروژه Compose = نام ریپو · کانتینرها: <project>-<service> (مثلاً chat-db)
  • سرویس‌های third-party (docmost, cloudreve, 3x-ui, grafana…) ریپو نمی‌خواهند؛ compose آن‌ها در infra/apps/ با نسخه pin شده

ریپوهای هدف

سرنوشت ریپوهای موجود

نحوهٔ اجرای OmniRoute

  • تصمیم بنیان‌گذار: هیچ تغییری در کد engine نمی‌دهیم. پس fork و image واسط ارزشی ایجاد نمی‌کنند.
  • Compose در infra/apps/omniroute/ مستقیماً image رسمیِ diegosouzapw/omniroute:<version> را اجرا می‌کند. تگ باید دقیقاً پین شود؛ latest ممنوع است.
  • ارتقای upstream = یک PR که نسخه image را در Compose عوض می‌کند → pull → تست دود → دیپلوی.
  • مرز قرارداد با پنل فقط HTTP است (ENGINE_URL=http://127.0.0.1:20128).
  • اگر روزی نیاز به patch پیدا شد، آن‌وقت fork می‌کنیم — نه زودتر. (قانون: fork آخرین راه‌حل است، نه اولین.)
  • نسخهٔ اجراشده در inventory و پیام deploy ثبت می‌شود تا rollback با تغییر تگ به نسخهٔ قبلی انجام شود.

ساختار infra

Secretها (.env، کلید TLS، توکن بات) فقط روی سرور یا GitHub Secrets — هرگز در Git.

ساختار داخلی ریپوهای جدید

panel (محصول: پنل + فروشگاه + بات):
chat (rename از chat-gcat):
docs (Fumadocs):

۳.۱ نقشه کامل پورت / کانتینر / مسیر روی سرور

قرارداد: همه فایل‌ها زیر /opt/stacks/<stack>/ · همه publishها فقط 127.0.0.1 · DB/Redis بدون publish · نام کانتینر <stack>-<service>. پورت‌های عمومی مجاز: 22 (SSH، فقط کلید + IP مدیریت) · 80 · 443 · inboundهای VPN 3x-ui (صریح در ufw). بقیه همه loopback. داده‌های persistent: /opt/stacks/<stack>/data/ (bind mount) یا volume نام‌دار <stack>_<service>_data — هر stack فقط داده خودش. بکاپ‌ها: /opt/backups/.

۴. جریان دیپلوی

  • تغییر nginx: فقط از infra → nginx -t → reload → smoke-test همه دامنه‌ها
  • دیپلوی engine نباید پنل را restart کند و برعکس (مزیت اصلی جداسازی)
  • Bootstrap سرور جدید = clone infra + BOOTSTRAP.md + restore بکاپ‌ها

۵. داده و بکاپ

۵.۱ بکاپ دوره‌ای به تلگرام (مصوب — روزی یک‌بار)

اسکریپت infra/scripts/backup-to-telegram.sh با systemd timer روزانه (ساعت کم‌ترافیک، مثلاً ۰۴:۰۰):
  1. Dump هر دیتابیس:
    • Postgresها: pg_dump -Fc داخل کانتینر (chat-postgres, cloudreve-db, wiki-db بعداً)
    • SQLiteها (engine/panel): sqlite3 .backup (نه کپی خام فایل — برای consistency)
  2. فشرده‌سازی + رمزنگاری: هر dump → zstd → age با کلید عمومی (کلید خصوصی فقط روی لپ‌تاپ‌های بنیان‌گذاران، هرگز روی سرور). دلیل: دیتابیس چت/فروشگاه حاوی داده کاربر و توکن است؛ کانال تلگرام نباید نسخه plaintext داشته باشد.
  3. ارسال به تلگرام: فایل رمزنگاری‌شده به کانال/گروه خصوصی «GCAT Backups» با بات ops؛ کپشن: نام سرویس + تاریخ + حجم + sha256.
  4. نوتیف نتیجه: خلاصه به گروه ops (موفق ✅ با حجم‌ها / شکست 🔴 فوری). شکست ارسال = alert، نه سکوت.
  5. نگه‌داری محلی: ۷ نسخه آخر در /opt/backups/ (برای restore سریع)؛ پاکسازی خودکار قدیمی‌ها.
  6. تست restore ماهانه: دانلود آخرین فایل از تلگرام → رمزگشایی → restore در کانتینر موقت → گزارش به ops.
محدودیت‌های تلگرام که طراحی باید رعایت کند:
  • سقف آپلود بات: ۵۰MB per file. اگر dump بزرگ‌تر شد → split به قطعات ۴۵MB با پسوند شماره‌دار + اسکریپت reassemble در restore. (dumpهای فعلی کوچک‌اند: کل والیوم‌های DB ~۳.۵GB شامل فایل، خود dumpها احتمالاً ده‌ها MB)
  • تلگرام مقصد ثانویه است نه یگانه: اگر روزی حجم از سقف گذشت یا بات محدود شد، مقصد اصلی object storage (S3 سازگار) جایگزین/مکمل می‌شود — اسکریپت از اول دو-مقصدی نوشته می‌شود (TARGETS=telegram,s3).
  • پیام‌های بکاپ در topic جدا از alertها تا نویز نگیرد.
قانون: بکاپی که restore آن تست نشده، بکاپ نیست. ماهی یک‌بار تست restore.

۶. نظارت، هشدار و نوتیف تلگرام

۶.۱ کانال نوتیف تلگرام (مصوب)

۶.۲ رویدادهایی که حتماً نوتیف می‌شوند

  1. Alertها: دامنه non-200 بیش از ۲ دقیقه · swap > 500MB · دیسک > 85٪ · RAM در دسترس < 1GB · restart کانتینر · SSL < 14 روز · healthcheck شکست‌خورده
  2. Backup: موفق/شکست هر اجرای pg_dump/restic + نتیجه تست restore ماهانه (شکست backup = 🔴 فوری)
  3. Deploy: شروع/موفق/شکست + rollback خودکار هر اپ و nginx (با sha قبل/بعد)
  4. امنیتی: ورود SSH جدید (fail2ban ban) · تغییر کانفیگ nginx خارج از pipeline (drift)
Runbookهای اولیه: 404 استاتیک · فشار swap · گواهی پشت ابرآروان · restart هر سرویس · سوییچ دامنه API. هر incident بعد از حل → ۱۰ دقیقه نوشتن runbook در Docmost.

۷. بودجه منابع (هدف: RAM 16GB)

آزادسازی‌های مصوب: Swarm · terminal · dsh (~220MB) · academia (~100MB) · xray (پس از جایگزینی) · heap از 4GB→2GB · ~۱۰GB آرشیو مایگریشن + کانتینرهای exited. حذف dsh/academia/terminal بخشی از بار جدید را جبران می‌کند، ولی بدون RAM 16GB باز هم فاز ۲ توصیه نمی‌شود.

۸. فازبندی اجرا

۹. ریسک‌ها و سؤال‌های باز

  1. 3x-ui جای xray: اثبات معادل‌سازی پروکسی برای مصرف‌کننده‌های فعلی (احتمالاً engine روی socks 10808) قبل از خاموشی xray.
  2. سوییچ ai→panel/api: کلاینت‌های API موجود نباید بشکنند — alias/ریدایرکت موقت + اطلاع‌رسانی.
  3. OIDC: تغییر دامنه پنل یعنی به‌روزرسانی هم‌زمان envهای چت و پنل؛ سوییچ باید اتمیک باشد.
  4. استخراج panel از omni: باید تاریخچه Git فایل‌های panel حفظ شود (git filter-repo) و مرز engine/panel در کد دقیق مشخص شود.
  5. RAM: بدون 16GB فاز ۲ اجرا نشود.
  6. Quora translator: هنوز تعریف نشده — خارج از معماری.
  7. داشبورد engine: oinawofb* بازنشسته شود؟ دسترسی ادمین به داشبورد engine از کجا باشد (پیشنهاد: engine.gcat.ir با basic-auth) — نیاز به تأیید.
  8. auth.gcat.ir: به‌عنوان alias پنل نگه داشته شود (تداوم SSO) یا آن هم به panel منتقل شود — نیاز به تأیید.

۱۰. ادغام بسته report/ (نسخه ۰.۱ — ممیزی موازی)

بسته F:\gcat\report\ یک ممیزی موازی با ۱۸ مشکل شناسه‌دار (P-01…P-18) است. یافته‌هایش پذیرفته شد با این نگاشت: تصمیم‌های باز گزارش که با تصمیم‌های جدید جایگزین شدند: D-01 (nginx میزبان→کانتینر فاز ۳ ✅)، D-02 (registry محلی→GHCR)، D-05 (compose ✅ Swarm حذف)، D-07 (Kuma→Grafana stack)، D-10 (dsh حذف/xray جایگزینی)، Q6 (code→حذف کامل)، Q12 (کامل). سؤال‌های گزارش که هنوز بازند: Q2 (پنجره downtime)، Q8 (مقصد بکاپ: object storage کدام provider؟)، Q9 (دسترسی SSH چند نفر)، R3 (دامنه‌های g-cat.ir بمانند؟)، R7 (والیوم chat1_migrated کی بازنشسته شود؟).