自我主機安裝{#self-host-installation}

我們為需要對其基礎設施進行更多控制的組織提供自助託管版本的 Tuist 伺服器。此版本允許您在自己的基礎架構上託管 Tuist，確保資料的安全和隱私。

[!WARNING] License Required

自行託管 Tuist 需要合法有效的付費授權。預置版 Tuist 僅適用於企業計劃的組織。如果您對此版本感興趣，請聯絡 [email protected]。

釋放速度{#release-cadence}

我們會持續釋出 Tuist 的新版本，因為新的可釋出變更會出現在主網站上。我們遵循 semantic versioning 以確保可預期的版本與相容性。

主要元件用來標記 Tuist 伺服器中需要與內部使用者協調的突破性變更。您不應該期望我們會使用它，如果我們需要，請放心，我們會與您合作，使過渡順利。

持續部署{#continuous-deployment}

我們強烈建議您設定持續部署管道，每天自動部署最新版本的 Tuist。這可確保您永遠都能存取最新的功能、改進和安全更新。

以下是一個 GitHub Actions 工作流程範例，每天檢查並部署新版本：

name: Update Tuist Server
on:
  schedule:
    - cron: '0 3 * * *' # Run daily at 3 AM UTC
  workflow_dispatch: # Allow manual runs

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - name: Check and deploy latest version
        run: |
          # Your deployment commands here
          # Example: docker pull ghcr.io/tuist/tuist:latest
          # Deploy to your infrastructure

運行時間要求{#runtime-requirements}

本節概述在您的基礎架構上託管 Tuist 伺服器的需求。

相容性矩陣{#compatibility-matrix}

Tuist 伺服器已通過測試，並與下列最低版本相容：

[!WARNING] Timescaledb Deprecation

TimescaleDB 目前是 Tuist 伺服器所需的 PostgreSQL 延伸，用於時間序列資料儲存和查詢。然而，TimescaleDB 已經廢棄 ，在不久的將來，當我們將所有的時間序列功能遷移到 ClickHouse 時，TimescaleDB 將不再是必要的依賴。目前，請確保您的 PostgreSQL 實例已安裝並啟用 TimescaleDB。

執行 Docker 虛擬化影像{#running-dockervirtualized-images}

我們透過 GitHub 的容器註冊處，將伺服器以 Docker 映像發行。

若要執行它，您的基礎架構必須支援執行 Docker 映像。請注意，大多數基礎結構供應商都支援它，因為它已經成為在生產環境中散佈和執行軟體的標準容器。

Postgres 資料庫{#postgres-database}

除了執行 Docker 映像檔之外，您還需要一個具有 [TimescaleDB 擴充套件] (https://www.timescale.com/) 的 Postgres 資料庫，以儲存關聯性和時間序列資料。大多數基礎結構供應商都提供 Postgres 資料庫（例如 AWS 和 Google Cloud）。

需要 TimescaleDB 擴充套件： Tuist 需要 TimescaleDB 擴充套件，以進行有效率的時間序列資料儲存和查詢。此擴充用於命令事件、分析和其他基於時間的功能。在執行 Tuist 之前，請確保您的 PostgreSQL 實例已安裝並啟用 TimescaleDB。

[!NOTE] Migrations

Docker 映像的入口點會在啟動服務之前自動執行任何待定的模式遷移。如果因缺少 TimescaleDB 擴充套件而導致遷移失敗，您需要先在資料庫中安裝。

ClickHouse 資料庫{#clickhouse-database}

Tuist 使用 ClickHouse 來儲存和查詢大量分析資料。ClickHouse 是所需的 ，用於建立洞察力等功能，並會在我們逐步淘汰 TimescaleDB 時成為主要的時間序列資料庫。您可以選擇自行託管 ClickHouse 或使用其託管服務。

[!NOTE] Migrations

Docker 映像的入口點會在啟動服務之前自動執行任何待定的 ClickHouse 方案遷移。

儲存{#storage}

您還需要一個解決方案來儲存檔案 (例如框架和函式庫的二進檔)。目前我們支援任何符合 S3 標準的儲存空間。

組態{#configuration}

服務的設定是在執行時透過環境變數完成。鑒於這些變數的敏感性，我們建議將它們加密並儲存到安全的密碼管理解決方案中。請放心，Tuist 會小心處理這些變數，確保它們不會顯示在日誌中。

[!NOTE] Launch Checks

必要的變數會在啟動時驗證。如果缺少任何變數，啟動將會失敗，錯誤訊息會詳細說明缺少的變數。

授權配置{#license-configuration}

作為內部使用者，您會收到一個授權金鑰，您需要將此金鑰顯示為環境變數。此金鑰用於驗證授權，並確保服務在合約條款內執行。

• 必須提供TUIST_LICENSE 或TUIST_LICENSE_CERTIFICATE_BASE64 ，但不能同時提供。標準部署使用TUIST_LICENSE 。

[!WARNING] Expiration Date

許可證有到期日。如果許可證在 30 天內到期，用戶在使用與伺服器互動的 Tuist 指令時會收到警告。如果您有興趣更新授權，請聯絡 [email protected]。

基本環境配置{#base-environment-configuration}

資料庫設定{#database-configuration}

下列環境變數用於設定資料庫連線：

驗證環境設定{#authentication-environment-configuration}

我們透過 身分提供者 (IdP)，協助進行驗證。要使用此功能，請確保伺服器的環境中存在所選提供者的所有必要環境變數。遺失變數 將導致 Tuist 繞過該提供者。

GitHub{#github}

我們建議使用 GitHub 應用程式，但您也可以使用 OAuth 應用程式。確保在伺服器環境中包含 GitHub 指定的所有重要環境變數。缺少變量會導致 Tuist 忽略 GitHub 認證。正確設定 GitHub 應用程式：

• 在 GitHub 應用程式的一般設定中：
  • 複製客戶端 ID ，並設定為TUIST_GITHUB_APP_CLIENT_ID
  • 建立並複製新的客戶端秘密 ，並將其設定為TUIST_GITHUB_APP_CLIENT_SECRET
  • 將Callback URL 設定為http://YOUR_APP_URL/users/auth/github/callback 。YOUR_APP_URL 也可以是您伺服器的 IP 位址。
• 需要以下權限：
  • 儲存庫：
    • 拉取請求：讀寫
  • 帳戶：
    • 電子郵件地址：唯讀

在Permissions and events 的Account permissions 部分，將Email addresses 權限設定為唯讀 。

然後，您需要在 Tuist 伺服器執行的環境中公開下列環境變數：

Google{#google}

您可以使用 OAuth 2 設定 Google 認證。為此，您需要建立一個 OAuth 客戶 ID 類型的新憑證。建立憑證時，選擇「Web 應用程式」作為應用程式類型，將其命名為Tuist ，並將重定向 URI 設定為{base_url}/users/auth/google/callback ，其中base_url 是您的託管服務所執行的 URL。建立應用程式後，複製用戶端 ID 和 secret，並分別設定為環境變數GOOGLE_CLIENT_ID 和GOOGLE_CLIENT_SECRET 。

[!NOTE] Consent Screen Scopes

您可能需要建立同意畫面。這樣做時，請務必加入userinfo.email 和openid 範圍，並將應用程式標示為內部應用程式。

Okta{#okta}

您可以透過 OAuth 2.0 通訊協定啟用 Okta 的驗證功能。您必須依照 <LocalizedLink href="/guides/integrations/sso#okta"> 這些指示 </LocalizedLink> 在 Okta 上 建立應用程式。

當您在設定 Okta 應用程式時取得用戶端 id 和 secret 後，您需要設定下列環境變數：

1 需要用您的組織 ID 取代。這通常是 1，但請檢查您的資料庫。

儲存環境配置{#storage-environment-configuration}

Tuist 需要儲存空間來存放透過 API 上傳的作品。必須設定其中一個支援的儲存解決方案 ，才能讓 Tuist 有效運作。

符合 S3 的儲存設備{#s3compliant-storages}

您可以使用任何符合 S3 標準的儲存提供者來儲存工件。驗證和設定與儲存提供者的整合需要下列環境變數：

[!NOTE] Aws Authentication With Web Identity Token From Environment Variables

如果您的儲存設備提供者是 AWS，而您想使用 Web 身份令牌進行驗證，您可以將環境變數TUIST_S3_AUTHENTICATION_METHOD 設定為aws_web_identity_token_from_env_vars ，Tuist 將使用傳統的 AWS 環境變數使用該方法。

Google 雲端儲存{#google-cloud-storage}

對於 Google Cloud Storage，請遵循 these docs 以取得AWS_ACCESS_KEY_ID 和AWS_SECRET_ACCESS_KEY 對。AWS_ENDPOINT 應設為https://storage.googleapis.com 。其他環境變數與任何其他 S3 相容的儲存相同。

電子郵件設定{#email-configuration}

Tuist 需要電子郵件功能來進行使用者驗證和交易通知 (例如密碼重設、帳戶通知)。目前，僅支援 Mailgun 作為電子郵件供應商。

* Email 配置變數只有在您想要傳送電子郵件時才需要。如果沒有設定，會自動跳過電子郵件確認。

[!NOTE] Smtp Support

目前不提供一般 SMTP 支援。如果您的內部部署需要 SMTP 支援，請聯絡 [email protected] 討論您的需求。

[!NOTE] Air-gapped Deployments

對於沒有網際網路存取或電子郵件供應商設定的內部安裝，預設會自動跳過電子郵件確認。使用者註冊後可立即登入。如果您已設定電子郵件，但仍想跳過確認，請設定TUIST_SKIP_EMAIL_CONFIRMATION=true 。若要在設定電子郵件時要求電子郵件確認，請設定TUIST_SKIP_EMAIL_CONFIRMATION=false 。

Git 平台設定{#git-platform-configuration}

Tuist 可以 <LocalizedLink href="/guides/server/authentication"> 整合 Git 平台</LocalizedLink>，提供額外的功能，例如自動在您的 pull request 中發佈註解。

GitHub{#platform-github}

您需要 建立一個 GitHub 應用程式。除非您建立了 OAuth GitHub 應用程式，否則您可以重複使用您建立的那個用於驗證的應用程式。在Permissions and events'Repository permissions 部分，您需要額外設定Pull requests 權限為Read and write 。

在TUIST_GITHUB_APP_CLIENT_ID 和TUIST_GITHUB_APP_CLIENT_SECRET 之上，您需要以下環境變數：

本地測試{#testing-locally}

我們提供全面的 Docker Compose 設定，其中包含所有必要的相依性，以便在部署到您的基礎架構之前，在本機上測試 Tuist 伺服器：

• PostgreSQL 15 搭配 TimescaleDB 2.16 延伸 (已廢棄)
• ClickHouse 25 用於分析
• 用於協調的 ClickHouse Keeper
• 適用於 S3 相容儲存設備的 MinIO
• Redis 用於跨部署的持久性 KV 儲存（可選）
• 用於資料庫管理的 pgweb

[!CAUTION] License Required

執行 Tuist 伺服器，包括本機開發實體，必須依法取得有效的TUIST_LICENSE 環境變數。如果您需要授權，請聯絡 [email protected]。

快速入門：

1. 下載組態檔案：

   bashCopy

   curl -O https://docs.tuist.io/server/self-host/docker-compose.yml
   curl -O https://docs.tuist.io/server/self-host/clickhouse-config.xml
   curl -O https://docs.tuist.io/server/self-host/clickhouse-keeper-config.xml
   curl -O https://docs.tuist.io/server/self-host/.env.example
   

2. 設定環境變數：

   bashCopy

   cp .env.example .env
   # Edit .env and add your TUIST_LICENSE and authentication credentials
   

3. 啟動所有服務：

   bashCopy

   docker compose up -d
   # or with podman:
   podman compose up -d
   

4. 透過 http://localhost:8080 存取伺服器

服務端點：

• Tuist 伺服器: http://localhost:8080
• MinIO 控制台： http://localhost:9003 (憑證：tuist /tuist_dev_password)
• MinIO API: http://localhost:9002
• pgweb (PostgreSQL UI): http://localhost:8081
• Prometheus Metrics: http://localhost:9091/metrics
• ClickHouse HTTP: http://localhost:8124

常用指令：

檢查服務狀態：

docker compose ps
# or: podman compose ps

檢視記錄：

docker compose logs -f tuist

停止服務：

docker compose down

重設一切（刪除所有資料）：

docker compose down -v

設定檔案：

• docker-compose.yml- 完成 Docker Compose 設定
• clickhouse-config.xml- ClickHouse 配置
• Clickhouse-keeper-config.xml- ClickHouse Keeper 設定
• .env.example- 環境變數檔案範例

部署{#deployment}

官方的 Tuist Docker 映像檔位於以下網址：

ghcr.io/tuist/tuist

拉取 Docker 映像{#pulling-the-docker-image}

您可以執行下列指令擷取影像：

docker pull ghcr.io/tuist/tuist:latest

或拉取特定版本：

docker pull ghcr.io/tuist/tuist:0.1.0

部署 Docker 映像{#deploying-the-docker-image}

Docker 映像的部署流程會根據您選擇的雲供應商和組織的持續部署方法而有所不同。由於大多數雲端解決方案和工具 (例如 Kubernetes)，都使用 Docker 映像作為基本單位，因此本節中的範例應該與您現有的設定相當吻合。

[!WARNING] 如果您的部署管道需要驗證伺服器是否正常運作，您可以傳送GET HTTP 請求到/ready ，並在回應中斷言200 狀態碼。

飛行{#fly}

若要在 Fly 上部署應用程式，您需要fly.toml 配置檔案。請考慮在您的持續部署 (CD) 管道中動態產生。以下是供您使用的參考範例：

app = "tuist"
primary_region = "fra"
kill_signal = "SIGINT"
kill_timeout = "5s"

[experimental]
  auto_rollback = true

[env]
  # Your environment configuration goes here
  # Or exposed through Fly secrets

[processes]
  app = "/usr/local/bin/hivemind /app/Procfile"

[[services]]
  protocol = "tcp"
  internal_port = 8080
  auto_stop_machines = false
  auto_start_machines = false
  processes = ["app"]
  http_options = { h2_backend = true }

  [[services.ports]]
    port = 80
    handlers = ["http"]
    force_https = true

  [[services.ports]]
    port = 443
    handlers = ["tls", "http"]
  [services.concurrency]
    type = "connections"
    hard_limit = 100
    soft_limit = 80

  [[services.http_checks]]
    interval = 10000
    grace_period = "10s"
    method = "get"
    path = "/ready"
    protocol = "http"
    timeout = 2000
    tls_skip_verify = false
    [services.http_checks.headers]

[[statics]]
  guest_path = "/app/public"
  url_prefix = "/"

然後，您可以執行fly launch --local-only --no-deploy 來啟動應用程式。在之後的部署中，您不需要執行fly launch --local-only ，而是需要執行fly deploy --local-only 。Fly.io 不允許拉取私有的 Docker 映像，這就是為什麼我們需要使用--local-only 這個旗號。

普羅米修斯度量{#prometheus-metrics}

Tuist 在/metrics 揭露 Prometheus metrics，以協助您監控自託管的實例。這些指標包括

Finch HTTP 用戶端指標{#finch-metrics}

Tuist 使用 Finch 作為 HTTP 客戶端，並揭露 HTTP 請求的詳細指標：

要求度量

• tuist_prom_ex_finch_request_count_total - Finch 請求總數 (計數器)
  • 標籤：finch_name,method,scheme,host,port,status
• tuist_prom_ex_finch_request_duration_milliseconds - HTTP 請求的持續時間 (直方圖)
  • 標籤：finch_name,method,scheme,host,port,status
  • 桶：10ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s
• tuist_prom_ex_finch_request_exception_count_total - Finch 請求例外總數 (計數器)
  • 標籤：finch_name,method,scheme,host,port,kind,reason

連線池佇列指標

• tuist_prom_ex_finch_queue_duration_milliseconds - 連線池佇列中等待的時間 (直方圖)
  • 標籤：finch_name,scheme,host,port,pool
  • 桶：1ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s
• tuist_prom_ex_finch_queue_idle_time_milliseconds - 連線在使用前的閒置時間 (直方圖)
  • 標籤：finch_name,scheme,host,port,pool
  • 桶：10毫秒、50毫秒、100毫秒、250毫秒、500毫秒、1秒、5秒、10秒
• tuist_prom_ex_finch_queue_exception_count_total - Finch 佇列異常總數 (計數器)
  • 標籤：finch_name,scheme,host,port,kind,reason

連線度量

• tuist_prom_ex_finch_connect_duration_milliseconds - 建立連線所花的時間 (直方圖)
  • 標籤：finch_name,scheme,host,port,錯誤
  • 桶：10ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s
• tuist_prom_ex_finch_connect_count_total - 連線嘗試總次數 (計數器)
  • Labels:finch_name,scheme,host,port

傳送指標

• tuist_prom_ex_finch_send_duration_milliseconds - 傳送要求所花的時間 (直方圖)
  • Labels:finch_name,method,scheme,host,port,error
  • 桶：1ms, 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s
• tuist_prom_ex_finch_send_idle_time_milliseconds - 連線在傳送前閒置的時間 (直方圖)
  • Labels:finch_name,method,scheme,host,port,error
  • 桶：1毫秒、5毫秒、10毫秒、25毫秒、50毫秒、100毫秒、250毫秒、500毫秒

所有直方圖度量都提供_bucket,_sum, 以及_count 變數，以供詳細分析。

其他指標

除了 Finch 測量標準之外，Tuist 還提供下列測量標準：

• BEAM 虛擬機器效能
• 自訂業務邏輯指標（儲存、帳戶、專案等）
• 資料庫效能 (使用 Tuist 主機架構時)

營運{#operations}

Tuist 在/ops/ 下提供了一套公用程式，您可以使用這些公用程式來管理您的實體。

[!WARNING] Authorization

只有句柄列在TUIST_OPS_USER_HANDLES 環境變數中的人才能存取/ops/ 端點。

• 錯誤 (/ops/errors)： 您可以檢視應用程式中發生的意外錯誤。這對於調試和了解出錯的原因非常有用，如果您遇到問題，我們可能會請您與我們分享這些資訊。
• 儀表板 (/ops/dashboard)： 您可以檢視儀表板，以深入瞭解應用程式的效能與健康狀況 (例如：記憶體消耗、執行中的進程、請求數量)。這個儀表板對於了解您使用的硬體是否足以處理負載相當有用。