معماری کلی 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 · بکاپ از صفر (بخش ۱۰)
۱. نمای کلی
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
- رکوردهای DNS جدید در ابرآروان: panel, api (+ حذف code/dsh/academia/oinawofb)
- تنظیمات OIDC چت (issuer/redirectها الان auth.gcat.ir هستند) + envهای SSO پنل
- کلاینتهای API موجود که به ai.gcat.ir وصلاند → اطلاعرسانی + ریدایرکت/alias موقت
- گواهی 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
ساختار داخلی ریپوهای جدید
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 روزانه (ساعت کمترافیک، مثلاً ۰۴:۰۰):
- Dump هر دیتابیس:
- Postgresها:
pg_dump -Fcداخل کانتینر (chat-postgres,cloudreve-db,wiki-dbبعداً) - SQLiteها (engine/panel):
sqlite3 .backup(نه کپی خام فایل — برای consistency)
- Postgresها:
- فشردهسازی + رمزنگاری: هر dump →
zstd→ageبا کلید عمومی (کلید خصوصی فقط روی لپتاپهای بنیانگذاران، هرگز روی سرور). دلیل: دیتابیس چت/فروشگاه حاوی داده کاربر و توکن است؛ کانال تلگرام نباید نسخه plaintext داشته باشد. - ارسال به تلگرام: فایل رمزنگاریشده به کانال/گروه خصوصی «GCAT Backups» با بات ops؛ کپشن: نام سرویس + تاریخ + حجم + sha256.
- نوتیف نتیجه: خلاصه به گروه ops (موفق ✅ با حجمها / شکست 🔴 فوری). شکست ارسال = alert، نه سکوت.
- نگهداری محلی: ۷ نسخه آخر در
/opt/backups/(برای restore سریع)؛ پاکسازی خودکار قدیمیها. - تست restore ماهانه: دانلود آخرین فایل از تلگرام → رمزگشایی → restore در کانتینر موقت → گزارش به ops.
- سقف آپلود بات: ۵۰MB per file. اگر dump بزرگتر شد → split به قطعات ۴۵MB با پسوند شمارهدار + اسکریپت reassemble در restore. (dumpهای فعلی کوچکاند: کل والیومهای DB ~۳.۵GB شامل فایل، خود dumpها احتمالاً دهها MB)
- تلگرام مقصد ثانویه است نه یگانه: اگر روزی حجم از سقف گذشت یا بات محدود شد، مقصد اصلی object storage (S3 سازگار) جایگزین/مکمل میشود — اسکریپت از اول دو-مقصدی نوشته میشود (
TARGETS=telegram,s3). - پیامهای بکاپ در topic جدا از alertها تا نویز نگیرد.
۶. نظارت، هشدار و نوتیف تلگرام
۶.۱ کانال نوتیف تلگرام (مصوب)
۶.۲ رویدادهایی که حتماً نوتیف میشوند
- Alertها: دامنه non-200 بیش از ۲ دقیقه · swap > 500MB · دیسک > 85٪ · RAM در دسترس < 1GB · restart کانتینر · SSL < 14 روز · healthcheck شکستخورده
- Backup: موفق/شکست هر اجرای pg_dump/restic + نتیجه تست restore ماهانه (شکست backup = 🔴 فوری)
- Deploy: شروع/موفق/شکست + rollback خودکار هر اپ و nginx (با sha قبل/بعد)
- امنیتی: ورود SSH جدید (fail2ban ban) · تغییر کانفیگ nginx خارج از pipeline (drift)
۷. بودجه منابع (هدف: RAM 16GB)
آزادسازیهای مصوب: Swarm · terminal · dsh (~220MB) · academia (~100MB) · xray (پس از جایگزینی) · heap از 4GB→2GB · ~۱۰GB آرشیو مایگریشن + کانتینرهای exited.
حذف dsh/academia/terminal بخشی از بار جدید را جبران میکند، ولی بدون RAM 16GB باز هم فاز ۲ توصیه نمیشود.
۸. فازبندی اجرا
۹. ریسکها و سؤالهای باز
- 3x-ui جای xray: اثبات معادلسازی پروکسی برای مصرفکنندههای فعلی (احتمالاً engine روی socks 10808) قبل از خاموشی xray.
- سوییچ ai→panel/api: کلاینتهای API موجود نباید بشکنند — alias/ریدایرکت موقت + اطلاعرسانی.
- OIDC: تغییر دامنه پنل یعنی بهروزرسانی همزمان envهای چت و پنل؛ سوییچ باید اتمیک باشد.
- استخراج panel از omni: باید تاریخچه Git فایلهای panel حفظ شود (git filter-repo) و مرز engine/panel در کد دقیق مشخص شود.
- RAM: بدون 16GB فاز ۲ اجرا نشود.
- Quora translator: هنوز تعریف نشده — خارج از معماری.
- داشبورد engine: oinawofb* بازنشسته شود؟ دسترسی ادمین به داشبورد engine از کجا باشد (پیشنهاد: engine.gcat.ir با basic-auth) — نیاز به تأیید.
- 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 کی بازنشسته شود؟).