نصب در زیرپوشه

Pitchbar می‌تواند در یک زیرپوشه از دامنه شما اجرا شود، نه یک زیردامنه اختصاصی — زمانی مفید است که یک دامنه را با سرویس‌های دیگر به اشتراک می‌گذارید (سایت بازاریابی در ریشه، Pitchbar در /app، صفحه وضعیت در /status). لاراول + Vite این را فقط با پیکربندی مدیریت می‌کنند؛ بدون نیاز به تغییر کد.

راهنمای زیر فرض می‌کند که می‌خواهید Pitchbar را در https://aichat.com/app داشته باشید. میزبان + مسیر خود را در هر جایی که این مقادیر را می‌بینید، جایگزین کنید.

۱. تنظیم APP_URL

فایل .env را در سرور تولید باز کنید. تنظیم کنید:

APP_URL=https://aichat.com/app

# نشست + Sanctum به میزبان (بدون مسیر) نیاز دارند.
SESSION_DOMAIN=aichat.com
SANCTUM_STATEFUL_DOMAINS=aichat.com

# مبدأ websocket Reverb — همان میزبان:پورت APP_URL.
REVERB_HOST=aichat.com
REVERB_PORT=443
REVERB_SCHEME=https

پس از ویرایش، php artisan config:clear + php artisan route:clear را اجرا کنید.

۲. اشاره ریشه اسناد به public/

مخزن Pitchbar یک برنامه لاراول است. ریشه اسناد عمومی باید public/ باشد، نه ریشه مخزن. در نصب زیرپوشه، سرور وب شما باید زیرمسیر را به آن دایرکتوری نگاشت کند.

Apache (.htaccess)

# /var/www/aichat.com/app -> مخزن Pitchbar
# /var/www/aichat.com/app/public ریشه اسناد برای /app است.
Alias /app /var/www/aichat.com/pitchbar/public

<Directory /var/www/aichat.com/pitchbar/public>
    AllowOverride All
    Require all granted
</Directory>

Nginx

server {
    listen 443 ssl http2;
    server_name aichat.com;
    root /var/www/aichat.com/marketing-site;  # سایت ریشه شما

    # زیرپوشه Pitchbar.
    location ^~ /app/ {
        alias /var/www/aichat.com/pitchbar/public/;
        try_files $uri $uri/ @pitchbar;

        location ~ \.php$ {
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $request_filename;
            fastcgi_param SCRIPT_NAME    /app/index.php;
            fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        }
    }

    location @pitchbar {
        rewrite ^/app(/.*)$ /app/index.php?$1 last;
    }
}

۳. دارایی‌های Vite

Vite APP_URL را در زمان ساخت می‌خواند تا مسیرهای مانیفست صحیح را بنویسد، بنابراین برنامه SPA مدیریت + بسته ویجت به‌طور خودکار در زیرپوشه حل می‌شوند. پس از استقرار، اجرا کنید:

npm ci
npm run build
npm run build:widget

public/build/manifest.json را بررسی کنید — ورودی‌ها باید در زمان ارائه در /app/build/... حل شوند.

۴. لینک نمادین ذخیره‌سازی

php artisan storage:link

public/storage ← storage/app/public را ایجاد می‌کند. لوگوهای برند آپلودشده، خروجی‌های عمومی و فایل‌های آواتار در آنجا قرار می‌گیرند؛ بدون لینک نمادین، خطای ۴۰۴ می‌دهند.

۵. قطعه نصب ویجت

مشتریان ویجت را از طریق یک تگ <script> در سایت خود نصب می‌کنند. آدرس باید به زیرپوشه شما اشاره کند:

<script
    src="https://aichat.com/app/widget/widget.js"
    data-agent-id="agent_..."
    defer
></script>

دکمه "کپی قطعه نصب" مدیریت در /app/agents/{id} آدرس را از APP_URL استخراج می‌کند، بنابراین تا زمانی که مرحله ۱ صحیح باشد، قطعه‌ای که مشتریان شما کپی می‌کنند، از قبل شامل زیرپوشه خواهد بود.

۶. پردازشگر صف + زمان‌بند

هر دو همچنان از ریشه مخزن اجرا می‌شوند و تحت تأثیر زیرپوشه قرار نمی‌گیرند:

php artisan queue:work
php artisan schedule:work

درایور پردازشگر cron کلودفلر (پیش‌فرض تولید) به https://aichat.com/app/api/v1/internal/queue-tick درخواست می‌زند — زمانی که آن را از /admin/integrations/cron-worker استقرار می‌دهید، اتصال QUEUE_TICK_URL پردازشگر را به‌روز کنید.

عیب‌یابی

برنامه SPA مدیریت در همه مسیرها به جز /app خطای ۴۰۴ می‌دهد

بازنویسی سرور وب، آدرس‌های لاراول را به index.php ارسال نمی‌کند. تأیید کنید که .htaccess داخل public/ در حال خوانده شدن است (Apache: AllowOverride All) یا بازگشت @pitchbar Nginx فعال می‌شود (Nginx: ترتیب try_files).

بسته ویجت خطای ۴۰۴ می‌دهد

ویجت پس از ساخت، یک نام فایل هش‌شده (widget.<hash>.js) منتشر می‌کند. قطعه data-agent-id به widget.js بدون هش اشاره می‌کند که آن نیز منتشر می‌شود. اگر خطای ۴۰۴ داد، npm run build:widget را پس از استقرار رد کرده‌اید.

کوکی نشست در میزبان‌های زیردامنه تنظیم نمی‌شود

اگر سایت بازاریابی را در aichat.com و Pitchbar را در aichat.com/app ارائه می‌دهید، هر دو میزبان کوکی یکسان اما مسیرهای متفاوتی دارند. SESSION_PATH=/app را در .env تنظیم کنید تا کوکی نشست لاراول به زیرپوشه محدود شود — بدون این، کوکی تنظیم‌شده توسط Pitchbar ممکن است توسط کتابخانه نشست سایت والد بازنویسی شود.

CSP / محتوای مختلط

CSP پیش‌فرض در میان‌افزار AddSecurityHeaders فقط self را برای اسکریپت‌ها مجاز می‌داند. اگر دارایی‌های ایستا را روی یک CDN میزبانی می‌کنید، میزبان CDN را از طریق کلید پیکربندی app_security.csp_extra_script_src به script-src اضافه کنید.

ارتقای websocket Reverb ناموفق است

Reverb روی پورت خود (پیش‌فرض ۸۰۸۰) گوش می‌دهد. پراکسی معکوس شما باید ارتقای WebSocket را پراکسی کند — برای Nginx اینگونه است:

location /reverb/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}

این موارد چه چیزی را تغییر نمی‌دهد

• نقاط پایانی وب‌هوک (Stripe، PayPal، Razorpay، افزونه وردپرس) آدرس خود را از APP_URL استخراج می‌کنند، بنابراین به‌طور خودکار شامل زیرپوشه می‌شوند. اگر از یک میزبان متفاوت مهاجرت کرده‌اید، آنها را در داشبوردهای مربوطه دوباره ثبت کنید.
• JWT ویجت همچنان به allowed_origins روی دستیار فروش متصل می‌شود — که مبدأ سایت مشتری است، نه میزبان Pitchbar شما. نصب زیرپوشه بر این که کدام سایت‌ها می‌توانند نصب کنند، تأثیری ندارد.
• محدوده فضاهای کاری، درگاه‌های صورتحساب، حل BYOK و تأخیر مسیر اصلی SSE همگی تحت تأثیر قرار نمی‌گیرند.