📝 docs: Add documentation
This commit is contained in:
web@ppanel
@@ -0,0 +1,387 @@
|
||||
# 贡献者
|
||||
|
||||
感谢所有为 PPanel 项目做出贡献的开发者！
|
||||
|
||||
## 项目贡献者
|
||||
|
||||
PPanel 是一个开源项目，我们欢迎并感谢所有形式的贡献，包括但不限于：
|
||||
|
||||
- 💻 代码贡献
|
||||
- 📝 文档改进
|
||||
- 🐛 Bug 报告
|
||||
- 💡 功能建议
|
||||
- 🌍 翻译工作
|
||||
- ⭐ Star 和推广
|
||||
|
||||
## 核心贡献者
|
||||
|
||||
<script setup>
|
||||
import { ref, onMounted } from 'vue'
|
||||
|
||||
const backendContributors = ref([])
|
||||
const frontendContributors = ref([])
|
||||
const backendLoading = ref(true)
|
||||
const frontendLoading = ref(true)
|
||||
|
||||
onMounted(async () => {
|
||||
// 获取后端相关仓库的贡献者
|
||||
try {
|
||||
const repos = ['server', 'ppanel', 'ppanel-node', 'subscription-template']
|
||||
const contributorsMap = new Map()
|
||||
|
||||
for (const repo of repos) {
|
||||
const response = await fetch(`https://api.github.com/repos/perfect-panel/${repo}/contributors`)
|
||||
if (response.ok) {
|
||||
const contributors = await response.json()
|
||||
contributors.forEach(contributor => {
|
||||
if (!contributorsMap.has(contributor.login)) {
|
||||
contributorsMap.set(contributor.login, {
|
||||
login: contributor.login,
|
||||
avatar_url: contributor.avatar_url,
|
||||
html_url: contributor.html_url,
|
||||
contributions: contributor.contributions
|
||||
})
|
||||
} else {
|
||||
const existing = contributorsMap.get(contributor.login)
|
||||
existing.contributions += contributor.contributions
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
backendContributors.value = Array.from(contributorsMap.values())
|
||||
.sort((a, b) => b.contributions - a.contributions)
|
||||
} catch (error) {
|
||||
console.error('Failed to fetch backend contributors:', error)
|
||||
} finally {
|
||||
backendLoading.value = false
|
||||
}
|
||||
|
||||
// 获取前端相关仓库的贡献者
|
||||
try {
|
||||
const repos = ['frontend', 'ppanel-web', 'ppanel-docs']
|
||||
const contributorsMap = new Map()
|
||||
|
||||
for (const repo of repos) {
|
||||
const response = await fetch(`https://api.github.com/repos/perfect-panel/${repo}/contributors`)
|
||||
if (response.ok) {
|
||||
const contributors = await response.json()
|
||||
contributors.forEach(contributor => {
|
||||
if (!contributorsMap.has(contributor.login)) {
|
||||
contributorsMap.set(contributor.login, {
|
||||
login: contributor.login,
|
||||
avatar_url: contributor.avatar_url,
|
||||
html_url: contributor.html_url,
|
||||
contributions: contributor.contributions
|
||||
})
|
||||
} else {
|
||||
const existing = contributorsMap.get(contributor.login)
|
||||
existing.contributions += contributor.contributions
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
frontendContributors.value = Array.from(contributorsMap.values())
|
||||
.sort((a, b) => b.contributions - a.contributions)
|
||||
} catch (error) {
|
||||
console.error('Failed to fetch frontend contributors:', error)
|
||||
} finally {
|
||||
frontendLoading.value = false
|
||||
}
|
||||
})
|
||||
</script>
|
||||
|
||||
### 后端仓库贡献者
|
||||
|
||||
<div v-if="backendLoading" class="contributors-loading">
|
||||
<div class="loading-spinner"></div>
|
||||
<p>正在加载贡献者信息...</p>
|
||||
</div>
|
||||
|
||||
<div v-else-if="backendContributors.length === 0" class="contributors-empty">
|
||||
<p>暂无贡献者数据</p>
|
||||
</div>
|
||||
|
||||
<div v-else>
|
||||
<div class="contributors-grid">
|
||||
<a
|
||||
v-for="contributor in backendContributors"
|
||||
:key="contributor.login"
|
||||
:href="contributor.html_url"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
class="contributor-card"
|
||||
>
|
||||
<img
|
||||
:src="contributor.avatar_url"
|
||||
:alt="contributor.login"
|
||||
class="contributor-avatar"
|
||||
loading="lazy"
|
||||
/>
|
||||
<div class="contributor-info">
|
||||
<div class="contributor-name" :title="contributor.login">{{ contributor.login }}</div>
|
||||
<div class="contributor-contributions">
|
||||
<svg class="contribution-icon" viewBox="0 0 16 16" width="12" height="12" fill="currentColor">
|
||||
<path d="M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Z"></path>
|
||||
</svg>
|
||||
{{ contributor.contributions }} 次贡献
|
||||
</div>
|
||||
</div>
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### 前端仓库贡献者
|
||||
|
||||
<div v-if="frontendLoading" class="contributors-loading">
|
||||
<div class="loading-spinner"></div>
|
||||
<p>正在加载贡献者信息...</p>
|
||||
</div>
|
||||
|
||||
<div v-else-if="frontendContributors.length === 0" class="contributors-empty">
|
||||
<p>暂无贡献者数据</p>
|
||||
</div>
|
||||
|
||||
<div v-else>
|
||||
<div class="contributors-grid">
|
||||
<a
|
||||
v-for="contributor in frontendContributors"
|
||||
:key="contributor.login"
|
||||
:href="contributor.html_url"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
class="contributor-card"
|
||||
>
|
||||
<img
|
||||
:src="contributor.avatar_url"
|
||||
:alt="contributor.login"
|
||||
class="contributor-avatar"
|
||||
loading="lazy"
|
||||
/>
|
||||
<div class="contributor-info">
|
||||
<div class="contributor-name" :title="contributor.login">{{ contributor.login }}</div>
|
||||
<div class="contributor-contributions">
|
||||
<svg class="contribution-icon" viewBox="0 0 16 16" width="12" height="12" fill="currentColor">
|
||||
<path d="M8 .25a.75.75 0 0 1 .673.418l1.882 3.815 4.21.612a.75.75 0 0 1 .416 1.279l-3.046 2.97.719 4.192a.751.751 0 0 1-1.088.791L8 12.347l-3.766 1.98a.75.75 0 0 1-1.088-.79l.72-4.194L.818 6.374a.75.75 0 0 1 .416-1.28l4.21-.611L7.327.668A.75.75 0 0 1 8 .25Z"></path>
|
||||
</svg>
|
||||
{{ contributor.contributions }} 次贡献
|
||||
</div>
|
||||
</div>
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<style scoped>
|
||||
.contributors-loading {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 3rem;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.loading-spinner {
|
||||
width: 40px;
|
||||
height: 40px;
|
||||
border: 3px solid var(--vp-c-divider);
|
||||
border-top-color: var(--vp-c-brand);
|
||||
border-radius: 50%;
|
||||
animation: spin 0.8s linear infinite;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
@keyframes spin {
|
||||
to { transform: rotate(360deg); }
|
||||
}
|
||||
|
||||
.contributors-empty {
|
||||
text-align: center;
|
||||
padding: 2rem;
|
||||
color: var(--vp-c-text-3);
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.contributors-stats {
|
||||
display: flex;
|
||||
gap: 1rem;
|
||||
margin-bottom: 1.5rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.stat-badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
padding: 0.5rem 1rem;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 20px;
|
||||
font-size: 13px;
|
||||
font-weight: 500;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.contributors-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
|
||||
gap: 1rem;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
.contributor-card {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 1rem;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 12px;
|
||||
text-decoration: none;
|
||||
color: var(--vp-c-text-1);
|
||||
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.contributor-card::before {
|
||||
content: '';
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
height: 2px;
|
||||
background: linear-gradient(90deg, var(--vp-c-brand), var(--vp-c-brand-light));
|
||||
transform: scaleX(0);
|
||||
transition: transform 0.3s ease;
|
||||
}
|
||||
|
||||
.contributor-card:hover {
|
||||
border-color: var(--vp-c-brand-light);
|
||||
transform: translateY(-4px);
|
||||
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
|
||||
}
|
||||
|
||||
.contributor-card:hover::before {
|
||||
transform: scaleX(1);
|
||||
}
|
||||
|
||||
.contributor-avatar {
|
||||
width: 56px;
|
||||
height: 56px;
|
||||
border-radius: 50%;
|
||||
margin-right: 1rem;
|
||||
border: 2px solid var(--vp-c-divider);
|
||||
transition: all 0.3s ease;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.contributor-card:hover .contributor-avatar {
|
||||
border-color: var(--vp-c-brand);
|
||||
transform: scale(1.05);
|
||||
}
|
||||
|
||||
.contributor-info {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.contributor-name {
|
||||
font-weight: 600;
|
||||
font-size: 15px;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
margin-bottom: 0.25rem;
|
||||
color: var(--vp-c-text-1);
|
||||
}
|
||||
|
||||
.contributor-contributions {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.25rem;
|
||||
font-size: 13px;
|
||||
color: var(--vp-c-text-2);
|
||||
}
|
||||
|
||||
.contribution-icon {
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.contributors-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.contributors-stats {
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
.stat-badge {
|
||||
width: 100%;
|
||||
justify-content: center;
|
||||
}
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
.contributor-card:hover {
|
||||
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
### 报告问题
|
||||
|
||||
如果你发现了 Bug 或有功能建议：
|
||||
|
||||
1. 在 [GitHub Issues](https://github.com/perfect-panel/frontend/issues) 中搜索是否已有类似问题
|
||||
2. 如果没有，创建一个新的 Issue
|
||||
3. 提供详细的信息：
|
||||
- 问题描述
|
||||
- 复现步骤
|
||||
- 预期行为
|
||||
- 实际行为
|
||||
- 环境信息（浏览器、操作系统等）
|
||||
- 截图或错误日志（如果适用）
|
||||
|
||||
### 文档贡献
|
||||
|
||||
文档同样重要！你可以：
|
||||
|
||||
- 修正错别字和语法错误
|
||||
- 改进现有文档的清晰度
|
||||
- 添加缺失的文档
|
||||
- 翻译文档到其他语言
|
||||
- 添加使用示例和教程
|
||||
|
||||
文档源文件位于 `/docs` 目录中。
|
||||
|
||||
### 翻译贡献
|
||||
|
||||
我们欢迎将 PPanel 翻译成更多语言：
|
||||
|
||||
1. 检查 `/docs` 目录下是否已有目标语言的文件夹
|
||||
2. 如果没有，创建新的语言文件夹（如 `/docs/ja` 为日语）
|
||||
3. 复制英文或中文版本作为基础
|
||||
4. 翻译内容
|
||||
5. 在 `.vitepress/config.mts` 中添加新语言配置
|
||||
6. 提交 Pull Request
|
||||
|
||||
## 社区
|
||||
|
||||
加入我们的社区，与其他开发者交流：
|
||||
|
||||
- **GitHub Discussions**: [讨论区](https://github.com/perfect-panel/frontend/discussions)
|
||||
- **GitHub Issues**: [问题追踪](https://github.com/perfect-panel/frontend/issues)
|
||||
- **Telegram**: [加入群组](https://t.me/PPanelChat)
|
||||
|
||||
## 行为准则
|
||||
|
||||
我们致力于为所有人提供一个友好、安全和受欢迎的环境。请阅读并遵守我们的 [行为准则](https://github.com/perfect-panel/frontend/blob/main/CODE_OF_CONDUCT.md)。
|
||||
|
||||
## 致谢
|
||||
|
||||
特别感谢所有为 PPanel 项目做出贡献的开发者、测试者、文档编写者和社区成员。是你们让 PPanel 变得更好！
|
||||
|
||||
## 许可证
|
||||
|
||||
通过贡献代码，你同意你的贡献将按照项目的 [GNU License](https://github.com/perfect-panel/frontend/blob/main/LICENSE) 许可证发布。
|
||||
@@ -0,0 +1,507 @@
|
||||
# 安装部署
|
||||
|
||||
本指南将帮助你使用 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:latest
|
||||
|
||||
# 或拉取指定版本
|
||||
docker pull ppanel/ppanel:v0.1.2
|
||||
```
|
||||
|
||||
#### 步骤 2: 准备配置
|
||||
|
||||
创建配置目录并准备配置文件：
|
||||
|
||||
```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)。
|
||||
:::
|
||||
|
||||
#### 步骤 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: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
|
||||
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: 准备配置
|
||||
|
||||
```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`
|
||||
|
||||
::: warning 默认凭据
|
||||
为了安全起见，首次登录后请立即修改默认管理员密码。
|
||||
:::
|
||||
|
||||
### 配置反向代理（可选）
|
||||
|
||||
对于生产环境部署，建议使用 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
|
||||
```
|
||||
|
||||
::: warning 数据持久化
|
||||
删除容器不会删除数据卷。如需同时删除数据卷，请使用：
|
||||
```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: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
|
||||
|
||||
```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: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: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: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 网络以获得更好的隔离：
|
||||
|
||||
```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:latest
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [配置指南](/zh/guide/configuration) - 了解详细的配置选项
|
||||
- [管理后台](/zh/admin/dashboard) - 开始管理你的面板
|
||||
- [API 参考](/zh/api/reference) - 集成 PPanel API
|
||||
|
||||
## 需要帮助？
|
||||
|
||||
如果遇到任何问题：
|
||||
|
||||
1. 查看上面的[故障排除](#故障排除)部分
|
||||
2. 搜索 [GitHub Issues](https://github.com/perfect-panel/ppanel/issues)
|
||||
3. 加入我们的社区讨论
|
||||
4. 创建新 issue 并附上详细的日志和系统信息
|
||||
@@ -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 并附上详细的系统信息和日志
|
||||
@@ -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`
|
||||
- 验证系统要求
|
||||
@@ -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)
|
||||
- 加入我们的社区讨论
|
||||
@@ -0,0 +1,93 @@
|
||||
# 简介
|
||||
|
||||
欢迎使用 PPanel！这是一个纯粹、专业、完美的开源代理面板工具，旨在为用户提供完整的管理解决方案。
|
||||
|
||||
## 什么是 PPanel？
|
||||
|
||||
PPanel 是一个现代化的代理面板系统，采用前后端分离架构，提供完整的用户管理、订阅服务、订单管理、节点管理等功能。无论您是个人用户还是企业用户，PPanel 都能满足您的需求。
|
||||
|
||||
## 核心特性
|
||||
|
||||
- **🎯 完整管理**: 服务器管理、节点配置、订阅系统、产品管理等
|
||||
- **💼 商务运营**: 订单管理、优惠券系统、营销活动、公告发布
|
||||
- **👥 用户支持**: 用户管理、工单系统、文档中心，提供全方位用户服务
|
||||
- **📊 数据分析**: 12 种类型日志，全面的流量、余额、佣金数据分析
|
||||
- **🔧 灵活配置**: 支付配置、认证控制、广告管理，灵活的系统选项
|
||||
- **🚀 现代技术栈**: 基于 React 19 + TypeScript + TailwindCSS + shadcn/ui 构建
|
||||
|
||||
## 术语说明
|
||||
|
||||
PPanel 的一些术语与其他面板系统存在差异，为确保您能准确理解文档内容并避免误解，建议在阅读前先了解以下术语：
|
||||
|
||||
### 用户端
|
||||
为最终用户提供的界面，用户通过该界面与系统进行交互。您可以根据需求自定义或重构该界面，实现站点的个性化定制。
|
||||
|
||||
### 管理端
|
||||
用于管理员操作的界面，负责管理系统、用户及数据。您可以根据需求对该界面进行定制或重构，以适应您的管理需求。
|
||||
|
||||
### 服务端
|
||||
PPanel 的 API 层，处理与前端的所有数据交互，负责业务逻辑的执行与数据服务的提供。
|
||||
|
||||
### 节点端
|
||||
负责 PPanel 服务端与各节点（落地端）的通信，确保网络节点的连接与服务的稳定性。
|
||||
|
||||
### 客户端
|
||||
用户用来连接系统的应用程序，通常是指用户的设备端软件或应用，负责与系统建立连接并使用相关服务。
|
||||
|
||||
## 项目架构
|
||||
|
||||
PPanel 采用 Monorepo 架构，便于统一管理和维护：
|
||||
|
||||
### 前端应用
|
||||
- **apps/admin**: 管理后台应用，提供完整的后台管理功能
|
||||
- **apps/user**: 用户端应用，为最终用户提供服务界面
|
||||
|
||||
### 共享包
|
||||
- **packages/ui**: 共享 UI 组件库，包含所有可复用的 UI 组件
|
||||
- **packages/typescript-config**: 统一的 TypeScript 配置
|
||||
|
||||
### 技术栈
|
||||
- **框架**: React 19 + TypeScript
|
||||
- **路由**: TanStack Router
|
||||
- **状态管理**: Zustand
|
||||
- **样式**: TailwindCSS 4.0
|
||||
- **UI 组件**: shadcn/ui
|
||||
- **构建工具**: Vite + Turbo
|
||||
- **代码规范**: Biome
|
||||
- **Git 规范**: Lefthook + Gitmoji
|
||||
|
||||
## 主要功能
|
||||
|
||||
### 运维管理
|
||||
- 服务器管理
|
||||
- 节点管理
|
||||
- 订阅配置
|
||||
- 产品管理
|
||||
|
||||
### 商务管理
|
||||
- 订单管理
|
||||
- 优惠券管理
|
||||
- 营销管理
|
||||
- 公告管理
|
||||
|
||||
### 用户与支持
|
||||
- 用户管理
|
||||
- 工单系统
|
||||
- 文档管理
|
||||
|
||||
### 系统管理
|
||||
- 系统配置
|
||||
- 认证控制
|
||||
- 支付配置
|
||||
- 广告配置
|
||||
|
||||
### 日志与分析
|
||||
- 完整的操作日志记录
|
||||
- 流量统计分析
|
||||
- 财务数据追踪
|
||||
|
||||
## 下一步
|
||||
|
||||
- [安装部署](/zh/guide/installation/) - 了解如何部署 PPanel
|
||||
- [配置指南](/zh/guide/configuration) - 配置你的 PPanel 实例
|
||||
- [管理后台](/zh/admin/dashboard) - 开始使用管理功能
|
||||
@@ -0,0 +1,168 @@
|
||||
# 节点端安装
|
||||
|
||||
`ppanel-node` 是部署在边缘服务器上的轻量代理守护进程，基于 `xray-core`，负责同步路由、订阅、心跳与密钥。本指南提供最快速的一键安装方式，并补充源码与容器方案。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
wget -N https://raw.githubusercontent.com/perfect-panel/ppanel-node/master/scripts/install.sh
|
||||
sudo bash install.sh --api-host https://panel.example.com --server-id 1 --secret-key <SECRET>
|
||||
```
|
||||
|
||||
脚本会自动识别系统/架构、拉取最新版、安装 geo 数据，并配置 `ppnode` CLI 与系统服务。
|
||||
|
||||
### 环境要求
|
||||
|
||||
- 64 位 Linux（Debian/Ubuntu ≥16、CentOS ≥7、Alpine、Arch 等）
|
||||
- 拥有 root 权限，且可访问 `github.com`
|
||||
- 防火墙需放通对外协议端口及访问面板的 443 端口
|
||||
- 面板后台已生成匹配的 **Server ID** 与 **Secret Key**
|
||||
|
||||
### 可选参数
|
||||
|
||||
- 位置参数 `vX.Y.Z`：安装指定 tag。
|
||||
- `--api-host https://panel.example.com`
|
||||
- `--server-id <ID>`（对应运维→服务器 管理页面中的记录）
|
||||
- `--secret-key <KEY>`
|
||||
|
||||
若未传入参数，脚本会在安装过程中交互式询问。
|
||||
|
||||
### 服务管理
|
||||
|
||||
安装完成后可通过 CLI 管理：
|
||||
|
||||
```bash
|
||||
ppnode status # 查看状态
|
||||
ppnode start # 启动
|
||||
ppnode restart # 重启 + 重新加载配置
|
||||
ppnode log # 查看日志
|
||||
ppnode update # 升级至最新版本
|
||||
ppnode update v1.2 # 安装指定版本
|
||||
ppnode uninstall # 卸载
|
||||
ppnode generate # 重新生成 /etc/PPanel-node/config.yml
|
||||
```
|
||||
|
||||
## 安装方式
|
||||
|
||||
### 方式一：一键脚本（推荐）
|
||||
|
||||
执行上方快速开始命令或运行 `sudo bash install.sh` 并按提示填写信息。脚本包含以下步骤：
|
||||
|
||||
1. 根据发行版安装依赖（`wget`、`curl`、`tar`、`socat`、cron 等）。
|
||||
2. 下载 `ppanel-node-linux-<arch>.zip`（支持 amd64/arm64/s390x）。
|
||||
3. 解压到 `/usr/local/PPanel-node`，安装 `geoip.dat`、`geosite.dat`，配置系统服务。
|
||||
4. 安装 `/usr/bin/ppnode` 管理脚本并设置开机自启。
|
||||
|
||||
### 方式二：从源码构建
|
||||
|
||||
1. 安装 Go 1.21+，并启用 JSON v2 实验特性：
|
||||
|
||||
```bash
|
||||
export GOEXPERIMENT=jsonv2
|
||||
```
|
||||
|
||||
2. 克隆仓库并编译：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/perfect-panel/ppanel-node.git
|
||||
cd ppanel-node
|
||||
GOEXPERIMENT=jsonv2 go build -v -o ./ppnode -trimpath -ldflags "-s -w -buildid="
|
||||
```
|
||||
|
||||
3. 复制二进制与 geo 数据：
|
||||
|
||||
```bash
|
||||
sudo install -Dm755 ./ppnode /usr/local/PPanel-node/ppnode
|
||||
sudo install -Dm644 ./geoip.dat /etc/PPanel-node/geoip.dat
|
||||
sudo install -Dm644 ./geosite.dat /etc/PPanel-node/geosite.dat
|
||||
```
|
||||
|
||||
4. 创建 systemd 服务：
|
||||
|
||||
```bash
|
||||
sudo tee /etc/systemd/system/PPanel-node.service <<'EOF'
|
||||
[Unit]
|
||||
Description=PPanel Node
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/PPanel-node/ppnode server
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now PPanel-node
|
||||
```
|
||||
|
||||
5. 复制仓库中的 `config.yml` 或手动创建（见配置章节），最后重启服务。
|
||||
|
||||
### 方式三：容器化部署
|
||||
|
||||
仓库自带 `Dockerfile`，可在不方便直接安装的宿主机上运行：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/perfect-panel/ppanel-node.git
|
||||
cd ppanel-node
|
||||
docker build -t ppanel-node:latest .
|
||||
docker run -d --name ppanel-node \
|
||||
--net host \
|
||||
-v /etc/PPanel-node:/etc/PPanel-node \
|
||||
ppanel-node:latest server
|
||||
```
|
||||
|
||||
建议挂载的目录：
|
||||
|
||||
- `/etc/PPanel-node/config.yml` —— 保存 API/密钥配置。
|
||||
- `/etc/PPanel-node/geoip.dat` 与 `/etc/PPanel-node/geosite.dat` —— 持久化 Geo 数据文件。
|
||||
- `/var/log/ppanel-node`（可选）—— 在宿主机收集日志。
|
||||
|
||||
## 配置节点
|
||||
|
||||
运行时配置位于 `/etc/PPanel-node/config.yml`，结构如下：
|
||||
|
||||
```yaml
|
||||
Log:
|
||||
Level: warn # debug | info | warn | error
|
||||
Output: "" # 为空代表 stdout，也可以写入文件
|
||||
Access: none # 访问日志路径，none 为关闭
|
||||
|
||||
Api:
|
||||
ApiHost: https://panel.example.com
|
||||
ServerID: 3
|
||||
SecretKey: b23d8ee1cfe44d7f
|
||||
Timeout: 30
|
||||
```
|
||||
|
||||
修改完成后重启服务：
|
||||
|
||||
```bash
|
||||
sudo systemctl restart PPanel-node
|
||||
# 或
|
||||
ppnode restart
|
||||
```
|
||||
|
||||
### 与面板的映射关系
|
||||
|
||||
1. 在 **运维管理 → 服务器管理** 中创建记录，获取对应的 Server ID 与 Secret Key。
|
||||
2. 将上述信息填入 `config.yml`，`ApiHost` 必须是面板的公网可访问地址。
|
||||
3. 确保节点能够访问面板 443 端口，且面板允许节点 IP 回连。
|
||||
4. 节点上报后会在面板中显示为在线，通常 30 秒内即可看到心跳。
|
||||
|
||||
## 升级与回滚
|
||||
|
||||
- `ppnode update` 仅替换二进制，保留配置与 geo 文件。
|
||||
- `ppnode update vX.Y.Z` 可按版本号回滚。
|
||||
- 源码部署时，重新构建目标 tag，替换 `/usr/local/PPanel-node/ppnode` 并 `systemctl restart PPanel-node`。
|
||||
|
||||
## 故障排查
|
||||
|
||||
- `ppnode log` 或 `journalctl -u PPanel-node -f` 查看运行日志。
|
||||
- 确认 `/etc/PPanel-node/config.yml` 中 `ApiHost`、`SecretKey` 填写正确。
|
||||
- 保证服务器可访问 GitHub（更新）与面板域名的 443 端口。
|
||||
- 面板显示离线时检查防火墙是否放行心跳、系统时间是否同步（`chronyc tracking`）。
|
||||
|
||||
更多细节可参阅源仓库：[`github.com/perfect-panel/ppanel-node`](https://github.com/perfect-panel/ppanel-node)。
|
||||
@@ -0,0 +1,505 @@
|
||||
# 后端分离部署
|
||||
|
||||
本指南将帮助您独立部署 PPanel 后端服务，适用于前后端分离部署场景。
|
||||
|
||||
## 概述
|
||||
|
||||
后端分离部署允许您将 PPanel 后端服务部署在独立的服务器上，提供 API 服务给前端应用。这种部署方式具有以下优势：
|
||||
|
||||
- 🚀 独立扩展后端服务性能
|
||||
- 🔒 更好的安全隔离
|
||||
- 🌐 支持多前端实例连接同一后端
|
||||
- 🛠️ 便于后端服务的独立维护和升级
|
||||
|
||||
## 系统要求
|
||||
|
||||
### 最低配置
|
||||
- CPU: 1 核心
|
||||
- 内存: 1 GB
|
||||
- 存储: 10 GB
|
||||
- 操作系统: Linux (推荐 Ubuntu 20.04+, Debian 11+, CentOS 8+)
|
||||
|
||||
### 推荐配置
|
||||
- CPU: 2 核心以上
|
||||
- 内存: 2 GB 以上
|
||||
- 存储: 20 GB 以上
|
||||
|
||||
## 部署方式
|
||||
|
||||
### 方式一：Docker 部署（推荐）
|
||||
|
||||
#### 1. 安装 Docker
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
curl -fsSL https://get.docker.com | sh
|
||||
|
||||
# 启动 Docker 服务
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
```
|
||||
|
||||
#### 2. 创建配置文件
|
||||
|
||||
创建后端配置文件 `config.yaml`：
|
||||
|
||||
```yaml
|
||||
# 数据库配置
|
||||
database:
|
||||
type: mysql
|
||||
host: localhost
|
||||
port: 3306
|
||||
username: ppanel
|
||||
password: your_password
|
||||
database: ppanel
|
||||
|
||||
# Redis 配置
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
password: ""
|
||||
db: 0
|
||||
|
||||
# 服务配置
|
||||
server:
|
||||
host: 0.0.0.0
|
||||
port: 8080
|
||||
|
||||
# CORS 配置（重要：允许前端域名访问）
|
||||
cors:
|
||||
allow_origins:
|
||||
- "https://your-frontend-domain.com"
|
||||
- "http://localhost:3000" # 开发环境
|
||||
allow_methods:
|
||||
- GET
|
||||
- POST
|
||||
- PUT
|
||||
- DELETE
|
||||
- OPTIONS
|
||||
allow_headers:
|
||||
- "*"
|
||||
|
||||
# JWT 配置
|
||||
jwt:
|
||||
secret: "your-secret-key"
|
||||
expire: 7200 # 2小时
|
||||
|
||||
# API 配置
|
||||
api:
|
||||
prefix: "/api"
|
||||
version: "v1"
|
||||
```
|
||||
|
||||
#### 3. 准备 MySQL 数据库
|
||||
|
||||
```bash
|
||||
# 使用 Docker 运行 MySQL
|
||||
docker run -d \
|
||||
--name ppanel-mysql \
|
||||
-e MYSQL_ROOT_PASSWORD=root_password \
|
||||
-e MYSQL_DATABASE=ppanel \
|
||||
-e MYSQL_USER=ppanel \
|
||||
-e MYSQL_PASSWORD=your_password \
|
||||
-p 3306:3306 \
|
||||
-v ppanel-mysql-data:/var/lib/mysql \
|
||||
mysql:8.0
|
||||
|
||||
# 等待 MySQL 启动
|
||||
sleep 10
|
||||
```
|
||||
|
||||
#### 4. 准备 Redis
|
||||
|
||||
```bash
|
||||
# 使用 Docker 运行 Redis
|
||||
docker run -d \
|
||||
--name ppanel-redis \
|
||||
-p 6379:6379 \
|
||||
-v ppanel-redis-data:/data \
|
||||
redis:7-alpine
|
||||
```
|
||||
|
||||
#### 5. 运行后端服务
|
||||
|
||||
```bash
|
||||
# 拉取后端镜像
|
||||
docker pull ghcr.io/perfect-panel/ppanel:latest
|
||||
|
||||
# 运行后端容器
|
||||
docker run -d \
|
||||
--name ppanel-backend \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/config.yaml:/app/config.yaml \
|
||||
--link ppanel-mysql:mysql \
|
||||
--link ppanel-redis:redis \
|
||||
ghcr.io/perfect-panel/ppanel:latest
|
||||
```
|
||||
|
||||
#### 6. 初始化数据库
|
||||
|
||||
```bash
|
||||
# 执行数据库迁移
|
||||
docker exec ppanel-backend ./ppanel migrate
|
||||
```
|
||||
|
||||
### 方式二：二进制部署
|
||||
|
||||
#### 1. 下载后端程序
|
||||
|
||||
```bash
|
||||
# 下载最新版本
|
||||
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
|
||||
|
||||
# 解压
|
||||
tar -xzf ppanel-linux-amd64.tar.gz
|
||||
cd ppanel
|
||||
|
||||
# 赋予执行权限
|
||||
chmod +x ppanel
|
||||
```
|
||||
|
||||
#### 2. 配置后端服务
|
||||
|
||||
创建配置文件 `config.yaml`（内容同上 Docker 部署方式）。
|
||||
|
||||
#### 3. 安装并配置 MySQL
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install mysql-server -y
|
||||
|
||||
# 创建数据库和用户
|
||||
sudo mysql <<EOF
|
||||
CREATE DATABASE ppanel;
|
||||
CREATE USER 'ppanel'@'localhost' IDENTIFIED BY 'your_password';
|
||||
GRANT ALL PRIVILEGES ON ppanel.* TO 'ppanel'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
EOF
|
||||
```
|
||||
|
||||
#### 4. 安装并配置 Redis
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install redis-server -y
|
||||
sudo systemctl start redis-server
|
||||
sudo systemctl enable redis-server
|
||||
```
|
||||
|
||||
#### 5. 初始化数据库
|
||||
|
||||
```bash
|
||||
# 执行数据库迁移
|
||||
./ppanel migrate
|
||||
```
|
||||
|
||||
#### 6. 创建 systemd 服务
|
||||
|
||||
创建服务文件 `/etc/systemd/system/ppanel.service`：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=PPanel Backend Service
|
||||
After=network.target mysql.service redis.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=ppanel
|
||||
WorkingDirectory=/opt/ppanel
|
||||
ExecStart=/opt/ppanel/ppanel server
|
||||
Restart=on-failure
|
||||
RestartSec=5s
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
启动服务：
|
||||
|
||||
```bash
|
||||
# 创建专用用户
|
||||
sudo useradd -r -s /bin/false ppanel
|
||||
|
||||
# 移动文件到安装目录
|
||||
sudo mkdir -p /opt/ppanel
|
||||
sudo mv ppanel config.yaml /opt/ppanel/
|
||||
sudo chown -R ppanel:ppanel /opt/ppanel
|
||||
|
||||
# 启动服务
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl start ppanel
|
||||
sudo systemctl enable ppanel
|
||||
|
||||
# 查看服务状态
|
||||
sudo systemctl status ppanel
|
||||
```
|
||||
|
||||
## 配置反向代理
|
||||
|
||||
### Nginx 配置
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name api.your-domain.com;
|
||||
|
||||
# HTTPS 重定向（推荐配置 SSL 证书）
|
||||
# return 301 https://$server_name$request_uri;
|
||||
|
||||
location / {
|
||||
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;
|
||||
|
||||
# WebSocket 支持
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
|
||||
# 超时配置
|
||||
proxy_connect_timeout 60s;
|
||||
proxy_send_timeout 60s;
|
||||
proxy_read_timeout 60s;
|
||||
}
|
||||
}
|
||||
|
||||
# HTTPS 配置示例
|
||||
# server {
|
||||
# listen 443 ssl http2;
|
||||
# server_name api.your-domain.com;
|
||||
#
|
||||
# ssl_certificate /path/to/cert.pem;
|
||||
# ssl_certificate_key /path/to/key.pem;
|
||||
#
|
||||
# location / {
|
||||
# proxy_pass http://127.0.0.1:8080;
|
||||
# # ... 其他配置同上
|
||||
# }
|
||||
# }
|
||||
```
|
||||
|
||||
重载 Nginx：
|
||||
|
||||
```bash
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Caddy 配置
|
||||
|
||||
```caddy
|
||||
api.your-domain.com {
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
|
||||
## 验证部署
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
# 检查后端服务是否运行
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# 预期输出
|
||||
# {"status":"ok","version":"1.0.0"}
|
||||
```
|
||||
|
||||
### 测试 API
|
||||
|
||||
```bash
|
||||
# 测试公共 API
|
||||
curl http://localhost:8080/api/v1/ping
|
||||
|
||||
# 预期输出
|
||||
# {"message":"pong"}
|
||||
```
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
除了配置文件，您也可以使用环境变量：
|
||||
|
||||
```bash
|
||||
# 数据库配置
|
||||
export DB_HOST=localhost
|
||||
export DB_PORT=3306
|
||||
export DB_USER=ppanel
|
||||
export DB_PASSWORD=your_password
|
||||
export DB_NAME=ppanel
|
||||
|
||||
# Redis 配置
|
||||
export REDIS_HOST=localhost
|
||||
export REDIS_PORT=6379
|
||||
export REDIS_PASSWORD=""
|
||||
|
||||
# JWT 密钥
|
||||
export JWT_SECRET=your-secret-key
|
||||
|
||||
# 服务端口
|
||||
export SERVER_PORT=8080
|
||||
```
|
||||
|
||||
Docker 运行时使用环境变量：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name ppanel-backend \
|
||||
-p 8080:8080 \
|
||||
-e DB_HOST=mysql \
|
||||
-e DB_USER=ppanel \
|
||||
-e DB_PASSWORD=your_password \
|
||||
-e REDIS_HOST=redis \
|
||||
--link ppanel-mysql:mysql \
|
||||
--link ppanel-redis:redis \
|
||||
ghcr.io/perfect-panel/ppanel:latest
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **使用强密码**：为数据库和 JWT 密钥设置强密码
|
||||
2. **配置防火墙**：仅开放必要端口（如 80, 443）
|
||||
3. **启用 HTTPS**：使用 SSL/TLS 证书加密通信
|
||||
4. **CORS 配置**：仅允许可信的前端域名访问
|
||||
5. **定期备份**：定期备份数据库和配置文件
|
||||
6. **监控日志**：定期检查应用日志和系统日志
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
```bash
|
||||
# 查看服务日志
|
||||
sudo journalctl -u ppanel -n 50 --no-pager
|
||||
|
||||
# Docker 查看日志
|
||||
docker logs ppanel-backend
|
||||
```
|
||||
|
||||
### 数据库连接失败
|
||||
|
||||
```bash
|
||||
# 测试 MySQL 连接
|
||||
mysql -h localhost -u ppanel -p -e "SELECT 1;"
|
||||
|
||||
# 检查 MySQL 服务状态
|
||||
sudo systemctl status mysql
|
||||
```
|
||||
|
||||
### Redis 连接失败
|
||||
|
||||
```bash
|
||||
# 测试 Redis 连接
|
||||
redis-cli ping
|
||||
|
||||
# 检查 Redis 服务状态
|
||||
sudo systemctl status redis-server
|
||||
```
|
||||
|
||||
### CORS 错误
|
||||
|
||||
确保在 `config.yaml` 中正确配置了前端域名：
|
||||
|
||||
```yaml
|
||||
cors:
|
||||
allow_origins:
|
||||
- "https://your-frontend-domain.com"
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 数据库优化
|
||||
|
||||
```sql
|
||||
-- 创建必要的索引
|
||||
CREATE INDEX idx_user_email ON users(email);
|
||||
CREATE INDEX idx_order_status ON orders(status);
|
||||
CREATE INDEX idx_created_at ON orders(created_at);
|
||||
```
|
||||
|
||||
### Redis 缓存配置
|
||||
|
||||
```yaml
|
||||
redis:
|
||||
# 启用缓存
|
||||
cache_enabled: true
|
||||
# 缓存过期时间（秒）
|
||||
cache_ttl: 3600
|
||||
```
|
||||
|
||||
### 应用层优化
|
||||
|
||||
```yaml
|
||||
# 启用 Gzip 压缩
|
||||
server:
|
||||
gzip: true
|
||||
|
||||
# 调整并发连接数
|
||||
server:
|
||||
max_connections: 1000
|
||||
```
|
||||
|
||||
## 升级指南
|
||||
|
||||
### Docker 升级
|
||||
|
||||
```bash
|
||||
# 拉取最新镜像
|
||||
docker pull ghcr.io/perfect-panel/ppanel:latest
|
||||
|
||||
# 停止旧容器
|
||||
docker stop ppanel-backend
|
||||
|
||||
# 备份数据
|
||||
docker exec ppanel-mysql mysqldump -u ppanel -p ppanel > backup.sql
|
||||
|
||||
# 删除旧容器
|
||||
docker rm ppanel-backend
|
||||
|
||||
# 运行新容器
|
||||
docker run -d \
|
||||
--name ppanel-backend \
|
||||
-p 8080:8080 \
|
||||
-v $(pwd)/config.yaml:/app/config.yaml \
|
||||
--link ppanel-mysql:mysql \
|
||||
--link ppanel-redis:redis \
|
||||
ghcr.io/perfect-panel/ppanel:latest
|
||||
|
||||
# 执行数据库迁移
|
||||
docker exec ppanel-backend ./ppanel migrate
|
||||
```
|
||||
|
||||
### 二进制升级
|
||||
|
||||
```bash
|
||||
# 停止服务
|
||||
sudo systemctl stop ppanel
|
||||
|
||||
# 备份旧版本
|
||||
sudo cp /opt/ppanel/ppanel /opt/ppanel/ppanel.backup
|
||||
|
||||
# 下载新版本
|
||||
wget https://github.com/perfect-panel/ppanel/releases/latest/download/ppanel-linux-amd64.tar.gz
|
||||
tar -xzf ppanel-linux-amd64.tar.gz
|
||||
|
||||
# 替换文件
|
||||
sudo mv ppanel /opt/ppanel/
|
||||
sudo chown ppanel:ppanel /opt/ppanel/ppanel
|
||||
|
||||
# 执行数据库迁移
|
||||
cd /opt/ppanel
|
||||
sudo -u ppanel ./ppanel migrate
|
||||
|
||||
# 启动服务
|
||||
sudo systemctl start ppanel
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [前端分离部署](./frontend.md) - 部署前端应用
|
||||
- [节点端安装](../node/installation.md) - 部署节点服务
|
||||
- [API 文档](/zh/api/reference) - 查看完整 API 文档
|
||||
@@ -0,0 +1,689 @@
|
||||
# 前端分离部署
|
||||
|
||||
本指南将帮助您独立部署 PPanel 前端应用，连接到已部署的后端服务。
|
||||
|
||||
## 概述
|
||||
|
||||
前端分离部署允许您将 PPanel 前端应用部署在独立的服务器或 CDN 上，通过 API 与后端服务通信。
|
||||
|
||||
PPanel 前端包含两个独立应用：
|
||||
- **用户端** (`ppanel-user-web`): 面向最终用户的界面
|
||||
- **管理端** (`ppanel-admin-web`): 面向管理员的后台管理界面
|
||||
|
||||
### 优势
|
||||
|
||||
- 🚀 利用 CDN 加速静态资源访问
|
||||
- 🌍 支持多地域分发
|
||||
- 📦 前端独立部署，不影响后端服务
|
||||
- 🔄 便于前端快速迭代和更新
|
||||
- 🎨 使用现代技术栈 (React 19, TypeScript, TailwindCSS 4)
|
||||
|
||||
## 前提条件
|
||||
|
||||
- 已完成[后端部署](./backend.md)
|
||||
- 后端 API 地址（如 `https://api.your-domain.com`）
|
||||
- 前端域名：
|
||||
- 用户端：`https://user.your-domain.com`
|
||||
- 管理端：`https://admin.your-domain.com`
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **运行时**: Bun (推荐) / Node.js 20+
|
||||
- **构建工具**: Vite 6
|
||||
- **框架**: React 19 + TypeScript
|
||||
- **路由**: TanStack Router
|
||||
- **样式**: TailwindCSS 4
|
||||
- **状态管理**: Zustand
|
||||
- **国际化**: i18next
|
||||
- **Monorepo**: Turborepo
|
||||
|
||||
## 部署方式
|
||||
|
||||
### 方式一：从源码构建（推荐）
|
||||
|
||||
#### 1. 环境准备
|
||||
|
||||
安装 Bun（推荐）：
|
||||
|
||||
```bash
|
||||
# Linux/macOS
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# Windows (WSL2)
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# 验证安装
|
||||
bun --version
|
||||
```
|
||||
|
||||
或使用 Node.js (需要 20+)：
|
||||
|
||||
```bash
|
||||
# 检查 Node.js 版本
|
||||
node --version # 应该是 v20 或更高
|
||||
```
|
||||
|
||||
#### 2. 克隆代码仓库
|
||||
|
||||
```bash
|
||||
git clone https://github.com/perfect-panel/frontend.git
|
||||
cd frontend
|
||||
```
|
||||
|
||||
#### 3. 安装依赖
|
||||
|
||||
```bash
|
||||
# 使用 Bun（推荐，更快）
|
||||
bun install
|
||||
|
||||
# 或使用 npm
|
||||
npm install
|
||||
|
||||
# 或使用 pnpm
|
||||
pnpm install
|
||||
```
|
||||
|
||||
#### 4. 配置环境变量
|
||||
|
||||
在应用目录下创建环境配置文件。
|
||||
|
||||
**管理端配置** (`apps/admin/.env.production`)：
|
||||
|
||||
```bash
|
||||
# 后端 API 地址（必需）
|
||||
VITE_API_BASE_URL=https://api.your-domain.com
|
||||
|
||||
# CDN 地址（可选，用于加速静态资源）
|
||||
VITE_CDN_URL=https://cdn.jsdmirror.com
|
||||
|
||||
# 启用教程文档（可选）
|
||||
VITE_TUTORIAL_DOCUMENT=true
|
||||
|
||||
# 开发环境默认登录凭证（生产环境请留空）
|
||||
VITE_USER_EMAIL=
|
||||
VITE_USER_PASSWORD=
|
||||
```
|
||||
|
||||
**用户端配置** (`apps/user/.env.production`)：
|
||||
|
||||
```bash
|
||||
# 后端 API 地址（必需）
|
||||
VITE_API_BASE_URL=https://api.your-domain.com
|
||||
|
||||
# CDN 地址（可选）
|
||||
VITE_CDN_URL=https://cdn.jsdmirror.com
|
||||
|
||||
# 启用教程文档（可选）
|
||||
VITE_TUTORIAL_DOCUMENT=true
|
||||
|
||||
# 开发环境默认登录凭证（生产环境请留空）
|
||||
VITE_USER_EMAIL=
|
||||
VITE_USER_PASSWORD=
|
||||
```
|
||||
|
||||
#### 5. 构建应用
|
||||
|
||||
构建所有应用：
|
||||
|
||||
```bash
|
||||
# 使用 Bun
|
||||
bun run build
|
||||
|
||||
# 或使用 npm
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建特定应用：
|
||||
|
||||
```bash
|
||||
# 进入应用目录
|
||||
cd apps/admin # 或 apps/user
|
||||
|
||||
# 构建
|
||||
bun run build # 或 npm run build
|
||||
```
|
||||
|
||||
构建完成后，静态文件将输出到：
|
||||
- 管理端：`apps/admin/dist/`
|
||||
- 用户端：`apps/user/dist/`
|
||||
|
||||
#### 6. 预览构建结果
|
||||
|
||||
```bash
|
||||
# 在应用目录下
|
||||
bun run serve # 或 npm run serve
|
||||
|
||||
# 默认访问地址：
|
||||
# 管理端：http://localhost:4173
|
||||
# 用户端：http://localhost:4173
|
||||
```
|
||||
|
||||
### 方式二：使用 Vercel 一键部署
|
||||
|
||||
#### 管理端部署
|
||||
|
||||
点击下方按钮一键部署到 Vercel：
|
||||
|
||||
[](https://vercel.com/new/clone?demo-description=PPanel%20is%20a%20pure%2C%20professional%2C%20and%20perfect%20open-source%20proxy%20panel%20tool&demo-image=https%3A%2F%2Furlscan.io%2Fliveshot%2F%3Fwidth%3D1920%26height%3D1080%26url%3Dhttps%3A%2F%2Fadmin.ppanel.dev&demo-title=PPanel%20Admin%20Web&repository-url=https%3A%2F%2Fgithub.com%2Fperfect-panel%2Ffrontend&root-directory=apps%2Fadmin)
|
||||
|
||||
#### 用户端部署
|
||||
|
||||
[](https://vercel.com/new/clone?demo-description=PPanel%20is%20a%20pure%2C%20professional%2C%20and%20perfect%20open-source%20proxy%20panel%20tool&demo-image=https%3A%2F%2Furlscan.io%2Fliveshot%2F%3Fwidth%3D1920%26height%3D1080%26url%3Dhttps%3A%2F%2Fuser.ppanel.dev&demo-title=PPanel%20User%20Web&repository-url=https%3A%2F%2Fgithub.com%2Fperfect-panel%2Ffrontend&root-directory=apps%2Fuser)
|
||||
|
||||
部署后在 Vercel 控制台配置环境变量：
|
||||
- `VITE_API_BASE_URL`: 你的后端 API 地址
|
||||
- `VITE_CDN_URL`: CDN 地址（可选）
|
||||
|
||||
### 方式三：使用 Netlify 部署
|
||||
|
||||
#### 1. 安装 Netlify CLI
|
||||
|
||||
```bash
|
||||
npm install -g netlify-cli
|
||||
```
|
||||
|
||||
#### 2. 登录 Netlify
|
||||
|
||||
```bash
|
||||
netlify login
|
||||
```
|
||||
|
||||
#### 3. 部署应用
|
||||
|
||||
```bash
|
||||
# 管理端
|
||||
cd apps/admin
|
||||
bun run build
|
||||
netlify deploy --prod --dir=dist
|
||||
|
||||
# 用户端
|
||||
cd apps/user
|
||||
bun run build
|
||||
netlify deploy --prod --dir=dist
|
||||
```
|
||||
|
||||
#### 4. 配置环境变量
|
||||
|
||||
在 Netlify 控制台的 Site settings → Build & deploy → Environment 中添加：
|
||||
- `VITE_API_BASE_URL`
|
||||
- `VITE_CDN_URL`
|
||||
|
||||
### 方式四：使用 Cloudflare Pages
|
||||
|
||||
#### 1. 连接 GitHub 仓库
|
||||
|
||||
登录 Cloudflare Dashboard → Workers & Pages → Create application → Pages → Connect to Git
|
||||
|
||||
#### 2. 配置构建设置
|
||||
|
||||
**管理端**：
|
||||
- **Framework preset**: None
|
||||
- **Build command**: `cd .. && bun install && cd apps/admin && bun run build`
|
||||
- **Build output directory**: `apps/admin/dist`
|
||||
- **Root directory**: `apps/admin`
|
||||
|
||||
**用户端**：
|
||||
- **Framework preset**: None
|
||||
- **Build command**: `cd .. && bun install && cd apps/user && bun run build`
|
||||
- **Build output directory**: `apps/user/dist`
|
||||
- **Root directory**: `apps/user`
|
||||
|
||||
#### 3. 配置环境变量
|
||||
|
||||
在 Settings → Environment variables 中添加：
|
||||
- `VITE_API_BASE_URL`
|
||||
- `VITE_CDN_URL`
|
||||
|
||||
## 自建服务器部署
|
||||
|
||||
### 使用 Nginx
|
||||
|
||||
#### 1. 安装 Nginx
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install nginx -y
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install nginx -y
|
||||
```
|
||||
|
||||
#### 2. 上传构建文件
|
||||
|
||||
```bash
|
||||
# 创建目录
|
||||
sudo mkdir -p /var/www/ppanel/{admin,user}
|
||||
|
||||
# 上传构建文件
|
||||
sudo cp -r apps/admin/dist/* /var/www/ppanel/admin/
|
||||
sudo cp -r apps/user/dist/* /var/www/ppanel/user/
|
||||
|
||||
# 设置权限
|
||||
sudo chown -R www-data:www-data /var/www/ppanel
|
||||
```
|
||||
|
||||
#### 3. 配置 Nginx
|
||||
|
||||
**管理端配置** (`/etc/nginx/sites-available/ppanel-admin`)：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name admin.your-domain.com;
|
||||
|
||||
root /var/www/ppanel/admin;
|
||||
index index.html;
|
||||
|
||||
# Gzip 压缩
|
||||
gzip on;
|
||||
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
|
||||
gzip_vary on;
|
||||
gzip_min_length 1024;
|
||||
|
||||
# 静态资源缓存
|
||||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
|
||||
expires 1y;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
# SPA 路由支持
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
|
||||
# 安全头
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
add_header Referrer-Policy "no-referrer-when-downgrade" always;
|
||||
}
|
||||
```
|
||||
|
||||
**用户端配置** (`/etc/nginx/sites-available/ppanel-user`)：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name user.your-domain.com;
|
||||
|
||||
root /var/www/ppanel/user;
|
||||
index index.html;
|
||||
|
||||
# 其他配置同管理端
|
||||
gzip on;
|
||||
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
|
||||
|
||||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
|
||||
expires 1y;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 启用站点
|
||||
|
||||
```bash
|
||||
# 启用站点
|
||||
sudo ln -s /etc/nginx/sites-available/ppanel-admin /etc/nginx/sites-enabled/
|
||||
sudo ln -s /etc/nginx/sites-available/ppanel-user /etc/nginx/sites-enabled/
|
||||
|
||||
# 测试配置
|
||||
sudo nginx -t
|
||||
|
||||
# 重载 Nginx
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
#### 5. 配置 HTTPS（推荐）
|
||||
|
||||
使用 Certbot 自动配置 SSL 证书：
|
||||
|
||||
```bash
|
||||
# 安装 Certbot
|
||||
sudo apt install certbot python3-certbot-nginx -y
|
||||
|
||||
# 获取证书
|
||||
sudo certbot --nginx -d admin.your-domain.com
|
||||
sudo certbot --nginx -d user.your-domain.com
|
||||
|
||||
# 自动续期
|
||||
sudo certbot renew --dry-run
|
||||
```
|
||||
|
||||
### 使用 Caddy
|
||||
|
||||
Caddy 自动处理 HTTPS，配置更简单。
|
||||
|
||||
#### 1. 安装 Caddy
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
|
||||
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
|
||||
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
|
||||
sudo apt update
|
||||
sudo apt install caddy
|
||||
```
|
||||
|
||||
#### 2. 配置 Caddyfile
|
||||
|
||||
创建 `/etc/caddy/Caddyfile`：
|
||||
|
||||
```caddy
|
||||
admin.your-domain.com {
|
||||
root * /var/www/ppanel/admin
|
||||
encode gzip
|
||||
file_server
|
||||
|
||||
try_files {path} /index.html
|
||||
|
||||
@static {
|
||||
path *.js *.css *.png *.jpg *.jpeg *.gif *.ico *.svg *.woff *.woff2 *.ttf *.eot
|
||||
}
|
||||
header @static Cache-Control "public, max-age=31536000, immutable"
|
||||
|
||||
header {
|
||||
X-Frame-Options "SAMEORIGIN"
|
||||
X-Content-Type-Options "nosniff"
|
||||
X-XSS-Protection "1; mode=block"
|
||||
}
|
||||
}
|
||||
|
||||
user.your-domain.com {
|
||||
root * /var/www/ppanel/user
|
||||
encode gzip
|
||||
file_server
|
||||
|
||||
try_files {path} /index.html
|
||||
|
||||
@static {
|
||||
path *.js *.css *.png *.jpg *.jpeg *.gif *.ico *.svg *.woff *.woff2 *.ttf *.eot
|
||||
}
|
||||
header @static Cache-Control "public, max-age=31536000, immutable"
|
||||
|
||||
header {
|
||||
X-Frame-Options "SAMEORIGIN"
|
||||
X-Content-Type-Options "nosniff"
|
||||
X-XSS-Protection "1; mode=block"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 启动 Caddy
|
||||
|
||||
```bash
|
||||
sudo systemctl restart caddy
|
||||
sudo systemctl enable caddy
|
||||
```
|
||||
|
||||
## 配置 CDN
|
||||
|
||||
### Cloudflare 配置
|
||||
|
||||
1. 添加域名到 Cloudflare
|
||||
2. 配置 DNS 记录指向源服务器
|
||||
3. 启用以下优化选项：
|
||||
- **Auto Minify**: 启用 JavaScript、CSS、HTML 压缩
|
||||
- **Brotli**: 启用 Brotli 压缩
|
||||
- **Rocket Loader**: 启用 JS 异步加载（可选）
|
||||
- **Caching Level**: 设置为 Standard
|
||||
|
||||
4. 配置页面规则：
|
||||
```
|
||||
*your-domain.com/*
|
||||
- Cache Level: Cache Everything
|
||||
- Edge Cache TTL: 1 month
|
||||
- Browser Cache TTL: Respect Existing Headers
|
||||
```
|
||||
|
||||
### 阿里云 CDN
|
||||
|
||||
1. 创建 CDN 加速域名
|
||||
2. 配置源站：指向前端服务器
|
||||
3. 配置缓存规则：
|
||||
- 静态文件（js, css, 图片）：缓存 1 年
|
||||
- HTML 文件：缓存 5 分钟或不缓存
|
||||
4. 启用 HTTPS 和 HTTP/2
|
||||
|
||||
## 环境变量说明
|
||||
|
||||
| 变量名 | 说明 | 必需 | 默认值 | 示例 |
|
||||
|--------|------|------|--------|------|
|
||||
| `VITE_API_BASE_URL` | 后端 API 地址 | ✅ | - | `https://api.your-domain.com` |
|
||||
| `VITE_CDN_URL` | CDN 地址 | ❌ | `https://cdn.jsdmirror.com` | `https://cdn.your-domain.com` |
|
||||
| `VITE_TUTORIAL_DOCUMENT` | 启用教程文档 | ❌ | `true` | `true` / `false` |
|
||||
| `VITE_USER_EMAIL` | 默认登录邮箱（仅开发） | ❌ | - | - |
|
||||
| `VITE_USER_PASSWORD` | 默认登录密码（仅开发） | ❌ | - | - |
|
||||
|
||||
## 验证部署
|
||||
|
||||
### 检查前端服务
|
||||
|
||||
```bash
|
||||
# 访问前端地址
|
||||
curl -I https://admin.your-domain.com
|
||||
curl -I https://user.your-domain.com
|
||||
|
||||
# 预期输出
|
||||
# HTTP/2 200
|
||||
# content-type: text/html
|
||||
```
|
||||
|
||||
### 检查 API 连接
|
||||
|
||||
在浏览器中打开前端地址，打开开发者工具：
|
||||
|
||||
1. 查看 Network 标签
|
||||
2. 检查到 API 的请求是否成功
|
||||
3. 确认请求地址正确（`https://api.your-domain.com`）
|
||||
4. 查看响应数据是否正常
|
||||
|
||||
### 检查构建版本
|
||||
|
||||
访问 `/version.lock` 文件查看当前部署的版本：
|
||||
|
||||
```bash
|
||||
curl https://admin.your-domain.com/version.lock
|
||||
# 输出示例: 1.2.0
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 1. 启用 HTTP/2
|
||||
|
||||
在 Nginx 中：
|
||||
|
||||
```nginx
|
||||
listen 443 ssl http2;
|
||||
```
|
||||
|
||||
### 2. 启用 Brotli 压缩
|
||||
|
||||
```bash
|
||||
# 安装 Nginx Brotli 模块
|
||||
sudo apt install libnginx-mod-http-brotli-filter libnginx-mod-http-brotli-static -y
|
||||
```
|
||||
|
||||
在 Nginx 配置中：
|
||||
|
||||
```nginx
|
||||
brotli on;
|
||||
brotli_types text/plain text/css application/json application/javascript text/xml application/xml;
|
||||
brotli_comp_level 6;
|
||||
```
|
||||
|
||||
### 3. 预加载关键资源
|
||||
|
||||
构建时 Vite 已自动处理，会在 `index.html` 中添加 `<link rel="modulepreload">`。
|
||||
|
||||
### 4. 启用 Service Worker
|
||||
|
||||
前端已内置 PWA 支持，构建后自动启用 Service Worker 缓存。
|
||||
|
||||
### 5. 使用 CDN 加速
|
||||
|
||||
配置 `VITE_CDN_URL` 环境变量，将静态资源加载从 CDN 获取。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### API 请求失败
|
||||
|
||||
**问题**: 前端无法连接到后端 API
|
||||
|
||||
**解决方案**:
|
||||
1. 检查 `VITE_API_BASE_URL` 是否正确配置
|
||||
2. 检查后端 CORS 配置是否允许前端域名
|
||||
3. 打开浏览器控制台查看具体错误信息
|
||||
4. 使用 `curl` 测试后端 API 是否可访问
|
||||
|
||||
```bash
|
||||
curl https://api.your-domain.com/api/health
|
||||
```
|
||||
|
||||
### 页面路由 404
|
||||
|
||||
**问题**: 刷新页面或直接访问子路由返回 404
|
||||
|
||||
**解决方案**: 确保 Web 服务器配置了 SPA 回退
|
||||
|
||||
```nginx
|
||||
# Nginx
|
||||
try_files $uri $uri/ /index.html;
|
||||
|
||||
# Apache (.htaccess)
|
||||
RewriteEngine On
|
||||
RewriteBase /
|
||||
RewriteRule ^index\.html$ - [L]
|
||||
RewriteCond %{REQUEST_FILENAME} !-f
|
||||
RewriteCond %{REQUEST_FILENAME} !-d
|
||||
RewriteRule . /index.html [L]
|
||||
```
|
||||
|
||||
### 静态资源加载失败
|
||||
|
||||
**问题**: JS/CSS 文件 404 或无法加载
|
||||
|
||||
**解决方案**:
|
||||
1. 检查文件权限
|
||||
2. 检查 Nginx `root` 路径是否正确
|
||||
3. 清除浏览器缓存
|
||||
4. 检查 CDN 配置
|
||||
|
||||
### 构建失败
|
||||
|
||||
**问题**: `bun run build` 或 `npm run build` 失败
|
||||
|
||||
**解决方案**:
|
||||
1. 确保 Node.js 版本 >= 20
|
||||
2. 删除 `node_modules` 和锁文件，重新安装
|
||||
```bash
|
||||
rm -rf node_modules bun.lockb
|
||||
bun install
|
||||
```
|
||||
3. 检查是否有语法错误或类型错误
|
||||
```bash
|
||||
bun run check
|
||||
```
|
||||
|
||||
## 更新部署
|
||||
|
||||
### 从源码更新
|
||||
|
||||
```bash
|
||||
# 拉取最新代码
|
||||
git pull origin main
|
||||
|
||||
# 重新安装依赖
|
||||
bun install
|
||||
|
||||
# 重新构建
|
||||
bun run build
|
||||
|
||||
# 更新文件
|
||||
sudo rm -rf /var/www/ppanel/admin
|
||||
sudo rm -rf /var/www/ppanel/user
|
||||
sudo cp -r apps/admin/dist /var/www/ppanel/admin
|
||||
sudo cp -r apps/user/dist /var/www/ppanel/user
|
||||
|
||||
# 清除 CDN 缓存（如使用 CDN）
|
||||
```
|
||||
|
||||
### Vercel 更新
|
||||
|
||||
Vercel 会自动监听 GitHub 仓库变动并自动部署。也可以手动触发：
|
||||
|
||||
```bash
|
||||
vercel --prod
|
||||
```
|
||||
|
||||
### Netlify 更新
|
||||
|
||||
```bash
|
||||
cd apps/admin # 或 apps/user
|
||||
bun run build
|
||||
netlify deploy --prod
|
||||
```
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **启用 HTTPS**: 必须使用 SSL/TLS 证书
|
||||
2. **配置 CSP**: 内容安全策略
|
||||
```nginx
|
||||
add_header Content-Security-Policy "default-src 'self'; connect-src 'self' https://api.your-domain.com; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval';";
|
||||
```
|
||||
3. **设置安全头**: 已在 Nginx 配置中包含
|
||||
4. **禁用目录浏览**: `Options -Indexes` (Apache) 或 `autoindex off;` (Nginx)
|
||||
5. **限制文件上传大小**:
|
||||
```nginx
|
||||
client_max_body_size 10M;
|
||||
```
|
||||
|
||||
## 监控和分析
|
||||
|
||||
### 添加网站分析
|
||||
|
||||
支持 Google Analytics、Umami、Plausible 等。
|
||||
|
||||
配置方式：在 `index.html` 中添加追踪代码，或使用环境变量配置。
|
||||
|
||||
### 错误追踪
|
||||
|
||||
前端支持集成 Sentry 进行错误追踪（需要在代码中配置）。
|
||||
|
||||
## 开发和生产环境
|
||||
|
||||
### 本地开发
|
||||
|
||||
```bash
|
||||
# 使用开发服务器
|
||||
cd apps/admin # 或 apps/user
|
||||
bun run dev
|
||||
|
||||
# 管理端默认运行在 http://localhost:3001
|
||||
# 用户端默认运行在 http://localhost:3000
|
||||
```
|
||||
|
||||
开发环境会使用 Vite 的代理功能，将 API 请求代理到后端。
|
||||
|
||||
### 预览生产构建
|
||||
|
||||
```bash
|
||||
# 构建后预览
|
||||
bun run build
|
||||
bun run serve
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [后端分离部署](./backend.md) - 如果还未部署后端
|
||||
- [节点端安装](../node/installation.md) - 部署节点服务
|
||||
- [功能文档](/zh/admin/dashboard) - 了解功能使用
|
||||
Reference in New Issue
Block a user