dros/.build/deploy-android-README.md

Android APK 自动部署到服务器

概述

本文档说明如何使用自动部署功能将构建好的 Android APK 文件上传到远程服务器。

功能特性

• ✅ 自动上传 APK 到服务器的 android-releases 目录
• ✅ 版本化管理（格式：v{版本号}-{时间戳}）
• ✅ 自动创建 latest.apk 符号链接指向最新版本
• ✅ 生成版本清单文件 versions.json 供客户端查询
• ✅ 保留所有历史版本

目录结构

服务器端目录结构：
/var/www/html/
├── releases/              # H5 部署目录
│   ├── v1.0.0-20250130-120000/
│   └── latest -> v1.0.0-20250130-120000
│
└── android-releases/      # Android APK 部署目录
    ├── v1.0.0-20250130-120000/
    │   └── dros-v1.0.0.apk
    ├── v1.0.1-20250131-150000/
    │   └── dros-v1.0.1.apk
    ├── latest.apk -> v1.0.1-20250131-150000/dros-v1.0.1.apk
    └── versions.json

环境变量配置

需要设置以下环境变量（与 H5 部署共用）：

DEPLOY_KEY=<SSH 私钥内容>
DEPLOY_HOST=<服务器地址>
DEPLOY_USER=<SSH 用户名>
DEPLOY_PATH=<H5 部署路径，如 /var/www/html/releases>

新增：启用 Android 自动部署

DEPLOY_ANDROID=true

使用方法

方式 1：构建时自动部署（推荐）

在构建 Android APK 时启用自动部署：

# Windows PowerShell
$env:DEPLOY_ANDROID="true"
npm run build:android

# Linux/macOS
DEPLOY_ANDROID=true npm run build:android

方式 2：仅构建不部署

npm run build:android

构建完成后会提示：

💡 提示: 设置 DEPLOY_ANDROID=true 可自动部署到服务器

方式 3：单独部署已有 APK

如果已经有构建好的 APK，可以单独运行部署脚本：

# 方式 A：通过命令行参数
node .build/deploy-android-to-server.js path/to/your-app.apk

# 方式 B：通过环境变量
APK_PATH=path/to/your-app.apk APP_VERSION=1.0.0 node .build/deploy-android-to-server.js

测试 SSH 连接

在部署前可以先测试 SSH 连接是否正常：

node .build/deploy-android-to-server.js --test

版本清单文件 (versions.json)

部署后会在服务器生成 versions.json 文件，格式如下：

{
  "latest": "v1.0.1-20250131-150000",
  "versions": [
    {
      "version": "v1.0.1-20250131-150000",
      "appVersion": "1.0.1",
      "timestamp": "2025-01-31T15:00:00.000Z",
      "filename": "dros-v1.0.1.apk",
      "size": 15728640,
      "downloadUrl": "/android-releases/v1.0.1-20250131-150000/dros-v1.0.1.apk"
    },
    {
      "version": "v1.0.0-20250130-120000",
      "appVersion": "1.0.0",
      "timestamp": "2025-01-30T12:00:00.000Z",
      "filename": "dros-v1.0.0.apk",
      "size": 15200000,
      "downloadUrl": "/android-releases/v1.0.0-20250130-120000/dros-v1.0.0.apk"
    }
  ]
}

客户端使用

客户端可以通过以下 URL 访问：

• 最新版本下载：https://your-domain.com/android-releases/latest.apk
• 版本清单：https://your-domain.com/android-releases/versions.json
• 特定版本下载：https://your-domain.com/android-releases/v1.0.0-20250130-120000/dros-v1.0.0.apk

工作流程

1. 构建 APK

   npm run build:android
   

   1. 生成版本化 APK
   2. 文件名：dros-v{版本号}.apk

   3. 位置：.build/dros/platforms/android/app/build/outputs/apk/debug/

   4. 安装到设备（如果连接了 Android 设备）

      adb install ...
      

2. 部署到服务器（如果 DEPLOY_ANDROID=true）

   • 连接 SSH
   • 创建版本目录
   • 上传 APK 文件
   • 更新 latest.apk 符号链接
   • 更新 versions.json 版本清单

完整示例

开发环境（本地构建）

npm run build:android

生产环境（自动部署）

# 1. 设置环境变量（仅首次需要）
export DEPLOY_KEY="$(cat ~/.ssh/id_rsa)"
export DEPLOY_HOST="your-server.com"
export DEPLOY_USER="deploy"
export DEPLOY_PATH="/var/www/html/releases"

# 2. 构建并部署
DEPLOY_ANDROID=true npm run build:android

CI/CD 集成

在 GitHub Actions 或其他 CI/CD 工具中：

- name: Build and Deploy Android APK
  env:
    DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
    DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
    DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
    DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
    DEPLOY_ANDROID: true
  run: |
    npm run build:android

故障排除

部署失败：认证错误

❌ 部署失败: All configured authentication methods failed
   → 认证失败，请检查 SSH 私钥是否正确

解决方法：

• 检查 DEPLOY_KEY 环境变量是否包含完整的私钥内容
• 确认私钥格式正确（包括 -----BEGIN ... KEY----- 头尾）
• 验证服务器是否允许该密钥登录

部署失败：连接超时

❌ 部署失败: Timed out while waiting for handshake
   → 连接超时，请检查网络和服务器地址

解决方法：

• 检查 DEPLOY_HOST 是否正确
• 确认网络连接正常
• 检查防火墙设置

路径转换问题

如果 DEPLOY_PATH 不是以 /releases 结尾，路径转换可能失败。

当前路径转换逻辑：

/var/www/html/releases -> /var/www/html/android-releases

解决方法： 确保 DEPLOY_PATH 以 /releases 结尾。

注意事项

1. 版本号管理：版本号来自 package.json 的 version 字段，确保每次发布前更新版本号
2. 磁盘空间：历史版本会一直保留，需定期清理旧版本释放空间
3. 下载链接：确保 Nginx 配置允许访问 android-releases 目录
4. 符号链接：如果服务器不支持符号链接，需要修改脚本改用复制方式

相关文件

• .build/deploy-android-to-server.js - Android 部署脚本
• .build/build-android.js - Android 构建脚本
• .build/deploy-to-server.js - H5 部署脚本（参考）

更新日志

• 2025-01-30：初始版本，支持自动部署和版本管理