لوکال می لوکال می مستندات جامع فنی توسعه دهندگان
کنسول توسعه دهندگان ورود

مستندات جامع فنی و راهنمای توسعه دهندگان لوکال می

راهنمای جامع اتصال و استفاده از سرویس های پایگاه داده ابری، احراز هویت توکن محور، توابع لبه و تله متری در لوکال می.

معرفی و معماری پلتفرم لوکال می

پلتفرم لوکال می یک زیرساخت جامع ابری بومی است که با هدف ارتقای چشمگیر سرعت توسعه اپلیکیشن های موبایل و وب پیاده سازی شده است. این سامانه توسعه دهندگان را از مدیریت سرورها، کانفیگ پایگاه داده، و زیرساخت های پیچیده کاملاً بی نیاز می سازد.

اصول کلیدی معماری لوکال می

  • ایزولاسیون کامل داده ها: هر پروژه دارای فضای کاملاً مجزا در پایگاه داده ابری است. داده های پروژه های مختلف تحت هیچ شرایطی با یکدیگر تداخل نداشته و از بالاترین سطح امنیت و پرفورمنس برخوردارند.
  • کلیدهای تفکیک شده به ازای هر سرویس: برخلاف سیستم های قدیمی که از یک کلید عمومی سراسری استفاده می کردند، لوکال می برای هر سرویس یک کلید مستقل با ساختار lm_[service]_[project]_[id] صادر می کند. در صورت افشای کلید یک سرویس، سایر سرویس ها ایمن می مانند.
  • ناوبری مدرن کلیکی سایدبار: سایدبار کنسول به صورت یکپارچه و دومرحله ای طراحی شده است. کلیک بر روی منوی سطح یک بدون تغییر صفحه، منوی سطح دو را به همراه دکمه بازگشت (در بالا برای دسکتاپ و در پایین برای موبایل) نمایش می دهد تا تجربه کاربری کامپکت و ارگونومیکی بدون هاورهای تصادفی فراهم گردد.
  • مینی پروفایل نوار بالا و نمایش موجودی لحظه ای: نوار بالای کنسول اطلاعات حساب و موجودی زنده کیف پول را همواره در دسترس قرار داده و با کلیک، پاپ اور پروفایل، نشان نقش کاربری و پنجره های شارژ شتاب را در اختیار قرار می دهد.
  • راه اندازی تمیز بدون دیتای دمو: سامانه هنگام اجرا کاملا تمیز شروع به کار می کند و هیچ پروژه، جدول یا رکورد نمایشی و فیک را از پیش تولید نمی کند.
  • مدل مصرف Pay-As-You-Go: منابع سیستم به صورت کاملاً پویا و شفاف با دقت میلی ثانیه ای سنجیده می شوند.

چرخه کار توسعه دهنده

  1. عضویت و ورود با شماره همراه در سامانه لوکال می.
  2. ایجاد یک پروژه جدید در کنسول توسعه دهندگان (هر توسعه دهنده در ابتدا با ۰ پروژه شروع می کند).
  3. ورود به صفحه اختصاصی هر سرویس در منوی کناری، تنظیم پارامترها و فعال سازی آن سرویس.
  4. کپی کردن کلید دسترسی اختصاصی همان سرویس و ارسال درخواست از اپلیکیشن کلاینت.

احراز هویت و ساختار کلیدهای دسترسی API

تمامی درخواست های ارسالی از سمت کلاینت ها (موبایل و وب) باید احراز هویت شوند. هدرهای استاندارد زیر برای برقراری ارتباط با پلتفرم الزامی هستند:

نام هدر مقدار الزامی توضیحات
x-api-key lm_[service]_[proj]_[id] کلید اختصاصی سرویسی که قصد فراخوانی آن را دارید.
Authorization Bearer <JWT_TOKEN> توکن احراز هویت کاربر نهایی اپلیکیشن (برای دسترسی های کاربرمحور).
Content-Type application/json قالب ارسال داده ها در متدهای POST و PUT.

قالب نام گذاری کلیدهای اختصاصی سرویس های ۴گانه

فرمت کلیدهای APISPECIFICATION
// ۱. پایگاه داده رابطه ای
lm_database_proj_xxxxxxxx_xxxxxxxxxxxx

// ۲. احراز هویت جامع کاربران
lm_auth_proj_xxxxxxxx_xxxxxxxxxxxx

// ۳. توابع سرورلس لبه شبکه
lm_functions_proj_xxxxxxxx_xxxxxxxxxxxx

// ۴. تله متری و پایش پروژه
lm_telemetry_proj_xxxxxxxx_xxxxxxxxxxxx

ورود به پنل کاربری، رمز عبور و دسترسی اختصاصی تک پروژه

کنسول لوکال می (/panel و /auth) سه متد احراز هویت مستقل را متناسب با نیازهای توسعه دهندگان، تیم ها و کارفرما ارائه می کند:

۱. ثبت نام خودکار توسعه دهنده (Self-Service Register)

ایجاد حساب توسعه دهنده به صورت آنی با ایمیل و رمز عبور امن Argon2id و صدور توکن نشست:

POST /_baas/v1/auth/register
JSON PayloadREQUEST
{
  "email": "developer@example.com",
  "fullName": "سهراب تهرانی",
  "password": "SecurePassword123!"
}

۲. ورود با نام کاربری و کلمه عبور اصلی

دسترسی جامع و نامحدود به تمامی پروژه های تحت مالکیت کاربر در پنل لوکال می. شما می توانید با استفاده از نام کاربری، ایمیل، یا شماره تلفن همراه به همراه کلمه عبور وارد شوید.

POST /_baas/v1/auth/login
JSON PayloadREQUEST
{
  "username": "sina", // یا ایمیل یا شماره موبایل
  "password": "developer123456"
}

۳. ورود اختصاصی تک پروژه با رمز مجزا

در مواقعی که می خواهید دسترسی پنل یک پروژه خاص را در اختیار فریلنسر، همکار یا کارفرما قرار دهید بدون اینکه به سایر پروژه ها، کیف پول یا اطلاعات کلی حساب کاربری شما دسترسی داشته باشد، می توانید در تب «تنظیمات پروژه» یک رمز عبور اختصاصی برای پروژه تعیین کنید.

کاربر با داشتن Project Slug و رمز پروژه، مستقیماً وارد محیط ایزوله همان پروژه می شود:

POST /_baas/v1/auth/project-login
JSON PayloadREQUEST
{
  "projectSlug": "my-online-shop",
  "password": "ProjectSecretPass2026!"
}

مدیریت رمز پروژه از طریق وب سرویس REST

تنظیم یا تغییر رمز عبور اختصاصی پروژه:

POST /_baas/v1/projects/{projectId}/password
JSON PayloadREQUEST
{
  "password": "NewProjectSecretPass"
}

حذف رمز عبور اختصاصی پروژه (غیرفعال سازی ورود مستقیم):

DELETE /_baas/v1/projects/{projectId}/password

دستورات CLI و راه اندازی سریع پروژه

جهت سهولت توسعه و استقرار محلی و پروداکشن، اسکریپت های زیر در package.json تعبیه شده اند:

ترمینال / CLIBASH
# راه اندازی سرور در محیط توسعه (Dev Mode)
pnpm dev

# ساخت نسخه پایانی و اجرای پروداکشن (Release Mode)
pnpm start

# اجرای کلیه تست های واحد و یکپارچگی
pnpm test

# اجرای ساخت کامل مونوریپو
pnpm build

زیرساخت شبکه، دیتاسنتر و اتصال شاپرک

تمام سرورهای لوکال می در مراکز داده داخلی مستقر در منطقه تهران (ir-central-tehran) میزبانی می شوند.

  • IP خروجی ثابت و حاکمیتی (Egress NAT): 2.180.12.94 — تمامی ارتباطات با وب سرویس های شاپرک، سرشماره های پیامکی، و سازمان های دولتی از این آدرس IP ثابت انجام می پذیرد.
  • پایداری شبکه ملی اطلاعات: در شرایط اختلال اینترنت بین الملل، دسترسی کاربران داخلی به پلتفرم و اپلیکیشن شما به صورت ۱۰۰٪ پایدار و بدون وقفه برقرار می ماند.

۱. سرویس پایگاه داده رابطه ای (Database API)

این سرویس جداول دیتابیس پروژه را مستقیماً به صورت RESTful در اختیار کلاینت قرار می دهد. نیازی به نوشتن کنترلرهای اضافه در بک اند نیست.

اندپوینت های عملیاتی پایگاه داده

GET /_baas/v1/{projectId}/db/{tableName}

دریافت رکوردهای جدول به همراه قابلیت فیلترگذاری و صفحه بندی (مسیر هم ارز: /_baas/v1/{projectId}/rest/{tableName}).

POST /_baas/v1/{projectId}/db/{tableName}

درج یک رکورد جدید در جدول مشخص شده.

POST /_baas/v1/{projectId}/db/tables

ایجاد جدول جدید در اسکیمای پایگاه داده با ارسال {"name": "orders"}.

PUT /_baas/v1/{projectId}/db/{tableName}/{id}

ویرایش و به روزرسانی مقادیر یک رکورد بر اساس شناسه.

DELETE /_baas/v1/{projectId}/db/{tableName}/{id}

حذف قطعی یک سطر از جدول.

فیلترها و عملگرهای جستجو

عملگرتوضیحنمونه استفاده
eqبرابری دقیق?status=eq.active
gt / gteبزرگتر / بزرگتر مساوی?price=gte.500000
lt / lteکوچکتر / کوچکتر مساوی?stock=lt.10
likeجستجوی متنی فازی?title=like.*گوشی*
limit / offsetصفحه بندی نتایج?limit=20&offset=40
orderمرتب سازی صعودی یا نزولی?order=created_at.desc

۲. سرویس احراز هویت جامع کاربران

سامانه یکپارچه احراز هویت با پشتیبانی همزمان از پیامک یکبارمصرف (SMS OTP)، نام کاربری و رمز عبور (Credentials)، و ورود با شبکه های اجتماعی (OAuth 2.0 گوگل و گیت هاب).

ساختار ثبت نام و ورود با ایمیل و رمز عبور (Argon2id + Ed25519)

۱. ثبت نام کاربر جدید:

POST /_baas/v1/{projectId}/auth/signup
JSON PayloadREQUEST
{
  "email": "user@example.com",
  "password": "StrongPassword123!",
  "name": "سارا محمدی"
}

۲. ورود و دریافت جلسه احراز هویت:

POST /_baas/v1/{projectId}/auth/login
JSON PayloadREQUEST
{
  "email": "user@example.com",
  "password": "StrongPassword123!"
}

ج) تبادل توکن احراز هویت ثالث (OAuth 2.0)

POST /_baas/v1/{projectId}/auth/oauth/{provider}

مقدار provider می تواند google یا github باشد. بدنه درخواست:

JSON PayloadREQUEST
{
  "code": "4/0AfgeXvu...",
  "redirectUri": "https://myapp.com/auth/callback"
}

د) مدیریت کاربران پروژه

دریافت لیست کاربران احراز هویت شده پروژه: GET /_baas/v1/{projectId}/auth/users

ثبت مستقیم کاربر از سمت کلاینت دارای دسترسی: POST /_baas/v1/{projectId}/auth/users

۳. توابع سرورلس لبه شبکه (COMPUTE_EDGE)

اجرای کدهای جاوااسکریپت در موتور ایزوله و پرسرعت Jint 4.1.0. ایده آل برای منطق تجاری سمت سرور، اعتبارسنجی داده ها، محاسبات مالی و وب هوک های ثالث بدون نیاز به مدیریت سرور اختصاصی.

ویژگی های امنیتی و زیرساختی

  • تزریق خودکار متغیرهای محیطی: کلیدهای API و اسرار پروژه به صورت ایمن در شیء process.env تزریق می شوند.
  • اتصال مستقیم درون فرآیندی به دیتابیس: دسترسی به داده ها از طریق شیء localme.from(tableName) با مجوز service_role بدون سربار شبکه.
  • خروجی ایگرس NAT حاکمیتی: درخواست های خروجی با آدرس IP استاتیک اختصاصی و فیلترینگ دامنه های داخلی (RFC 1918) انجام می پذیرد.

استقرار و مدیریت توابع

دریافت فهرست توابع مستقر: GET /_baas/v1/{projectId}/functions

استقرار یا به روزرسانی کد تابع: POST /_baas/v1/{projectId}/functions با بدنه {"name": "محاسبه تخفیف", "slug": "discount-calc", "script": "..."}

فراخوانی و اجرای تابع

POST /_baas/v1/{projectId}/functions/{funcSlug}/invoke

مسیر هم ارز: /_baas/v1/{projectId}/functions/{funcSlug}/exec. نمونه درخواست و پاسخ:

JSON PayloadREQUEST
{
  "cartId": "cart_9910",
  "coupon": "NOROOZ1403"
}
JSON ResultRESPONSE
{
  "status": "success",
  "output": {
    "discountPercent": 15,
    "maxDiscountIrr": 500000
  },
  "latencyMs": 6
}

۴. تله متری و پایش پروژه (OBSERVABILITY)

سیستم پایش بلادرنگ لاگ ها و شاخص های سلامت در لوکال می بر بستر پارتیشن های زمانی PostgreSQL پیاده سازی شده است و امکان رصد زنده کلیه تعاملات سیستم، کوئری های دیتابیس و اجرای توابع لبه را فراهم می سازد.

دریافت و فیلتر لاگ های زنده

GET /_baas/v1/{projectId}/logs?service={service}&level={level}&limit=100

پارامترهای فیلتر:

  • service: سرویس هدف (database, auth, functions, gateway).
  • level: سطح پیام (INFO, WARN, ERROR).
  • limit: تعداد رکوردهای خروجی (۱ الی ۲۰۰، پیش فرض ۵۰).

شناسایی خودکار کوئری های کند (Slow Queries)

کلیه کوئری های دیتابیس که اجرای آنها بیش از ۲۰۰ میلی ثانیه زمان ببرد، به طور خودکار با متادیتا و زمان تاخیر در بافر تله متری ثبت شده و در کنسول توسعه دهندگان قابل تحلیل هستند.

استودیوی مستقیم SQL

امکان اجرای مستقیم دستورات SQL بر روی اسکیمای ایزوله پروژه:

POST /_baas/v1/{projectId}/sql/execute

نمونه کدهای جامع و کتابخانه ها

برای سهولت ادغام با اپلیکیشن های موبایل و وب، کدهای نمونه کامل در ۴ محیط cURL، جاوااسکریپت/تایپ اسکریپت، پایتون و دارت/فلاتر ارائه گردیده است.

# ۱. دریافت رکوردهای جدول دیتابیس
curl -X GET "https://api.localme.ir/_baas/v1/proj_fdbb724/db/products?limit=10" \
  -H "x-api-key: lm_database_proj_fdbb724_a1b2c3"

# ۲. ثبت نام کاربر جدید با ایمیل و کلمه عبور
curl -X POST "https://api.localme.ir/_baas/v1/proj_fdbb724/auth/signup" \
  -H "x-api-key: lm_auth_proj_fdbb724_d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecretPassword123!", "fullName": "کاربر نمونه"}'

# ۳. ورود کاربر با ایمیل و کلمه عبور
curl -X POST "https://api.localme.ir/_baas/v1/proj_fdbb724/auth/login" \
  -H "x-api-key: lm_auth_proj_fdbb724_d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "SecretPassword123!"}'

# ۴. اجرای تابع سرورلس لبه
curl -X POST "https://api.localme.ir/_baas/v1/proj_fdbb724/functions/fare-calculator/invoke" \
  -H "x-api-key: lm_functions_proj_fdbb724_g7h8i9" \
  -H "Content-Type: application/json" \
  -d '{"distance_km": 12}'
// کلاینت جاوا اسکریپت / تایپ اسکریپت لوکال می
class LocalMeClient {
  constructor(projectId, keys) {
    this.projectId = projectId;
    this.keys = keys;
    this.baseUrl = 'https://api.localme.ir/_baas/v1';
  }

  // ۱. کوئری پایگاه داده
  async getRecords(table, params = {}) {
    const qs = new URLSearchParams(params).toString();
    const res = await fetch(`${this.baseUrl}/${this.projectId}/db/${table}${qs ? '?' + qs : ''}`, {
      headers: { 'x-api-key': this.keys.database }
    });
    return await res.json();
  }

  // ۲. ثبت نام کاربر با ایمیل و کلمه عبور
  async signup(email, password, fullName = '') {
    const res = await fetch(`${this.baseUrl}/${this.projectId}/auth/signup`, {
      method: 'POST',
      headers: { 'x-api-key': this.keys.auth, 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password, fullName })
    });
    return await res.json();
  }

  // ۳. ورود با ایمیل و پسورد
  async login(email, password) {
    const res = await fetch(`${this.baseUrl}/${this.projectId}/auth/login`, {
      method: 'POST',
      headers: { 'x-api-key': this.keys.auth, 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    });
    return await res.json();
  }

  // ۴. اجرای تابع سرورلس لبه
  async invokeFunction(slug, context = {}) {
    const res = await fetch(`${this.baseUrl}/${this.projectId}/functions/${slug}/invoke`, {
      method: 'POST',
      headers: { 'x-api-key': this.keys.functions, 'Content-Type': 'application/json' },
      body: JSON.stringify(context)
    });
    return await res.json();
  }
}
import requests

class LocalMeClient:
    def __init__(self, project_id: str, keys: dict):
        self.project_id = project_id
        self.keys = keys
        self.base_url = "https://api.localme.ir/_baas/v1"

    def get_records(self, table: str, params: dict = None) -> list:
        url = f"{self.base_url}/{self.project_id}/db/{table}"
        headers = {"x-api-key": self.keys.get("database")}
        r = requests.get(url, headers=headers, params=params)
        r.raise_for_status()
        return r.json()

    def signup(self, email: str, password: str, full_name: str = "") -> dict:
        url = f"{self.base_url}/{self.project_id}/auth/signup"
        headers = {"x-api-key": self.keys.get("auth"), "Content-Type": "application/json"}
        r = requests.post(url, headers=headers, json={"email": email, "password": password, "fullName": full_name})
        r.raise_for_status()
        return r.json()

    def invoke_function(self, slug: str, context: dict) -> dict:
        url = f"{self.base_url}/{self.project_id}/functions/{slug}/invoke"
        headers = {"x-api-key": self.keys.get("functions"), "Content-Type": "application/json"}
        r = requests.post(url, headers=headers, json=context)
        r.raise_for_status()
        return r.json()
import 'dart:convert';
import 'package:http/http.dart' as http;

class LocalMeService {
  final String projectId;
  final Map<String, String> keys;
  final String baseUrl = 'https://api.localme.ir/_baas/v1';

  LocalMeService({required this.projectId, required this.keys});

  // ۱. دریافت رکوردهای جدول دیتابیس
  Future<List<dynamic>> getTableRecords(String table) async {
    final uri = Uri.parse('$baseUrl/$projectId/db/$table');
    final res = await http.get(uri, headers: {'x-api-key': keys['database'] ?? ''});
    if (res.statusCode == 200) {
      return jsonDecode(utf8.decode(res.bodyBytes)) as List<dynamic>;
    }
    throw Exception('خطا در دریافت اطلاعات: ${res.statusCode}');
  }

  // ۲. ثبت نام کاربر جدید با ایمیل و کلمه عبور
  Future<Map<String, dynamic>> signup(String email, String password, {String fullName = ''}) async {
    final uri = Uri.parse('$baseUrl/$projectId/auth/signup');
    final res = await http.post(
      uri,
      headers: {'x-api-key': keys['auth'] ?? '', 'Content-Type': 'application/json'},
      body: jsonEncode({'email': email, 'password': password, 'fullName': fullName}),
    );
    return jsonDecode(utf8.decode(res.bodyBytes)) as Map<String, dynamic>;
  }

  // ۳. فراخوانی تابع لبه
  Future<Map<String, dynamic>> invokeFunction(String slug, Map<String, dynamic> context) async {
    final uri = Uri.parse('$baseUrl/$projectId/functions/$slug/invoke');
    final res = await http.post(
      uri,
      headers: {'x-api-key': keys['functions'] ?? '', 'Content-Type': 'application/json'},
      body: jsonEncode(context),
    );
    return jsonDecode(utf8.decode(res.bodyBytes)) as Map<String, dynamic>;
  }
}

کدهای وضعیت HTTP و راهنمای رفع اشکال

کد وضعیتعنوان خطاعلت و راهکار رفع
200 OKعملیات موفقدرخواست با موفقیت پردازش شد.
201 Createdایجاد موفق رکوردرکورد در جدول یا کاربر در سیستم با موفقیت ثبت شد.
400 Bad Requestقالب داده نامعتبربدنه JSON ارسالی معتبر نیست یا فیلدهای اجباری ارسال نشده اند.
401 Unauthorizedکلید نامعتبرکلید هدر x-api-key ارسال نشده یا نامعتبر است.
402 Payment Requiredاتمام موجودی کیف پولاعتبار کیف پول پروژه تمام شده است. از پنل توسعه کیف پول را شارژ نمایید.
403 Forbiddenعدم دسترسی به منبعسرویس مورد نظر برای پروژه غیرفعال شده یا سطح دسترسی ناکافی است.
404 Not Foundمنبع یافت نشدپروژه، جدول، باکت یا تابع مورد نظر در سامانه وجود ندارد.
429 Too Many Requestsمحدودیت نرخ فراخوانیتعداد درخواست ها در دقیقه از سقف تعیین شده فراتر رفته است.
500 Server Errorخطای سرورخطای پردازش داخلی در زمان اجرای اسکریپت یا کوئری دیتابیس.