# hpt_pack
**Repository Path**: igancao/hpt_pack
## Basic Information
- **Project Name**: hpt_pack
- **Description**: htp_pack 是一个本地部署的可视化构建平台，支持 Android、iOS、HarmonyOS、Flutter 等主流应用类型的一站式打包、签名与分发。通过集成 GitLab 源码拉取、阿里云 OSS 产物上传及内网扫码安装功能，显著提升移动端持续交付效率。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-01-23
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 📦 hpt_pack — 本地可视化多平台打包平台
> ⚠️ **仅支持 macOS 系统**
> 当前项目尚未在 Windows 或 Linux 上验证运行，请务必在 **macOS 环境**下操作。
`hpt_pack` 是一个**本地部署的可视化构建平台**，支持 **Android（APK）、iOS（IPA）、HarmonyOS（HAP）、Flutter** 等主流应用的一站式打包、签名与分发。通过集成 GitLab 源码拉取、阿里云 OSS 产物上传及内网扫码安装功能，显著提升移动端持续交付效率。
---
## ✨ 核心功能
- ✅ **全平台构建**：Android / iOS / HarmonyOS / Flutter
- ✅ **灵活参数配置**：自定义 build type、flavor、channel、环境变量等
- ✅ **自动化签名**：内置证书管理，自动完成 APK/IPA/HAP 签名
- ✅ **扫码安装**：生成二维码，手机扫码即可内网安装（需局域网）
- ✅ **CI/CD 集成**：对接 GitLab + 阿里云 OSS
- ✅ **技术栈**：后端基于 **FastAPI**，前端采用 **Flutter Web**
---
## 🖥️ 部署建议
`hpt_pack` 可部署于：
- **公司专用打包机**（推荐）：集中管理构建环境，避免占用开发机资源；
- **本地开发电脑**：便于调试和快速验证。
> ⚠️ **重要前提**：
> - 打包机必须能访问 **公司 GitLab 实例**（拉取代码、切换分支、读取 tags）；
> - 若 GitLab 启用私有网络或自签名证书，请提前配置代理或信任证书；
> - 使用扫码安装功能时，**手机与打包机需在同一局域网**，且端口 `8010` 未被防火墙阻断。
---
## 🛠️ 前期准备（macOS）
### 1. 安装 Python 3.13.11（使用 `pyenv`）
```bash
# 安装 pyenv（推荐 Homebrew）
brew install pyenv
# 配置 shell（以 zsh 为例）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# 重载配置
source ~/.zshrc
# 安装并设为全局默认版本
pyenv install 3.13.11
pyenv global 3.13.11
```
> 🔗 参考：[pyenv 官方 macOS 安装指南](https://github.com/pyenv/pyenv#homebrew-in-macos)
---
### 2. 安装 Poetry（依赖管理）
```bash
# 安装 Poetry
curl -sSL https://install.python-poetry.org | python3 -
# 将 Poetry 加入 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 验证安装
poetry --version
```
> 💡 若提示权限问题，请确保 `$HOME/.local/bin` 存在且可写。
> 🔗 参考：[Poetry 官方安装文档](https://python-poetry.org/docs/#installation)
---
### 3. 安装并配置 MySQL
#### 推荐方式：Homebrew
```bash
brew install mysql
brew services start mysql
mysql_secure_installation # 按提示设置 root 密码
```
#### 创建数据库
```sql
mysql -u root -p
CREATE DATABASE hpt_pack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
> ⚠️ **注意**：若使用非 `root` 用户，请授予 `hpt_pack` 数据库的 `CREATE`, `ALTER`, `DROP`, `INDEX` 等 DDL 权限。
---
### 4. 配置项目参数
#### 📄 `settings.toml`（主配置文件）
配置公共参数，如：
- 数据库连接 URL
- GitLab 地址
- 阿里云 OSS endpoint
#### 🔒 `.secrets.toml`（敏感信息，**禁止提交到 Git**）
在 `settings.toml` 同级目录创建 `.secrets.toml`：
```toml
dynaconf_merge = true
[development]
DATABASE_PASSWORD = "your_mysql_password"
GITLAB_API_TOKEN = "your_gitlab_token"
OSS_ACCESS_KEY_ID = "your_oss_key_id"
OSS_ACCESS_KEY_SECRET = "your_oss_key_secret"
[production]
DATABASE_PASSWORD = "your_mysql_password"
GITLAB_API_TOKEN = "your_gitlab_token"
OSS_ACCESS_KEY_ID = "your_oss_key_id"
OSS_ACCESS_KEY_SECRET = "your_oss_key_secret"
```
> ✅ **务必替换 `your_mysql_password` 为你实际设置的 MySQL 密码！**
> 🔒 **安全提醒**：将 `.secrets.toml` 加入 `.gitignore`！
---
## 🚚 项目流程
---
## ▶️ 启动项目
```bash
ENV=production poetry run python main.py
```
访问 Web 控制台：
```
http://127.0.0.1:8010
```
---
## 📖 使用示例
### 示例一：Flutter 项目
#### 步骤 1：创建项目 + 自定义环境
在项目设置中指定 Flutter 及构建环境（路径需替换为本地实际路径）：
```env
FLUTTER=/Users/yourname/flutter_3.22.0
PUB_CACHE=/Users/yourname/flutter_3.22.0/.pub-cache
PATH=/Users/yourname/flutter_3.22.0/bin:/Users/yourname/Library/Android/sdk/build-tools/35.0.0
JAVA_HOME=/Users/yourname/Library/Java/JavaVirtualMachines/corretto-17.0.7/Contents/Home/
GRADLE_OPTS=-Dorg.gradle.java.home=/Users/yourname/Library/Java/JavaVirtualMachines/corretto-17.0.7/Contents/Home/
```
#### 步骤 2：创建构建任务
- **iOS**：必须启用 **Xcode 自动签名**，确保已登录 Apple 开发者账号
- **Android**：配置 keystore 信息
- **HarmonyOS**：上传证书与 profile 文件，用于签名 `manifest.json5`
#### 步骤 3：执行打包任务
选择构建配置 → 点击“创建任务” → 系统自动拉取代码、构建、签名、上传，并生成安装二维码。
---
### 示例二：纯 Android 项目
#### 环境配置示例：
```env
ANDROID_HOME=/Users/yourname/Library/Android/sdk
ANDROID_SDK_ROOT=/Users/yourname/Library/Android/sdk
PATH=/Users/yourname/Library/Android/sdk/build-tools/35.0.0:$PATH
```
---
### 示例三：纯 iOS 项目
- 必须使用 **Xcode 自动管理签名**
- 打包前请确保项目在 Xcode 中可正常 Archive 且无证书错误
- 平台会复用当前 macOS 登录的 Apple ID 进行签名
---
## 🐞 常见问题
| 问题 | 解决方案 |
|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **MySQL 非 root 用户无法建表** | 授予用户 `CREATE`, `ALTER`, `DROP`, `INDEX` 等 DDL 权限 |
| **`cryptography` 编译失败** | 在 `pyproject.toml` 中显式指定：`cryptography = "^46.0.3"`，然后运行 `poetry install` |
| **iOS 自动签名失败** | 确保 Xcode 已登录 Apple 开发者账号，且 Bundle ID 与 Provisioning Profile 匹配 |
| **HarmonyOS 报错：`No Hmos SDK found`** | 在 `~/.zshrc` 中添加：```bash
export OH_TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=$OH_TOOL_HOME/sdk
export HOS_SDK_HOME="$OH_TOOL_HOME/sdk"
export OHOS_SDK_HOME="$HOS_SDK_HOME"
export PATH=$OH_TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$OH_TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$OH_TOOL_HOME/tools/node/bin:$PATH
```保存后执行 `source ~/.zshrc` |
| **其他构建失败** | 建议先在原生 IDE（Android Studio / Xcode / DevEco Studio）中手动构建成功，再使用平台构建 |
> 💡 提示：所有路径请根据你本地 DevEco Studio 安装位置调整（默认为 `/Applications/DevEco-Studio.app`）。
---
## ✅ 祝您打包顺利！
如有建议或问题，欢迎提交 Issue 或 PR！