安裝與管理 GroundRunners

GroundRunners 可讓連鎖指令與內部系統或無法透過網際網路存取的遠端資料來源互動。GroundRunner 通常由 IT 專業人員或熟悉貴機構網路設定的人員安裝在專用伺服器上，例如承載連接資料來源的伺服器。

在設定 GroundRunner 之前，建議先檢閱Chain Builder 安全架構。

要求

需要相容的作業系統，如果您的 GroundRunner 要存取 Windows 通用命名規則 (UNC) 路徑等共用資源，則也需要具有足夠權限的使用者帳戶。

在初始化安裝 GroundRunner 時，GroundRunner 並未安裝 Java Runtime Environment (JRE)。

設定完成且 GroundRunner 開始執行後，系統會依需要自動下載 JRE，以執行相依於 Java 的命令。不需要安裝或管理員介入，且擷取的 JRE 不會影響主機上已有的 JRE 安裝。

另外，如果您有組織需求，需要使用特定的 JRE，也可將 SHARED_LIBRARY_OVERRIDES 環境變數設定為指向系統安裝。在這種情況下，GroundRunner 將不會自動下載 Workiva 標準 JRE，而會使用所提供者的系統 JRE 安裝。

Workiva 提供的 JRE 採用 GPL v2 授權，並受classpath exception 涵蓋。

附註：若要在 Java 安裝中使用自訂憑證，請參閱使用 GroundRunners 的自訂憑證。

GroundRunner 目前可以在下列作業系統系列上安裝，無需外部檔案庫相依性：

Windows 和 Windows Server
Linux 發行版及其衍生版本：
- RedHat、Fedora、AmazonLinux
- Debian/Ubuntu
macOS（僅供測試使用）

Workiva 致力於支援上述所有作業系統系列的現代版本。但是，我們無法支援任何已被其供應商指定為「生命末期」的作業系統。這些較舊的作業系統可能會帶來潛在安全風險，應盡快更新至最新版本。進一步瞭解我們的生命週期結束政策。

附註：每個作業系統的支援排程由個別供應商設定。例如，Microsoft 對 Windows 7 的支援已於 2020 年 1 月 14 日終止；Workiva 對 Windows 7 的支援也已於同日終止。

硬體需求

雖然 GroundRunner 需要的伺服器資源有限，但建議至少使用：

512 MB 的可用隨機存取記憶體（RAM）
100 GB 可用磁碟空間

注意：為了協助計算所需磁碟空間，含有五個命令的鏈結，每個命令產生 10 MB 的暫時性輸出，需要 50 MB 才能完成。

建議的主機組態包括採用下列項目配置的虛擬主機：

二到四個處理器

附註: 基於 ARM 的處理器與 GroundRunner 不相容。
8 GB 系統記憶體
固態硬碟 (SSD) 儲存裝置

此伺服器必須全天候可供使用，以便與 GroundRunner 進行通訊。

預設情況下，GroundRunners 使用本機管理帳戶，無法存取共用磁碟機等遠端資源。

若要存取共用資源 (如 Windows UNC 路徑)，請使用具有該資源足夠特權的使用者帳戶，啟動 GroundRunner。如果使用預設本機系統管理員以外的使用者帳戶，請授予其管理 GroundRunner 安裝目錄的權限以啟用自動更新。

角色需求

於 Workiva 平台上

於 Workiva 平台上，您需要具備能存取 Chain Builder 設定，並可管理執行器的角色。共有兩種角色：

鏈結擁有者：此為主要必備角色。具備此角色的使用者可存取 Chain Builder 中的「下載」區段，以取得最新的 GroundRunner 安裝檔案，並可管理「執行器」分頁，以啟動或監控該服務。
組織鏈結安全性管理員：此組織層級角色也具備跨多個工作區管理連線及執行器的權限。

於伺服器上

由於「手動更新」需要在安裝 GroundRunner 的實體或虛擬機器上停止服務並替換執行檔，使用者必須具備該主機伺服器的管理員權限。

Windows：您必須具備以系統管理員身分執行命令提示字元的能力，並能存取 Windows 服務管理員（以停止並重新啟動 GroundRunner 服務）。
Linux/macOS：您必須具備 sudo 或 root 權限，才能將檔案移入安裝目錄並重新啟動背景處理程序。

下載 GroundRunner

若要下載 GroundRunner 以安裝或手動更新：

在 Workiva 首頁側邊欄上，點選Chains（自動化工作流程） 。
在 Chains（自動化工作流程）建立器側邊（這是一個新的標籤），點擊 Connections 。

另外，您也可以點選右上方的使用者個人檔案圖示，選取 Chains 管理員，然後選取工作區設定。
按一下上方功能表長條圖中的Downloads 。
尋找適用於您作業系統的 GroundRunner，並點選下載。
一旦成功下載至您的電腦，請從下列設定中選取適當的指示，並依照指示安裝 GroundRunner。

安裝 GroundRunner

Microsoft 安裝程式 (MSI) 需要 .NET 3.5 或更高版本。
若無法符合此要求，則必須改用命令列介面安裝 GroundRunner。

安裝 GroundRunner：

解壓縮GroundRunner.zip 到新的資料夾，並開啟資料夾。
執行 GroundRunner.msi 以開啟 GroundRunner 安裝精靈。
按一下「繼續」(Next)。
查看並接受授權協議中的條款，然後按 [下一步]。
於目的地資料夾欄位，輸入 GroundRunner 的安裝路徑（例如：C:\Program Files\GroundRunner\），然後按一下 下一步。
於平台公司代碼欄位，輸入您的公司代碼。
在 [平台授權主機] 中：
- 若為亞太地區，請輸入 h.apac.wdesk.com/s/chains-reaper。
- 若為加拿大，請輸入 h.ca.wdesk.com/s/chains-reaper。
- 若為歐洲、中東及非洲地區，請輸入 h.eu.wdesk.com/s/chains-reaper。
- 若為美國、中美洲及南美洲地區，請輸入 h.app.wdesk.com/s/chains-reaper。
若使用代理伺服器，請於 代理主機 欄位輸入其 URL 及連接埠。
（例如：http://yourproxy:3000。）
若要略過代理伺服器，請於 無代理主機 欄位輸入以逗號分隔的主機清單。
依序按 [下一步]、[安裝] 及 [完成]。
安裝完成後，於 Windows 服務管理員中以滑鼠右鍵點選 GroundRunner，然後選取啟動。

您的 GroundRunner 現在已經安裝完成，可以進行啟動。

若要以命令列介面安裝，您必須將 GroundRunner 的安裝檔下載至程式檔案中的專屬目錄（例如 c:\Program Files (x86)\wdata）。您可以解壓縮安裝檔案並解壓縮到該目錄的根目錄。

接著即可安裝 GroundRunner：

於 Windows 命令視窗中，輸入
```
c:\Program Files (x86)\wdata\installer.exe install
```
並接受所有預設設定。
- 於初始化系統選取「windows」。
  
  您需要指定 GroundRunner 以 Windows 服務的方式運作，才能支援自動更新。GroundRunner 僅應以服務方式執行，測試用途則不在此限。
- 就路徑而言，在新目錄中建立檔案資料夾
  （例如，C:\Program Files (x86)\Wdata\Files）。
- 對於授權主機名稱 (AUTH_HOST)：
  - 若為亞太地區，請輸入 h.apac.wdesk.com/s/chains-reaper。
  - 若為加拿大，請輸入 h.ca.wdesk.com/s/chains-reaper。
  - 若為歐洲、中東及非洲地區，請輸入 h.eu.wdesk.com/s/chains-reaper。
  - 若為美國、中美洲及南美洲地區，請輸入 h.app.wdesk.com/s/chains-reaper。
- 輸入您的公司代碼。
從目錄中刪除 GroundRunner 可執行檔目錄以外的所有檔案。
選取將 GroundRunner 當成服務或前景流程執行。
- 如果以服務方式執行，請執行下列其中一項：
  - 於命令對話框中，輸入 sc start GroundRunner。
  - 於 Windows 服務管理員中，啟動 GroundRunner 服務。
- 若以前景處理程序方式執行，請於命令對話框中輸入：
```
cd c:\Program Files (x86)\wdata GroundRunner.exe
```

您的 GroundRunner 現已安裝完成，可供啟用。

步驟 1. 安裝 GroundRunner

將 GroundRunner 的安裝檔下載至其專屬目錄，
例如：/home/user_name/wdata/。

注意：「/home/user_name/wdata」僅為範例。請依照貴組織的政策決定服務安裝位置。
於命令對話框中，使用以下指令解壓縮安裝檔：
```
unzip GroundRunner.zip
```
輸入 GroundRunner 的詳細資訊。
1. 輸入 ./installer install
2. 對於授權主機名稱 (AUTH_HOST)：
  - 若為亞太地區，請輸入 h.apac.wdesk.com/s/chains-reaper。
  - 若為加拿大，請輸入 h.ca.wdesk.com/s/chains-reaper。
  - 若為歐洲、中東及非洲地區，請輸入 h.eu.wdesk.com/s/chains-reaper。
  - 若為美國、中美洲及南美洲地區，請輸入 h.app.wdesk.com/s/chains-reaper。
3. 輸入您的公司代碼。
刪除該目錄中除安裝過程建立之資料夾以外的所有檔案。

步驟 2. 將 GroundRunner 設定為 systemd 服務（Linux）

為確保 GroundRunner 的自動更新功能正常運作，且維持良好的維護習慣，GroundRunner 必須安裝為已啟用、可重新啟動的 systemd 服務。請參閱您作業系統的相關文件及貴組織的政策，瞭解如何將 GroundRunner 設定為 systemd 服務。

若為基本設定，自動更新功能要想正常運作，需符合以下 systemd 單元檔案要求：

請確認 ExecStart 執行檔指向 GroundRunnerMonitor 二進位檔，而非
GroundRunner 二進位檔。
設定 Restart=always。
請勿設定 StartLimitBurst 或 StartLimitIntervalSec，因為這些設定可能會導致 GroundRunner 無法在發生暫時性錯誤時重新啟動。若不希望 GroundRunner 進入快速重啟循環，可設定 RestartSec。
輸入 systemctl enable 以啟用 GroundRunner 的 systemd 服務單元，讓 GroundRunner 在重新開機後仍能持續運作。

Workiva 並未正式支援以前景處理程序方式執行 GroundRunner。此方式或許適合用於測試設定，但一旦 GroundRunner 設定完成，就應設定為長期執行的背景處理程序。

於 macOS 上執行 GroundRunner（僅供測試）

Workiva 支援於 macOS 上執行 GroundRunner，但僅限於測試用途。雖然 macOS 版的 GroundRunner 可執行與 Linux 及 Windows 版本相同的命令，但 Workiva 並未正式支援將 launchd 作為有效的服務管理員。這是因為 Apple 已於 2022 年停止支援其 macOS 伺服器軟體。Apple 筆記型電腦及桌上型電腦並不適合用於執行 GroundRunner。

啟動 GroundRunner

安裝 GroundRunner 後，您必須在 Chain Builder 中啟用它。

在 Chains（自動化工作流程）鏈結建立器側欄上，點擊 Connections 。
按一下頂端的Runners ，然後按一下Pending Registration 。
輸入簡短且具描述性的執行器名稱。
例如「<datasource>-GroundRunner」。
若您希望在 GroundRunner 狀態異常時收到通知，請將 此執行器狀態異常時通知我 切換開關設為「開啟」（會變為藍色）。
按一下 [啟動]。

GR 設定檢查清單

您執行的是 GroundRunnerMonitor 執行檔（而非 GroundRunner 執行檔）嗎？
您是否已將 GroundRunnerMonitor 設定為系統層級、可重新啟動的服務？
- 適用於 Linux：Systemd。
- 適用於 Windows：Windows 服務。
您的服務是否會在系統重新啟動時重新啟動？
- 於 Linux 上：systemctl enable。
- 於 Windows 上：啟動類型設為 自動。
您是否於受支援的伺服器作業系統上執行？
您是否已啟用 GroundRunner 通知功能？

手動更新 GroundRunner

雖然很少需要，但您可能需要手動升級 GroundRunner。
請參閱 Workiva 支援頁面中的 GroundRunner 手動更新，以瞭解具體操作說明。

解除安裝 GroundRunner

如果您不再需要 GroundRunner，可以將其解除安裝。

從 Windows 設定，前往Apps & features ，選擇GroundRunner (64 位元) ，然後按一下 Uninstall 。

停止 GroundRunner 服務：
- 若以服務方式執行，請使用 Windows 服務管理員，或於命令視窗中輸入
  sc stop GroundRunner。
- 若以前景處理程序方式執行，請按 Ctrl+C。
於命令對話框中，以管理員身分輸入
installer.exe uninstall。
刪除 GroundRunner 可執行檔目錄。

於命令對話框中，停止 GroundRunner 服務並刪除其執行檔目錄（例如：/home/<username>/wdata/Contents）。

安裝自訂的 JRE

如果需要，您可以安裝自己的 JRE 來支援 GroundRunner。此 JRE 的 Java 版本必須與 Groundrunner 所需的版本相符。除了Oracle Essbase 和Oracle Hyperion Financial Management (HFM) GroundRunners 之外，所有 GroundRunners 使用相同的 JRE 版本。

有關如何安裝自訂 JRE 的資訊，請參閱停用 Workiva 共用程式庫 。

GroundRunner 組態設定與外寄網域

若要能與其資料來源通訊，您可能必須在安裝 GroundRunner 的伺服器上開啟防火牆連接埠。若要變更部分 GroundRunner 的組態設定，您可以在安裝二進位檔案的目錄中編輯 GroundRunner.config 檔案。

組態	設定
連接埠	0 到 65535。 GroundRunner 預設使用連接埠 8821 彼此通訊。但只在不同伺服器上的 GroundRunner 在網路內共用命令輸出時，才需要連接埠。
COMPANY_TOKEN	保留預設，除非為不同租用戶配置 GroundRunner
LOG_LEVEL	info 或 debug
PROTOCOL	保留預設
HTTP_PROXY_URL	如果使用代理伺服器，請輸入其 URL 和連接埠（如有必要）。例如，`http://yourproxy:3000` 注意：GroundRunner 可以使用 Proxy 伺服器，但不能使用透過 New Technology LAN Manager (NTLM) 驗證的伺服器。請輸入伺服器的 IP 位址。
LONG_POLL	如果使用 Proxy 伺服器，請設定為 true，指示執行器使用長輪詢來擷取命令。為了確保效能，請只在 Proxy 伺服器或防火牆不支援 Web 通訊端時，使用長輪詢。
NO_PROXY	若要略過 Proxy 伺服器，請改為提供以逗號分隔的主機清單，直接連線。若要根據通用模式加入多個主機，請使用 * 萬用字元。
GROUNDRUNNER_CERT	使用多個 GroundRunner，並希望將加密的資訊傳送給第二個 GroundRunner 時需要。這必須與PORT 一起使用。啟動執行器時，也必須將 PROTOCOL 欄位指定為 HTTPS。
GROUNDRUNNER_CERT_KEY	使用多個 GroundRunner，並希望接收來自第二個 GroundRunner 的加密資訊時需要。此功能還必須與PORT 一起使用。
DISABLE_WEBSOCKETS	執行轉換需要使用 Websockets。如果停用，任何使用轉換的指令都會完全跳過。

註: 您的自簽憑證必須有一個主題替代名稱 (SAN)。如果沒有，GroundRunner 嘗試下載檔案時，會顯示一則錯誤訊息，指出遺漏 SAN。

如果您的網路必須允許外寄網域，下列網域適用於 GroundRunner：

網域	目的
`h.app.wdesk.com` `h.apac.wdesk.com` `h.ca.wdesk.com` `h.eu.wdesk.com`	常見 Wokiva 服務的主要子網域，包含 Wdata
`*.wdesk.com`	實際執行 Workiva 平台的主要網域
`..wdesk.com`	Workiva 平台中支援組件的子網域

若無法使用萬用字元 (*) 進行允許清單權限設定，請使用您所屬地區的「mothership」網域，以允許下載 GroundRunner 資源，避免日後可能發生的封鎖問題。

網域	目的
`mothership.app.wdesk.com` `mothership.apac.wdesk.com` `mothership.ca.wdesk.com` `mothership.eu.wdesk.com`	用於下載所需鏈結資源的子網域。

安全性

注意：GroundRunner 絕不收集或彙總資料，僅在傳輸過程中保留資料。擴充功能驗證 (EV) 憑證一律透過 DigiCert®，加密和保護 GroundRunner 與其資料來源之間的流量。

注意：要保護內部部署資料的安全，CloudRunners 可以與 GroundRunners 共用輸出，但 GroundRunners 無法與 CloudRunner 共用檔案輸出。

疑難排解 GroundRunner 錯誤

如果在鏈結執行時收到這些錯誤，請檢查命令的 GroundRunner：

提示：為了協助簡化疑難排解，您可以建立鏈結，自動下載 GroundRunner 的記錄檔案至表格中。

錯誤訊息	原因	解決方法
與代理程式通訊失敗，未執行此命令	此命令無法與其 GroundRunner 通訊。如果發生這種情況，GroundRunner 不會啟動，或者 GroundRunner 和鏈結產生器之間網路會中斷。	請確認： GroundRunner 的服務正在運作。 GroundRunner 的伺服器已連接到網路。
無法下載與命令相關聯的資源。如果仍發生錯誤，請聯絡支援人員。	與這些命令鏈相關的運行程序無法相互溝通。當命令使用不同的執行器，而 CloudRunner 嘗試使用來自 GroundRunner 的命令的檔案輸出時，通常會發生這種情況。	連鎖中的所有指令使用相同的執行器。如果鏈中的命令需要多個運行程序，請驗證沒有使用 GroundRunners 的命令將檔案輸出傳給使用 CloudRunner 的命令。
啟動命令時出現錯誤：exec: \"\\[connector].exe\": file does not exist" commandExecutorId=[ID]	惡意軟體或防毒應用程式錯誤辨識連接器，並攔截其與 GroundRunner 的通訊。	從應用程式的掃描中排除 GroundRunner 安裝目錄。
憑證錯誤	使用自我簽署憑證	在許多情況下，使用自我簽署憑證加密 GroundRunner 通訊很方便。如果使用自我簽署憑證，請確保憑證的通用名稱與可存取伺服器的 URL 相符。舉例來說，如果您的 GroundRunner 正在偵聽連接埠 8821，且您可以從網路 localhost 存取伺服器，則憑證的通用名稱會是 localhost。
間歇性鏈結失敗並顯示錯誤：「同儕重設連線」	在相同電腦上安裝多個執行器時，每個執行器都需有不重複的 GUID。如果使用相同 GUID，執行器可能會重複並進入更新循環，導致偶爾鏈結失敗。	建議完全重新安裝 GroundRunner。
在 GroundRunner 上跳過指令，但在 CloudRunner 上成功	執行轉換需要使用 Websockets。停用 websockets 後，任何轉換都會完全跳過。	開啟您的設定檔，並設定 `DISABLE_WEBSOCKETS=false` 。
從套接字讀取錯誤。`重試連線: read tcp<IP>:<Port>-><IP>:<Port>: wsarecv：連線嘗試失敗，原因是連線方在一段時間/週期後沒有正確回應，或建立的連線失敗，原因是連線主機沒有回應。`	內部防火牆或網路問題	請您的內部 IT 或網路團隊審閱記錄／審核組態，以解決錯誤。
讀取<IP>:<Port>-><IP>:<Port>:`wsarecv：現有連線被遠端主機強制關閉`	內部防火牆或網路問題	請您的內部 IT 或網路團隊審閱記錄／審核組態，以解決錯誤。

其他資源

支援

社群

Workiva 支援中心