📝 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,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：
+
+[![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) - 了解功能使用