Installation and Deployment - langningchen/miniapp GitHub Wiki

Miniapp 安装部署

本指南详细介绍如何安装、部署、管理和更新 miniapp 应用，包括生产环境部署的最佳实践。

🎯 部署概览

Miniapp 的部署过程包括：

  • 📦 应用打包 - 生成 .amr 格式的安装包
  • 📤 文件传输 - 将应用上传到设备
  • 🔧 应用安装 - 使用 miniapp_cli 安装
  • ✅ 安装验证 - 确认应用正常运行
  • 🔄 更新管理 - 版本升级和回滚

📋 部署前准备

确认编译完成

确保已完成 编译流程详解：

# 检查编译产物
ls -la dist/

# 应该包含：
# miniapp.amr - 主安装包
# 其他资源文件

验证设备连接

# 确认设备连接正常
adb devices

# 检查设备存储空间
adb shell df -h /userdisk/

# 确认设备支持 miniapp
adb shell miniapp_cli --help

📦 应用打包详解

理解 AMR 格式

AMR (Application Mobile Runtime) 是有道词典笔的应用包格式：

  • 包含编译后的二进制文件
  • 包含前端资源文件
  • 包含配置和元数据
  • 支持签名和验证

检查打包内容

# 查看 AMR 包内容（如果可以解压）
file dist/miniapp.amr

# 检查包大小
ls -lh dist/miniapp.amr

# 验证包的完整性
md5sum dist/miniapp.amr

自定义打包配置

如果需要修改打包配置，编辑相应的配置文件：

// 应用配置示例
{
  "name": "miniapp",
  "version": "1.0.0",
  "description": "有道词典笔 Miniapp",
  "main": "app.js",
  "permissions": [
    "network",
    "storage",
    "microphone"
  ]
}

📤 文件传输优化

高效传输策略

# 压缩传输（如果网络较慢）
gzip dist/miniapp.amr
adb push dist/miniapp.amr.gz /userdisk/Favorite/
adb shell "cd /userdisk/Favorite && gunzip miniapp.amr.gz"

# 验证传输完整性
local_md5=$(md5sum dist/miniapp.amr | cut -d' ' -f1)
remote_md5=$(adb shell md5sum /userdisk/Favorite/miniapp.amr | cut -d' ' -f1)
if [ "$local_md5" = "$remote_md5" ]; then
    echo "✅ 传输完整"
else
    echo "❌ 传输有误"
fi

批量文件传输

如果需要传输多个文件：

# 创建传输脚本
cat > transfer_files.sh << 'EOF'
#!/bin/bash
FILES=(
    "dist/miniapp.amr"
    "config/app_config.json"
    "assets/icon.png"
)

for file in "${FILES[@]}"; do
    echo "传输 $file..."
    adb push "$file" "/userdisk/Favorite/$(basename "$file")"
done
EOF

chmod +x transfer_files.sh
./transfer_files.sh

🔧 应用安装管理

基本安装流程

# 1. 上传应用包
adb push dist/miniapp.amr /userdisk/Favorite/miniapp.amr

# 2. 检查上传结果
adb shell ls -la /userdisk/Favorite/miniapp.amr

# 3. 安装应用
adb shell miniapp_cli install /userdisk/Favorite/miniapp.amr

# 4. 验证安装
adb shell miniapp_cli list | grep miniapp

高级安装选项

# 强制安装（覆盖已有版本）
adb shell miniapp_cli install --force /userdisk/Favorite/miniapp.amr

# 指定安装位置
adb shell miniapp_cli install --path /custom/path /userdisk/Favorite/miniapp.amr

# 安装时设置权限
adb shell miniapp_cli install --permissions network,storage /userdisk/Favorite/miniapp.amr

安装状态检查

# 查看所有已安装的 miniapp
adb shell miniapp_cli list

# 查看特定应用信息
adb shell miniapp_cli info com.miniapp.package

# 检查应用状态
adb shell miniapp_cli status com.miniapp.package

🚀 应用启动和测试

启动应用

# 启动应用
adb shell miniapp_cli launch com.miniapp.package

# 或通过 Activity Manager 启动
adb shell am start -n com.miniapp.package/.MainActivity

# 检查应用是否在运行
adb shell ps aux | grep miniapp

功能测试

# 监控应用启动日志
adb logcat -c
adb shell miniapp_cli launch com.miniapp.package &
adb logcat -s "MiniApp:*"

# 测试网络功能
adb shell "curl -I http://www.baidu.com"

# 测试存储功能
adb shell "ls -la /userdisk/miniapp/"

性能测试

# 监控内存使用
adb shell dumpsys meminfo com.miniapp.package

# 监控 CPU 使用
adb shell top -p $(adb shell pidof com.miniapp.package)

# 监控启动时间
time adb shell miniapp_cli launch com.miniapp.package

🔄 版本管理

版本信息管理

# 查看当前版本
adb shell miniapp_cli version com.miniapp.package

# 查看版本历史
adb shell ls -la /userdisk/miniapp/versions/

# 备份当前版本
adb pull /userdisk/Favorite/miniapp.amr ./backup/miniapp_v$(date +%Y%m%d).amr

应用更新

#!/bin/bash
# 应用更新脚本 update_miniapp.sh

NEW_VERSION="$1"
if [ -z "$NEW_VERSION" ]; then
    echo "用法: $0 <新版本号>"
    exit 1
fi

echo "开始更新到版本 $NEW_VERSION..."

# 1. 备份当前版本
adb shell miniapp_cli backup com.miniapp.package

# 2. 停止应用
adb shell miniapp_cli stop com.miniapp.package

# 3. 上传新版本
adb push "dist/miniapp_v${NEW_VERSION}.amr" "/userdisk/Favorite/miniapp.amr"

# 4. 更新应用
adb shell miniapp_cli update com.miniapp.package /userdisk/Favorite/miniapp.amr

# 5. 启动应用
adb shell miniapp_cli launch com.miniapp.package

echo "更新完成"

版本回滚

# 查看可用备份
adb shell miniapp_cli list-backups com.miniapp.package

# 回滚到指定版本
adb shell miniapp_cli rollback com.miniapp.package v1.0.0

# 验证回滚
adb shell miniapp_cli version com.miniapp.package

🔧 应用配置管理

配置文件管理

# 查看配置文件
adb shell cat /userdisk/miniapp/config.json

# 备份配置
adb pull /userdisk/miniapp/config.json ./backup/

# 更新配置
cat > new_config.json << 'EOF'
{
  "debug": false,
  "api_endpoint": "https://api.example.com",
  "cache_size": "100MB"
}
EOF

adb push new_config.json /userdisk/miniapp/config.json

环境变量设置

# 设置生产环境变量
adb shell "echo 'NODE_ENV=production' > /userdisk/miniapp/.env"

# 设置调试模式
adb shell "echo 'DEBUG=true' >> /userdisk/miniapp/.env"

# 查看环境变量
adb shell cat /userdisk/miniapp/.env

📊 部署监控

创建监控脚本

#!/bin/bash
# 部署监控脚本 monitor_deployment.sh

APP_PACKAGE="com.miniapp.package"

while true; do
    # 检查应用状态
    STATUS=$(adb shell miniapp_cli status $APP_PACKAGE 2>/dev/null)
    
    # 检查进程
    PID=$(adb shell pidof $APP_PACKAGE 2>/dev/null)
    
    # 检查内存使用
    if [ -n "$PID" ]; then
        MEMORY=$(adb shell dumpsys meminfo $PID | grep "TOTAL" | awk '{print $2}')
        echo "[$(date)] 应用运行中 - PID: $PID, 内存: ${MEMORY}KB"
    else
        echo "[$(date)] 应用未运行"
    fi
    
    sleep 30
done

日志收集

# 自动收集应用日志
#!/bin/bash
LOG_DIR="logs/$(date +%Y%m%d)"
mkdir -p $LOG_DIR

# 收集应用日志
adb logcat -s "MiniApp:*" > $LOG_DIR/app.log &

# 收集系统日志
adb logcat -s "System:*" > $LOG_DIR/system.log &

echo "日志收集已启动，保存到 $LOG_DIR/"

🔒 安全部署

权限检查

# 检查应用权限
adb shell dumpsys package com.miniapp.package | grep permission

# 验证应用签名
adb shell dumpsys package com.miniapp.package | grep signature

# 检查文件权限
adb shell ls -la /userdisk/miniapp/

安全配置

# 设置安全模式
adb shell "echo 'SECURITY_MODE=strict' >> /userdisk/miniapp/.env"

# 启用访问日志
adb shell "echo 'ACCESS_LOG=true' >> /userdisk/miniapp/.env"

# 配置白名单
cat > whitelist.json << 'EOF'
{
  "allowed_domains": [
    "api.youdao.com",
    "dict.youdao.com"
  ]
}
EOF

adb push whitelist.json /userdisk/miniapp/

📋 部署检查清单

部署前检查：

  • 编译无错误
  • 所有测试通过
  • 版本号正确
  • 配置文件正确
  • 依赖库齐全

部署过程检查：

  • 设备连接稳定
  • 存储空间充足
  • 文件传输完整
  • 安装成功
  • 权限配置正确

部署后验证：

  • 应用能正常启动
  • 基本功能正常
  • 性能指标正常
  • 日志输出正常
  • 配置生效

🚀 下一步

部署完成后，请参考：

❗ 常见部署问题

问题1：安装失败 - 权限不足

解决方案：

# 检查设备权限
adb shell whoami

# 使用 root 权限安装
adb shell su -c "miniapp_cli install /userdisk/Favorite/miniapp.amr"

# 检查文件权限
adb shell ls -la /userdisk/Favorite/miniapp.amr

问题2：应用启动失败

解决方案：

# 查看详细错误信息
adb logcat -c
adb shell miniapp_cli launch com.miniapp.package
adb logcat -d | grep -E "(FATAL|ERROR)"

# 检查依赖库
adb shell ldd /path/to/miniapp/binary

# 检查配置文件
adb shell cat /userdisk/miniapp/config.json

问题3：版本冲突

解决方案：

# 完全卸载旧版本
adb shell miniapp_cli uninstall com.miniapp.package

# 清理缓存
adb shell rm -rf /userdisk/miniapp/cache/

# 重新安装
adb shell miniapp_cli install /userdisk/Favorite/miniapp.amr

问题4：性能问题

解决方案：

# 检查系统资源
adb shell cat /proc/meminfo
adb shell cat /proc/loadavg

# 优化应用配置
adb shell "echo 'CACHE_SIZE=50MB' >> /userdisk/miniapp/.env"

# 重启应用
adb shell miniapp_cli restart com.miniapp.package

需要帮助？ 查看 常见问题解决 获取更多部署和运维解决方案。

⚠️ **GitHub.com Fallback** ⚠️