Docker zh TW

Docker

ASF可用於Docker容器中。我們的Docker套件目前可以在ghcr.io及Docker Hub獲得。

特別注意，在Docker容器中執行ASF被視為一種進階設定，對於絕大多數使用者來說是不需要的，且通常與非容器設定相比並無優勢。若您考慮將Docker作為把ASF當作服務執行的一種解決方案，例如使它隨著您的作業系統自動啟動，那麼您應考慮閱讀管理章節，並適當設定systemd服務，這幾乎總比在Docker容器中執行ASF還要更好。

在Docker容器中執行ASF通常會涉及一些新問題及狀況，您必須自行面對並解決這些問題。這就是為什麼我們強烈建議您避免使用Docker，除非您已經具備相關知識，且不需要其他人幫助您了解其內部結構。此外，我們也不會在ASF Wiki詳細說明這些。本章節主要提供了非常複雜設定的有效使用範例，例如關於進階網路的設定，或安全性超過ASF在systemd服務中所附帶的標準沙盒（它已經透過非常先進的安全機制來確保卓越的程序隔離）。對於那些少數人，在這裡我們著重解釋了關於ASF與Docker相容性的概念，僅此而已。若您決定將ASF與Docker一起使用，我們會假定您已擁有足夠的Docker知識。

本標籤始終指向在main分支中ASF所提交的最新組建版本，運作原理與直接從我們的CI管線中抓取最新產生的版本相同。通常您應避免使用此標籤，因為它是以開發為目的，專為開發人員及進階使用者的軟體，含有大量的錯誤。該映像檔會隨著GitHub的main分支每次提交而更新，因此您可以預期它會頻繁更新（且經常損壞）。這是我們用來標示ASF專案的當前狀態，不一定能保證穩定或經過測試，就像在我們的發布週期中所說明的那樣。此標籤不應在任何生產環境中使用。

`released`

與上述標籤非常相似，本標籤始終指向ASF最新發布的版本，包含預覽版本。與main標籤不同，此映像檔會在每次推播新的GitHub標籤時更新。為喜歡冒險、敢於嘗試新事物但又可能考慮相對穩定的進階使用者所準備。若您不想使用latest標籤，我們建議您使用此標籤。實際上，它的運作方式與滾動標籤在拉取時指向最新A.B.C.D版本的方式相同。請注意，使用此標籤與使用我們的預覽版本是相同的。

`latest`

與其他標籤相比，只有本標籤包含了ASF的自動更新功能，且指向ASF最新的穩定版本。此標籤的目的是提供一個預設的合理Docker容器，能執行適用於特定作業系統的ASF組建版本的自動更新。因此，此映像檔不需要經常更新，因為所包含的ASF版本將會在需要時進行自動更新。當然，可以安全關閉UpdatePeriod（設定成0），但在這種情形下，您可能更應使用固定的A.B.C.D版本。同理，您也可以修改預設的UpdateChannel，以改為自動更新released標籤。

由於latest映像檔具有自動更新功能，它具有linux作業系統特定的裸作業系統ASF版本，與所有其他標籤相反，包含含有.NET作業系統執行環境及generic的ASF版本。這是因為較新（更新後）的ASF版本可能會需要比映像檔內建還要新的執行環境，這將需要從頭開始重新組建映像檔，並使使用計畫無效。

`A.B.C.D`

與上述的標籤相比，本標籤是固定的，這代表映像檔一經發布就不再會更新。這個運作方式與我們GitHub發布版本相似，在最初的版本發布後就不會變動，這將保證您的環境穩定。通常，當您想使用特定的ASF版本，且不想使用任何類型的自動更新（例如latest標籤所提供的）時，您就應該使用此標籤。

哪個標籤最適合我？

這取決於您的需求。對於大多數使用者來說，latest標籤應該是最好的，因為它提供了桌面執行ASF時所有的一切，區別只是作為服務執行在特殊的Docker容器中。而那些經常重新建立映像檔，或想要自己完全控制ASF版本的人來說，可能會更喜歡released標籤。若您想要使用某個固定的ASF版本，或在您沒有打算時永遠不會變更版本，A.B.C.D版本可供您使用，作為ASF固定的里程碑，隨時都可以回溯至此。

一般來說我們不建議使用main組建版本，因為這只是用來標示ASF專案當前狀態的。這種狀態無法保證能正常運作，但是如果您對ASF的開發感興趣，非常歡迎您去嘗試。

架構

ASF Docker映像檔目前建立於linux平台上，針對3種架構：x64、arm及arm64。您可以在相容性章節中，有著更深入的了解。

我們的標籤使用多平台清單，這代表安裝在您設備上的Docker會在拉取時自動選擇適合的映像檔。若您需要拉取不符合您當前執行平台的特定映像檔，您可以透過適當的Docker命令--platform來切換，例如docker run。查看關於映像檔清單的Docker文件來深入了解。

使用方法

若需完整資料，請使用Docker官方文件，我們在本指南中只會介紹基礎用法，歡迎您去更深入的挖掘。

你好，ASF！

首先，我們應該驗證Docker是否運作正常，以這來作為我們ASF的「Hello World」：

docker run -it --name asf --pull always --rm justarchi/archisteamfarm

docker run會為您建立一個新的ASF Docker容器，並在前景中執行（-it）。 --pull always確保會最先拉取最新的映像檔，而--rm確保我們的容器在停止之後會被清除，因為我們現在只是測試一切是否運作正常。

若一切運作正常，在拉取所有層並啟動容器後，您應該會注意到ASF已正確啟動，並通知我們目前沒有定義任何Bot，這很好⸺我們驗證了ASF在Docker中運作正常。按CTRL+C以終止ASF程序，同時也使容器終止。

若仔細查看該命令，您會注意到我們沒有宣告任何標籤，而它會自動預設成latest。如果您想要使用與latest不同的標籤，例如released，那麼您應該顯性宣告：

docker run -it --name asf --pull always --rm justarchi/archisteamfarm:released

使用卷

若您在Docker容器中使用ASF，那麼很明顯您需要設定程式自身。您可以透過不同方式做到，但建議是在本機電腦中建立config資料夾，然後在ASF Docker容器中掛載它作為共用卷。

舉例來說，我們假設您的ASF設定資料夾位於/home/archi/ASF/config資料夾中。這個資料夾包含ASF.json核心與我們想要執行的Bot。現在我們只需要將這個資料夾當作共用卷附加至Docker容器中，也就是ASF的設定資料夾（/app/config）。

docker run -it -v /home/archi/ASF/config:/app/config --name asf --pull always justarchi/archisteamfarm

就是這樣，現在您的ASF Docker容器將會以讀寫模式使用您本機電腦的共用資料夾，這是設定ASF的一切。您可以使用相同的方式掛載您想要與ASF共用的其他卷，例如/app/logs或/app/plugins。

當然，這只是達成我們目標的一種特定方式，沒有什麼阻止您使用其他方法，例如建立您自己的Dockerfile將您的設定檔複製至ASF Docker容器中的/app/config資料夾中。本指南只會涵蓋基礎用法。

卷的權限

ASF容器預設是以預設的root使用者初始化，這使容器能夠處理內部權限問題，然後再切換成asf（UID 1000）使用者來處理主程序的剩餘部分。雖然這對絕大多數使用者來說應該能夠接受，但它確實會影響共用卷，因為新建立的檔案擁有者會是asf使用者，如果您想讓其他使用者使用您的共用卷，這可能就不是很理想了。

您有兩種方式更改執行ASF的使用者。我們建議使用第一種，就是使用您想要執行ASF的使用者UID來宣告ASF_USER環境變數。第二種方式則是傳遞由Docker直接支援的--user旗標。

您可以使用例如id -u等的命令來查詢您的uid，然後依上述方式來進行設定。舉例來說，假設您的目標使用者的uid為1001：

docker run -it -e ASF_USER=1001 -v /home/archi/ASF/config:/app/config --name asf --pull always justarchi/archisteamfarm

# 或者，若您了解下列指令的限制
docker run -it -u 1001 -v /home/archi/ASF/config:/app/config --name asf --pull always justarchi/archisteamfarm

ASF_USER及--user旗標間的差異極小，但非常重要。 ASF_USER是由ASF支援的自訂機制，在這個情境中，Docker容器仍以root啟動，然後ASF的啟動腳本會以ASF_USER指定的使用者執行主程式。在使用--user旗標時，您會以指定的使用者啟動整個程序，包含ASF啟動腳本。第一條指令使ASF的啟動腳本能自動為您處理權限及其他您可能會遇見的常見問題，例如它能確保您的/app及/asf資料夾的擁有者是ASF_USER。在第二種情境下，因為我們未以root執行，所以就無法做到上述功能，您必須自行提前處理好所有問題。

若您決定使用--user旗標，您需要將所有ASF檔案的擁有者從預設的asf改成您新增的使用者。您可以使用下列命令變更：

# 只有在您並未使用 ASF_USER 的時候才要執行
docker exec -u root asf chown -hR 1001 /app /asf

在您使用docker run建立容器後，只需執行一次，且只有在您決定透過--user Docker旗標使用自訂使用者時才需執行。也不要忘記將上述命令中的1001引數更改成您實際想要執行ASF的UID。

在 SELinux 使用卷

若您在作業系統上以強制狀態使用SELinux，這是基於例如RHEL發行版的預設設定，那麼您應該在掛載卷時附加:Z選項，才能正確設定SELinux的上下文。

docker run -it -v /home/archi/ASF/config:/app/config:Z --name asf --pull always justarchi/archisteamfarm

這會使ASF能夠在Docker容器中建立以卷為目標的檔案。

多個實例同步

ASF也包含了支援多個實例的同步，正如管理章節所述。當在Docker容器中執行ASF時，若您使用多個容器且希望它們同步，可以手動選擇「加入程序」。

預設情形下，每個在Docker容器執行的ASF都是獨立的，這代表同步不會發生。為了在它們之間啟用同步，您必須將每個ASF容器中的/tmp/ASF路徑以讀寫模式連結至您想要同步的代管Docker的共用路徑上。這與上述連結卷的方式完全相同，只是路徑不同：

mkdir -p /tmp/ASF-g1
docker run -v /tmp/ASF-g1:/tmp/ASF -v /home/archi/ASF/config:/app/config --name asf1 --pull always justarchi/archisteamfarm
docker run -v /tmp/ASF-g1:/tmp/ASF -v /home/john/ASF/config:/app/config --name asf2 --pull always justarchi/archisteamfarm
# 以此類推，所有 ASF 容器現在相互同步

我們建議將ASF的/tmp/ASF資料夾也連結至您設備上的/tmp暫存檔資料夾，當然，您也可以自由選擇連結至需要的其他路徑。每個預期同步的ASF容器都應有與其他容器共用的/tmp/ASF資料夾，會參與同一個同步程序。

可能您已經從上述猜出，您也可以透過連結不同的Docker代管路徑至ASF的/tmp/ASF，來建立兩個或多個「同步群組」。

掛載/tmp/ASF完全屬於選擇性功能，且實際上並不建議使用，除非您明確需要同步兩個或多個ASF容器。我們不建議在使用單個容器時掛載/tmp/ASF，因為如果您只執行單一的ASF容器，這個操作不會有任何正面作用，反而可能會帶來本應能避免的其他問題。

命令列引數

ASF允許您透過環境變數向Docker容器傳遞命令列引數。對於受支援的開關，您應使用特定的環境變數；其餘開關則使用ASF_ARGS。這可以向docker run加入-e開關來達成，例如：

docker run -it -e "ASF_CRYPTKEY=MyPassword" -e "ASF_ARGS=--no-config-migrate" --name asf --pull always justarchi/archisteamfarm

這會正確把您的--cryptkey及其他引數傳遞給Docker容器中執行的ASF程序。當然，若您是進階使用者，您也可以修改ENTRYPOINT或加入CMD來傳遞您的自訂引數。

除非您想要提供自訂加密鍵或其他進階選項，否則通常您不需要任何特殊的環境變數，因為我們的Docker容器已經設定成使用--no-restart --system-required合理的預設選項執行，因此就不需要在ASF_ARGS中指定這些旗標。

IPC

假設您並未修改IPC全域設定屬性的預設值，那麼它已是啟用的。但是，您必須額外做兩件事情，才能使IPC在Docker容器中正常運作。首先，您必須使用IPCPassword，或在自訂的IPC.config中更改預設的KnownNetworks，使您能夠在不使用的情形下連線。除非您真的知道您在做什麼，否則請直接使用IPCPassword。其次，您還需要更改localhost預設的監聽位址，因為Docker無法將外部流量路由至回送介面。 http://*:1242是一個監聽所有介面的設定範例。當然，您也可以使用更加嚴格的連結，例如只使用區域網路LAN或VPN網路，但它必須是可從外部存取的路由⸺而localhost就不是，因為該路由完全在客戶機內部。

為了執行上述操作，您需要使用自訂IPC組態如下列所示：

{
    "Kestrel": {
        "Endpoints": {
            "HTTP": {
                "Url": "http://*:1242"
            }
        }
    }
}

在非回送介面上設定IPC後，我們需要使用-P或-p開關來告訴Docker映射至ASF的1242/tcp連接埠上。

舉例來說，本命令（只）會將ASF IPC介面公開給主機：

docker run -it -p 127.0.0.1:1242:1242 -p [::1]:1242:1242 --name asf --pull always justarchi/archisteamfarm

若您一切都設定正確，上述的docker run命令將會使IPC介面在您的主機運作，標準的localhost:1242路由現在已正確重定向至您的客戶機上。值得注意的是，我們沒有進一步公開此路由，因此只能在Docker主機內完成連線，從而保持了安全。當然，如果您知道您在做什麼，且確保擁有適合的安全措施，您也可以進一步公開此路由。

完整的範例

綜上所述，完整設定的範例如下所示：

docker run -p 127.0.0.1:1242:1242 -p [::1]:1242:1242 -v /home/archi/ASF/config:/app/config -v /home/archi/ASF/plugins:/app/plugins --name asf --pull always justarchi/archisteamfarm

這假定您將使用單一ASF容器，且所有ASF設定檔都位於/home/archi/ASF/config中。您應該將設定的路徑更改成與您設備相符的路徑。您也可以提供ASF自訂外掛程式，將它們放置於/home/archi/ASF/plugins。若您決定將IPC.config包含在您的設定資料夾中，此設定也可以用於IPC，內容如下所示：

{
    "Kestrel": {
        "Endpoints": {
            "HTTP": {
                "Url": "http://*:1242"
            }
        }
    }
}

專業小技巧

當您準備好ASF的Docker容器後，您就不必每次都使用docker run了。您可以透過docker stop asf及docker start asf簡單地停止／啟動ASF Docker容器。請注意，如果您使用的不是latest標籤，那麼使用最新版本的ASF仍然需要您再次執行docker stop、docker rm及docker run。這是因為每次您想要使用包含在映像檔中的ASF版本時，您都必須由新的ASF Docker映像檔重建您的容器。在latest標籤中，ASF已包含自我更新的能力，因此使用最新版本的ASF不需要重建映像檔（但偶爾這樣做仍有好處，可以使用新的.NET相依執行環境及底層作業系統，這可能會在跨越ASF主要大版本時會需要）。

如上所述，latest以外標籤的ASF不會自動更新，這代表您必須負責使用最新的justarchi/archisteamfarm儲存庫。這有很多優點，因為通常應用程式在執行時不應動到自身的程式碼，但我們也理解不必擔心Docker容器內ASF的版本所帶來的便利。若您需要一個良好的實際範例且正確的Docker用法，我們建議使用released標籤，而不是latest。但如果您不介意，只想讓ASF正常運作並自動更新，那麼latest即可。

通常您應該要在具有Headless: true全域設定的Docker容器內執行ASF。這會明確告訴ASF您不會提供缺少的資料，且它也不應詢問這些。當然，對於初次設定，您應該讓這個選項維持在false，這樣您就可以方便設定；但對於長期來說，您通常不會需要連線至ASF控制台，因此這樣告知是合理的。如果需要，使用input指令即可。這樣ASF就不會無限期等待不存在的使用者輸入（不然這樣等待也只是在浪費資源）。這也使ASF能夠在容器內以非互動模式執行，這非常重要，例如在轉送訊號時，可以使ASF在收到docker stop asf請求時正常關閉。