ngrok ინტეგრაცია

ngrok არის პოპულარული გვირაბის სერვისი, რომელიც უსაფრთხო შესვლას ქმნის თქვენს ლოკალურ PRX ინსტანციაზე. ეს არის ყველაზე სწრაფი გზა webhook-ებისა და გარე ინტეგრაციების დასაწყებად -- ერთი ბრძანება გაძლევთ საჯარო HTTPS URL-ს, რომელიც თქვენს ლოკალურ აგენტზე მიუთითებს.

მიმოხილვა

ngrok საუკეთესოდ შეეფერება:

• დეველოპმენტს და ტესტირებას -- საჯარო URL-ის მიღება წამებში ანგარიშის გარეშე
• Webhook პროტოტიპირებას -- Telegram, Discord, GitHub ან Slack ინტეგრაციების სწრაფი ტესტირება
• დემოებს და პრეზენტაციებს -- დროებითი საჯარო URL-ის გაზიარება აგენტის საჩვენებლად
• გარემოებს, სადაც Cloudflare ან Tailscale ხელმისაწვდომი არ არის

პროდაქშენ განთავსებისთვის, განიხილეთ Cloudflare გვირაბი ან Tailscale Funnel, რომლებიც უკეთეს საიმედოობას, მორგებულ დომენებსა და ნულოვანი ნდობის წვდომის კონტროლებს გვთავაზობს.

წინაპირობები

1. ngrok CLI დაყენებული PRX-ის გამშვებ მანქანაზე
2. ngrok ანგარიში auth ტოკენით (უფასო დონე საკმარისია)

ngrok-ის დაყენება

# Debian / Ubuntu (snap-ით)
sudo snap install ngrok

# macOS
brew install ngrok

# ბინარის ჩამოტვირთვა (ყველა პლატფორმა)
# https://ngrok.com/download

# ავთენტიფიკაცია (ერთჯერადი დაყენება)
ngrok config add-authtoken <YOUR_AUTH_TOKEN>

თქვენი auth ტოკენი მიიღეთ ngrok-ის დაშბორდიდან.

კონფიგურაცია

ბაზისური დაყენება

[tunnel]
backend = "ngrok"
local_addr = "127.0.0.1:8080"

[tunnel.ngrok]
# Auth ტოკენი. ასევე შეიძლება მითითდეს NGROK_AUTHTOKEN გარემოს ცვლადით.
# გამოტოვებისას, ngrok ტოკენს თავისი ლოკალური კონფიგურაციიდან იყენებს.
authtoken = ""

# რეგიონი გვირაბის ენდფოინთისთვის.
# ვარიანტები: "us", "eu", "ap", "au", "sa", "jp", "in"
region = "us"

მორგებული დომენი (ფასიანი გეგმები)

ngrok-ის ფასიანი გეგმები მხარს უჭერს მუდმივ მორგებულ დომენებს:

[tunnel]
backend = "ngrok"
local_addr = "127.0.0.1:8080"

[tunnel.ngrok]
authtoken = "${NGROK_AUTHTOKEN}"

# მორგებული დომენი (მოითხოვს ngrok-ის ფასიან გეგმას)
domain = "agent.example.com"

რეზერვირებული დომენი

უფასო დონეზე სტაბილური URL-ებისთვის, ngrok გვთავაზობს რეზერვირებულ დომენებს:

[tunnel.ngrok]
authtoken = "${NGROK_AUTHTOKEN}"

# ngrok-ის მიერ მინიჭებული რეზერვირებული დომენი (მაგ., "example-agent.ngrok-free.app")
domain = "example-agent.ngrok-free.app"

კონფიგურაციის მითითება

პარამეტრი	ტიპი	ნაგულისხმევი	აღწერა
authtoken	string	--	ngrok ავთენტიფიკაციის ტოკენი
region	string	"us"	გვირაბის რეგიონი: "us", "eu", "ap", "au", "sa", "jp", "in"
domain	string	--	მორგებული ან რეზერვირებული დომენი (ფასიანი ფუნქცია)
subdomain	string	--	ფიქსირებული ქვედომენი ngrok-free.app-ზე
ngrok_path	string	"ngrok"	ngrok ბინარის ბილიკი
inspect	boolean	true	ngrok-ის შემოწმების დაშბორდის ჩართვა (localhost:4040)
log_level	string	"info"	ngrok ლოგის დონე: "debug", "info", "warn", "error"
metadata	string	--	თვითნებური მეტამონაცემების სტრიქონი, მიმაგრებული გვირაბის სესიაზე
basic_auth	string	--	HTTP Basic Auth user:password ფორმატში
ip_restrictions	list	[]	ნებადართული CIDR დიაპაზონების სია (მაგ., ["203.0.113.0/24"])
circuit_breaker	float	--	შეცდომების სიჩქარის ზღურბლი (0.0-1.0) circuit breaker-ის გასააქტიურებლად
compression	boolean	false	პასუხის კომპრესიის ჩართვა

როგორ მართავს PRX ngrok-ს

გვირაბის დაწყებისას, PRX ngrok-ს შვილ პროცესად უშვებს:

ngrok http 127.0.0.1:8080 \
  --authtoken=<token> \
  --region=us \
  --log=stdout \
  --log-format=json

შემდეგ PRX ngrok-ის ლოკალურ API-ს (http://127.0.0.1:4040/api/tunnels) იკითხავს მინიჭებული საჯარო URL-ის მისაღებად. ეს URL ინახება და გამოიყენება webhook რეგისტრაციისა და არხის კონფიგურაციისთვის.

უფასო დონის შეზღუდვები

ngrok-ის უფასო დონეს რამდენიმე შეზღუდვა აქვს:

შეზღუდვა	უფასო დონე	გავლენა PRX-ზე
ერთდროული გვირაბები	1	მხოლოდ ერთი PRX ინსტანცია ngrok ანგარიშზე
კავშირები წუთში	40	შეიძლება შეზღუდოს მაღალი ტრაფიკის webhook-ებს
მორგებული დომენები	ხელმიუწვდომელი	URL ყოველ გადატვირთვაზე იცვლება
IP შეზღუდვები	ხელმიუწვდომელი	წყარო IP-ების შეზღუდვა შეუძლებელია
გამტარუნარიანობა	შეზღუდული	დიდი ფაილების გადაცემა შეიძლება შეზღუდულ იქნას
შუამავალი გვერდი	ჩანს პირველ ვიზიტზე	შეიძლება ხელი შეუშალოს ზოგიერთ webhook პროვაიდერს

უსაფრთხოების გათვალისწინებები

• Auth ტოკენის დაცვა -- ngrok auth ტოკენი ანიჭებს გვირაბის შექმნის წვდომას თქვენს ანგარიშზე. შეინახეთ PRX-ის საიდუმლოებების მენეჯერში ან გადაეცით NGROK_AUTHTOKEN გარემოს ცვლადით.
• უფასო დონის URL-ები საჯაროა -- ნებისმიერს URL-ით შეუძლია თქვენს აგენტთან მიღწევა. გამოიყენეთ basic_auth ან ip_restrictions (ფასიანი) წვდომის შესაზღუდად.
• TLS-ის შეწყვეტა -- ngrok წყვეტს TLS-ს მის ზღვარზე. ტრაფიკი ngrok-სა და ლოკალურ PRX-ს შორის ngrok-ის ინფრასტრუქტურაზე გადის.

პრობლემების მოგვარება

სიმპტომი	მიზეზი	გადაწყვეტა
"authentication failed"	არასწორი ან აკლია auth ტოკენი	გაუშვით ngrok config add-authtoken <token>
URL ვერ ამოიცნო	ngrok API არ პასუხობს :4040-ზე	შეამოწმეთ, რომ 4040 პორტს სხვა პროცესი არ იყენებს
"tunnel session limit"	უფასო დონე 1 გვირაბს იძლევა	შეაჩერეთ სხვა ngrok სესიები ან განაახლეთ
Webhook-ები 502 აბრუნებს	PRX გეითვეი არ ისმენს	შეამოწმეთ local_addr-ის შესაბამისობა გეითვეისთან

დაკავშირებული გვერდები

• გვირაბის მიმოხილვა
• Cloudflare გვირაბი
• Tailscale Funnel
• უსაფრთხოების მიმოხილვა