web@ppanel 7279275532 📝 docs: Update default administrator account information and security recommendations in installation guides

2025-12-28 07:05:21 +00:00

9.8 KiB

Raw Blame History

安装部署

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

系统要求

最低配置

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

前置条件

安装 Docker

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

Ubuntu/Debian:

# 更新包索引
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:

# 安装 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

验证安装

# 查看 Docker 版本
docker --version

# 查看 Docker Compose 版本
docker compose version

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

快速开始

方式一：使用 Docker Run

步骤 1: 拉取镜像

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

# 或拉取指定版本
docker pull ppanel/ppanel:v0.1.2

步骤 2: 准备配置

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

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

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

database:
  type: sqlite
  path: /app/data/ppanel.db

# 根据需要添加更多配置
EOF

::: tip 提示详细的配置选项请参考配置指南。 :::

步骤 3: 运行容器

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: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: 验证运行状态

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

# 查看日志
docker logs -f ppanel

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

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

步骤 1: 创建 docker-compose.yml

version: '3.8'

services:
  ppanel:
    image: ppanel/ppanel:latest
    container_name: ppanel
    ports:
      - "8080:8080"
    volumes:
      - ./ppanel-config:/app/etc:ro
      - ppanel-data:/app/data
    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:
  ppanel-data:
    driver: local

步骤 2: 准备配置

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

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

步骤 3: 启动服务

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

# 查看日志
docker compose logs -f

# 查看状态
docker compose ps

部署后配置

访问应用

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

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

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

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

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

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

安全建议：

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

配置反向代理（可选）

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

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
}

容器管理

查看日志

# Docker Run
docker logs -f ppanel

# Docker Compose
docker compose logs -f

停止容器

# Docker Run
docker stop ppanel

# Docker Compose
docker compose stop

重启容器

# Docker Run
docker restart ppanel

# Docker Compose
docker compose restart

删除容器

# Docker Run
docker stop ppanel
docker rm ppanel

# Docker Compose
docker compose down

::: warning 数据持久化删除容器不会删除数据卷。如需同时删除数据卷，请使用：

docker compose down -v

:::

升级

备份配置

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

# 备份配置
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

# 拉取最新镜像
docker pull ppanel/ppanel: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:latest

使用 Docker Compose

# 拉取最新镜像
docker compose pull

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

验证升级

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

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

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

故障排除

容器立即退出

检查架构兼容性:

# 查看主机架构
uname -m

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

查看日志:

docker logs ppanel

无法访问服务

检查容器是否运行:
```
docker ps | grep ppanel
```
检查端口映射:
```
docker port ppanel
```

检查防火墙规则:

# 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

配置未生效

验证挂载路径:
```
docker exec ppanel ls -la /app/etc
```

检查配置语法:

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

重启容器:
```
docker restart ppanel
```

性能问题

检查资源使用情况:
```
docker stats ppanel
```
增加容器资源（如果使用 Docker Desktop）:
- 打开 Docker Desktop 设置
- 转到 Resources（资源）
- 增加 CPU 和内存分配
检查磁盘空间:
```
df -h
docker system df
```

高级配置

使用环境变量

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

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:latest

运行多个实例

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

# 实例 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: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:latest

自定义网络

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

# 创建网络
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:latest

下一步

配置指南 - 了解详细的配置选项
管理后台 - 开始管理你的面板
API 参考 - 集成 PPanel API

需要帮助？

如果遇到任何问题：

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

9.8 KiB Raw Blame History Unescape Escape

安装部署

系统要求

最低配置

推荐配置

前置条件

安装 Docker

验证安装

快速开始

方式一：使用 Docker Run

步骤 1: 拉取镜像

步骤 2: 准备配置

步骤 3: 运行容器

步骤 4: 验证运行状态

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

步骤 1: 创建 docker-compose.yml

步骤 2: 准备配置

步骤 3: 启动服务

部署后配置

访问应用

配置反向代理（可选）

容器管理

查看日志

停止容器

重启容器

删除容器

升级

备份配置

升级步骤

使用 Docker Run

使用 Docker Compose

验证升级

故障排除

容器立即退出

无法访问服务

配置未生效

性能问题

高级配置

使用环境变量

运行多个实例

自定义网络

下一步

需要帮助？

9.8 KiB

Raw Blame History