yan/rvs-prxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ae15f30253
rvs-prxy/Design_Doc/architecture.md

11 KiB
Raw Blame History

Generic Reverse Proxy Architecture

Overview

This document describes a generic reverse proxy architecture that enables internal services to be accessible via public domains. The architecture uses FRP (Fast Reverse Proxy) for tunneling and Traefik for HTTP/HTTPS routing with automatic certificate management.

Architecture Block Diagram

+-------------------+    SSH Commands     +-------------------+
|   Local Host      | ------------------> |  Proxy Server     |
|                   |                     |                   |
|  +-------------+  |    FRP Tunnel       |  +-------------+  |
|  | Application |  | ------------------> |  |   FRPS      |  |
|  |   Service   |  |                     |  | (Server)    |  |<--- Public IPs
|  |             |  |                     |  |             |  |    Port: 16999
|  +-------------+  |                     |  +-------------+  |
|                   |                     |                   |
|  +-------------+  |    FRP Client       |  +-------------+  |
|  |   FRPC      |  | ------------------> |  |   Traefik   |  |<--- Domains
|  | (Client)    |  |                     |  | (Router)    |  |    HTTPS/TLS
|  |             |  |                     |  |             |  |
|  +-------------+  |                     |  +-------------+  |
|                   |                     |                   |
|  +-------------+  |                     |  +-------------+  |
|  | Docker      |  |                     |  | Docker      |  |
|  | Container   |  |                     |  | Container   |  |
|  +-------------+  |                     |  +-------------+  |
+-------------------+                     +-------------------+
        |                                           |
        |                                           |
        +------------------ Volumes ------------------+
        |    rad-git-sshd-itl-frpc-<instance>       |
        +-------------------------------------------+

Architecture Components

Core Components

  • FRP (Fast Reverse Proxy): Handles TCP/UDP tunneling between internal and external networks
    • FRPS (FRP Server): Runs on the public-facing server
    • FRPC (FRP Client): Runs on internal service hosts
  • Traefik: HTTP/HTTPS router with automatic Let's Encrypt certificate management
  • Docker & Docker Compose: Container orchestration and deployment
  • SSH: Secure communication for remote configuration management

Supporting Elements

  • Configuration Storage: Docker volumes for persistent configuration
  • DNS Management: Domain-to-IP mapping for public access
  • Certificate Management: Automatic SSL/TLS certificate provisioning and renewal

Prerequisites

  • FRP (Fast Reverse Proxy) service with frpc and frps
  • Traefik reverse proxy
  • Docker and Docker Compose installed
  • SSH key for remote server access
  • Environment variable for configuration source (DOWNLOAD_SOURCE)
  • User permissions for Docker commands
  • Authentication keys for secure access

Parameters

Required Parameters

  • Instance Name: Unique identifier for the service instance (alphanumeric, hyphens, underscores only)
  • Application Port(s): Internal port(s) where the service is listening
  • Domain Name: Public domain for Traefik routing rules
  • FRP Server Address: Public IP address of the FRP server
  • FRP Server Port: Port for FRP communication (default 16999)

Optional Parameters

  • Docker Network: Network for container isolation (default uses Docker bridge)
  • Proxy Ports: Custom remote ports for external access (defaults: TCP ports matching internal ports)
  • Service Type: Protocol specification (TCP/UDP/HTTP/HTTPS)

Outcomes

  • Public domain connectivity to internal service
  • Secure encrypted tunnel between internal and external networks
  • Automatic SSL/TLS certificates via Let's Encrypt
  • Persistent configuration through Docker volumes
  • Automated service discovery and routing

Architecture Flow

1. Configuration Phase

  1. User provides service parameters via interactive prompts or command-line
  2. System validates parameters and checks for existing configurations
  3. Generates appropriate FRP client configuration (frpc.toml)
  4. Persists configuration to Docker volumes for continuity

2. Deployment Phase

  1. Creates Docker container with FRP client
  2. Establishes connection to FRP server
  3. Sets up port forwarding rules
  4. Updates proxy server to recognize new instance

3. Routing Phase

  1. Traefik configuration updated with new routing rules
  2. Domain name routes to appropriate internal service
  3. Automatic SSL/TLS certificate provisioned
  4. Health checks and monitoring established

4. Management Phase

  1. Persistent configuration for service continuity
  2. Backup and recovery mechanisms
  3. Restart procedures for configuration changes
  4. Service status monitoring

Real-World Example: Using auto-sys-deploy.sh and update-compose-config.sh

Example: Deploying a New FRP Client Instance

Based on auto-sys-deploy.sh.md and update-compose-config.sh.md, here's a real-world example of the architecture in action:

Initial Setup

  • Prerequisites: Docker, SSH key at ~/.ssh/itl-devs1, DOWNLOAD_SOURCE environment variable
  • Command: ./auto-sys-deploy.sh setup-frpc

Interactive Configuration (from auto-sys-deploy.sh)

  1. Instance Name Selection:

    • Default: setup-frpc-$(date +%Y%m%d-%H%M%S)
    • User input: my-app-instance-20231005-143000
    • Validation: alphanumeric, hyphens, underscores only

  2. Docker Network Selection:

    • Options: Select from existing networks, custom network, or default
    • User input: Select network bridge or create custom
    • Outcome: Container runs on specific Docker network

  3. FRP Server Configuration:

    • Server Address: 192.168.1.100 (example IP)
    • Server Port: 16999 (default)
    • Validation: Ensure server is accessible

  4. Proxy Configuration:

    • Rad Proxy (from auto-sys-deploy.sh):
      • Local Port: 8776 (default)
      • Remote Port: 8779 (user input)
      • Name: rad-my-app-instance-20231005-143000
    • SSH Proxy (from auto-sys-deploy.sh):
      • Local Port: 22 (default)
      • Remote Port: 13076 (user input)
      • Name: ssh-my-app-instance-20231005-143000
    • Web Proxy (from auto-sys-deploy.sh):
      • Local Port: 80 (default)
      • Remote Port: 13077 (user input)
      • Name: web-my-app-instance-20231005-143000

  5. Domain Configuration:

    • Input: myapp.example.com
    • Used for Traefik routing rules

Configuration Generation (from auto-sys-deploy.sh)

The script generates frpc.toml with:

serverAddr = "192.168.1.100"
serverPort = 16999

[[proxies]]
name = "rad-my-app-instance-20231005-143000"
type = "tcp"
localPort = 8776
localIP = "rad-git-sshd-my-app-instance-20231005-143000"
remotePort = 8779

[[proxies]]
name = "ssh-my-app-instance-20231005-143000"
type = "tcp"
localPort = 22
localIP = "rad-git-sshd-my-app-instance-20231005-143000"
remotePort = 13076

[[proxies]]
name = "web-my-app-instance-20231005-143000"
type = "tcp"
localPort = 80
localIP = "rad-git-sshd-my-app-instance-20231005-143000"
remotePort = 13077

Container Deployment (from auto-sys-deploy.sh)

  • Creates Docker volume: rad-git-sshd-itl-frpc-my-app-instance-20231005-143000
  • Starts container: rad-git-sshd-frpc-my-app-instance-20231005-143000
  • Uses image: snowdreamtech/frpc:0.62.0-alpine3.21
  • Mounts config volume: /etc/frp

Proxy Server Configuration (from update-compose-config.sh)

The script updates docker-compose.app.yml with:

Ports Section:

ports:
  # ... other ports ...
  
  # my-app-instance-20231005-143000 Self-hosting ports ====
  - "8779:8779/tcp"
  - "13076:13076/tcp" 
  - "13077:13077/tcp"
  # =========================
  
  # ... other ports ...

Labels Section:

labels:
  # ... other labels ...
  
  # my-app-instance-20231005-143000 Self-hosting labels ====
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-http.entrypoints=web"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-http.rule=Host(`myapp.example.com`)"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-http.service=frps-my-app-instance-20231005-143000"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-http.middlewares=http2https@file"

  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.entrypoints=websecure"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.rule=Host(`myapp.example.com`)"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.service=frps-my-app-instance-20231005-143000"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.tls=true"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.tls.certresolver=letsencrypt"
  - "traefik.http.routers.frps-my-app-instance-20231005-143000-https.tls.domains[0].main=myapp.example.com"

  - "traefik.http.services.frps-my-app-instance-20231005-143000.loadbalancer.server.port=13077"
  # =========================
  
  # ... other labels ...

Backup and Service Restart (from update-compose-config.sh)

  • Creates backup: docker-compose.app.yml.backup_YYYYMMDD_HHMMSS
  • Restarts service with: ./stop.sh && ./start.sh
  • Verifies deployment with: docker logs --tail 50 frps_frps_1

Extensibility Points

Protocol Support

  • TCP/UDP: Native FRP support for any TCP/UDP based service
  • HTTP/HTTPS: Enhanced routing via Traefik with automatic certificates
  • Custom Protocols: Extensible architecture for proprietary protocols

Service Types

  • Web Applications: HTTP/HTTPS routing with domain-based access
  • Database Services: Secure TCP tunneling for database connections
  • SSH Services: Encrypted access to internal SSH servers
  • API Services: Secure API endpoint exposure

Scaling Options

  • Load Balancing: Multiple instances behind single domain
  • Geographic Distribution: Multiple proxy servers in different regions
  • Protocol Multiplexing: Multiple services through single tunnel

Security Considerations

  • Encrypted tunnels between internal and external networks
  • Access control through SSH keys and authentication
  • Firewall isolation of internal services
  • Automatic certificate management for HTTPS
  • Docker container isolation

Maintenance Requirements

  • Regular backup of configuration files
  • Certificate renewal monitoring
  • Connection health monitoring
  • Log aggregation and analysis
  • Docker image updates

Generic Application Examples

Web Application Deployment

  • Parameters: Instance name, internal web port (80/443), domain name
  • Outcome: Public website accessible via configured domain

Database Access

  • Parameters: Instance name, internal database port, restricted domain
  • Outcome: Secure external access to internal database

Custom Service Exposure

  • Parameters: Instance name, custom application port, specific domain
  • Outcome: External access to internal custom service