# Gitea Actions Runner配置指南

##環境資訊

- **Gitea Server**: https://gitea.momentry.ddns.net
- **Gitea版本**: 1.25.3（支援 Actions）
- **Runner位置**:本機Mac
- **目標**:實機測試 macOS音訊功能

---

##配置步驟

### 1. 取得 Runner Token

1.登入 Gitea: https://gitea.momentry.ddns.net
2.進入 **Settings → Actions → Runners**
3.建立新 Runner，複製 Token

**Token格式範例：**
```
A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
```

---

### 2.下載並安裝 Runner

**macOS ARM版本：**

```bash
#下載 act_runner（Gitea官方Runner）
wget https://dl.gitea.com/act_runner/latest/act_runner-darwin-arm64

#設定執行權限
chmod +x act_runner-darwin-arm64

#移動到系統路徑
sudo mv act_runner-darwin-arm64 /usr/local/bin/act_runner

#驗證安裝
act_runner --version
```

---

### 3.註冊 Runner

**連接遠端 Gitea：**

```bash
#註冊 Runner（使用步驟1取得的Token）
act_runner register --instance https://gitea.momentry.ddns.net --token <YOUR_TOKEN>

#交互式配置
#會提示輸入 Runner名稱、標籤等資訊
```

**建議配置：**
- Runner名稱：`macos-runner`
- Labels：`macos-latest`
- Runner group：default

---

### 4.啟動 Runner

**前景執行（測試用）：**

```bash
act_runner daemon
```

**背景服務（macOS launchd）：**

建立服務配置檔案：

```xml
<!-- ~/Library/LaunchAgents/com.gitea.runner.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitea.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/act_runner</string>
        <string>daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/gitea-runner.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/gitea-runner.err</string>
</dict>
</plist>
```

**載入服務：**

```bash
#載入服務
launchctl load ~/Library/LaunchAgents/com.gitea.runner.plist

#驗證服務狀態
launchctl list | grep gitea
```

---

### 5.驗證 Runner狀態

**在 Gitea網頁驗證：**

1.登入 Gitea
2. Settings → Actions → Runners
3.確認 Runner已連接（狀態為 green）

**在本機驗證：**

```bash
#檢查 Runner狀態
act_runner list

#檢查 Runner日誌
tail -f /tmp/gitea-runner.log
```

---

##必要環境配置

### Rust Toolchain

```bash
#確認 Rust環境
rustc --version
cargo --version

#若未安裝
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### SwitchAudioSource（音訊測試）

```bash
#安裝
brew install switchaudio-source

#驗證
SwitchAudioSource -a
```

###其他工具

```bash
#確認 clippy
cargo clippy --version

#確認 rustfmt
cargo fmt -- --version
```

---

## Workflow觸發測試

###觸發方式

**Push觸發：**

```bash
git push origin main
```

**PR觸發：**

```bash
git checkout -b feature/test
git push origin feature/test
#在 Gitea建立 Pull Request
```

**查看執行結果：**

1.進入專案頁面
2. Actions →查看workflow執行狀態

---

##常見問題

### Runner無法連接 Gitea

**檢查網路連接：**

```bash
curl -I https://gitea.momentry.ddns.net
```

**確認 Token正確：**

```bash
act_runner list
```

### Workflow執行失敗

**檢查日誌：**

```bash
tail -f /tmp/gitea-runner.log
```

**常見錯誤：**

- Rust未安裝 →安裝 Rust toolchain
- SwitchAudioSource未安裝 → brew install
- clippy警告 →修復代碼

---

## Runner維護

###更新 Runner

```bash
#停止服務
launchctl unload ~/Library/LaunchAgents/com.gitea.runner.plist

#下載新版本
wget https://dl.gitea.com/act_runner/latest/act_runner-darwin-arm64

#重新安裝
chmod +x act_runner-darwin-arm64
sudo mv act_runner-darwin-arm64 /usr/local/bin/act_runner

#重新啟動
launchctl load ~/Library/LaunchAgents/com.gitea.runner.plist
```

###清理緩存

```bash
#清理 cargo緩存
cargo clean

#清理測試暫存檔
rm -f data/users/test_*.sqlite
```

---

##進階配置

###多 Runner支援

若有多台機器，可配置多個 Runner：

```bash
#第二台機器註冊
act_runner register --instance https://gitea.momentry.ddns.net --token <TOKEN2>
```

**使用不同 labels區分：**

- macos-runner-1: `macos-latest`
- macos-runner-2: `macos-14`
- linux-runner: `ubuntu-latest`

---

##安全性考量

### Token管理

- Token應妥善保存，避免暴露
-定期更新 Token
- 使用環境變數配置

###網路安全

- Gitea使用 HTTPS（已配置）
- Runner使用 Token認證
-僅連接信任的 Gitea server

---

##叢考資源

- [Gitea Actions官方文檔](https://docs.gitea.com/usage/actions/overview)
- [act_runner GitHub](https://gitea.com/gitea/act_runner)
- [GitHub Actions兼容性](https://docs.gitea.com/usage/actions/comparison)

---

**最後更新：2026-05-16**