檢視原始碼 mix release (Mix v1.16.2)

組建當前專案的獨立版本

$ MIX_ENV=prod mix release
$ MIX_ENV=prod mix release NAME

組建版本後，可以將其打包並部署到目標，只要目標執行與執行 mix release 指令的機器相同的作業系統 (OS) 發行版和版本即可。

可以在 mix.exs 檔案中，於 def project 內的 :releases 鍵下，設定版本

def project do
  [
    releases: [
      demo: [
        include_executables_for: [:unix],
        applications: [runtime_tools: :permanent]
      ],

      ...
    ]
  ]
end

可以指定多個版本，其中鍵為版本名稱，值為包含版本設定的關鍵字清單。透過以下方式發布特定名稱：

$ MIX_ENV=prod mix release demo

如果給定的名稱不存在，會引發錯誤。

如果呼叫 mix release，而未指定版本名稱，且已設定多個版本，除非在專案設定的根目錄設定 default_release: NAME，否則會引發錯誤。

如果呼叫 mix release，且未設定任何版本，會使用應用程式名稱和預設值組建版本。

為何需要版本？

版本允許開發人員預先編譯並將所有程式碼和執行時間打包成單一單元。版本的優點包括

• 程式碼預載。VM 有兩種載入程式碼的機制：互動式和嵌入式。預設情況下，它會以互動模式執行，在首次使用模組時動態載入模組。當應用程式首次呼叫 Enum.map/2 時，VM 會找到 Enum 模組並載入它。有一個缺點：在生產環境中啟動新的伺服器時，可能需要載入許多其他模組，導致第一批要求的回應時間異常激增。透過版本，系統會預先載入所有模組，並保證系統在開機後就能處理要求。

• 設定和自訂。版本讓開發人員能精細控制系統設定和用於啟動系統的 VM 旗標。

• 獨立。版本不需要在生產成品中包含原始碼。所有程式碼都已預先編譯並打包。版本甚至不需要伺服器中的 Erlang 或 Elixir，因為它預設包含 Erlang VM 及其執行時間。此外，Erlang 和 Elixir 標準函式庫都會被精簡，只保留實際使用的部分。

• 多個版本。可以為每個應用程式組建不同的版本，並採用不同的設定，甚至可以完全使用不同的應用程式。

• 管理腳本。版本附帶腳本，用於啟動、重新啟動、遠端連線至執行中系統、執行 RPC 呼叫、作為守護程式執行、作為 Windows 服務執行等。

執行版本

組建版本後，您可以在版本內呼叫 bin/RELEASE_NAME start 來啟動它。在生產環境中，您會執行

$ MIX_ENV=prod mix release
$ _build/prod/rel/my_app/bin/my_app start

bin/my_app start 將啟動連線至目前標準輸入/輸出的系統，記錄預設也會寫入其中。這是執行系統的首選方式。許多工具（例如 systemd）、平台即服務（例如 Heroku）和許多容器平台（例如 Docker）都能處理標準輸入/輸出，並將記錄內容重新導向其他地方。這些工具和平台也會在系統崩潰時負責重新啟動系統。

您也可以執行一次性命令，在類 Unix 系統上將版本作為守護程式執行，或將其安裝為 Windows 服務。我們將在接下來探討這些內容。您也可以透過呼叫 bin/RELEASE_NAME 來列出所有可用的命令。

一次性命令 (eval 和 rpc)

如果您想在版本中呼叫特定模組和函式，您可以透過兩種方式執行：使用 eval 或 rpc。

$ bin/RELEASE_NAME eval "IO.puts(:hello)"
$ bin/RELEASE_NAME rpc "IO.puts(:hello)"

eval 命令會啟動 VM 的自己的執行個體，但不會啟動版本中的任何應用程式，也不會啟動發行。例如，如果您需要在執行實際系統之前進行一些準備工作，例如遷移資料庫，eval 會是很好的選擇。只要記住，您在 eval 期間使用的任何應用程式都必須明確啟動。

您可以透過呼叫 Application.ensure_all_started/1 來啟動應用程式。從 Elixir v1.16 開始，保證已至少載入應用程式。在較早的版本中，如果您需要載入應用程式但不要啟動它們，您也需要呼叫 Application.load/1。

執行命令的另一種方式是使用 rpc，它會連線至目前執行的系統，並指示它執行給定的表達式。這表示您需要保證系統已啟動，並小心您執行的指令。您也可以使用 remote 將遠端 IEx 會話連線至系統。

輔助模組

在操作系統時，您可能會發現自己經常將某段程式碼當作一次性指令執行。您可以考慮建立一個模組來將這些任務分組

# lib/my_app/release_tasks.ex
defmodule MyApp.ReleaseTasks do
  def eval_purge_stale_data() do
    # Eval commands needs to start the app before
    # Or Application.load(:my_app) if you can't start it
    Application.ensure_all_started(:my_app)

    # Code that purges stale data
    ...
  end

  def rpc_print_connected_users() do
    # Code that print users connected to the current running system
    ...
  end
end

在上面的範例中，我們使用執行函式的指令名稱作為函式名稱的前綴，但這完全是可選的。

並執行它們

$ bin/RELEASE_NAME eval "MyApp.ReleaseTasks.eval_purge_stale_data()"
$ bin/RELEASE_NAME rpc "MyApp.ReleaseTasks.rpc_print_connected_users()"

守護程式模式 (類 Unix)

您可以使用指令以守護程式模式執行發佈版本

$ bin/RELEASE_NAME daemon

在守護程式模式中，系統會透過 run_erl 在背景中啟動。您可能還想在守護程式模式中啟用 heart，以便在系統發生故障時自動重新啟動系統。請參閱產生的 releases/RELEASE_VSN/env.sh 檔案。

守護程式會將其所有標準輸出寫入發佈版本根目錄中的「tmp/log/」目錄。您可以透過執行 tail -f tmp/log/erlang.log.1 或類似的指令來查看日誌檔。一旦檔案過大，索引字尾會遞增。開發人員也可以從發佈版本根目錄呼叫「to_erl tmp/pipe/」來附加到守護程式的標準輸入。但是，請注意，附加到系統時應極為小心，因為用於退出 Elixir 系統的常用指令，例如按兩次 Ctrl+C 或 Ctrl+\，實際上會關閉守護程式。因此，即使在守護程式模式中，也應優先使用 bin/RELEASE_NAME remote。

您可以透過設定 RELEASE_TMP 環境變數來自訂用於記錄和在守護程式模式中進行管道傳輸的 tmp 目錄。請參閱「自訂」區段。

服務模式 (Windows)

雖然 Windows 上沒有守護程式，但可以在 erlsrv 的協助下將發佈的系統安裝為 Windows 上的服務。這可以透過執行以下指令來完成

$ bin/RELEASE_NAME install

安裝後，必須透過 erlsrv 可執行檔明確管理服務，該可執行檔包含在 erts-VSN/bin 目錄中。服務不會在安裝後自動啟動。

例如，如果您有一個名為 demo 的版本，您可以安裝服務，然後從版本根目錄啟動服務，如下所示

$ bin/demo install
$ erts-VSN/bin/erlsrv.exe start demo_demo

服務名稱為 demo_demo，因為該名稱是通過將節點名稱與版本名稱連接起來構建的。由於 Elixir 自動對兩者使用相同的名稱，因此服務將被引用為 demo_demo。

install 命令必須以管理員身份執行。

bin/RELEASE_NAME 命令

bin/RELEASE_NAME 支援以下命令

start        Starts the system
start_iex    Starts the system with IEx attached
daemon       Starts the system as a daemon (Unix-like only)
daemon_iex   Starts the system as a daemon with IEx attached (Unix-like only)
install      Installs this system as a Windows service (Windows only)
eval "EXPR"  Executes the given expression on a new, non-booted system
rpc "EXPR"   Executes the given expression remotely on the running system
remote       Connects to the running system via a remote shell
restart      Restarts the running system via a remote command
stop         Stops the running system via a remote command
pid          Prints the operating system PID of the running system via a remote command
version      Prints the release name and version to be booted

部署

需求

版本建立在主機上，這是一部包含 Erlang、Elixir 以及編譯應用程式所需的任何其他相依項目的機器。然後將版本部署到目標，目標可能是與主機相同的機器，但通常是分開的，而且通常有很多目標（多個執行個體，或將版本部署到異質環境）。

要在不進行交叉編譯的情況下從主機直接部署到單獨的目標，主機和目標之間必須相同

• 目標架構（例如，x86_64 或 ARM）
• 目標供應商 + 作業系統（例如，Windows、Linux 或 Darwin/macOS）
• 目標 ABI（例如，musl 或 gnu）

這通常以目標三元組的形式表示，例如，x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、x86_64-apple-darwin。

因此，更精確地說，要從主機直接部署到單獨的目標，Erlang 執行時間系統 (ERTS) 和任何原生相依項目 (NIF) 都必須為相同的目標三元組編譯。如果您在 MacBook (x86_64-apple-darwin) 上建置並嘗試部署到典型的 Ubuntu 機器 (x86_64-unknown-linux-gnu)，版本將無法運作。您應該在 x86_64-unknown-linux-gnu 主機上建置版本。正如我們將看到的，這可以用多種方式完成，例如在目標本身上發布，或使用虛擬機器或容器，通常作為發布管線的一部分。

除了匹配目標三元組外，目標還必須具備應用程式在執行時所需的所有系統套件。常見的一種情況是在建置使用 :crypto 或 :ssl 的應用程式時需要 OpenSSL，它動態連結到 ERTS。此類原生相依項目的另一個常見來源來自包含 NIF（原生實現函式）的相依項目，這些相依項目可能會動態連結到它們使用的函式庫。

當然，某些作業系統和套件管理員在版本之間可能有所不同，因此如果您的目標是讓主機和目標之間具有完全相容性，最好確保主機和目標上的作業系統和系統套件管理員具有相同的版本。在某些系統中這甚至可能是一個要求，特別是對於嘗試建立完全可重製環境的套件管理員（Nix、Guix）。

類似地，在為 Windows 建立獨立套件和版本時，請注意 Erlang 執行時期系統會依賴某些 Microsoft 函式庫（Visual Studio 2013 的 Visual C++ 可重新散發套件）。這些函式庫會在安裝 Erlang 時安裝（如果之前不存在），但它並非標準 Windows 環境的一部分。在沒有這些函式庫的電腦上部署獨立版本，將會在嘗試執行版本時導致失敗。解決此問題的方法之一是在第一次部署版本時下載並安裝這些 Microsoft 函式庫（Erlang 安裝程式版本 10.6 附帶「Microsoft Visual C++ 2013 可重新散發套件 - 12.0.30501」）。

或者，您也可以將已編譯的物件檔案打包到版本中，只要它們是針對相同的目標編譯的。如果這樣做，您需要使用包含類 Unix 系統上已打包物件的路徑或 Windows 系統上 $PATH 環境變數的 LD_LIBRARY_PATH 環境變數來更新。

目前，由於此過程中涉及的複雜性，沒有官方方法可以將版本從一個目標三元組交叉編譯到另一個目標三元組。

技術

有幾種方法可以保證版本是在與目標具有相同屬性的主機上建置的。一個簡單的選項是擷取原始碼、編譯程式碼並在目標上組裝版本。它會像這樣

$ git clone remote://path/to/my_app.git my_app_source
$ cd my_app_source
$ mix deps.get --only prod
$ MIX_ENV=prod mix release
$ _build/prod/rel/my_app/bin/my_app start

如果您願意，您也可以將版本編譯到一個單獨的目錄，這樣您可以在組裝版本後刪除所有原始碼

$ git clone remote://path/to/my_app.git my_app_source
$ cd my_app_source
$ mix deps.get --only prod
$ MIX_ENV=prod mix release --path ../my_app_release
$ cd ../my_app_release
$ rm -rf ../my_app_source
$ bin/my_app start

但是，如果您有多個生產節點或版本組裝過程很長，這個選項可能會很昂貴，因為每個節點都需要個別組裝版本。

您可以使用幾種不同的方式自動化此過程。一種選擇是將其作為持續整合 (CI) / 持續部署 (CD) 管道的部分。當您有 CI/CD 管道時，您的 CI/CD 管道中的機器通常會在與您的生產伺服器完全相同的目標三元組上執行（如果沒有，則應該如此）。在這種情況下，您可以透過呼叫 MIX_ENV=prod mix release 在 CI/CD 管道的結尾組裝版本，並將成品推送到 S3 或任何其他網路儲存空間。要執行部署，您的生產機器可以從網路儲存空間擷取部署並執行 bin/my_app start。

自動化部署的另一種機制是使用映像，例如 Amazon Machine Images，或容器平台，例如 Docker。例如，您可以使用 Docker 在本地執行一個系統，其目標三重與您的生產伺服器完全相同。在容器內，您可以呼叫 MIX_ENV=prod mix release 並建立一個包含作業系統、所有相依套件以及發行的完整映像和/或容器。

換句話說，只要您記得在相同的目標三重中建置系統，就有多種方法可以部署系統，並且可以自動化發行並將其整合到所有這些方法中。

部署系統後，可以透過將 SIGINT/SIGTERM 傳送到系統來關閉系統，這是大多數容器、平台和工具執行的動作，或透過明確呼叫 bin/RELEASE_NAME stop 來關閉。系統收到關閉要求後，每個應用程式及其各自的監督樹將一個一個地停止，順序與其啟動順序相反。

自訂

開發人員有幾種方法可以在發行中自訂產生的成品。

選項

下列選項可以在每個發行定義的 mix.exs 中設定

• :applications - 一個關鍵字清單，其中應用程式名稱為鍵，其模式為值。預設情況下，:applications 包括目前的應用程式以及目前應用程式所依賴的所有應用程式，遞迴。您可以透過在此處列出新應用程式或變更現有應用程式的模式來包含新應用程式或變更現有應用程式的模式。

  將盡可能保留所提供應用程式的順序，只有 :kernel、:stdlib、:sasl 和 :elixir 會列在指定的應用程式清單之前。支援的值為

  • :permanent (預設) - 應用程式已啟動，如果應用程式終止，節點會關閉，無論原因為何
  • :transient - 應用程式已啟動，如果應用程式異常終止，節點會關閉
  • :temporary - 應用程式已啟動，如果應用程式終止，節點不會關閉
  • :load - 應用程式僅載入
  • :none - 應用程式是發行的一部分，但未載入或啟動

  如果您變更應用程式的模式，該模式將套用至其所有子應用程式。但是，如果應用程式有兩個父應用程式，則優先順序最高的父應用程式的模式會獲勝（根據上述清單，:permanent 優先順序最高）。

• :strip_beams - 控制 BEAM 檔案是否應移除其偵錯資訊、文件區塊和其他非必要元資料。預設為 true。可以設定為 false 以停用移除。也接受 [keep: ["Docs", "Dbgi"]] 以保留通常會移除的特定區塊。您也可以將 :compress 選項設定為 true 以啟用 BEAM 檔案的個別壓縮，儘管通常建議壓縮整個發行。

• :cookie - 代表 Erlang Distribution cookie 的字串。如果未設定此選項，則在組建第一個發行時，會將隨機 cookie 寫入 releases/COOKIE 檔案。在執行階段，我們將首先嘗試從 RELEASE_COOKIE 環境變數中擷取 cookie，然後我們將讀取 releases/COOKIE 檔案。

  如果您手動設定這個選項，我們建議 cookie 選項使用長且隨機產生的字串，例如：Base.url_encode64(:crypto.strong_rand_bytes(40))。我們也建議將 cookie 中的字元限制為 Base.url_encode64/1 回傳的子集。

• :validate_compile_env - 預設情況下，發行版會將所有執行時期設定與在應用程式或其相依項編譯時透過 Application.compile_env/3 函式標記的任何設定進行比對。如果兩者不符，表示您的系統設定錯誤，無法啟動。您可以將此選項設為 false 來停用此檢查。

• :path - 發行版應安裝到的路徑。預設為 "_build/MIX_ENV/rel/RELEASE_NAME"。

• :version - 發行版版本，為字串或 {:from_app, app_name}。預設為目前的應用程式版本。 {:from_app, app_name} 格式可用於輕鬆從其他應用程式參照應用程式版本。這在 umbrella 應用程式中特別有用。

• :quiet - 布林值，控制發行版是否應將步驟寫入標準輸出。預設為 false。

• :include_erts - 布林值、字串或零元匿名函式。如果為布林值，則表示是否應將包含 Erlang VM 的 Erlang 執行時期系統 (ERTS) 包含在發行版中。預設為 true，這也是建議值。如果為字串，則表示現有 ERTS 安裝的路徑。如果為零元匿名函式，則為回傳上述任何一種 (布林值或字串) 的函式。

  您也可以將此選項設為 false，如果您希望使用目標上安裝的 ERTS 版本。不過，請注意，目標上的 ERTS 版本必須與組建發行版時使用的 ERTS 版本完全相同。將其設為 false 也會停用熱程式碼升級。因此，:include_erts 應謹慎設為 false，而且僅在您在執行它的伺服器上組建發行版時才這麼做。

• :include_executables_for - 列出應為哪些作業系統產生可執行檔的原子清單。預設設為 [:unix, :windows]。您可以如下自訂這些設定

  releases: [
    demo: [
      include_executables_for: [:unix] # Or [:windows] or []
    ]
  ]

• :rel_templates_path - 複製到發行版本的範本檔案路徑，例如「vm.args.eex」、「remote.vm.args.eex」、「env.sh.eex」（或「env.bat.eex」）和「overlays」。預設為專案根目錄中的「rel」。

• :overlays - 額外檔案的目錄清單，將原樣複製到發行版本中。預設情況下，:rel_templates_path 中的「overlays」目錄始終包含在此清單中（通常位於「rel/overlays」）。有關更多資訊，請參閱「Overlays」區段。

• :steps - 組裝發行版本時要執行的步驟清單。有關更多資訊，請參閱「步驟」區段。

• :skip_mode_validation_for - 指定要略過「不安全」模式的嚴格驗證的應用程式名稱（原子）清單。「不安全」情況是指父應用程式模式為 :permanent，但其依賴的其中一個應用程式設定為 :load。請小心使用此功能，因為模式無效的發行版本可能無法在沒有其他調整的情況下啟動。預設為 []。

請注意，每個發行版本定義都可以指定為匿名函式。如果某些發行版本屬性難以計算，這會很有用

releases: [
  demo: fn ->
    [version: @version <> "+" <> git_ref()]
  end
]

除了上述選項之外，還可以透過調整發行版本步驟或在啟動時執行自訂選項和指令，自訂產生的發行版本。我們將在接下來詳細說明這兩種方法。

Overlays

通常需要在組裝發行版本後將額外檔案複製到發行版本根目錄。這可以透過將這些檔案放置在 rel/overlays 目錄中來輕鬆完成。其中的任何檔案都會原樣複製到發行版本根目錄。例如，如果您放置了「rel/overlays/Dockerfile」檔案，「Dockerfile」將原樣複製到發行版本根目錄。

如果您想要指定額外的 overlay 目錄，可以使用 :overlays 選項來執行此動作。如果您需要動態複製檔案，請參閱「步驟」區段。

步驟

可以在組裝發行版本之前和之後新增一個或多個步驟。這可以使用 :steps 選項來完成

releases: [
  demo: [
    steps: [&set_configs/1, :assemble, &copy_extra_files/1]
  ]
]

:steps 選項必須是清單，且必須始終包含原子 :assemble，它執行大部分的發行組建。您可以在 :assemble 之前和之後傳遞匿名函式，以自訂您的發行組建管道。這些匿名函式將接收 Mix.Release 結構，且必須傳回相同或已更新的 Mix.Release 結構。也可以在 :assemble 之後任何地方傳遞 :tar 步驟，以建置發行的 tarball。如果發行 :path 未設定，tarball 會建立在 _build/MIX_ENV/RELEASE_NAME-RELEASE_VSN.tar.gz 中。否則，會建立在已設定的 :path 中。

請參閱 Mix.Release，以取得結構和可修改欄位的更多文件。請注意，:steps 欄位本身可以修改，且每次呼叫步驟時都會更新。因此，如果您需要在組建發行之前和之後執行命令，您只需要在管道中宣告第一個步驟，然後將最後一個步驟注入發行結構。步驟欄位也可以用於驗證步驟是在組建發行之前還是之後設定的。

vm.args 和 env.sh (env.bat)

case $RELEASE_COMMAND in
  start*|daemon*)
    ELIXIR_ERL_OPTIONS="-kernel inet_dist_listen_min $BEAM_PORT inet_dist_listen_max $BEAM_PORT"
    export ELIXIR_ERL_OPTIONS
    ;;
  *)
    ;;
esac

IF NOT %RELEASE_COMMAND:start=%==%RELEASE_COMMAND% (
  set ELIXIR_ERL_OPTIONS="-kernel inet_dist_listen_min %BEAM_PORT% inet_dist_listen_max %BEAM_PORT%"
)

echo $@

echo %*

import Config
config :my_app, :secret_key, System.fetch_env!("MY_APP_SECRET_KEY")

import Config
config :my_app, :secret_key, System.fetch_env!("MY_APP_SECRET_KEY")

releases: [
  demo: [
    runtime_config_path: ...
  ]
]

bin/
  RELEASE_NAME
erts-ERTS_VSN/
lib/
  APP_NAME-APP_VSN/
    ebin/
    include/
    priv/
releases/
  RELEASE_VSN/
    consolidated/
    elixir
    elixir.bat
    env.bat
    env.sh
    iex
    iex.bat
    remote.vm.args
    runtime.exs
    start.boot
    start.script
    start_clean.boot
    start_clean.script
    sys.config
    vm.args
  COOKIE
  start_erl.data
tmp/

my_app_umbrella/
  apps/
    my_app_core/
    my_app_event_processing/
    my_app_web/

releases: [
  web_and_event_processing: [
    applications: [
      my_app_event_processing: :permanent,
      my_app_web: :permanent
    ]
  ],

  web_only: [
    applications: [my_app_web: :permanent]
  ],

  event_processing_only: [
    applications: [my_app_event_processing: :permanent]
  ]
]

defmodule Counter do
  use GenServer

  def start_link(_) do
    GenServer.start_link(__MODULE__, :ok, name: __MODULE__)
  end

  def bump do
    GenServer.call(__MODULE__, :bump)
  end

  ## Callbacks

  def init(:ok) do
    {:ok, 0}
  end

  def handle_call(:bump, counter) do
    {:reply, :ok, counter + 1}
  end
end

defmodule Counter do
  use GenServer

  def start_link(_) do
    GenServer.start_link(__MODULE__, :ok, name: __MODULE__)
  end

  def bump(by) do
    GenServer.call(__MODULE__, {:bump, by})
  end

  ## Callbacks

  def init(:ok) do
    {:ok, {0, 0}}
  end

  def handle_call({:bump, by}, {counter, max}) do
    {:reply, :ok, {counter + by, max(max, by)}}
  end
end

defmodule Counter do
  use GenServer

  def start_link(_) do
    GenServer.start_link(__MODULE__, :ok, name: __MODULE__)
  end

  def bump(by) do
    GenServer.call(__MODULE__, {:bump, by})
  end

  ## Callbacks

  def init(:ok) do
    {:ok, {0, 0}}
  end

  def handle_call(:bump, {counter, max}) do
    {:reply, :ok, {counter + 1, max(max, 1)}}
  end

  def handle_call({:bump, by}, {counter, max}) do
    {:reply, :ok, {counter + by, max(max, by)}}
  end

  def code_change(_, counter, _) do
    {:ok, {counter, 0}}
  end
end