跳转到内容

安装

我们为需要更多基础设施控制权的组织提供自托管版本的 Tuist 服务器。此版本允许你在自己的基础设施上托管 Tuist,确保你的数据保持安全私有。

::: warning 需要许可证

自托管 Tuist 需要合法有效的付费许可证。Tuist 的本地部署版本仅适用于 Enterprise 计划组织。如果你对此版本感兴趣,请联系 [email protected]

:::

我们会在新的可发布变更合并到 main 分支后持续发布新版本的 Tuist。我们遵循语义化版本控制以确保可预测的版本控制和兼容性。

主要版本用于标记 Tuist 服务器的重大变更,这些变更需要与本地部署用户协调。我们预计不会使用它,但如果需要,我们会与你合作使过渡顺利进行。

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

以下是一个 GitHub Actions 工作流程示例,每天检查并部署新版本:

name: Update Tuist Server
on:
schedule:
- cron: '0 3 * * *' # 每天 UTC 时间 3 AM 运行
workflow_dispatch: # 允许手动运行
jobs:
update:
runs-on: ubuntu-latest
steps:
- name: Check and deploy latest version
run: |
# 你的部署命令在这里
# 示例: docker pull ghcr.io/tuist/tuist:latest
# 部署到你的基础设施

本节概述了在你的基础设施上托管 Tuist 服务器的要求。

Tuist 服务器已过测试并与以下最低版本兼容:

组件最低版本备注
PostgreSQL15
ClickHouse25用于分析

运行 Docker 虚拟化镜像 {#running-dockervirtualized-images}

Section titled “运行 Docker 虚拟化镜像 {#running-dockervirtualized-images}”

我们通过 GitHub 的容器注册表将服务器分发为 Docker 镜像。

要运行它,你的基础设施必须支持运行 Docker 镜像。请注意,大多数基础设施提供商都支持它,因为它已成为在生产环境中分发和运行软件的标准容器。

除了运行 Docker 镜像外,你还需要一个 Postgres 数据库 来存储关系数据。大多数基础设施提供商在其产品中都包含 Postgres 数据库(例如 AWSGoogle Cloud)。

::: info 迁移

Docker 镜像的入口点在启动服务之前会自动运行任何待处理的 schema 迁移。

:::

ClickHouse 数据库 {#clickhouse-database}

Section titled “ClickHouse 数据库 {#clickhouse-database}”

Tuist 使用 ClickHouse 来存储和查询大量分析数据。ClickHouse 对于构建洞察等功能是必需的。你可以选择自托管 ClickHouse 或使用他们的托管服务。

::: info 迁移

Docker 镜像的入口点在启动服务之前会自动运行任何待处理的 ClickHouse schema 迁移。

:::

你还需要一个用于存储文件(例如框架和库二进制文件)的解决方案。目前我们支持任何 S3 兼容的存储。

::: tip 优化缓存

如果你的主要目标是自带存储桶来存储二进制文件并减少缓存延迟,你可能不需要自托管整个服务器。你可以自托管缓存节点并将它们连接到托管的 Tuist 服务器或你的自托管服务器。

请参阅 缓存自托管指南

:::

自托管缓存节点 {#self-hosted-cache-nodes}

Section titled “自托管缓存节点 {#self-hosted-cache-nodes}”

要在自托管 Tuist 服务器上使用自托管缓存节点:

  1. 按照 缓存自托管指南 部署你的缓存节点。
  2. TUIST_CACHE_ENDPOINTS 设置为逗号分隔的缓存节点 URL 列表(例如,https://cache-1.example.com,https://cache-2.example.com)。

服务的配置在运行时通过环境变量完成。鉴于这些变量的敏感性质,我们建议将它们加密并存储在安全的密码管理解决方案中。请放心,Tuist 会极其谨慎地处理这些变量,确保它们永远不会显示在日志中。

::: info 启动检查

必要的变量会在启动时进行验证。如果有任何缺失,启动将失败,错误消息将详细说明缺失的变量。

:::

作为本地部署用户,你会收到一个许可证密钥,你需要将其作为环境变量公开。此密钥用于验证许可证并确保服务按照协议条款运行。

环境变量描述必需默认示例
TUIST_LICENSE签署服务级别协议后提供的许可证是*******
TUIST_LICENSE_CERTIFICATE_BASE64TUIST_LICENSE 的特殊替代方案。用于在无法联系外部服务的 air-gapped 环境中进行离线许可证验证的 Base64 编码公钥证书。仅在无法使用 TUIST_LICENSE 时使用是*LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...

* 必须提供 TUIST_LICENSETUIST_LICENSE_CERTIFICATE_BASE64 之一,但不能同时提供。标准部署使用 TUIST_LICENSE

::: warning 过期日期

许可证有过期日期。如果许可证在不到 30 天后过期,用户在使用与服务器交互的 Tuist 命令时会收到警告。如果你有兴趣续订许可证,请联系 [email protected]

:::

基础环境配置 {#base-environment-configuration}

Section titled “基础环境配置 {#base-environment-configuration}”
环境变量描述必需默认示例
TUIST_APP_URL从互联网访问实例的基础 URLhttps://tuist.dev
TUIST_SECRET_KEY_BASE用于加密信息的密钥(例如 cookie 中的会话)c5786d9f869239cbddeca645575349a570ffebb332b64400c37256e1c9cb7ec831345d03dc0188edd129d09580d8cbf3ceaf17768e2048c037d9c31da5dcacfa
TUIST_SECRET_KEY_PASSWORD生成哈希密码的 pepper$TUIST_SECRET_KEY_BASE
TUIST_SECRET_KEY_TOKENS生成随机令牌的密钥$TUIST_SECRET_KEY_BASE
TUIST_SECRET_KEY_ENCRYPTION用于 AES-GCM 加密敏感数据的 32 字节密钥$TUIST_SECRET_KEY_BASE
TUIST_USE_IPV6当为 1 时,配置应用使用 IPv6 地址01
TUIST_LOG_LEVEL应用使用的日志级别info日志级别
TUIST_GITHUB_APP_NAME你的 GitHub 应用名称的 URL 版本my-app
TUIST_GITHUB_APP_PRIVATE_KEY_BASE64用于 GitHub 应用解锁额外功能(如自动发布 PR 评论)的 Base64 编码私钥LS0tLS1CRUdJTiBSU0EgUFJJVkFUR...
TUIST_GITHUB_APP_PRIVATE_KEY用于 GitHub 应用解锁额外功能(如自动发布 PR 评论)的私钥。我们建议使用 Base64 编码版本以避免特殊字符问题-----BEGIN RSA...
TUIST_OPS_USER_HANDLES有权访问操作 URL 的用户句柄逗号分隔列表user1,user2
TUIST_WEB启用 Web 服务器端点110
TUIST_OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry Collector 的 gRPC 端点,用于发送追踪http://localhost:4317
TUIST_LOKI_URL兼容 Loki 端点的基础 URL,用于推送日志(例如 Grafana Alloy 或 Loki)http://localhost:3100

以下环境变量用于配置数据库连接:

环境变量描述必需默认示例
DATABASE_URL访问 Postgres 数据库的 URL。请注意,URL 应包含身份验证信息postgres://username:[email protected]/production
TUIST_CLICKHOUSE_URL访问 ClickHouse 数据库的 URL。请注意,URL 应包含身份验证信息http://username:[email protected]/production
TUIST_USE_SSL_FOR_DATABASE为真时,使用 SSL 连接数据库11
TUIST_DATABASE_POOL_SIZE保持打开的连接池连接数1010
TUIST_DATABASE_QUEUE_TARGET检查从连接池中取出的所有连接是否超过队列间隔的时间间隔(毫秒)(更多信息)300300
TUIST_DATABASE_QUEUE_INTERVAL队列中连接池用于确定是否应该开始丢弃新连接的阈值时间(毫秒)(更多信息)10001000
TUIST_CLICKHOUSE_FLUSH_INTERVAL_MSClickHouse 缓冲区刷新之间的时间间隔(毫秒)50005000
TUIST_CLICKHOUSE_MAX_BUFFER_SIZE强制刷新前的最大 ClickHouse 缓冲区大小(字节)10000001000000
TUIST_CLICKHOUSE_BUFFER_POOL_SIZE运行的 ClickHouse 缓冲区进程数55

身份验证环境配置 {#authentication-environment-configuration}

Section titled “身份验证环境配置 {#authentication-environment-configuration}”

我们通过身份提供商 (IdP) 促进身份验证。要使用此功能,请确保所选提供商的所有必要环境变量都存在于服务器环境中。缺失的变量将导致 Tuist 跳过该提供商。

我们建议使用 GitHub App 进行身份验证,但你也可以使用 OAuth App。请确保在服务器环境中包含 GitHub 指定的所有必要环境变量。缺失的变量将导致 Tuist 忽略 GitHub 身份验证。要正确设置 GitHub 应用:

  • 在 GitHub 应用的一般设置中:
    • 复制 Client ID 并将其设置为 TUIST_GITHUB_APP_CLIENT_ID
    • 创建并复制新的 client secret 并将其设置为 TUIST_GITHUB_APP_CLIENT_SECRET
    • Callback URL 设置为 http://YOUR_APP_URL/users/auth/github/callbackYOUR_APP_URL 也可以是你的服务器 IP 地址。
  • 需要以下权限:
    • 仓库:
      • 拉取请求:读写
    • 账户:
      • 邮箱地址:只读

Permissions and eventsAccount permissions 部分,将 Email addresses 权限设置为 Read-only

然后,你需要在 Tuist 服务器运行的环境中公开以下环境变量:

环境变量描述必需默认示例
TUIST_GITHUB_APP_CLIENT_IDGitHub 应用的 client IDIv1.a629723000043722
TUIST_GITHUB_APP_CLIENT_SECRET应用的 client secret232f972951033b89799b0fd24566a04d83f44ccc

你可以使用 OAuth 2 设置 Google 身份验证。为此,你需要创建一个类型为 OAuth client ID 的新凭据。创建凭据时,选择 “Web Application” 作为应用类型,命名为 Tuist,并将重定向 URI 设置为 {base_url}/users/auth/google/callback,其中 base_url 是你托管服务运行的 URL。创建应用后,复制 client ID 和 secret,分别将它们设置为环境变量 GOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRET

::: info 同意屏幕作用域

你可能需要创建同意屏幕。创建时,请确保添加 userinfo.emailopenid 作用域,并将应用标记为内部应用。

:::

你可以通过 OAuth 2.0 协议启用 Okta 身份验证。你需要按照 这些说明 在 Okta 上创建一个应用

设置 Okta 应用时获得 client id 和 secret 后,你需要设置以下环境变量:

环境变量描述必需默认示例
TUIST_OKTA_1_CLIENT_ID用于向 Okta 进行身份验证的 client ID。数字应该是你的组织 ID
TUIST_OKTA_1_CLIENT_SECRET用于向 Okta 进行身份验证的 client secret

数字 1 需要替换为你的组织 ID。通常是 1,但请在你的数据库中检查。

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

Section titled “存储环境配置 {#storage-environment-configuration}”

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

你可以使用任何 S3 兼容的存储提供商来存储工件。以下环境变量是验证和配置与存储提供商集成所必需的:

环境变量描述必需默认示例
TUIST_S3_ACCESS_KEY_IDAWS_ACCESS_KEY_ID用于向存储提供商进行身份验证的 access key IDAKIAIOSFOD
TUIST_S3_SECRET_ACCESS_KEYAWS_SECRET_ACCESS_KEY用于向存储提供商进行身份验证的 secret access keywJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
TUIST_S3_REGIONAWS_REGION存储桶所在的区域autous-west-2
TUIST_S3_ENDPOINTAWS_ENDPOINT存储提供商的端点https://s3.us-west-2.amazonaws.com
TUIST_S3_BUCKET_NAME存储工件的存储桶名称tuist-artifacts
TUIST_S3_CA_CERT_PEM用于验证 S3 HTTPS 连接的 PEM 编码 CA 证书。适用于具有自签名证书或内部证书颁发机构的 air-gapped 环境系统 CA 证书包-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----
TUIST_S3_CONNECT_TIMEOUT与存储提供商建立连接的超时时间(毫秒)30003000
TUIST_S3_RECEIVE_TIMEOUT从存储提供商接收数据的超时时间(毫秒)50005000
TUIST_S3_POOL_TIMEOUT到存储提供商的连接池的超时时间(毫秒)。无超时使用 infinity50005000
TUIST_S3_POOL_MAX_IDLE_TIME池中连接的最大空闲时间(毫秒)。使用 infinity 使连接永久保持活动状态infinity60000
TUIST_S3_POOL_SIZE每个池的最大连接数500500
TUIST_S3_POOL_COUNT使用的连接池数量系统调度器数量4
TUIST_S3_PROTOCOL连接到存储提供商时使用的协议(http1http2http1http1
TUIST_S3_VIRTUAL_HOSTURL 是否应使用存储桶名称作为子域(虚拟主机)构造false1

::: info 使用环境变量的 Web 身份令牌进行 AWS 身份验证

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

:::

Google Cloud Storage {#google-cloud-storage}

Section titled “Google Cloud Storage {#google-cloud-storage}”

对于 Google Cloud Storage,请按照这些文档获取 AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY 对。AWS_ENDPOINT 应设置为 https://storage.googleapis.com。其他环境变量与任何其他 S3 兼容存储相同。

Tuist 需要邮件功能用于用户身份验证和事务性通知(例如密码重置、账户通知)。目前,仅支持 Mailgun 作为邮件提供商。

环境变量描述必需默认示例
TUIST_MAILGUN_API_KEY用于 Mailgun 身份验证的 API 密钥是*key-1234567890abcdef
TUIST_MAILING_DOMAIN发送邮件的域名是*mg.tuist.io
TUIST_MAILING_FROM_ADDRESS将显示在 “From” 字段中的邮箱地址是*[email protected]
TUIST_MAILING_REPLY_TO_ADDRESS用户回复的可选回复地址[email protected]
TUIST_SKIP_EMAIL_CONFIRMATION跳过新用户注册的邮箱确认。启用后,用户注册后会自动确认,可以立即登录如果未配置邮箱则为 true,如果配置了邮箱则为 falsetruefalse10

* 仅在你想要发送邮件时才需要配置邮件变量。如果未配置,邮箱确认会自动跳过

::: info SMTP 支持

目前不支持通用 SMTP 支持。如果你的本地部署需要 SMTP 支持,请联系 [email protected] 讨论你的需求。

:::

::: info AIR-GAPPED 部署

对于没有互联网访问或邮件提供商配置的内置部署,邮箱确认默认会自动跳过。用户注册后可以立即登录。如果你已配置了邮箱但仍想跳过确认,请设置 TUIST_SKIP_EMAIL_CONFIRMATION=true。要在配置了邮箱时要求邮箱确认,请设置 TUIST_SKIP_EMAIL_CONFIRMATION=false

:::

Git 平台配置 {#git-platform-configuration}

Section titled “Git 平台配置 {#git-platform-configuration}”

Tuist 可以 与 Git 平台集成 以提供额外功能,例如自动在你的 pull request 中发布评论。

你需要创建一个 GitHub 应用。你可以复用为身份验证创建的那个,除非你创建了 OAuth GitHub 应用。在 Permissions and eventsRepository permissions 部分,你还需要额外将 Pull requests 权限设置为 Read and write

除了 TUIST_GITHUB_APP_CLIENT_IDTUIST_GITHUB_APP_CLIENT_SECRET 外,你还需要以下环境变量:

环境变量描述必需默认示例
TUIST_GITHUB_APP_PRIVATE_KEYGitHub 应用的私钥-----BEGIN RSA PRIVATE KEY-----...

我们提供了一个全面的 Docker Compose 配置,包含在将 Tuist 服务器部署到你的基础设施之前,在本地机器上测试它所需的所有依赖项:

  • PostgreSQL 15
  • ClickHouse 25 用于分析
  • ClickHouse Keeper 用于协调
  • MinIO 用于 S3 兼容存储
  • Redis 用于跨部署的持久化 KV 存储(可选)
  • pgweb 用于数据库管理

::: danger 需要许可证

运行 Tuist 服务器(包括本地开发实例)需要合法的 TUIST_LICENSE 环境变量。如果你需要许可证,请联系 [email protected]

:::

快速开始:

  1. 下载配置文件:

    Terminal window
    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. 配置环境变量:

    Terminal window
    cp .env.example .env
    # 编辑 .env 并添加你的 TUIST_LICENSE 和身份验证凭据
  3. 启动所有服务:

    Terminal window
    docker compose up -d
    # 或使用 podman:
    podman compose up -d
  4. http://localhost:8080 访问服务器

服务端点:

常用命令:

检查服务状态:

Terminal window
docker compose ps
# 或:podman compose ps

查看日志:

Terminal window
docker compose logs -f tuist

停止服务:

Terminal window
docker compose down

重置一切(删除所有数据):

Terminal window
docker compose down -v

配置文件:

官方 Tuist Docker 镜像可在以下位置获取:

ghcr.io/tuist/tuist

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

Section titled “拉取 Docker 镜像 {#pulling-the-docker-image}”

你可以通过执行以下命令获取镜像:

Terminal window
docker pull ghcr.io/tuist/tuist:latest

或拉取特定版本:

Terminal window
docker pull ghcr.io/tuist/tuist:0.1.0

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

Section titled “部署 Docker 镜像 {#deploying-the-docker-image}”

Docker 镜像的部署过程因你选择的云提供商和组织的持续部署方法而异。由于大多数云解决方案和工具(如 Kubernetes)都使用 Docker 镜像作为基本单元,本节中的示例应该与你现有的设置很好地吻合。

::: warning

如果你的部署管道需要验证服务器是否正常运行,你可以向 /ready 发送 GET HTTP 请求并在响应中断言 200 状态码。

:::

要在 Fly 上部署应用,你需要 fly.toml 配置文件。考虑在你的持续部署 (CD) 管道中动态生成它。以下是供你使用的参考示例:

app = "tuist"
primary_region = "fra"
kill_signal = "SIGINT"
kill_timeout = "5s"
[experimental]
auto_rollback = true
[env]
# 你的环境配置在这里
# 或通过 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 标志。

Tuist 在 /metrics 公开 Prometheus 指标,以帮助你监控自托管实例。这些指标包括:

Finch HTTP 客户端指标 {#finch-metrics}

Section titled “Finch HTTP 客户端指标 {#finch-metrics}”

Tuist 使用 Finch 作为其 HTTP 客户端,并公开有关 HTTP 请求的详细指标:

  • tuist_prom_ex_finch_request_count_total - Finch 请求总数(计数器)
    • 标签:finch_namemethodschemehostportstatus
  • tuist_prom_ex_finch_request_duration_milliseconds - HTTP 请求持续时间(直方图)
    • 标签:finch_namemethodschemehostportstatus
    • 桶:10ms、50ms、100ms、250ms、500ms、1s、2.5s、5s、10s
  • tuist_prom_ex_finch_request_exception_count_total - Finch 请求异常总数(计数器)
    • 标签:finch_namemethodschemehostportkindreason
  • tuist_prom_ex_finch_queue_duration_milliseconds - 在连接池队列中等待的时间(直方图)
    • 标签:finch_nameschemehostportpool
    • 桶:1ms、5ms、10ms、25ms、50ms、100ms、250ms、500ms、1s
  • tuist_prom_ex_finch_queue_idle_time_milliseconds - 连接在使用前空闲的时间(直方图)
    • 标签:finch_nameschemehostportpool
    • 桶:10ms、50ms、100ms、250ms、500ms、1s、5s、10s
  • tuist_prom_ex_finch_queue_exception_count_total - Finch 队列异常总数(计数器)
    • 标签:finch_nameschemehostportkindreason
  • tuist_prom_ex_finch_connect_duration_milliseconds - 建立连接所花费的时间(直方图)
    • 标签:finch_nameschemehostporterror
    • 桶:10ms、50ms、100ms、250ms、500ms、1s、2.5s、5s
  • tuist_prom_ex_finch_connect_count_total - 连接尝试总数(计数器)
    • 标签:finch_nameschemehostport
  • tuist_prom_ex_finch_send_duration_milliseconds - 发送请求所花费的时间(直方图)
    • 标签:finch_namemethodschemehostporterror
    • 桶:1ms、5ms、10ms、25ms、50ms、100ms、250ms、500ms、1s
  • tuist_prom_ex_finch_send_idle_time_milliseconds - 连接在发送前空闲的时间(直方图)
    • 标签:finch_namemethodschemehostporterror
    • 桶:1ms、5ms、10ms、25ms、50ms、100ms、250ms、500ms

所有直方图指标都提供 _bucket_sum_count 变体以供详细分析。

除了 Finch 指标外,Tuist 还公开以下指标:

  • BEAM 虚拟机性能
  • 自定义业务逻辑指标(存储、账户、项目等)
  • 数据库性能(使用 Tuist 托管基础设施时)

Tuist 在 /ops/ 下提供了一组实用程序,可用于管理你的实例。

::: warning 授权

只有句柄列在 TUIST_OPS_USER_HANDLES 环境变量中的人才能访问 /ops/ 端点。

:::

  • 错误 (/ops/errors): 你可以查看应用中发生的意外错误。这对于调试和了解出了问题很有用,如果你遇到问题,我们可能会要求你与我们分享这些信息。
  • 仪表板 (/ops/dashboard): 你可以查看提供应用性能和健康状况洞察的仪表板(例如内存消耗、运行中的进程、请求数量)。这个仪表板对于了解你使用的硬件是否足以处理负载非常有用。