راهنمای فنی سرور
برای کسی که سایت را روی سرور نگه می‌دارد. کوتاه و بدون توضیح اضافه: داده کجاست، پشتیبان چطور گرفته می‌شود، چطور ری‌استارت می‌شود.
فهرست بخش‌ها
۱. ساختار پروژه
| فریم‌ورک | Next.js 16 — App Router، React 19، TypeScript |
|---|---|
| استایل | Tailwind 4 |
| پکیج‌منیجر | pnpm (نسخه پین‌شده در package.json) |
| دیتابیس | ندارد. همه‌چیز در فایل JSON. |
| خروجی بیلد | standalone — یعنی .next/standalone/server.js |
| مسیر سایت | ~/Projects/saeed-site |
چون داده در فایل است، هر صفحه‌ای که از داده می‌خواند بعد از هر ذخیره با
revalidatePath تازه می‌شود. لازم نیست بعد از تغییر محتوا بیلد بگیرید.
فقط تغییر کد بیلد و ری‌استارت می‌خواهد.
۲. نصب و اجرا
دستی
cd ~/Projects/saeed-site
pnpm install
pnpm build
PORT=3300 pnpm start # http://127.0.0.1:3300
برای توسعه، pnpm dev را بزنید. پورت پیش‌فرضش ۳۰۰۰ است؛
اگر پورت دیگری خواستید، با متغیر PORT بدهید.
داکر
یک Dockerfile در ریشه پروژه هست: بیلد چندمرحله‌ای، خروجی standalone،
کاربر غیر روت، PORT=3300، و پوشه data/ که باید از هاست مانت شود
تا پنل بتواند در آن بنویسد.
docker build -t pscgame .
docker run -d --name pscgame -p 3300:3300 \
-v /srv/pscgame/data:/app/data \
-v /srv/pscgame/public/catalog:/app/public/catalog \
pscgameمسیرهای مانت نمونه‌اند. روی سرور واقعی، همان مسیرهایی را بگذارید که فایل‌ها در آن‌ها هستند.
pcsgame.nexushost.ir روی چه سرویسی اجرا می‌شود؟ (systemd / docker compose / pm2)
دستور دقیق ری‌استارت:
TODO(deploy): systemctl restart ... / docker compose up -d --build / ...
محل کانفیگ nginx یا پروکسی و مسیر گواهی TLS:
TODO(deploy): /etc/nginx/...
مسیر پوشه پروژه روی سرور:
TODO(deploy)
نسخه نود روی سرور:
TODO(deploy) (ایمیج داکر از node:22-alpine استفاده می‌کند)
وضعیت روی این ماشین
هنگام نوشتن این راهنما، سایت روی همین ماشین با یک پروسه next-server روی پورت
۳۳۰۰ اجرا می‌شد، از پوشه ~/Projects/saeed-site، دستی و بدون سرویس مدیریت‌شده.
هیچ سرویس systemd یا یونیت کاربری برایش پیدا نشد.
یعنی با ری‌استارت ماشین، سایت هم بالا نمی‌آید. برای سرور واقعی این باید درست شود.
۳. داده‌ها
دو فایل، تمام حالت سایت را نگه می‌دارند:
data/catalog.json |
محصول‌ها، دسته‌بندی‌ها، برندها، تنظیمات (از جمله رمز پنل و مرچنت‌کد)، کاشی‌های صفحه اصلی، ترتیب ردیف‌ها، سفارش‌ها، نظرات، هشدارهای موجودی، درخواست محصول و مقاله‌های بلاگ. |
|---|---|
data/story.json |
بخش‌های استوری هر محصول، کلیدش اسلاگ محصول است. |
فایل کاتالوگ الان حدود ۲ مگابایت است و هر بار کامل بازنویسی می‌شود. نوشتن اتمیک است: اول فایل موقت، بعد جای فایل اصلی می‌نشیند. پس نیمه‌کاره خراب نمی‌شود.
src/lib/store.ts انجام می‌شود.
فایل‌های دیگری هم در data/ هست: seed.json،
specs-i18n.json، story-i18n.json و پوشه‌های خام مرجع.
آن‌ها برای ساخت اولیه بودند و برای اجرای سایت لازم نیستند.
حذفشان نکنید تا زمانی که مطمئن شدید کسی به آن‌ها نیاز ندارد.
۴. پشتیبان‌گیری
دو فایل را کپی کنید. تمام.
cd ~/Projects/saeed-site
mkdir -p /var/backups/pscgame
cp data/catalog.json "/var/backups/pscgame/catalog-$(date +%F-%H%M).json"
cp data/story.json "/var/backups/pscgame/story-$(date +%F-%H%M).json"اگر عکس‌های آپلودشده مهم‌اند، این دو پوشه را هم بردارید:
tar czf "/var/backups/pscgame/media-$(date +%F).tar.gz" \
public/catalog public/media public/uploadsبازگرداندن
- فایل پشتیبان را روی فایل فعلی کپی کنید.
- سایت را ری‌استارت کنید. دلیلش کش درون‌حافظه‌ای است: کد فایل را بر اساس زمان تغییر می‌شناسد، ولی ری‌استارت مطمئن‌ترین راه است.
- در پنل یک محصول را باز کنید و ببینید محتوا برگشته باشد.
۵. فایل‌های رسانه
public/catalog/ | عکس محصول‌ها و لوگوی برندها. حدود ۱۴۵ مگابایت. |
|---|---|
public/catalog/story/ | عکس و ویدیوی آپلودشده از ویرایشگر استوری. |
public/media/ | ویدیوهای کاشی‌های صفحه اصلی. |
public/uploads/ | عکس‌هایی که مشتری با نظر می‌فرستد (حداکثر ۴ فایل، هر کدام ۴ مگابایت). |
فایل‌های public/ داخل ایمیج داکر کپی می‌شوند.
اگر می‌خواهید آپلودها بعد از بیلد تازه بمانند، پوشه‌ها را مانت کنید (در بخش ۲ نمونه‌اش هست).
آپلود استوری به ffmpeg و magick روی سرور نیاز دارد
(عکس به webp، ویدیو به mp4 بدون صدا).
اگر این دو نصب نباشند، آپلود با پیام «تبدیل فایل نشد» رد می‌شود.
۶. دسترسی مدیریت
- رمز در
data/catalog.json→settings.adminPasswordاست. - مقدار پیش‌فرض:
psc-admin. باید عوض شود. - بعد از ورود، کوکی
psc_adminست می‌شود:httpOnly،sameSite=lax، عمر ۱۲ ساعت. - مقدار خود کوکی همان رمز است. یعنی هر کسی کوکی را ببیند رمز را دارد.
- رمز به صورت ساده در فایل ذخیره می‌شود، بدون هش.
data/catalog.json را از دسترس عمومی بیرون نگه دارید
(داخل data/ است، نه public/ — همین‌طور بماند).
۷. نکته‌های شناخته‌شده
- ورود مشتری، پیگیری سفارش و حساب کاربری هنوز پیاده نشده‌اند و روی خود صفحه هم نوشته شده.
- درگاه زرین‌پال در حالت آزمایشی است تا مرچنت‌کد وارد شود؛ سفارش‌ها با وضعیت
demoثبت می‌شوند. - در فرم محصول دکمه آپلود عکس نیست؛ عکس‌ها با آدرس مسیر در
public/catalog/ارجاع داده می‌شوند. - تنوع محصول (مدل و سایز) در پنل ویرایش نمی‌شود.
- اندازه ردیف‌های صفحه اصلی (
homeRowSizes) در پنل نیست. - نام فروشگاه و شعار در پنل ذخیره می‌شوند، ولی در قالب سایت استفاده نمی‌شوند؛ عنوان صفحه‌ها ثابت است.
- متن مرجوعی در صفحه محصول ۳۰ روز و در شرایط و ضوابط ۷ روز است.
- هیچ سرویس systemd برای سایت روی این ماشین ساخته نشده؛ اجرا دستی است.
- ایمیج داکر فقط
libc6-compatنصب می‌کند. قبل از تکیه بر آپلود استوری، نصبffmpegوimagemagickدر ایمیج را بررسی کنید. - سایت هیچ ایمیل و پیامکی نمی‌فرستد؛ اطلاع‌رسانی سفارش دستی است.
۸. چک‌لیست پیش از تحویل
- رمز پنل از
psc-adminعوض شود. - مرچنت‌کد واقعی در پنل ذخیره شود و تیک sandbox برداشته شود.
- یک خرید واقعی کوچک تست شود؛ سفارش باید
paidشود. - سرویس مدیریت‌شده برای سایت ساخته شود تا بعد از ری‌استارت بالا بیاید.
- کرون پشتیبان برای
catalog.jsonوstory.json. - HTTPS و ریدایرکت از
http. - پوشه‌های
data/وpublic/catalog/مانت‌شده و قابل نوشتن برای کاربر اجرا. ffmpegوmagickروی سرور نصب باشند.- بخش‌های TODO(deploy) این صفحه پر شوند.