https://wiki.hesabix.ir/index.php?action=history&feed=atom&title=%D8%B1%D8%A7%D9%87%D9%86%D9%85%D8%A7%DB%8C_Hesabix_CLI 2026-05-25T21:50:10Z تاریخچهٔ نسخه‌ها برای این صفحه در ویکی MediaWiki 1.45.1 https://wiki.hesabix.ir/index.php?title=%D8%B1%D8%A7%D9%87%D9%86%D9%85%D8%A7%DB%8C_Hesabix_CLI&diff=38&oldid=prev 2026-05-15T10:10:07Z

<p>صفحه‌ای تازه حاوی «این راهنما برای سروری است که Hesabix با &#039;&#039;&#039;deploy.sh&#039;&#039;&#039; نصب شده و دستور &#039;&#039;&#039;hesabix&#039;&#039;&#039; در مسیر سیستم (معمولاً &lt;code&gt;/usr/local/bin/hesabix&lt;/code&gt;) در دسترس است. همهٔ دستورات &#039;&#039;&#039;باید با کاربر ریشه&#039;&#039;&#039; اجرا شوند (مثلاً &lt;code&gt;sudo hesabix ...&lt;/code&gt;). == پیش‌نیازها و مفاهیم == * &#039;&#039;&#039;مسیر ریشهٔ نصب (APP_ROOT)...» ایجاد کرد</p> <p><b>صفحهٔ تازه</b></p><div>این راهنما برای سروری است که Hesabix با &#039;&#039;&#039;deploy.sh&#039;&#039;&#039; نصب شده و دستور &#039;&#039;&#039;hesabix&#039;&#039;&#039; در مسیر سیستم (معمولاً &lt;code&gt;/usr/local/bin/hesabix&lt;/code&gt;) در دسترس است. همهٔ دستورات &#039;&#039;&#039;باید با کاربر ریشه&#039;&#039;&#039; اجرا شوند (مثلاً &lt;code&gt;sudo hesabix ...&lt;/code&gt;).<br /> <br /> == پیش‌نیازها و مفاهیم ==<br /> <br /> * &#039;&#039;&#039;مسیر ریشهٔ نصب (APP_ROOT)&#039;&#039;&#039; به‌طور پیش‌فرض &lt;code&gt;/opt/hesabix&lt;/code&gt; است. اگر متغیر محیطی &lt;code&gt;APP_ROOT&lt;/code&gt; روی سرور شما متفاوت است، اسکریپت از همان مقدار استفاده می‌کند.<br /> * فایل &#039;&#039;&#039;&lt;code&gt;${APP_ROOT}/.deploy_env&lt;/code&gt;&#039;&#039;&#039; پس از اولین deploy ساخته می‌شود و شامل تنظیماتی مانند آدرس مخزن Git، نام شاخه، دامنهٔ API و UI است. برای دستورات &lt;code&gt;-update&lt;/code&gt; و &lt;code&gt;-services&lt;/code&gt; وجود این فایل &#039;&#039;&#039;ضروری&#039;&#039;&#039; است.<br /> * منبع رسمی اسکریپت CLI در مخزن: &lt;code&gt;${APP_ROOT}/app/scripts/hesabix&lt;/code&gt; (معادل &lt;code&gt;app/scripts/hesabix&lt;/code&gt; در checkout).<br /> * اگر بدون ریشه اجرا کنید، پیام خطا می‌گیرید و اسکریپت متوقف می‌شود.<br /> <br /> == خلاصهٔ دستورات ==<br /> {| class=&quot;wikitable&quot;<br /> !دستور<br /> !کاربرد<br /> |-<br /> |&lt;code&gt;sudo hesabix -update&lt;/code&gt;<br /> |به‌روزرسانی کامل از مخزن، مایگریشن، ری‌استارت سرویس‌ها، بیلد وب Flutter، همگام‌سازی فایل‌های UI و reload nginx<br /> |-<br /> |&lt;code&gt;sudo hesabix -update -source URL -branch NAME&lt;/code&gt;<br /> |همان به‌روزرسانی با &#039;&#039;&#039;یک‌بار&#039;&#039;&#039; نادیده گرفتن آدرس مخزن و نام شاخهٔ ذخیره‌شده در &lt;code&gt;.deploy_env&lt;/code&gt;<br /> |-<br /> |&lt;nowiki&gt;stop|restart|status}&lt;/nowiki&gt;<br /> |کنترل واحدهای systemd هسابیکس (و در صورت نصب، pgAdmin4)<br /> |-<br /> |&lt;code&gt;sudo hesabix -cli reload&lt;/code&gt;<br /> |کپی مجدد اسکریپت CLI از مخزن به &lt;code&gt;/usr/local/bin/hesabix&lt;/code&gt;<br /> |-<br /> |&lt;code&gt;sudo hesabix -h&lt;/code&gt; یا &lt;code&gt;sudo hesabix --help&lt;/code&gt;<br /> |نمایش راهنمای کوتاه<br /> |}<br /> <br /> == hesabix -update (به‌روزرسانی سرور) ==<br /> <br /> === هدف ===<br /> اجرای &#039;&#039;&#039;pipeline کامل به‌روزرسانی&#039;&#039;&#039; که در فایل &lt;code&gt;${APP_ROOT}/app/update.sh&lt;/code&gt; پیاده‌سازی شده است: گرفتن آخرین کد از Git، نصب/به‌روزرسانی وابستگی‌های Python، اجرای مایگریشن Alembic، ری‌استارت سرویس‌های بک‌اند، بیلد release وب Flutter، کپی خروجی به وب‌سرور و در نهایت &#039;&#039;&#039;reload&#039;&#039;&#039; nginx.<br /> <br /> === نحوهٔ اجرا ===<br /> &lt;pre&gt;<br /> sudo hesabix -update<br /> sudo hesabix -update -source https://example.com/your-repo.git -branch main<br /> &lt;/pre&gt;<br /> <br /> * &#039;&#039;&#039;&lt;code&gt;-source REPO_URL&lt;/code&gt;&#039;&#039;&#039; (اختیاری): برای &#039;&#039;&#039;همان اجرا&#039;&#039;&#039; مقدار &lt;code&gt;REPO_URL&lt;/code&gt; را override می‌کند (قبل از فراخوانی &lt;code&gt;update.sh&lt;/code&gt; به صورت &lt;code&gt;export REPO_URL=...&lt;/code&gt;).<br /> * &#039;&#039;&#039;&lt;code&gt;-branch NAME&lt;/code&gt;&#039;&#039;&#039; (اختیاری): برای همان اجرا نام شاخهٔ Git را override می‌کند (&lt;code&gt;export BRANCH=...&lt;/code&gt;).<br /> * اگر هر دو را ندهید، مقادیر از &lt;code&gt;.deploy_env&lt;/code&gt; (پس از &lt;code&gt;source&lt;/code&gt; شدن) خوانده می‌شوند.<br /> <br /> === گام‌های اصلی (خلاصهٔ فنی) ===<br /> <br /> # &#039;&#039;&#039;Git:&#039;&#039;&#039; رفتن به &lt;code&gt;${APP_ROOT}/app&lt;/code&gt;، هم‌راستا کردن remote با &lt;code&gt;REPO_URL&lt;/code&gt; در صورت تفاوت، &lt;code&gt;fetch&lt;/code&gt;، checkout شاخه روی &lt;code&gt;origin/&amp;#x3C;BRANCH&amp;#x3E;&lt;/code&gt; و &lt;code&gt;pull --ff-only&lt;/code&gt;. اگر pull معمولی به‌دلیل تغییرات محلی یا عدم fast-forward شکست بخورد، اسکریپت با &#039;&#039;&#039;&lt;code&gt;git reset --hard origin/&amp;#x3C;BRANCH&amp;#x3E;&lt;/code&gt;&#039;&#039;&#039; سعی در هم‌راستاسازی اجباری می‌کند (تغییرات و commitهای محلی روی آن clone از بین می‌روند).<br /> # &#039;&#039;&#039;بک‌اند:&#039;&#039;&#039; فعال‌سازی venv در &lt;code&gt;hesabixAPI&lt;/code&gt;، تنظیم آینهٔ pip هسابیکس، نصب editable با pip، اطمینان از سازگاری جدول &lt;code&gt;alembic_version&lt;/code&gt;، اجرای &lt;code&gt;alembic upgrade head&lt;/code&gt;، &lt;code&gt;chown&lt;/code&gt; به &lt;code&gt;www-data&lt;/code&gt;، &lt;code&gt;systemctl restart&lt;/code&gt; برای &lt;code&gt;hesabix-api&lt;/code&gt;، &lt;code&gt;hesabix-rq-worker&lt;/code&gt; و &lt;code&gt;hesabix-notification-moderation&lt;/code&gt; و بررسی فعال بودن API.<br /> # &#039;&#039;&#039;فرانت (Flutter web):&#039;&#039;&#039; به‌روزرسانی اختیاری SDK در &lt;code&gt;/opt/flutter&lt;/code&gt;، بیلد با &lt;code&gt;build_web.sh&lt;/code&gt; (حالت release، تمیز کردن، نصب وابستگی‌ها)، آدرس پایهٔ API از روی دامنه و در صورت وجود گواهی Let&#039;s Encrypt (یا &lt;code&gt;API_PUBLIC_SCHEME&lt;/code&gt;)، rsync خروجی به &lt;code&gt;/var/www/&amp;#x3C;UI_DOMAIN&amp;#x3E;/&lt;/code&gt;.<br /> # &#039;&#039;&#039;Nginx:&#039;&#039;&#039; تنظیم &lt;code&gt;client_max_body_size&lt;/code&gt; برای API در صورت وجود فایل کانفیگ، اجرای اسکریپت اختیاری برای قوانین کش UI، &lt;code&gt;nginx -t&lt;/code&gt; و &lt;code&gt;systemctl reload nginx&lt;/code&gt;.<br /> # &#039;&#039;&#039;سلامت API (اختیاری):&#039;&#039;&#039; در صورت وجود &lt;code&gt;curl&lt;/code&gt;، تلاش برای فراخوانی health endpoint (خطا در این مرحله &#039;&#039;&#039;مرگبار&#039;&#039;&#039; نیست).<br /> <br /> === لاگ ===<br /> خروجیٔ زمانی به فایل &#039;&#039;&#039;&lt;code&gt;${APP_ROOT}/update.log&lt;/code&gt;&#039;&#039;&#039; نیز append می‌شود؛ برای عیب‌یابی پس از به‌روزرسانی این فایل را بررسی کنید.<br /> <br /> === پیش‌نیازهای مهم ===<br /> <br /> * وجود &lt;code&gt;${APP_ROOT}/app/.git&lt;/code&gt; و متغیرهای &#039;&#039;&#039;&lt;code&gt;API_DOMAIN&lt;/code&gt;&#039;&#039;&#039;، &#039;&#039;&#039;&lt;code&gt;UI_DOMAIN&lt;/code&gt;&#039;&#039;&#039;، &#039;&#039;&#039;&lt;code&gt;BRANCH&lt;/code&gt;&#039;&#039;&#039;، &#039;&#039;&#039;&lt;code&gt;REPO_URL&lt;/code&gt;&#039;&#039;&#039; (در env یا &lt;code&gt;.deploy_env&lt;/code&gt;).<br /> * وجود &lt;code&gt;${APP_ROOT}/.db_password&lt;/code&gt; برای اتصال PostgreSQL در مراحل مایگریشن.<br /> * وجود venv بک‌اند: &lt;code&gt;hesabixAPI/.venv&lt;/code&gt; (در غیر این صورت باید یک بار deploy کامل انجام شده باشد).<br /> * نصب Flutter در PATH سرور (طبق deploy).<br /> <br /> &#039;&#039;&#039;نکتهٔ امنیتی:&#039;&#039;&#039; اگر روی سرور تغییرات محلی در مخزن دارید که نمی‌خواهید از دست بروند، قبل از &lt;code&gt;-update&lt;/code&gt; از آن‌ها &#039;&#039;&#039;پشتیبان&#039;&#039;&#039; بگیرید؛ مسیر بازیابی خودکار ممکن است با reset سخت، تاریخچهٔ محلی را حذف کند.<br /> <br /> == hesabix -services (مدیریت سرویس‌های systemd) ==<br /> <br /> === واحدهای هدف ===<br /> <br /> * &#039;&#039;&#039;هسته (اجباری):&#039;&#039;&#039; &lt;code&gt;hesabix-api&lt;/code&gt;، &lt;code&gt;hesabix-rq-worker&lt;/code&gt;، &lt;code&gt;hesabix-notification-moderation&lt;/code&gt;<br /> * &#039;&#039;&#039;اختیاری:&#039;&#039;&#039; اگر واحد &lt;code&gt;pgadmin4.service&lt;/code&gt; روی سیستم &#039;&#039;&#039;loaded&#039;&#039;&#039; باشد، در start/restart/stop/status لحاظ می‌شود.<br /> <br /> === اعمال‌ها ===<br /> {| class=&quot;wikitable&quot;<br /> !عمل<br /> !توضیح<br /> |-<br /> |&lt;code&gt;start&lt;/code&gt;<br /> |روشن کردن سرویس‌های هسته به ترتیب، سپس pgAdmin4 (در صورت وجود)<br /> |-<br /> |&lt;code&gt;stop&lt;/code&gt;<br /> |خاموش کردن به ترتیب &#039;&#039;&#039;معکوس&#039;&#039;&#039; (ابتدا pgAdmin4 در صورت وجود، سپس هسته)<br /> |-<br /> |&lt;code&gt;restart&lt;/code&gt;<br /> |تنظیم drop-in محیطی برای API (&lt;code&gt;HESABIX_ALLOW_SUDO_JOURNALCTL=1&lt;/code&gt;)، &lt;code&gt;daemon-reload&lt;/code&gt; و ری‌استارت همه<br /> |-<br /> |&lt;code&gt;status&lt;/code&gt;<br /> |نمایش وضعیت هر واحد با &lt;code&gt;systemctl status&lt;/code&gt;<br /> |}<br /> &lt;pre&gt;<br /> sudo hesabix -services status<br /> sudo hesabix -services restart<br /> &lt;/pre&gt;اگر یکی از واحدهای هسته روی میزبان نصب/loaded نباشد، اسکریپت با پیام خطا خارج می‌شود و از شما می‌خواهد مرحلهٔ backend در deploy را دوباره اجرا کنید.<br /> <br /> == hesabix -cli reload (به‌روزرسانی خودِ دستور hesabix) ==<br /> گاهی پس از &lt;code&gt;git pull&lt;/code&gt; دستی یا deploy، نسخهٔ نصب‌شده در &lt;code&gt;/usr/local/bin/hesabix&lt;/code&gt; با نسخهٔ داخل مخزن (&lt;code&gt;${APP_ROOT}/app/scripts/hesabix&lt;/code&gt;) یکی نیست. این دستور:<br /> <br /> * فایل منبع را از مخزن می‌خواند، در یک فایل موقت کپی می‌کند، با &#039;&#039;&#039;sha256sum&#039;&#039;&#039; یا &#039;&#039;&#039;cmp&#039;&#039;&#039; با مقصد مقایسه می‌کند؛<br /> * اگر یکسان باشد: پیام «hesabix CLI is already up-to-date.» و خروج بدون تغییر؛<br /> * اگر متفاوت باشد: جایگزینی اتمی با &lt;code&gt;mv&lt;/code&gt; و &lt;code&gt;chmod 755&lt;/code&gt; روی &lt;code&gt;/usr/local/bin/hesabix&lt;/code&gt;.<br /> &lt;pre&gt;<br /> sudo hesabix -cli reload<br /> &lt;/pre&gt;&#039;&#039;&#039;مهم:&#039;&#039;&#039; &lt;code&gt;-cli&lt;/code&gt; را &#039;&#039;&#039;نباید&#039;&#039;&#039; هم‌زمان با &lt;code&gt;-update&lt;/code&gt; یا &lt;code&gt;-services&lt;/code&gt; ترکیب کنید؛ اسکریپت خطا می‌دهد. همچنین &lt;code&gt;-update&lt;/code&gt; و &lt;code&gt;-services&lt;/code&gt; را &#039;&#039;&#039;نمی‌توان&#039;&#039;&#039; در یک خط با هم زد.<br /> <br /> تنها action پشتیبانی‌شده برای &lt;code&gt;-cli&lt;/code&gt; در حال حاضر &#039;&#039;&#039;reload&#039;&#039;&#039; است.<br /> <br /> == محدودیت‌های ترکیب آرگومان‌ها ==<br /> <br /> * &lt;code&gt;-cli ...&lt;/code&gt; &#039;&#039;&#039;فقط به تنهایی&#039;&#039;&#039;.<br /> * یا &lt;code&gt;-update&lt;/code&gt; &#039;&#039;&#039;یا&#039;&#039;&#039; &lt;code&gt;-services ACTION&lt;/code&gt; — نه هر دو.<br /> * بدون آرگومان (و بدون حالت خاص): در صورت وجود deploy، رفتار پیش‌فرض نمایش usage است (بسته به اینکه آیا فقط CLI خالی فراخوانی شده یا نه؛ برای دیدن قطعی، &lt;code&gt;-h&lt;/code&gt; بزنید).<br /> <br /> == رفع اشکال سریع ==<br /> <br /> * API بالا نمی‌آید پس از update: &lt;code&gt;journalctl -u hesabix-api -n 100 --no-pager&lt;/code&gt;<br /> * مایگریشن خطا داد: لاگ &lt;code&gt;update.log&lt;/code&gt; و خروجی Alembic در همان اجرا<br /> * Nginx reload نشد: خروجی &lt;code&gt;nginx -t&lt;/code&gt; در مرحلهٔ ۴ اسکریپت update<br /> <br /> ----&#039;&#039;این صفحه از رفتار اسکریپت‌های &lt;code&gt;app/scripts/hesabix&lt;/code&gt; و &lt;code&gt;app/update.sh&lt;/code&gt; در مخزن Hesabix استخراج شده است؛ در صورت تغییر نسخه، متن را با همان فایل‌ها تطبیق دهید.&#039;&#039;</div>

Morrning