OmniRoute — Deployment Guide on VM with 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. 設定 VM

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 限制為僅允許 Cloudflare IP。請參閱進階安全性章節。

---

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 bridge 使用

# === 應用程式 ===
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

# === URL（請變更為您的網域）===
# 排程工作／自行擷取所使用的內部伺服器對伺服器基礎 URL。
BASE_URL=http://127.0.0.1:20128
# 用於 OAuth 回呼、儀表板連結和所產生公用 URL 的瀏覽器端 URL。
NEXT_PUBLIC_BASE_URL=https://llms.seudominio.com
# 用於產生公用資產 URL 的選用明確公用來源覆寫值。
# 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（伺服器傳送事件）— 串流 AI 回應
        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 時，它們不能取代該 URL 設定。只有在用戶端無法直接連線至 OmniRoute，且您的代理會移除並重建 傳入的轉送標頭時，才啟用 OMNIROUTE_TRUST_PROXY。

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. 設定 Cloudflare DNS

4.1 新增 DNS 記錄

在 Cloudflare 控制面板 → DNS 中：

類型	名稱	內容	Proxy
A	llms	203.0.113.10（VM IP 位址）	✅ 已代理

4.2 設定 SSL

在 SSL/TLS → Overview 下：

• 模式：Full (Strict)

在 SSL/TLS → Edge Certificates 下：

• Always Use HTTPS：✅ 開啟
• 最低 TLS 版本：TLS 1.2
• Automatic HTTPS Rewrites：✅ 開啟

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   # 最後 50 行

手動備份資料庫

# 將資料從磁碟區複製到主機
docker cp omniroute:/app/data ./backup-$(date +%F)

# 或壓縮整個磁碟區
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 限制為僅允許 Cloudflare IP

cat > /etc/nginx/cloudflare-ips.conf << 'CF'
# Cloudflare IPv4 範圍 — 請定期更新
# 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

在 nginx.conf 的 http {} 區塊內加入以下內容：

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 遠端存取（不直接暴露 VM）：

# 在本機儲存庫中
cd omnirouteCloud
npm install
npx wrangler login
npx wrangler deploy

另請參閱 TUNNELS_GUIDE.md，以取得儲存庫內的 Cloudflare Tunnel 操作指南。獨立的 omnirouteCloud/ worker 位於另一個配套儲存庫中。

---

連接埠摘要

連接埠	服務	存取方式
22	SSH	公開（使用 fail2ban）
80	nginx HTTP	重新導向 → HTTPS
443	nginx HTTPS	透過 Cloudflare Proxy
20128	OmniRoute	僅限 localhost（透過 nginx）

低記憶體／小型 VPS 最佳化

針對小型 VPS 執行個體（1 GB RAM 或更少）的部署：

• 停用背景服務 — 設定 OMNIROUTE_DISABLE_BACKGROUND_SERVICES=1，以略過排程器、MCP 伺服器及定期維護工作。請參閱 docs/reference/ENVIRONMENT.md。
• 使用 SQLite WAL 模式 — 預設已啟用，可降低並行讀取期間的記憶體峰值。
• 限制 V8 堆積大小 — 設定 OMNIROUTE_MEMORY_MB（例如 512），使執行階段不會校準出大於 VM 的上限。請參閱 docs/reference/ENVIRONMENT.md。
• 重量級請求准入會依堆積上限自動調整 – 設定上述 OMNIROUTE_MEMORY_MB 後，擷取位元組預算（OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES）會依同一上限自動推導，因此記憶體受限的 VM 無需額外調校，即可獲得較小的並行請求預算；超額請求會收到可重試的 503 及 Retry-After，而不會彼此競爭記憶體。僅當您需要在此機制之上設定硬性上限時，才設定舊版的 OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT 請求數量上限。
• 避免在 VPS 上執行 next build — 請在本機建置，並部署獨立輸出（.next/standalone/）。
• 使用 top／free -m 監控 — 在 1 GB VM 上閒置時，OmniRoute 通常會使用 200-400 MB RSS。

---

OmniRoute 原始碼 (a58000c7685f)