PPanel 完整安装指南：从零开始部署代理面板

本文原载于 PayIn Blog，转载请注明出处。

前言：本文基于 PPanel 1.2.2 版本编写。由于 PPanel 项目持续更新，官方文档 https://ppanel.dev/ 可能存在滞后，本文记录了我在实际安装过程中遇到的问题和解决方案，希望能帮助到同样踩坑的朋友。

PPanel 架构概述

PPanel 由以下四个独立组件组成，可以部署在同一台服务器，也可以分布式部署：

组件	说明
Server	核心后端服务，提供所有 API 接口
Admin Frontend	管理员后台界面
User Frontend	用户前台界面
PPanel Node	边缘节点代理服务

第一步：下载并解压 Server

从 GitHub Releases 页面下载对应系统的服务端版本：

# 以 Linux amd64 为例
wget https://github.com/perfect-panel/server/releases/download/v1.2.2/ppanel-server-linux-amd64.tar.gz

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

解压后目录结构：

.
├── ppanel-server          # 可执行文件
└── etc/
    └── ppanel.yaml        # 配置文件（初始为空）

第二步：使用 Docker 安装 MySQL 和 Redis

推荐使用 Docker 安装 MySQL 和 Redis，便于管理和迁移。

安装 Docker

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

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

创建 Docker 网络

docker network create ppanel-net

启动 MySQL

docker run -d 
  --name ppanel-mysql 
  --network ppanel-net 
  -e MYSQL_ROOT_PASSWORD=你的root密码 
  -e MYSQL_DATABASE=ppanel 
  -e MYSQL_USER=ppanel 
  -e MYSQL_PASSWORD=你的密码 
  -v ppanel-mysql-data:/var/lib/mysql 
  -p 3306:3306 
  --restart unless-stopped 
  mysql:8.0 
  --character-set-server=utf8mb4 
  --collation-server=utf8mb4_unicode_ci

启动 Redis

docker run -d 
  --name ppanel-redis 
  --network ppanel-net 
  -v ppanel-redis-data:/data 
  -p 6379:6379 
  --restart unless-stopped 
  redis:7-alpine 
  redis-server --appendonly yes

如需设置 Redis 密码：

docker run -d 
  --name ppanel-redis 
  --network ppanel-net 
  -v ppanel-redis-data:/data 
  -p 6379:6379 
  --restart unless-stopped 
  redis:7-alpine 
  redis-server --appendonly yes --requirepass 你的Redis密码

验证服务

# 检查容器状态
docker ps

# 测试 MySQL 连接
docker exec -it ppanel-mysql mysql -uppanel -p你的密码 -e "SHOW DATABASES;"

# 测试 Redis 连接
docker exec -it ppanel-redis redis-cli ping
# 应返回 PONG

第三步：配置 ppanel.yaml

参考配置文档，编辑 etc/ppanel.yaml：

# 服务器设置
Host: 0.0.0.0
Port: 8080
Debug: false

# JWT 认证配置
JwtAuth:
  AccessSecret: "请替换为一个随机的长字符串"  # 重要：用于 token 加密
  AccessExpire: 604800  # token 有效期，单位秒，默认 7 天

# MySQL 数据库配置（Docker）
MySQL:
  Addr: "127.0.0.1:3306"
  Username: "ppanel"
  Password: "你的密码"
  Dbname: "ppanel"
  MaxIdleConns: 10
  MaxOpenConns: 100
  LogMode: "info"
  SlowThreshold: 1000

# Redis 缓存配置（Docker）
Redis:
  Host: "127.0.0.1:6379"
  Pass: ""  # 如果设置了密码则填入
  DB: 0

# 管理员账户（首次启动时自动创建）
Administer:
  Email: "admin@example.com"  Password: "你的管理员密码"

重要提示：

AccessSecret 请使用随机生成的字符串，可用 openssl rand -hex 32 生成
Administer 配置仅在首次启动时生效，之后修改不会更新数据库

第四步：启动 Server

使用 screen 或 tmux 在后台启动服务：

# 使用 screen
screen -S ppanel

# 启动服务
./ppanel-server run --config etc/ppanel.yaml

首次启动时，Server 会自动初始化数据库表结构，可以从终端日志中观察：

[INFO] Starting database migration...
[INFO] Creating table: users
[INFO] Creating table: servers
...
[INFO] Database migration completed
[INFO] Starting server on 0.0.0.0:8080

按 Ctrl+A D 将 screen 放入后台。

验证服务是否正常

curl http://localhost:8080/v1/common/site/config

如果返回 JSON 配置信息，说明服务启动成功。

第五步：构建并部署前端

环境准备

推荐使用 Bun（也可使用 Node.js 20+）：

# 安装 Bun
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

克隆代码并安装依赖

git clone https://github.com/perfect-panel/frontend.git
cd frontend
bun install

配置环境变量

管理端 apps/admin/.env.production：

VITE_API_BASE_URL=https://api.你的域名.com
VITE_CDN_URL=https://cdn.jsdmirror.com
VITE_TUTORIAL_DOCUMENT=true

用户端 apps/user/.env.production：

VITE_API_BASE_URL=https://api.你的域名.com
VITE_CDN_URL=https://cdn.jsdmirror.com
VITE_SHOW_LANDING_PAGE=true

构建

# 构建所有应用
bun run build

# 或分别构建
cd apps/admin && bun run build
cd apps/user && bun run build

构建产物位置：

管理端：apps/admin/dist/
用户端：apps/user/dist/

部署到 Nginx

将构建产物复制到 Web 目录：

sudo mkdir -p /var/www/ppanel-admin /var/www/ppanel-user
sudo cp -r apps/admin/dist/* /var/www/ppanel-admin/
sudo cp -r apps/user/dist/* /var/www/ppanel-user/

配置 Nginx（前端站点）：

server {
    listen 80;
    server_name admin.你的域名.com;

    root /var/www/ppanel-admin;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

server {
    listen 80;
    server_name user.你的域名.com;

    root /var/www/ppanel-user;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

踩坑提醒：不建议使用 Vercel 一键部署。实测发现 User 前端部署到 Vercel 后，VITE_API_BASE_URL 环境变量不生效。这是因为 Vite 的环境变量在构建时会被打包进代码，Vercel 的运行时环境变量对其无效。

第六步：Nginx 反向代理与 Cloudflare HTTPS 配置

问题说明

前端部署完成后，你可能会遇到两个问题：

CORS 跨域拦截：Admin/User 前端通过浏览器异步请求 Server API，当前端域名（如 admin.example.com）与 API 域名（如 api.example.com）不一致时，浏览器会触发 CORS 安全机制阻止请求。
HTTPS 混合内容拦截：前端通常部署在 HTTPS 下，而 PPanel Server 默认监听 HTTP 8080 端口。浏览器会阻止从 HTTPS 页面向 HTTP 接口发起请求。

配置 Nginx 反向代理解决 CORS

创建 API 服务器的 Nginx 配置：

server {
    listen 80;
    server_name api.你的域名.com;

    location / {
        # 反向代理到 PPanel Server
        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;

        # CORS 配置
        add_header 'Access-Control-Allow-Origin' '*' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always;
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

        # 处理 OPTIONS 预检请求
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' '*';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain; charset=utf-8';
            add_header 'Content-Length' 0;
            return 204;
        }
    }
}

重载 Nginx：

sudo nginx -t          # 检查配置语法
sudo systemctl reload nginx

配置 Cloudflare 实现 HTTPS

建议为所有三个域名（API、Admin、User）都配置 HTTPS，避免混合内容问题。使用 Cloudflare 的 Flexible SSL 是最简单的解决方案。

1. 将域名接入 Cloudflare

登录 Cloudflare
添加你的域名，按提示修改 DNS 服务器

2. 添加 DNS 记录

为三个子域名都添加 A 记录：

类型	名称	内容	代理状态
A	api	你的服务器IP	已代理（橙色云朵）
A	admin	你的服务器IP	已代理（橙色云朵）
A	user	你的服务器IP	已代理（橙色云朵）

重要：确保三个域名的代理状态都为”已代理”（橙色云朵），这样 Cloudflare 才会提供 HTTPS 证书

3. 配置 SSL/TLS 加密模式

进入 SSL/TLS → 概述，选择加密模式为 Flexible。

Flexible 模式说明：

浏览器 ↔ Cloudflare：HTTPS（加密）
Cloudflare ↔ 你的服务器：HTTP（不加密）

这样无需在服务器配置 SSL 证书，Cloudflare 会自动为三个域名提供 HTTPS。

请求流程总结

第七步：部署 PPanel Node

在管理后台创建服务器

登录 Admin 前端
进入 节点管理 → 服务器管理
点击 新增服务器，填入节点服务器信息

重要：在选择协议配置时，必须指定协议端口！否则虽然能保存成功，但协议实际上并未启用，后续节点无法正常工作。

获取安装命令

服务器创建后，点击连接
弹出安装命令，注意修改 API 主机地址为你的 Server URL
在节点服务器执行修改后的命令

创建节点

安装完成后，管理界面可能仍显示服务器”离线”，这是正常的。

在管理界面创建节点
将节点关联到刚创建的服务器
等待几分钟，服务器状态应变为”在线”

排查问题

如果长时间未上线，到节点服务器查看日志：

ppnode log

常见问题：

API 地址配置错误
防火墙阻止了通信端口
SSL 证书问题（如果使用 HTTPS）

总结

至此，PPanel 完整安装完成！整体架构如下：

┌─────────────────┐     ┌─────────────────┐
│  Admin Frontend │     │  User Frontend  │
│  (admin.xxx)    │     │  (user.xxx)     │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     │ HTTPS (Cloudflare)
              ┌──────▼──────┐
              │   Server    │
              │  (api.xxx)  │
              └──────┬──────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
    ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
    │ Node 1  │ │ Node 2  │ │ Node N  │
    └─────────┘ └─────────┘ └─────────┘

其他高级配置（订阅、支付、邮件通知等），请参考 PPanel 官方文档。

资源链接

本文基于 PPanel v1.2.2 编写，更新于 2025 年 12 月 26 日。

原文链接：https://blog.payin.com/zh/posts/ppanel-install-guide/

目录