# H5 应用更新客户端使用教程

## 📖 目录

- [简介](#简介)
- [系统要求](#系统要求)
- [快速开始](#快速开始)
- [详细使用说明](#详细使用说明)
  - [交互模式](#交互模式)
  - [非交互模式](#非交互模式)
  - [命令行参数](#命令行参数)
- [使用场景](#使用场景)
- [常见问题](#常见问题)
- [故障排除](#故障排除)
- [最佳实践](#最佳实践)

---

## 简介

`update-client.sh` 是一个用于从版本服务器下载和更新 H5 应用的自动化脚本。它提供了以下功能：

✅ **安全认证** - 用户名密码验证，密码隐藏输入  
✅ **版本管理** - 自动获取和选择可用版本  
✅ **自动备份** - 更新前自动备份当前版本  
✅ **完整性验证** - 支持 MD5/SHA256 校验  
✅ **详细日志** - 记录完整操作日志  
✅ **锁机制** - 防止重复执行  
✅ **交互式和自动化模式** - 灵活适应不同场景

---

## 系统要求

### 必需工具

脚本依赖以下工具，请确保已安装：

- `bash` - Bash shell 解释器
- `curl` - 用于 HTTP 请求
- `wget` - 用于文件下载
- `tar` - 文件归档工具（可选）

### 支持的操作系统

- ✅ Linux (所有发行版)
- ✅ macOS
- ✅ Windows (通过 Git Bash、WSL 或 MSYS2)

### 在 Windows 上运行

**推荐方式：Git Bash**

1. 安装 [Git for Windows](https://git-scm.com/download/win)
2. 右键项目文件夹 → "Git Bash Here"
3. 执行脚本

**其他方式：**
- WSL (Windows Subsystem for Linux)
- MSYS2

---

## 快速开始

### 1. 下载脚本

```bash
# 确保脚本在项目根目录
ls -l update-client.sh
```

### 2. 基本执行（交互模式）

```bash
# 使用 bash 执行脚本
bash update-client.sh
```

### 3. 按提示操作

```
请输入用户名 [默认: deploy]: deploy
请输入密码: ********
请输入下载目录 [默认: ./h5]: 
```

### 4. 选择版本

```
可用版本列表（最新10个）:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  0. latest (最新版本)
  1. v1.1.5-20251129-143005
  2. v1.1.5-20251129-120530
  3. v1.1.4-20251128-163015
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

请选择版本 [0-3，默认: 0]: 0
```

### 5. 确认并执行

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  更新摘要
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  服务器: dros.overs.games
  用户名: deploy
  目标目录: ./h5
  版本: latest
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

确认执行更新? [y/N]: y
```

---

## 详细使用说明

### 交互模式

交互模式适合手动操作，提供友好的提示和选择界面。

#### 启动交互模式

```bash
bash update-client.sh
```

#### 交互流程

1. **输入用户名**
   - 默认值：`deploy`
   - 直接按 Enter 使用默认值
   - 或输入其他用户名

2. **输入密码**
   - 密码输入时不显示（安全）
   - 至少 6 位字符
   - 不能为空

3. **指定下载目录**
   - 默认值：`./h5`
   - 如果目录不存在，会询问是否创建

4. **选择版本**
   - 显示最新 10 个可用版本
   - 输入序号选择
   - 默认选择 `latest`（最新版本）

5. **确认更新**
   - 显示更新摘要
   - 输入 `y` 确认，`n` 或其他取消

6. **自动执行**
   - 备份当前版本
   - 下载新版本
   - 验证文件完整性
   - 完成更新

---

### 非交互模式

非交互模式适合自动化脚本和 CI/CD 流程。

#### 基本语法

```bash
bash update-client.sh [选项]
```

#### 完整示例

```bash
bash update-client.sh \
  --user deploy \
  --password your_password \
  --dir ./h5 \
  --version latest \
  --yes
```

#### 静默模式（最小输出）

```bash
bash update-client.sh \
  -u deploy \
  -p your_password \
  -d ./h5 \
  -v v1.1.5-20251129-143005 \
  -y \
  -s
```

---

### 命令行参数

| 参数 | 简写 | 说明 | 默认值 | 必需 |
|------|------|------|--------|------|
| `--user` | `-u` | 用户名 | `deploy` | 否 |
| `--password` | `-p` | 密码 | - | 否* |
| `--dir` | `-d` | 下载目录 | `./h5` | 否 |
| `--version` | `-v` | 版本号 | `latest` | 否 |
| `--include-static` | `-i` | 包含 static 文件夹 | `false` | 否 |
| `--yes` | `-y` | 跳过确认 | `false` | 否 |
| `--silent` | `-s` | 静默模式 | `false` | 否 |
| `--help` | `-h` | 显示帮助 | - | 否 |

\* 如果不通过参数提供密码，会在交互时提示输入

**关于 static 文件夹**：
- `static` 文件夹通常包含大量静态资源（图片、视频等）
- 默认情况下**不包含** static 文件夹，以节省时间和带宽
- 首次部署或 static 资源有更新时，需添加 `-i` 参数

#### 查看帮助

```bash
bash update-client.sh --help
```

---

## 使用场景

### 场景 1：开发环境日常更新

```bash
# 最简单的方式 - 交互模式
bash update-client.sh
```

### 场景 2：生产环境自动部署

```bash
#!/bin/bash
# deploy.sh - 生产部署脚本

# 从环境变量读取密码
DEPLOY_PASSWORD="${DEPLOY_PASSWORD}"

bash update-client.sh \
  -u deploy \
  -p "$DEPLOY_PASSWORD" \
  -d /var/www/html/h5 \
  -v latest \
  -y \
  -s

# 检查更新是否成功
if [ $? -eq 0 ]; then
    echo "部署成功！"
    # 可以在这里重启服务等
    # systemctl restart nginx
else
    echo "部署失败！"
    exit 1
fi
```

### 场景 3：定时更新任务

```bash
# 添加到 crontab
# 每天凌晨 2 点自动更新

0 2 * * * cd /path/to/project && bash update-client.sh -u deploy -p password -y -s >> /var/log/update.log 2>&1
```

### 场景 4：更新到特定版本

```bash
# 回滚到之前的版本
bash update-client.sh \
  -u deploy \
  -p your_password \
  -v v1.1.4-20251128-163015 \
  -y
```

### 场景 5：CI/CD 集成

**GitHub Actions 示例：**

```yaml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Deploy to server
        env:
          DEPLOY_PASSWORD: ${{ secrets.DEPLOY_PASSWORD }}
        run: |
          bash update-client.sh \
            -u deploy \
            -p "$DEPLOY_PASSWORD" \
            -d ./h5 \
            -v latest \
            -y \
            -s
```

---

## 常见问题

### Q1: 如何查看脚本版本？

A: 脚本顶部有版本信息，或查看帮助：

```bash
bash update-client.sh --help
```

### Q2: 密码可以保存在文件中吗？

A: 不推荐！但如果需要，可以：

```bash
# 从文件读取密码
PASSWORD=$(cat ~/.deploy_password)
bash update-client.sh -u deploy -p "$PASSWORD" -y
```

**更安全的方式：**

```bash
# 使用环境变量
export DEPLOY_PASSWORD="your_password"
bash update-client.sh -u deploy -p "$DEPLOY_PASSWORD" -y
```

### Q3: 如何查看更新日志？

A: 日志保存在 `./logs/` 目录：

```bash
# 查看最新日志
ls -lt ./logs/update_*.log | head -1

# 查看日志内容
tail -f ./logs/update_20251129_143005.log
```

### Q4: 备份的旧版本在哪里？

A: 备份保存在原目录旁边：

```bash
# 如果更新目录是 ./h5
# 备份会命名为 ./h5_backup_20251129_143005

ls -d ./h5_backup_*
```

### Q5: 如何恢复到备份版本？

A:

```bash
# 删除当前版本
rm -rf ./h5

# 恢复备份（替换为实际的备份目录名）
mv ./h5_backup_20251129_143005 ./h5
```

### Q6: 脚本运行中断了怎么办？

A: 删除锁文件后重试：

```bash
# 删除锁文件
rm -f /tmp/update-client-${USER}.lock

# 重新运行
bash update-client.sh
```

### Q7: 如何跳过备份步骤？

A: 脚本会自动检测，如果目录为空或不存在则跳过备份。如果需要强制不备份，可以先清空目录：

```bash
# 谨慎操作！
rm -rf ./h5/*
```

### Q8: 什么时候需要更新 static 文件夹？

A: **需要更新 static 的情况**：
- ✅ 首次部署应用
- ✅ 静态资源有更新（图片、字体、视频等）
- ✅ 版本升级涉及静态文件变更

**可以跳过 static 的情况**：
- ✅ 仅代码逻辑更新
- ✅ 静态资源使用 CDN
- ✅ static 文件夹从未变化

**示例**：

```bash
# 首次部署 - 包含 static
bash update-client.sh -u deploy -p password -y -i

# 日常更新 - 跳过 static（默认）
bash update-client.sh -u deploy -p password -y

# 静态资源有更新 - 包含 static
bash update-client.sh -u deploy -p password -y --include-static
```

### Q9: 如何确认 static 文件夹是否被更新？

A: 查看更新摘要和日志：

**更新摘要中会显示**：
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  更新摘要
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  服务器: dros.overs.games
  用户名: deploy
  目标目录: ./h5
  版本: latest
  static 文件夹: 跳过    ← 这里显示状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**日志中会记录**：
```bash
# 查看日志
cat ./logs/update_*.log | grep "static"

# 会看到类似输出
[INFO] static 文件夹: 跳过更新
# 或
[INFO] static 文件夹: 包含在更新中
```

---

## 故障排除

### 问题 1：无法连接到服务器

**错误信息：**
```
[ERROR] 无法连接到服务器
[ERROR] 请检查网络连接、用户名和密码
```

**解决方法：**

1. 检查网络连接：
   ```bash
   ping dros.overs.games
   ```

2. 手动测试连接：
   ```bash
   curl -k -I --user "deploy:your_password" https://dros.overs.games/releases/
   ```

3. 检查用户名和密码是否正确

4. 检查服务器地址是否正确

---

### 问题 2：缺少依赖工具

**错误信息：**
```
[ERROR] 缺少必需工具: wget curl
```

**解决方法：**

**Linux (Ubuntu/Debian):**
```bash
sudo apt-get update
sudo apt-get install curl wget
```

**Linux (CentOS/RHEL):**
```bash
sudo yum install curl wget
```

**macOS:**
```bash
brew install wget
# curl 通常已预装
```

**Windows (Git Bash):**
- Git Bash 通常已包含这些工具
- 如果缺失，重新安装 Git for Windows

---

### 问题 3：权限被拒绝

**错误信息：**
```
bash: ./update-client.sh: Permission denied
```

**解决方法：**

```bash
# 不要用 ./update-client.sh
# 改用 bash 命令
bash update-client.sh
```

---

### 问题 4：版本列表为空

**错误信息：**
```
[ERROR] 无法获取版本列表
```

**解决方法：**

1. 检查服务器上是否有可用版本
2. 确认 releases 目录访问权限
3. 手动检查：
   ```bash
   curl -k --user "deploy:password" https://dros.overs.games/releases/
   ```

---

### 问题 5：下载失败

**错误信息：**
```
[ERROR] 下载失败
```

**解决方法：**

1. 检查磁盘空间：
   ```bash
   df -h
   ```

2. 检查目录写入权限：
   ```bash
   ls -ld ./h5
   ```

3. 手动测试下载：
   ```bash
   wget --user=deploy --password=your_password \
        --no-check-certificate \
        https://dros.overs.games/releases/latest/
   ```

---

### 问题 6：文件完整性验证失败

**错误信息：**
```
[ERROR] 文件完整性验证失败
```

**解决方法：**

1. 重新下载
2. 检查网络稳定性
3. 如果持续失败，联系服务器管理员检查校验文件

---

## 最佳实践

### 1. 安全性

✅ **DO（推荐）：**
- 使用环境变量存储密码
- 定期更换密码
- 限制脚本文件权限：`chmod 700 update-client.sh`
- 在生产环境使用非交互模式

❌ **DON'T（不推荐）：**
- 在脚本中硬编码密码
- 在命令历史中暴露密码
- 将密码提交到版本控制系统

### 2. 自动化

```bash
# 创建包装脚本
cat > auto-update.sh << 'EOF'
#!/bin/bash
set -e

# 从安全位置读取密码
DEPLOY_PASSWORD=$(cat ~/.secrets/deploy_password)

# 执行更新
bash update-client.sh \
  -u deploy \
  -p "$DEPLOY_PASSWORD" \
  -d /var/www/html/h5 \
  -v latest \
  -y \
  -s

# 更新成功后的操作
if [ $? -eq 0 ]; then
    # 重启服务
    sudo systemctl reload nginx
    
    # 发送通知
    echo "H5 应用已更新到最新版本" | mail -s "部署成功" admin@example.com
fi
EOF

chmod 700 auto-update.sh
```

### 3. 监控和日志

```bash
# 保留最近 30 天的日志
find ./logs -name "update_*.log" -mtime +30 -delete

# 监控更新状态
tail -f ./logs/update_*.log | grep -E "\[ERROR\]|\[✓\]"
```

### 4. 版本管理

```bash
# 记录当前版本
echo "latest" > ./h5/.version

# 更新后验证
cat ./h5/.version
```

### 5. 回滚策略

```bash
# 更新前记录当前版本信息
CURRENT_VERSION=$(cat ./h5/.version 2>/dev/null || echo "unknown")
echo "更新前版本: $CURRENT_VERSION" >> ./logs/update_history.log

# 执行更新
bash update-client.sh -u deploy -p "$PASSWORD" -v latest -y

# 如果更新失败，自动回滚
if [ $? -ne 0 ]; then
    echo "更新失败，正在回滚..."
    if [ -d "./h5_backup_*" ]; then
        rm -rf ./h5
        mv $(ls -dt ./h5_backup_* | head -1) ./h5
        echo "已回滚到: $CURRENT_VERSION"
    fi
fi
```

---

## 技术支持

如有问题或建议，请：

1. 查看日志文件：`./logs/update_*.log`
2. 检查常见问题部分
3. 联系系统管理员

---

## 版本历史

- **v1.0.0** (2025-11-29)
  - 初始版本发布
  - 支持交互和非交互模式
  - 添加版本选择功能
  - 实现自动备份机制
  - 支持文件完整性验证
  - 添加锁机制防止并发

---

## 许可证

本脚本为内部使用工具，请勿外传。

---

**最后更新：** 2025-11-29  
**维护者：** 开发团队