گاهی هنگام نصب یک ماژول سفارشی در Odoo، فایل ZIP بارگذاری نمی‌شود، افزونه در فهرست Apps نمایش داده نمی‌شود یا فرایند نصب با خطا متوقف می‌شود. در چنین شرایطی، می‌توان فایل ماژول را از طریق SSH به سرور لینوکس منتقل کرد، در مسیر صحیح افزونه‌ها قرار داد و سپس نصب را از پنل مدیریت Odoo انجام داد.

در این راهنمای کاربردی زاگروس ERP، مراحل انتقال، استخراج، تنظیم دسترسی‌ها، شناسایی و نصب ماژول را قدم‌به‌قدم بررسی می‌کنیم.

در این آموزش یاد می‌گیرید:

• چگونه فایل ZIP را از ویندوز به سرور منتقل کنید.

• چگونه ساختار ماژول و مسیر افزونه‌های Odoo را بررسی کنید.

• چگونه دسترسی‌های لازم را تنظیم کنید.

• چگونه فهرست Apps را به‌روزرسانی و ماژول را نصب کنید.

• چگونه خطاهای رایج را عیب‌یابی کنید.

پیش‌نیاز: این آموزش برای نصب‌هایی است که به سرور لینوکس و دسترسی SSH دسترسی دارید. اگر از Odoo Online استفاده می‌کنید، معمولاً امکان دسترسی مستقیم به سیستم‌عامل سرور را ندارید.

مراحل نصب ماژول Odoo از طریق SSH

مرحله ۱: پیدا کردن فایل ZIP ماژول

ابتدا فایل ماژول را از منبع معتبر دریافت کنید. در این مثال، نام فایل زیر را در نظر می‌گیریم:

zagros_enterprise_manager.zip

مسیر فایل در ویندوز:

D:\Projects\12. test\zagros-erp2\custom-addons\zagros_enterprise_manager.zip

مسیر بالا نمونه است؛ هنگام اجرای دستورات باید آدرس واقعی فایل خود را جایگزین کنید.

مرحله ۲: انتقال فایل ZIP از ویندوز به سرور

در ویندوز، PowerShell را باز کنید و دستور زیر را اجرا کنید:

scp "D:\Projects\12. test\zagros-erp2\custom-addons\zagros_enterprise_manager.zip" root@185.126.203.251:/root/

در این دستور:

• scp ابزار انتقال فایل از طریق SSH است.

• 185.126.203.251 آدرس نمونه سرور است.

• /root/ مسیر مقصد فایل روی سرور است.

آدرس سرور را با IP یا نام میزبان واقعی خود جایگزین کنید. در صورت درخواست، اطلاعات احراز هویت SSH را وارد کنید.

اگر با خطای No such file or directory مواجه شدید، مسیر فایل ویندوز را بررسی کنید و مطمئن شوید نام فایل و پسوند ZIP صحیح است.

مرحله ۳: ورود به سرور لینوکس

پس از انتقال فایل، از PowerShell به سرور متصل شوید:

ssh root@185.126.203.251

از این مرحله به بعد، دستورات را در ترمینال سرور لینوکس اجرا کنید، نه در PowerShell ویندوز.

مرحله ۴: بررسی فایل ZIP و ساختار ماژول

ابتدا وجود فایل را بررسی کنید:

ls -lh /root/zagros_enterprise_manager.zip

سپس فهرست فایل‌های داخل آرشیو را ببینید:

unzip -l /root/zagros_enterprise_manager.zip

ساختار متداول یک ماژول Odoo می‌تواند به شکل زیر باشد:

zagros_enterprise_manager/
├── __init__.py
├── __manifest__.py
├── models/
├── views/
├── data/
└── static/

وجود همه پوشه‌های بالا الزامی نیست؛ اما در یک ماژول معمولی، فایل __manifest__.py باید مستقیماً داخل پوشه اصلی ماژول قرار داشته باشد.

اگر ZIP شامل یک پوشه اضافی است یا فایل Manifest در سطح اشتباه قرار گرفته، پیش از استخراج ساختار آن را اصلاح کنید.

مرحله ۵: استخراج ماژول در مسیر افزونه‌های Odoo

در این مثال، مسیر افزونه‌های سفارشی برابر است با:

/opt/zagros/custom-addons

ابتدا مطمئن شوید این مسیر، مسیر صحیح افزونه‌های سفارشی در سرور شماست. سپس دستور زیر را اجرا کنید:

unzip -o /root/zagros_enterprise_manager.zip -d /opt/zagros/custom-addons/

گزینه -o فایل‌های هم‌نام را بدون پرسش بازنویسی می‌کند. اگر نسخه قبلی ماژول وجود دارد، پیش از اجرا از مناسب بودن این کار مطمئن شوید.

پوشه مقصد را بررسی کنید:

ls -la /opt/zagros/custom-addons/

سپس محتویات پوشه ماژول را ببینید:

ls -la /opt/zagros/custom-addons/zagros_enterprise_manager/

فایل __manifest__.py باید در همین سطح باشد، نه در پوشه‌ای تودرتو و غیرضروری.

مرحله ۶: تنظیم مجوزهای دسترسی

Odoo باید بتواند فایل‌های ماژول را بخواند. در این مثال، نام کاربر سرویس odoo است.

ابتدا وجود فایل Manifest را بررسی کنید:

test -f /opt/zagros/custom-addons/zagros_enterprise_manager/__manifest__.py && echo "manifest found"

اگر پیام manifest found نمایش داده شد و کاربر سرویس واقعاً odoo است، می‌توانید مالکیت پوشه همین ماژول را تنظیم کنید:

chown -R odoo:odoo /opt/zagros/custom-addons/zagros_enterprise_manager

سپس مجوزهای معمول دسترسی را اعمال کنید:

chmod -R u=rwX,go=rX /opt/zagros/custom-addons/zagros_enterprise_manager

نکته امنیتی: نام کاربر، گروه و مجوزهای مناسب ممکن است در سرور شما متفاوت باشند. این دستورات را بدون بررسی شرایط واقعی سرور اجرا نکنید و از تغییر مالکیت یا مجوز کل پوشه افزونه‌ها خودداری کنید.

مرحله ۷: بررسی مسیر افزونه‌ها و سرویس Odoo

Odoo فقط مسیرهای افزونه‌ای را بررسی می‌کند که در تنظیمات آن تعریف شده‌اند.

برای مشاهده مسیر addons_path در فایل پیکربندی نمونه، اجرا کنید:

grep -E '^[[:space:]]*addons_path[[:space:]]*=' /opt/zagros/odoo/odoo.conf

مطمئن شوید مسیر /opt/zagros/custom-addons در تنظیمات واقعی Odoo وجود دارد. مسیر فایل پیکربندی نیز ممکن است در نصب شما متفاوت باشد.

اگر کد ماژول تغییر کرده و برای بارگذاری مجدد آن به راه‌اندازی سرویس نیاز دارید، ابتدا نام واقعی سرویس را بررسی کنید. در این مثال، نام سرویس zagros.service است:

systemctl restart zagros.service

وضعیت سرویس را بررسی کنید:

systemctl is-active zagros.service

خروجی مورد انتظار:

active

اگر سرویس فعال نشد، گزارش خطا را بررسی کنید:

journalctl -u zagros.service -n 80 --no-pager

راه‌اندازی مجدد ممکن است دسترسی کاربران را برای مدت کوتاهی قطع کند. در محیط عملیاتی، این کار را با برنامه‌ریزی انجام دهید.

مرحله ۸: به‌روزرسانی فهرست Apps در Odoo

اکنون وارد پنل مدیریت Odoo شوید:

1. به بخش Apps بروید.

2. در صورت نیاز، Developer Mode یا حالت توسعه‌دهنده را فعال کنید.

3. گزینه Update Apps List یا «به‌روزرسانی فهرست برنامه‌ها» را پیدا کنید.

4. عملیات را تأیید کنید.

5. نام فنی ماژول را جست‌وجو کنید:

   zagros_enterprise_manager

اگر نتیجه نمایش داده نشد، فیلترهای فعال در Apps را بررسی کنید.

توجه: به‌روزرسانی فهرست برنامه‌ها به معنی نصب ماژول نیست؛ این کار فقط به Odoo اجازه می‌دهد افزونه‌های موجود در مسیرهای تعریف‌شده را دوباره شناسایی کند.

مرحله ۹: نصب و بررسی نتیجه نهایی

اگر ماژول در فهرست Apps نمایش داده شد:

1. نام، توضیحات و نسخه آن را بررسی کنید.

2. از سازگاری ماژول با نسخه Odoo و نصب بودن وابستگی‌های آن مطمئن شوید.

3. روی Install یا Activate کلیک کنید؛ متن دکمه به نسخه و وضعیت ماژول بستگی دارد.

4. منتظر بمانید تا فرایند نصب پایان یابد.

5. منوها، فرم‌ها و قابلیت‌های جدید را بررسی کنید.

اگر نصب با خطا متوقف شد، متن کامل خطا را ذخیره کنید و گزارش سرویس Odoo را بررسی کنید. از تکرار نصب بدون مشخص کردن علت خطا خودداری کنید.
برای مشاهده نمونه‌ای از ماژول‌های قابل استفاده در Odoo 19، می‌توانید ماژول تقویم شمسی Odoo 19 را بررسی کنید.

پس از نصب و فعال‌سازی ماژول، محیط Odoo آماده استفاده از قابلیت‌های جدید خواهد بود.

عیب‌یابی خطاهای رایج نصب ماژول Odoo

نکات امنیتی پیش از نصب روی سرور اصلی

• پیش از نصب یا به‌روزرسانی ماژول در محیط عملیاتی، از دیتابیس و اطلاعات ضروری نسخه پشتیبان معتبر تهیه کنید.

• فایل ماژول را فقط از منبع قابل اعتماد دریافت کنید.

• پیش از بازنویسی نسخه موجود، از فایل‌های فعلی و سازگاری نسخه جدید مطمئن شوید.

• مجوزهای دسترسی را فقط در محدوده لازم تغییر دهید.

• سازگاری ماژول با نسخه Odoo، وابستگی‌ها و مجوز استفاده از آن را بررسی کنید.

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

جمع‌بندی

اگر آپلود مستقیم فایل ZIP در Odoo با مشکل مواجه شد، انتقال فایل از طریق SSH می‌تواند جایگزین مناسبی باشد. با انتقال فایل، بررسی ساختار ماژول، استخراج در مسیر صحیح، تنظیم دسترسی‌ها و به‌روزرسانی فهرست Apps می‌توانید افزونه سفارشی را برای نصب در دسترس Odoo قرار دهید.
اگر برای راه‌اندازی Odoo فارسی و استقرار آن روی سرور اختصاصی خود به کمک نیاز دارید، می‌توانید جزئیات خدمت راه‌اندازی Odoo فارسی روی سرور شما را مشاهده کنید.

البته موفقیت این روش به ساختار صحیح ماژول، مسیرهای پیکربندی‌شده، مجوزهای دسترسی و وابستگی‌های آن بستگی دارد.