# Flutter Android APK 在线升级完整方案

> 支持 Google Play 和自建服务器双渠道的 Flutter Android 应用升级解决方案

## 目录

- [一、方案概述](#一方案概述)
- [二、技术栈与依赖](#二技术栈与依赖)
- [三、架构设计](#三架构设计)
- [四、Google Play 应用内更新](#四google-play-应用内更新)
- [五、自建服务器 APK 升级](#五自建服务器-apk-升级)
- [六、统一升级服务](#六统一升级服务)
- [七、后端接口设计](#七后端接口设计)
- [八、Android 原生配置](#八android-原生配置)
- [九、安全性考虑](#九安全性考虑)
- [十、实施步骤](#十实施步骤)

---

## 一、方案概述

### 1.1 升级渠道对比

| 渠道 | 适用场景 | 升级体验 | 审核要求 |
|------|---------|---------|---------|
| Google Play | 海外市场、正规渠道 | 应用内更新，体验流畅 | 需要审核 |
| 自建服务器 | 国内市场、企业内部 | 下载 APK 安装 | 无需审核 |

### 1.2 核心特性

- 支持 Google Play 应用内更新（灵活更新、强制更新）
- 支持自建服务器 APK 下载安装
- 使用应用专属目录，无需外部存储权限
- SHA-256 文件完整性校验
- 支持应用市场来源检测
- 渠道构建层面完全隔离
- 强制 HTTPS 下载

---

## 二、技术栈与依赖

### 2.1 Flutter 依赖

```yaml
dependencies:
  # 版本信息
  package_info_plus: ^8.0.0
  
  # HTTP 请求与下载
  dio: ^5.4.0
  
  # Google Play 应用内更新
  in_app_update: ^4.2.2
  
  # 权限管理
  permission_handler: ^11.0.0
  
  # 路径获取
  path_provider: ^2.1.0
  
  # SHA-256 校验
  crypto: ^3.0.3
  
  # URL 启动
  url_launcher: ^6.2.0
```

### 2.2 Android 依赖

Google Play Core Library 会由 `in_app_update` 插件自动添加。

---

## 三、架构设计

### 3.1 目录结构

```
lib/
└── core/
    └── updater/
        ├── models/
        │   ├── version_info.dart              # 版本信息模型
        │   └── update_config.dart             # 更新配置
        ├── channels/
        │   ├── google_play_updater.dart       # Google Play 更新
        │   └── self_hosted_updater.dart       # 自建服务器更新
        ├── version_checker.dart               # 版本检测
        ├── download_manager.dart              # 下载管理
        ├── apk_installer.dart                 # APK 安装器
        ├── app_market_detector.dart           # 应用市场检测
        └── update_service.dart                # 升级服务统一入口
```

---

## 四、Google Play 应用内更新

### 4.1 Google Play 更新器实现

**文件: `lib/core/updater/channels/google_play_updater.dart`**

```dart
import 'package:in_app_update/in_app_update.dart';

enum GooglePlayUpdateType {
  flexible,    // 灵活更新：后台下载，可继续使用
  immediate,   // 强制更新：阻塞式，必须更新
}

class GooglePlayUpdater {
  /// 检查是否有更新可用
  static Future<bool> checkForUpdate() async {
    try {
      final updateInfo = await InAppUpdate.checkForUpdate();
      return updateInfo.updateAvailability == UpdateAvailability.updateAvailable;
    } catch (e) {
      print('Check update failed: $e');
      return false;
    }
  }

  /// 灵活更新
  /// 用户可以在后台下载，继续使用应用
  static Future<void> performFlexibleUpdate() async {
    try {
      final updateInfo = await InAppUpdate.checkForUpdate();
      
      if (updateInfo.updateAvailability == UpdateAvailability.updateAvailable) {
        if (updateInfo.flexibleUpdateAllowed) {
          await InAppUpdate.startFlexibleUpdate();
          
          InAppUpdate.completeFlexibleUpdate().then((_) {
            print('Update completed, app will restart');
          }).catchError((e) {
            print('Update failed: $e');
          });
        } else {
          print('Flexible update not allowed');
        }
      }
    } catch (e) {
      print('Flexible update error: $e');
    }
  }

  /// 强制更新
  /// 阻塞式更新，用户必须更新才能继续使用
  static Future<void> performImmediateUpdate() async {
    try {
      final updateInfo = await InAppUpdate.checkForUpdate();
      
      if (updateInfo.updateAvailability == UpdateAvailability.updateAvailable) {
        if (updateInfo.immediateUpdateAllowed) {
          await InAppUpdate.performImmediateUpdate();
        } else {
          print('Immediate update not allowed');
        }
      }
    } catch (e) {
      print('Immediate update error: $e');
    }
  }

  /// 智能更新策略
  /// 根据版本差异决定更新方式
  static Future<void> smartUpdate({
    required int currentVersion,
    required int latestVersion,
  }) async {
    final versionDiff = latestVersion - currentVersion;
    
    if (versionDiff >= 10) {
      // 版本差异大，强制更新
      await performImmediateUpdate();
    } else {
      // 版本差异小，灵活更新
      await performFlexibleUpdate();
    }
  }
}
```

### 4.2 使用示例

```dart
class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _checkGooglePlayUpdate();
  }

  Future<void> _checkGooglePlayUpdate() async {
    await Future.delayed(const Duration(seconds: 3));
    
    final hasUpdate = await GooglePlayUpdater.checkForUpdate();
    if (hasUpdate) {
      _showUpdateDialog();
    }
  }

  void _showUpdateDialog() {
    showDialog(
      context: context,
      barrierDismissible: false,
      builder: (context) => AlertDialog(
        title: const Text('发现新版本'),
        content: const Text('有新版本可用，是否立即更新？'),
        actions: [
          TextButton(
            onPressed: () {
              Navigator.pop(context);
              GooglePlayUpdater.performFlexibleUpdate();
            },
            child: const Text('更新'),
          ),
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('稍后'),
          ),
        ],
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(/* ... */);
  }
}
```

---

## 五、自建服务器 APK 升级

### 5.1 版本信息模型

**文件: `lib/core/updater/models/version_info.dart`**

```dart
import 'package:json_annotation/json_annotation.dart';

part 'version_info.g.dart';

@JsonSerializable()
class VersionInfo {
  final String version;          // 版本号: "1.2.0"
  final int versionCode;         // 版本代码: 120
  final String downloadUrl;      // APK 下载地址
  final int fileSize;            // 文件大小(字节)
  final String fileSizeFriendly; // 友好显示: "25.6 MB"
  final String sha256;           // SHA-256 校验
  final bool forceUpdate;        // 是否强制更新
  final String? updateLog;       // 更新日志
  final DateTime releaseDate;    // 发布时间

  VersionInfo({
    required this.version,
    required this.versionCode,
    required this.downloadUrl,
    required this.fileSize,
    required this.fileSizeFriendly,
    required this.sha256,
    this.forceUpdate = false,
    this.updateLog,
    required this.releaseDate,
  });

  factory VersionInfo.fromJson(Map<String, dynamic> json) =>
      _$VersionInfoFromJson(json);
  
  Map<String, dynamic> toJson() => _$VersionInfoToJson(this);
}
```

### 5.2 版本检测器

**文件: `lib/core/updater/version_checker.dart`**

```dart
import 'package:package_info_plus/package_info_plus.dart';
import 'package:dio/dio.dart';
import 'models/version_info.dart';

class VersionChecker {
  final String apiBaseUrl;
  final Dio _dio;

  VersionChecker({required this.apiBaseUrl})
      : _dio = Dio(BaseOptions(
          baseUrl: apiBaseUrl,
          connectTimeout: const Duration(seconds: 10),
        ));

  /// 获取当前版本信息
  Future<PackageInfo> getCurrentVersion() async {
    return await PackageInfo.fromPlatform();
  }

  /// 从服务器获取最新版本信息
  Future<VersionInfo?> fetchLatestVersion() async {
    try {
      final response = await _dio.get('/api/app/version/check');
      
      if (response.statusCode == 200) {
        return VersionInfo.fromJson(response.data);
      }
      return null;
    } catch (e) {
      print('Fetch version failed: $e');
      return null;
    }
  }

  /// 检查是否有新版本
  Future<VersionInfo?> checkForUpdate() async {
    try {
      final currentInfo = await getCurrentVersion();
      final latestInfo = await fetchLatestVersion();

      if (latestInfo == null) return null;

      final currentCode = int.parse(currentInfo.buildNumber);
      if (latestInfo.versionCode > currentCode) {
        return latestInfo;
      }

      return null;
    } catch (e) {
      print('Check update failed: $e');
      return null;
    }
  }

  /// 是否需要强制更新
  Future<bool> needForceUpdate() async {
    final latestInfo = await checkForUpdate();
    return latestInfo?.forceUpdate ?? false;
  }
}
```

### 5.3 下载管理器

**文件: `lib/core/updater/download_manager.dart`**

```dart
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:path_provider/path_provider.dart';
import 'package:crypto/crypto.dart';
import 'dart:convert';

class DownloadManager {
  final Dio _dio = Dio();
  CancelToken? _cancelToken;

  /// 下载 APK 文件
  /// [url] 下载地址（必须是 HTTPS）
  /// [sha256Expected] SHA-256 校验值
  /// [onProgress] 下载进度回调 (已下载字节, 总字节)
  Future<File?> downloadApk({
    required String url,
    required String sha256Expected,
    Function(int received, int total)? onProgress,
  }) async {
    try {
      // 强制 HTTPS
      if (!url.startsWith('https://')) {
        print('Download URL must use HTTPS');
        return null;
      }

      _cancelToken = CancelToken();

      // 使用应用专属目录（无需额外权限）
      final dir = await getApplicationDocumentsDirectory();
      final savePath = '${dir.path}/app_update.apk';
      final file = File(savePath);

      if (await file.exists()) {
        await file.delete();
      }

      print('Downloading APK to: $savePath');

      await _dio.download(
        url,
        savePath,
        cancelToken: _cancelToken,
        onReceiveProgress: (received, total) {
          if (total != -1) {
            final progress = (received / total * 100).toStringAsFixed(0);
            print('Download progress: $progress%');
            onProgress?.call(received, total);
          }
        },
        options: Options(
          receiveTimeout: const Duration(minutes: 10),
          sendTimeout: const Duration(minutes: 10),
        ),
      );

      print('Download completed');

      // 校验 SHA-256
      final isValid = await _verifySha256(file, sha256Expected);
      if (!isValid) {
        print('SHA-256 verification failed');
        await file.delete();
        return null;
      }

      print('SHA-256 verified');
      return file;
    } catch (e) {
      print('Download failed: $e');
      return null;
    }
  }

  /// 取消下载
  void cancelDownload() {
    _cancelToken?.cancel('User cancelled download');
  }

  /// 校验文件 SHA-256
  Future<bool> _verifySha256(File file, String expectedSha256) async {
    try {
      final bytes = await file.readAsBytes();
      final digest = sha256.convert(bytes);
      final actualSha256 = digest.toString();
      
      print('Expected SHA-256: $expectedSha256');
      print('Actual SHA-256:   $actualSha256');
      
      return actualSha256.toLowerCase() == expectedSha256.toLowerCase();
    } catch (e) {
      print('SHA-256 verification error: $e');
      return false;
    }
  }
}
```

### 5.4 APK 安装器

**文件: `lib/core/updater/apk_installer.dart`**

```dart
import 'dart:io';
import 'package:flutter/services.dart';
import 'package:permission_handler/permission_handler.dart';

class ApkInstaller {
  static const MethodChannel _channel = MethodChannel('com.yourapp/apk_installer');

  /// 安装 APK
  static Future<bool> installApk(File apkFile) async {
    try {
      if (!await apkFile.exists()) {
        print('APK file not found');
        return false;
      }

      // Android 8.0+ 需要请求安装权限
      if (Platform.isAndroid) {
        final hasPermission = await _requestInstallPermission();
        if (!hasPermission) {
          print('Install permission denied');
          return false;
        }
      }

      print('Installing APK: ${apkFile.path}');
      final result = await _channel.invokeMethod('installApk', {
        'apkPath': apkFile.path,
      });
      
      print('Installation triggered: $result');
      return true;
    } catch (e) {
      print('Install failed: $e');
      return false;
    }
  }

  /// 请求安装权限（Android 8.0+）
  static Future<bool> _requestInstallPermission() async {
    if (await Permission.requestInstallPackages.isGranted) {
      return true;
    }

    final status = await Permission.requestInstallPackages.request();
    return status.isGranted;
  }
}
```

### 5.5 应用市场检测器

**文件: `lib/core/updater/app_market_detector.dart`**

```dart
import 'dart:io';
import 'package:flutter/services.dart';
import 'package:url_launcher/url_launcher.dart';

class AppMarketDetector {
  static const MethodChannel _channel = MethodChannel('com.yourapp/app_market');

  /// 获取安装来源
  static Future<String?> getInstallerPackageName() async {
    if (!Platform.isAndroid) return null;

    try {
      final installer = await _channel.invokeMethod<String>('getInstallerPackageName');
      return installer;
    } catch (e) {
      print('Get installer failed: $e');
      return null;
    }
  }

  /// 判断是否来自应用市场
  static Future<bool> isFromAppMarket() async {
    final installer = await getInstallerPackageName();
    
    if (installer == null || installer.isEmpty) {
      return false; // 直接安装
    }

    // 常见应用市场包名
    const marketPackages = [
      'com.huawei.appmarket',
      'com.xiaomi.market',
      'com.oppo.market',
      'com.bbk.appstore',
      'com.tencent.android.qqdownloader',
      'com.qihoo.appstore',
      'com.baidu.appsearch',
      'com.wandoujia.phoenix2',
      'com.dragon.android.pandaspace',
      'com.sec.android.app.samsungapps',
    ];

    return marketPackages.contains(installer);
  }

  /// 打开应用市场详情页
  static Future<void> openAppMarketDetail(String packageName) async {
    final marketUri = Uri.parse('market://details?id=$packageName');

    if (await canLaunchUrl(marketUri)) {
      await launchUrl(marketUri, mode: LaunchMode.externalApplication);
    } else {
      final webUri = Uri.parse('https://play.google.com/store/apps/details?id=$packageName');
      await launchUrl(webUri, mode: LaunchMode.externalApplication);
    }
  }
}
```

### 5.6 自建服务器更新器

**文件: `lib/core/updater/channels/self_hosted_updater.dart`**

```dart
import 'dart:io';
import 'package:flutter/material.dart';
import '../version_checker.dart';
import '../download_manager.dart';
import '../apk_installer.dart';
import '../app_market_detector.dart';
import '../models/version_info.dart';

class SelfHostedUpdater {
  final VersionChecker versionChecker;
  final DownloadManager downloadManager;

  SelfHostedUpdater({
    required String apiBaseUrl,
  })  : versionChecker = VersionChecker(apiBaseUrl: apiBaseUrl),
        downloadManager = DownloadManager();

  /// 检查并提示更新
  Future<void> checkAndPromptUpdate(BuildContext context) async {
    final versionInfo = await versionChecker.checkForUpdate();
    
    if (versionInfo == null) {
      print('Already latest version');
      return;
    }

    if (!context.mounted) return;

    // 检测安装来源
    final isFromMarket = await AppMarketDetector.isFromAppMarket();
    
    if (isFromMarket) {
      _showMarketUpdateDialog(context, versionInfo);
    } else {
      _showSelfHostedUpdateDialog(context, versionInfo);
    }
  }

  /// 应用市场更新提示
  void _showMarketUpdateDialog(BuildContext context, VersionInfo versionInfo) {
    showDialog(
      context: context,
      barrierDismissible: !versionInfo.forceUpdate,
      builder: (context) => WillPopScope(
        onWillPop: () async => !versionInfo.forceUpdate,
        child: AlertDialog(
          title: Text(versionInfo.forceUpdate ? '发现重要更新' : '发现新版本'),
          content: SingleChildScrollView(
            child: Column(
              mainAxisSize: MainAxisSize.min,
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text('最新版本: ${versionInfo.version}'),
                if (versionInfo.updateLog != null) ...[
                  const SizedBox(height: 16),
                  const Text('更新内容:', style: TextStyle(fontWeight: FontWeight.bold)),
                  const SizedBox(height: 8),
                  Text(versionInfo.updateLog!),
                ],
                const SizedBox(height: 16),
                const Text(
                  '检测到您的应用来自应用市场，建议前往应用市场更新以获得最佳体验。',
                  style: TextStyle(fontSize: 12, color: Colors.grey),
                ),
              ],
            ),
          ),
          actions: [
            if (!versionInfo.forceUpdate)
              TextButton(
                onPressed: () => Navigator.pop(context),
                child: const Text('稍后'),
              ),
            ElevatedButton(
              onPressed: () async {
                Navigator.pop(context);
                final packageInfo = await versionChecker.getCurrentVersion();
                await AppMarketDetector.openAppMarketDetail(packageInfo.packageName);
              },
              child: const Text('前往应用市场'),
            ),
          ],
        ),
      ),
    );
  }

  /// 自建更新对话框
  void _showSelfHostedUpdateDialog(BuildContext context, VersionInfo versionInfo) {
    showDialog(
      context: context,
      barrierDismissible: !versionInfo.forceUpdate,
      builder: (context) => WillPopScope(
        onWillPop: () async => !versionInfo.forceUpdate,
        child: AlertDialog(
          title: Text(versionInfo.forceUpdate ? '发现重要更新' : '发现新版本'),
          content: SingleChildScrollView(
            child: Column(
              mainAxisSize: MainAxisSize.min,
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text('最新版本: ${versionInfo.version}'),
                const SizedBox(height: 8),
                Text('文件大小: ${versionInfo.fileSizeFriendly}'),
                if (versionInfo.updateLog != null) ...[
                  const SizedBox(height: 16),
                  const Text('更新内容:', style: TextStyle(fontWeight: FontWeight.bold)),
                  const SizedBox(height: 8),
                  Text(versionInfo.updateLog!),
                ],
              ],
            ),
          ),
          actions: [
            if (!versionInfo.forceUpdate)
              TextButton(
                onPressed: () => Navigator.pop(context),
                child: const Text('稍后'),
              ),
            ElevatedButton(
              onPressed: () {
                Navigator.pop(context);
                _startUpdate(context, versionInfo);
              },
              child: const Text('立即更新'),
            ),
          ],
        ),
      ),
    );
  }

  /// 开始下载并安装
  Future<void> _startUpdate(BuildContext context, VersionInfo versionInfo) async {
    if (!context.mounted) return;

    showDialog(
      context: context,
      barrierDismissible: false,
      builder: (context) => _DownloadProgressDialog(
        versionInfo: versionInfo,
        downloadManager: downloadManager,
      ),
    );
  }
}

/// 下载进度对话框
class _DownloadProgressDialog extends StatefulWidget {
  final VersionInfo versionInfo;
  final DownloadManager downloadManager;

  const _DownloadProgressDialog({
    required this.versionInfo,
    required this.downloadManager,
  });

  @override
  State<_DownloadProgressDialog> createState() => _DownloadProgressDialogState();
}

class _DownloadProgressDialogState extends State<_DownloadProgressDialog> {
  double _progress = 0.0;
  String _statusText = '准备下载...';
  bool _isDownloading = true;

  @override
  void initState() {
    super.initState();
    _startDownload();
  }

  Future<void> _startDownload() async {
    setState(() {
      _statusText = '正在下载...';
    });

    final apkFile = await widget.downloadManager.downloadApk(
      url: widget.versionInfo.downloadUrl,
      sha256Expected: widget.versionInfo.sha256,
      onProgress: (received, total) {
        setState(() {
          _progress = received / total;
          final receivedMB = (received / 1024 / 1024).toStringAsFixed(1);
          final totalMB = (total / 1024 / 1024).toStringAsFixed(1);
          _statusText = '正在下载... $receivedMB MB / $totalMB MB';
        });
      },
    );

    if (apkFile == null) {
      setState(() {
        _statusText = '下载失败';
        _isDownloading = false;
      });
      return;
    }

    setState(() {
      _statusText = '下载完成，准备安装...';
    });

    await Future.delayed(const Duration(milliseconds: 500));

    final installed = await ApkInstaller.installApk(apkFile);
    
    if (!mounted) return;

    if (installed) {
      Navigator.pop(context);
    } else {
      setState(() {
        _statusText = '安装失败';
        _isDownloading = false;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return WillPopScope(
      onWillPop: () async => !_isDownloading,
      child: AlertDialog(
        title: const Text('正在更新'),
        content: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            LinearProgressIndicator(value: _progress),
            const SizedBox(height: 16),
            Text(_statusText),
          ],
        ),
        actions: [
          if (!_isDownloading)
            TextButton(
              onPressed: () {
                widget.downloadManager.cancelDownload();
                Navigator.pop(context);
              },
              child: const Text('关闭'),
            ),
        ],
      ),
    );
  }
}
```

---

## 六、统一升级服务

### 6.1 升级服务入口

**文件: `lib/core/updater/update_service.dart`**

```dart
import 'package:flutter/material.dart';
import 'channels/google_play_updater.dart';
import 'channels/self_hosted_updater.dart';

enum UpdateChannel {
  googlePlay,
  selfHosted,
}

class UpdateService {
  static UpdateService? _instance;
  UpdateService._();
  
  factory UpdateService() {
    _instance ??= UpdateService._();
    return _instance!;
  }

  late UpdateChannel _channel;
  late String _apiBaseUrl;
  SelfHostedUpdater? _selfHostedUpdater;

  /// 初始化
  void initialize({
    required UpdateChannel channel,
    String? apiBaseUrl,
  }) {
    _channel = channel;
    
    if (channel == UpdateChannel.selfHosted) {
      if (apiBaseUrl == null) {
        throw ArgumentError('apiBaseUrl is required for self-hosted channel');
      }
      _apiBaseUrl = apiBaseUrl;
      _selfHostedUpdater = SelfHostedUpdater(apiBaseUrl: apiBaseUrl);
    }

    print('UpdateService initialized with channel: $_channel');
  }

  /// 检查更新
  Future<void> checkForUpdate(BuildContext context) async {
    switch (_channel) {
      case UpdateChannel.googlePlay:
        await _checkGooglePlayUpdate(context);
        break;
      case UpdateChannel.selfHosted:
        await _selfHostedUpdater!.checkAndPromptUpdate(context);
        break;
    }
  }

  Future<void> _checkGooglePlayUpdate(BuildContext context) async {
    final hasUpdate = await GooglePlayUpdater.checkForUpdate();
    
    if (!hasUpdate) {
      print('No update available');
      return;
    }

    if (!context.mounted) return;

    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: const Text('发现新版本'),
        content: const Text('有新版本可用，是否立即更新？'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('稍后'),
          ),
          ElevatedButton(
            onPressed: () {
              Navigator.pop(context);
              GooglePlayUpdater.performFlexibleUpdate();
            },
            child: const Text('更新'),
          ),
        ],
      ),
    );
  }

  /// 手动检查更新
  Future<void> manualCheckUpdate(BuildContext context) async {
    showDialog(
      context: context,
      barrierDismissible: false,
      builder: (context) => const Center(
        child: CircularProgressIndicator(),
      ),
    );

    await Future.delayed(const Duration(seconds: 1));
    
    if (!context.mounted) return;
    Navigator.pop(context);

    await checkForUpdate(context);
  }
}
```

### 6.2 使用示例

**在 main.dart 中初始化:**

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  UpdateService().initialize(
    channel: UpdateChannel.selfHosted,
    apiBaseUrl: 'https://your-api.com',
  );
  
  runApp(const MyApp());
}
```

**在 App 启动时检查更新:**

```dart
class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _checkUpdate();
  }

  Future<void> _checkUpdate() async {
    await Future.delayed(const Duration(seconds: 3));
    
    if (!mounted) return;
    
    await UpdateService().checkForUpdate(context);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(/* ... */);
  }
}
```

---

## 七、后端接口设计

### 7.1 版本检测接口

```
GET /api/app/version/check

Query Parameters:
  - platform: android | ios
  - current_version: 1.1.0
  - current_version_code: 110

Response:
{
  "version": "1.2.0",
  "versionCode": 120,
  "downloadUrl": "https://your-cdn.com/app-release-v1.2.0.apk",
  "fileSize": 26843545,
  "fileSizeFriendly": "25.6 MB",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "forceUpdate": false,
  "updateLog": "1. 修复若干已知问题\n2. 优化用户体验",
  "releaseDate": "2024-01-15T10:00:00Z"
}
```

### 7.2 后端实现示例

Node.js + Express:

```javascript
app.get('/api/app/version/check', async (req, res) => {
  const { platform, current_version_code } = req.query;
  
  const latestVersion = await db.getLatestVersion(platform);
  
  if (parseInt(current_version_code) >= latestVersion.versionCode) {
    return res.json({ needUpdate: false });
  }
  
  res.json({
    needUpdate: true,
    version: latestVersion.version,
    versionCode: latestVersion.versionCode,
    downloadUrl: `https://cdn.example.com/${latestVersion.apkFile}`,
    fileSize: latestVersion.fileSize,
    fileSizeFriendly: formatFileSize(latestVersion.fileSize),
    sha256: latestVersion.sha256,
    forceUpdate: latestVersion.forceUpdate,
    updateLog: latestVersion.updateLog,
    releaseDate: latestVersion.releaseDate,
  });
});
```

### 7.3 数据库表设计

```sql
CREATE TABLE app_versions (
  id BIGSERIAL PRIMARY KEY,
  platform VARCHAR(10) NOT NULL,
  version VARCHAR(50) NOT NULL,
  version_code INTEGER NOT NULL,
  apk_file VARCHAR(255),
  download_url TEXT NOT NULL,
  file_size BIGINT NOT NULL,
  sha256 VARCHAR(64) NOT NULL,
  force_update BOOLEAN DEFAULT FALSE,
  update_log TEXT,
  release_date TIMESTAMP NOT NULL,
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMP DEFAULT NOW(),
  
  INDEX idx_platform (platform),
  INDEX idx_version_code (version_code),
  INDEX idx_active (is_active)
);
```

---

## 八、Android 原生配置

### 8.1 MainActivity 实现

**文件: `android/app/src/main/kotlin/com/yourapp/MainActivity.kt`**

```kotlin
package com.yourapp

import android.content.Intent
import android.net.Uri
import android.os.Build
import androidx.core.content.FileProvider
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel
import java.io.File

class MainActivity: FlutterActivity() {
    private val INSTALLER_CHANNEL = "com.yourapp/apk_installer"
    private val MARKET_CHANNEL = "com.yourapp/app_market"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        
        // APK 安装器
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, INSTALLER_CHANNEL)
            .setMethodCallHandler { call, result ->
                when (call.method) {
                    "installApk" -> {
                        val apkPath = call.argument<String>("apkPath")
                        if (apkPath != null) {
                            installApk(apkPath)
                            result.success(true)
                        } else {
                            result.error("INVALID_PATH", "APK path is null", null)
                        }
                    }
                    else -> result.notImplemented()
                }
            }
        
        // 应用市场检测
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, MARKET_CHANNEL)
            .setMethodCallHandler { call, result ->
                when (call.method) {
                    "getInstallerPackageName" -> {
                        try {
                            val installer = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                                packageManager.getInstallSourceInfo(packageName).installingPackageName
                            } else {
                                @Suppress("DEPRECATION")
                                packageManager.getInstallerPackageName(packageName)
                            }
                            result.success(installer)
                        } catch (e: Exception) {
                            result.success(null)
                        }
                    }
                    else -> result.notImplemented()
                }
            }
    }

    private fun installApk(apkPath: String) {
        val apkFile = File(apkPath)
        if (!apkFile.exists()) return

        val intent = Intent(Intent.ACTION_VIEW)
        intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK

        val apkUri: Uri = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
            intent.flags = Intent.FLAG_GRANT_READ_URI_PERMISSION
            FileProvider.getUriForFile(
                this,
                "${applicationContext.packageName}.fileprovider",
                apkFile
            )
        } else {
            Uri.fromFile(apkFile)
        }

        intent.setDataAndType(apkUri, "application/vnd.android.package-archive")
        startActivity(intent)
    }
}
```

### 8.2 Gradle Flavor 配置

**文件: `android/app/build.gradle`**

```gradle
android {
    // 其他配置...

    flavorDimensions "channel"
    
    productFlavors {
        googleplay {
            dimension "channel"
            applicationIdSuffix ".googleplay"
            versionNameSuffix "-gp"
        }
        
        china {
            dimension "channel"
            versionNameSuffix "-china"
        }
    }
}
```

### 8.3 Google Play 版本 Manifest

**文件: `android/app/src/googleplay/AndroidManifest.xml`**

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    
    <application>
        <!-- Google Play 版本不需要 FileProvider -->
    </application>
</manifest>
```

### 8.4 自建渠道 Manifest

**文件: `android/app/src/china/AndroidManifest.xml`**

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
    
    <application>
        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="${applicationId}.fileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/file_paths" />
        </provider>
    </application>
</manifest>
```

### 8.5 FileProvider 路径配置

**文件: `android/app/src/main/res/xml/file_paths.xml`**

```xml
<?xml version="1.0" encoding="utf-8"?>
<paths>
    <files-path name="internal_files" path="." />
    <cache-path name="cache" path="." />
</paths>
```

### 8.6 构建命令

```bash
# Google Play 版本
flutter build apk --flavor googleplay --dart-define=CHANNEL=googleplay

# 国内版本
flutter build apk --flavor china --dart-define=CHANNEL=china
```

---

## 九、安全性考虑

### 9.1 HTTPS 强制

所有下载链接必须使用 HTTPS 协议：

```dart
if (!downloadUrl.startsWith('https://')) {
  throw Exception('Download URL must use HTTPS');
}
```

### 9.2 SHA-256 完整性校验

下载完成后必须校验文件完整性：

```dart
final isValid = await _verifySha256(apkFile, expectedSha256);
if (!isValid) {
  await apkFile.delete();
  throw Exception('SHA-256 verification failed');
}
```

### 9.3 渠道隔离

- Google Play 版本：不包含任何安装相关权限和代码
- 自建渠道版本：包含完整的下载安装功能
- 使用 Gradle Flavor 在构建层面完全隔离

### 9.4 应用市场策略

检测应用来源，避免与应用市场升级机制冲突：

```dart
final isFromMarket = await AppMarketDetector.isFromAppMarket();
if (isFromMarket) {
  // 引导用户去应用市场更新
  AppMarketDetector.openAppMarketDetail(packageName);
} else {
  // 使用自建更新
  selfHostedUpdate();
}
```

---

## 十、实施步骤

### Step 1: 添加依赖

```bash
flutter pub add package_info_plus dio in_app_update permission_handler path_provider crypto url_launcher
```

### Step 2: 创建目录结构

```bash
mkdir -p lib/core/updater/{models,channels}
```

### Step 3: 创建 Flutter 代码

按照本文档创建以下文件：
- models/version_info.dart
- version_checker.dart
- download_manager.dart
- apk_installer.dart
- app_market_detector.dart
- channels/google_play_updater.dart
- channels/self_hosted_updater.dart
- update_service.dart

### Step 4: 生成 JSON 序列化代码

```bash
flutter pub run build_runner build --delete-conflicting-outputs
```

### Step 5: 配置 Android 原生代码

- 修改 MainActivity.kt
- 配置 build.gradle
- 创建 Flavor 专属 AndroidManifest.xml
- 添加 file_paths.xml

### Step 6: 实现后端 API

实现版本检测接口，返回最新版本信息。

### Step 7: 初始化服务

在 main.dart 中初始化 UpdateService。

### Step 8: 构建测试

```bash
# Google Play 版本
flutter build apk --flavor googleplay --dart-define=CHANNEL=googleplay --release

# 国内版本
flutter build apk --flavor china --dart-define=CHANNEL=china --release
```

### Step 9: 验证权限

```bash
# 检查 Google Play 版本（不应有安装权限）
aapt dump permissions build/app/outputs/flutter-apk/app-googleplay-release.apk | grep INSTALL

# 检查国内版本（应有安装权限）
aapt dump permissions build/app/outputs/flutter-apk/app-china-release.apk | grep INSTALL
```

### Step 10: 测试验证

- 测试下载流程
- 测试应用市场检测
- 测试强制更新
- 测试断网场景

---

## 附录

### A. 常见问题

| 问题 | 解决方案 |
|------|---------|
| 下载失败 | 检查网络、确保 HTTPS、添加重试机制 |
| 无法安装 | 确认 china flavor 有安装权限 |
| SHA-256 校验失败 | 重新下载、检查网络稳定性 |
| Google Play 更新不显示 | 确保 versionCode 递增 |

### B. 调试命令

```bash
# 查看 APK 权限
aapt dump permissions app-release.apk

# 查看 APK 包名
aapt dump badging app-release.apk | grep package

# 生成 SHA-256
sha256sum app-release.apk
```

### C. 参考资源

- [Flutter 官方文档](https://flutter.dev/docs)
- [in_app_update 插件](https://pub.dev/packages/in_app_update)
- [Android FileProvider 指南](https://developer.android.com/reference/androidx/core/content/FileProvider)

---

文档版本: 2.0  
最后更新: 2024-01-15