გვირაბი და NAT-ის გავლა

PRX აგენტებს ხშირად სჭირდებათ შემომავალი კავშირების მიღება -- GitHub-ის webhook callback-ები, Telegram-ის განახლებები, Slack-ის მოვლენები ან კვანძებს შორის კომუნიკაცია. NAT-ის ან firewall-ის უკან გაშვებისას, გვირაბის ქვესისტემა უზრუნველყოფს ავტომატურ შესვლას გვირაბის პროვაიდერთან გამავალი კავშირის დამყარებითა და საჯარო URL-ის თქვენს ლოკალურ PRX ინსტანციაზე მიბმით.

რატომ არის მნიშვნელოვანი გვირაბი

PRX-ის ბევრი ფუნქცია საჯაროდ მისაწვდომ ენდფოინთს მოითხოვს:

• Webhook არხები -- Telegram, Discord, Slack და GitHub ყველა მოვლენებს თქვენ მიერ მოწოდებულ URL-ზე აგზავნის. საჯარო ენდფოინთის გარეშე, ეს არხები ვერ მიაწვდის შეტყობინებებს თქვენს აგენტს.
• OAuth2 callback-ები -- პროვაიდერის ავთენტიფიკაციის ნაკადები ბრაუზერს ლოკალურ URL-ზე გადამისამართებს. გვირაბები ამას მუშაობის საშუალებას აძლევს, როდესაც PRX კერძო ქსელში მუშაობს.
• კვანძიდან კვანძზე კომუნიკაცია -- განაწილებული PRX განთავსებები კვანძების ერთმანეთთან მისაწვდომობას მოითხოვს. გვირაბები კვანძებს სხვადასხვა ქსელს შორის აკავშირებს.
• MCP სერვერის ჰოსტინგი -- როდესაც PRX MCP სერვერის როლს ასრულებს გარე კლიენტებისთვის, გვირაბი საჯარო ენდფოინთს უზრუნველყოფს.

მხარდაჭერილი ბექენდები

PRX-ს გააჩნია ოთხი გვირაბის ბექენდი და no-op სარეზერვო:

ბექენდი	პროვაიდერი	უფასო დონე	მორგებული დომენი	ავთენტიფიკაცია საჭირო	ნულოვანი ნდობა
Cloudflare გვირაბი	Cloudflare	დიახ	დიახ (ზონით)	დიახ (cloudflared)	დიახ
Tailscale Funnel	Tailscale	დიახ (პირადი)	MagicDNS-ით	დიახ (Tailscale ანგარიში)	დიახ
ngrok	ngrok	დიახ (შეზღუდული)	დიახ (ფასიანი)	დიახ (auth ტოკენი)	არა
მორგებული ბრძანება	ნებისმიერი	დამოკიდებულია	დამოკიდებულია	დამოკიდებულია	დამოკიდებულია
None	--	--	--	--	--

არქიტექტურა

გვირაბის ქვესისტემა Tunnel ტრეიტზეა აშენებული:

#[async_trait]
pub trait Tunnel: Send + Sync {
    /// გვირაბის გაშვება და საჯარო URL-ის დაბრუნება.
    async fn start(&mut self) -> Result<String>;

    /// გვირაბის შეჩერება და რესურსების გასუფთავება.
    async fn stop(&mut self) -> Result<()>;

    /// გვირაბის ჯანმრთელობისა და საჯარო URL-ის მისაწვდომობის შემოწმება.
    async fn health_check(&self) -> Result<bool>;
}

თითოეული ბექენდი ამ ტრეიტს ახორციელებს. TunnelProcess სტრუქტურა მართავს ძირითად შვილ პროცესს (მაგ., cloudflared, tailscale, ngrok) -- გაშვებას, stdout/stderr-ის გადაღებას, გრაციოზულ გამორთვასა და წარუმატებლობისას ავტომატურ გადატვირთვას.

┌─────────────────────────────────────────────┐
│                PRX გეითვეი                   │
│            (localhost:8080)                   │
└──────────────────┬──────────────────────────┘
                   │ (ლოკალური)
┌──────────────────▼──────────────────────────┐
│              TunnelProcess                   │
│  ┌──────────────────────────────────┐       │
│  │  cloudflared / tailscale / ngrok │       │
│  │  (შვილი პროცესი)                │       │
│  └──────────────┬───────────────────┘       │
└─────────────────┼───────────────────────────┘
                  │ (გამავალი TLS)
┌─────────────────▼───────────────────────────┐
│      გვირაბის პროვაიდერის ზღვრული ქსელი    │
│    https://your-agent.example.com            │
└──────────────────────────────────────────────┘

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

გვირაბის კონფიგურაცია config.toml-ში:

[tunnel]
# ბექენდის არჩევა: "cloudflare" | "tailscale" | "ngrok" | "custom" | "none"
backend = "cloudflare"

# ლოკალური მისამართი, რომელზეც გვირაბი ტრაფიკს გადაამისამართებს.
# უნდა ემთხვეოდეს თქვენი გეითვეის მოსმენის მისამართს.
local_addr = "127.0.0.1:8080"

# ჯანმრთელობის შემოწმების ინტერვალი წამებში. გვირაბი გადაიტვირთება, თუ
# ჯანმრთელობის შემოწმება თანმიმდევრულად `max_failures`-ჯერ ვერ ხერხდება.
health_check_interval_secs = 30
max_failures = 3

# ავტოგამოვლენა: თუ backend = "auto", PRX ეძებს ხელმისაწვდომ
# გვირაბის ბინარებს თანმიმდევრობით: cloudflared, tailscale, ngrok.
# ვერ პოვნისას გადადის "none"-ზე გაფრთხილებით.

ბექენდისთვის სპეციფიკური კონფიგურაცია

თითოეულ ბექენდს აქვს საკუთარი კონფიგურაციის სექცია. იხილეთ ინდივიდუალური ბექენდის გვერდები დეტალებისთვის:

• Cloudflare გვირაბი -- [tunnel.cloudflare]
• Tailscale Funnel -- [tunnel.tailscale]
• ngrok -- [tunnel.ngrok]

მორგებული ბრძანების ბექენდი

ნატიურად მხარდაუჭერელი გვირაბის პროვაიდერებისთვის გამოიყენეთ custom ბექენდი:

[tunnel]
backend = "custom"

[tunnel.custom]
# გასაშვები ბრძანება. უნდა მიიღოს ტრაფიკი local_addr-ზე და
# დაბეჭდოს საჯარო URL stdout-ში startup_timeout_secs-ის ფარგლებში.
command = "bore"
args = ["local", "8080", "--to", "bore.pub"]
startup_timeout_secs = 15

# არასავალდებულო: regex საჯარო URL-ის stdout-იდან ამოსაღებად.
# პირველი ჯგუფი გამოიყენება URL-ად.
url_pattern = "listening at (https?://[\\S]+)"

ავტოგამოვლენა

backend = "auto"-ისას PRX $PATH-ში ეძებს გვირაბის ბინარებს ამ თანმიმდევრობით:

1. cloudflared -- უპირატესი ნულოვანი ნდობის შესაძლებლობებისთვის
2. tailscale -- უპირატესი კერძო mesh ქსელისთვის
3. ngrok -- ფართოდ ხელმისაწვდომი, მარტივი გამართვა

ვერ პოვნისას გვირაბი ითიშება და PRX გაფრთხილებას ბეჭდავს. Webhook-ზე დამოკიდებული არხები არ იმუშავებს გვირაბის ან საჯარო IP-ის გარეშე.

TunnelProcess-ის სასიცოცხლო ციკლი

TunnelProcess სტრუქტურა მართავს შვილი პროცესის სასიცოცხლო ციკლს:

ფაზა	აღწერა
გაშვება	გვირაბის ბინარის გაშვება კონფიგურირებული არგუმენტებით
URL-ის ამოღება	stdout-ის პარსინგი საჯარო URL-ისთვის (startup_timeout_secs-ის ფარგლებში)
მონიტორინგი	პერიოდული ჯანმრთელობის შემოწმება HTTP GET-ით საჯარო URL-ზე
გადატვირთვა	თუ max_failures თანმიმდევრული ჯანმრთელობის შემოწმება ვერ ხერხდება, შეჩერება და გადატვირთვა
გამორთვა	SIGTERM-ის გაგზავნა, 5 წამის ლოდინი, შემდეგ SIGKILL თუ ჯერ კიდევ მუშაობს

გარემოს ცვლადები

გვირაბის კონფიგურაცია ასევე შეიძლება გარემოს ცვლადებით მითითდეს, რომლებიც config.toml-ზე უპირატესობას იღებს:

ცვლადი	აღწერა
PRX_TUNNEL_BACKEND	გვირაბის ბექენდის გადაფარვა
PRX_TUNNEL_LOCAL_ADDR	ლოკალური გადამისამართების მისამართის გადაფარვა
PRX_TUNNEL_URL	გვირაბის გაშვების გამოტოვება და ამ URL-ის გამოყენება
CLOUDFLARE_TUNNEL_TOKEN	Cloudflare გვირაბის ტოკენი
NGROK_AUTHTOKEN	ngrok ავთენტიფიკაციის ტოკენი

PRX_TUNNEL_URL-ის მითითება სასარგებლოა, როდესაც უკვე გაქვთ რევერს პროქსი ან დატვირთვის ბალანსერი, რომელიც PRX-ს საჯაროდ გამოაქვეყნებს. გვირაბის ქვესისტემა პროცესის მართვას გამოტოვებს და მოწოდებულ URL-ს პირდაპირ გამოიყენებს.

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

• TLS შეწყვეტა -- ყველა მხარდაჭერილი ბექენდი TLS-ს პროვაიდერის ზღვარზე წყვეტს. ტრაფიკი პროვაიდერსა და თქვენს ლოკალურ PRX ინსტანციას შორის დაშიფრულ გვირაბზე მოძრაობს.
• წვდომის კონტროლი -- Cloudflare და Tailscale მხარს უჭერს იდენტობაზე დაფუძნებულ წვდომის პოლიტიკებს. გამოიყენეთ ეს მგრძნობიარე აგენტის ენდფოინთების გამოქვეყნებისას.
• სანდოობის მონაცემების შენახვა -- გვირაბის ტოკენები და ავთენტიფიკაციის გასაღებები PRX-ის საიდუმლოებების მენეჯერში ინახება. არასოდეს ჩაატანოთ ვერსიის კონტროლში.
• პროცესის იზოლაცია -- TunnelProcess ცალკე შვილ პროცესად მუშაობს. ის არ იზიარებს მეხსიერებას PRX აგენტის გაშვების გარემოსთან.

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

სიმპტომი	მიზეზი	გადაწყვეტა
გვირაბი იწყება, მაგრამ webhook-ები ვერ ხერხდება	URL არხის კონფიგურაციას არ გადაეცა	შეამოწმეთ tunnel.public_url გამოიყენება არხის მიერ
გვირაბი განმეორებით გადაიტვირთება	ჯანმრთელობის შემოწმება არასწორ ენდფოინთს ხვდება	შეამოწმეთ local_addr ემთხვევა გეითვეის მოსმენის მისამართს
"binary not found" შეცდომა	გვირაბის CLI დაყენებული არ არის	დააყენეთ შესაბამისი ბინარი (cloudflared, tailscale, ngrok)
URL-ის ამოღებისას ტაიმაუტი	გვირაბის ბინარის გაშვებას ბევრი დრო სჭირდება	გაზარდეთ startup_timeout_secs

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

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