# 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 部署共用）：

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

**新增**：启用 Android 自动部署

```bash
DEPLOY_ANDROID=true
```

## 使用方法

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

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

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

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

### 方式 2：仅构建不部署

```bash
npm run build:android
```

构建完成后会提示：
```
💡 提示: 设置 DEPLOY_ANDROID=true 可自动部署到服务器
```

### 方式 3：单独部署已有 APK

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

```bash
# 方式 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 连接是否正常：

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

## 版本清单文件 (versions.json)

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

```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**
   ```bash
   npm run build:android
   ```

2. **生成版本化 APK**
   - 文件名：`dros-v{版本号}.apk`
   - 位置：`.build/dros/platforms/android/app/build/outputs/apk/debug/`

3. **安装到设备**（如果连接了 Android 设备）
   ```bash
   adb install ...
   ```

4. **部署到服务器**（如果 `DEPLOY_ANDROID=true`）
   - 连接 SSH
   - 创建版本目录
   - 上传 APK 文件
   - 更新 `latest.apk` 符号链接
   - 更新 `versions.json` 版本清单

## 完整示例

### 开发环境（本地构建）

```bash
npm run build:android
```

### 生产环境（自动部署）

```bash
# 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 工具中：

```yaml
- 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` 结尾，路径转换可能失败。

**当前路径转换逻辑**：
```javascript
/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：初始版本，支持自动部署和版本管理