vf_react/docs/DEPLOYMENT.md

VF React 自动化部署指南

📋 目录

• 概述
• 快速开始
• 详细使用说明
• 配置说明
• 故障排查
• FAQ

---

概述

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

核心特性

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

---

快速开始

1. 首次配置（5 分钟）

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

npm run deploy:setup

配置向导会询问：

• 服务器地址和 SSH 信息
• 部署路径配置
• 企业微信通知配置（可选）

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

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

npm run deploy

执行后会：

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

3. 回滚版本（10 秒）

回滚到上一个版本：

npm run rollback

回滚到指定版本：

npm run rollback -- 2  # 回滚到前 2 个版本

查看可回滚的版本列表：

npm run rollback -- list

---

详细使用说明

首次配置

运行配置向导

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. 初始化服务器

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

部署到生产环境

执行部署

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

版本回滚

查看可回滚的版本

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)

回滚到上一个版本

npm run rollback

或指定版本：

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  # 配置文件示例

配置项说明

服务器配置

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

# SSH 用户名
SERVER_USER=ubuntu

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

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

路径配置

# 服务器上的 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 配置

# 部署分支
DEPLOY_BRANCH=feature

备份配置

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

企业微信通知配置

# 是否启用企业微信通知
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

部署配置

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

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

# 构建命令
BUILD_COMMAND=npm run build

修改配置

编辑配置文件：

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 连接：

   ssh ubuntu@your-server.com
   

3. 确认 SSH 密钥已添加到服务器：

   ssh-copy-id ubuntu@your-server.com
   

2. 构建失败

错误信息：

[ERROR] 构建失败
npm run build exited with code 1

可能原因：

• 代码存在语法错误
• 依赖包版本不兼容
• Node.js 版本不匹配

解决方法：

1. 在本地先运行构建测试：

   npm run build
   

2. 检查并修复错误
3. 确认服务器 Node.js 版本：

   ssh ubuntu@your-server.com "node -v"
   

3. 权限不足

错误信息：

[ERROR] 复制文件失败
Permission denied

可能原因：

• 对生产目录没有写权限
• 需要 sudo 权限

解决方法：

1. 检查生产目录权限：

   ssh ubuntu@your-server.com "ls -ld /var/www/valuefrontier.cn"
   

2. 修改目录所有者：

   ssh ubuntu@your-server.com "sudo chown -R ubuntu:ubuntu /var/www/valuefrontier.cn"
   

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

错误信息：

[⚠] 企业微信通知发送失败

可能原因：

• Webhook URL 错误
• 网络问题

解决方法：

1. 检查 Webhook URL 是否正确
2. 手动测试通知：

   bash scripts/notify-wechat.sh test
   

---

FAQ

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

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

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

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

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

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

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

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

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

A: 部署日志保存在服务器上：

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。

---

祝部署顺利！ 🎉