BYOK (کلیدهای هوش مصنوعی فضای کاری)

BYOK — مخفف Bring Your Own Keys (کلیدهای خود را بیاورید) — به هر فضای کاری اجازه می‌دهد هزینه‌ی سرویس‌های Cloudflare، OpenAI، OpenRouter یا Qdrant خود را جداگانه پرداخت کند، به جای اینکه از اعتبارنامه‌های اشتراکی اپراتور پلتفرم استفاده کند. این قابلیت برای اپراتورهایی که Pitchbar را به‌عنوان SaaS به مشتریان متعدد می‌فروشند، بسیار کاربردی است: چت، جستجوی هوشمند و ذخیره‌سازی جستجوی هوشمند هر مشتری در حساب بالادستی خودشان ثبت می‌شود، نه در حساب شما.

نحوه‌ی کارکرد ماتریس سیاست‌ها

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

کلید سراسری	لغو هر کاربر	BYOK فعال است؟
خاموش	تنظیم نشده	خیر — از کلیدهای پلتفرم استفاده می‌شود.
خاموش	اجبار به روشن	بله — این کاربر با وجود خاموش بودن پیش‌فرض پلتفرم، به BYOK دسترسی دارد.
خاموش	اجبار به خاموش	خیر.
روشن	تنظیم نشده	بله — هر فضای کاری باید کلیدهای خود را وارد کند.
روشن	اجبار به روشن	بله (همانند حالت تنظیم‌نشده وقتی کلید سراسری روشن است).
روشن	اجبار به خاموش	خیر — رد صریح همیشه برنده است.

این ماتریس توسط App\Support\ByokResolver::isUnlockedFor($user, $workspace) اعمال می‌شود. اتصالات LLM و بردار در هر بار حل، این تابع را فراخوانی می‌کنند، بنابراین تغییر یک کلید در درخواست بعدی بدون نیاز به بارگذاری مجدد Octane اعمال می‌شود.

فعالسازی BYOK

سراسری (همه فضاهای کاری)

1. به‌عنوان مدیر ارشد وارد شوید.
2. /settings/system را باز کنید.
3. کلید "فعالسازی سراسری BYOK" را روشن کنید. ذخیره کنید.

از این لحظه به بعد، هر فضای کاری باید کلیدهای خود را وارد کند تا ویجت آن بتواند به بازدیدکنندگان پاسخ دهد. فضاهای کاری بدون کلید، به‌جای نمایش خطا، یک پیام دوستانه "این فضای کاری پیکربندی نشده است" در چت نشان می‌دهند.

لغو در سطح کاربر

1. به‌عنوان مدیر ارشد وارد شوید.
2. /admin/users را باز کنید.
3. کاربر مورد نظر را پیدا کنید. ستون BYOK دارای یک منوی کشویی سه‌حالته است:
   • پیروی از سراسری (پیش‌فرض) — از کلید سراسری پیروی می‌کند.
   • اجبار به فعال — دسترسی BYOK را فقط به این کاربر اعطا می‌کند.
   • اجبار به غیرفعال — BYOK را برای این کاربر مسدود می‌کند. همیشه برنده است.

مشتریان کلیدهای خود را کجا وارد می‌کنند

وقتی BYOK برای یک فضای کاری فعال شود، یک ورودی کلیدهای هوش مصنوعی در نوار کناری تنظیمات مشتری ظاهر می‌شود (بین توکن‌های API و صفحات پلتفرم). روی آن کلیک کنید تا /settings/byok-keys باز شود:

• Cloudflare — account_id، توکن API، نام شاخص Vectorize، لغوهای اختیاری مدل چت / جستجوی هوشمند.
• OpenAI — کلید API، لغوهای اختیاری مدل چت / جستجوی هوشمند.
• OpenRouter — کلید API، لغو اختیاری مدل چت.
• Qdrant — آدرس پایه، کلید API، نام مجموعه.

هر بخش یک دکمه‌ی ذخیره جداگانه دارد تا مشتری بتواند سرویس‌ها را یک‌یک پیکربندی کند، و یک دکمه‌ی پاک کردن جداگانه برای پاک کردن فقط اعتبارنامه‌های همان سرویس. فرم هرگز کلیدها را به رابط کاربری بازنمی‌گرداند — مشتریان در هر بار تغییر، آنها را دوباره وارد می‌کنند. فیلدهای عمومی (account_id، نام مدل‌ها، نام شاخص‌ها، آدرس Qdrant) از قبل پر شده‌اند.

مدیران ارشد ورودی "کلیدهای هوش مصنوعی" را نمی‌بینند. آنها اعتبارنامه‌های سراسری پلتفرم را در /settings/system → سرویس‌های هوش مصنوعی مدیریت می‌کنند. BYOK در سطح فضای کاری فقط برای مشتریان است.

چه چیزی ذخیره می‌شود، کجا و چگونه محافظت می‌شود

فیلد	ستون پایگاه داده	رمزگذاری
همه اعتبارنامه‌های BYOK	workspaces.byok_keys (نقشه JSON)	encrypted:array از طریق APP_KEY
کلید سراسری	app_settings.byok_enabled_globally (boolean)	ساده (یک کلید عمومی است)
لغو در سطح کاربر	users.byok_enabled (nullable boolean)	ساده

ستون رمزگذاری‌شده یک پاکت Laravel Crypt را ذخیره می‌کند. ستون خام پایگاه داده هرگز حاوی اعتبارنامه‌های ساده نیست — هر کسی که مستقیماً ستون را بخواند فقط یک بلوک base64 می‌بیند. رمزگشایی نیاز به APP_KEY دارد؛ چرخش APP_KEY ستون را غیرقابل خواندن می‌کند تا زمانی که مشتریان دوباره کلیدها را وارد کنند.

تضمین‌های ایزوله‌سازی فضای کاری

BYOK هر فضای کاری را از سایر فضاها جدا می‌کند. مرز در پنج لایه اعمال می‌شود:

1. رمزگذاری ستون پایگاه داده. خواندن workspaces.byok_keys خارج از برنامه، یک پاکت Crypt را برمی‌گرداند، نه توکن ساده.
2. حل فضای کاری. هر فراخوانی به ByokResolver::keysFor(...) یک مدل Workspace دریافت می‌کند که از CurrentWorkspace::get() آمده است. این راهنما، فضای کاری را از default_workspace_id مدیر تأییدشده یا agent.workspace_id JWT ویجت حل می‌کند — هرگز از ورودی بدنه درخواست. هیچ جستجوی سراسری وجود ندارد که بتواند فضای کاری اشتباهی را نشت دهد.
3. طول عمر اتصال ظرف. OpenAiClient و QdrantClient به‌صورت scoped() در AppServiceProvider متصل هستند، نه singleton(). هر درخواست HTTP، مشتری را بازسازی می‌کند. کلیدهای فضای کاری A هرگز در حافظه پردازشگر برای درخواست بعدی فضای کاری B باقی نمی‌مانند، حتی در Octane.
4. سطح تغییر. ByokKeysController::clear و ::update فضای کاری را از CurrentWorkspace حل می‌کنند، هرگز از یک پارامتر ?workspace_id=. فضای کاری A نمی‌تواند کلیدهای فضای کاری B را از طریق هیچ فراخوانی API مستند پاک یا بخواند.
5. تست‌های بازگشتی منفی. tests/Feature/Byok/ByokTenantIsolationTest.php هر تضمین را قفل می‌کند — رمزگذاری در حالت استراحت، A-B را نمی‌بیند، تغییر A به B دست نمی‌زند، پاک کردن A به B دست نمی‌زند. حذف هر یک از محافظت‌ها، مجموعه تست را با شکست مواجه می‌کند.

جریان حل در زمان اجرا

وقتی بازدیدکننده پیامی ارسال می‌کند، اتصال ظرف LLM اجرا می‌شود:

1. CurrentWorkspace را از JWT ویجت حل می‌کند.
2. ByokResolver::isUnlockedFor($user, $workspace) را فراخوانی می‌کند (جریان بازدیدکننده کاربر ندارد، بنابراین resolver فقط کلید سراسری و کلیدهای فضای کاری را بررسی می‌کند).
3. اگر فعال باشد و workspaces.byok_keys کلیدهای سرویس‌دهنده‌ی مربوطه را داشته باشد، مشتری را با آن اعتبارنامه‌ها می‌سازد.
4. اگر فعال باشد اما کلیدها وجود نداشته باشند و کلید سراسری روشن باشد، MissingByokKeyException را پرتاب می‌کند — بازدیدکننده یک پیام دوستانه "فضای کاری پیکربندی نشده" می‌بیند، نه یک خطای سیستمی.
5. در غیر این صورت (کلید سراسری خاموش + بدون لغو هر کاربر + بدون کلید فضای کاری) به اعتبارنامه‌های سراسری پلتفرم بازمی‌گردد.

همین زنجیره، انتخاب اتصال Vectorize / Qdrant، اعتبارنامه‌های Cloudflare Browser Rendering خزنده و رتبه‌بندی مجدد را نیز هدایت می‌کند.

سوالات متداول

آیا مشتریان BYOK هیچ‌چیز به Pitchbar پرداخت نمی‌کنند؟

آنها همچنان برای خود برنامه به شما پرداخت می‌کنند (اشتراک، پیشنهاد مادام‌العمر). BYOK فقط هزینه‌های متغیر هوش مصنوعی، جستجوی هوشمند و بارگذاری کامل صفحات را جابه‌جا می‌کند. صورتحساب Pitchbar شما با قبض بالادستی هوش مصنوعی ارتباطی ندارد.

وقتی کلید سراسری را روشن می‌کنم، چه اتفاقی برای فضاهای کاری موجود با کلید پلتفرم می‌افتد؟

درخواست بعدی آنها کلیدها را از دست می‌دهد و پیام "فضای کاری پیکربندی نشده" را می‌بینند. راه‌حل یکی از موارد زیر است:

• مالک فضای کاری کلیدها را از طریق /settings/byok-keys وارد کند.
• آن کاربر خاص را مجبور به رد کنید (مدیر ارشد → /admin/users) تا به اعتبارنامه‌های پلتفرم بازگردند.
• کلید سراسری را خاموش کنید و فقط برای مشتریانی که می‌خواهید در BYOK باشند، فعال کنید.

آیا می‌توانم APP_KEY را تغییر دهم؟

بله، اما ورودی‌های موجود رمزگذاری‌شده در ستون byok_keys با کلید قدیمی مهر و موم شده‌اند — چرخش آنها را تا زمانی که مشتریان دوباره کلیدها را وارد کنند، غیرقابل خواندن می‌کند. یک دستور artisan یک‌باره (یا مهاجرت درجا) اجرا کنید تا با کلید قدیمی رمزگشایی و با کلید جدید رمزگذاری مجدد شود. همین نکته در مورد هر تبدیل encrypted دیگر در برنامه نیز صدق می‌کند.

آیا BYOK بر محافظت‌های SSRF خزنده تأثیر می‌گذارد؟

خیر. محافظت SSRF (لیست ممنوعه IPهای خصوصی + محافظت در برابر تغییر DNS) صرف‌نظر از اینکه کدام حساب Cloudflare آدرس را دریافت می‌کند، اجرا می‌شود. BYOK فقط اعتبارنامه‌ها را عوض می‌کند؛ شبکه ایمنی سر جای خود باقی می‌ماند.

مشتریان BYOK مصرف خود را کجا می‌بینند؟

آن را در داشبورد سرویس‌دهنده‌ی خود (Cloudflare، OpenAI، Qdrant Cloud) بررسی می‌کنند — Pitchbar مصرف را به آنها بازنمی‌گرداند. تحلیل‌های سطح فضای کاری در داشبورد Pitchbar شما همچنان تعداد مکالمات و پیام‌ها را نشان می‌دهد که برای همبستگی آنها کافی است.