Apidog Self-hosted Runner 可以理解為一個可託管在獨立伺服器上的自動化程式。它可以執行 Apidog 中的任務，例如排程自動化測試、排程 API 文件匯入，以及返回模擬回應結果。最低要求的 Docker 版本為 20.10.0，建議使用版本 20.10.13。
快速開始#
本節將引導你如何在伺服器上部署 General Runner。1. 部署 General Runner#
前往 Apidog Home 頁面，選擇你想要的團隊，然後點擊右側的 Resources。接著點擊 Deploy General Runner 開始。2. 取得 Runner 部署命令#
點擊 Deploy General Runner 後，從彈出視窗中複製 General Runner 的部署命令。你可以根據需要自訂命令，支援自訂伺服器 OS、公開連接埠、掛載資料目錄等。以下是這些設定的詳細說明：Server OS：指定 Docker 容器的作業系統。這包含 Linux、macOS 和 Windows。選擇正確的作業系統對於確保 Docker 容器正常運作至關重要。
Docker Image：提供三個版本：General、Slim 和 Custom。如果你的「自訂腳本」需要呼叫外部程式，請根據所需環境選擇適合安裝的映像檔：General：包含 Runner 的所有功能，並預先安裝以下語言環境：Node.js 18、Java 21、Python 3 和 PHP 8。
Slim：包含 Runner 的所有功能，但僅預先安裝 Node.js 18。
Custom：包含 Runner 的所有功能，並支援外部程式的自訂語言環境。你可以建立自己的 Dockerfile，依需求新增或移除環境。
Exposed Port：預設情況下，Docker 容器不會將內部連接埠公開供外部存取。使用 -p 參數，你可以將容器內部連接埠對應到主機上的連接埠，允許外部存取容器提供的服務。例如，-p 80:4524 會將容器的內部連接埠 4524 對應到主機的連接埠 80。
Mount Data Directory：-v 參數允許你將主機上的目錄掛載到容器中，讓容器能夠存取並操作主機上的檔案（例如資料庫設定或外部程式）。例如，-v "/opt/runner":/opt/runner 會將主機的 /opt/runner 目錄掛載到容器的 /opt/runner 目錄。
部署命令包含 token 資訊，基於資料安全原因只會顯示一次。每次點擊 Deploy General Runner 都會產生新的命令。請將命令儲存在本機，因為你可以將其用於未來的 Runner 升級。
3. 在伺服器上部署 Runner#
將複製的部署命令貼到伺服器的終端機中，Runner 安裝將自動開始。安裝完成後，終端機會列印相關資訊。如果發生錯誤，你可以根據錯誤詳細資訊進行疑難排解。如果仍無法解決，請聯絡我們並提供回饋。4. 在伺服器上檢視 Runner 狀態#
你可以透過 Docker 用戶端檢視容器的執行狀態。你也可以在終端機中使用 docker ps 命令來檢視容器的執行狀態。5. 在 Apidog 檢視已部署的 General Runner#
確認伺服器上的 Runner 容器已部署並啟用後，返回 Apidog。你可以在 Team Resources → General Runner 中看到 Runner 已部署並連接到 Apidog。如果 General Runner 已成功部署在伺服器上，但未顯示於 Apidog 用戶端中，請點擊「General Runner」右側的重新整理按鈕來重新整理頁面並再次檢查。
| 狀態 | 說明 |
|---|
| 已啟動 | Runner 在伺服器上的容器中正常啟用，與 Apidog 保持通訊，並可處理 Apidog 發出的相關任務。 |
| 已停止 | Runner 在 Apidog 中被手動停止，但仍在伺服器上的容器中正常執行並保持通訊。它不會處理 Apidog 發出的任務，且新任務無法指定已停止的 Runner 來執行。你可以在 Apidog 手動啟用它，將 Runner 恢復為已啟動狀態。 |
| 離線 | Runner 已與 Apidog 中斷連線，無法處理任務。這可能是因為伺服器上的 Runner 容器停止，或伺服器與 Apidog 之間發生通訊問題。若要恢復 Runner，請確保 Runner 容器正在執行，且與 Apidog 的通訊沒有問題，使 Runner 能恢復為已啟動狀態。 |
你可以在一個團隊內部署多個 General Runner。建立需要自託管 Runner 的任務時，團隊成員可以從可用的 Runner 中選擇。在 Runner 中儲存檔案#
使用 Runner 執行端點請求、測試情境和排程任務等任務時，可能需要特定本機檔案來支援任務執行。範例包括：在 Pre/Post Processors 中使用資料庫連線
| 使用內容 | 指定目錄路徑（或檔案名稱） | Docker 命令範例 |
|---|
| 其他程式語言 | /app/external-programs/ | -v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms |
| 資料庫連線設定檔 | /app/database/database-connections.json | -v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json |
| SSL 憑證清單檔 | /app/ssl/ssl-client-cert-list.json | -v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json |
你可以參考此頁面了解如何從 Apidog 用戶端匯出設定檔。 升級與重新部署 Runner#
升級 Runner#
當 Runner 發佈新版本時，桌面 Runner UI 中會出現升級圖示。點擊該圖示以安裝 Apidog 提供的最新版本。點擊 Upgrade 會提示你停止目前正在執行的 Runner 容器。請注意，一旦容器停止，排程任務以及用戶端傳送到此 Runner 的任何任務都將不再執行。確認升級後，Apidog 會自動停止目前的 Runner 容器，並提供部署新版本的命令。依照初始部署步驟重新部署 Runner。部署成功後，你將使用最新版本。注意：用戶端中現有的排程任務不會受到影響，也不需要重新指派。重新部署 Runner#
如果 Runner 遇到問題，而你在 Q&A 區段找不到解決方案，或說明無法提供幫助，請考慮重新部署 Runner。若要執行此操作，請前往特定 Runner 的 More Actions 區段並點擊 Redeploy。重新部署流程與上述升級相同。注意：重新部署也會停止 Runner 容器。Q&A#
使用 docker ps 命令找出有問題的 Runner。
步驟 1：收集資訊以診斷問題：
開啟開發者工具（Alt+7+8），將測試情境傳送到有問題的 Runner，並記錄端點詳細資訊
如果你能識別問題且它不是由 Apidog 錯誤造成，請自行修復
如果你無法找出問題，請聯絡 Apidog 社群以取得進一步協助
步驟 1：確認任務完成：
檢查 Apidog 用戶端中是否有排程任務的測試報告
此錯誤有兩個可能原因：
部署命令已重新產生：如果你產生命令、關閉彈出視窗，然後再次點擊，新的 token 可能會使先前的 token 失效。若要修復此問題：切換到左上角的另一個團隊，然後返回需要部署 Runner 的團隊
重新產生部署命令、複製並執行。請確保在流程完成前不要再次點擊重新產生。
teamId 變數的 ID 資料錯誤：這是一個已在最新版本中修復的已知錯誤。如果問題仍然存在：切換到左上角的另一個團隊，然後返回需要部署 Runner 的團隊
重新產生部署命令、複製並執行。請確保在流程完成前不要再次點擊重新產生。
