PPanel

简体中文

English

简体中文

English

Appearance

2026-08-09
2117
9.9m

安装部署 ​

本指南将帮助你使用 Docker 在服务器上部署 PPanel。

系统要求 ​

最低配置 ​

  • 操作系统: Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
  • CPU: 1 核心
  • 内存: 512MB RAM
  • 存储: 1GB 可用磁盘空间
  • Docker: 20.10+
  • Docker Compose: 2.0+ (可选，但推荐使用)

推荐配置 ​

  • CPU: 2+ 核心
  • 内存: 2GB+ RAM
  • 存储: 5GB+ 可用磁盘空间

前置条件 ​

安装 Docker ​

如果你还没有安装 Docker，请按照官方安装指南进行安装：

Ubuntu/Debian:

bash
# 更新包索引
sudo apt-get update

# 安装必要的依赖包
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

CentOS/RHEL:

bash
# 安装 yum-utils
sudo yum install -y yum-utils

# 添加 Docker 仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

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

验证安装 ​

bash
# 查看 Docker 版本
docker --version

# 查看 Docker Compose 版本
docker compose version

# 测试 Docker 安装
sudo docker run hello-world

快速开始 ​

方式一：使用 Docker Run ​

步骤 1: 拉取镜像 ​

bash
# 拉取最新版本
docker pull ppanel/ppanel-server:latest

# 或锁定具体版本（标签格式 <版本>-<提交>，见 hub.docker.com/r/ppanel/ppanel-server/tags）
docker pull ppanel/ppanel-server:1.15.20-23f8e345

步骤 2: 准备配置 ​

创建配置目录并准备配置文件：

bash
# 创建配置目录
mkdir -p ppanel-config

# 创建配置文件
cat > ppanel-config/ppanel.yaml <<EOF
# PPanel 配置文件
Host: 0.0.0.0
Port: 8080

JwtAuth:
  AccessSecret: $(openssl rand -base64 32)
  AccessExpire: 604800

# PostgreSQL 与 Redis 都是必需的，Addr 填主机名或容器名，不能填 localhost
Database:
  Driver: postgres
  Addr: postgres:5432
  Username: ppanel
  Password: your-password
  Dbname: ppanel
  Config: sslmode=disable&TimeZone=Asia%2FShanghai

Redis:
  Host: redis:6379
  Pass: ''
  DB: 0
EOF

提示

详细的配置选项请参考 配置指南。

步骤 3: 运行容器 ​

bash
docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -v $(pwd)/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  --restart unless-stopped \
  ppanel/ppanel-server:latest

参数说明:

  • -d: 以守护进程模式运行容器（后台运行）
  • --name ppanel: 设置容器名称
  • -p 8080:8080: 将容器的 8080 端口映射到宿主机的 8080 端口
  • -v $(pwd)/ppanel-config:/app/etc:ro: 挂载配置目录（只读）
  • -v ppanel-data:/app/data: 创建数据卷用于持久化存储
  • --restart unless-stopped: 容器自动重启（除非手动停止）

步骤 4: 验证运行状态 ​

bash
# 查看容器状态
docker ps | grep ppanel

# 查看日志
docker logs -f ppanel

# 测试服务是否可访问
curl http://localhost:8080

方式二：使用 Docker Compose（推荐） ​

步骤 1: 创建 docker-compose.yml ​

yaml
services:
  postgres:
    image: postgres:18-alpine
    container_name: ppanel-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ppanel
      POSTGRES_USER: ppanel
      POSTGRES_PASSWORD: your-password
      TZ: Asia/Shanghai
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ppanel -d ppanel"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:8-alpine
    container_name: ppanel-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  ppanel:
    image: ppanel/ppanel-server:latest
    container_name: ppanel
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "8080:8080"
    volumes:
      - ./ppanel-config:/app/etc:ro
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  postgres-data:
  redis-data:

配置里的地址必须与服务名一致

上面 ppanel.yaml 中的 Addr: postgres:5432、Host: redis:6379 对应这里的服务名。容器内的 localhost 指向容器自身，填 localhost 会导致连接被拒。POSTGRES_PASSWORD 也要与配置文件里 Database.Password 一致。

步骤 2: 准备配置 ​

bash
# 创建配置目录
mkdir -p ppanel-config

# 复制或创建配置文件
# 详细配置请参考配置指南

步骤 3: 启动服务 ​

bash
# 以守护进程模式启动
docker compose up -d

# 查看日志
docker compose logs -f

# 查看状态
docker compose ps

部署后配置 ​

访问应用 ​

安装成功后，你可以通过以下地址访问：

  • 用户面板: http://your-server-ip:8080
  • 管理后台: http://your-server-ip:8080/admin

管理员账户

默认管理员账户（如果配置文件未设置）：

  • 邮箱: admin@ppanel.dev
  • 密码: password

一键安装脚本会自动生成随机的管理员账户并在安装结束时显示：

  • 邮箱: admin-[8位随机字符]@ppanel.dev
  • 密码: [随机生成的16位密码]

安全建议：

  • 使用一键安装脚本时，请妥善保管脚本生成的凭据
  • 首次登录后立即修改密码
  • 如果使用默认账户，必须在首次登录后修改邮箱和密码

配置反向代理（可选） ​

对于生产环境部署，建议使用 Nginx 或 Caddy 作为反向代理以启用 HTTPS。

Nginx 示例:

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

    location / {
        proxy_pass http://localhost: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;
    }
}

Caddy 示例:

your-domain.com {
    reverse_proxy localhost:8080
}

容器管理 ​

查看日志 ​

bash
# Docker Run
docker logs -f ppanel

# Docker Compose
docker compose logs -f

停止容器 ​

bash
# Docker Run
docker stop ppanel

# Docker Compose
docker compose stop

重启容器 ​

bash
# Docker Run
docker restart ppanel

# Docker Compose
docker compose restart

删除容器 ​

bash
# Docker Run
docker stop ppanel
docker rm ppanel

# Docker Compose
docker compose down

数据持久化

删除容器不会删除数据卷。如需同时删除数据卷，请使用：

bash
docker compose down -v

升级 ​

备份配置 ​

升级前，请先备份配置和数据：

bash
# 备份配置
tar czf ppanel-config-backup-$(date +%Y%m%d).tar.gz ppanel-config/

# 备份数据卷
docker run --rm \
  -v ppanel-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/ppanel-data-backup-$(date +%Y%m%d).tar.gz /data

升级步骤 ​

使用 Docker Run ​

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

# 停止并删除旧容器
docker stop ppanel
docker rm ppanel

# 使用相同配置启动新容器
docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -v $(pwd)/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  --restart unless-stopped \
  ppanel/ppanel-server:latest

使用 Docker Compose ​

bash
# 拉取最新镜像
docker compose pull

# 使用新镜像重新创建容器
docker compose up -d

验证升级 ​

bash
# 检查容器是否正在运行
docker ps | grep ppanel

# 检查日志是否有错误
docker logs ppanel

# 验证应用是否可访问
curl http://localhost:8080

故障排除 ​

容器立即退出 ​

检查架构兼容性:

bash
# 查看主机架构
uname -m

# 查看镜像架构
docker image inspect ppanel/ppanel-server:latest --format '{{.Architecture}}'

查看日志:

bash
docker logs ppanel

无法访问服务 ​

  1. 检查容器是否运行:

    bash
    docker ps | grep ppanel

  2. 检查端口映射:

    bash
    docker port ppanel

  3. 检查防火墙规则:

    bash
    # Ubuntu/Debian
sudo ufw status
sudo ufw allow 8080

# CentOS/RHEL
sudo firewall-cmd --list-ports
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload

配置未生效 ​

  1. 验证挂载路径:

    bash
    docker exec ppanel ls -la /app/etc

  2. 检查配置语法:

    bash
    docker exec ppanel cat /app/etc/ppanel.yaml

  3. 重启容器:

    bash
    docker restart ppanel

性能问题 ​

  1. 检查资源使用情况:

    bash
    docker stats ppanel

  2. 增加容器资源（如果使用 Docker Desktop）:

    • 打开 Docker Desktop 设置
    • 转到 Resources（资源）
    • 增加 CPU 和内存分配

  3. 检查磁盘空间:

    bash
    df -h
docker system df

高级配置 ​

使用环境变量 ​

你可以通过环境变量覆盖配置：

bash
docker run -d \
  --name ppanel \
  -p 8080:8080 \
  -e SERVER_PORT=8080 \
  -e DATABASE_TYPE=sqlite \
  -v $(pwd)/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  --restart unless-stopped \
  ppanel/ppanel-server:latest

运行多个实例 ​

要运行多个实例，请使用不同的端口和容器名称：

bash
# 实例 1
docker run -d \
  --name ppanel-1 \
  -p 8081:8080 \
  -v $(pwd)/ppanel-config-1:/app/etc:ro \
  -v ppanel-data-1:/app/data \
  ppanel/ppanel-server:latest

# 实例 2
docker run -d \
  --name ppanel-2 \
  -p 8082:8080 \
  -v $(pwd)/ppanel-config-2:/app/etc:ro \
  -v ppanel-data-2:/app/data \
  ppanel/ppanel-server:latest

自定义网络 ​

创建自定义 Docker 网络以获得更好的隔离：

bash
# 创建网络
docker network create ppanel-net

# 在自定义网络上运行容器
docker run -d \
  --name ppanel \
  --network ppanel-net \
  -p 8080:8080 \
  -v $(pwd)/ppanel-config:/app/etc:ro \
  -v ppanel-data:/app/data \
  ppanel/ppanel-server:latest

下一步 ​

需要帮助？ ​

如果遇到任何问题：

  1. 查看上面的故障排除部分
  2. 搜索 GitHub Issues
  3. 加入我们的社区讨论
  4. 创建新 issue 并附上详细的日志和系统信息
最近更新

Copyright © 2025 PPanel