📝 docs: Add documentation

2025-12-11 03:29:07 +00:00
parent 50e695a1bb
commit 99e7f6062d
135 changed files with 79115 additions and 8 deletions
@@ -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：
+
+[![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_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) - 了解功能使用