128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# Zoraxy Reverse Proxy Setup Guide
|
|
|
|
> **Zoraxy is a Go-based reverse proxy + ACME daemon, running as a systemd service in LXC 108. It is NOT OpenWRT. Earlier docs referenced \`uci\` commands — those are removed; configuration is via the admin UI or by editing JSON config files in \`/opt/zoraxy/conf/proxy/\` and restarting \`systemctl restart zoraxy\`.**
|
|
|
|
|
|
## Overview
|
|
Configure reverse proxies for AI service endpoints with automatic SSL certificates.
|
|
|
|
## Target Services
|
|
|
|
| Service | Domain | Target | Port |
|
|
|---------|--------|--------|------|
|
|
| LiteLLM | `litellm.nuclide.systems` | `192.168.1.40` | `14000` |
|
|
| LobeHub | `chat.nuclide.systems` | `192.168.1.40` | `14001` |
|
|
| MCP Gateway | `mcp.nuclide.systems` | `192.168.1.40` | `8080` |
|
|
| Garage S3 | `s3.nuclide.systems` | `192.168.1.40` | `10004` |
|
|
|
|
## Method A — Zoraxy admin UI (recommended)
|
|
|
|
### Step 1: Access Zoraxy Panel
|
|
```
|
|
http://192.168.1.4:8000
|
|
```
|
|
|
|
### Step 2: Navigate to Rewrite Rules
|
|
1. Go to **"Reverse Proxy"** in the left sidebar
|
|
2. Click **"Rewrite Rules"**
|
|
|
|
### Step 3: Add Each Service
|
|
Click **"Add New Rule"** and fill in:
|
|
|
|
**For LiteLLM (`litellm.nuclide.systems`):**
|
|
- **Domain:** `litellm.nuclide.systems`
|
|
- **SSL:** `ON`
|
|
- **HTTPS Redirect:** `ON`
|
|
- **HSTS:** `ON`
|
|
- **Target Type:** `Server`
|
|
- **Target:** `192.168.1.40:14000`
|
|
- **Timeout:** `300` seconds
|
|
- **Proxy Time:** `300` seconds
|
|
|
|
**For LobeHub (`chat.nuclide.systems`):**
|
|
- **Domain:** `chat.nuclide.systems`
|
|
- **SSL:** `ON`
|
|
- **HTTPS Redirect:** `ON`
|
|
- **HSTS:** `ON`
|
|
- **Target Type:** `Server`
|
|
- **Target:** `192.168.1.40:14001`
|
|
- **Timeout:** `300` seconds
|
|
- **Proxy Time:** `300` seconds
|
|
|
|
**For MCP Gateway (`mcp.nuclide.systems`):**
|
|
- **Domain:** `mcp.nuclide.systems`
|
|
- **SSL:** `ON`
|
|
- **HTTPS Redirect:** `ON`
|
|
- **HSTS:** `ON`
|
|
- **Target Type:** `Server`
|
|
- **Target:** `192.168.1.40:8080`
|
|
- **Timeout:** `300` seconds
|
|
- **Proxy Time:** `300` seconds
|
|
|
|
**For Garage S3 (`s3.nuclide.systems`):**
|
|
- **Domain:** `s3.nuclide.systems`
|
|
- **SSL:** `ON`
|
|
- **HTTPS Redirect:** `ON`
|
|
- **HSTS:** `ON`
|
|
- **Target Type:** `Server`
|
|
- **Target:** `192.168.1.40:10004`
|
|
- **Timeout:** `300` seconds
|
|
- **Proxy Time:** `300` seconds
|
|
|
|
### Step 4: Save All Rules
|
|
Click **"Save"** at the bottom of the page.
|
|
|
|
### Step 5: SSL Certificate Generation
|
|
- Zoraxy automatically initiates Let's Encrypt certificate generation
|
|
- Wait 1-2 minutes for certificates to be issued
|
|
- Visual indicator: Green padlock icon in the UI
|
|
|
|
## Method B — automation via scripts/zoraxy_sync.py
|
|
|
|
Run from the control node:
|
|
|
|
```bash
|
|
# Generate UCI config
|
|
/opt/stacks/scripts/configure_zoraxy_helpers.sh --export-uci
|
|
|
|
# Or deploy via SSH (requires root@192.168.1.4 SSH access)
|
|
/opt/stacks/scripts/configure_zoraxy_helpers.sh --deploy
|
|
```
|
|
|
|
## Verification
|
|
|
|
After setup, verify all endpoints:
|
|
|
|
```bash
|
|
# Test each service
|
|
curl -I https://litellm.nuclide.systems/health
|
|
curl -I https://chat.nuclide.systems/api/health
|
|
curl -I https://mcp.nuclide.systems/health
|
|
curl -I https://s3.nuclide.systems/
|
|
```
|
|
|
|
Expected: HTTP 200 with SSL certificate.
|
|
|
|
## Troubleshooting
|
|
|
|
### SSL Certificate Issues
|
|
- Wait 2-3 minutes for Let's Encrypt to respond
|
|
- Check domain DNS resolution: `dig litellm.nuclide.systems`
|
|
- Verify firewall allows port 80 validation
|
|
|
|
### Proxy Connection Failed
|
|
- Check backend service is running: `htop` or `docker ps`
|
|
- Verify internal IP: `192.168.1.40` is reachable from Zoraxy
|
|
- Check target port is correct
|
|
|
|
### Configuration Not Saving
|
|
- Check Web UI is logged in (session expiry)
|
|
- Try clearing browser cache
|
|
- Verify UCI config syntax
|
|
|
|
## Notes
|
|
- SSL certificates are **automatic** via Let's Encrypt
|
|
- Zoraxy auto-renews certificates before expiry
|
|
- HSTS is recommended for production use
|
|
- All services use the same target IP (`192.168.1.40`)
|