مستندات جامع فنی و راهنمای توسعه دهندگان لوکال می
راهنمای جامع اتصال و استفاده از سرویس های پایگاه داده ابری، احراز هویت توکن محور، توابع لبه و تله متری در لوکال می.
معرفی و معماری پلتفرم لوکال می
پلتفرم لوکال می یک زیرساخت جامع ابری بومی است که با هدف ارتقای چشمگیر سرعت توسعه اپلیکیشن های موبایل و وب پیاده سازی شده است. این سامانه توسعه دهندگان را از مدیریت سرورها، کانفیگ پایگاه داده، و زیرساخت های پیچیده کاملاً بی نیاز می سازد.
اصول کلیدی معماری لوکال می
- ایزولاسیون کامل داده ها: هر پروژه دارای فضای کاملاً مجزا در پایگاه داده ابری است. داده های پروژه های مختلف تحت هیچ شرایطی با یکدیگر تداخل نداشته و از بالاترین سطح امنیت و پرفورمنس برخوردارند.
- کلیدهای تفکیک شده به ازای هر سرویس: برخلاف سیستم های قدیمی که از یک کلید عمومی سراسری استفاده می کردند، لوکال می برای هر سرویس یک کلید مستقل با ساختار
lm_[service]_[project]_[id]صادر می کند. در صورت افشای کلید یک سرویس، سایر سرویس ها ایمن می مانند. - ناوبری مدرن کلیکی سایدبار: سایدبار کنسول به صورت یکپارچه و دومرحله ای طراحی شده است. کلیک بر روی منوی سطح یک بدون تغییر صفحه، منوی سطح دو را به همراه دکمه بازگشت (در بالا برای دسکتاپ و در پایین برای موبایل) نمایش می دهد تا تجربه کاربری کامپکت و ارگونومیکی بدون هاورهای تصادفی فراهم گردد.
- مینی پروفایل نوار بالا و نمایش موجودی لحظه ای: نوار بالای کنسول اطلاعات حساب و موجودی زنده کیف پول را همواره در دسترس قرار داده و با کلیک، پاپ اور پروفایل، نشان نقش کاربری و پنجره های شارژ شتاب را در اختیار قرار می دهد.
- راه اندازی تمیز بدون دیتای دمو: سامانه هنگام اجرا کاملا تمیز شروع به کار می کند و هیچ پروژه، جدول یا رکورد نمایشی و فیک را از پیش تولید نمی کند.
- مدل مصرف Pay-As-You-Go: منابع سیستم به صورت کاملاً پویا و شفاف با دقت میلی ثانیه ای سنجیده می شوند.
چرخه کار توسعه دهنده
- عضویت و ورود با شماره همراه در سامانه لوکال می.
- ایجاد یک پروژه جدید در کنسول توسعه دهندگان (هر توسعه دهنده در ابتدا با ۰ پروژه شروع می کند).
- ورود به صفحه اختصاصی هر سرویس در منوی کناری، تنظیم پارامترها و فعال سازی آن سرویس.
- کپی کردن کلید دسترسی اختصاصی همان سرویس و ارسال درخواست از اپلیکیشن کلاینت.
احراز هویت و ساختار کلیدهای دسترسی API
تمامی درخواست های ارسالی از سمت کلاینت ها (موبایل و وب) باید احراز هویت شوند. هدرهای استاندارد زیر برای برقراری ارتباط با پلتفرم الزامی هستند:
| نام هدر | مقدار الزامی | توضیحات |
|---|---|---|
x-api-key |
lm_[service]_[proj]_[id] |
کلید اختصاصی سرویسی که قصد فراخوانی آن را دارید. |
Authorization |
Bearer <JWT_TOKEN> |
توکن احراز هویت کاربر نهایی اپلیکیشن (برای دسترسی های کاربرمحور). |
Content-Type |
application/json |
قالب ارسال داده ها در متدهای POST و PUT. |
قالب نام گذاری کلیدهای اختصاصی سرویس های ۴گانه
// ۱. پایگاه داده رابطه ای
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 و صدور توکن نشست:
/_baas/v1/auth/register
{
"email": "developer@example.com",
"fullName": "سهراب تهرانی",
"password": "SecurePassword123!"
}
۲. ورود با نام کاربری و کلمه عبور اصلی
دسترسی جامع و نامحدود به تمامی پروژه های تحت مالکیت کاربر در پنل لوکال می. شما می توانید با استفاده از نام کاربری، ایمیل، یا شماره تلفن همراه به همراه کلمه عبور وارد شوید.
/_baas/v1/auth/login
{
"username": "sina", // یا ایمیل یا شماره موبایل
"password": "developer123456"
}
۳. ورود اختصاصی تک پروژه با رمز مجزا
در مواقعی که می خواهید دسترسی پنل یک پروژه خاص را در اختیار فریلنسر، همکار یا کارفرما قرار دهید بدون اینکه به سایر پروژه ها، کیف پول یا اطلاعات کلی حساب کاربری شما دسترسی داشته باشد، می توانید در تب «تنظیمات پروژه» یک رمز عبور اختصاصی برای پروژه تعیین کنید.
کاربر با داشتن Project Slug و رمز پروژه، مستقیماً وارد محیط ایزوله همان پروژه می شود:
/_baas/v1/auth/project-login
{
"projectSlug": "my-online-shop",
"password": "ProjectSecretPass2026!"
}
مدیریت رمز پروژه از طریق وب سرویس REST
تنظیم یا تغییر رمز عبور اختصاصی پروژه:
/_baas/v1/projects/{projectId}/password
{
"password": "NewProjectSecretPass"
}
حذف رمز عبور اختصاصی پروژه (غیرفعال سازی ورود مستقیم):
/_baas/v1/projects/{projectId}/password
دستورات CLI و راه اندازی سریع پروژه
جهت سهولت توسعه و استقرار محلی و پروداکشن، اسکریپت های زیر در package.json تعبیه شده اند:
# راه اندازی سرور در محیط توسعه (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 در اختیار کلاینت قرار می دهد. نیازی به نوشتن کنترلرهای اضافه در بک اند نیست.
اندپوینت های عملیاتی پایگاه داده
/_baas/v1/{projectId}/db/{tableName}
دریافت رکوردهای جدول به همراه قابلیت فیلترگذاری و صفحه بندی (مسیر هم ارز: /_baas/v1/{projectId}/rest/{tableName}).
/_baas/v1/{projectId}/db/{tableName}
درج یک رکورد جدید در جدول مشخص شده.
/_baas/v1/{projectId}/db/tables
ایجاد جدول جدید در اسکیمای پایگاه داده با ارسال {"name": "orders"}.
/_baas/v1/{projectId}/db/{tableName}/{id}
ویرایش و به روزرسانی مقادیر یک رکورد بر اساس شناسه.
/_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)
۱. ثبت نام کاربر جدید:
/_baas/v1/{projectId}/auth/signup
{
"email": "user@example.com",
"password": "StrongPassword123!",
"name": "سارا محمدی"
}
۲. ورود و دریافت جلسه احراز هویت:
/_baas/v1/{projectId}/auth/login
{
"email": "user@example.com",
"password": "StrongPassword123!"
}
ج) تبادل توکن احراز هویت ثالث (OAuth 2.0)
/_baas/v1/{projectId}/auth/oauth/{provider}
مقدار provider می تواند google یا github باشد. بدنه درخواست:
{
"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": "..."}
فراخوانی و اجرای تابع
/_baas/v1/{projectId}/functions/{funcSlug}/invoke
مسیر هم ارز: /_baas/v1/{projectId}/functions/{funcSlug}/exec. نمونه درخواست و پاسخ:
{
"cartId": "cart_9910",
"coupon": "NOROOZ1403"
}
{
"status": "success",
"output": {
"discountPercent": 15,
"maxDiscountIrr": 500000
},
"latencyMs": 6
}
۴. تله متری و پایش پروژه (OBSERVABILITY)
سیستم پایش بلادرنگ لاگ ها و شاخص های سلامت در لوکال می بر بستر پارتیشن های زمانی PostgreSQL پیاده سازی شده است و امکان رصد زنده کلیه تعاملات سیستم، کوئری های دیتابیس و اجرای توابع لبه را فراهم می سازد.
دریافت و فیلتر لاگ های زنده
/_baas/v1/{projectId}/logs?service={service}&level={level}&limit=100
پارامترهای فیلتر:
service: سرویس هدف (database,auth,functions,gateway).level: سطح پیام (INFO,WARN,ERROR).limit: تعداد رکوردهای خروجی (۱ الی ۲۰۰، پیش فرض ۵۰).
شناسایی خودکار کوئری های کند (Slow Queries)
کلیه کوئری های دیتابیس که اجرای آنها بیش از ۲۰۰ میلی ثانیه زمان ببرد، به طور خودکار با متادیتا و زمان تاخیر در بافر تله متری ثبت شده و در کنسول توسعه دهندگان قابل تحلیل هستند.
استودیوی مستقیم SQL
امکان اجرای مستقیم دستورات SQL بر روی اسکیمای ایزوله پروژه:
/_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 | خطای سرور | خطای پردازش داخلی در زمان اجرای اسکریپت یا کوئری دیتابیس. |