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

Runtime و Configuration زیرساخت Backend

این صفحه قرارداد اجرای Binary API و مرز Configuration مشترک را تعریف می‌کند. مقدار واقعی Secret و اطلاعات محیط Production در مستندات ثبت نمی‌شود.

Composition و Lifecycle

cmd/api فقط Dependencyها را می‌سازد، Routeها را متصل می‌کند، Migration را اجرا می‌کند و Lifecycle را مدیریت می‌کند. Business Logic، Query و HTTP Mapping در Composition Root مجاز نیست.

ترتیب Startup:

  1. بارگذاری و اعتبارسنجی Configuration؛
  2. ساخت Logger بدون Field حساس؛
  3. اتصال و Ping محدودشده PostgreSQL؛
  4. اجرای Migrationهای Embedded و Pending؛
  5. ساخت Dependencyهای Feature و Router؛
  6. بازکردن Listener پس از آماده‌شدن Dependencyهای اجباری.

شکست هر مرحله پیش از Listener باعث Fail-fast می‌شود. Shutdown با Signal، Timeout محدود و بستن HTTP Server و Pool انجام می‌شود.

Environmentها

مقدار APP_ENV Dotenv OTP Log Adapter کاربرد
development مجاز مجاز توسعه محلی و محیط Development
test مجاز مجاز Test خودکار
staging ممنوع ممنوع محیط نزدیک Production
production ممنوع ممنوع Production

.env فقط مقدارهای تعریف‌نشده Process را تکمیل می‌کند و Environment موجود را Override نمی‌کند.

Configuration اصلی

  • HTTP_ADDRESS، HTTP_REQUEST_TIMEOUT و HTTP_MAX_REQUEST_BYTES؛
  • DATABASE_URL برای توسعه Native یا اجزای جداگانه Database برای Container؛
  • DATABASE_MIN_CONNS، DATABASE_MAX_CONNS و Timeoutهای اتصال و Health؛
  • DATABASE_PASSWORD_FILE و OTP_HMAC_PEPPER_FILE برای Secret فایل‌محور؛
  • SHUTDOWN_TIMEOUT، APP_ENV و LOG_LEVEL.

قواعد Secret

  • Secret در Repository، Command Argument، Image Layer، Log، Metric، Trace یا Response قرار نمی‌گیرد.
  • مقدار Environment مستقیم Secret فقط در Development و Test و در صورت تصریح Config مجاز است.
  • فایل Secret حداقل Permission لازم و UID/GID سازگار با Process غیر Root دارد.
  • خطای خواندن Secret فقط نام Configuration و علت امن را گزارش می‌کند، نه مقدار آن را.

توسعه Native

Backend با Role اختصاصی tripylon به PostgreSQL روی 127.0.0.1:5432 متصل می‌شود. استفاده API از Superuser ممنوع است. Quick Start اجرایی در backend/README.md و تنظیمات نمونه در backend/.env.example نگهداری می‌شوند.

آزمون لازم

  • Config الزامی، مقدار نامعتبر و Environment پشتیبانی‌نشده؛
  • اولویت Process Environment نسبت به Dotenv؛
  • منع Adapter ناامن در Staging و Production؛
  • Startup Failure در قطع Database یا شکست Migration؛
  • Shutdown در بازه Timeout تعیین‌شده.