OmniRoute/docs/i18n/fa/docs/ops/VM_DEPLOYMENT_GUIDE.md

OmniRoute — Deployment Guide on VM with Cloudflare (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 زبانها: 🇺🇸 انگلیسی | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

راهنمای کامل نصب و پیکربندی OmniRoute روی یک ماشین مجازی (VPS) با دامنهای که از طریق Cloudflare مدیریت میشود.

---

پیشنیازها

مورد	حداقل	پیشنهادی
CPU	1 vCPU	2 vCPU
RAM	1 GB	2 GB
دیسک	10 GB SSD	25 GB SSD
سیستمعامل	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS
دامنه	ثبتشده در Cloudflare	—
Docker	Docker Engine 24+	Docker 27+

ارائهدهندگان آزمایششده: Akamai (Linode)، DigitalOcean، Vultr، Hetzner، AWS Lightsail.

---

1. پیکربندی ماشین مجازی

1.1 ایجاد نمونه

در ارائهدهنده VPS موردنظر خود:

• Ubuntu 24.04 LTS را انتخاب کنید
• حداقل پلن (1 vCPU / 1 GB RAM) را انتخاب کنید
• یک گذرواژه قدرتمند برای root تنظیم یا کلید SSH را پیکربندی کنید
• IP عمومی را یادداشت کنید (برای مثال، 203.0.113.10)

1.2 اتصال از طریق SSH

ssh root@203.0.113.10

1.3 بهروزرسانی سیستم

apt update && apt upgrade -y

1.4 نصب Docker

# نصب وابستگیها
apt install -y ca-certificates curl gnupg

# افزودن مخزن رسمی Docker
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $ (. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

1.5 نصب nginx

apt install -y nginx

1.6 پیکربندی دیوار آتش (UFW)

ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP (تغییر مسیر)
ufw allow 443/tcp   # HTTPS
ufw enable

نکته: برای حداکثر امنیت، دسترسی به پورتهای 80 و 443 را فقط به IPهای Cloudflare محدود کنید. بخش امنیت پیشرفته را ببینید.

---

2. نصب OmniRoute

2.1 ایجاد پوشه پیکربندی

mkdir -p /opt/omniroute

2.2 ایجاد فایل متغیرهای محیطی

cat > /opt/omniroute/.env << 'EOF'
# === امنیت ===
JWT_SECRET=CHANGE-TO-A-UNIQUE-64-CHAR-SECRET-KEY
INITIAL_PASSWORD=YourSecurePassword123!
API_KEY_SECRET=REPLACE-WITH-ANOTHER-SECRET-KEY
STORAGE_ENCRYPTION_KEY=REPLACE-WITH-THIRD-SECRET-KEY
STORAGE_ENCRYPTION_KEY_VERSION=v1
MACHINE_ID_SALT=CHANGE-TO-A-UNIQUE-SALT
OMNIROUTE_WS_BRIDGE_SECRET=REPLACE-WITH-WS-BRIDGE-SECRET  # در محیط عملیاتی الزامی است: توسط پل Codex Responses WS استفاده میشود

# === برنامه ===
PORT=20128
NODE_ENV=production
HOSTNAME=0.0.0.0
DATA_DIR=/app/data
APP_LOG_TO_FILE=true
AUTH_COOKIE_SECURE=true
REQUIRE_API_KEY=false

# === نشانیهای اینترنتی (به دامنه خود تغییر دهید) ===
# نشانی پایه داخلی سروربهسرور برای وظایف زمانبندیشده / واکشیهای داخلی.
BASE_URL=http://127.0.0.1:20128
# نشانی قابلدسترسی برای مرورگر که برای بازگشتهای OAuth، پیوندهای داشبورد و نشانیهای عمومی تولیدشده استفاده میشود.
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
# بازنویسی صریح و اختیاری مبدأ عمومی برای نشانیهای تولیدشده داراییهای عمومی.
# OMNIROUTE_PUBLIC_BASE_URL=https://llms.seudominio.com

# === همگامسازی ابری (اختیاری) ===
# CLOUD_URL=https://cloud.omniroute.online
# NEXT_PUBLIC_CLOUD_URL=https://cloud.omniroute.online
EOF

⚠️ مهم: کلیدهای محرمانه منحصربهفرد ایجاد کنید! برای هر کلید از openssl rand -hex 32 استفاده کنید.

2.3 راهاندازی کانتینر

docker pull diegosouzapw/omniroute:latest

docker run -d \
  --name omniroute \
  --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

2.4 بررسی اجرای صحیح آن

docker ps | grep omniroute
docker logs omniroute --tail 20

باید [DB] SQLite database ready و listening on port 20128 را نمایش دهد.

---

3. پیکربندی nginx (پروکسی معکوس)

3.1 ایجاد گواهی SSL ‏(Cloudflare Origin)

در داشبورد Cloudflare:

1. به SSL/TLS → Origin Server بروید
2. روی Create Certificate کلیک کنید
3. مقادیر پیشفرض را حفظ کنید (15 سال، *.yourdomain.com)
4. Origin Certificate و Private Key را کپی کنید

mkdir -p /etc/nginx/ssl

# گواهی را جایگذاری کنید
nano /etc/nginx/ssl/origin.crt

# کلید خصوصی را جایگذاری کنید
nano /etc/nginx/ssl/origin.key

chmod 600 /etc/nginx/ssl/origin.key

3.2 پیکربندی Nginx

cat > /etc/nginx/sites-available/omniroute << 'NGINX'
# سرور پیشفرض — دسترسی مستقیم از طریق IP را مسدود میکند
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;
    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    server_name _;
    return 444;
}

# OmniRoute — HTTPS
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name llms.yourdomain.com;  # به دامنه خود تغییر دهید

    ssl_certificate     /etc/nginx/ssl/origin.crt;
    ssl_certificate_key /etc/nginx/ssl/origin.key;
    ssl_protocols TLSv1.2 TLSv1.3;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:20128;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # پشتیبانی از WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # SSE (رویدادهای ارسالشده از سرور) — پاسخهای جریانی هوش مصنوعی
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

# هدایت HTTP → HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name llms.yourdomain.com;
    return 301 https://$server_name$request_uri;
}
NGINX

زمانهای انقضای جریان پروکسی معکوس را با متغیرهای محیطی زمان انقضای OmniRoute هماهنگ نگه دارید. اگر FETCH_TIMEOUT_MS / STREAM_IDLE_TIMEOUT_MS را افزایش میدهید، proxy_read_timeout / proxy_send_timeout را نیز به مقداری بالاتر از همان آستانه افزایش دهید.

OmniRoute از NEXT_PUBLIC_BASE_URL بهعنوان مبدأ متعارف قابلمشاهده برای مرورگر جهت فراخوانیهای بازگشتی OAuth و پیوندهای عمومی تولیدشده استفاده میکند. عملیات نوشتن احراز هویتشده در داشبورد از درخواستهای هممبدأ بههمراه محافظت CSRF وابسته به نشست استفاده میکنند؛ بنابراین به URL پایه عمومی ثابت نیازی ندارند. هدرهای X-Forwarded-* بالا همچنان فرادادههای مسیریابی مفیدی هستند، اما هنگامی که OAuth یا پیوندهای تولیدشده مرورگر به آن نیاز دارند، جایگزینی برای تنظیم URL عمومی صریح محسوب نمیشوند. OMNIROUTE_TRUST_PROXY را فقط زمانی فعال کنید که OmniRoute مستقیماً توسط کلاینتها قابلدسترسی نباشد و پروکسی شما هدرهای فورواردشده ورودی را حذف و دوباره ایجاد کند.

3.3 فعالسازی و آزمایش

# پیکربندی پیشفرض را حذف کنید
rm -f /etc/nginx/sites-enabled/default

# OmniRoute را فعال کنید
ln -sf /etc/nginx/sites-available/omniroute /etc/nginx/sites-enabled/omniroute

# آزمایش و بارگذاری مجدد
nginx -t && systemctl reload nginx

---

4. پیکربندی DNS در Cloudflare

4.1 افزودن رکورد DNS

در داشبورد Cloudflare به بخش DNS بروید:

نوع	نام	محتوا	پراکسی
A	llms	203.0.113.10 (IP ماشین مجازی)	✅ فعال

4.2 پیکربندی SSL

در بخش SSL/TLS → Overview:

• حالت: Full (Strict)

در بخش SSL/TLS → Edge Certificates:

• استفاده همیشگی از HTTPS: ✅ روشن
• حداقل نسخه TLS: TLS 1.2
• بازنویسی خودکار HTTPS: ✅ روشن

4.3 آزمایش

curl -sI https://llms.seudominio.com/health
# باید HTTP/2 200 را برگرداند

---

5. عملیات و نگهداری

ارتقا به نسخه جدید

docker pull diegosouzapw/omniroute:latest
docker stop omniroute && docker rm omniroute
docker run -d --name omniroute --restart unless-stopped \
  --env-file /opt/omniroute/.env \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

مشاهده لاگها

docker logs -f omniroute          # پخش بلادرنگ
docker logs omniroute --tail 50   # ۵۰ خط آخر

پشتیبانگیری دستی از پایگاه داده

# کپیکردن دادهها از volume به میزبان
docker cp omniroute:/app/data ./backup-$(date +%F)

# یا فشردهسازی کل volume
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data

بازیابی از نسخه پشتیبان

docker stop omniroute
docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/omniroute-data-YYYY-MM-DD.tar.gz -C /"
docker start omniroute

---

6. امنیت پیشرفته

محدودکردن nginx به IPهای Cloudflare

cat > /etc/nginx/cloudflare-ips.conf << 'CF'
# محدودههای IPv4 مربوط به Cloudflare — بهصورت دورهای بهروزرسانی شوند
# https://www.cloudflare.com/ips-v4/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
set_real_ip_from 103.22.200.0/22;
set_real_ip_from 103.31.4.0/22;
set_real_ip_from 141.101.64.0/18;
set_real_ip_from 108.162.192.0/18;
set_real_ip_from 190.93.240.0/20;
set_real_ip_from 188.114.96.0/20;
set_real_ip_from 197.234.240.0/22;
set_real_ip_from 198.41.128.0/17;
set_real_ip_from 162.158.0.0/15;
set_real_ip_from 104.16.0.0/13;
set_real_ip_from 104.24.0.0/14;
set_real_ip_from 172.64.0.0/13;
set_real_ip_from 131.0.72.0/22;
real_ip_header CF-Connecting-IP;
CF

عبارت زیر را درون بلوک http {} در فایل nginx.conf اضافه کنید:

include /etc/nginx/cloudflare-ips.conf;

نصب fail2ban

apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban

# بررسی وضعیت
fail2ban-client status sshd

مسدودکردن دسترسی مستقیم به پورت Docker

# جلوگیری از دسترسی مستقیم خارجی به پورت 20128
iptables -I DOCKER-USER -p tcp --dport 20128 -j DROP
iptables -I DOCKER-USER -i lo -p tcp --dport 20128 -j ACCEPT

# دائمیکردن قوانین
apt install -y iptables-persistent
netfilter-persistent save

---

7. استقرار در Cloudflare Workers (اختیاری)

برای دسترسی از راه دور از طریق Cloudflare Workers (بدون در معرض دسترسی مستقیم قرار دادن ماشین مجازی):

# در مخزن محلی
cd omnirouteCloud
npm install
npx wrangler login
npx wrangler deploy

همچنین برای راهنمای گامبهگام Cloudflare Tunnel درون مخزن، TUNNELS_GUIDE.md را ببینید. worker مستقل omnirouteCloud/ در یک مخزن مکمل جداگانه قرار دارد.

---

خلاصه پورتها

پورت	سرویس	دسترسی
22	SSH	عمومی (با fail2ban)
80	nginx HTTP	هدایت مجدد → HTTPS
443	nginx HTTPS	از طریق پروکسی Cloudflare
20128	OmniRoute	فقط localhost (از طریق nginx)

بهینهسازی برای حافظه کم / VPS کوچک

برای استقرار روی نمونههای کوچک VPS (با 1 GB RAM یا کمتر):

• سرویسهای پسزمینه را غیرفعال کنید — مقدار OMNIROUTE_DISABLE_BACKGROUND_SERVICES=1 را تنظیم کنید تا زمانبند، سرور MCP و وظایف نگهداری دورهای اجرا نشوند. به docs/reference/ENVIRONMENT.md مراجعه کنید.
• از حالت WAL در SQLite استفاده کنید — این حالت بهطور پیشفرض فعال است و اوج مصرف حافظه هنگام خواندنهای همزمان را کاهش میدهد.
• حافظه heap در V8 را محدود کنید — مقدار OMNIROUTE_MEMORY_MB (برای مثال 512) را تنظیم کنید تا محیط اجرا سقفی بزرگتر از VM تعیین نکند. به docs/reference/ENVIRONMENT.md مراجعه کنید.
• پذیرش درخواستهای سنگین بهطور خودکار متناسب با سقف heap مقیاس میشود -- پس از تنظیم OMNIROUTE_MEMORY_MB در بالا، بودجه بایتی دریافت داده (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES) بر اساس همان سقف محاسبه میشود؛ بنابراین یک VM با محدودیت حافظه، بدون نیاز به تنظیمات اضافی، بودجه کوچکتری برای درخواستهای همزمان خواهد داشت. درخواستهای مازاد بهجای رقابت برای حافظه، پاسخ قابلتلاشمجدد 503 را همراه با Retry-After دریافت میکنند. سقف قدیمی تعداد درخواستها، یعنی OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT، را فقط در صورتی تنظیم کنید که علاوه بر این، به یک سقف سخت نیاز دارید.
• از اجرای next build روی VPS خودداری کنید — پروژه را بهصورت محلی بسازید و خروجی مستقل (.next/standalone/) را مستقر کنید.
• با top / free -m نظارت کنید — OmniRoute معمولاً در حالت بیکار روی یک VM با 1 GB حافظه، بین 200 تا 400 MB حافظه RSS مصرف میکند.