694 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 前端分离部署
本指南将帮助您独立部署 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
# 显示落地页(可选,设为 false 则直接跳转登录页)
VITE_SHOW_LANDING_PAGE=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
[![Deploy with Vercel](https://vercel.com/button)](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)
#### 用户端部署
[![Deploy with Vercel](https://vercel.com/button)](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_SHOW_LANDING_PAGE` | 显示落地页 | ❌ | `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) - 了解功能使用