راهنمای Hesabix CLI

این راهنما برای سروری است که Hesabix با deploy.sh نصب شده و دستور hesabix در مسیر سیستم (معمولاً /usr/local/bin/hesabix) در دسترس است. همهٔ دستورات باید با کاربر ریشه اجرا شوند (مثلاً sudo hesabix ...).

پیش‌نیازها و مفاهیم

• مسیر ریشهٔ نصب (APP_ROOT) به‌طور پیش‌فرض /opt/hesabix است. اگر متغیر محیطی APP_ROOT روی سرور شما متفاوت است، اسکریپت از همان مقدار استفاده می‌کند.
• فایل ${APP_ROOT}/.deploy_env پس از اولین deploy ساخته می‌شود و شامل تنظیماتی مانند آدرس مخزن Git، نام شاخه، دامنهٔ API و UI است. برای دستورات -update و -services وجود این فایل ضروری است.
• منبع رسمی اسکریپت CLI در مخزن: ${APP_ROOT}/app/scripts/hesabix (معادل app/scripts/hesabix در checkout).
• اگر بدون ریشه اجرا کنید، پیام خطا می‌گیرید و اسکریپت متوقف می‌شود.

خلاصهٔ دستورات

دستور	کاربرد
sudo hesabix -update	به‌روزرسانی کامل از مخزن، مایگریشن، ری‌استارت سرویس‌ها، بیلد وب Flutter، همگام‌سازی فایل‌های UI و reload nginx
sudo hesabix -update -source URL -branch NAME	همان به‌روزرسانی با یک‌بار نادیده گرفتن آدرس مخزن و نام شاخهٔ ذخیره‌شده در .deploy_env
stop|restart|status}	کنترل واحدهای systemd هسابیکس (و در صورت نصب، pgAdmin4)
sudo hesabix -cli reload	کپی مجدد اسکریپت CLI از مخزن به /usr/local/bin/hesabix
sudo hesabix -h یا sudo hesabix --help	نمایش راهنمای کوتاه

hesabix -update (به‌روزرسانی سرور)

هدف

اجرای pipeline کامل به‌روزرسانی که در فایل ${APP_ROOT}/app/update.sh پیاده‌سازی شده است: گرفتن آخرین کد از Git، نصب/به‌روزرسانی وابستگی‌های Python، اجرای مایگریشن Alembic، ری‌استارت سرویس‌های بک‌اند، بیلد release وب Flutter، کپی خروجی به وب‌سرور و در نهایت reload nginx.

نحوهٔ اجرا

sudo hesabix -update
sudo hesabix -update -source https://example.com/your-repo.git -branch main

• -source REPO_URL (اختیاری): برای همان اجرا مقدار REPO_URL را override می‌کند (قبل از فراخوانی update.sh به صورت export REPO_URL=...).
• -branch NAME (اختیاری): برای همان اجرا نام شاخهٔ Git را override می‌کند (export BRANCH=...).
• اگر هر دو را ندهید، مقادیر از .deploy_env (پس از source شدن) خوانده می‌شوند.

گام‌های اصلی (خلاصهٔ فنی)

1. Git: رفتن به ${APP_ROOT}/app، هم‌راستا کردن remote با REPO_URL در صورت تفاوت، fetch، checkout شاخه روی origin/<BRANCH> و pull --ff-only. اگر pull معمولی به‌دلیل تغییرات محلی یا عدم fast-forward شکست بخورد، اسکریپت با git reset --hard origin/<BRANCH> سعی در هم‌راستاسازی اجباری می‌کند (تغییرات و commitهای محلی روی آن clone از بین می‌روند).
2. بک‌اند: فعال‌سازی venv در hesabixAPI، تنظیم آینهٔ pip هسابیکس، نصب editable با pip، اطمینان از سازگاری جدول alembic_version، اجرای alembic upgrade head، chown به www-data، systemctl restart برای hesabix-api، hesabix-rq-worker و hesabix-notification-moderation و بررسی فعال بودن API.
3. فرانت (Flutter web): به‌روزرسانی اختیاری SDK در /opt/flutter، بیلد با build_web.sh (حالت release، تمیز کردن، نصب وابستگی‌ها)، آدرس پایهٔ API از روی دامنه و در صورت وجود گواهی Let's Encrypt (یا API_PUBLIC_SCHEME)، rsync خروجی به /var/www/<UI_DOMAIN>/.
4. Nginx: تنظیم client_max_body_size برای API در صورت وجود فایل کانفیگ، اجرای اسکریپت اختیاری برای قوانین کش UI، nginx -t و systemctl reload nginx.
5. سلامت API (اختیاری): در صورت وجود curl، تلاش برای فراخوانی health endpoint (خطا در این مرحله مرگبار نیست).

لاگ

خروجیٔ زمانی به فایل ${APP_ROOT}/update.log نیز append می‌شود؛ برای عیب‌یابی پس از به‌روزرسانی این فایل را بررسی کنید.

پیش‌نیازهای مهم

• وجود ${APP_ROOT}/app/.git و متغیرهای API_DOMAIN، UI_DOMAIN، BRANCH، REPO_URL (در env یا .deploy_env).
• وجود ${APP_ROOT}/.db_password برای اتصال PostgreSQL در مراحل مایگریشن.
• وجود venv بک‌اند: hesabixAPI/.venv (در غیر این صورت باید یک بار deploy کامل انجام شده باشد).
• نصب Flutter در PATH سرور (طبق deploy).

نکتهٔ امنیتی: اگر روی سرور تغییرات محلی در مخزن دارید که نمی‌خواهید از دست بروند، قبل از -update از آن‌ها پشتیبان بگیرید؛ مسیر بازیابی خودکار ممکن است با reset سخت، تاریخچهٔ محلی را حذف کند.

hesabix -services (مدیریت سرویس‌های systemd)

واحدهای هدف

• هسته (اجباری): hesabix-api، hesabix-rq-worker، hesabix-notification-moderation
• اختیاری: اگر واحد pgadmin4.service روی سیستم loaded باشد، در start/restart/stop/status لحاظ می‌شود.

اعمال‌ها

عمل	توضیح
start	روشن کردن سرویس‌های هسته به ترتیب، سپس pgAdmin4 (در صورت وجود)
stop	خاموش کردن به ترتیب معکوس (ابتدا pgAdmin4 در صورت وجود، سپس هسته)
restart	تنظیم drop-in محیطی برای API (HESABIX_ALLOW_SUDO_JOURNALCTL=1)، daemon-reload و ری‌استارت همه
status	نمایش وضعیت هر واحد با systemctl status

sudo hesabix -services status
sudo hesabix -services restart

اگر یکی از واحدهای هسته روی میزبان نصب/loaded نباشد، اسکریپت با پیام خطا خارج می‌شود و از شما می‌خواهد مرحلهٔ backend در deploy را دوباره اجرا کنید.

hesabix -cli reload (به‌روزرسانی خودِ دستور hesabix)

گاهی پس از git pull دستی یا deploy، نسخهٔ نصب‌شده در /usr/local/bin/hesabix با نسخهٔ داخل مخزن (${APP_ROOT}/app/scripts/hesabix) یکی نیست. این دستور:

• فایل منبع را از مخزن می‌خواند، در یک فایل موقت کپی می‌کند، با sha256sum یا cmp با مقصد مقایسه می‌کند؛
• اگر یکسان باشد: پیام «hesabix CLI is already up-to-date.» و خروج بدون تغییر؛
• اگر متفاوت باشد: جایگزینی اتمی با mv و chmod 755 روی /usr/local/bin/hesabix.

sudo hesabix -cli reload

مهم: -cli را نباید هم‌زمان با -update یا -services ترکیب کنید؛ اسکریپت خطا می‌دهد. همچنین -update و -services را نمی‌توان در یک خط با هم زد.

تنها action پشتیبانی‌شده برای -cli در حال حاضر reload است.

محدودیت‌های ترکیب آرگومان‌ها

• -cli ... فقط به تنهایی.
• یا -update یا -services ACTION — نه هر دو.
• بدون آرگومان (و بدون حالت خاص): در صورت وجود deploy، رفتار پیش‌فرض نمایش usage است (بسته به اینکه آیا فقط CLI خالی فراخوانی شده یا نه؛ برای دیدن قطعی، -h بزنید).

رفع اشکال سریع

• API بالا نمی‌آید پس از update: journalctl -u hesabix-api -n 100 --no-pager
• مایگریشن خطا داد: لاگ update.log و خروجی Alembic در همان اجرا
• Nginx reload نشد: خروجی nginx -t در مرحلهٔ ۴ اسکریپت update

---

این صفحه از رفتار اسکریپت‌های app/scripts/hesabix و app/update.sh در مخزن Hesabix استخراج شده است؛ در صورت تغییر نسخه، متن را با همان فایل‌ها تطبیق دهید.