📝 docs: Add documentation

This commit is contained in:
web@ppanel
2025-12-11 03:29:07 +00:00
parent 50e695a1bb
commit 99e7f6062d
135 changed files with 79115 additions and 8 deletions
+585
View File
@@ -0,0 +1,585 @@
# 二进制部署
本指南介绍如何使用预编译的二进制可执行文件部署 PPanel。此方法适合不想使用 Docker 或需要更多部署控制权的用户。
## 前置条件
- **操作系统**: Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
- **架构**: amd64 (x86_64) 或 arm64
- **权限**: Root 或 sudo 访问权限
- **依赖**: 无(二进制文件静态编译)
## 下载二进制文件
### 步骤 1: 检查系统架构
```bash
# 查看系统架构
uname -m
# 输出: x86_64 (amd64) 或 aarch64 (arm64)
```
### 步骤 2: 下载最新版本
访问 [GitHub Releases](https://github.com/perfect-panel/ppanel/releases) 页面或直接下载:
```bash
# 创建安装目录
sudo mkdir -p /opt/ppanel
cd /opt/ppanel
# 下载 Linux amd64 版本
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
# 或下载 Linux arm64 版本
# wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-arm64.tar.gz
# 解压
tar -xzf ppanel-linux-amd64.tar.gz
# 验证解压的文件
ls -la
```
预期的文件结构:
```
/opt/ppanel/
├── ppanel-server # 主服务器二进制文件
├── gateway # 网关二进制文件
└── etc/ # 配置目录
└── ppanel.yaml # 配置文件
```
## 配置
### 步骤 1: 准备配置
```bash
# 复制示例配置
sudo cp etc/ppanel.yaml etc/ppanel.yaml.backup
# 编辑配置
sudo nano etc/ppanel.yaml
```
**基础配置示例:**
```yaml
server:
host: 0.0.0.0
port: 8080
mode: release # debug, release, 或 test
database:
type: sqlite
path: /opt/ppanel/data/ppanel.db
# MySQL/PostgreSQL 配置:
# type: mysql
# host: localhost
# port: 3306
# user: ppanel
# password: your_password
# database: ppanel
log:
level: info # debug, info, warn, error
path: /opt/ppanel/logs
gateway:
port: 8080
timeout: 30s
```
### 步骤 2: 创建必要的目录
```bash
# 创建数据和日志目录
sudo mkdir -p /opt/ppanel/data
sudo mkdir -p /opt/ppanel/logs
# 设置适当的权限
sudo chmod 755 /opt/ppanel
sudo chmod 700 /opt/ppanel/data
sudo chmod 755 /opt/ppanel/logs
```
## 运行服务
### 方式一: 直接运行(测试用)
用于快速测试:
```bash
# 使二进制文件可执行
sudo chmod +x /opt/ppanel/ppanel-server
sudo chmod +x /opt/ppanel/gateway
# 直接运行服务器
cd /opt/ppanel
sudo ./ppanel-server
# 在另一个终端运行网关(如果分离)
# sudo ./gateway
```
`Ctrl+C` 停止。
### 方式二: Systemd 服务(推荐)
为生产环境部署创建 systemd 服务:
#### 步骤 1: 创建服务文件
```bash
sudo nano /etc/systemd/system/ppanel.service
```
**服务文件内容:**
```ini
[Unit]
Description=PPanel Server
Documentation=https://github.com/perfect-panel/ppanel
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/ppanel
ExecStart=/opt/ppanel/ppanel-server
Restart=always
RestartSec=10
# 安全设置
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/ppanel/data /opt/ppanel/logs
# 资源限制
LimitNOFILE=65535
LimitNPROC=4096
# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ppanel
[Install]
WantedBy=multi-user.target
```
#### 步骤 2: 启用并启动服务
```bash
# 重新加载 systemd
sudo systemctl daemon-reload
# 启用服务(开机自启)
sudo systemctl enable ppanel
# 启动服务
sudo systemctl start ppanel
# 检查状态
sudo systemctl status ppanel
```
## 服务管理
### 检查状态
```bash
# 检查服务是否运行
sudo systemctl status ppanel
# 查看详细状态
sudo systemctl show ppanel
```
### 查看日志
```bash
# 查看 systemd 日志
sudo journalctl -u ppanel -f
# 查看最后 100 行
sudo journalctl -u ppanel -n 100
# 查看应用日志
sudo tail -f /opt/ppanel/logs/ppanel.log
```
### 启动/停止/重启
```bash
# 启动服务
sudo systemctl start ppanel
# 停止服务
sudo systemctl stop ppanel
# 重启服务
sudo systemctl restart ppanel
# 重新加载配置(如果支持)
sudo systemctl reload ppanel
```
### 启用/禁用自动启动
```bash
# 启用开机自启
sudo systemctl enable ppanel
# 禁用自动启动
sudo systemctl disable ppanel
# 检查是否已启用
sudo systemctl is-enabled ppanel
```
## 部署后配置
### 验证安装
```bash
# 检查服务是否监听端口
sudo netstat -tlnp | grep 8080
# 或使用 ss
sudo ss -tlnp | grep 8080
# 测试 HTTP 访问
curl http://localhost:8080
# 检查进程
ps aux | grep ppanel
```
### 访问应用
- **用户面板**: `http://your-server-ip:8080`
- **管理后台**: `http://your-server-ip:8080/admin`
### 配置防火墙
```bash
# Ubuntu/Debian (UFW)
sudo ufw allow 8080/tcp
sudo ufw status
# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports
```
### 设置反向代理
生产环境建议使用 Nginx 或 Caddy 作为反向代理:
**Nginx 配置** (`/etc/nginx/sites-available/ppanel`):
```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;
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
启用配置:
```bash
sudo ln -s /etc/nginx/sites-available/ppanel /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
## 升级
### 升级前备份
```bash
# 停止服务
sudo systemctl stop ppanel
# 备份当前版本
sudo cp -r /opt/ppanel /opt/ppanel-backup-$(date +%Y%m%d)
# 备份数据库
sudo cp /opt/ppanel/data/ppanel.db /opt/ppanel/data/ppanel.db.backup-$(date +%Y%m%d)
# 备份配置
sudo cp /opt/ppanel/etc/ppanel.yaml /opt/ppanel/etc/ppanel.yaml.backup-$(date +%Y%m%d)
```
### 下载并安装新版本
```bash
# 下载新版本
cd /tmp
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
# 解压到临时位置
mkdir ppanel-new
tar -xzf ppanel-linux-amd64.tar.gz -C ppanel-new
# 备份旧的二进制文件
sudo mv /opt/ppanel/ppanel-server /opt/ppanel/ppanel-server.old
sudo mv /opt/ppanel/gateway /opt/ppanel/gateway.old
# 安装新的二进制文件
sudo cp ppanel-new/ppanel-server /opt/ppanel/
sudo cp ppanel-new/gateway /opt/ppanel/
# 设置权限
sudo chmod +x /opt/ppanel/ppanel-server
sudo chmod +x /opt/ppanel/gateway
# 启动服务
sudo systemctl start ppanel
# 检查状态
sudo systemctl status ppanel
```
### 回滚
如果升级失败:
```bash
# 停止服务
sudo systemctl stop ppanel
# 恢复旧的二进制文件
sudo mv /opt/ppanel/ppanel-server.old /opt/ppanel/ppanel-server
sudo mv /opt/ppanel/gateway.old /opt/ppanel/gateway
# 恢复数据库(如需要)
sudo cp /opt/ppanel/data/ppanel.db.backup-YYYYMMDD /opt/ppanel/data/ppanel.db
# 启动服务
sudo systemctl start ppanel
```
## 故障排除
### 服务启动失败
```bash
# 查看详细日志
sudo journalctl -u ppanel -xe
# 检查配置语法
/opt/ppanel/ppanel-server --check-config
# 验证权限
ls -la /opt/ppanel
sudo chown -R root:root /opt/ppanel
```
### 端口被占用
```bash
# 查找占用端口的进程
sudo lsof -i :8080
sudo netstat -tlnp | grep 8080
# 在配置中更改端口
sudo nano /opt/ppanel/etc/ppanel.yaml
# 更新 server.port 值
# 重启服务
sudo systemctl restart ppanel
```
### 二进制文件无法执行
```bash
# 检查架构兼容性
uname -m
file /opt/ppanel/ppanel-server
# 检查是否可执行
ls -la /opt/ppanel/ppanel-server
sudo chmod +x /opt/ppanel/ppanel-server
# 检查缺失的库(静态编译应该没有)
ldd /opt/ppanel/ppanel-server
```
### 内存使用过高
```bash
# 检查内存使用
ps aux | grep ppanel
top -p $(pgrep ppanel-server)
# 在 systemd 服务中添加内存限制
sudo nano /etc/systemd/system/ppanel.service
# 在 [Service] 下添加:
# MemoryMax=2G
# MemoryHigh=1.5G
sudo systemctl daemon-reload
sudo systemctl restart ppanel
```
### 数据库连接问题
```bash
# 检查数据库文件权限
ls -la /opt/ppanel/data/
# 对于 SQLite,验证配置中的路径
sudo nano /opt/ppanel/etc/ppanel.yaml
# 测试数据库连接
sqlite3 /opt/ppanel/data/ppanel.db "SELECT 1;"
# 检查日志中的数据库错误
sudo journalctl -u ppanel | grep -i database
```
## 卸载
完全移除 PPanel
```bash
# 停止并禁用服务
sudo systemctl stop ppanel
sudo systemctl disable ppanel
# 删除服务文件
sudo rm /etc/systemd/system/ppanel.service
sudo systemctl daemon-reload
# 删除安装目录
sudo rm -rf /opt/ppanel
# 删除防火墙规则(如果添加过)
sudo ufw delete allow 8080/tcp
# 或
sudo firewall-cmd --permanent --remove-port=8080/tcp
sudo firewall-cmd --reload
```
## 高级配置
### 以非 Root 用户运行
为了更好的安全性,使用专用用户运行:
```bash
# 创建专用用户
sudo useradd -r -s /bin/false ppanel
# 更改所有权
sudo chown -R ppanel:ppanel /opt/ppanel
# 更新 systemd 服务
sudo nano /etc/systemd/system/ppanel.service
# 更改: User=ppanel
# 如果绑定到端口 < 1024,授予能力
sudo setcap 'cap_net_bind_service=+ep' /opt/ppanel/ppanel-server
sudo systemctl daemon-reload
sudo systemctl restart ppanel
```
### 多实例部署
运行多个实例:
```bash
# 创建独立目录
sudo mkdir -p /opt/ppanel-1
sudo mkdir -p /opt/ppanel-2
# 复制二进制文件和配置
sudo cp -r /opt/ppanel/* /opt/ppanel-1/
sudo cp -r /opt/ppanel/* /opt/ppanel-2/
# 编辑配置使用不同端口
sudo nano /opt/ppanel-1/etc/ppanel.yaml # port: 8081
sudo nano /opt/ppanel-2/etc/ppanel.yaml # port: 8082
# 创建独立的 systemd 服务
sudo cp /etc/systemd/system/ppanel.service /etc/systemd/system/ppanel-1.service
sudo cp /etc/systemd/system/ppanel.service /etc/systemd/system/ppanel-2.service
# 相应编辑服务文件
sudo systemctl daemon-reload
sudo systemctl enable ppanel-1 ppanel-2
sudo systemctl start ppanel-1 ppanel-2
```
### 自定义环境变量
在 systemd 服务中添加环境变量:
```ini
[Service]
Environment="PPANEL_ENV=production"
Environment="PPANEL_DEBUG=false"
EnvironmentFile=/opt/ppanel/env.conf
```
## 性能调优
### 优化文件限制
```bash
# 编辑限制
sudo nano /etc/security/limits.conf
# 添加:
* soft nofile 65535
* hard nofile 65535
# systemd 服务中已设置:
# LimitNOFILE=65535
```
### 启用数据库优化
对于 SQLite
```bash
# 在 ppanel.yaml 中添加
database:
type: sqlite
path: /opt/ppanel/data/ppanel.db
options:
cache_size: -2000
journal_mode: WAL
synchronous: NORMAL
```
## 下一步
- [配置指南](/zh/guide/configuration) - 详细的配置选项
- [管理后台](/zh/admin/dashboard) - 开始管理你的面板
- [API 参考](/zh/api/reference) - API 集成
## 需要帮助?
- 查看 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
- 查看 systemd 日志: `sudo journalctl -u ppanel -f`
- 查看应用日志: `tail -f /opt/ppanel/logs/ppanel.log`
@@ -0,0 +1,443 @@
# Docker Compose 部署
Docker Compose 是生产环境推荐的部署方式。它提供更好的服务管理、更简单的配置和更便捷的升级流程。
## 前置条件
### 安装 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
```
## 部署步骤
### 步骤 1: 创建项目目录
```bash
# 创建项目目录
mkdir -p ~/ppanel
cd ~/ppanel
```
### 步骤 2: 创建 docker-compose.yml
创建 `docker-compose.yml` 文件,内容如下:
```yaml
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
```
**配置说明:**
- **image**: 使用的 Docker 镜像(latest 或指定版本如 `v0.1.2`
- **ports**: 将容器的 8080 端口映射到宿主机的 8080 端口
- **volumes**:
- `./ppanel-config:/app/etc:ro` - 配置目录(只读)
- `ppanel-data:/app/data` - 持久化数据存储
- **restart**: 自动重启策略
- **environment**: 设置时区(可改为 `Asia/Shanghai` 等)
- **healthcheck**: 服务健康检查
### 步骤 3: 准备配置
```bash
# 创建配置目录
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 提示
详细的配置选项请参考 [配置指南](/zh/guide/configuration)。
:::
### 步骤 4: 启动服务
```bash
# 拉取最新镜像
docker compose pull
# 以守护进程模式启动
docker compose up -d
# 查看日志
docker compose logs -f
```
### 步骤 5: 验证部署
```bash
# 查看服务状态
docker compose ps
# 测试服务是否可访问
curl http://localhost:8080
# 查看实时日志
docker compose logs -f ppanel
```
## 部署后配置
### 访问应用
安装成功后,你可以通过以下地址访问:
- **用户面板**: `http://your-server-ip:8080`
- **管理后台**: `http://your-server-ip:8080/admin`
::: warning 默认凭据
为了安全起见,首次登录后请立即修改默认管理员密码。
:::
### 配置反向代理(推荐)
对于生产环境部署,建议使用 Nginx 或 Caddy 作为反向代理以启用 HTTPS。
**Nginx 配置:**
```nginx
server {
listen 80;
server_name your-domain.com;
# 重定向到 HTTPS
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/private.key;
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;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
}
}
```
**Caddy 配置:**
```
your-domain.com {
reverse_proxy localhost:8080
}
```
::: tip 提示
Caddy 会通过 Let's Encrypt 自动处理 SSL 证书。
:::
## 服务管理
### 查看日志
```bash
# 查看所有日志
docker compose logs
# 实时跟踪日志
docker compose logs -f
# 查看特定服务日志
docker compose logs ppanel
```
### 停止服务
```bash
# 停止所有服务
docker compose stop
# 停止特定服务
docker compose stop ppanel
```
### 重启服务
```bash
# 重启所有服务
docker compose restart
# 重启特定服务
docker compose restart ppanel
```
### 停止并删除服务
```bash
# 停止并删除容器
docker compose down
# 停止并删除容器和数据卷
docker compose down -v
```
::: warning 数据持久化
使用 `docker compose down -v` 会删除所有数据卷。只有在想完全清除所有数据时才使用此命令。
:::
## 升级
### 升级前备份
```bash
# 备份配置
tar czf ppanel-config-backup-$(date +%Y%m%d).tar.gz ppanel-config/
# 备份数据卷
docker run --rm \
-v ppanel_ppanel-data:/data \
-v $(pwd):/backup \
alpine tar czf /backup/ppanel-data-backup-$(date +%Y%m%d).tar.gz /data
```
### 升级步骤
```bash
# 拉取最新镜像
docker compose pull
# 使用新镜像重新创建容器
docker compose up -d
# 查看日志验证
docker compose logs -f
```
### 回滚
如果升级后遇到问题:
```bash
# 编辑 docker-compose.yml,将镜像改为之前的版本
# image: ppanel/ppanel:v0.1.1
# 使用之前的版本重启
docker compose up -d
```
## 高级配置
### 自定义端口
要使用不同的端口,编辑 `docker-compose.yml`
```yaml
ports:
- "3000:8080" # 宿主机端口 3000 -> 容器端口 8080
```
### 多实例部署
要运行多个实例,创建独立的目录:
```bash
# 实例 1
mkdir ~/ppanel-1
cd ~/ppanel-1
# 创建 docker-compose.yml,使用端口 8081
# 实例 2
mkdir ~/ppanel-2
cd ~/ppanel-2
# 创建 docker-compose.yml,使用端口 8082
```
### 资源限制
添加资源限制以防止过度消耗:
```yaml
services:
ppanel:
# ... 其他配置 ...
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '0.5'
memory: 512M
```
### 自定义网络
创建自定义网络以获得更好的隔离:
```yaml
version: '3.8'
services:
ppanel:
# ... 其他配置 ...
networks:
- ppanel-net
networks:
ppanel-net:
driver: bridge
```
## 故障排除
### 容器启动失败
```bash
# 查看错误日志
docker compose logs ppanel
# 检查容器状态
docker compose ps
# 验证配置
docker compose config
```
### 端口被占用
```bash
# 检查什么在使用该端口
sudo lsof -i :8080
# 在 docker-compose.yml 中更改端口
# ports:
# - "8081:8080"
```
### 权限问题
```bash
# 修复配置目录权限
sudo chown -R $USER:$USER ppanel-config/
# 确保文件可读
chmod 644 ppanel-config/ppanel.yaml
```
### 无法从外部访问
1. **检查防火墙规则:**
```bash
# Ubuntu/Debian
sudo ufw allow 8080
# CentOS/RHEL
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
```
2. **验证服务是否监听:**
```bash
docker compose ps
netstat -tlnp | grep 8080
```
## 下一步
- [配置指南](/zh/guide/configuration) - 详细的配置选项
- [管理后台](/zh/admin/dashboard) - 开始管理你的面板
- [API 参考](/zh/api/reference) - API 集成指南
## 需要帮助?
如果遇到任何问题:
1. 查看上面的[故障排除](#故障排除)部分
2. 查看 [Docker Compose 日志](#查看日志)
3. 搜索 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
4. 创建新 issue 并附上详细的系统信息和日志
+348
View File
@@ -0,0 +1,348 @@
# Docker Run 部署
本指南介绍如何使用 `docker run` 命令部署 PPanel。此方法适合快速测试或简单部署。
::: tip 提示
对于生产环境,我们推荐使用 [Docker Compose](/zh/guide/installation/docker-compose)。
:::
## 前置条件
### 安装 Docker
**Ubuntu/Debian:**
```bash
# 更新包索引
sudo apt-get update
# 安装 Docker
sudo apt-get install -y ca-certificates curl gnupg lsb-release
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
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
```
**CentOS/RHEL:**
```bash
# 安装 Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
# 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker
```
### 验证安装
```bash
docker --version
sudo docker run hello-world
```
## 快速开始
### 步骤 1: 拉取镜像
```bash
# 拉取最新版本
docker pull ppanel/ppanel:latest
# 或拉取指定版本
docker pull ppanel/ppanel:v0.1.2
```
### 步骤 2: 准备配置
```bash
# 创建配置目录
mkdir -p ~/ppanel-config
# 创建配置文件
cat > ~/ppanel-config/ppanel.yaml <<EOF
server:
host: 0.0.0.0
port: 8080
database:
type: sqlite
path: /app/data/ppanel.db
EOF
```
### 步骤 3: 运行容器
**基础命令:**
```bash
docker run -d \
--name ppanel \
-p 8080:8080 \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
--restart unless-stopped \
ppanel/ppanel:latest
```
**完整参数命令:**
```bash
docker run -d \
--name ppanel \
-p 8080:8080 \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
-e TZ=Asia/Shanghai \
--restart unless-stopped \
--memory="2g" \
--cpus="2" \
ppanel/ppanel:latest
```
**参数说明:**
- `-d`: 以守护进程模式运行(后台运行)
- `--name ppanel`: 设置容器名称
- `-p 8080:8080`: 端口映射(宿主机:容器)
- `-v ~/ppanel-config:/app/etc:ro`: 挂载配置(只读)
- `-v ppanel-data:/app/data`: 创建数据卷
- `-e TZ=Asia/Shanghai`: 设置时区
- `--restart unless-stopped`: 自动重启策略
- `--memory="2g"`: 内存限制
- `--cpus="2"`: CPU 限制
### 步骤 4: 验证运行
```bash
# 查看容器状态
docker ps | grep ppanel
# 查看日志
docker logs -f ppanel
# 测试访问
curl http://localhost:8080
```
## 容器管理
### 查看日志
```bash
# 查看所有日志
docker logs ppanel
# 实时跟踪日志
docker logs -f ppanel
# 查看最后 100 行
docker logs --tail 100 ppanel
# 显示时间戳
docker logs -t ppanel
```
### 停止容器
```bash
docker stop ppanel
```
### 启动容器
```bash
docker start ppanel
```
### 重启容器
```bash
docker restart ppanel
```
### 删除容器
```bash
# 停止并删除
docker stop ppanel
docker rm ppanel
```
::: warning 注意
删除容器不会删除数据卷。要删除数据卷:
```bash
docker volume rm ppanel-data
```
:::
## 升级
### 备份数据
```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
```
### 升级流程
```bash
# 拉取最新镜像
docker pull ppanel/ppanel:latest
# 停止旧容器
docker stop ppanel
# 删除旧容器
docker rm ppanel
# 使用相同配置启动新容器
docker run -d \
--name ppanel \
-p 8080:8080 \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
--restart unless-stopped \
ppanel/ppanel:latest
# 验证
docker logs -f ppanel
```
## 高级用法
### 自定义网络
```bash
# 创建网络
docker network create ppanel-net
# 在自定义网络上运行
docker run -d \
--name ppanel \
--network ppanel-net \
-p 8080:8080 \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
ppanel/ppanel:latest
```
### 环境变量
```bash
docker run -d \
--name ppanel \
-p 8080:8080 \
-e SERVER_PORT=8080 \
-e DATABASE_TYPE=sqlite \
-e TZ=Asia/Shanghai \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
ppanel/ppanel:latest
```
### 多实例部署
```bash
# 实例 1 使用端口 8081
docker run -d \
--name ppanel-1 \
-p 8081:8080 \
-v ~/ppanel-config-1:/app/etc:ro \
-v ppanel-data-1:/app/data \
ppanel/ppanel:latest
# 实例 2 使用端口 8082
docker run -d \
--name ppanel-2 \
-p 8082:8080 \
-v ~/ppanel-config-2:/app/etc:ro \
-v ppanel-data-2:/app/data \
ppanel/ppanel:latest
```
### 资源限制
```bash
docker run -d \
--name ppanel \
-p 8080:8080 \
--memory="2g" \
--memory-swap="2g" \
--cpus="2" \
--pids-limit=100 \
-v ~/ppanel-config:/app/etc:ro \
-v ppanel-data:/app/data \
ppanel/ppanel:latest
```
## 故障排除
### 容器立即退出
```bash
# 查看日志
docker logs ppanel
# 检查架构
uname -m
docker image inspect ppanel/ppanel:latest --format '{{.Architecture}}'
```
### 端口被占用
```bash
# 检查什么在使用该端口
sudo lsof -i :8080
# 使用不同端口
docker run -d --name ppanel -p 8081:8080 ...
```
### 配置未加载
```bash
# 验证挂载
docker exec ppanel ls -la /app/etc
# 查看文件内容
docker exec ppanel cat /app/etc/ppanel.yaml
# 检查权限
ls -la ~/ppanel-config/
```
### 进入容器 Shell
```bash
# 进入 bash(如果可用)
docker exec -it ppanel bash
# 进入 sh
docker exec -it ppanel sh
# 运行命令
docker exec ppanel ls -la /app
```
## 下一步
- 尝试 [Docker Compose](/zh/guide/installation/docker-compose) 以获得更简单的管理方式
- 配置[反向代理](/zh/guide/installation/docker-compose#配置反向代理)
- 了解[配置选项](/zh/guide/configuration)
## 需要帮助?
- 查看 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
- 查看 Docker 日志: `docker logs ppanel`
- 验证系统要求
+57
View File
@@ -0,0 +1,57 @@
# 安装概览
PPanel 支持多种部署方式,以适应不同的需求和环境。选择最适合你需求的部署方式。
## 部署方式
### Docker 部署(推荐)
最简单、最可靠的部署方式。Docker 确保环境一致性并简化更新流程。
- **[Docker Run](/zh/guide/installation/docker-run)** - 单命令快速部署
- **[Docker Compose](/zh/guide/installation/docker-compose)** - 生产环境推荐,更好的管理方式
### 传统部署
- **[二进制部署](/zh/guide/installation/binary)** - 使用预编译二进制文件和 systemd 服务部署
### 高级部署
- **[Kubernetes](/zh/guide/installation/kubernetes)** - 在 Kubernetes 集群中部署 PPanel 以实现高可用
- **[源码部署](/zh/guide/installation/from-source)** - 从源码构建并运行 PPanel
## 系统要求
### 最低配置
- **操作系统**: Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+)
- **CPU**: 1 核心
- **内存**: 512MB RAM
- **存储**: 1GB 可用磁盘空间
### 推荐配置
- **CPU**: 2+ 核心
- **内存**: 2GB+ RAM
- **存储**: 5GB+ 可用磁盘空间
## 前置条件
所有部署方式都需要:
- 基于 Linux 的操作系统
- 基本的命令行知识
- 网络访问以下载软件包/镜像
具体的前置条件因部署方式而异 - 请查看各个指南了解详情。
## 快速开始
对于大多数用户,我们推荐从 Docker Compose 开始:
1. [安装 Docker 和 Docker Compose](/zh/guide/installation/docker-compose#前置条件)
2. [下载配置文件](/zh/guide/installation/docker-compose#下载配置)
3. [启动服务](/zh/guide/installation/docker-compose#启动服务)
## 需要帮助?
- 查看我们的[故障排除指南](/zh/guide/troubleshooting)
- 访问 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
- 加入我们的社区讨论