feat: MarkBase initial version
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%
This commit is contained in:
Warren
300
docs/gitea_runner_setup.md
Normal file
300
docs/gitea_runner_setup.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user