پرش به مطلب اصلی

متغیرهای محیطی

🖼
تصویر: مدیریت متغیرهای محیطی در داشبوردplaceholder — تصویر را اینجا جایگزین کنید

متغیرهای محیطی (Environment Variables) روش استاندارد تزریق تنظیمات، رمزها، و پارامترهای اتصال به اپلیکیشن شما هستند. ابرکلیک مقادیر را رمزگذاری‌شده ذخیره می‌کند و در زمان اجرا به کانتینر تزریق می‌کند.

متغیرهای سطح پروژه

ابرکلیک متغیرهای محیطی را در دو سطح پشتیبانی می‌کند: سطح پروژه (به همه اپلیکیشن‌های پروژه تزریق می‌شود) و سطح اپ (فقط به یک اپلیکیشن). اگر متغیری در هر دو سطح تعریف شود، مقدار سطح اپ اولویت دارد.

تنظیم از طریق داشبورد​

در داشبورد، وارد صفحه اپلیکیشن شوید و تب متغیرهای محیطی را باز کنید. در ویرایشگر متغیرها می‌توانید:

  • متغیر جدید اضافه کنید (کلید + مقدار)
  • مقدار موجود را ویرایش یا حذف کنید
  • متغیرهای حساس را به‌عنوان Secret علامت‌گذاری کنید (مقدار در لاگ و داشبورد پنهان می‌شود)
  • چند متغیر را به‌صورت دسته‌ای در قالب KEY=VALUE وارد کنید

پس از ذخیره، تغییرات در استقرار بعدی اعمال می‌شوند. برای اعمال فوری، اپ را ری‌استارت کنید.

تنظیم از طریق CLI​

abrclick run env

# تنظیم یک یا چند متغیر
abrclick run env set DATABASE_HOST=db.example.com
abrclick run env set KEY1=value1 KEY2=value2

# حذف یک متغیر
abrclick run env unset MY_SECRET_KEY
نکته

برای اپلیکیشن‌هایی که هنوز لینک نشده‌اند، پرچم --app را اضافه کنید:

abrclick run env set API_KEY=xyz --app <appId>

زمان تزریق: Runtime در مقابل Build-time​

به‌صورت پیش‌فرض تمام متغیرها در زمان اجرا (runtime) تزریق می‌شوند — یعنی فرآیند build به آن‌ها دسترسی ندارد.

اگر نیاز دارید متغیری در حین build در دسترس باشد (مثلاً برای NEXT_PUBLIC_* در Next.js یا ابزارهای مشابه)، نام متغیر را با پیشوند BUILD_ شروع کنید:

# این متغیر هم در build و هم در runtime موجود است
BUILD_NEXT_PUBLIC_API_URL=https://api.abrclick.ir
هشدار

مقادیر BUILD_* در لایه‌های image ممکن است قابل مشاهده باشند. هرگز رمزها یا توکن‌های حساس را با این پیشوند تعریف نکنید.

متغیرهای خودکار پلتفرم​

ابرکلیک برخی متغیرها را به‌صورت خودکار تزریق می‌کند. این متغیرها را override نکنید:

متغیرمقدارتوضیح
PORTعدد پورت (مثلاً 8080)پورتی که اپ باید روی آن listen کند
APP_URLhttps://<slug>.apps.abrclick.cloudآدرس عمومی اپلیکیشن

اپلیکیشن شما باید روی پورت PORT$ گوش دهد:

// Node.js
const port = process.env.PORT || 3000;
app.listen(port);
# Python / Flask
import os
port = int(os.environ.get("PORT", 8000))
app.run(host="0.0.0.0", port=port)
// Go
port := os.Getenv("PORT")
if port == "" {
    port = "8080"
}
http.ListenAndServe(":"+port, nil)

متغیرهای خودکار اتصال به پایگاه داده​

وقتی یک پایگاه داده را به اپلیکیشن لینک می‌کنید (از داشبورد یا CLI)، ابرکلیک به‌صورت خودکار متغیرهای اتصال را تزریق می‌کند:

PostgreSQL​

DATABASE_URL=postgresql://user:pass@host:5432/dbname
DATABASE_HOST=...
DATABASE_PORT=5432
DATABASE_NAME=...
DATABASE_USER=...
DATABASE_PASSWORD=...

Redis​

REDIS_URL=redis://:password@host:6379
REDIS_HOST=...
REDIS_PORT=6379
REDIS_PASSWORD=...

MongoDB​

MONGO_URL=mongodb://user:pass@host:27017/dbname
MONGO_HOST=...
MONGO_PORT=27017
MONGO_NAME=...
MONGO_USER=...
MONGO_PASSWORD=...
اطلاع

مقادیر اتصال به صورت service discovery داخلی هستند و در شبکه خصوصی کلاستر کار می‌کنند. این اتصال‌ها کم‌تاخیر و ایمن هستند و نیازی به رمزنگاری اضافه ندارند.

برای لینک کردن پایگاه داده به اپ:

# لیست پایگاه‌های داده پروژه
abrclick db list

# اطلاعات پایگاه داده
abrclick db info <dbId>

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

متغیرهای Secret (رمز)​

برای متغیرهایی که نباید در لاگ‌ها یا داشبورد نمایش داده شوند (مانند API Key، رمز JWT، کلید رمزنگاری)، گزینه Secret را فعال کنید.

ویژگی‌های متغیر Secret:

  • مقدار در داشبورد پس از ذخیره قابل مشاهده نیست
  • در خروجی لاگ‌ها با *** جایگزین می‌شود
  • هنگام بررسی لاگ از طریق CLI نیز پنهان می‌ماند
  • مقدار همچنان به کانتینر تزریق می‌شود و اپ به آن دسترسی کامل دارد
# نمونه: تنظیم کلید JWT به‌عنوان Secret از داشبورد
# (گزینه Secret را هنگام افزودن متغیر فعال کنید)
JWT_SECRET=your-super-secret-key-here

فایل .env — چه کاری انجام دهیم؟​

هرگز فایل .env را commit نکنید

فایل‌های .env حاوی رمزها و اطلاعات حساس هستند. commit کردن آن‌ها در git مخاطره امنیتی جدی ایجاد می‌کند.

توصیه‌های ابرکلیک:

  1. فایل .env را به .gitignore اضافه کنید:
# .gitignore
.env
.env.local
.env.*.local
  1. یک فایل .env.example با کلیدها (بدون مقادیر واقعی) نگه‌دارید:
# .env.example — این فایل را commit کنید
DATABASE_URL=
JWT_SECRET=
SMTP_HOST=
THIRD_PARTY_API_KEY=
  1. مقادیر واقعی را از طریق داشبورد یا CLI در پلتفرم تنظیم کنید.

برای توسعه محلی، همچنان می‌توانید از .env استفاده کنید — اما هرگز آن را push نکنید.

اولویت‌بندی متغیرها​

اگر یک متغیر هم در پلتفرم تعریف شده باشد و هم در Dockerfile یا کد اپ، ترتیب اولویت به این شکل است:

  1. متغیرهای پلتفرم (بالاترین اولویت) — از طریق داشبورد یا CLI تنظیم شده
  2. متغیرهای خودکار پلتفرم (PORT، APP_URL، اتصال DB)
  3. متغیرهای ENV در Dockerfile (پایین‌ترین اولویت)

نمونه کامل: اپ Node.js با PostgreSQL​

// config.js
module.exports = {
  port: process.env.PORT || 3000,
  appUrl: process.env.APP_URL,
  db: {
    url: process.env.DATABASE_URL,
  },
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: process.env.JWT_EXPIRES_IN || '7d',
  },
  smtp: {
    host: process.env.SMTP_HOST,
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
};

متغیرهای مربوطه در پلتفرم:

کلیدنوعتوضیح
DATABASE_URLخودکارپس از لینک DB تزریق می‌شود
JWT_SECRETSecretاز داشبورد با گزینه Secret
JWT_EXPIRES_INمعمولیمثلاً 24h
SMTP_HOSTمعمولیآدرس سرور ایمیل
SMTP_USERمعمولینام کاربری SMTP
SMTP_PASSSecretرمز SMTP

گام بعدی​