chore: 移除旧的GitHub Actions文档并迁移Windows构建配置到Gitea

refactor: 更新Windows构建工作流配置
This commit is contained in:
shanshanzhong 2025-11-06 18:16:56 -08:00
parent 0e1c043e34
commit 14b95b07b4
8 changed files with 0 additions and 1890 deletions

View File

View File

@ -1,311 +0,0 @@
# 📖 GitHub Actions 构建完全指南
## 🎯 功能概述
本 workflow 支持:
**自动编译 libcore.aar** - sing-box 核心库
**Release 构建** - 默认生成正式版 APK
**可配置 API 域名** - 支持自定义后端域名
**可配置 OSS 地址** - 支持自定义配置文件 CDN
**分架构打包** - 生成 arm64-v8a / armeabi-v7a / x86_64 版本
**自动创建 Release** - 推送标签自动发布
---
## 🚀 使用方法
### 方法一:手动触发(推荐,支持自定义配置)
1. **打开 Actions 页面**
- 进入 GitHub 仓库
- 点击顶部 **Actions** 标签
2. **选择 Workflow**
- 左侧选择 **Build Android APK**
- 右侧点击 **Run workflow** 下拉框
3. **配置参数**
| 参数 | 说明 | 默认值 |
|-----|------|--------|
| **构建类型** | debug 或 release | `release` |
| **API 域名** | 后端 API 服务器域名 | `api.maodag.top` |
| **OSS 地址 1** | 配置文件 CDN 地址(香港) | `https://ppp2.oss-cn-hongkong.aliyuncs.com/bear1.txt` |
| **OSS 地址 2** | 配置文件 CDN 地址(东京) | `https://xgp3.oss-ap-northeast-1.aliyuncs.com/bear1.txt` |
| **OSS 地址 3** | 配置文件 CDN 地址(首尔) | `https://xpp4.oss-ap-northeast-2.aliyuncs.com/bear1.txt` |
| **OSS 地址 4** | 配置文件 CDN 地址(新加坡) | `https://xpp5.oss-ap-southeast-1.aliyuncs.com/bear1.txt` |
4. **开始构建**
- 点击绿色 **Run workflow** 按钮
- 等待约 30 分钟完成
5. **下载 APK**
- 构建完成后,在运行记录页面找到 **Artifacts** 区域
- 下载对应架构的 APK
---
### 方法二:推送代码自动构建(使用默认配置)
```bash
# 提交代码
git add .
git commit -m "feat: 新功能"
# 推送到 main 分支
git push origin main
```
**注意:** 自动触发的构建使用默认配置(`api.maodag.top` 和默认 OSS 地址)
---
### 方法三:创建 Release 版本
```bash
# 1. 打标签(必须以 v 开头)
git tag v1.0.0
# 2. 推送标签
git push origin v1.0.0
# 3. 自动触发构建并创建 Release
# 访问 https://github.com/你的用户名/LighthouseApp/releases 查看
```
---
## 📦 构建产物
### APK 命名规则
```
BearVPN-{架构}-{类型}-{日期}-{提交哈希}.apk
```
**示例:**
```
BearVPN-arm64-v8a-release-20251027-abc1234.apk
BearVPN-armeabi-v7a-release-20251027-abc1234.apk
BearVPN-x86_64-release-20251027-abc1234.apk
```
### 架构说明
| 架构 | 适用设备 | 推荐度 |
|------|---------|-------|
| **arm64-v8a** | 2017年后的现代手机 | ⭐⭐⭐⭐⭐ |
| **armeabi-v7a** | 2012-2017年的老旧手机 | ⭐⭐ |
| **x86_64** | Android 模拟器 | ⭐⭐⭐ |
**大多数用户应下载 `arm64-v8a` 版本**
---
## 🔧 配置示例
### 示例 1修改 API 域名
如果你的后端部署在 `api.example.com`
1. 手动触发 workflow
2. 将 **API 域名** 改为 `api.example.com`
3. OSS 地址保持默认
4. 点击 Run workflow
### 示例 2使用自己的 CDN
如果你有自己的配置文件 CDN
1. 手动触发 workflow
2. API 域名保持默认
3. 修改 **OSS 地址 1-4** 为你的 CDN 地址,例如:
- OSS 地址 1: `https://cdn1.example.com/config.txt`
- OSS 地址 2: `https://cdn2.example.com/config.txt`
- OSS 地址 3: `https://cdn3.example.com/config.txt`
- OSS 地址 4: `https://cdn4.example.com/config.txt`
4. 点击 Run workflow
### 示例 3完全自定义配置
```yaml
构建类型: release
API 域名: api.mycompany.com
OSS 地址 1: https://config.mycdn.com/v1/nodes.txt
OSS 地址 2: https://backup1.mycdn.com/v1/nodes.txt
OSS 地址 3: https://backup2.mycdn.com/v1/nodes.txt
OSS 地址 4: https://backup3.mycdn.com/v1/nodes.txt
```
---
## ⏱️ 构建时间
| 阶段 | 时间 |
|-----|------|
| 编译 libcore.aar | 10-15 分钟 |
| 编译 Flutter APK | 15-20 分钟 |
| **总计** | **约 30 分钟** |
---
## 🔍 查看构建日志
1. 打开 Actions 页面
2. 点击对应的运行记录
3. 点击具体的 job如 "编译 Android APK"
4. 展开步骤查看详细日志
**关键步骤:**
- `⚙️ 配置 API 域名和 OSS 地址` - 查看配置是否正确替换
- `🔨 构建 APK` - 查看编译过程
- `📦 重命名 APK 文件` - 查看生成的文件名和 MD5
---
## 🐛 常见问题
### Q1: 如何验证配置是否生效?
**A:** 查看 `⚙️ 配置 API 域名和 OSS 地址` 步骤的日志:
```
🔧 配置构建参数:
API 域名: api.example.com
OSS 地址 1: https://cdn1.example.com/config.txt
...
✅ 配置替换完成
📄 查看修改后的配置:
static List<String> kr_baseDomains = ["api.example.com","api.example.com"];
static String kr_currentDomain = "api.example.com";
```
如果看到你设置的域名,说明配置成功。
---
### Q2: Release 构建和 Debug 构建有什么区别?
| 特性 | Debug | Release |
|-----|-------|---------|
| **文件大小** | 较大 | 较小(优化后) |
| **性能** | 较慢 | 快 |
| **调试信息** | 包含 | 移除 |
| **代码混淆** | 无 | 有 |
| **适用场景** | 开发测试 | 正式发布 |
**推荐:** 生产环境使用 **release** 构建
---
### Q3: 如何使用环境变量配置(不想每次手动输入)?
在仓库 **Settings → Secrets and variables → Actions → Variables** 添加:
| 变量名 | 值 |
|-------|---|
| `DEFAULT_API_DOMAIN` | `api.example.com` |
| `DEFAULT_OSS_URL_1` | `https://cdn1.example.com/config.txt` |
| `DEFAULT_OSS_URL_2` | `https://cdn2.example.com/config.txt` |
| `DEFAULT_OSS_URL_3` | `https://cdn3.example.com/config.txt` |
| `DEFAULT_OSS_URL_4` | `https://cdn4.example.com/config.txt` |
然后修改 workflow 文件,将默认值改为:
```yaml
default: ${{ vars.DEFAULT_API_DOMAIN || 'api.maodag.top' }}
```
---
### Q4: 构建失败 - "libcore.aar not found"
**原因:** libcore 编译失败
**解决:**
1. 检查 `build-libcore` job 的日志
2. 确认 Go 环境和 gomobile 安装成功
3. 确认 libcore 子模块已正确初始化
---
### Q5: 如何配置签名Release 构建必需)?
详见主文档 `.github/workflows/README.md` 的签名配置章节。
---
## 💡 高级技巧
### 技巧 1同时构建多个版本
修改 `build-apk` job
```yaml
strategy:
matrix:
build_type: [debug, release]
api_domain: ['api.maodag.top', 'api.example.com']
```
这样会生成 4 个 APK2种类型 × 2个域名
---
### 技巧 2添加构建完成通知
在 workflow 最后添加:
```yaml
- name: 📢 发送 Telegram 通知
if: success()
run: |
curl -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN }}/sendMessage" \
-d chat_id=${{ secrets.TELEGRAM_CHAT_ID }} \
-d text="✅ BearVPN 构建成功!下载: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
```
需要先配置 `TELEGRAM_BOT_TOKEN``TELEGRAM_CHAT_ID` Secrets。
---
### 技巧 3缓存加速构建
workflow 已配置 Go 和 Flutter 缓存,首次构建约 30 分钟,后续构建可缩短至 15-20 分钟。
---
## 📊 构建状态徽章
在 README.md 中添加:
```markdown
![Build Status](https://github.com/你的用户名/LighthouseApp/actions/workflows/build-android-apk.yml/badge.svg)
```
效果:![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
---
## 🔗 相关文件
- **主 Workflow:** `.github/workflows/build-android-apk.yml`
- **配置文件:** `lib/app/common/app_config.dart`
- **libcore 源码:** `libcore/` 子模块
---
## 📞 需要帮助?
- 查看 [GitHub Actions 文档](https://docs.github.com/actions)
- 查看构建日志排查问题
- 提交 Issue 到仓库
---
**生成时间:** 2025-10-27
**作者:** Claude Code
**版本:** 1.0.0

View File

@ -1,366 +0,0 @@
# 🎯 如何在 GitHub 上构建你的应用
## 📋 前提条件
✅ 已将配置推送到 GitHub
✅ 有 GitHub 账号访问权限
---
## 🚀 方法一:手动触发构建(推荐新手)
### 步骤 1: 访问 GitHub Actions 页面
1. 打开浏览器,访问你的仓库:
```
https://github.com/你的用户名/LighthouseApp
```
2. 点击顶部导航栏的 **Actions** 标签
```
Code Issues Pull requests Actions Projects Wiki Security Insights
↑ 点这里
```
---
### 步骤 2: 选择 Workflow
在左侧栏看到可用的 workflows
```
All workflows
├── Build Android APK ← 仅构建 Android
├── Build Multi-Platform ← 构建所有平台 ⭐推荐
└── Build Clash Core
```
**选择建议:**
- 🟢 **首次测试:** 选择 **Build Android APK**(快速)
- 🔵 **正式发布:** 选择 **Build Multi-Platform**(全平台)
---
### 步骤 3: 运行 Workflow
1. 点击选择的 workflow 名称
2. 右侧出现 **"Run workflow"** 下拉按钮
```
[Run workflow ▼]
```
3. 点击下拉按钮,展开配置面板
---
### 步骤 4: 配置参数
#### 如果选择 "Build Android APK"
```yaml
┌─────────────────────────────────────────┐
│ Run workflow │
├─────────────────────────────────────────┤
│ Use workflow from │
│ Branch: main [▼] │
│ │
│ 构建类型 │
│ ○ debug │
│ ● release │
│ │
│ API 域名 │
│ [api.maodag.top________________] │
│ │
│ OSS 配置地址 1 │
│ [https://ppp2.oss-cn-hongkong...] │
│ │
│ OSS 配置地址 2 │
│ [https://xgp3.oss-ap-northeast-1...] │
│ │
│ OSS 配置地址 3 │
│ [https://xpp4.oss-ap-northeast-2...] │
│ │
│ OSS 配置地址 4 │
│ [https://xpp5.oss-ap-southeast-1...] │
│ │
│ [Cancel] [Run workflow] │
└─────────────────────────────────────────┘
```
**配置说明:**
- **构建类型:** 选择 `release`(生产环境)
- **API 域名:** 填写你的后端域名(默认 `api.maodag.top`
- **OSS 地址:** 保持默认或填写你的 CDN 地址
#### 如果选择 "Build Multi-Platform"
额外多一个参数:
```yaml
│ 构建平台 │
│ [android,windows,macos,linux______] │
```
**选项:**
- `android` - 仅 Android
- `windows` - 仅 Windows
- `macos` - 仅 macOS
- `linux` - 仅 Linux
- `android,windows` - Android + Windows
- `android,windows,macos,linux` - 全部平台 ⭐
---
### 步骤 5: 开始构建
1. 检查所有参数是否正确
2. 点击绿色的 **"Run workflow"** 按钮
3. 页面刷新,顶部出现黄色进度条:
```
⚠️ Build Android APK #1
Queued - This workflow is in queue waiting to run
```
4. 几秒后变为蓝色(运行中):
```
🔵 Build Android APK #1
In progress - This workflow is currently running
```
---
### 步骤 6: 监控构建进度
1. 点击运行记录(蓝色行)
2. 看到构建阶段:
```
编译 libcore.aar 🔵 Running (15分钟)
编译 Android APK ⏸️ Pending
```
3. 可以展开查看实时日志:
```
▼ 编译 libcore.aar
▼ 📦 编译 libcore.aar
🚀 开始编译 libcore...
[gomobile] installing...
✅ libcore.aar 生成成功
```
4. 等待所有阶段完成(约 30-85 分钟)
---
### 步骤 7: 下载构建产物
构建成功后:
1. 向下滚动到 **Artifacts** 区域
```
📦 Artifacts
Produced during runtime
Name Size Expires
apk-arm64-v8a-release 42.5 MB in 30 days [Download]
apk-armeabi-v7a-release 38.2 MB in 30 days [Download]
apk-x86_64-release 45.1 MB in 30 days [Download]
```
2. 点击 **[Download]** 下载对应文件
3. 下载的是 ZIP 文件,解压后得到 APK
```
apk-arm64-v8a-release.zip
└── BearVPN-android-arm64-v8a-release-20251027-abc1234.apk
```
---
## 🏷️ 方法二:推送标签自动构建
这种方式会自动构建并创建 GitHub Release。
### 步骤 1: 在本地打标签
```bash
cd /Users/mac/Project/Dart/LighthouseApp
# 创建标签(版本号必须以 v 开头)
git tag v1.0.0
# 查看标签
git tag
```
---
### 步骤 2: 推送标签到 GitHub
```bash
git push origin v1.0.0
```
**输出:**
```
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 160 bytes | 160.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0)
To github.com:你的用户名/LighthouseApp.git
* [new tag] v1.0.0 -> v1.0.0
```
---
### 步骤 3: 自动触发构建
1. 推送标签后GitHub 自动检测到标签
2. 触发 **Build Multi-Platform** workflow
3. 使用默认配置构建所有平台
---
### 步骤 4: 查看构建进度
1. 访问 Actions 页面
2. 看到自动创建的构建任务:
```
🔵 Build Multi-Platform
v1.0.0
```
---
### 步骤 5: 下载 Release
构建成功后:
1. 访问 **Releases** 页面:
```
https://github.com/你的用户名/LighthouseApp/releases
```
2. 看到新创建的 Release
```
📦 v1.0.0
Latest Pre-release
🎉 BearVPN 多平台版本发布
Assets (7)
├── BearVPN-android-arm64-v8a-release-*.apk 42.5 MB
├── BearVPN-android-armeabi-v7a-release-*.apk 38.2 MB
├── BearVPN-android-x86_64-release-*.apk 45.1 MB
├── BearVPN-windows-x64-release-*.zip 52.3 MB
├── BearVPN-macos-release-*.zip 48.7 MB
├── BearVPN-linux-x64-release-*.tar.gz 45.9 MB
└── Source code (zip)
```
3. 直接下载需要的文件
---
## ⏱️ 构建时间参考
| Workflow | 平台 | 时间 |
|---------|------|------|
| Build Android APK | Android | 30 分钟 |
| Build Multi-Platform | Android | 35 分钟 |
| Build Multi-Platform | Windows | 30 分钟 |
| Build Multi-Platform | macOS | 35 分钟 |
| Build Multi-Platform | Linux | 30 分钟 |
| Build Multi-Platform | 全部平台 | **60-85 分钟** |
**提示:** 平台是并行构建的,不是累加时间。
---
## 🎯 推荐流程
### 首次测试(验证流程)
```
1. 选择 "Build Android APK"
2. 使用默认配置
3. 运行构建
4. 等待 30 分钟
5. 下载 arm64-v8a APK
6. 安装测试
```
### 正式发布(生产环境)
```
1. 确保代码已测试
2. 本地打标签: git tag v1.0.0
3. 推送标签: git push origin v1.0.0
4. 等待 60-85 分钟
5. 在 Releases 页面下载所有平台
6. 分发给用户
```
---
## 🐛 常见问题
### Q1: 找不到 "Run workflow" 按钮
**原因:** 可能还在查看历史运行记录
**解决:**
1. 点击左侧的 workflow 名称
2. 确保在 workflow 主页面
3. 右侧会出现 "Run workflow" 按钮
---
### Q2: 构建失败
**排查步骤:**
1. 点击失败的运行记录
2. 展开红色的步骤
3. 查看错误日志
4. 常见错误:
- libcore 编译失败 → 检查 Go 环境
- APK 构建失败 → 检查 Flutter 依赖
---
### Q3: Artifacts 下载后是空的
**原因:** 构建可能失败
**解决:**
1. 检查构建日志
2. 确保所有步骤都是绿色 ✅
3. 重新运行构建
---
### Q4: 如何修改 API 域名
**方法 1** 手动触发时修改参数
**方法 2** 修改代码中的默认值
```dart
// lib/app/common/app_config.dart
static String kr_currentDomain = "api.example.com";
```
---
## 📞 需要帮助?
- **查看详细文档:** `.github/workflows/INDEX.md`
- **快速开始:** `.github/workflows/QUICKSTART.md`
- **问题反馈:** GitHub Issues
---
**准备好了吗?立即开始构建!** 🚀

View File

@ -1,318 +0,0 @@
# 📚 GitHub Actions 构建系统总览
## 🎯 快速导航
| 文档 | 用途 | 适合人群 |
|-----|------|---------|
| **[QUICKSTART.md](./QUICKSTART.md)** | 3步快速开始 | 新手 |
| **[README.md](./README.md)** | 基础说明 | 所有人 |
| **[BUILD_GUIDE.md](./BUILD_GUIDE.md)** | Android 详细指南 | Android 开发者 |
| **[MULTIPLATFORM_GUIDE.md](./MULTIPLATFORM_GUIDE.md)** | 多平台构建指南 | 全平台开发者 |
---
## 📋 可用的 Workflows
### 1. `build-android-apk.yml` - Android 专用构建
**功能:**
- ✅ 编译 libcore.aar
- ✅ 构建 Android APK (arm64/armv7/x86_64)
- ✅ 配置 API 域名和 OSS 地址
- ✅ Release 构建
**触发条件:**
- 推送到 main/develop 分支
- 创建 v* 标签
- 手动触发
**文档:** [BUILD_GUIDE.md](./BUILD_GUIDE.md)
---
### 2. `build-multiplatform.yml` - 多平台构建 ⭐推荐
**功能:**
- ✅ Android APK
- ✅ Windows 可执行文件
- ✅ macOS 应用
- ✅ Linux 可执行文件
- ✅ 可选择构建平台
- ✅ 统一配置管理
**触发条件:**
- 推送到 main/develop 分支
- 创建 v* 标签
- 手动触发
**文档:** [MULTIPLATFORM_GUIDE.md](./MULTIPLATFORM_GUIDE.md)
---
### 3. `build-clash-core.yml` - Clash 核心编译
**功能:**
- 编译 Clash Meta 核心
- 支持多架构 (arm64/armv7/x86_64)
**触发条件:**
- core/ 目录变更
- 手动触发
---
## 🚀 使用建议
### 场景 1: 日常开发(仅 Android
**使用:** `build-android-apk.yml`
```bash
# 推送代码自动触发
git push origin main
```
**时间:** 约 30 分钟
**产物:** 3 个 Android APK
---
### 场景 2: 正式发布(所有平台)
**使用:** `build-multiplatform.yml`
```bash
# 1. 打标签
git tag v1.0.0
git push origin v1.0.0
# 2. 自动构建所有平台并创建 Release
```
**时间:** 约 60-85 分钟(并行)
**产物:** Android + Windows + macOS + Linux
---
### 场景 3: 测试特定平台
**使用:** `build-multiplatform.yml` 手动触发
```yaml
构建平台: android,windows # 只构建这两个
```
**时间:** 约 35 分钟
**产物:** 指定平台
---
## 📦 构建产物对比
### Android 专用构建
```
BearVPN-android-arm64-v8a-release-20251027-abc1234.apk
BearVPN-android-armeabi-v7a-release-20251027-abc1234.apk
BearVPN-android-x86_64-release-20251027-abc1234.apk
```
### 多平台构建
```
# Android
BearVPN-android-arm64-v8a-release-20251027-abc1234.apk
BearVPN-android-armeabi-v7a-release-20251027-abc1234.apk
BearVPN-android-x86_64-release-20251027-abc1234.apk
# Windows
BearVPN-windows-x64-release-20251027-abc1234.zip
# macOS
BearVPN-macos-release-20251027-abc1234.zip
# Linux
BearVPN-linux-x64-release-20251027-abc1234.tar.gz
```
---
## ⚙️ 配置参数说明
### 所有 Workflow 通用参数
| 参数 | 默认值 | 说明 |
|-----|-------|------|
| **构建类型** | `release` | debug 或 release |
| **API 域名** | `api.maodag.top` | 后端服务器地址 |
| **OSS 地址 1** | 香港 CDN | 配置文件源 |
| **OSS 地址 2** | 东京 CDN | 备用配置源 |
| **OSS 地址 3** | 首尔 CDN | 备用配置源 |
| **OSS 地址 4** | 新加坡 CDN | 备用配置源 |
### 多平台专用参数
| 参数 | 默认值 | 说明 |
|-----|-------|------|
| **构建平台** | `android,windows,macos,linux` | 选择构建的平台 |
---
## ⏱️ 构建时间对比
| Workflow | 单平台 | 全平台 |
|---------|-------|-------|
| **Android 专用** | 30分钟 | - |
| **多平台** | 30-40分钟 | 60-85分钟 |
---
## 🎯 选择 Workflow 的建议
### 选择 `build-android-apk.yml` 如果:
- ✅ 只需要 Android 版本
- ✅ 快速迭代开发
- ✅ CI/CD 自动触发
### 选择 `build-multiplatform.yml` 如果:
- ✅ 需要桌面版本
- ✅ 正式版本发布
- ✅ 需要灵活选择平台
---
## 🔧 环境配置
### 必需的 Secrets用于 Release 签名)
**Android:**
```
KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD
```
**macOS:**
```
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
```
**Windows:**
```
WINDOWS_CERTIFICATE_BASE64
WINDOWS_CERTIFICATE_PASSWORD
```
**说明:** 如果不配置签名,可以使用 debug 构建。
---
## 📊 构建流程图
### Android 专用
```
Checkout 代码
编译 libcore.aar (15min)
配置 API/OSS
构建 APK (20min)
上传产物
```
### 多平台
```
Checkout 代码
编译 libcore.aar (15min)
├─→ Android (20min) ─┐
├─→ Windows (15min) ─┤
├─→ macOS (20min) ─┼─→ 创建 Release
└─→ Linux (15min) ─┘
```
---
## 🐛 故障排查
### 问题 1: libcore 编译失败
**检查:**
1. Go 环境是否正常
2. gomobile 是否安装
3. 网络连接(下载依赖)
**日志位置:** `build-libcore` job
---
### 问题 2: Android 构建失败
**常见原因:**
- libcore.aar 未生成
- Gradle 依赖问题
- 签名配置错误
**解决:** 查看 `build-android` job 日志
---
### 问题 3: macOS 构建失败
**常见原因:**
- 签名证书未配置
- Xcode 版本不兼容
**解决:**
- 使用 debug 构建
- 或配置签名证书
---
## 💡 高级用法
### 1. 定时构建
添加到 workflow:
```yaml
on:
schedule:
- cron: '0 2 * * *' # 每天UTC 2:00
```
### 2. PR 自动构建
已配置:推送 PR 到 main 分支自动触发
### 3. 构建通知
可集成 Telegram/Slack/钉钉通知
---
## 📞 获取帮助
- **查看文档:** 本目录下的 Markdown 文件
- **查看日志:** GitHub Actions 页面
- **提交问题:** Issues 页面
---
## 🔗 相关链接
- [GitHub Actions 文档](https://docs.github.com/actions)
- [Flutter CI/CD](https://docs.flutter.dev/deployment/cd)
- [sing-box 文档](https://sing-box.sagernet.org/)
---
**版本:** 1.0.0
**更新:** 2025-10-27
**作者:** Claude Code

View File

@ -1,407 +0,0 @@
# 🌐 多平台构建完全指南
## 📋 支持的平台
**Android** - arm64-v8a / armeabi-v7a / x86_64
**Windows** - x64
**macOS** - Universal (Intel + Apple Silicon)
**Linux** - x64
---
## 🚀 快速开始
### 方法 1: 构建所有平台(推荐)
1. 打开 GitHub Actions 页面
2. 选择 **Build Multi-Platform**
3. 点击 **Run workflow**
4. 配置参数:
```yaml
构建类型: release
API 域名: api.maodag.top
OSS 地址 1-4: 使用默认值
构建平台: android,windows,macos,linux # 构建所有平台
```
5. 点击 **Run workflow** 开始
---
### 方法 2: 仅构建指定平台
**场景:** 只需要 Android 和 Windows 版本
```yaml
构建平台: android,windows # 只构建这两个平台
```
**可选值:**
- `android` - 仅 Android
- `windows` - 仅 Windows
- `macos` - 仅 macOS
- `linux` - 仅 Linux
- `android,windows` - Android + Windows
- `android,windows,macos,linux` - 全部平台
---
## ⏱️ 构建时间估算
| 平台 | 时间 | 说明 |
|-----|------|-----|
| **libcore** | 10-15分钟 | Android 依赖 |
| **Android** | 15-20分钟 | 3个架构APK |
| **Windows** | 10-15分钟 | x64可执行文件 |
| **macOS** | 15-20分钟 | Universal应用 |
| **Linux** | 10-15分钟 | x64可执行文件 |
| **总计(全平台)** | **60-85分钟** | 并行构建 |
---
## 📦 构建产物
### Android
```
BearVPN-android-arm64-v8a-release-20251027-abc1234.apk (推荐)
BearVPN-android-armeabi-v7a-release-20251027-abc1234.apk (老设备)
BearVPN-android-x86_64-release-20251027-abc1234.apk (模拟器)
```
**安装:** 直接点击APK安装
---
### Windows
```
BearVPN-windows-x64-release-20251027-abc1234.zip
```
**内容结构:**
```
BearVPN.exe # 主程序
flutter_windows.dll # Flutter运行时
data/ # 资源文件
```
**运行:**
1. 解压 ZIP 文件
2. 双击 `BearVPN.exe` 运行
3. 如提示缺少依赖,安装 [VC++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe)
---
### macOS
```
BearVPN-macos-release-20251027-abc1234.zip
```
**内容:**
```
BearVPN.app # 应用程序包Universal
```
**安装:**
1. 解压 ZIP 文件
2. 将 `BearVPN.app` 拖到 **应用程序** 文件夹
3. 首次运行右键点击 → 打开(绕过 Gatekeeper
**支持架构:**
- Intel (x86_64)
- Apple Silicon (arm64)
---
### Linux
```
BearVPN-linux-x64-release-20251027-abc1234.tar.gz
```
**内容结构:**
```
bearvpn # 可执行文件
lib/ # 共享库
data/ # 资源文件
```
**运行:**
```bash
# 1. 解压
tar -xzf BearVPN-linux-x64-release-*.tar.gz
cd bundle
# 2. 添加执行权限
chmod +x bearvpn
# 3. 运行
./bearvpn
```
**依赖要求:**
- GTK+ 3
- libstdc++12
**安装依赖Ubuntu/Debian**
```bash
sudo apt-get install libgtk-3-0 libstdc++6
```
**安装依赖Fedora/RHEL**
```bash
sudo dnf install gtk3 libstdc++
```
---
## 🔧 配置说明
### 所有平台通用配置
| 参数 | 默认值 | 说明 |
|-----|-------|------|
| **构建类型** | `release` | debug 或 release |
| **API 域名** | `api.maodag.top` | 后端服务器 |
| **OSS 地址 1** | 香港 CDN | 配置文件源 |
| **OSS 地址 2** | 东京 CDN | 备用源 |
| **OSS 地址 3** | 首尔 CDN | 备用源 |
| **OSS 地址 4** | 新加坡 CDN | 备用源 |
| **构建平台** | `android,windows,macos,linux` | 选择平台 |
---
## 📥 下载构建产物
### 从 Actions 页面下载
1. 打开运行记录
2. 滚动到 **Artifacts** 区域
3. 下载对应平台:
- `android-apk` - Android APK (所有架构)
- `windows-x64` - Windows 可执行程序
- `macos-app` - macOS 应用
- `linux-x64` - Linux 可执行程序
### 从 Releases 下载(推送标签时)
1. 访问 Releases 页面
2. 选择版本
3. 在 Assets 中下载对应平台文件
---
## 🎯 使用场景
### 场景 1: 开发测试(仅 Android
```yaml
构建类型: debug
构建平台: android
API 域名: api.test.com
```
**优点:** 快速约20分钟
---
### 场景 2: 正式发布(全平台)
```yaml
构建类型: release
构建平台: android,windows,macos,linux
API 域名: api.maodag.top
```
**优点:** 一次构建,覆盖所有用户
---
### 场景 3: 仅桌面平台
```yaml
构建类型: release
构建平台: windows,macos,linux
```
**用途:** 桌面版更新
---
## 🐛 常见问题
### Q1: Windows 构建失败 - "7z command not found"
**原因:** Windows runner 默认有 7z
**解决:** 检查构建日志,可能是其他错误
---
### Q2: macOS 构建失败 - "Code signing required"
**原因:** Release 构建需要签名
**解决方案:**
**方法 1** 使用 debug 构建(测试用)
**方法 2** 配置签名证书(生产用)
```yaml
# 在 Secrets 中添加
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
MACOS_KEYCHAIN_PASSWORD
PROVISIONING_PROFILE_BASE64
```
---
### Q3: Linux 运行时提示缺少库
**错误:**
```
error while loading shared libraries: libgtk-3.so.0
```
**解决:**
```bash
sudo apt-get update
sudo apt-get install libgtk-3-0
```
---
### Q4: 如何只更新某个平台?
**方法 1** 手动触发指定平台
```yaml
构建平台: android # 只构建 Android
```
**方法 2** 创建平台专用 workflow推荐
---
### Q5: 构建时间太长怎么办?
**优化方案:**
1. **仅构建需要的平台**
```yaml
构建平台: android # 而不是全部
```
2. **使用缓存**(已配置)
- Flutter SDK 缓存
- Gradle 缓存
- Go modules 缓存
3. **分批构建**
- 白天构建 Android/Windows
- 晚上构建 macOS/Linux
---
## 💡 高级用法
### 技巧 1: 矩阵构建多个配置
修改 workflow:
```yaml
strategy:
matrix:
api_domain: ['api.prod.com', 'api.test.com']
platform: ['android', 'windows', 'macos', 'linux']
```
**效果:** 生成 8 个版本2域名 × 4平台
---
### 技巧 2: 定时自动构建
添加到 workflow:
```yaml
on:
schedule:
- cron: '0 2 * * *' # 每天凌晨2点UTC
```
---
### 技巧 3: 构建完成通知
添加 Telegram 通知:
```yaml
- name: 📢 通知
run: |
curl -X POST "https://api.telegram.org/bot${{ secrets.TG_BOT_TOKEN }}/sendMessage" \
-d chat_id=${{ secrets.TG_CHAT_ID }} \
-d text="✅ 多平台构建完成!"
```
---
## 📊 构建并行示意图
```
libcore (15min)
├─→ Android (20min) ─┐
├─→ Windows (15min) ─┤
├─→ macOS (20min) ─┼─→ Release (2min)
└─→ Linux (15min) ─┘
总时间: 约 35-40分钟并行
如果串行: 约 85分钟
```
---
## 🔐 安全建议
### Release 版本签名
**Android:**
```yaml
# Secrets 配置
KEYSTORE_BASE64
KEYSTORE_PASSWORD
KEY_ALIAS
KEY_PASSWORD
```
**macOS:**
```yaml
# Secrets 配置
MACOS_CERTIFICATE_BASE64
MACOS_CERTIFICATE_PASSWORD
```
**Windows:**
```yaml
# Secrets 配置
WINDOWS_CERTIFICATE_BASE64
WINDOWS_CERTIFICATE_PASSWORD
```
---
## 📞 需要帮助?
- 查看 [GitHub Actions 文档](https://docs.github.com/actions)
- 查看 [Flutter 桌面支持](https://docs.flutter.dev/desktop)
- 提交 Issue
---
**版本:** 1.0.0
**更新:** 2025-10-27
**作者:** Claude Code

View File

@ -1,78 +0,0 @@
# 🚀 GitHub Actions 快速开始
## 📋 3 步开始使用
### 步骤 1: 推送配置文件
```bash
cd /Users/mac/Project/Dart/LighthouseApp
git add .github/workflows/
git commit -m "feat: 添加 GitHub Actions 自动构建配置"
git push origin main
```
### 步骤 2: 手动触发构建
1. 打开 GitHub 仓库页面
2. 点击 **Actions** 标签
3. 左侧选择 **Build Android APK**
4. 右侧点击 **Run workflow** 下拉按钮
5. 配置参数(可以使用默认值):
```
构建类型: release
API 域名: api.maodag.top
OSS 地址 1-4: 使用默认值
```
6. 点击绿色 **Run workflow** 按钮
### 步骤 3: 下载 APK
- 等待约 30 分钟
- 在构建记录页面找到 **Artifacts**
- 下载 `apk-arm64-v8a-release`(推荐)
---
## 🎯 自定义配置示例
### 场景 1: 更换 API 域名
```yaml
构建类型: release
API 域名: api.example.com ← 修改这里
OSS 地址: 保持默认
```
### 场景 2: 使用自己的 CDN
```yaml
构建类型: release
API 域名: api.maodag.top
OSS 地址 1: https://your-cdn.com/config1.txt ← 修改这里
OSS 地址 2: https://your-cdn.com/config2.txt ← 修改这里
OSS 地址 3: https://your-cdn.com/config3.txt ← 修改这里
OSS 地址 4: https://your-cdn.com/config4.txt ← 修改这里
```
---
## 📖 详细文档
- **完整指南:** [BUILD_GUIDE.md](./BUILD_GUIDE.md)
- **基础说明:** [README.md](./README.md)
---
## ✅ 核心功能
**Release 构建** - 生产环境优化版本
**可配置域名** - 支持自定义 API 和 CDN
**分架构打包** - arm64/armv7/x86_64
**自动 Release** - 推送标签自动发布
---
**需要帮助?** 查看 [BUILD_GUIDE.md](./BUILD_GUIDE.md)

View File

@ -1,90 +0,0 @@
# GitHub Actions 构建说明
## 📋 工作流概览
### `build-android-apk.yml` - Android APK 自动构建
**触发条件:**
- ✅ 推送到 `main``develop` 分支
- ✅ 打 `v*` 标签时自动创建 Release
- ✅ 手动触发Actions 页面点击 "Run workflow"
**构建产物:**
- `libcore.aar` - sing-box 核心库
- `BearVPN-arm64-v8a-*.apk` - 64位 ARM 版本(推荐)
- `BearVPN-armeabi-v7a-*.apk` - 32位 ARM 版本
- `BearVPN-x86_64-*.apk` - 模拟器版本
---
## 🚀 使用方法
### 方法一:推送代码自动构建
```bash
git add .
git commit -m "feat: 新功能"
git push origin main
```
### 方法二:手动触发
1. 打开仓库 **Actions** 页面
2. 点击 **Build Android APK**
3. 点击 **Run workflow**
### 方法三:创建 Release
```bash
git tag v1.0.0
git push origin v1.0.0
```
---
## 📦 下载构建产物
- **Actions 页面:** 点击运行记录 → Artifacts 区域下载
- **Releases 页面:** 选择版本 → Assets 下载
---
## 🔧 配置 Release 签名(可选)
1. 生成密钥:
```bash
keytool -genkey -v -keystore release.keystore -alias bearvpn -keyalg RSA -keysize 2048 -validity 10000
```
2. 转换为 Base64
```bash
base64 release.keystore > keystore.base64.txt
```
3. 在 GitHub 仓库 **Settings → Secrets** 添加:
- `KEYSTORE_BASE64`
- `KEYSTORE_PASSWORD`
- `KEY_ALIAS`
- `KEY_PASSWORD`
---
## ⏱️ 构建时间
- libcore.aar: 10-15 分钟
- Flutter APK: 15-20 分钟
- **总计: 约 30 分钟**
---
## 🐛 常见问题
**Q: 构建失败 "libcore.aar not found"**
A: 检查 libcore 子模块是否正确初始化
**Q: Release 未创建**
A: 标签必须以 `v` 开头,如 `v1.0.0`
---
生成时间: 2025-10-27

View File

@ -1,320 +0,0 @@
name: Build Windows
on:
push:
branches:
- main
- develop
tags:
- 'v*'
pull_request:
branches:
- main
workflow_dispatch:
inputs:
build_type:
description: '构建类型'
required: true
default: 'release'
type: choice
options:
- debug
- release
api_domain:
description: 'API 域名'
required: true
default: 'api.maodag.top'
type: string
oss_url_1:
description: 'OSS 配置地址 1'
required: true
default: 'https://ppp2.oss-cn-hongkong.aliyuncs.com/bear1.txt'
type: string
oss_url_2:
description: 'OSS 配置地址 2'
required: true
default: 'https://xgp3.oss-ap-northeast-1.aliyuncs.com/bear1.txt'
type: string
oss_url_3:
description: 'OSS 配置地址 3'
required: true
default: 'https://xpp4.oss-ap-northeast-2.aliyuncs.com/bear1.txt'
type: string
oss_url_4:
description: 'OSS 配置地址 4'
required: true
default: 'https://xpp5.oss-ap-southeast-1.aliyuncs.com/bear1.txt'
type: string
encryption_key:
description: '加密密钥'
required: true
default: 'c0qhq99a-nq8h-ropg-wrlc-ezj4dlkxqpzx'
type: string
jobs:
# ==================== 编译 libcore (Windows) ====================
build-libcore-windows:
name: 编译 libcore (Windows)
runs-on: client-server
steps:
- name: 📥 Checkout 代码
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: 🔧 设置 Go 环境
uses: actions/setup-go@v5
with:
go-version: '1.23'
cache: true
cache-dependency-path: libcore/go.sum
- name: 🔧 设置 Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: 🔧 安装 MinGW (交叉编译工具)
run: |
sudo apt-get update
sudo apt-get install -y mingw-w64
- name: 📦 编译 libcore.dll
working-directory: libcore
run: |
echo "🚀 开始编译 Windows libcore..."
make windows-amd64
if [ -f "bin/libcore.dll" ] && [ -f "bin/HiddifyCli.exe" ]; then
echo "✅ Windows libcore 编译成功"
ls -lh bin/libcore.dll bin/HiddifyCli.exe
else
echo "❌ Windows libcore 编译失败"
exit 1
fi
- name: 📤 上传 Windows libcore
uses: actions/upload-artifact@v4
with:
name: libcore-windows
path: |
libcore/bin/libcore.dll
libcore/bin/HiddifyCli.exe
libcore/bin/webui/**
retention-days: 7
# ==================== Windows 构建 ====================
build-windows:
name: 构建 Windows
needs: build-libcore-windows
runs-on: windows-latest
steps:
- name: 📥 Checkout 代码
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: 🔧 设置 Flutter
uses: subosito/flutter-action@v2
with:
flutter-version: '3.24.5'
channel: 'stable'
cache: true
- name: 📥 下载 Windows libcore
uses: actions/download-artifact@v4
with:
name: libcore-windows
path: libcore_windows_temp
- name: 🔧 复制 libcore 文件到正确位置并重命名
run: |
Write-Host "📋 开始复制 libcore 文件..."
# 显示下载的文件结构
Write-Host "🔍 检查下载的文件结构:"
Get-ChildItem -Recurse libcore_windows_temp -ErrorAction SilentlyContinue | Format-Table Name, FullName
# 确保目标目录存在
New-Item -ItemType Directory -Force -Path "libcore\bin" | Out-Null
# 查找 libcore.dll可能在 libcore_windows_temp/bin/ 或 libcore_windows_temp/libcore/bin/
$dllFiles = Get-ChildItem -Path libcore_windows_temp -Recurse -Filter "libcore.dll" -ErrorAction SilentlyContinue
if ($dllFiles) {
$sourceDll = $dllFiles[0].FullName
Write-Host "✅ 找到 libcore.dll: $sourceDll"
Copy-Item $sourceDll "libcore\bin\libcore.dll" -Force
} else {
Write-Host "❌ 未找到 libcore.dll"
Write-Host "当前目录内容:"
Get-ChildItem -Path . -Recurse | Select-Object -First 20 | Format-Table Name, FullName
exit 1
}
# 查找并复制 HiddifyCli.exe重命名为 BearVPNCli.exe
$exeFiles = Get-ChildItem -Path libcore_windows_temp -Recurse -Filter "HiddifyCli.exe" -ErrorAction SilentlyContinue
if ($exeFiles) {
$sourceExe = $exeFiles[0].FullName
Write-Host "✅ 找到 HiddifyCli.exe: $sourceExe"
Write-Host "📝 复制并重命名为 BearVPNCli.exe"
Copy-Item $sourceExe "libcore\bin\BearVPNCli.exe" -Force
Write-Host "✅ 重命名完成HiddifyCli.exe → BearVPNCli.exe"
} else {
Write-Host "⚠️ 未找到 HiddifyCli.exe这不是致命错误"
}
# 复制 webui 目录
$webuiDir = Get-ChildItem -Path libcore_windows_temp -Recurse -Filter "webui" -Directory -ErrorAction SilentlyContinue
if ($webuiDir) {
Write-Host "✅ 找到 webui 目录: $($webuiDir[0].FullName)"
Copy-Item -Path $webuiDir[0].FullName -Destination "libcore\bin\webui" -Recurse -Force
} else {
Write-Host "⚠️ 未找到 webui 目录(这不是致命错误)"
}
Write-Host ""
Write-Host "📄 验证复制后的文件结构:"
if (Test-Path "libcore\bin") {
Get-ChildItem libcore\bin\ -Recurse | Format-Table Name, FullName, Length
} else {
Write-Host "❌ libcore\bin 目录不存在"
}
if (-not (Test-Path "libcore\bin\libcore.dll")) {
Write-Host "❌ libcore.dll 未正确复制到 libcore\bin\"
exit 1
}
Write-Host "✅ libcore 文件复制完成"
shell: pwsh
- name: ⚙️ 配置 API、OSS 和加密密钥
shell: bash
run: |
CONFIG_FILE="lib/app/common/app_config.dart"
API_DOMAIN="${{ inputs.api_domain || 'api.maodag.top' }}"
OSS_URL_1="${{ inputs.oss_url_1 || 'https://ppp2.oss-cn-hongkong.aliyuncs.com/bear1.txt' }}"
OSS_URL_2="${{ inputs.oss_url_2 || 'https://xgp3.oss-ap-northeast-1.aliyuncs.com/bear1.txt' }}"
OSS_URL_3="${{ inputs.oss_url_3 || 'https://xpp4.oss-ap-northeast-2.aliyuncs.com/bear1.txt' }}"
OSS_URL_4="${{ inputs.oss_url_4 || 'https://xpp5.oss-ap-southeast-1.aliyuncs.com/bear1.txt' }}"
ENCRYPTION_KEY="${{ inputs.encryption_key || 'c0qhq99a-nq8h-ropg-wrlc-ezj4dlkxqpzx' }}"
ENCRYPTION_KEY_ESCAPED=$(echo "$ENCRYPTION_KEY" | perl -pe 's/([\[\].*^$()+?{|\\])/\\$1/g')
sed -i "s|api\.maodag\.top|$API_DOMAIN|g" "$CONFIG_FILE"
sed -i "s|https://ppp2\.oss-cn-hongkong\.aliyuncs\.com/bear1\.txt|$OSS_URL_1|g" "$CONFIG_FILE"
sed -i "s|https://xgp3\.oss-ap-northeast-1\.aliyuncs\.com/bear1\.txt|$OSS_URL_2|g" "$CONFIG_FILE"
sed -i "s|https://xpp4\.oss-ap-northeast-2\.aliyuncs\.com/bear1\.txt|$OSS_URL_3|g" "$CONFIG_FILE"
sed -i "s|https://xpp5\.oss-ap-southeast-1\.aliyuncs\.com/bear1\.txt|$OSS_URL_4|g" "$CONFIG_FILE"
sed -i "s|c0qhq99a-nq8h-ropg-wrlc-ezj4dlkxqpzx|$ENCRYPTION_KEY_ESCAPED|g" "$CONFIG_FILE"
- name: 📦 安装 Flutter 依赖
run: |
flutter pub get
- name: 🔧 生成代码文件 (build_runner)
run: |
echo "🔧 开始运行 build_runner..."
flutter pub run build_runner build --delete-conflicting-outputs
echo ""
echo "✅ build_runner 完成,检查生成的文件..."
if (Test-Path "lib\singbox\model\singbox_status.freezed.dart") {
echo "✅ singbox_status.freezed.dart 已生成"
} else {
echo "❌ singbox_status.freezed.dart 未生成"
exit 1
}
if (Test-Path "lib\singbox\service\singbox_service_provider.g.dart") {
echo "✅ singbox_service_provider.g.dart 已生成"
} else {
echo "❌ singbox_service_provider.g.dart 未生成"
exit 1
}
shell: pwsh
- name: 🔧 验证 libcore 文件存在
run: |
Write-Host "📋 验证 libcore 文件是否存在..."
if (Test-Path "libcore\bin\libcore.dll") {
$dllInfo = Get-Item "libcore\bin\libcore.dll"
Write-Host "✅ libcore.dll 存在: $($dllInfo.FullName) - 大小: $($dllInfo.Length) bytes"
} else {
Write-Host "❌ libcore.dll 不存在"
Write-Host "当前 libcore\bin 目录内容:"
if (Test-Path "libcore\bin") {
Get-ChildItem "libcore\bin" | Format-Table Name, FullName, Length
} else {
Write-Host "libcore\bin 目录不存在"
}
exit 1
}
if (Test-Path "libcore\bin\BearVPNCli.exe") {
$exeInfo = Get-Item "libcore\bin\BearVPNCli.exe"
Write-Host "✅ BearVPNCli.exe 存在: $($exeInfo.FullName) - 大小: $($exeInfo.Length) bytes"
} else {
Write-Host "⚠️ BearVPNCli.exe 不存在"
}
shell: pwsh
- name: 🔨 构建 Windows (Release)
run: |
flutter build windows --release
- name: 🔍 验证 Windows 文件结构
run: |
Write-Host "📋 检查 Release 目录文件结构..."
$releaseDir = "build\windows\x64\runner\Release"
if (Test-Path $releaseDir) {
Write-Host "✅ Release 目录存在"
Write-Host ""
Write-Host "📄 文件列表:"
Get-ChildItem $releaseDir | Format-Table Name, Length, LastWriteTime
# 检查关键文件
if (Test-Path "$releaseDir\BearVPN.exe") {
Write-Host "✅ BearVPN.exe 存在"
} else {
Write-Host "❌ BearVPN.exe 不存在"
}
if (Test-Path "$releaseDir\BearVPNCli.exe") {
Write-Host "✅ BearVPNCli.exe 存在"
} else {
Write-Host "⚠️ BearVPNCli.exe 不存在"
}
if (Test-Path "$releaseDir\libcore.dll") {
Write-Host "✅ libcore.dll 存在"
} else {
Write-Host "❌ libcore.dll 不存在"
}
} else {
Write-Host "❌ Release 目录不存在"
}
shell: pwsh
- name: 📦 打包 Windows
shell: bash
run: |
COMMIT_SHA=${GITHUB_SHA::7}
DATE=$(date '+%Y%m%d')
cd build/windows/x64/runner/Release
7z a -tzip "../../../../../BearVPN-windows-x64-release-${DATE}-${COMMIT_SHA}.zip" ./*
- name: 📤 上传 Windows
uses: actions/upload-artifact@v4
with:
name: windows-x64
path: BearVPN-windows-*.zip
retention-days: 30