استقرار PasarGuard Node روی Railway

این پروژه یک wrapper مستقل برای build و استقرار PasarGuard Node روی Railway است. سورس upstream داخل این repository کپی نشده و هنگام build از یک commit مشخص دریافت می‌شود.

معماری استقرار

کانتینر فقط یک listener از نوع TLS اجرا می‌کند. Railway متغیر PORT را تزریق می‌کند (در بسیاری از استقرارها 8080) و اسکریپت start.sh همان مقدار را به SERVICE_PORT منتقل می‌کند.

برای اتصال پنل PasarGuard که خارج از Railway است باید از TCP Proxy استفاده کنید. TCP Proxy دو پورت دارد:

• پورت داخلی: پورتی که در متغیر PORT یا لاگ سرویس دیده می‌شود.
• پورت عمومی: پورتی که Railway همراه hostname عمومی تولید می‌کند.

آدرس خصوصی railway-pg-node.railway.internal فقط از داخل شبکه Railway قابل دسترسی است.

استقرار سریع

1. در Railway یک Project جدید بسازید و Deploy from GitHub repo را انتخاب کنید.

2. این repository را انتخاب کنید.

3. متغیر ضروری زیر را اضافه کنید:

   API_KEY=123e4567-e89b-12d3-a456-426614174000
   

   همین UUID باید در پنل PasarGuard نیز وارد شود.

4. یک Railway Volume بسازید و به سرویس متصل کنید:

   • روی فضای خالی Project Canvas راست‌کلیک کنید و Add Volume را بزنید؛ یا Ctrl+K را فشار دهید و Volume را جست‌وجو کنید.

   • سرویس railway-pg-node را انتخاب کنید.

   • Mount Path را دقیقاً این مقدار بگذارید:

     /var/lib/pg-node
     

   اگر گزینهٔ Volume را نمی‌بینید، نقش حساب شما باید Member یا Admin باشد؛ نقش Deployer اجازهٔ ساخت Volume ندارد.

5. سرویس را Deploy کنید و لاگ‌ها را ببینید. نمونهٔ لاگ موفق:

   gRPC Server listening on 0.0.0.0:8080
   

6. در بخش Networking → TCP Proxy برای پورت داخلی سرویس (در مثال بالا 8080) یک Proxy بسازید.

7. hostname و port عمومی تولیدشده را کپی کنید.

8. متغیر زیر را با hostname عمومی خود تنظیم کنید:

   TLS_SERVER_NAME=altaria.proxy.rlwy.net
   

9. دوباره Deploy کنید تا certificate با hostname صحیح ساخته شود.

در Dockerfile عمداً دستور VOLUME وجود ندارد؛ Volume باید از تنظیمات خود Railway ساخته و به سرویس متصل شود.

ساخت Volume با Railway CLI

railway volume add --mount-path /var/lib/pg-node

بعد Volume ساخته‌شده را به همین سرویس متصل و تغییرات را Deploy کنید.

اضافه‌کردن Node به پنل PasarGuard

در پنل به مسیر زیر بروید:

Nodes → Add Node

مقادیر را این‌گونه وارد کنید:

فیلد پنل	مقدار
Name	مثلاً Railway Node
Host / Address	hostname عمومی TCP Proxy
Port	پورت عمومی TCP Proxy، نه پورت داخلی
Protocol	gRPC
API Key	همان مقدار API_KEY در Railway
Certificate / CA	محتوای کامل فایل ssl_cert.pem
API Port	اگر اجباری بود، همان پورت عمومی TCP Proxy

از آدرس railway-pg-node.railway.internal استفاده نکنید؛ مگر اینکه پنل نیز داخل همان شبکه Railway اجرا شود.

متغیرهای محیطی

متغیر	مقدار پیش‌فرض	ضروری	توضیح
API_KEY	—	بله	UUID مشترک با پنل PasarGuard
SERVICE_PROTOCOL	grpc	خیر	فقط grpc یا rest
PORT	مقدار Railway	خیر	پورت تزریق‌شده توسط Railway
SERVICE_PORT	62050	خیر	مقدار جایگزین وقتی PORT وجود ندارد
NODE_HOST	0.0.0.0	خیر	آدرس listen
SSL_CERT_FILE	/var/lib/pg-node/certs/ssl_cert.pem	خیر	مسیر certificate
SSL_KEY_FILE	/var/lib/pg-node/certs/ssl_key.pem	خیر	مسیر private key
GENERATED_CONFIG_PATH	/var/lib/pg-node/generated	خیر	مسیر کانفیگ‌های تولیدشده
TLS_SERVER_NAME	pasarguard-node	خیر	hostname درج‌شده در SAN certificate
PASARGUARD_NODE_REF	commit ثابت	خیر	نسخه upstream هنگام Docker build

برای اجرای محلی از .env.example استفاده کنید.

چرخهٔ certificate

اگر هر دو فایل زیر وجود نداشته باشند، کانتینر آن‌ها را خودکار می‌سازد:

/var/lib/pg-node/certs/ssl_cert.pem
/var/lib/pg-node/certs/ssl_key.pem

اگر فقط یکی از فایل‌ها وجود داشته باشد، سرویس عمداً متوقف می‌شود. هیچ‌وقت فقط یکی از آن‌ها را حذف نکنید.

رفع خطای CERTIFICATE_VERIFY_FAILED

این خطا یعنی hostname certificate با hostname TCP Proxy یکی نیست. ابتدا این متغیر را تنظیم کنید:

TLS_SERVER_NAME=altaria.proxy.rlwy.net

سپس در Console سرویس Railway این دستور را اجرا کنید:

rm -f /var/lib/pg-node/certs/ssl_cert.pem \
      /var/lib/pg-node/certs/ssl_key.pem

برای بررسی حذف فایل‌ها:

ls -la /var/lib/pg-node/certs

حالا سرویس را Redeploy کنید. certificate جدید با SAN دامنهٔ صحیح ساخته می‌شود. فایل جدید زیر را از Volume دریافت و کل محتوای آن را در پنل وارد کنید:

/var/lib/pg-node/certs/ssl_cert.pem

خطاها و لاگ‌های رایج

Failed to load env file ... .env: no such file

این هشدار روی Railway طبیعی است. متغیرها از بخش Railway Variables تزریق می‌شوند و وجود فایل .env ضروری نیست.

gRPC Server listening on 0.0.0.0:8080

یعنی Node با موفقیت اجرا شده است. پورت داخلی TCP Proxy را 8080 بگذارید و در پنل، پورت عمومی TCP Proxy را وارد کنید.

dockerfile invalid: docker VOLUME ... is not supported

نباید در Dockerfile دستور VOLUME اضافه کنید. Volume را از Railway بسازید و روی /var/lib/pg-node mount کنید.

خطای connection refused 127.0.0.1:10002

این خطا یعنی یک outbound با نامی مانند de به HTTP proxy محلی روی پورت 10002 اشاره می‌کند، اما چنین proxyای داخل کانتینر اجرا نشده است.

در پنل PasarGuard، outbound یا route مربوط به de را حذف/غیرفعال کنید یا آدرس proxy را به یک مقصد واقعی و قابل‌دسترسی تغییر دهید. اگر اتصال مستقیم می‌خواهید، route را روی outbound نوع freedom/direct بگذارید.

127.0.0.1 به خود کانتینر اشاره می‌کند، نه به کامپیوتر شما یا پنل.

پنل به Node وصل نمی‌شود

موارد زیر را بررسی کنید:

1. TCP Proxy ساخته شده و پورت داخلی آن با PORT لاگ یکی است.
2. در پنل hostname و port عمومی TCP Proxy وارد شده است.
3. SERVICE_PROTOCOL=grpc است.
4. API_KEY در Railway و پنل دقیقاً یکسان است.
5. آدرس خصوصی railway.internal در پنل استفاده نشده است.
6. certificate جدید در پنل جایگزین شده است.

API_KEY is required یا UUID نامعتبر

در Railway Variables یک UUID معتبر برای API_KEY قرار دهید و سرویس را Redeploy کنید.

خطای دسترسی WireGuard

WireGuard به CAP_NET_ADMIN، nftables و پشتیبانی کرنل میزبان نیاز دارد. ممکن است Railway این قابلیت‌ها را در اختیار کانتینر نگذارد. در Railway از backend نوع Xray استفاده کنید یا Node را روی VM/VPS با Docker Compose اجرا کنید.

اجرای محلی با Docker

Copy-Item .env.example .env
docker build -t railway-pg-node .
docker run --rm `
  -p 62050:62050 `
  --env-file .env `
  -v pg-node-data:/var/lib/pg-node `
  railway-pg-node

برای build نسخهٔ دیگری از upstream:

docker build `
  --build-arg PASARGUARD_NODE_REF=<commit-or-tag> `
  -t railway-pg-node .

کمک مالی

قبل از ارسال، شبکهٔ کیف پول را دقیق بررسی کنید؛ انتقال روی شبکهٔ اشتباه قابل برگشت نیست.

شبکه	دارایی	آدرس
BNB Smart Chain (BEP-20)	USDT / Tether	0x2364898407e8A42DA554B909989cd9B28eE61314
TON	TON	UQCondoXRwQNt0fQvvmYGa_Fn39D9szjQH4eBqIcUd5r1yfH
TRON	TRX	TRhnkJFpj9uxA2aqUxapJAFhkzNPbfxKwp

فایل‌های repository

فایل	کاربرد
Dockerfile	ساخت image از upstream ثابت و runtime
start.sh	اعتبارسنجی متغیرها، ساخت TLS و اجرای Node
railway.toml	تنظیمات build و restart در Railway
.env.example	قالب متغیرهای اجرای محلی
tests/startup.Tests.ps1	تست قرارداد startup

upstream و مجوز

این wrapper پروژهٔ PasarGuard Node را build و اجرا می‌کند. قبل از بازتوزیع imageهای تغییر‌یافته، مجوز GPL-3.0 پروژهٔ upstream را بررسی کنید.