hi-client/.github/workflows/BUILD_GUIDE.md

# 📖 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 个 APK（2种类型 × 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