پرش به محتویات

عیب‌یابی رایج

در این بخش راه‌حل مشکلات رایج را بررسی می‌کنیم.

مشکلات نصب

مشکل: اسکریپت اجرا نمی‌شود

ویندوز:

  1. PowerShell را به صورت Administrator اجرا کنید
  2. دستور زیر را اجرا کنید: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. دوباره اسکریپت را اجرا کنید

لینوکس:

# اجازه اجرا به فایل بدهید
chmod +x start-penpot.sh

# سپس اجرا کنید
./start-penpot.sh

یا با sudo: 

sudo ./start-penpot.sh

مشکل: Docker نصب نمی‌شود

ویندوز:

  • مطمئن شوید که WSL2 نصب است
  • Virtualization را در BIOS فعال کنید
  • از Docker Desktop به صورت دستی نصب کنید

لینوکس:

# بررسی کنید که Virtualization فعال است
grep -E 'vmx|svm' /proc/cpuinfo

# اگر خالی بود، Virtualization در BIOS فعال نیست

مشکل: Port 9001 در حال استفاده است

راه‌حل ۱: متوقف کردن Penpot

docker compose down

سپس دوباره اجرا کنید: 

docker compose up -d

راه‌حل ۲: تغییر پورت

در فایل .env پورت را تغییر دهید:

PENPOT_PUBLIC_URI=http://localhost:9002

سپس در docker-compose.yml پورت را تغییر دهید:

ports:
  - "9002:9001"

راه‌حل ۳: پیدا کردن و متوقف کردن برنامه دیگر

ویندوز: 

netstat -ano | findstr :9001
taskkill /PID [PID-NUMBER] /F

لینوکس: 

sudo lsof -i :9001
sudo kill -9 [PID-NUMBER]

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

مشکل: حافظه کم

علائم: - Penpot کند است - خطاهای "Out of Memory" - سیستم فریز می‌شود

راه‌حل:

  1. بررسی استفاده از RAM: 

    # ویندوز: Task Manager
# لینوکس:
free -h

  2. بستن برنامه‌های دیگر

  3. محدود کردن حافظه Docker:

در فایل docker-compose.yml: 

services:
  penpot-frontend:
    mem_limit: 2g
  penpot-backend:
    mem_limit: 4g

  1. افزایش RAM (اگر ممکن است)

حداقل نیاز: ۸ گیگابایت RAM

مشکل: فضای دیسک کم

بررسی فضای خالی:

# ویندوز: در File Explorer
# لینوکس:
df -h

پاک کردن ایمیج‌های استفاده نشده:

docker system prune -a

حذف volumes قدیمی:

# مراقب باشید! این داده‌ها را پاک می‌کند
docker volume prune

مشکل: سرعت پایین

علل احتمالی:

  1. RAM کم — حداقل ۸ گیگابایت نیاز است
  2. هارد دیسک کند — استفاده از SSD توصیه می‌شود
  3. CPU ضعیف — پردازنده دو هسته‌ای یا بهتر نیاز است

راه‌حل:

  • استفاده از SSD به جای HDD
  • افزایش RAM
  • بستن برنامه‌های دیگر
  • استفاده از سرور قوی‌تر برای تیم

مشکلات اتصال

مشکل: نمی‌توانم به Penpot دسترسی پیدا کنم

بررسی وضعیت سرویس‌ها:

docker compose ps

همه سرویس‌ها باید Up باشند.

بررسی لاگ‌ها:

docker compose logs

یا برای سرویس خاص: 

docker compose logs penpot-frontend
docker compose logs penpot-backend

بررسی پورت:

# ویندوز:
netstat -ano | findstr :9001

# لینوکس:
sudo lsof -i :9001

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

بررسی تنظیمات .env:

PENPOT_PUBLIC_URI=http://192.168.1.100:9001

(به جای 192.168.1.100، IP واقعی سرور را قرار دهید)

بررسی فایروال:

ویندوز: - Windows Firewall → Allow an app - Docker Desktop و پورت 9001 را اضافه کنید

لینوکس: 

# UFW
sudo ufw allow 9001/tcp

# یا firewalld
sudo firewall-cmd --add-port=9001/tcp --permanent
sudo firewall-cmd --reload

بررسی IP:

# ویندوز:
ipconfig

# لینوکس:
ip addr show

مشکلات داده

مشکل: داده‌هایم گم شده

بررسی volumes:

docker volume ls
docker volume inspect [volume-name]

بازیابی از بکاپ:

اگر بکاپ دارید: 

# 1. Penpot را متوقف کنید
docker compose down

# 2. volumes قدیمی را حذف کنید
docker volume rm [volume-name]

# 3. بکاپ را بازیابی کنید
cp -r volumes-backup volumes

# 4. راه‌اندازی مجدد
docker compose up -d

مشکل: نمی‌توانم فایل import کنم

بررسی فرمت فایل: - Penpot از فایل‌های .fig (Figma) پشتیبانی می‌کند - فرمت‌های دیگر ممکن است پشتیبانی نشوند

بررسی اندازه فایل: - فایل‌های خیلی بزرگ ممکن است مشکل ایجاد کنند - سعی کنید فایل را به بخش‌های کوچک‌تر تقسیم کنید

مشکل: تغییرات ذخیره نمی‌شود

بررسی فضای دیسک: - اگر فضای دیسک پر باشد، تغییرات ذخیره نمی‌شود

بررسی دسترسی‌ها: 

# لینوکس:
ls -la volumes/

مطمئن شوید که Docker دسترسی نوشتن دارد.

مشکلات Docker

مشکل: Docker اجرا نمی‌شود

ویندوز:

  1. Docker Desktop را باز کنید
  2. Settings → General → Restart Docker Desktop
  3. اگر کار نکرد، Docker Desktop را uninstall و دوباره install کنید

لینوکس:

# بررسی وضعیت سرویس
sudo systemctl status docker

# راه‌اندازی سرویس
sudo systemctl start docker
sudo systemctl enable docker

مشکل: ایمیج دانلود نمی‌شود

بررسی اتصال اینترنت:

ping docker.io

استفاده از رجیستری ایرانی:

رجیستری آروان‌کلاود را تنظیم کنید. راهنمای نصب با اینترنت ملی →

استفاده از بسته آفلاین:

اگر اینترنت ندارید، از بسته آفلاین استفاده کنید.

مشکل: Container متوقف می‌شود

بررسی لاگ‌ها:

docker compose logs [service-name]

بررسی منابع:

docker stats

ممکن است RAM یا CPU کافی نباشد.

راه‌اندازی مجدد:

docker compose restart [service-name]

یا: 

docker compose down
docker compose up -d

مشکلات مرورگر

مشکل: صفحه سفید نمایش داده می‌شود

  1. پاک کردن کش مرورگر:
  2. Ctrl+Shift+Delete

  3. Clear cache and cookies

  4. استفاده از مرورگر دیگر:

  5. Chrome, Firefox, Edge را امتحان کنید

  6. بررسی Console:

  7. F12 → Console
  8. خطاها را بررسی کنید

مشکل: فونت‌ها درست نمایش داده نمی‌شود

بررسی فایل CSS:

مطمئن شوید که فایل custom.css درست لود شده است.

بررسی فونت‌ها:

مطمئن شوید که فایل‌های فونت در مسیر درست هستند: 

docs/static/fonts/Vazirmatn-Regular.woff2
docs/static/fonts/Vazirmatn-Bold.woff2

راه‌اندازی مجدد کامل

اگر هیچ کدام از راه‌حل‌ها کار نکرد:

# 1. متوقف کردن همه چیز
docker compose down

# 2. حذف containers
docker compose rm -f

# 3. حذف volumes (مراقب باشید! داده‌ها پاک می‌شود)
docker volume rm [volume-names]

# 4. پاک کردن ایمیج‌ها
docker rmi [image-names]

# 5. راه‌اندازی مجدد
docker compose up -d

دریافت کمک بیشتر

اگر مشکل شما حل نشد:

  1. بررسی لاگ‌ها: 

    docker compose logs > logs.txt

  2. گزارش مشکل:

  3. به گیت‌هاب بروید
  4. Issue جدید باز کنید

  5. لاگ‌ها و جزئیات مشکل را اضافه کنید

  6. مستندات Penpot:

  7. مستندات رسمی Penpot
  8. انجمن Penpot

نکته: همیشه قبل از انجام تغییرات بزرگ، از داده‌هایتان بکاپ بگیرید!