Backend Separation Deployment

This guide will help you independently deploy the PPanel backend service, suitable for front-end and back-end separation deployment scenarios.

Overview

Backend separation deployment allows you to deploy the PPanel backend service on an independent server to provide API services for frontend applications. This deployment method has the following advantages:

🚀 Independently scale backend service performance
🔒 Better security isolation
🌐 Support multiple frontend instances connecting to the same backend
🛠️ Facilitate independent maintenance and upgrades of backend services

System Requirements

Minimum Configuration

CPU: 1 core
Memory: 1 GB
Storage: 10 GB
OS: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+ recommended)

Recommended Configuration

CPU: 2+ cores
Memory: 2+ GB
Storage: 20+ GB

Deployment Methods

Method 1: Docker Deployment (Recommended)

1. Install Docker

bash

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

2. Create Configuration File

Create backend config file config.yaml:

yaml

# Database configuration
database:
  type: mysql
  host: localhost
  port: 3306
  username: ppanel
  password: your_password
  database: ppanel

# Redis configuration
redis:
  host: localhost
  port: 6379
  password: ""
  db: 0

# Server configuration
server:
  host: 0.0.0.0
  port: 8080

# CORS configuration (Important: allow frontend domain access)
cors:
  allow_origins:
    - "https://your-frontend-domain.com"
    - "http://localhost:3000"  # Development environment
  allow_methods:
    - GET
    - POST
    - PUT
    - DELETE
    - OPTIONS
  allow_headers:
    - "*"

# JWT configuration
jwt:
  secret: "your-secret-key"
  expire: 7200  # 2 hours

# API configuration
api:
  prefix: "/api"
  version: "v1"

3. Prepare MySQL Database

bash

# Run MySQL with Docker
docker run -d \
  --name ppanel-mysql \
  -e MYSQL_ROOT_PASSWORD=root_password \
  -e MYSQL_DATABASE=ppanel \
  -e MYSQL_USER=ppanel \
  -e MYSQL_PASSWORD=your_password \
  -p 3306:3306 \
  -v ppanel-mysql-data:/var/lib/mysql \
  mysql:8.0

# Wait for MySQL to start
sleep 10

4. Prepare Redis

bash

# Run Redis with Docker
docker run -d \
  --name ppanel-redis \
  -p 6379:6379 \
  -v ppanel-redis-data:/data \
  redis:7-alpine

5. Run Backend Service

bash

# Pull backend image
docker pull ghcr.io/perfect-panel/ppanel:latest

# Run backend container
docker run -d \
  --name ppanel-backend \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --link ppanel-mysql:mysql \
  --link ppanel-redis:redis \
  ghcr.io/perfect-panel/ppanel:latest

6. Initialize Database

bash

# Execute database migration
docker exec ppanel-backend ./ppanel migrate

Method 2: Binary Deployment

1. Download Backend Program

bash

# Download latest version
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz

# Extract
tar -xzf ppanel-linux-amd64.tar.gz
cd ppanel

# Grant execute permission
chmod +x ppanel

2. Configure Backend Service

Create config file config.yaml (same content as Docker deployment method).

3. Install and Configure MySQL

bash

# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server -y

# Create database and user
sudo mysql <<EOF
CREATE DATABASE ppanel;
CREATE USER 'ppanel'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON ppanel.* TO 'ppanel'@'localhost';
FLUSH PRIVILEGES;
EOF

4. Install and Configure Redis

bash

# Ubuntu/Debian
sudo apt install redis-server -y
sudo systemctl start redis-server
sudo systemctl enable redis-server

5. Initialize Database

bash

# Execute database migration
./ppanel migrate

6. Create systemd Service

Create service file /etc/systemd/system/ppanel.service:

ini

[Unit]
Description=PPanel Backend Service
After=network.target mysql.service redis.service

[Service]
Type=simple
User=ppanel
WorkingDirectory=/opt/ppanel
ExecStart=/opt/ppanel/ppanel server
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Start service:

bash

# Create dedicated user
sudo useradd -r -s /bin/false ppanel

# Move files to installation directory
sudo mkdir -p /opt/ppanel
sudo mv ppanel config.yaml /opt/ppanel/
sudo chown -R ppanel:ppanel /opt/ppanel

# Start service
sudo systemctl daemon-reload
sudo systemctl start ppanel
sudo systemctl enable ppanel

# Check service status
sudo systemctl status ppanel

Configure Reverse Proxy

Nginx Configuration

nginx

server {
    listen 80;
    server_name api.your-domain.com;

    # HTTPS redirect (recommended to configure SSL certificate)
    # return 301 https://$server_name$request_uri;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header 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 support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Timeout configuration
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

# HTTPS configuration example
# server {
#     listen 443 ssl http2;
#     server_name api.your-domain.com;
#
#     ssl_certificate /path/to/cert.pem;
#     ssl_certificate_key /path/to/key.pem;
#
#     location / {
#         proxy_pass http://127.0.0.1:8080;
#         # ... other configs same as above
#     }
# }

Reload Nginx:

bash

sudo nginx -t
sudo systemctl reload nginx

Caddy Configuration

caddy

api.your-domain.com {
    reverse_proxy localhost:8080
}

Verify Deployment

Health Check

bash

# Check if backend service is running
curl http://localhost:8080/api/health

# Expected output
# {"status":"ok","version":"1.0.0"}

Test API

bash

# Test public API
curl http://localhost:8080/api/v1/ping

# Expected output
# {"message":"pong"}

Environment Variable Configuration

Besides config file, you can also use environment variables:

bash

# Database configuration
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=ppanel
export DB_PASSWORD=your_password
export DB_NAME=ppanel

# Redis configuration
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_PASSWORD=""

# JWT secret
export JWT_SECRET=your-secret-key

# Server port
export SERVER_PORT=8080

Using environment variables with Docker:

bash

docker run -d \
  --name ppanel-backend \
  -p 8080:8080 \
  -e DB_HOST=mysql \
  -e DB_USER=ppanel \
  -e DB_PASSWORD=your_password \
  -e REDIS_HOST=redis \
  --link ppanel-mysql:mysql \
  --link ppanel-redis:redis \
  ghcr.io/perfect-panel/ppanel:latest

Security Recommendations

Use Strong Passwords: Set strong passwords for database and JWT secret
Configure Firewall: Only open necessary ports (e.g., 80, 443)
Enable HTTPS: Use SSL/TLS certificates to encrypt communication
CORS Configuration: Only allow trusted frontend domains
Regular Backups: Regularly backup database and config files
Monitor Logs: Regularly check application and system logs

Troubleshooting

Service Failed to Start

bash

# View service logs
sudo journalctl -u ppanel -n 50 --no-pager

# Docker view logs
docker logs ppanel-backend

Database Connection Failed

bash

# Test MySQL connection
mysql -h localhost -u ppanel -p -e "SELECT 1;"

# Check MySQL service status
sudo systemctl status mysql

Redis Connection Failed

bash

# Test Redis connection
redis-cli ping

# Check Redis service status
sudo systemctl status redis-server

CORS Error

Ensure frontend domain is correctly configured in config.yaml:

yaml

cors:
  allow_origins:
    - "https://your-frontend-domain.com"

Performance Optimization

Database Optimization

sql

-- Create necessary indexes
CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_order_status ON orders(status);
CREATE INDEX idx_created_at ON orders(created_at);

Redis Cache Configuration

yaml

redis:
  # Enable cache
  cache_enabled: true
  # Cache expiration time (seconds)
  cache_ttl: 3600

Application Layer Optimization

yaml

# Enable Gzip compression
server:
  gzip: true

# Adjust concurrent connections
server:
  max_connections: 1000

Upgrade Guide

Docker Upgrade

bash

# Pull latest image
docker pull ghcr.io/perfect-panel/ppanel:latest

# Stop old container
docker stop ppanel-backend

# Backup data
docker exec ppanel-mysql mysqldump -u ppanel -p ppanel > backup.sql

# Remove old container
docker rm ppanel-backend

# Run new container
docker run -d \
  --name ppanel-backend \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --link ppanel-mysql:mysql \
  --link ppanel-redis:redis \
  ghcr.io/perfect-panel/ppanel:latest

# Execute database migration
docker exec ppanel-backend ./ppanel migrate

Binary Upgrade

bash

# Stop service
sudo systemctl stop ppanel

# Backup old version
sudo cp /opt/ppanel/ppanel /opt/ppanel/ppanel.backup

# Download new version
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
tar -xzf ppanel-linux-amd64.tar.gz

# Replace file
sudo mv ppanel /opt/ppanel/
sudo chown ppanel:ppanel /opt/ppanel/ppanel

# Execute database migration
cd /opt/ppanel
sudo -u ppanel ./ppanel migrate

# Start service
sudo systemctl start ppanel

Next Steps

Frontend Separation Deployment - Deploy frontend application
Node Agent Installation - Deploy node service
API Documentation - View complete API documentation

Backend Separation Deployment ​

Overview ​

System Requirements ​

Minimum Configuration ​

Recommended Configuration ​

Deployment Methods ​

Method 1: Docker Deployment (Recommended) ​

1. Install Docker ​

2. Create Configuration File ​

3. Prepare MySQL Database ​

4. Prepare Redis ​

5. Run Backend Service ​

6. Initialize Database ​

Method 2: Binary Deployment ​

1. Download Backend Program ​

2. Configure Backend Service ​

3. Install and Configure MySQL ​

4. Install and Configure Redis ​

5. Initialize Database ​

6. Create systemd Service ​

Configure Reverse Proxy ​

Nginx Configuration ​

Caddy Configuration ​

Verify Deployment ​

Health Check ​

Test API ​

Environment Variable Configuration ​

Security Recommendations ​

Troubleshooting ​

Service Failed to Start ​

Database Connection Failed ​

Redis Connection Failed ​

CORS Error ​

Performance Optimization ​

Database Optimization ​

Redis Cache Configuration ​

Application Layer Optimization ​

Upgrade Guide ​

Docker Upgrade ​

Binary Upgrade ​

Next Steps ​

Backend Separation Deployment

Overview

System Requirements

Minimum Configuration

Recommended Configuration

Deployment Methods

Method 1: Docker Deployment (Recommended)

1. Install Docker

2. Create Configuration File

3. Prepare MySQL Database

4. Prepare Redis

5. Run Backend Service

6. Initialize Database

Method 2: Binary Deployment

1. Download Backend Program

2. Configure Backend Service

3. Install and Configure MySQL

4. Install and Configure Redis

5. Initialize Database

6. Create systemd Service

Configure Reverse Proxy

Nginx Configuration

Caddy Configuration

Verify Deployment

Health Check

Test API

Environment Variable Configuration

Security Recommendations

Troubleshooting

Service Failed to Start

Database Connection Failed

Redis Connection Failed

CORS Error

Performance Optimization

Database Optimization

Redis Cache Configuration

Application Layer Optimization

Upgrade Guide

Docker Upgrade

Binary Upgrade

Next Steps