docs: Add one-click installation script for PPanel with Docker support

- Introduced `install-ppanel.sh` script for automated installation of PPanel using Docker Compose. - Updated installation documentation to include one-click deployment options and detailed configuration steps. - Enhanced configuration files for MySQL and Redis with necessary parameters. - Improved Docker Compose setup with health checks and custom network configurations. - Added instructions for firewall configuration and reverse proxy setup for production environments. - Included troubleshooting tips and advanced options for non-interactive installations and proxy environments.
2025-12-27 11:38:50 +00:00
parent 62d45bbac1
commit 912c5c4cb6
16 changed files with 2466 additions and 564 deletions
@@ -23,19 +23,29 @@ uname -m

 访问 [GitHub Releases](https://github.com/perfect-panel/ppanel/releases) 页面或直接下载：

+::: tip 安装目录
+你可以将 PPanel 安装在任意目录，本文档使用 `/opt/ppanel` 作为示例。如果选择其他目录，请相应调整后续命令中的路径。
+:::
+
 ```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
+wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-linux-amd64.tar.gz

 # 或下载 Linux arm64 版本
-# wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-arm64.tar.gz
+# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-linux-arm64.tar.gz
+
+# 或下载 macOS amd64 版本
+# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-darwin-amd64.tar.gz
+
+# 或下载 macOS arm64 版本 (Apple Silicon)
+# wget https://github.com/perfect-panel/ppanel/releases/latest/download/gateway-darwin-arm64.tar.gz

 # 解压
-tar -xzf ppanel-linux-amd64.tar.gz
+tar -xzf gateway-linux-amd64.tar.gz

 # 验证解压的文件
 ls -la
@@ -44,8 +54,7 @@ ls -la
 预期的文件结构：
 ```
 /opt/ppanel/
-├── ppanel-server    # 主服务器二进制文件
-├── gateway          # 网关二进制文件
+├── gateway          # 网关可执行文件
 └── etc/             # 配置目录
    └── ppanel.yaml  # 配置文件
 ```
@@ -55,52 +64,92 @@ ls -la
 ### 步骤 1: 准备配置

 ```bash
-# 复制示例配置
-sudo cp etc/ppanel.yaml etc/ppanel.yaml.backup
-
 # 编辑配置
-sudo nano etc/ppanel.yaml
+sudo nano /opt/ppanel/etc/ppanel.yaml
 ```

-**基础配置示例:**
+**配置示例:**
+
+::: tip 相对路径
+配置中的路径（如 `Path`、`logs` 等）支持相对路径。相对路径是相对于程序工作目录（WorkingDirectory）的，在 systemd 服务中即 `/opt/ppanel`。
+:::

 ```yaml
-server:
-  host: 0.0.0.0
-  port: 8080
-  mode: release  # debug, release, 或 test
+Host: 0.0.0.0
+Port: 8080
+TLS:
+    Enable: false
+    CertFile: ""
+    KeyFile: ""
+Debug: false

-database:
-  type: sqlite
-  path: /opt/ppanel/data/ppanel.db
-  # MySQL/PostgreSQL 配置:
-  # type: mysql
-  # host: localhost
-  # port: 3306
-  # user: ppanel
-  # password: your_password
-  # database: ppanel
+Static:
+  Admin:
+    Enabled: true
+    Prefix: /admin
+    Path: ./static/admin
+  User:
+    Enabled: true
+    Prefix: /
+    Path: ./static/user

-log:
-  level: info  # debug, info, warn, error
-  path: /opt/ppanel/logs
+JwtAuth:
+    AccessSecret: your-secret-key-change-this
+    AccessExpire: 604800

-gateway:
-  port: 8080
-  timeout: 30s
+Logger:
+    ServiceName: ApiService
+    Mode: console
+    Encoding: plain
+    TimeFormat: "2006-01-02 15:04:05.000"
+    Path: logs
+    Level: info
+    MaxContentLength: 0
+    Compress: false
+    Stat: true
+    KeepDays: 0
+    StackCooldownMillis: 100
+    MaxBackups: 0
+    MaxSize: 0
+    Rotation: daily
+    FileTimeFormat: 2006-01-02T15:04:05.000Z07:00
+
+MySQL:
+    Addr: localhost:3306
+    Username: your-username
+    Password: your-password
+    Dbname: ppanel
+    Config: charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+    MaxIdleConns: 10
+    MaxOpenConns: 10
+    SlowThreshold: 1000
+
+Redis:
+    Host: localhost:6379
+    Pass: your-redis-password
+    DB: 0
 ```

+::: warning 必需配置
+**MySQL 和 Redis 是必需的。** 部署前请配置以下项：
+- `JwtAuth.AccessSecret` - 使用强随机密钥（必需）
+- `MySQL.*` - 配置你的 MySQL 数据库连接（必需）
+- `Redis.*` - 配置你的 Redis 连接（必需）
+:::
+
 ### 步骤 2: 创建必要的目录

 ```bash
 # 创建数据和日志目录
 sudo mkdir -p /opt/ppanel/data
 sudo mkdir -p /opt/ppanel/logs
+sudo mkdir -p /opt/ppanel/static

 # 设置适当的权限
 sudo chmod 755 /opt/ppanel
 sudo chmod 700 /opt/ppanel/data
 sudo chmod 755 /opt/ppanel/logs
+sudo chmod 755 /opt/ppanel/static
 ```

 ## 运行服务
@@ -111,15 +160,11 @@ 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
+sudo ./gateway
 ```

 按 `Ctrl+C` 停止。
@@ -147,7 +192,7 @@ Wants=network-online.target
 Type=simple
 User=root
 WorkingDirectory=/opt/ppanel
-ExecStart=/opt/ppanel/ppanel-server
+ExecStart=/opt/ppanel/gateway
 Restart=always
 RestartSec=10

@@ -262,7 +307,7 @@ ps aux | grep ppanel
 ### 访问应用

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

 ### 配置防火墙

@@ -312,70 +357,11 @@ sudo systemctl reload nginx

 ## 升级

-### 升级前备份
+直接从**管理后台**主页升级 PPanel。在仪表盘主页可以检查新版本并一键升级。

-```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
-```
+::: tip 提示
+系统会自动处理升级过程，包括下载新的二进制文件和重启服务。
+:::

 ## 故障排除

@@ -413,14 +399,14 @@ sudo systemctl restart ppanel
 ```bash
 # 检查架构兼容性
 uname -m
-file /opt/ppanel/ppanel-server
+file /opt/ppanel/gateway

 # 检查是否可执行
-ls -la /opt/ppanel/ppanel-server
-sudo chmod +x /opt/ppanel/ppanel-server
+ls -la /opt/ppanel/gateway
+sudo chmod +x /opt/ppanel/gateway

 # 检查缺失的库（静态编译应该没有）
-ldd /opt/ppanel/ppanel-server
+ldd /opt/ppanel/gateway
 ```

 ### 内存使用过高
@@ -497,7 +483,7 @@ sudo nano /etc/systemd/system/ppanel.service
 # 更改: User=ppanel

 # 如果绑定到端口 < 1024，授予能力
-sudo setcap 'cap_net_bind_service=+ep' /opt/ppanel/ppanel-server
+sudo setcap 'cap_net_bind_service=+ep' /opt/ppanel/gateway

 sudo systemctl daemon-reload
 sudo systemctl restart ppanel
@@ -77,17 +77,17 @@ cd ~/ppanel
 version: '3.8'

 services:
-  ppanel:
+  ppanel-service:
    image: ppanel/ppanel:latest
-    container_name: ppanel
+    container_name: ppanel-service
+    restart: always
    ports:
      - "8080:8080"
    volumes:
-      - ./ppanel-config:/app/etc:ro
-      - ppanel-data:/app/data
-    restart: unless-stopped
-    environment:
-      - TZ=Asia/Shanghai
+      - ./config:/app/etc:ro
+      - ./web:/app/static
+    networks:
+      - ppanel-net
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
      interval: 30s
@@ -95,45 +95,92 @@ services:
      retries: 3
      start_period: 40s

-volumes:
-  ppanel-data:
-    driver: local
+networks:
+  ppanel-net:
+    driver: bridge
 ```

 **配置说明:**

 - **image**: 使用的 Docker 镜像（latest 或指定版本如 `v0.1.2`）
- **ports**: 将容器的 8080 端口映射到宿主机的 8080 端口
+- **container_name**: 设置自定义容器名称
+- **ports**: 将容器的 8080 端口映射到宿主机的 8080 端口（可根据需要修改宿主机端口）
 - **volumes**:
-  - `./ppanel-config:/app/etc:ro` - 配置目录（只读）
-  - `ppanel-data:/app/data` - 持久化数据存储
- **restart**: 自动重启策略
- **environment**: 设置时区（可改为 `Asia/Shanghai` 等）
+  - `./config:/app/etc:ro` - 配置目录（只读）
+  - `./web:/app/static` - 静态文件目录（管理后台和用户前端）
+- **networks**: 创建自定义网络以实现服务隔离
+- **restart**: 自动重启策略（always 表示总是重启）
 - **healthcheck**: 服务健康检查

 ### 步骤 3: 准备配置

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

 # 创建配置文件
-cat > ppanel-config/ppanel.yaml <<EOF
-# PPanel 配置文件
-server:
-  host: 0.0.0.0
-  port: 8080
+cat > config/ppanel.yaml <<EOF
+Host: 0.0.0.0
+Port: 8080
+TLS:
+    Enable: false
+    CertFile: ""
+    KeyFile: ""
+Debug: false

-database:
-  type: sqlite
-  path: /app/data/ppanel.db
+Static:
+  Admin:
+    Enabled: true
+    Prefix: /admin
+    Path: ./static/admin
+  User:
+    Enabled: true
+    Prefix: /
+    Path: ./static/user

-# 根据需要添加更多配置
+JwtAuth:
+    AccessSecret: your-secret-key-change-this
+    AccessExpire: 604800
+
+Logger:
+    ServiceName: ApiService
+    Mode: console
+    Encoding: plain
+    TimeFormat: "2006-01-02 15:04:05.000"
+    Path: logs
+    Level: info
+    MaxContentLength: 0
+    Compress: false
+    Stat: true
+    KeepDays: 0
+    StackCooldownMillis: 100
+    MaxBackups: 0
+    MaxSize: 0
+    Rotation: daily
+    FileTimeFormat: 2006-01-02T15:04:05.000Z07:00
+
+MySQL:
+    Addr: localhost:3306
+    Username: your-username
+    Password: your-password
+    Dbname: ppanel
+    Config: charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+    MaxIdleConns: 10
+    MaxOpenConns: 10
+    SlowThreshold: 1000
+
+Redis:
+    Host: localhost:6379
+    Pass: your-redis-password
+    DB: 0
 EOF
 ```

-::: tip 提示
-详细的配置选项请参考 [配置指南](/zh/guide/configuration)。
+::: warning 必需配置
+**MySQL 和 Redis 是必需的。** 部署前请配置以下项：
+- `JwtAuth.AccessSecret` - 使用强随机密钥（必需）
+- `MySQL.*` - 配置你的 MySQL 数据库连接（必需）
+- `Redis.*` - 配置你的 Redis 连接（必需）
 :::

 ### 步骤 4: 启动服务
@@ -169,7 +216,7 @@ docker compose logs -f ppanel
 安装成功后，你可以通过以下地址访问：

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

 ::: warning 默认凭据
 为了安全起见，首次登录后请立即修改默认管理员密码。
@@ -272,43 +319,11 @@ docker compose down -v

 ## 升级

-### 升级前备份
+直接从**管理后台**主页升级 PPanel。在仪表盘主页可以检查新版本并一键升级。

-```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
-```
+::: tip 提示
+系统会自动处理升级过程，包括拉取新镜像和重启服务。
+:::

 ## 高级配置

@@ -317,8 +332,10 @@ docker compose up -d
 要使用不同的端口，编辑 `docker-compose.yml`：

 ```yaml
-ports:
-  - "3000:8080"  # 宿主机端口 3000 -> 容器端口 8080
+services:
+  ppanel-service:
+    ports:
+      - "3000:8080"  # 宿主机端口 3000 -> 容器端口 8080
 ```

 ### 多实例部署
@@ -403,10 +420,10 @@ sudo lsof -i :8080

 ```bash
 # 修复配置目录权限
-sudo chown -R $USER:$USER ppanel-config/
+sudo chown -R $USER:$USER config/

 # 确保文件可读
-chmod 644 ppanel-config/ppanel.yaml
+chmod 644 config/ppanel.yaml
 ```

 ### 无法从外部访问
@@ -67,53 +67,106 @@ mkdir -p ~/ppanel-config

 # 创建配置文件
 cat > ~/ppanel-config/ppanel.yaml <<EOF
-server:
-  host: 0.0.0.0
-  port: 8080
+Host: 0.0.0.0
+Port: 8080
+TLS:
+    Enable: false
+    CertFile: ""
+    KeyFile: ""
+Debug: false

-database:
-  type: sqlite
-  path: /app/data/ppanel.db
+Static:
+  Admin:
+    Enabled: true
+    Prefix: /admin
+    Path: ./static/admin
+  User:
+    Enabled: true
+    Prefix: /
+    Path: ./static/user
+
+JwtAuth:
+    AccessSecret: your-secret-key-change-this
+    AccessExpire: 604800
+
+Logger:
+    ServiceName: ApiService
+    Mode: console
+    Encoding: plain
+    TimeFormat: "2006-01-02 15:04:05.000"
+    Path: logs
+    Level: info
+    MaxContentLength: 0
+    Compress: false
+    Stat: true
+    KeepDays: 0
+    StackCooldownMillis: 100
+    MaxBackups: 0
+    MaxSize: 0
+    Rotation: daily
+    FileTimeFormat: 2006-01-02T15:04:05.000Z07:00
+
+MySQL:
+    Addr: localhost:3306
+    Username: your-username
+    Password: your-password
+    Dbname: ppanel
+    Config: charset=utf8mb4&parseTime=true&loc=Asia%2FShanghai
+    MaxIdleConns: 10
+    MaxOpenConns: 10
+    SlowThreshold: 1000
+
+Redis:
+    Host: localhost:6379
+    Pass: your-redis-password
+    DB: 0
 EOF
 ```

+::: warning 必需配置
+**MySQL 和 Redis 是必需的。** 部署前请配置以下项：
+- `JwtAuth.AccessSecret` - 使用强随机密钥（必需）
+- `MySQL.*` - 配置你的 MySQL 数据库连接（必需）
+- `Redis.*` - 配置你的 Redis 连接（必需）
+:::
+
 ### 步骤 3: 运行容器

 **基础命令:**
 ```bash
 docker run -d \
-  --name ppanel \
+  --name ppanel-service \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
-  -v ppanel-data:/app/data \
-  --restart unless-stopped \
+  -v ~/ppanel-web:/app/static \
+  --restart always \
  ppanel/ppanel:latest
 ```

 **完整参数命令:**
 ```bash
 docker run -d \
-  --name ppanel \
+  --name ppanel-service \
  -p 8080:8080 \
  -v ~/ppanel-config:/app/etc:ro \
-  -v ppanel-data:/app/data \
-  -e TZ=Asia/Shanghai \
-  --restart unless-stopped \
+  -v ~/ppanel-web:/app/static \
+  --restart always \
  --memory="2g" \
  --cpus="2" \
+  --network ppanel-net \
  ppanel/ppanel:latest
 ```

 **参数说明:**
 - `-d`: 以守护进程模式运行（后台运行）
- `--name ppanel`: 设置容器名称
+- `--name ppanel-service`: 设置容器名称
 - `-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 限制
+- `-v ~/ppanel-web:/app/static`: 挂载静态文件目录
+- `--restart always`: 自动重启策略（总是重启）
+- `--memory="2g"`: 内存限制（可选）
+- `--cpus="2"`: CPU 限制（可选）
+- `--network ppanel-net`: 连接到自定义网络（可选）

 ### 步骤 4: 验证运行

@@ -181,43 +234,11 @@ docker volume rm ppanel-data

 ## 升级

-### 备份数据
+直接从**管理后台**主页升级 PPanel。在仪表盘主页可以检查新版本并一键升级。

-```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
-```
+::: tip 提示
+系统会自动处理升级过程，包括拉取新镜像和重启服务。
+:::

 ## 高级用法

@@ -0,0 +1,289 @@
+# 一键部署
+
+使用自动化安装脚本快速部署 PPanel。适合快速测试或生产环境部署。
+
+## 前置条件
+
+- 干净的 Linux 服务器 (Ubuntu 20.04+, Debian 10+, CentOS 8+)
+- Root 或 sudo 访问权限
+- 基本的网络连接
+
+## 安装步骤
+
+### 方式一：完整安装（推荐）
+
+一条命令同时安装 Docker 和 PPanel：
+
+```bash
+curl -fsSL https://ppanel.dev/scripts/zh/install-docker.sh | sudo bash && \
+curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+### 方式二：分步安装
+
+如果你希望分别安装各个组件：
+
+#### 步骤 1: 安装 Docker 和 Docker Compose
+
+```bash
+curl -fsSL https://ppanel.dev/scripts/zh/install-docker.sh | sudo bash
+```
+
+此脚本将会：
+- ✅ 自动检测你的操作系统
+- ✅ 安装 Docker Engine 和 Docker Compose Plugin
+- ✅ 配置 Docker 服务开机自启
+- ✅ 将当前用户添加到 docker 组
+- ✅ 验证安装是否成功
+
+#### 步骤 2: 安装 PPanel
+
+```bash
+curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+此脚本将会：
+- ✅ 检查 Docker 环境
+- ✅ 检查端口可用性
+- ✅ 创建安装目录
+- ✅ 交互式配置（MySQL、Redis）
+- ✅ 自动生成 JWT 密钥
+- ✅ 创建 docker-compose.yml
+- ✅ 拉取 Docker 镜像并启动服务
+- ✅ 显示访问信息
+
+## 安装时的配置
+
+安装脚本会提示你输入以下信息：
+
+### MySQL 配置（必需）
+
+```
+MySQL 地址 (默认: localhost:3306):
+MySQL 用户名 (默认: ppanel):
+MySQL 密码: [你的密码]
+MySQL 数据库名 (默认: ppanel):
+```
+
+### Redis 配置（必需）
+
+```
+Redis 地址 (默认: localhost:6379):
+Redis 密码 (可选): [你的密码]
+Redis DB (默认: 0):
+```
+
+::: tip 提示
+安装脚本会自动为你生成一个安全的 JWT 密钥。
+:::
+
+## 自定义安装目录
+
+默认情况下，PPanel 安装到 `~/ppanel`。你可以指定自定义目录：
+
+```bash
+INSTALL_DIR=/opt/ppanel curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+## 自定义端口
+
+默认情况下，PPanel 监听 8080 端口。要使用其他端口：
+
+```bash
+HOST_PORT=3000 curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+## 部署后配置
+
+### 访问你的安装
+
+安装成功后，你可以访问：
+
+- **用户面板**: `http://your-server-ip:8080`
+- **管理后台**: `http://your-server-ip:8080/admin/`
+
+### 常用命令
+
+安装脚本会显示这些有用的命令：
+
+```bash
+# 进入安装目录
+cd ~/ppanel
+
+# 查看服务状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f
+
+# 重启服务
+docker compose restart
+
+# 停止服务
+docker compose stop
+
+# 启动服务
+docker compose start
+```
+
+### 配置防火墙
+
+**Ubuntu/Debian:**
+```bash
+sudo ufw allow 8080/tcp
+sudo ufw status
+```
+
+**CentOS/RHEL:**
+```bash
+sudo firewall-cmd --permanent --add-port=8080/tcp
+sudo firewall-cmd --reload
+```
+
+### 设置反向代理（推荐）
+
+生产环境部署建议配置带 HTTPS 的反向代理：
+
+**Nginx:**
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    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
+}
+```
+
+## 升级
+
+直接从**管理后台**主页升级 PPanel。在仪表盘主页可以检查新版本并一键升级。
+
+::: tip 提示
+系统会自动处理升级过程，包括拉取新镜像和重启服务。
+:::
+
+## 故障排除
+
+### 安装失败
+
+如果安装失败，请检查：
+
+1. **网络连接**: 确保服务器可以访问 Docker Hub 和 GitHub
+2. **系统要求**: 验证你的操作系统是否支持
+3. **权限**: 确保你有 sudo/root 访问权限
+4. **端口可用性**: 检查端口 8080 是否可用
+
+### Docker 未找到
+
+如果出现 "Docker not found" 错误：
+
+```bash
+# 检查 Docker 是否已安装
+docker --version
+
+# 如果未安装，先运行 Docker 安装脚本
+curl -fsSL https://ppanel.dev/scripts/zh/install-docker.sh | sudo bash
+```
+
+### 服务无法启动
+
+查看日志检查错误：
+
+```bash
+cd ~/ppanel
+docker compose logs -f
+```
+
+常见问题：
+- MySQL 连接失败：检查 MySQL 凭据
+- Redis 连接失败：检查 Redis 凭据
+- 端口已被占用：更改 HOST_PORT
+
+### 权限被拒绝
+
+如果遇到 Docker 权限错误：
+
+```bash
+# 将用户添加到 docker 组
+sudo usermod -aG docker $USER
+
+# 注销并重新登录，或运行：
+newgrp docker
+```
+
+## 卸载
+
+完全移除 PPanel：
+
+```bash
+cd ~/ppanel
+docker compose down
+cd ~
+rm -rf ~/ppanel
+```
+
+## 高级选项
+
+### 非交互式安装
+
+对于自动化部署，可以使用环境变量预配置设置：
+
+```bash
+export INSTALL_DIR=/opt/ppanel
+export HOST_PORT=8080
+export MYSQL_ADDR=localhost:3306
+export MYSQL_USER=ppanel
+export MYSQL_PASSWORD=your-password
+export MYSQL_DB=ppanel
+export REDIS_HOST=localhost:6379
+export REDIS_PASS=your-redis-password
+export REDIS_DB=0
+
+curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+### 代理环境下安装
+
+如果你的服务器在代理后面：
+
+```bash
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+
+curl -fsSL https://ppanel.dev/scripts/zh/install-docker.sh | sudo bash
+curl -fsSL https://ppanel.dev/scripts/zh/install-ppanel.sh | bash
+```
+
+## 下一步
+
+- [配置指南](/zh/guide/configuration) - 自定义你的 PPanel 设置
+- [管理后台](/zh/admin/dashboard) - 开始管理你的面板
+- [API 参考](/zh/api/reference) - 与你的应用集成
+
+## 需要帮助？
+
+- 查看 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
+- 查看安装日志
+- 加入我们的社区获取支持