مستنداتامنیت
مدیریت API
مستندات API / امنیت

امنیت و مدیریت کلید

الگوی امن نگهداری، استفاده، چرخش و لغو API Key در محیط production.

اصل اول

کلید فقط در سمت سرور

API Key یک secret کامل است و هرکس آن را داشته باشد می‌تواند از اعتبار حساب شما مصرف کند.

انجام دهید

  • Secret manager یا متغیر محیطی
  • کلید جدا برای development و production
  • ارسال درخواست از API route یا serverless function
  • لغو فوری کلید مشکوک

انجام ندهید

  • قرار دادن کلید در NEXT_PUBLIC_*
  • ارسال مستقیم از مرورگر یا اپ عمومی
  • ثبت کلید کامل در log و telemetry
  • commit کردن فایل .env

الگوی production

یک proxy کوچک در بک‌اند بسازید

Server routeTypeScript
export async function POST(request: Request) {
  const { message } = await request.json()

  // ورودی کاربر را قبل از ارسال اعتبارسنجی کنید.
  const response = await fetch('https://kujichat.com/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.KUJICHAT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'kuji-v0',
      messages: [
        { role: 'user', content: String(message).slice(0, 4000) },
      ],
    }),
  })

  return new Response(response.body, {
    status: response.status,
    headers: { 'Content-Type': 'application/json' },
  })
}

چرخهٔ عمر

چرخش و لغو کلید

  1. کلید جدید بسازید

    کلید جدید را برای همان محیط بسازید و مقدار کامل را در secret manager ذخیره کنید.

  2. بدون downtime جابه‌جا شوید

    deployment را با secret جدید منتشر و یک درخواست آزمایشی ارسال کنید.

  3. کلید قدیمی را لغو کنید

    پس از تأیید عملکرد، کلید قبلی را از پنل غیرفعال کنید.

قبل از انتشار

چک‌لیست امنیت production

کلید فقط در secretهای محیط اجراست.
ورودی کاربر محدود و اعتبارسنجی می‌شود.
timeout برای HTTP client تنظیم شده است.
429 و 5xx با retry محدود مدیریت می‌شوند.
متن حساس و کلید کامل log نمی‌شود.
برای usage و خطاهای غیرعادی مانیتورینگ دارید.