e3d6b60825
Phase 1 (Infrastructure): - Docs: README.md, AGENTS.md, CHANGELOG.md - Tests: 26 tests (modes_test, filetree_api_test) - Examples: examples/sample.md, sample.json - CI/CD: .gitea/workflows/test.yml, release.yml - Runner: configuration scripts and guides Phase 2 (Quality): - Code quality: rustfmt/clippy config - Security: environment variables - Test coverage: 62 tests (+36) - Documentation: CONTRIBUTING.md, docs/api.yaml - Showcase: demo_features.md, developer_quickstart.md Test coverage: 75% Test pass rate: 100%
300 lines
4.8 KiB
Markdown
300 lines
4.8 KiB
Markdown
# 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** |