自助安装{#self-host-installation}

我们为需要对基础设施进行更多控制的组织提供自助托管版 Tuist 服务器。该版本允许您在自己的基础设施上托管 Tuist，确保您的数据安全私密。

[!WARNING] License Required

自助托管 Tuist 需要合法有效的付费许可证。企业内部版本的 Tuist 仅适用于企业计划。如果您对该版本感兴趣，请联系 [email protected]。

释放节奏{#release-cadence}

我们会根据 Main 上可发布的新变更，不断发布 Tuist 的新版本。我们遵循语义版本，以确保可预测的版本和兼容性。

主要组件用于标记 Tuist 服务器中需要与内部用户协调的破坏性更改。您不要指望我们会使用它，如果我们需要，请放心，我们会与您合作，使过渡顺利进行。

持续部署{#continuous-deployment}

我们强烈建议设置持续部署管道，每天自动部署最新版本的 Tuist。这将确保您始终可以访问最新的功能、改进和安全更新。

下面是一个 GitHub 操作工作流程示例，每天检查并部署新版本：

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 映像。请注意，大多数基础设施提供商都支持 Docker，因为它已成为在生产环境中分发和运行软件的标准容器。

Postgres 数据库{#postgres-database}

除了运行 Docker 映像，您还需要一个带有 TimescaleDB 扩展的 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
  • 将回调 URL 设置为http://YOUR_APP_URL/users/auth/github/callback 。YOUR_APP_URL 也可以是服务器的 IP 地址。
• 需要以下权限
  • 资料库：
    • 拉取请求：读写
  • 账户
    • 电子邮件地址：只读

在Permissions and events 的Account permissions 部分，将Email addresses 权限设置为Read-only 。

然后，您需要在 Tuist 服务器运行的环境中公开以下环境变量：

谷歌{#google}

您可以使用 OAuth 2 与 Google 进行身份验证。为此，你需要创建一个 OAuth 客户端 ID 类型的新凭证。创建凭证时，选择 "Web 应用程序 "作为应用程序类型，将其命名为Tuist ，并将重定向 URI 设置为{base_url}/users/auth/google/callback ，其中base_url 是您的托管服务运行的 URL。创建应用程序后，复制客户端 ID 和秘密，并将其分别设置为环境变量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 和密码后，您需要设置以下环境变量：

1 需要用您的机构 ID 代替。通常是 1，但请在您的数据库中查看。

存储环境配置{#storage-environment-configuration}

Tuist 需要存储空间来存放通过 API 上传的工件。必须配置一个受支持的存储解决方案 ，Tuist 才能有效运行。

符合 S3 标准的存储{#s3compliant-storages}

您可以使用任何兼容 S3 的存储提供程序来存储人工制品。需要使用以下环境变量来验证和配置与存储提供商的集成：

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

如果您的存储提供商是 AWS，并且您想使用网络身份令牌进行身份验证，您可以将环境变量TUIST_S3_AUTHENTICATION_METHOD 设置为aws_web_identity_token_from_env_vars ，Tuist 将使用传统的 AWS 环境变量使用该方法。

谷歌云存储{#google-cloud-storage}

对于 Google Cloud Storage，请按照这些文档获取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>集成，提供额外功能，例如自动在拉取请求中发布注释。

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用户界面）： http://localhost:8081
• 普罗米修斯度量标准：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-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 映像作为基本单元，因此本节中的示例应与您的现有设置保持一致。

:: 警告

如果部署管道需要验证服务器是否正常运行，可以向/ready 发送GET HTTP 请求，并在响应中断言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 deploy --local-only ，而不是运行fly launch --local-only 。Fly.io 不允许拉取私有的 Docker 镜像，因此我们需要使用--local-only 标志。

普罗米修斯指标{#prometheus-metrics}

Tuist 在/metrics 公开 Prometheus 指标，帮助您监控自托管实例。这些指标包括

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
  • 桶10毫秒、50毫秒、100毫秒、250毫秒、500毫秒、1秒、2.5秒、5秒、10秒
• 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
  • 桶1毫秒、5毫秒、10毫秒、25毫秒、50毫秒、100毫秒、250毫秒、500毫秒、1秒
• 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,error
  • 桶10毫秒、50毫秒、100毫秒、250毫秒、500毫秒、1秒、2.5秒、5秒
• tuist_prom_ex_finch_connect_count_total - 尝试连接的总次数（计数器）。
  • 标签：finch_name,scheme,host,port

发送指标

• tuist_prom_ex_finch_send_duration_milliseconds - 发送请求所用的时间（直方图）
  • 标签：finch_name,method,scheme,host,port,error
  • 桶1毫秒、5毫秒、10毫秒、25毫秒、50毫秒、100毫秒、250毫秒、500毫秒、1秒
• tuist_prom_ex_finch_send_idle_time_milliseconds - 发送前连接空闲的时间（直方图）。
  • 标签：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）： 您可以查看仪表盘，了解应用程序的性能和健康状况（如内存消耗、正在运行的进程、请求数）。该仪表盘对于了解所使用的硬件是否足以处理负载非常有用。