c76a09c9d6
- Changed Docker pull commands in backend.md and its Chinese counterpart to use ppanel/ppanel:latest instead of ghcr.io/perfect-panel/ppanel:latest. - Removed obsolete Vue.js and source map files from the cache.
506 lines
9.1 KiB
Markdown
506 lines
9.1 KiB
Markdown
# 后端分离部署
|
||
|
||
本指南将帮助您独立部署 PPanel 后端服务，适用于前后端分离部署场景。
|
||
|
||
## 概述
|
||
|
||
后端分离部署允许您将 PPanel 后端服务部署在独立的服务器上，提供 API 服务给前端应用。这种部署方式具有以下优势：
|
||
|
||
- 🚀 独立扩展后端服务性能
|
||
- 🔒 更好的安全隔离
|
||
- 🌐 支持多前端实例连接同一后端
|
||
- 🛠️ 便于后端服务的独立维护和升级
|
||
|
||
## 系统要求
|
||
|
||
### 最低配置
|
||
- CPU: 1 核心
|
||
- 内存: 1 GB
|
||
- 存储: 10 GB
|
||
- 操作系统: Linux (推荐 Ubuntu 20.04+, Debian 11+, CentOS 8+)
|
||
|
||
### 推荐配置
|
||
- CPU: 2 核心以上
|
||
- 内存: 2 GB 以上
|
||
- 存储: 20 GB 以上
|
||
|
||
## 部署方式
|
||
|
||
### 方式一：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
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. **使用强密码**：为数据库和 JWT 密钥设置强密码
|
||
2. **配置防火墙**：仅开放必要端口（如 80, 443）
|
||
3. **启用 HTTPS**：使用 SSL/TLS 证书加密通信
|
||
4. **CORS 配置**：仅允许可信的前端域名访问
|
||
5. **定期备份**：定期备份数据库和配置文件
|
||
6. **监控日志**：定期检查应用日志和系统日志
|
||
|
||
## 故障排查
|
||
|
||
### 服务无法启动
|
||
|
||
```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
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- [前端分离部署](./frontend.md) - 部署前端应用
|
||
- [节点端安装](../node/installation.md) - 部署节点服务
|
||
- [API 文档](/zh/api/reference) - 查看完整 API 文档
|