vf_react/docs/DEPLOYMENT.md

# VF React 自动化部署指南

## 📋 目录

- [概述](#概述)
- [快速开始](#快速开始)
- [详细使用说明](#详细使用说明)
- [配置说明](#配置说明)
- [故障排查](#故障排查)
- [FAQ](#faq)

---

## 概述

本项目提供了完整的自动化部署方案，让您可以在本地电脑一键部署到生产环境，无需登录服务器。

### 核心特性

- ✅ **本地一键部署** - 运行 `npm run deploy` 即可完成部署
- ✅ **智能备份** - 每次部署前自动备份，保留最近 5 个版本
- ✅ **快速回滚** - 10 秒内回滚到任意历史版本
- ✅ **企业微信通知** - 部署成功/失败实时推送消息
- ✅ **安全可靠** - 部署前确认，失败自动回滚
- ✅ **详细日志** - 完整记录每次部署过程

---

## 快速开始

### 1. 首次配置（5 分钟）

运行配置向导，按提示输入配置信息：

```bash
npm run deploy:setup
```

配置向导会询问：
- 服务器地址和 SSH 信息
- 部署路径配置
- 企业微信通知配置（可选）

配置完成后会自动初始化服务器环境。

### 2. 日常部署（2-3 分钟）

```bash
npm run deploy
```

执行后会：
1. 检查本地代码状态
2. 显示部署预览，需要输入 `yes` 确认
3. 自动连接服务器
4. 拉取代码、构建、部署
5. 发送企业微信通知

### 3. 回滚版本（10 秒）

回滚到上一个版本：
```bash
npm run rollback
```

回滚到指定版本：
```bash
npm run rollback -- 2  # 回滚到前 2 个版本
```

查看可回滚的版本列表：
```bash
npm run rollback -- list
```

---

## 详细使用说明

### 首次配置

#### 运行配置向导

```bash
npm run deploy:setup
```

#### 配置过程

**1. 服务器配置**
```
请输入服务器 IP 或域名: your-server.com
请输入 SSH 用户名 [ubuntu]: ubuntu
请输入 SSH 端口 [22]: 22
检测到 SSH 密钥: ~/.ssh/id_rsa
是否使用该密钥? (y/n) [y]: y

正在测试 SSH 连接...
✓ SSH 连接测试成功
```

**2. 部署路径配置**
```
Git 仓库路径 [/home/ubuntu/vf_react]:
生产环境路径 [/var/www/valuefrontier.cn]:
备份目录 [/home/ubuntu/deployments]:
日志目录 [/home/ubuntu/deploy-logs]:
部署分支 [feature]:
保留备份数量 [5]:
```

**3. 企业微信通知配置**
```
是否启用企业微信通知? (y/n) [n]: y
请输入企业微信 Webhook URL: https://qyapi.weixin.qq.com/...

正在测试企业微信通知...
✓ 企业微信通知测试成功
```

**4. 初始化服务器**
```
正在创建服务器目录...
✓ 服务器目录创建完成
设置脚本执行权限...
✓ 服务器环境初始化完成
```

### 部署到生产环境

#### 执行部署

```bash
npm run deploy
```

#### 部署流程

**步骤 1: 检查本地代码**
```
[1/8] 检查本地代码
当前分支: feature
最新提交: c93f689 - feat: 添加消息推送能力
提交作者: qiye
✓ 本地代码检查完成
```

**步骤 2: 显示部署预览**
```
[2/8] 部署预览

╔════════════════════════════════════════════════════════════════╗
║                         部署预览                                ║
╚════════════════════════════════════════════════════════════════╝

项目信息:
  项目名称: vf_react
  部署环境: 生产环境
  目标服务器: ubuntu@your-server.com

代码信息:
  当前分支: feature
  提交版本: c93f689
  提交信息: feat: 添加消息推送能力
  提交作者: qiye

部署路径:
  Git 仓库: /home/ubuntu/vf_react
  生产目录: /var/www/valuefrontier.cn

════════════════════════════════════════════════════════════════

确认部署到生产环境? (yes/no): yes
```

**步骤 3-7: 自动执行部署**
```
[3/8] 测试 SSH 连接
✓ SSH 连接成功

[4/8] 上传部署脚本
✓ 部署脚本上传完成

[5/8] 执行远程部署

========================================
  服务器端部署脚本
========================================

[INFO] 创建必要的目录...
[SUCCESS] 目录创建完成
[INFO] 检查 Git 仓库...
[SUCCESS] Git 仓库检查通过
[INFO] 切换到 feature 分支...
[SUCCESS] 已在 feature 分支
[INFO] 拉取最新代码...
[SUCCESS] 代码更新完成
[INFO] 安装依赖...
[SUCCESS] 依赖检查完成
[INFO] 构建项目...
[SUCCESS] 构建完成
[INFO] 备份当前版本...
[SUCCESS] 备份完成: /home/ubuntu/deployments/backup-20250121-143020
[INFO] 部署到生产环境...
[SUCCESS] 部署完成
[INFO] 清理旧备份...
[SUCCESS] 旧备份清理完成

========================================
  部署成功！
========================================
提交: c93f689 - feat: 添加消息推送能力
备份: /home/ubuntu/deployments/backup-20250121-143020
耗时: 2分15秒

✓ 远程部署完成

[6/8] 发送部署通知
✓ 企业微信通知已发送

[7/8] 清理临时文件
✓ 清理完成

[8/8] 部署完成

╔════════════════════════════════════════════════════════════════╗
║                      🎉 部署成功！                              ║
╚════════════════════════════════════════════════════════════════╝

部署信息:
  版本: c93f689
  分支: feature
  提交: feat: 添加消息推送能力
  作者: qiye
  时间: 2025-01-21 14:33:45
  耗时: 2分15秒

访问地址:
  https://valuefrontier.cn
```

### 版本回滚

#### 查看可回滚的版本

```bash
npm run rollback -- list
```

输出：
```
可用的备份版本：

  1. backup-20250121-153045 (2025-01-21 15:30:45) [当前版本]
  2. backup-20250121-150030 (2025-01-21 15:00:30)
  3. backup-20250121-143020 (2025-01-21 14:30:20)
  4. backup-20250121-140010 (2025-01-21 14:00:10)
  5. backup-20250121-133000 (2025-01-21 13:30:00)
```

#### 回滚到上一个版本

```bash
npm run rollback
```

或指定版本：
```bash
npm run rollback -- 2  # 回滚到第 2 个版本
```

#### 回滚流程

```
╔════════════════════════════════════════════════════════════════╗
║                       版本回滚工具                              ║
╚════════════════════════════════════════════════════════════════╝

可用的备份版本：
  1. backup-20250121-153045 (2025-01-21 15:30:45) [当前版本]
  2. backup-20250121-150030 (2025-01-21 15:00:30)
  3. backup-20250121-143020 (2025-01-21 14:30:20)

确认回滚到版本 #2? (yes/no): yes

[INFO] 正在执行回滚...

========================================
  服务器端回滚脚本
========================================

[INFO] 开始回滚到版本 #2...
[INFO] 目标版本: backup-20250121-150030
[INFO] 清空生产目录: /var/www/valuefrontier.cn
[INFO] 恢复备份文件...
[SUCCESS] 回滚完成

========================================
  回滚成功！
========================================
目标版本: backup-20250121-150030

╔════════════════════════════════════════════════════════════════╗
║                     🎉 回滚成功！                               ║
╚════════════════════════════════════════════════════════════════╝

回滚信息:
  目标版本: backup-20250121-150030
  回滚时间: 2025-01-21 15:35:20

访问地址:
  https://valuefrontier.cn
```

---

## 配置说明

### 配置文件位置

```
.env.deploy          # 部署配置文件（不提交到 Git）
.env.deploy.example  # 配置文件示例
```

### 配置项说明

#### 服务器配置

```bash
# 服务器 IP 或域名
SERVER_HOST=your-server.com

# SSH 用户名
SERVER_USER=ubuntu

# SSH 端口（默认 22）
SERVER_PORT=22

# SSH 密钥路径（留空使用默认 ~/.ssh/id_rsa）
SSH_KEY_PATH=
```

#### 路径配置

```bash
# 服务器上的 Git 仓库路径
REMOTE_PROJECT_PATH=/home/ubuntu/vf_react

# 生产环境部署路径
PRODUCTION_PATH=/var/www/valuefrontier.cn

# 部署备份目录
BACKUP_DIR=/home/ubuntu/deployments

# 部署日志目录
LOG_DIR=/home/ubuntu/deploy-logs
```

#### Git 配置

```bash
# 部署分支
DEPLOY_BRANCH=feature
```

#### 备份配置

```bash
# 保留备份数量（超过会自动删除最旧的）
KEEP_BACKUPS=5
```

#### 企业微信通知配置

```bash
# 是否启用企业微信通知
ENABLE_WECHAT_NOTIFY=true

# 企业微信机器人 Webhook URL
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxx

# 通知提及的用户（@all 或手机号/userid，逗号分隔）
WECHAT_MENTIONED_LIST=@all
```

#### 部署配置

```bash
# 是否在部署前运行 npm install
RUN_NPM_INSTALL=true

# 是否在部署前运行 npm test
RUN_NPM_TEST=false

# 构建命令
BUILD_COMMAND=npm run build
```

### 修改配置

编辑配置文件：
```bash
vim .env.deploy
```

或使用编辑器打开 `.env.deploy` 文件。

---

## 企业微信通知

### 配置企业微信机器人

1. **打开企业微信群聊**
2. **添加群机器人**
   - 点击群设置（右上角 ···）
   - 选择"群机器人"
   - 点击"添加机器人"
3. **设置机器人信息**
   - 输入机器人名称（如：部署通知机器人）
   - 复制 Webhook URL
4. **配置到项目**
   - 将 Webhook URL 粘贴到 `.env.deploy` 文件的 `WECHAT_WEBHOOK_URL` 字段

### 通知内容

#### 部署成功通知
```
【生产环境部署成功】
项目：vf_react
环境：生产环境
分支：feature
版本：c93f689
提交信息：feat: 添加消息推送能力
部署时间：2025-01-21 14:33:45
部署耗时：2分15秒
操作人：qiye
访问地址：https://valuefrontier.cn
```

#### 部署失败通知
```
【⚠️ 生产环境部署失败】
项目：vf_react
环境：生产环境
分支：feature
失败原因：构建失败
失败时间：2025-01-21 14:35:20
操作人：qiye
已自动回滚到上一版本
```

#### 回滚成功通知
```
【版本回滚成功】
项目：vf_react
环境：生产环境
回滚版本：backup-20250121-150030
回滚时间：2025-01-21 15:35:20
操作人：qiye
```

---

## 故障排查

### 常见问题

#### 1. SSH 连接失败

**错误信息**：
```
[✗] SSH 连接失败
```

**可能原因**：
- 服务器地址、用户名或端口配置错误
- SSH 密钥未配置或路径错误
- 服务器防火墙阻止连接

**解决方法**：
1. 检查配置文件 `.env.deploy` 中的服务器信息
2. 测试 SSH 连接：
   ```bash
   ssh ubuntu@your-server.com
   ```
3. 确认 SSH 密钥已添加到服务器：
   ```bash
   ssh-copy-id ubuntu@your-server.com
   ```

#### 2. 构建失败

**错误信息**：
```
[ERROR] 构建失败
npm run build exited with code 1
```

**可能原因**：
- 代码存在语法错误
- 依赖包版本不兼容
- Node.js 版本不匹配

**解决方法**：
1. 在本地先运行构建测试：
   ```bash
   npm run build
   ```
2. 检查并修复错误
3. 确认服务器 Node.js 版本：
   ```bash
   ssh ubuntu@your-server.com "node -v"
   ```

#### 3. 权限不足

**错误信息**：
```
[ERROR] 复制文件失败
Permission denied
```

**可能原因**：
- 对生产目录没有写权限
- 需要 sudo 权限

**解决方法**：
1. 检查生产目录权限：
   ```bash
   ssh ubuntu@your-server.com "ls -ld /var/www/valuefrontier.cn"
   ```
2. 修改目录所有者：
   ```bash
   ssh ubuntu@your-server.com "sudo chown -R ubuntu:ubuntu /var/www/valuefrontier.cn"
   ```

#### 4. 企业微信通知发送失败

**错误信息**：
```
[⚠] 企业微信通知发送失败
```

**可能原因**：
- Webhook URL 错误
- 网络问题

**解决方法**：
1. 检查 Webhook URL 是否正确
2. 手动测试通知：
   ```bash
   bash scripts/notify-wechat.sh test
   ```

---

## FAQ

### Q1: 部署会影响正在访问网站的用户吗？

A: 部署过程中会有短暂的服务中断（约 1-2 秒），建议在流量较低时进行部署。

### Q2: 如果部署过程中网络断开怎么办？

A: 脚本会自动检测错误并停止部署。由于有自动备份，可以安全地重新运行部署或执行回滚。

### Q3: 可以同时部署多个项目吗？

A: 不建议。请等待当前部署完成后再部署其他项目。

### Q4: 备份文件占用空间过大怎么办？

A: 可以修改 `.env.deploy` 中的 `KEEP_BACKUPS` 配置，减少保留的备份数量。

### Q5: 如何查看详细的部署日志？

A: 部署日志保存在服务器上：
```bash
ssh ubuntu@your-server.com "cat /home/ubuntu/deploy-logs/deploy-YYYYMMDD-HHMMSS.log"
```

### Q6: 可以在 Windows 上使用吗？

A: 可以。脚本使用标准的 Bash 命令，在 Git Bash 或 WSL 中都可以正常运行。

### Q7: 如何禁用企业微信通知？

A: 编辑 `.env.deploy` 文件，将 `ENABLE_WECHAT_NOTIFY` 设置为 `false`。

### Q8: 部署失败后是否需要手动回滚？

A: 不需要。如果构建失败，脚本会自动回滚到上一个版本。

---

## 目录结构

```
vf_react/
├── scripts/                          # 部署脚本目录
│   ├── setup-deployment.sh          # 配置向导
│   ├── deploy-from-local.sh         # 本地部署脚本
│   ├── deploy-on-server.sh          # 服务器部署脚本
│   ├── rollback-from-local.sh       # 本地回滚脚本
│   ├── rollback-on-server.sh        # 服务器回滚脚本
│   └── notify-wechat.sh             # 企业微信通知脚本
├── .env.deploy.example              # 配置文件示例
├── .env.deploy                      # 配置文件（不提交到 Git）
├── DEPLOYMENT.md                    # 本文档
└── package.json                     # 包含部署命令
```

**服务器目录结构**：
```
/home/ubuntu/
├── vf_react/                        # Git 仓库
│   └── build/                       # 构建产物
├── deployments/                     # 版本备份
│   ├── backup-20250121-143020/
│   ├── backup-20250121-150030/
│   └── current -> backup-20250121-150030
└── deploy-logs/                     # 部署日志
    └── deploy-20250121-143020.log
```

---

## 命令速查表

| 命令 | 说明 |
|------|------|
| `npm run deploy:setup` | 首次配置部署环境 |
| `npm run deploy` | 部署到生产环境 |
| `npm run rollback` | 回滚到上一个版本 |
| `npm run rollback -- 2` | 回滚到前 2 个版本 |
| `npm run rollback -- list` | 查看可回滚的版本列表 |

---

## 支持

如有问题，请联系开发团队或提交 Issue。

---

**祝部署顺利！** 🎉