后端分离部署

本指南将帮助您独立部署 PPanel 后端服务，适用于前后端分离部署场景。

概述

后端分离部署允许您将 PPanel 后端服务部署在独立的服务器上，提供 API 服务给前端应用。这种部署方式具有以下优势：

🚀 独立扩展后端服务性能
🔒 更好的安全隔离
🌐 支持多前端实例连接同一后端
🛠️ 便于后端服务的独立维护和升级

系统要求

最低配置

CPU: 1 核心
内存: 1 GB
存储: 10 GB
操作系统: Linux (推荐 Ubuntu 20.04+, Debian 11+, CentOS 8+)

部署方式

方式一：Docker 部署（推荐）

1. 安装 Docker

bash

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

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

2. 创建配置文件

创建后端配置文件 config.yaml：

yaml

# 数据库配置
database:
  type: mysql
  host: localhost
  port: 3306
  username: ppanel
  password: your_password
  database: ppanel

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

# 服务配置
server:
  host: 0.0.0.0
  port: 8080

# CORS 配置（重要：允许前端域名访问）
cors:
  allow_origins:
    - "https://your-frontend-domain.com"
    - "http://localhost:3000"  # 开发环境
  allow_methods:
    - GET
    - POST
    - PUT
    - DELETE
    - OPTIONS
  allow_headers:
    - "*"

# JWT 配置
jwt:
  secret: "your-secret-key"
  expire: 7200  # 2小时

# API 配置
api:
  prefix: "/api"
  version: "v1"

3. 准备 MySQL 数据库

bash

# 使用 Docker 运行 MySQL
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

# 等待 MySQL 启动
sleep 10

4. 准备 Redis

bash

# 使用 Docker 运行 Redis
docker run -d \
  --name ppanel-redis \
  -p 6379:6379 \
  -v ppanel-redis-data:/data \
  redis:7-alpine

5. 运行后端服务

bash

# 拉取后端镜像
docker pull ppanel/ppanel:latest

# 运行后端容器
docker run -d \
  --name ppanel-backend \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --link ppanel-mysql:mysql \
  --link ppanel-redis:redis \
  ppanel/ppanel:latest

6. 初始化数据库

bash

# 执行数据库迁移
docker exec ppanel-backend ./ppanel migrate

方式二：二进制部署

1. 下载后端程序

bash

# 下载最新版本
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz

# 解压
tar -xzf ppanel-linux-amd64.tar.gz
cd ppanel

# 赋予执行权限
chmod +x ppanel

2. 配置后端服务

创建配置文件 config.yaml（内容同上 Docker 部署方式）。

3. 安装并配置 MySQL

bash

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

# 创建数据库和用户
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. 安装并配置 Redis

bash

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

5. 初始化数据库

bash

# 执行数据库迁移
./ppanel migrate

6. 创建 systemd 服务

创建服务文件 /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

启动服务：

bash

# 创建专用用户
sudo useradd -r -s /bin/false ppanel

# 移动文件到安装目录
sudo mkdir -p /opt/ppanel
sudo mv ppanel config.yaml /opt/ppanel/
sudo chown -R ppanel:ppanel /opt/ppanel

# 启动服务
sudo systemctl daemon-reload
sudo systemctl start ppanel
sudo systemctl enable ppanel

# 查看服务状态
sudo systemctl status ppanel

配置反向代理

Nginx 配置

nginx

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

    # HTTPS 重定向（推荐配置 SSL 证书）
    # 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 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 超时配置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

# HTTPS 配置示例
# 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;
#         # ... 其他配置同上
#     }
# }

重载 Nginx：

bash

sudo nginx -t
sudo systemctl reload nginx

Caddy 配置

caddy

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

验证部署

健康检查

bash

# 检查后端服务是否运行
curl http://localhost:8080/api/health

# 预期输出
# {"status":"ok","version":"1.0.0"}

测试 API

bash

# 测试公共 API
curl http://localhost:8080/api/v1/ping

# 预期输出
# {"message":"pong"}

环境变量配置

除了配置文件，您也可以使用环境变量：

bash

# 数据库配置
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=ppanel
export DB_PASSWORD=your_password
export DB_NAME=ppanel

# Redis 配置
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_PASSWORD=""

# JWT 密钥
export JWT_SECRET=your-secret-key

# 服务端口
export SERVER_PORT=8080

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 \
  ppanel/ppanel:latest

安全建议

使用强密码：为数据库和 JWT 密钥设置强密码
配置防火墙：仅开放必要端口（如 80, 443）
启用 HTTPS：使用 SSL/TLS 证书加密通信
CORS 配置：仅允许可信的前端域名访问
定期备份：定期备份数据库和配置文件
监控日志：定期检查应用日志和系统日志

故障排查

服务无法启动

bash

# 查看服务日志
sudo journalctl -u ppanel -n 50 --no-pager

# Docker 查看日志
docker logs ppanel-backend

数据库连接失败

bash

# 测试 MySQL 连接
mysql -h localhost -u ppanel -p -e "SELECT 1;"

# 检查 MySQL 服务状态
sudo systemctl status mysql

Redis 连接失败

bash

# 测试 Redis 连接
redis-cli ping

# 检查 Redis 服务状态
sudo systemctl status redis-server

CORS 错误

确保在 config.yaml 中正确配置了前端域名：

yaml

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

性能优化

数据库优化

sql

-- 创建必要的索引
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 缓存配置

yaml

redis:
  # 启用缓存
  cache_enabled: true
  # 缓存过期时间（秒）
  cache_ttl: 3600

应用层优化

yaml

# 启用 Gzip 压缩
server:
  gzip: true

# 调整并发连接数
server:
  max_connections: 1000

升级指南

Docker 升级

bash

# 拉取最新镜像
docker pull ppanel/ppanel:latest

# 停止旧容器
docker stop ppanel-backend

# 备份数据
docker exec ppanel-mysql mysqldump -u ppanel -p ppanel > backup.sql

# 删除旧容器
docker rm ppanel-backend

# 运行新容器
docker run -d \
  --name ppanel-backend \
  -p 8080:8080 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --link ppanel-mysql:mysql \
  --link ppanel-redis:redis \
  ppanel/ppanel:latest

# 执行数据库迁移
docker exec ppanel-backend ./ppanel migrate

二进制升级

bash

# 停止服务
sudo systemctl stop ppanel

# 备份旧版本
sudo cp /opt/ppanel/ppanel /opt/ppanel/ppanel.backup

# 下载新版本
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
tar -xzf ppanel-linux-amd64.tar.gz

# 替换文件
sudo mv ppanel /opt/ppanel/
sudo chown ppanel:ppanel /opt/ppanel/ppanel

# 执行数据库迁移
cd /opt/ppanel
sudo -u ppanel ./ppanel migrate

# 启动服务
sudo systemctl start ppanel

下一步

前端分离部署 - 部署前端应用
节点端安装 - 部署节点服务
API 文档 - 查看完整 API 文档

后端分离部署 ​

概述 ​

系统要求 ​

最低配置 ​

推荐配置 ​

部署方式 ​

方式一：Docker 部署（推荐） ​

1. 安装 Docker ​

2. 创建配置文件 ​

3. 准备 MySQL 数据库 ​

4. 准备 Redis ​

5. 运行后端服务 ​

6. 初始化数据库 ​

方式二：二进制部署 ​

1. 下载后端程序 ​

2. 配置后端服务 ​

3. 安装并配置 MySQL ​

4. 安装并配置 Redis ​

5. 初始化数据库 ​

6. 创建 systemd 服务 ​

配置反向代理 ​

Nginx 配置 ​

Caddy 配置 ​

验证部署 ​

健康检查 ​

测试 API ​

环境变量配置 ​

安全建议 ​

故障排查 ​

服务无法启动 ​

数据库连接失败 ​

Redis 连接失败 ​

CORS 错误 ​

性能优化 ​

数据库优化 ​

Redis 缓存配置 ​

应用层优化 ​

升级指南 ​

Docker 升级 ​

二进制升级 ​

下一步 ​

后端分离部署

概述

系统要求

最低配置

推荐配置

部署方式

方式一：Docker 部署（推荐）

1. 安装 Docker

2. 创建配置文件

3. 准备 MySQL 数据库

4. 准备 Redis

5. 运行后端服务

6. 初始化数据库

方式二：二进制部署

1. 下载后端程序

2. 配置后端服务

3. 安装并配置 MySQL

4. 安装并配置 Redis

5. 初始化数据库

6. 创建 systemd 服务

配置反向代理

Nginx 配置

Caddy 配置

验证部署

健康检查

测试 API

环境变量配置

安全建议

故障排查

服务无法启动

数据库连接失败

Redis 连接失败

CORS 错误

性能优化

数据库优化

Redis 缓存配置

应用层优化

升级指南

Docker 升级

二进制升级

下一步