مشکلات رایج و رفع عیب

به راهنمای رفع عیب HarborDB خوش آمدید. این منبع جامع به شما کمک می‌کند تا به سرعت رایج‌ترین مشکلاتی که هنگام کار با HarborDB و PostgreSQL با آن مواجه می‌شوید را شناسایی و حل کنید. چه با مشکلات اتصال، عملکرد کند، یا مشکلات رابط کاربری مواجه باشید، در اینجا راه‌حل‌های گام به گام پیدا خواهید کرد.

نحوه استفاده از این راهنما

1. مشکل خود را شناسایی کنید از دسته‌بندی‌های زیر
2. مراحل رفع عیب را دنبال کنید به ترتیب
3. راه‌حل‌ها را امتحان کنید تا مشکل حل شود
4. اگر هنوز حل نشد، از بخش "تماس با پشتیبانی" استفاده کنید

مرجع سریع: مشکلات رایج

| مشکل | علت احتمالی | راه‌حل سریع | | -------------------------- | --------------------------------------- | ---------------------------------------- | | عدم اتصال به PostgreSQL | سرور در حال اجرا نیست، فایروال مسدود می‌کند | PostgreSQL را راه‌اندازی کنید، تنظیمات فایروال را بررسی کنید | | عملکرد کند کوئری | ایندکس‌های گمشده، مجموعه داده‌های بزرگ | ایندکس اضافه کنید، از LIMIT استفاده کنید، کوئری‌ها را بهینه کنید | | استفاده حافظه بالا | تب‌های باز زیاد، مجموعه نتایج بزرگ | تب‌های استفاده نشده را ببندید، حالت streaming را فعال کنید | | صادرسازی ناموفق | مشکلات مجوز، دیسک پر | مجوزهای فایل را بررسی کنید، فضای دیسک آزاد کنید | | رابط کاربری احساس کندی می‌دهد | محدودیت‌های منابع سیستم | برنامه‌های دیگر را ببندید، HarborDB را مجدداً راه‌اندازی کنید |

مشکلات اتصال

"نمی‌توان به سرور PostgreSQL متصل شد"

علائم:

• خطاهای timeout اتصال
• پیام‌های "Connection refused"
• بارگذاری بی‌نهایت هنگام تست اتصال

رفع عیب گام به گام:

1. بررسی وضعیت سرور PostgreSQL:

   # در Terminal، بررسی کنید آیا PostgreSQL در حال اجرا است
   pg_isready -h localhost -p 5432
   

   • اگر در حال اجرا نیست: brew services start postgresql (Homebrew) یا از طریق System Preferences راه‌اندازی کنید

2. تأیید جزئیات اتصال:

   • نام میزبان: localhost برای محلی، IP/نام میزبان صحیح برای از راه دور
   • پورت: پیش‌فرض 5432، پورت PostgreSQL خود را تأیید کنید
   • نام پایگاه داده: باید قبل از اتصال وجود داشته باشد
   • نام کاربری/رمز عبور: حساس به حروف بزرگ و کوچک، اعتبارنامه‌ها را بررسی کنید

3. بررسی تنظیمات فایروال:

   • System Preferences → Security & Privacy → Firewall
   • مطمئن شوید پورت PostgreSQL (5432) مجاز است
   • برای تست موقتاً فایروال را غیرفعال کنید

4. تست اتصال شبکه:

   # برای سرورهای از راه دور
   ping your-server-address
   telnet your-server-address 5432
   

راه‌حل‌های رایج:

• ✅ سرویس PostgreSQL را راه‌اندازی کنید
• ✅ نام میزبان/آدرس IP صحیح
• ✅ پورت فایروال 5432 را باز کنید
• ✅ از اعتبارنامه‌های صحیح استفاده کنید

"احراز هویت رمز عبور ناموفق بود"

علل:

• نام کاربری یا رمز عبور نادرست
• عدم تطابق روش احراز هویت PostgreSQL
• کاربر فاقد مجوزهای پایگاه داده است

راه‌حل‌ها:

1. بازنشانی رمز عبور PostgreSQL:

   -- به عنوان superuser متصل شوید (از طریق خط فرمان)
   ALTER USER username WITH PASSWORD 'new_password';
   

2. بررسی روش احراز هویت:

   • فایل pg_hba.conf را مشاهده کنید
   • روش‌های رایج: md5، scram-sha-256، trust
   • در صورت نیاز روش را به‌روزرسانی کنید، PostgreSQL را مجدداً راه‌اندازی کنید

3. تأیید مجوزهای کاربر:

   -- لیست کاربران و مجوزها
   \du
   
   -- لیست پایگاه‌های داده و دسترسی
   \l
   

خطاهای اتصال SSL/TLS

هنگام اتصال به سرورهای از راه دور:

1. بررسی نیازمندی‌های SSL:

   • سرور ممکن است نیاز به حالت SSL خاصی داشته باشد
   • ممکن است نیاز به وارد کردن گواهی داشته باشد

2. حالت‌های مختلف SSL را در HarborDB امتحان کنید:

   • با prefer شروع کنید
   • سپس require را امتحان کنید
   • در نهایت verify-full (نیاز به گواهی)

3. گواهی‌ها را وارد کنید اگر از verify-full استفاده می‌کنید:

   • گواهی را از مدیر سرور دریافت کنید
   • به Keychain Access macOS وارد کنید
   • دسترسی HarborDB به گواهی را مجاز کنید

مشکلات عملکرد

اجرای کند کوئری

مراحل تشخیص:

1. از EXPLAIN برای تحلیل استفاده کنید:

   • روی دکمه "Explain" (⚡) در HarborDB کلیک کنید
   • به دنبال "Seq Scan" (اسکن کامل جدول) باشید - اغلب کند است
   • به دنبال "Index Scan" باشید - معمولاً سریع‌تر است

2. بررسی ایندکس‌های گمشده:

   -- یافتن ستون‌های فیلتر شده مکرر بدون ایندکس
   SELECT schemaname, tablename, attname
   FROM pg_stats
   WHERE schemaname NOT LIKE 'pg_%'
     AND n_distinct > 100
     AND attname NOT IN (
       SELECT column_name
       FROM information_schema.columns
       WHERE table_schema = schemaname
         AND table_name = tablename
     );
   

3. ایندکس‌های مناسب اضافه کنید:

   -- ایندکس تک ستونی
   CREATE INDEX idx_table_column ON table_name(column_name);
   
   -- ایندکس چند ستونی برای الگوهای کوئری رایج
   CREATE INDEX idx_table_col1_col2 ON table_name(col1, col2);
   

رفع سریع عملکرد:

• LIMIT clause به کوئری‌های اکتشافی اضافه کنید
• فقط ستون‌های مورد نیاز را انتخاب کنید (نه SELECT *)
• از WHERE clauses با ستون‌های ایندکس شده استفاده کنید
• از توابع در WHERE clauses که استفاده از ایندکس را جلوگیری می‌کنند اجتناب کنید

استفاده حافظه بالا

علائم:

• HarborDB از RAM بیش از حد استفاده می‌کند (Activity Monitor را بررسی کنید)
• سیستم کند می‌شود
• خطاهای "Out of memory"

راه‌حل‌ها:

1. کاهش اندازه کش کوئری:

   • Preferences → Performance → Query Cache
   • از پیش‌فرض 256MB به 128MB کاهش دهید اگر حافظه محدود است

2. فعال کردن حالت Streaming:

   • Preferences → Performance → Streaming Results
   • برای نتایج > 10,000 ردیف فعال کنید
   • استفاده حافظه برای مجموعه داده‌های بزرگ را کاهش می‌دهد

3. مدیریت تب‌های باز:

   • تب‌های کوئری استفاده نشده را ببندید
   • HarborDB مجموعه نتایج را در حافظه به ازای هر تب نگه می‌دارد
   • کار منظم: حداکثر ۵-۱۰ تب

4. مجدداً راه‌اندازی HarborDB:

   • در طول استفاده سنگین روزانه خروج و راه‌اندازی مجدد
   • استفاده انباشته شده حافظه را پاک می‌کند

برنامه احساس کندی می‌دهد

رفع سریع:

1. برنامه‌های دیگر را ببندید:

   • به ویژه برنامه‌های با مصرف منابع بالا (Chrome با تب‌های زیاد، Docker و غیره)
   • Activity Monitor را برای فشار حافظه بررسی کنید

2. کاهش انیمیشن‌های UI:

   • Preferences → Appearance → Disable animations
   • تجربه نرم‌تر روی سخت‌افزار قدیمی

3. ساده‌سازی رابط کاربری:

   • بخش‌های نوار کناری استفاده نشده را جمع کنید
   • از تم رنگی ساده‌تر استفاده کنید
   • رنگ‌آمیزی نحوی را برای کوئری‌های بسیار بزرگ غیرفعال کنید

مشکلات صادرسازی و فایل

صادرسازی ناموفق است یا فایل‌های خالی ایجاد می‌کند

علل و راه‌حل‌های رایج:

1. مشکلات مجوز:

   # بررسی مجوزهای پوشه
   ls -la ~/Desktop/
   
   # مکان ذخیره متفاوت امتحان کنید
   # از پوشه Documents به جای Desktop استفاده کنید
   

2. مشکلات فضای دیسک:

   # بررسی فضای دیسک موجود
   df -h
   
   # حداقل ۲x اندازه صادرسازی آزاد نیاز است
   

3. مشکلات قالب فایل:

   • CSV: جداکننده متفاوت امتحان کنید (کاما، سمیکالن، تب)
   • CSV: محدودکننده متن اضافه کنید (کوتیشن اطراف فیلدها)
   • JSON: هر دو قالب "Pretty" و "Compact" را امتحان کنید

4. بهینه‌سازی صادرسازی بزرگ:

   • به صورت تکه‌های کوچکتر صادر کنید
   • برای مجموعه داده‌های بزرگ به جای JSON از CSV استفاده کنید
   • فشرده‌سازی را در تنظیمات صادرسازی فعال کنید

"فایل یافت نشد" یا صادرسازی‌های گم شده

1. بررسی مکان ذخیره پیش‌فرض:

   • Preferences → Export → Default Save Location
   • به پوشه دسترسی مکرر تغییر دهید

2. جستجوی فایل‌ها:

   # جستجوی فایل‌های CSV/JSON اخیر
   find ~ -name "*.csv" -mtime -1
   find ~ -name "*.json" -mtime -1
   

3. بررسی سطل زباله:

   • صادرسازی‌ها ممکن است به طور تصادفی حذف شده باشند
   • اگر پیدا شد از سطل زباله بازیابی کنید

مشکلات رابط کاربری و نمایش

تم به درستی اعمال نمی‌شود

مشکلات حالت تیره/روشن macOS:

1. بررسی System Settings:

   • System Settings → Appearance
   • مطمئن شوید "Auto" یا تم مورد نظر انتخاب شده است

2. مجدداً راه‌اندازی HarborDB:

   • کاملاً خروج (⌘ + Q)
   • برای اعمال تم سیستم دوباره باز کنید

3. اجبار تم در HarborDB:

   • Preferences → Appearance → Theme
   • "Light"، "Dark" یا "System" را انتخاب کنید

ویژگی‌ها یا منوهای گم شده

1. به‌روزرسانی HarborDB:

   • بررسی به‌روزرسانی‌ها (HarborDB → Check for Updates)
   • App Store → تب Updates

2. بازنشانی چیدمان رابط کاربری:

   • Window → Reset Layout
   • ترتیب پنل پیش‌فرض را بازیابی می‌کند

3. بررسی در دسترس بودن ویژگی:

   • برخی ویژگی‌ها نیاز به نسخه‌های خاص PostgreSQL دارند
   • سازگاری را در مستندات ویژگی تأیید کنید

مشکلات نمایش متن

مشکلات اندازه فونت/خوانایی:

1. تنظیم اندازه فونت ویرایشگر:

   • Preferences → Editor → Font Size
   • برای خوانایی بهتر افزایش دهید

2. استفاده از Zoom macOS:

   • System Settings → Accessibility → Zoom
   • برای بزرگنمایی موقت فعال کنید

3. حالت کنتراست بالا:

   • System Settings → Accessibility → Display
   • کنتراست را برای دید بهتر افزایش دهید

مشکلات ویژه macOS

خطای "App is Damaged"

هنگام باز کردن HarborDB:

# حذف ویژگی quarantine
sudo xattr -cr /Applications/HarborDB.app

# دوباره HarborDB را باز کنید
open /Applications/HarborDB.app

هشدارهای Gatekeeper

برای دانلود مستقیم (نه App Store):

1. System Settings → Privacy & Security
2. به بخش "Security" اسکرول کنید
3. روی "Open Anyway" در کنار هشدار HarborDB کلیک کنید
4. باز کردن را تأیید کنید

مشکلات دسترسی Touch ID/Keychain

خطاهای "HarborDB wants to use your password":

1. بازنشانی مجوزهای Keychain:

   • برنامه Keychain Access را باز کنید
   • "HarborDB" را جستجو کنید
   • ورودی‌های موجود را حذف کنید
   • اتصال را در HarborDB دوباره اضافه کنید

2. تعمیر Keychain:

   • Keychain Access → File → Keychain First Aid
   • تعمیر روی Keychain "Login" اجرا کنید

سازگاری با نسخه‌های macOS

حداقل: macOS 12.0 (Monterey) توصیه شده: macOS 13.0 (Ventura) یا جدیدتر

بررسی سازگاری:

# بررسی نسخه macOS
sw_vers

# بررسی معماری (Apple Silicon در مقابل Intel)
uname -m

مشکلات ویژه پایگاه داده

"Relation does not exist"

هنگام کوئری جداول:

1. بررسی Schema:

   -- لیست تمام جداول در Schema فعلی
   \dt
   
   -- لیست جداول در تمام Schemaها
   SELECT schemaname, tablename
   FROM pg_tables
   WHERE tablename LIKE '%your_table%';
   

2. استفاده از نام‌های واجد شرایط:

   -- به جای: SELECT * FROM users;
   -- از واجد شرایط schema استفاده کنید:
   SELECT * FROM public.users;
   SELECT * FROM auth.users;
   

3. تنظیم Schema پیش‌فرض:

   • اتصال را در HarborDB ویرایش کنید
   • "Default Schema" را به Schema پرکاربرد تنظیم کنید

خطاهای مجوز روی اشیاء پایگاه داده

Permission denied for relation

1. بررسی مجوزهای شما:

   -- به عنوان superuser یا مالک جدول متصل شوید
   SELECT grantee, privilege_type
   FROM information_schema.role_table_grants
   WHERE table_name = 'your_table';
   

2. درخواست مجوزها:

   -- مثال: اعطای مجوز SELECT
   GRANT SELECT ON table_name TO your_username;
   

مدیریت مجموعه داده بزرگ

"Out of memory" یا بسیار کند:

1. استفاده از صفحه‌بندی سمت سرور:

   -- به جای: SELECT * FROM huge_table;
   -- استفاده کنید:
   SELECT * FROM huge_table LIMIT 1000 OFFSET 0;
   -- سپس OFFSET را برای صفحات بعدی افزایش دهید
   

2. فعال کردن Streaming در HarborDB:

   • Preferences → Performance → Streaming Mode
   • آستانه تنظیم کنید (مثلاً 10,000 ردیف)

3. برای کوئری‌های پیچیده مکرر از Materialized Views استفاده کنید

مشکلات شبکه و اتصال از راه دور

اتصال از راه دور کند

نکات بهینه‌سازی:

1. فعال کردن فشرده‌سازی:

   • Connection settings → Advanced → Compression
   • اندازه انتقال داده را کاهش می‌دهد

2. استفاده از SSH Tunneling:

   • امن‌تر از اتصال مستقیم
   • می‌تواند عملکرد را در شبکه‌های محدود بهبود بخشد

3. زمان‌بندی کوئری‌های سنگین:

   • در ساعت‌های خارج از اوج اجرا کنید
   • از ویژگی زمان‌بندی کوئری HarborDB استفاده کنید

قطع اتصال متناوب

1. افزایش تنظیمات Timeout:

   • Connection settings → Timeout
   • از 30 به 60 ثانیه افزایش دهید

2. فعال کردن Keep-Alive:

   • Connection settings → Keep-Alive
   • اتصالات بیکار را حفظ می‌کند

3. بررسی پایداری شبکه:

   # تست پایداری شبکه
   ping -c 100 your-server-address
   # به دنبال از دست رفتن بسته باشید
   

قبل از تماس با پشتیبانی

اطلاعات برای جمع‌آوری

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

1. اطلاعات سیستم:

   • نسخه macOS (Apple menu → About This Mac)
   • نسخه HarborDB (HarborDB → About HarborDB)
   • نسخه PostgreSQL (SELECT version();)

2. جزئیات خطا:

   • پیام خطای دقیق (اسکرین‌شات در صورت امکان)
   • مراحل بازتولید مشکل
   • زمان شروع مشکل

3. جزئیات پیکربندی:

   • تنظیمات اتصال (بدون رمزهای عبور)
   • کوئری ایجادکننده مشکل (در صورت وجود)
   • تنظیمات صادرسازی (اگر مربوط به صادرسازی است)

ابزارهای تشخیصی در HarborDB

1. تولید گزارش تشخیصی:

   • Help → Create Diagnostic Report
   • شامل لاگ‌ها، پیکربندی، اطلاعات سیستم می‌شود

2. مشاهده لاگ‌های برنامه:

   • Help → Show Logs
   • فیلتر برای پیام‌های خطا و هشدار

3. Console.app برای لاگ‌های سیستم:

   • Console.app را باز کنید
   • "HarborDB" را جستجو کنید
   • به دنبال گزارش‌های crash باشید

خودبررسی سریع

قبل از تماس با پشتیبانی، تأیید کنید:

• [ ] macOS به‌روز است
• [ ] HarborDB آخرین نسخه است
• [ ] سرور PostgreSQL در حال اجرا است
• [ ] اتصال شبکه پایدار است
• [ ] فضای دیسک کافی موجود است
• [ ] کاربر مجوزهای لازم را دارد

تماس با پشتیبانی

اگر تمام مراحل رفع عیب را امتحان کرده‌اید و مشکل ادامه داشت:

1. ایمیل پشتیبانی: support@harbordb.com

2. در ایمیل خود شامل کنید:

   • گزارش تشخیصی (از منوی Help)
   • اسکرین‌شات‌های پیام‌های خطا
   • مراحل بازتولید مشکل
   • چه مراحل رفع عیبی را امتحان کرده‌اید

3. زمان پاسخ مورد انتظار:

   • پاسخ اولیه: در عرض ۲۴-۴۸ ساعت
   • ساعات کاری: دوشنبه-جمعه، ۹AM-۵PM EST
   • مشکلات اضطراری: ایمیل را به عنوان "URGENT" علامت‌گذاری کنید

اقدامات پیشگیرانه

نگهداری منظم

هفتگی:

• HarborDB را برای پاک کردن حافظه مجدداً راه‌اندازی کنید
• فایل‌های صادرسازی موقت را پاک کنید
• تنظیمات اتصال مهم را پشتیبان‌گیری کنید

ماهانه:

• HarborDB و PostgreSQL را به‌روزرسانی کنید
• کوئری‌های کند را مرور و بهینه کنید
• اتصالات استفاده نشده را پاک کنید

بهترین شیوه‌ها برای جلوگیری از مشکلات

1. مدیریت اتصال:

   • از نام‌های اتصال معنادار استفاده کنید
   • به طور منظم اتصالات را تست کنید
   • اتصالات استفاده نشده را حذف کنید

2. توسعه کوئری:

   • همیشه در طول اکتشاف از LIMIT استفاده کنید
   • قبل از اجرای کوئری‌های بزرگ با EXPLAIN تست کنید
   • کوئری‌های پیچیده را برای استفاده مجدد ذخیره کنید

3. نگهداری سیستم:

   • macOS را به‌روز نگه دارید
   • پشتیبان‌گیری منظم Time Machine
   • فضای دیسک را نظارت کنید

منابع اضافی

• سؤالات متداول HarborDB - پاسخ به سؤالات رایج
• راهنمای شروع به کار - نصب و راه‌اندازی
• بهینه‌سازی عملکرد - تنظیم پیشرفته
• راهنمای امنیت macOS - بهترین شیوه‌های امنیتی