# app-ship **Repository Path**: flu-cli/app-ship ## Basic Information - **Project Name**: app-ship - **Description**: 一站式多平台 App 上传工具。支持全平台安装包（安卓/iOS/鸿蒙）一键分发至各大应用商店，提供透明开源、官方 API 调用、多并发上传及环境变量配置支持。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 2 - **Created**: 2026-03-24 - **Last Updated**: 2026-10-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # App Ship 多平台应用发布与分发引擎 — CLI 命令行工具 & npm 库，按平台真实动作处理构建上传、草稿、测试分发与送审。 [![npm version](https://img.shields.io/npm/v/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship) [![npm downloads](https://img.shields.io/npm/dm/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) **Languages**: [English](https://gitee.com/flu-cli/flu-cli/blob/main/packages/app-ship/README_EN.md) | 简体中文 ## 目录 - [⚡ 3分钟快速开始](#-3分钟快速开始) - [特性](#特性) - [使用指南](#使用指南) - [支持平台](#支持平台) - [详细配置参考](#详细配置参考) - [常见问题](#常见问题) - [安全与隐私](#安全与隐私) - [开发指南](#开发指南) - [社区与支持](#社区与支持) --- ## ⚡ 3分钟快速开始 ### 1️⃣ 安装 ```bash npm install -g @huoye/app-ship ``` ### 2️⃣ 初始化配置 ```bash app-ship init ``` 这会生成 `app-ship.yaml` 配置文件。 ### 3️⃣ 迁移凭据 如果已有包含凭据或环境变量占位符的旧配置，先迁移到 macOS Keychain 与本地加密 vault： ```bash app-ship credentials migrate -c app-ship.yaml -o app-ship.safe.yaml app-ship credentials list ``` 新配置只引用不含秘密的 `credentialProfile`： ```yaml publish: pgyer: enable: true credentialProfile: app-ship-pgyer access: type: public # 必须显式选择 public / password / invite ``` ### 4️⃣ 上传应用 ```bash app-ship upload -c app-ship.safe.yaml -f app-release.apk ``` CLI 会先显示绑定产物 SHA-256 的发布计划。需要显式确认的平台应在核对后使用当前计划 ID 重跑： ```bash app-ship upload -c app-ship.safe.yaml -f app-release.apk \ --confirm-plan ``` > 💡 需要上传到特定平台？使用 `--platform` 参数： > > ```bash > app-ship upload -c app-ship.yaml -f app.apk --platform pgyer,huawei > ``` --- ## 特性 - **8 大平台实测通过** ✅：蒲公英、华为、小米、OPPO、vivo、腾讯应用宝、App Store、鸿蒙 - **并行上传**：多平台同时上传，可配置并发数 - **智能分发**：自动路由 APK → Android 商店、IPA → Apple、HAP → 鸿蒙 - **指数退避重试**：网络波动自动重试，可配置退避策略 - **安全发布合同**：发布计划绑定平台、动作、包名、版本和产物 SHA-256 - **三种使用方式**：CLI 命令行、npm 库、VSCode 插件 - **框架无关**：Flutter、React Native、原生 Android/iOS、鸿蒙均可使用 - **官方 API**：直接调用各平台官方 API，无第三方转接，透明开源 --- ## 使用指南 ### 1️⃣ CLI 命令行 适合 DevOps、CI/CD 流水线和命令行用户。 **常用命令**： ```bash # 查看支持的平台 app-ship platforms # 上传到所有启用的平台 app-ship upload -c app-ship.yaml -f app-release.apk # 仅上传到指定平台 app-ship upload -c app-ship.yaml -f app-release.apk --platform pgyer,huawei # Google Play 必须确认当前产物对应的计划，首版只进入 internal 草稿 app-ship upload -c app-ship.yaml -f app-release.aab \ --platform google_play \ --confirm-plan # 将旧 YAML 凭据迁移到本机安全存储，并输出不含秘密的新配置 app-ship credentials migrate -c app-ship.yaml -o app-ship.safe.yaml app-ship credentials list # 带元数据上传 app-ship upload -c app-ship.yaml -f app-release.apk \ --version 2.0.0 \ --build-number 42 \ --changelog "修复了已知问题" # 显示详细日志 app-ship upload -c app-ship.yaml -f app-release.apk --verbose # 查看当前项目最近的本地发布回执；JSON 可直接交给 AI 或脚本处理 app-ship history app-ship history --project /path/to/project --json # 查看帮助 app-ship --help app-ship --version ``` **CLI 参数说明**： | 参数 | 简写 | 说明 | | -------------------- | ---- | ---------------------------- | | `--config ` | `-c` | 配置文件路径 (YAML) | | `--file ` | `-f` | 安装包路径 (APK/IPA/AAB/HAP) | | `--platform ` | `-p` | 逗号分隔的平台列表（可选） | | `--version ` | `-v` | 版本号（默认："1.0.0"） | | `--build-number ` | `-b` | 构建号（默认："1"） | | `--changelog ` | - | 更新日志 | | `--confirm-plan ` | - | 确认预览中的一个或多个计划 ID | | `--verbose` | - | 显示详细输出 | 上传完成后会自动在 `~/.flu-cli/release-receipts/` 保存项目隔离的结构化回执。回执只记录产物路径、大小、SHA-256、渠道状态和白名单远端标识；不会保存 Token、密钥、服务账号内容或完整平台响应。每个项目最多保留 100 条。 --- ### 2️⃣ npm 库（编程集成） 当前第二批把完整安全门禁接在 CLI `upload` 入口。`UploadManager` 与各平台 adapter 是可信进程内的 低层能力，不会替调用方生成发布计划或取得用户确认，不能直接暴露给 MCP、Web 请求或其它不可信入口。 自建发布系统必须实现与 CLI 等价的流程：先绑定产物生成每个平台的 `ReleasePlan`，再校验 `ReleaseConfirmation`，最后才解析 Profile 并调用低层上传器。没有完成这条编排时请使用 CLI。 **可信本地集成**： 以下只展示可信本地凭据解析边界，不构成可直接执行上传的完整示例。调用方不得记录或序列化 `resolvedConfig`，也不得跳过前述 plan gate： ```typescript import { ConfigValidator, createDefaultCredentialProfileStore, hydrateCredentialProfiles, } from "@huoye/app-ship"; const config = ConfigValidator.loadAndValidate("./app-ship.yaml"); if (!config) throw new Error("配置无效"); const resolvedConfig = await hydrateCredentialProfiles( config, createDefaultCredentialProfileStore(), ); if (!ConfigValidator.validateResolved(resolvedConfig)) throw new Error("配置无效"); ``` --- ### 3️⃣ VSCode 插件（可视化） 安装 **Flu CLI** VSCode 插件，在 IDE 内点击操作即可完成构建和上传。 **功能特点**： - 实时构建 & 上传进度展示 - 可视化配置面板 - 自动密钥管理 - 下载链接 + 二维码展示 详见 [VSCode 插件文档](https://gitee.com/flu-cli/flu-cli/tree/master/packages/vscode-extension#readme)。 --- ## 支持平台 本工具直接调用各平台**官方 API**，所有 API 地址和文档均为平台官方提供。 | 平台 | 文件 | 认证 | 官方 API 文档 | 状态 | | ---------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | 🐧 **蒲公英** | APK, IPA | API Key | [pgyer.com/api](https://www.pgyer.com/doc/view/api_basic) | ✅ 已实测 | | 🟥 **华为** | APK, AAB | OAuth2 | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/publish-app-0000001100974822) | ✅ 已实测 | | 🔴 **小米** | APK | RSA 签名 | [小米开放平台](https://dev.mi.com/console/doc/detail?pId=1695) | ✅ 已实测 | | 🟠 **OPPO** | APK | HMAC-SHA256 | [OPPO 开发者平台](https://open.oppomobile.com/wiki/doc#id=10106) | ✅ 已实测 | | 🔵 **vivo** | APK | HMAC + MD5 | [vivo 开放平台](https://dev.vivo.com.cn/openAbility/interface) | ✅ 已实测 | | 🐧 **腾讯应用宝** | APK | HMAC-SHA256 | [应用宝平台](https://open.qq.com/doc/?id=11016) | ✅ 已实测 | | 🍎 **Apple App Store** | IPA | Apple ID / API | [App Store Connect API](https://developer.apple.com/app-store-connect/api/) | ✅ 已实测 | | 🟣 **鸿蒙** | HAP | OAuth2 | [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) | ✅ 已实测 | | 🍎 **TestFlight** | IPA | Apple API | [TestFlight API](https://developer.apple.com/testflight/testers/) | ⚠️ 开发中 | | 🍎 **Ad Hoc** | IPA | 证书 | [Apple 文档](https://developer.apple.com/documentation/xcode/distributing-your-app-for-beta-testing) | ⚠️ 开发中 | | 🎮 **Google Play** | AAB | Service Account | [Android Publisher API](https://developers.google.com/android-publisher/api-ref/rest) | ✅ internal 草稿已实测 | --- ## 详细配置参考 ### 安全的 app-ship.yaml 配置 所有凭据从平台官方后台申请，但 YAML 只保存 `credentialProfile` 引用。旧配置用 `app-ship credentials migrate` 一次性导入；迁移命令拒绝覆盖源文件。 ```yaml version: "1.0.0" # 重试策略（可选） retry: maxRetries: 3 initialDelayMs: 1000 backoffMultiplier: 2 maxDelayMs: 30000 publish: # ── 蒲公英 (官方 API: https://www.pgyer.com/doc/view/api_basic) ── pgyer: enable: true credentialProfile: app-ship-pgyer description: "测试版本" access: type: password # ── 华为 (官方 API: https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) ── huawei: enable: false credentialProfile: app-ship-huawei appId: "YOUR_APP_ID" packageName: "com.example.app" releaseType: draft # ── 小米 (官方 API: https://dev.mi.com/console/doc/detail?pId=1695) ── xiaomi: enable: false credentialProfile: app-ship-xiaomi packageName: "com.example.app" # ── OPPO (官方 API: https://open.oppomobile.com/wiki/doc#id=10106) ── oppo: enable: false credentialProfile: app-ship-oppo # ── vivo (官方 API: https://dev.vivo.com.cn/openAbility/interface) ── vivo: enable: false credentialProfile: app-ship-vivo # ── 腾讯应用宝 (官方 API: https://open.qq.com/doc/?id=11016) ── tencent: enable: false credentialProfile: app-ship-tencent # ── 鸿蒙 (官方 API: https://developer.huawei.com/consumer/cn/doc/development/AppGallery-connect-Guides/agcapi-getstarted-0000001111209402) ── harmony: enable: false credentialProfile: app-ship-harmony appId: "YOUR_APP_ID" packageName: "com.example.app" # ── App Store / TestFlight (官方 API: https://developer.apple.com/app-store-connect/api/) ── app_store: enable: false mode: app_store credentialProfile: app-ship-app_store # ── Google Play（首版仅上传内部测试草稿；API 轨道标识为 internal）── google_play: enable: false credentialProfile: app-ship-google_play packageName: "com.example.app" track: internal ``` Google Play 连接器只从用户本机读取服务账号文件，并直接请求 Android Publisher API。 应用需已在 Play Console 创建且包名一致；首版只接受 AAB，并固定写入 `internal` 轨道的 `draft` 发布记录，不提交审核，也不发布到测试用户或生产用户。 如果应用从未上传过 APK/AAB，需先在 Play Console 手工上传并保存首个版本，之后才能使用 Edits API；CLI 上传还必须显式提供预览中的 `--confirm-plan `。 ### 环境变量支持 旧配置在迁移时仍可使用 `${VAR_NAME}`。迁移完成后，安全配置只保留 Profile： ```yaml pgyer: enable: true credentialProfile: app-ship-pgyer access: type: invite ``` 在 CI/CD 中设置环境变量即可： ```bash export PGYER_API_KEY="your-actual-key" app-ship credentials migrate -c app-ship.legacy.yaml -o app-ship.yaml ``` --- ## 常见问题 ### Q: 如何获取各平台的 API Key？ **蒲公英**: 登录 [pgyer.com](https://www.pgyer.com) → 账号设置 → API 信息 **华为**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → 我的项目 → 项目设置 → 密钥管理 **小米**: [小米开放平台](https://dev.mi.com/console/) → 应用管理 → 应用详情 → 上传接口 **OPPO/vivo/腾讯**: 对应开发者平台 → 应用管理 → API 管理 **Apple**: [App Store Connect](https://appstoreconnect.apple.com) → 用户和访问权限 → API 密钥 --- ### Q: 上传失败如何排查？ 1. 使用 `--verbose` 参数查看详细日志： ```bash app-ship upload -c app-ship.yaml -f app.apk --verbose ``` 2. 检查以下几点： - 网络连接正常 - 各平台服务状态正常 - API Key 和权限配置正确 - 应用包格式是否正确 3. 查看 [Issues](https://gitee.com/flu-cli/flu-cli/issues) 是否有类似问题 --- ### Q: 支持 Windows / Mac 吗？ 上传适配器仍可在 Node.js 支持的平台运行，但本批安全凭据存储只完成 macOS Keychain 垂直切片。CLI 在 Linux / Windows 会明确停止，不会退回 YAML 明文凭据。 --- ### Q: 可以在 CI/CD 中使用吗？ 当前不把无界面 CI Keychain 会话声明为已验证能力。CI 专用凭据提供器及身份边界完成后再开放； 不要通过回退到 YAML 明文或命令行参数绕过限制。 --- ## 安全与隐私 ### 🔐 密钥管理 - **目标边界**：项目 YAML、Git、日志、回执、MCP 参数和模型上下文不得包含原始凭据 - **本地保管**：普通 Secret 进入操作系统安全存储，JSON / `.p8` 进入本地加密凭据库或经检查的外部路径 - **MCP 脱敏**：MCP 只能读取 `credentialProfile`、`configured`、`verified` 等元数据，不能读取或导出秘密 - **本地处理**：所有认证和签名操作都在你的机器本地执行 - **官方渠道**：直接调用各平台官方 API，无第三方转接 > 当前安全存储垂直切片只验证 macOS Keychain。Linux / Windows 会明确停止，待对应系统安全存储完成验证后再开放。旧 YAML / 环境变量只允许作为 `credentials migrate` 的迁移输入，`upload` 要求使用 `credentialProfile`。 ### 🛡️ 最佳实践 1. **保护配置文件** - 将 `app-ship.yaml` 加入 `.gitignore`： ```bash echo "app-ship.yaml" >> .gitignore ``` 2. **在 CI/CD 中使用环境变量** - 不要提交凭证到版本控制 3. **定期轮换凭证** - 按各平台建议定期更新 API Key 4. **权限最小化** - 为 API Key 设置尽可能细粒度的权限 ### 📜 法律声明 使用本工具时，你同意： - 遵守各平台的服务协议和 API 使用政策 - 合法获取并妥善保管凭证和密钥 - 自行承担因不当使用造成的一切后果 本工具作者不对违规使用或产生的损失承担任何责任。 --- ## 开发指南 ### 项目结构 ``` packages/app-ship/ ├── src/ │ ├── index.ts # 📦 库入口 — 导出所有公共 API │ ├── cli.ts # 🖥️ CLI 入口 — 命令行工具主程序 │ ├── types.ts # 📐 类型定义 — 所有接口和类型 │ ├── adapters/ # 🔌 上传适配器层 │ │ ├── pgyer_uploader.ts │ │ ├── huawei_uploader.ts │ │ ├── xiaomi_uploader.ts │ │ └── ... │ ├── utils/ # 🔧 工具层 │ │ ├── upload-manager.ts # 并发调度 + 智能分发 │ │ ├── retry-strategy.ts # 指数退避 + 错误分类 │ │ └── ... │ └── validators/ # ✅ 验证层 │ ├── config_validator.ts │ └── env_validator.ts ├── dist/ ├── package.json └── tsconfig.json ``` ### 本地开发 ```bash # 安装依赖 npm install # 构建 npm run build # 开发模式（监听文件变化） npm run dev ``` ### 新增平台支持（3 步） 1. **实现 `IUploader` 接口**（在 `src/adapters/` 下） 2. **在 `src/adapters/index.ts` 导出** 3. **在 `src/utils/upload-manager.ts` 注册** 详见源码注释。 --- ## 目录架构 ``` ┌─────────────────────────────────┐ │ 用户界面层 │ ├──────┬─────────────┬─────────────┤ │ CLI │ VSCode 插件 │ npm 库 │ └──┬───┴──────┬──────┴──────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────┐ │ 配置管理 & 验证 │ └──────────────┬──────────────────┘ ▼ ┌─────────────────────────────────┐ │ 上传管理（并发、智能分发） │ └──────────────┬──────────────────┘ ▼ ┌─────────────────────────────────┐ │ 平台适配器（8+ 个平台） │ └──────────────┬──────────────────┘ ▼ ┌─────────────────────────────────┐ │ 基础设施（重试、JWT、日志） │ └─────────────────────────────────┘ ``` --- ## 社区与支持 扫描下方二维码或搜索公众号**火叶**关注我们 | 关注公众号 | 加作者微信入群 | 赞赏支持 | | :--------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: | | 微信号
**火叶** | 微信号
**微信**: `Huoye-TT`
（备注: `flu-cli`） | [给作者加鸡腿 ☕️](http://huozhiye.cn/flu-cli/advanced/rewards/rewards) | > 💡 你也可以点击插件详情页顶部的 **Sponsor** 按钮来支持本项目。 --- ## License MIT | Copyright © 2025-2026 火叶工作室