shop-front-end/doc/部署和维护指南.md

# 部署和维护指南

## 部署流程

### 1. 环境准备

#### 服务器要求
- **操作系统**: Linux (推荐 Ubuntu 20.04+ 或 CentOS 7+)
- **Web 服务器**: Nginx 1.18+
- **Node.js**: 16.0+
- **内存**: 至少 2GB
- **存储**: 至少 10GB 可用空间

#### 软件安装

```bash
# 安装 Node.js (使用 NodeSource 仓库)
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 pnpm
npm install -g pnpm

# 安装 Nginx
sudo apt update
sudo apt install nginx
```

### 2. 项目部署

#### 构建项目

```bash
# 克隆项目
git clone <repository-url>
cd shop-front-end

# 安装依赖
pnpm install

# 构建生产版本
pnpm build
```

#### 配置 Nginx

创建 Nginx 配置文件 `/etc/nginx/sites-available/shop-frontend`:

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/shop-front-end/dist;
    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;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # API 代理
    location /api/ {
        proxy_pass http://backend-server: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;
    }
}
```

启用站点配置:

```bash
sudo ln -s /etc/nginx/sites-available/shop-frontend /etc/nginx/sites-enabled/
sudo nginx -t  # 测试配置
sudo systemctl reload nginx  # 重新加载配置
```

#### 配置 SSL (可选)

使用 Let's Encrypt 配置 HTTPS:

```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com
```

### 3. 环境配置

#### 环境变量

创建 `.env.production` 文件:

```env
VITE_API_BASE_URL=https://your-api-domain.com
VITE_ROUTER_HISTORY=history
VITE_PUBLIC_PATH=/
VITE_HIDE_HOME=false
```

#### 服务器配置文件

在 `public/` 目录下创建 `serverConfig.json`:

```json
{
  "Title": "智能柜管理系统",
  "FixedHeader": true,
  "HiddenSideBar": false,
  "MultiTagsCache": false,
  "KeepAlive": true,
  "Locale": "zh",
  "Layout": "vertical",
  "Theme": "default",
  "DarkMode": false,
  "Grey": false,
  "Weak": false,
  "HideTabs": false,
  "HideFooter": false,
  "SidebarStatus": true,
  "EpThemeColor": "#409EFF",
  "ShowLogo": true,
  "ShowModel": "smart",
  "MenuArrowIconNoTransition": false,
  "CachingAsyncRoutes": false,
  "ResponsiveStorageNameSpace": "responsive-"
}
```

## 维护操作

### 1. 日常维护

#### 日志监控

```bash
# 查看 Nginx 访问日志
tail -f /var/log/nginx/access.log

# 查看 Nginx 错误日志
tail -f /var/log/nginx/error.log

# 查看系统日志
journalctl -u nginx -f
```

#### 性能监控

```bash
# 查看系统资源使用
top
htop

# 查看磁盘使用
df -h

# 查看内存使用
free -h
```

### 2. 备份策略

#### 代码备份

```bash
# 备份项目代码
tar -czf shop-frontend-backup-$(date +%Y%m%d).tar.gz /path/to/shop-front-end

# 备份 Nginx 配置
tar -czf nginx-config-backup-$(date +%Y%m%d).tar.gz /etc/nginx/
```

#### 自动化备份脚本

创建备份脚本 `/opt/scripts/backup.sh`:

```bash
#!/bin/bash

# 备份目录
BACKUP_DIR="/opt/backups"
DATE=$(date +%Y%m%d)

# 创建备份目录
mkdir -p $BACKUP_DIR/$DATE

# 备份项目代码
tar -czf $BACKUP_DIR/$DATE/shop-frontend.tar.gz /path/to/shop-front-end

# 备份 Nginx 配置
tar -czf $BACKUP_DIR/$DATE/nginx-config.tar.gz /etc/nginx/

# 删除 30 天前的备份
find $BACKUP_DIR -type d -mtime +30 -exec rm -rf {} \;

echo "Backup completed: $BACKUP_DIR/$DATE"
```

设置定时任务:

```bash
# 编辑 crontab
crontab -e

# 添加每天凌晨 2 点执行备份
0 2 * * * /opt/scripts/backup.sh
```

### 3. 更新流程

#### 手动更新

```bash
# 进入项目目录
cd /path/to/shop-front-end

# 拉取最新代码
git pull origin master

# 安装依赖
pnpm install

# 构建新版本
pnpm build

# 重启 Nginx
sudo systemctl reload nginx
```

#### 自动化更新脚本

创建更新脚本 `/opt/scripts/update.sh`:

```bash
#!/bin/bash

# 项目目录
PROJECT_DIR="/path/to/shop-front-end"
LOG_FILE="/var/log/shop-frontend-update.log"

# 记录开始时间
echo "$(date): Starting update process" >> $LOG_FILE

# 进入项目目录
cd $PROJECT_DIR

# 拉取最新代码
echo "$(date): Pulling latest code" >> $LOG_FILE
git pull origin master

# 安装依赖
echo "$(date): Installing dependencies" >> $LOG_FILE
pnpm install

# 构建项目
echo "$(date): Building project" >> $LOG_FILE
pnpm build

# 重启 Nginx
echo "$(date): Reloading Nginx" >> $LOG_FILE
sudo systemctl reload nginx

echo "$(date): Update completed successfully" >> $LOG_FILE
```

### 4. 故障排除

#### 常见问题及解决方案

**问题 1: 页面显示空白**
- **原因**: 资源加载失败或路由配置错误
- **解决**:
  1. 检查浏览器控制台错误信息
  2. 确认静态资源路径正确
  3. 检查 Nginx 配置中的 try_files 指令

**问题 2: API 请求失败**
- **原因**: 代理配置错误或后端服务不可用
- **解决**:
  1. 检查 Nginx 代理配置
  2. 确认后端服务正常运行
  3. 检查网络连接

**问题 3: 页面刷新 404**
- **原因**: SPA 路由未正确配置
- **解决**:
  1. 确认 Nginx 配置中包含 `try_files $uri $uri/ /index.html;`
  2. 检查 Vue Router 的 history 模式配置

**问题 4: 静态资源加载慢**
- **原因**: 未启用压缩或缓存
- **解决**:
  1. 启用 Nginx gzip 压缩
  2. 配置静态资源缓存头
  3. 考虑使用 CDN

#### 性能优化

**Nginx 性能优化配置:**

```nginx
# /etc/nginx/nginx.conf
http {
    # 基础优化
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        application/atom+xml
        application/javascript
        application/json
        application/ld+json
        application/manifest+json
        application/rss+xml
        application/vnd.geo+json
        application/vnd.ms-fontobject
        application/x-font-ttf
        application/x-web-app-manifest+json
        application/xhtml+xml
        application/xml
        font/opentype
        image/bmp
        image/svg+xml
        image/x-icon
        text/cache-manifest
        text/css
        text/plain
        text/vcard
        text/vnd.rim.location.xloc
        text/vtt
        text/x-component
        text/x-cross-domain-policy;

    # 静态资源缓存
    open_file_cache max=1000 inactive=20s;
    open_file_cache_valid 30s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;
}
```

### 5. 安全配置

#### Nginx 安全配置

```nginx
server {
    # 隐藏 Nginx 版本信息
    server_tokens off;

    # 安全头设置
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    # 限制请求大小
    client_max_body_size 10m;

    # 限制请求速率
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    location /api/ {
        limit_req zone=api burst=20 nodelay;
        # ... 其他配置
    }
}
```

#### 防火墙配置

```bash
# 启用防火墙
sudo ufw enable

# 允许 SSH
sudo ufw allow ssh

# 允许 HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

# 查看防火墙状态
sudo ufw status
```

### 6. 监控和告警

#### 基础监控脚本

创建健康检查脚本 `/opt/scripts/health-check.sh`:

```bash
#!/bin/bash

# 检查 Nginx 服务状态
if ! systemctl is-active --quiet nginx; then
    echo "Nginx is not running" | mail -s "Nginx Alert" admin@example.com
    sudo systemctl restart nginx
fi

# 检查磁盘空间
DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 90 ]; then
    echo "Disk usage is over 90%" | mail -s "Disk Alert" admin@example.com
fi

# 检查内存使用
MEM_USAGE=$(free | awk 'NR==2{printf "%.2f", $3*100/$2}')
if (( $(echo "$MEM_USAGE > 90" | bc -l) )); then
    echo "Memory usage is over 90%" | mail -s "Memory Alert" admin@example.com
fi
```

设置定时监控:

```bash
# 每 5 分钟执行一次健康检查
*/5 * * * * /opt/scripts/health-check.sh
```

## 附录

### 常用命令

```bash
# Nginx 相关
sudo systemctl status nginx    # 查看状态
sudo systemctl start nginx     # 启动
sudo systemctl stop nginx      # 停止
sudo systemctl restart nginx   # 重启
sudo systemctl reload nginx    # 重新加载配置

# 日志相关
sudo journalctl -u nginx -f    # 查看 Nginx 日志
sudo tail -f /var/log/nginx/access.log  # 访问日志
sudo tail -f /var/log/nginx/error.log   # 错误日志

# 系统监控
top                           # 系统资源使用
htop                          # 增强版 top
df -h                         # 磁盘使用
free -h                       # 内存使用
```

### 配置文件位置

- **Nginx 主配置**: `/etc/nginx/nginx.conf`
- **站点配置**: `/etc/nginx/sites-available/`
- **启用站点**: `/etc/nginx/sites-enabled/`
- **Nginx 日志**: `/var/log/nginx/`
- **项目目录**: `/path/to/shop-front-end/`
- **构建输出**: `/path/to/shop-front-end/dist/`

---

**文档版本**: 1.0
**最后更新**: 2025-10-15