📝 docs: Add documentation
This commit is contained in:
web@ppanel
@@ -0,0 +1,505 @@
|
||||
# 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
|
||||
|
||||
1. **Use Strong Passwords**: Set strong passwords for database and JWT secret
|
||||
2. **Configure Firewall**: Only open necessary ports (e.g., 80, 443)
|
||||
3. **Enable HTTPS**: Use SSL/TLS certificates to encrypt communication
|
||||
4. **CORS Configuration**: Only allow trusted frontend domains
|
||||
5. **Regular Backups**: Regularly backup database and config files
|
||||
6. **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](./frontend.md) - Deploy frontend application
|
||||
- [Node Agent Installation](../node/installation.md) - Deploy node service
|
||||
- [API Documentation](/api/reference) - View complete API documentation
|
||||
Reference in New Issue
Block a user