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

📖 目录

简介
系统要求
快速开始
详细使用说明
使用场景
常见问题
故障排除
最佳实践

简介

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

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

系统要求

必需工具

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

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

支持的操作系统

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

在 Windows 上运行

推荐方式：Git Bash

安装 Git for Windows
右键项目文件夹 → "Git Bash Here"
执行脚本

其他方式：

WSL (Windows Subsystem for Linux)
MSYS2

快速开始

1. 下载脚本

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

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

# 使用 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 update-client.sh

交互流程

输入用户名
- 默认值：deploy
- 直接按 Enter 使用默认值
- 或输入其他用户名
输入密码
- 密码输入时不显示（安全）
- 至少 6 位字符
- 不能为空
指定下载目录
- 默认值：./h5
- 如果目录不存在，会询问是否创建
选择版本
- 显示最新 10 个可用版本
- 输入序号选择
- 默认选择 latest（最新版本）
确认更新
- 显示更新摘要
- 输入 y 确认，n 或其他取消
自动执行
- 备份当前版本
- 下载新版本
- 验证文件完整性
- 完成更新

非交互模式

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

基本语法

bash update-client.sh [选项]

完整示例

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

静默模式（最小输出）

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 update-client.sh --help

使用场景

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

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

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

#!/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：定时更新任务

# 添加到 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 update-client.sh \
  -u deploy \
  -p your_password \
  -v v1.1.4-20251128-163015 \
  -y

场景 5：CI/CD 集成

GitHub Actions 示例：

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 update-client.sh --help

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

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

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

更安全的方式：

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

Q3: 如何查看更新日志？

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

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

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

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

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

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

ls -d ./h5_backup_*

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

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

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

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

A: 删除锁文件后重试：

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

# 重新运行
bash update-client.sh

Q7: 如何跳过备份步骤？

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

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

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

A: 需要更新 static 的情况：

✅ 首次部署应用
✅ 静态资源有更新（图片、字体、视频等）
✅ 版本升级涉及静态文件变更

可以跳过 static 的情况：

✅ 仅代码逻辑更新
✅ 静态资源使用 CDN
✅ static 文件夹从未变化

示例：

# 首次部署 - 包含 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 文件夹: 跳过    ← 这里显示状态
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

日志中会记录：

# 查看日志
cat ./logs/update_*.log | grep "static"

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

故障排除

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

错误信息：

[ERROR] 无法连接到服务器
[ERROR] 请检查网络连接、用户名和密码

解决方法：

检查网络连接：
```
ping dros.overs.games
```
1. 手动测试连接： bash curl -k -I --user "deploy:your_password" https://dros.overs.games/releases/
检查用户名和密码是否正确
检查服务器地址是否正确

问题 2：缺少依赖工具

错误信息：

[ERROR] 缺少必需工具: wget curl

解决方法：

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install curl wget

Linux (CentOS/RHEL):

sudo yum install curl wget

macOS:

brew install wget
# curl 通常已预装

Windows (Git Bash):

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

问题 3：权限被拒绝

错误信息：

bash: ./update-client.sh: Permission denied

解决方法：

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

问题 4：版本列表为空

错误信息：

[ERROR] 无法获取版本列表

解决方法：

检查服务器上是否有可用版本
确认 releases 目录访问权限

手动检查：

curl -k --user "deploy:password" https://dros.overs.games/releases/

问题 5：下载失败

错误信息： ```

[ERROR] 下载失败


**解决方法：**

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

检查目录写入权限：
```
ls -ld ./h5
```
1. 手动测试下载： bash wget --user=deploy --password=your_password \ --no-check-certificate \ https://dros.overs.games/releases/latest/

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

错误信息：

[ERROR] 文件完整性验证失败

解决方法：

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

最佳实践

1. 安全性

✅ DO（推荐）：

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

❌ DON'T（不推荐）：

在脚本中硬编码密码
在命令历史中暴露密码
将密码提交到版本控制系统

2. 自动化

# 创建包装脚本
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. 监控和日志

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

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

4. 版本管理

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

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

5. 回滚策略

# 更新前记录当前版本信息
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

技术支持

如有问题或建议，请：

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

版本历史

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

许可证

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

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

update-client使用教程.md 14 KB Trvalý odkaz Historie Surový

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

📖 目录

简介

系统要求

必需工具

支持的操作系统

在 Windows 上运行

快速开始

1. 下载脚本

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

3. 按提示操作

4. 选择版本

5. 确认并执行

详细使用说明

交互模式

启动交互模式

交互流程

非交互模式

基本语法

完整示例

静默模式（最小输出）

命令行参数

查看帮助

使用场景

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

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

场景 3：定时更新任务

场景 4：更新到特定版本

场景 5：CI/CD 集成

常见问题

Q1: 如何查看脚本版本？

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

Q3: 如何查看更新日志？

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

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

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

Q7: 如何跳过备份步骤？

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

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

故障排除

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

问题 2：缺少依赖工具

问题 3：权限被拒绝

问题 4：版本列表为空

问题 5：下载失败

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

最佳实践

1. 安全性

2. 自动化

3. 监控和日志

4. 版本管理

5. 回滚策略

技术支持

版本历史

许可证

update-client使用教程.md 14 KB

Trvalý odkaz Historie Surový