docs: 将所有文档迁移到 docs/ 目录
- 移动42个文档文件到 docs/ 目录 - 更新 .gitignore 允许 docs/ 下的 .md 文件 - 删除根目录下的重复文档文件 📁 文档分类： - StockDetailPanel 重构文档（3个） - PostHog 集成文档（6个） - 系统架构和API文档（33个） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
zdl
648
docs/DEPLOYMENT.md
Normal file
648
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,648 @@
|
||||
# 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。
|
||||
|
||||
---
|
||||
|
||||
**祝部署顺利！** 🎉
|
||||
Reference in New Issue
Block a user