راهنمای gRPC
APIهای پرکارایی gRPC برای شبکهسازی مش، اتصال VPN و اطلاعات تهدید. Protocol Buffers، جریانسازی دوطرفه و تأخیر زیر یک میلیثانیه.
APIهای پرکارایی gRPC
سرویسهای RPC مبتنی بر Protocol Buffer برای شبکهسازی مش، مدیریت تونل VPN و اطلاعات تهدید. جریانسازی دوطرفه، نوعدهی قوی و سربار زیر یک میلیثانیه.
مرور کلی
APIهای gRPC سرویس OrbVPN برای ارتباط کمتأخیر و پرگذردهی میان سرویسها طراحی شدهاند. اینها پروتکل اصلی برای شبکهسازی مش (OrbMesh)، مدیریت تونل VPN و جریانسازی بیدرنگ اطلاعات تهدید هستند.
Protocol Buffers
پیامهای نوعدهیشدهٔ قوی و باینریسریالایز که ۵ تا ۱۰ برابر کوچکتر از JSON و بهطور چشمگیری برای تجزیه سریعترند. نحو Proto3 با سازگاری کامل رو به عقب.
جریانسازی دوطرفه
پشتیبانی کامل از هر چهار الگوی gRPC: یکطرفه (unary)، جریانسازی سمت سرور، جریانسازی سمت کلاینت و جریانسازی دوطرفه. عالی برای سنجههای بیدرنگ و فیدهای تهدید.
انتقال HTTP/2
ساختهشده بر پایهٔ HTTP/2 با جریانهای چندگانه (multiplexed)، فشردهسازی سرآیند و کنترل جریان. چندین RPC یک اتصال TCP واحد را به اشتراک میگذارند.
تولید کد
از روی فایلهای proto بهطور مستقیم، استابهای کلاینت نوعایمن را در Go، Python، JavaScript، Java، C++ و بیش از ۱۰ زبان دیگر تولید کنید.
برپاسازی اتصال
سه نقطه پایانی gRPC بخشهای مختلف پلتفرم OrbVPN را سرویسدهی میکنند.
| سرویس | آدرس | TLS | احراز هویت |
|---|---|---|---|
| OrbNET gRPC | grpc://api.orbai.world:50051 | TLS 1.3 | فراداده JWT |
| OrbMesh gRPC | برای هر سرور IP:50051 | mTLS | گواهی کلاینت |
| OrbGuard gRPC | grpc://guard.orbai.world:50051 | TLS 1.3 | فراداده کلید API |
احراز هویت
هر سرویس gRPC از یک سازوکار احراز هویت متفاوت استفاده میکند که بهصورت فرادادهٔ gRPC (معادل سرآیندهای HTTP) ارسال میشود.
OrbNET — فراداده JWT
توکن دسترسی JWT خود را بهعنوان کلید فرادادهٔ authorization پیوست کنید.
import "google.golang.org/grpc/metadata"
md := metadata.Pairs("authorization", "Bearer eyJhbGciOiJIUzI1NiIs...")
ctx := metadata.NewOutgoingContext(context.Background(), md)
resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "usr_abc123"})OrbGuard — فراداده کلید API
کلید API خود را بهعنوان کلید فرادادهٔ x-api-key پیوست کنید.
md := metadata.Pairs("x-api-key", "ogk_live_abc123...")
ctx := metadata.NewOutgoingContext(context.Background(), md)
resp, err := threatClient.CheckIndicator(ctx, &pb.CheckIndicatorRequest{
Indicator: "suspicious-domain.com",
Type: pb.IndicatorType_DOMAIN,
})OrbMesh — mTLS (احراز هویت متقابل TLS)
گرههای OrbMesh با استفاده از گواهیهای کلاینت صادرشده توسط CA سرویس OrbVPN احراز هویت میشوند.
import "google.golang.org/grpc/credentials"
creds, err := credentials.NewClientTLSFromFile("ca.pem", "")
// For mTLS, load both client cert and key
tlsCert, err := tls.LoadX509KeyPair("client.pem", "client-key.pem")
tlsConfig := &tls.Config{
Certificates: []tls.Certificate{tlsCert},
RootCAs: certPool,
}
conn, err := grpc.Dial(
"mesh-node-ip:50051",
grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
)تأمین گواهی
گواهیهای گرهِ OrbMesh بهطور خودکار در جریان ثبت گره تأمین میشوند. برای مشاهدهٔ فرایند کامل راهاندازی، به مرور کلی OrbMesh مراجعه کنید.
سرویسها
۱. OrbMeshService
صفحهٔ کنترل شبکهسازی مش. ثبت گره، پایش سلامت، توپولوژی و جمعآوری بیدرنگ سنجهها را در سراسر ناوگان سرورهای OrbVPN مدیریت میکند.
OrbMeshService
صفحهٔ کنترل شبکهسازی مش برای مدیریت ناوگان سرورهای OrbVPN، پایش سلامت و کنترل توپولوژی.
RegisterNodeHeartbeatStreamMetricsPushMetricsSyncTopologyGetNodeStatusListNodesDrainNodeRotateCertificatesDeregisterNode۲. VPNService
مدیریت چرخهٔ عمر تونل VPN. از پروتکلهای WireGuard، VLESS و OrbConnect همراه با جریانسازی بیدرنگ وضعیت پشتیبانی میکند.
VPNService
مدیریت چرخهٔ عمر تونل VPN برای پروتکلهای WireGuard، VLESS و OrbConnect.
ConnectWireGuardConnectVLESSConnectOrbConnectDisconnectGetStatusStreamStatus۳. ThreatIntelligenceService
شناسایی بیدرنگ تهدید، بررسی نشانگرها و تحلیل انبوه تهدید از OrbGuard Labs.
ThreatIntelligenceService
اطلاعات تهدید و تحلیل نشانگر از OrbGuard Labs. نشانگرها را بررسی کنید، تهدیدهای زنده را جریانسازی کنید و تحلیل انبوه انجام دهید.
CheckIndicatorStreamThreatsBatchCheckStreamIndicatorsLiveAnalysisانواع پیام کلیدی
RegisterNodeRequest
RegisterNodeRequest| # | فیلد | نوع | توضیحات |
|---|---|---|---|
| 1 | hostnamereq | string | نام میزبان کاملاً مقیدِ گره. |
| 2 | ip_addressreq | string | نشانی IP عمومی گره. |
| 3 | regionreq | string | کد منطقهٔ جغرافیایی (مثلاً us-east-1، eu-west-1). |
| 4 | repeated protocols | Protocol | فهرست پروتکلهای VPN پشتیبانیشده (WIREGUARD، VLESS، ORBCONNECT). |
| 5 | capacityreq | NodeCapacity | بیشینهٔ ظرفیت اتصال و محدودیتهای منابع برای گره. |
| 6 | labels | map<string, string> | برچسبهای کلید-مقدار دلخواه برای دستهبندی گره و قواعد مسیریابی. |
ConnectWireGuardRequest
ConnectWireGuardRequest| # | فیلد | نوع | توضیحات |
|---|---|---|---|
| 1 | user_idreq | string | شناسهٔ کاربرِ احراز هویتشده. |
| 2 | device_idreq | string | شناسهٔ یکتای دستگاه برای کلاینت در حال اتصال. |
| 3 | server_id | string | شناسهٔ سرور ترجیحی. اگر خالی باشد، صفحهٔ کنترل بهینهترین سرور را انتخاب میکند. |
| 4 | public_keyreq | bytes | کلید عمومی WireGuard دستگاه کلاینت (۳۲ بایت، Curve25519). |
| 5 | preshared_key | bytes | کلید ازپیشبهاشتراکگذاشتهٔ اختیاری WireGuard برای مقاومت پساکوانتومی (۳۲ بایت). |
| 6 | preferred_endpoint | string | منطقهٔ سرور یا کد شهر ترجیحی برای بهینهسازی جغرافیایی. |
| 7 | kill_switch | bool | فعالسازی قواعد kill switch در پاسخ سرور (مسدودکردن ترافیک در صورت افتادن تونل). |
CheckIndicatorRequest
CheckIndicatorRequest| # | فیلد | نوع | توضیحات |
|---|---|---|---|
| 1 | indicatorreq | string | مقدار نشانگری که باید بررسی شود (دامنه، نشانی IP، URL یا هشِ فایل). |
| 2 | typereq | IndicatorType | نوع نشانگر: DOMAIN، IP، URL، SHA256، MD5 یا SHA1. |
| 3 | include_context | bool | گنجاندن زمینهٔ غنیسازی (WHOIS، تاریخچهٔ DNS، نشانگرهای مرتبط) در پاسخ. |
| 4 | include_yara_matches | bool | اجرای قواعد منطبق YARA و گنجاندن نتایج (فقط برای نشانگرهای هشِ فایل کاربرد دارد). |
ThreatEvent
ThreatEvent| # | فیلد | نوع | توضیحات |
|---|---|---|---|
| 1 | idreq | string | شناسهٔ یکتای رویداد. |
| 2 | indicatorreq | string | نشانگر تهدید (دامنه، IP، URL یا هش). |
| 3 | indicator_typereq | IndicatorType | نوع نشانگر. |
| 4 | severityreq | Severity | شدت تهدید: INFO، LOW، MEDIUM، HIGH یا CRITICAL. |
| 5 | scorereq | int32 | امتیاز تهدید از ۰ (بیخطر) تا ۱۰۰ (بدافزارِ تأییدشده). |
| 6 | repeated categories | string | دستههای تهدید: malware، phishing، c2، spam، cryptominer و غیره. |
| 7 | first_seenreq | google.protobuf.Timestamp | زمانی که نشانگر برای نخستینبار توسط OrbGuard مشاهده شد. |
| 8 | last_seenreq | google.protobuf.Timestamp | زمانی که نشانگر برای آخرینبار مشاهده شد. |
نمونههای کد
Go — RPC یکطرفه
package main
import (
"context"
"fmt"
"log"
pb "github.com/orbvpn/proto/orbguard/v1"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
"google.golang.org/grpc/metadata"
)
func main() {
// Connect with TLS
creds, err := credentials.NewClientTLSFromFile("ca.pem", "guard.orbai.world")
if err != nil {
log.Fatal(err)
}
conn, err := grpc.Dial("guard.orbai.world:50051", grpc.WithTransportCredentials(creds))
if err != nil {
log.Fatal(err)
}
defer conn.Close()
client := pb.NewThreatIntelligenceServiceClient(conn)
// Attach API key
ctx := metadata.AppendToOutgoingContext(
context.Background(),
"x-api-key", "ogk_live_abc123...",
)
// Check a threat indicator
resp, err := client.CheckIndicator(ctx, &pb.CheckIndicatorRequest{
Indicator: "suspicious-domain.com",
Type: pb.IndicatorType_DOMAIN,
IncludeContext: true,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Indicator: %s\n", resp.Indicator)
fmt.Printf("Score: %d/100\n", resp.Score)
fmt.Printf("Severity: %s\n", resp.Severity)
fmt.Printf("Malicious: %v\n", resp.IsMalicious)
for _, cat := range resp.Categories {
fmt.Printf(" Category: %s\n", cat)
}
}Go — جریانسازی سمت سرور
// Stream real-time threat events
stream, err := client.StreamThreats(ctx, &pb.StreamThreatsRequest{
Severity: []pb.Severity{pb.Severity_HIGH, pb.Severity_CRITICAL},
Categories: []string{"malware", "phishing", "c2"},
})
if err != nil {
log.Fatal(err)
}
for {
event, err := stream.Recv()
if err != nil {
log.Println("Stream ended:", err)
break
}
fmt.Printf("[%s] %s -- %s (score: %d)\n",
event.Severity,
event.IndicatorType,
event.Indicator,
event.Score,
)
}Go — جریانسازی دوطرفه
// Bidirectional topology sync with OrbMesh
stream, err := meshClient.SyncTopology(ctx)
if err != nil {
log.Fatal(err)
}
// Send local topology updates in a goroutine
go func() {
updates := getLocalTopologyUpdates() // your implementation
for _, update := range updates {
if err := stream.Send(&update); err != nil {
log.Println("Send error:", err)
return
}
}
stream.CloseSend()
}()
// Receive cluster-wide topology updates
for {
update, err := stream.Recv()
if err != nil {
log.Println("Stream ended:", err)
break
}
fmt.Printf("Topology update: node=%s action=%s\n",
update.NodeId, update.Action)
applyTopologyUpdate(update) // your implementation
}Python — RPC یکطرفه
import grpc
from orbguard.v1 import threat_service_pb2 as pb
from orbguard.v1 import threat_service_pb2_grpc as pb_grpc
# Connect with TLS
credentials = grpc.ssl_channel_credentials(
root_certificates=open("ca.pem", "rb").read()
)
channel = grpc.secure_channel("guard.orbai.world:50051", credentials)
client = pb_grpc.ThreatIntelligenceServiceStub(channel)
# Attach API key metadata
metadata = [("x-api-key", "ogk_live_abc123...")]
# Check a threat indicator
response = client.CheckIndicator(
pb.CheckIndicatorRequest(
indicator="suspicious-domain.com",
type=pb.DOMAIN,
include_context=True,
),
metadata=metadata,
)
print(f"Indicator: {response.indicator}")
print(f"Score: {response.score}/100")
print(f"Severity: {pb.Severity.Name(response.severity)}")
print(f"Malicious: {response.is_malicious}")Python — جریانسازی سمت سرور
# Stream real-time threats
stream = client.StreamThreats(
pb.StreamThreatsRequest(
severity=[pb.HIGH, pb.CRITICAL],
categories=["malware", "phishing"],
),
metadata=metadata,
)
for event in stream:
print(f"[{pb.Severity.Name(event.severity)}] "
f"{pb.IndicatorType.Name(event.indicator_type)}: "
f"{event.indicator} (score: {event.score})")Python — جریانسازی دوطرفهٔ ناهمگام
import asyncio
import grpc.aio
async def live_analysis():
channel = grpc.aio.secure_channel(
"guard.orbai.world:50051",
grpc.ssl_channel_credentials(open("ca.pem", "rb").read()),
)
client = pb_grpc.ThreatIntelligenceServiceStub(channel)
metadata = [("x-api-key", "ogk_live_abc123...")]
# Bidirectional stream
async def indicator_generator():
indicators = [
("suspicious-domain.com", pb.DOMAIN),
("192.168.1.100", pb.IP),
("https://phishing-site.com/login", pb.URL),
]
for indicator, itype in indicators:
yield pb.AnalysisRequest(indicator=indicator, type=itype)
await asyncio.sleep(0.1) # Simulate real-time submissions
stream = client.LiveAnalysis(indicator_generator(), metadata=metadata)
async for result in stream:
print(f"Result: {result.indicator} -> score={result.score}, "
f"malicious={result.is_malicious}")
asyncio.run(live_analysis())الگوهای جریانسازی
gRPC از چهار الگوی ارتباطی پشتیبانی میکند. سرویس OrbVPN از هر چهار الگو در سرویسهای خود استفاده میکند.
یکطرفه (Unary)
درخواست-پاسخ کلاسیک. کلاینت یک درخواست میفرستد و سرور یک پاسخ بازمیگرداند. برای CheckIndicator، RegisterNode و ConnectWireGuard استفاده میشود.
جریانسازی سمت سرور
کلاینت یک درخواست میفرستد و سرور یک جریان از پاسخها بازمیگرداند. برای StreamMetrics، StreamThreats و StreamStatus استفاده میشود.
جریانسازی سمت کلاینت
کلاینت یک جریان از درخواستها میفرستد و سرور یک پاسخ بازمیگرداند. برای PushMetrics و StreamIndicators استفاده میشود.
جریانسازی دوطرفه
هم کلاینت و هم سرور بهطور مستقل جریانهایی از پیامها میفرستند. برای SyncTopology و LiveAnalysis استفاده میشود.
مقایسهٔ الگوها
| الگو | کاربرد | نمونههای OrbVPN |
|---|---|---|
| Unary | یک درخواست، یک پاسخ | CheckIndicator، RegisterNode، ConnectWireGuard |
| Server Stream | اشتراک در دادهٔ پیوسته | StreamMetrics، StreamThreats، StreamStatus |
| Client Stream | ارسال دادهٔ دستهای | PushMetrics، StreamIndicators |
| Bidirectional | همگامسازی بیدرنگ، تحلیل تعاملی | SyncTopology، LiveAnalysis |
مرجع فایلهای Proto
فایلهای proto را دانلود کنید تا استابهای کلاینت را در هر زبان پشتیبانیشده تولید کنید.
| فایل Proto | بسته | توضیح |
|---|---|---|
orbmesh/v1/mesh_service.proto | orbvpn.mesh.v1 | صفحهٔ کنترل OrbMesh — مدیریت گره، توپولوژی، سنجهها |
orbnet/v1/vpn_service.proto | orbvpn.vpn.v1 | مدیریت تونل VPN — WireGuard، VLESS، OrbConnect |
orbguard/v1/threat_service.proto | orbvpn.guard.v1 | اطلاعات تهدید — نشانگرها، تحلیل، جریانسازی |
orbvpn/v1/common.proto | orbvpn.v1 | انواع مشترک — Severity، IndicatorType، Protocol، NodeCapacity |
دسترسی به فایلهای Proto
فایلهای proto در مخزن GitHub سرویس OrbVPN در دسترساند. مخزن را کلون کنید و با protoc یا buf کد کلاینت را به زبان خودتان تولید کنید.
تولید کد کلاینت
# Using protoc (Go example)
protoc --go_out=. --go-grpc_out=. \
-I proto/ \
proto/orbguard/v1/threat_service.proto
# Using buf (recommended)
buf generate proto/
# Using grpc_tools (Python)
python -m grpc_tools.protoc \
-I proto/ \
--python_out=. \
--grpc_python_out=. \
proto/orbguard/v1/threat_service.protoابزارهای توسعه
grpcurl
ابزار خط فرمان برای تعامل با سرورهای gRPC. مانند cURL اما برای gRPC. از reflection، ورودی JSON و جریانسازی پشتیبانی میکند.
Evans
کلاینت جامع و گویای gRPC با رابط REPL. برای کاوش تعاملی سرویسها همراه با تکمیل خودکار با Tab عالی است.
BloomRPC
کلاینت گرافیکی برای سرویسهای gRPC. فایلهای proto را وارد کنید، درخواست بفرستید و پاسخها را با رابطی شبیه Postman بررسی کنید.
نمونههای grpcurl
# List available services (requires server reflection)
grpcurl -cacert ca.pem guard.orbai.world:50051 list
# Describe a service
grpcurl -cacert ca.pem guard.orbai.world:50051 \
describe orbvpn.guard.v1.ThreatIntelligenceService
# Check a threat indicator
grpcurl -cacert ca.pem \
-H "x-api-key: ogk_live_abc123..." \
-d '{"indicator": "suspicious-domain.com", "type": "DOMAIN"}' \
guard.orbai.world:50051 \
orbvpn.guard.v1.ThreatIntelligenceService/CheckIndicator
# Stream threats (server streaming)
grpcurl -cacert ca.pem \
-H "x-api-key: ogk_live_abc123..." \
-d '{"severity": ["HIGH", "CRITICAL"]}' \
guard.orbai.world:50051 \
orbvpn.guard.v1.ThreatIntelligenceService/StreamThreatsمدیریت خطا
gRPC از کدهای وضعیت استاندارد استفاده میکند. سرویسهای OrbVPN جزئیات خطای بیشتری را در فرادادهٔ وضعیت بازمیگردانند.
| کد gRPC | معنا | علت رایج |
|---|---|---|
OK (0) | موفقیت | — |
INVALID_ARGUMENT (3) | درخواست نامعتبر | فیلد مفقود یا نامعتبر در پیام درخواست |
NOT_FOUND (5) | منبع یافت نشد | گره، کاربر یا نشانگر یافت نشد |
PERMISSION_DENIED (7) | شکست احراز هویت | JWT/کلید API نامعتبر یا منقضیشده |
RESOURCE_EXHAUSTED (8) | محدودشده با نرخ | درخواستهای بیش از حد — با عقبنشینی دوباره تلاش کنید |
UNAVAILABLE (14) | سرویس از دسترس خارج | خطای گذرا — با عقبنشینی دوباره تلاش کنید |
UNAUTHENTICATED (16) | بدون اعتبارنامه | فرادادهٔ authorization مفقود |
import (
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
resp, err := client.CheckIndicator(ctx, req)
if err != nil {
st, ok := status.FromError(err)
if ok {
switch st.Code() {
case codes.Unauthenticated:
// Refresh token and retry
case codes.ResourceExhausted:
// Rate limited -- backoff and retry
case codes.Unavailable:
// Transient failure -- retry with backoff
default:
log.Fatalf("gRPC error: %s -- %s", st.Code(), st.Message())
}
}
}مهلت / وقفهٔ زمانی
همیشه برای زمینهٔ gRPC خود یک مهلت تعیین کنید. بدون مهلت، یک RPC گیرکرده میتواند منابع را بهطور نامحدود اشغال کند. مهلت ۳۰ ثانیهای یک پیشفرض خوب برای RPCهای یکطرفه است. برای RPCهای جریانسازی، از مهلت طولانیتری استفاده کنید یا وقفههای زمانی در سطح برنامه پیادهسازی کنید.
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
resp, err := client.CheckIndicator(ctx, req)نکات کارایی
اتصالها را دوباره استفاده کنید
اتصالهای gRPC روی یک اتصال TCP واحد چندگانه (multiplex) میشوند. برای هر مقصد یک کانال بسازید و آن را در همهٔ RPCها دوباره استفاده کنید. برای هر درخواست یک اتصال جدید نسازید.
برای عملیات انبوه از جریانسازی استفاده کنید
برای عملیات دستهای، RPCهای جریانسازی سمت کلاینت یا دوطرفه را به فراخوانیهای مکرر یکطرفه ترجیح دهید. StreamIndicators ده برابر سریعتر از فراخوانی CheckIndicator در یک حلقه است.
مهلتها را تعیین کنید
همیشه مهلتهای زمینه را تعیین کنید. یک پیشفرض منطقی، ۳۰ ثانیه برای RPCهای یکطرفه و ۵ دقیقه برای RPCهای جریانسازی است. بدون مهلت، RPCهای گیرکرده منابع را نشت میدهند.
Keepalive را فعال کنید
پارامترهای keepalive مربوط به gRPC را پیکربندی کنید تا از بستهشدن اتصالهای بیکار توسط پراکسیهای میانی جلوگیری شود. زمان keepalive را روی ۳۰ ثانیه و وقفهٔ زمانی را روی ۱۰ ثانیه تنظیم کنید.
با gRPC بسازید
از APIهای پرکارایی gRPC سرویس OrbVPN برای شبکهسازی مش، مدیریت تونل VPN و اطلاعات تهدید بیدرنگ بهره ببرید. نوعدهیشدهٔ قوی، فوقالعاده سریع و آمادهٔ تولید.