# GitHub Actions 工作流说明

本项目使用 GitHub Actions 实现自动化的持续集成（CI）和发布（Release）。

## 工作流文件

### 1. `ci.yml` - 持续集成 ✅

**触发条件**：
- 推送到 `main` 或 `master` 分支
- Pull Request

**包含 3 个任务**：

#### 📋 代码质量检查（quality）
- 代码格式检查（`cargo fmt`）
- 静态分析（`cargo clippy`）
- 文档检查（`cargo doc`）
- **运行环境**：Ubuntu 最新版

#### 🧪 测试（test）
- 运行所有单元测试
- Debug 和 Release 模式编译
- **运行环境**：Ubuntu、macOS、Windows（3 个平台）

#### 🔧 编译检查（build-check）
- 快速验证关键平台的可编译性
- **目标平台**：
  - macOS Apple Silicon (ARM64)
  - Linux x86_64

**执行时间**：约 5-8 分钟

---

### 2. `release.yml` - 发布构建 🚀

**触发条件**：
- 推送 tag（如 `v1.0.0`）
- 手动触发（在 GitHub Actions 页面）

**功能**：在 5 个平台上原生编译并创建 Release

#### 支持的平台

| 平台 | Target | 编译工具 | 运行环境 |
|------|--------|---------|---------|
| macOS Intel | x86_64-apple-darwin | cargo | macos-13 |
| macOS ARM64 | aarch64-apple-darwin | cargo | macos-latest |
| Linux x86_64 | x86_64-unknown-linux-gnu | **cargo-zigbuild** | ubuntu-latest |
| Linux ARM64 | aarch64-unknown-linux-gnu | **cargo-zigbuild** | ubuntu-latest |
| Windows x86_64 | x86_64-pc-windows-gnu | cargo | windows-latest |

#### 编译产物

每个平台生成：
- 压缩包（`.tar.gz` 或 `.zip`）
- SHA256 校验和文件（`.sha256`）

**执行时间**：约 15-20 分钟

---

## 使用方法

### 方法 1：创建 Tag 自动发布（推荐）

```bash
# 1. 确保代码已提交
git add .
git commit -m "feat: ready for v1.0.0"
git push

# 2. 创建并推送 tag
git tag v1.0.0
git push origin v1.0.0

# 3. GitHub Actions 自动执行：
#    - 编译所有 5 个平台
#    - 创建 Release
#    - 上传二进制文件和校验和
```

访问 `https://github.com/<用户名>/<仓库名>/releases` 查看发布结果。

### 方法 2：手动触发编译

1. 访问 GitHub 仓库的 Actions 页面
2. 选择 "Build and Release" 工作流
3. 点击 "Run workflow"
4. 选择分支并运行

**注意**：手动触发不会创建 Release，只会编译并上传 Artifacts（保留 7 天）。

---

## 关键优化

### ✨ 使用 cargo-zigbuild

**为什么**：
- ❌ 原方案：使用 `cross` + Docker（慢、重量级）
- ✅ 新方案：使用 `cargo-zigbuild`（快、轻量级）

**优势**：
1. **编译速度更快**：不需要 Docker 容器启动
2. **更可靠**：直接使用 Zig 作为链接器
3. **更好的兼容性**：指定 glibc 2.28（兼容更多 Linux 发行版）
4. **统一工具链**：与本地开发环境一致

### 🚀 其他优化

1. **改进的缓存策略**
   ```yaml
   - uses: Swatinem/rust-cache@v2
     with:
       prefix-key: v1
       shared-key: ${{ matrix.target }}
       cache-on-failure: true
   ```
   - 每个平台独立缓存
   - 失败时也缓存依赖
   - 加快后续构建

2. **生成 SHA256 校验和**
   - 每个发布文件都有对应的 `.sha256` 文件
   - 用户可以验证下载的完整性

3. **更清晰的日志输出**
   - 每个步骤都有明确的中文说明
   - 打包时显示文件列表
   - 便于调试和追踪问题

4. **fail-fast: false**
   - 一个平台失败不影响其他平台
   - 确保尽可能多的平台成功编译

---

## 查看编译产物

### CI 构建
- 访问 Actions 页面
- 查看对应的 workflow run
- 不会上传 artifacts（仅测试编译）

### Release 构建

#### Tag 触发（自动发布）
- 访问 Releases 页面下载
- 包含所有平台的二进制文件
- 包含 SHA256 校验和

#### 手动触发
- 在 workflow run 页面的 Artifacts 部分下载
- 保留 7 天后自动删除

---

## 编译产物命名

### 压缩包
- macOS: `portable-macos-{arch}.tar.gz`
- Linux: `portable-linux-{arch}.tar.gz`
- Windows: `portable-windows-{arch}.zip`

### 校验和
- macOS: `portable-macos-{arch}.tar.gz.sha256`
- Linux: `portable-linux-{arch}.tar.gz.sha256`
- Windows: `portable-windows-{arch}.zip.sha256`

### 验证下载

```bash
# macOS/Linux
sha256sum -c portable-linux-x86_64.tar.gz.sha256

# Windows (PowerShell)
Get-FileHash portable-windows-x86_64.zip -Algorithm SHA256
```

---

## 本地开发 vs GitHub Actions

| 项目 | 本地开发 | GitHub Actions |
|------|----------|----------------|
| **编译工具** | cargo-zigbuild + cargo | cargo-zigbuild + cargo |
| **平台支持** | 5 个平台 | 5 个平台 |
| **编译时间** | ~5 分钟 | ~15-20 分钟 |
| **优势** | 快速迭代测试 | 自动化发布、原生环境 |
| **使用场景** | 开发调试 | 正式发布 |

---

## 常见问题

### 1. CI 失败了怎么办？

**代码格式问题**：
```bash
# 本地修复
cargo fmt --all
git add .
git commit -m "fix: format code"
git push
```

**Clippy 警告**：
```bash
# 本地检查
cargo clippy --all-targets --all-features -- -D warnings

# 修复后重新提交
```

### 2. Release 编译失败？

查看 Actions 页面的详细日志：
1. 点击失败的 workflow run
2. 展开失败的步骤
3. 查看错误信息

常见原因：
- 依赖版本问题
- 编译错误（本地测试通过了吗？）
- 网络问题（GitHub 服务临时故障）

解决方法：
- 修复问题后重新推送 tag：
  ```bash
  git tag -d v1.0.0           # 删除本地 tag
  git push origin :v1.0.0     # 删除远程 tag
  # 修复问题...
  git tag v1.0.0              # 重新创建 tag
  git push origin v1.0.0      # 重新推送
  ```

### 3. 如何测试 Release 流程？

使用手动触发功能：
1. 访问 Actions 页面
2. 选择 "Build and Release"
3. 手动运行
4. 下载 Artifacts 验证

**注意**：手动触发不会创建 Release，只是测试编译流程。

### 4. 为什么 Linux 使用 glibc 2.28？

glibc 2.28 是一个很好的平衡点：
- ✅ 兼容大多数 Linux 发行版（Ubuntu 18.04+, Debian 10+, CentOS 8+）
- ✅ 支持现代特性
- ✅ 广泛部署

如果需要更旧的兼容性，可以修改为 `2.17`（CentOS 7）。

---

## 技术细节

### cargo-zigbuild 配置

```yaml
# Linux x86_64
cargo-zigbuild build --release --bins --target x86_64-unknown-linux-gnu.2.28

# Linux ARM64
cargo-zigbuild build --release --bins --target aarch64-unknown-linux-gnu.2.28
```

**工作原理**：
1. 使用 Zig 作为 C/C++ 链接器
2. 静态链接 musl/glibc
3. 无需安装交叉编译工具链
4. 产物可以在目标系统上直接运行

### 缓存策略

```yaml
prefix-key: v1          # 版本前缀，手动失效缓存时更新
shared-key: ${{ matrix.target }}  # 每个平台独立缓存
cache-on-failure: true  # 失败时也缓存依赖
```

缓存内容：
- `~/.cargo/registry`
- `~/.cargo/git`
- `target/` 目录

---

## 相关资源

- [GitHub Actions 文档](https://docs.github.com/actions)
- [cargo-zigbuild GitHub](https://github.com/rust-cross/cargo-zigbuild)
- [Rust Actions](https://github.com/actions-rs)
- [本地编译指南](../../scripts/BUILD.md)
