安装

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

发布节奏

我们会在新的可发布变更合并到 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 服务器已过测试并与以下最低版本兼容：

组件	最低版本	备注
PostgreSQL	15
ClickHouse	25	用于分析

运行 Docker 虚拟化镜像

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

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

Postgres 数据库

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

ClickHouse 数据库

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

存储

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

请参阅 缓存自托管指南。

自托管缓存节点

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

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

配置

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

许可证配置

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

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

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

基础环境配置

环境变量	描述	必需	默认	示例
TUIST_APP_URL	从互联网访问实例的基础 URL	是		https://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 地址	否	0	1
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 服务器端点	否	1	1 或 0
TUIST_OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry 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 连接数据库	否	1	1
TUIST_DATABASE_POOL_SIZE	保持打开的连接池连接数	否	10	10
TUIST_DATABASE_QUEUE_TARGET	检查从连接池中取出的所有连接是否超过队列间隔的时间间隔（毫秒）（更多信息）	否	300	300
TUIST_DATABASE_QUEUE_INTERVAL	队列中连接池用于确定是否应该开始丢弃新连接的阈值时间（毫秒）（更多信息）	否	1000	1000
TUIST_CLICKHOUSE_FLUSH_INTERVAL_MS	ClickHouse 缓冲区刷新之间的时间间隔（毫秒）	否	5000	5000
TUIST_CLICKHOUSE_MAX_BUFFER_SIZE	强制刷新前的最大 ClickHouse 缓冲区大小（字节）	否	1000000	1000000
TUIST_CLICKHOUSE_BUFFER_POOL_SIZE	运行的 ClickHouse 缓冲区进程数	否	5	5

身份验证环境配置

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

GitHub

我们建议使用 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/callback。YOUR_APP_URL 也可以是你的服务器 IP 地址。
• 需要以下权限：
  • 仓库：
    • 拉取请求：读写
  • 账户：
    • 邮箱地址：只读

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

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

环境变量	描述	必需	默认	示例
TUIST_GITHUB_APP_CLIENT_ID	GitHub 应用的 client ID	是		Iv1.a629723000043722
TUIST_GITHUB_APP_CLIENT_SECRET	应用的 client secret	是		232f972951033b89799b0fd24566a04d83f44ccc

Google

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

Okta

你可以通过 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，但请在你的数据库中检查。

存储环境配置

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

S3 兼容存储

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

环境变量	描述	必需	默认	示例
TUIST_S3_ACCESS_KEY_ID 或 AWS_ACCESS_KEY_ID	用于向存储提供商进行身份验证的 access key ID	是		AKIAIOSFOD
TUIST_S3_SECRET_ACCESS_KEY 或 AWS_SECRET_ACCESS_KEY	用于向存储提供商进行身份验证的 secret access key	是		wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
TUIST_S3_REGION 或 AWS_REGION	存储桶所在的区域	否	auto	us-west-2
TUIST_S3_ENDPOINT 或 AWS_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	与存储提供商建立连接的超时时间（毫秒）	否	3000	3000
TUIST_S3_RECEIVE_TIMEOUT	从存储提供商接收数据的超时时间（毫秒）	否	5000	5000
TUIST_S3_POOL_TIMEOUT	到存储提供商的连接池的超时时间（毫秒）。无超时使用 infinity	否	5000	5000
TUIST_S3_POOL_MAX_IDLE_TIME	池中连接的最大空闲时间（毫秒）。使用 infinity 使连接永久保持活动状态	否	infinity	60000
TUIST_S3_POOL_SIZE	每个池的最大连接数	否	500	500
TUIST_S3_POOL_COUNT	使用的连接池数量	否	系统调度器数量	4
TUIST_S3_PROTOCOL	连接到存储提供商时使用的协议（http1 或 http2）	否	http1	http1
TUIST_S3_VIRTUAL_HOST	URL 是否应使用存储桶名称作为子域（虚拟主机）构造	否	false	1

Google Cloud Storage

对于 Google Cloud Storage，请按照这些文档获取 AWS_ACCESS_KEY_ID 和 AWS_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，如果配置了邮箱则为 false	true、false、1、0

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

Git 平台配置

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

GitHub

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

除了 TUIST_GITHUB_APP_CLIENT_ID 和 TUIST_GITHUB_APP_CLIENT_SECRET 外，你还需要以下环境变量：

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

本地测试

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

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

快速开始：

1. 下载配置文件：

   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. 配置环境变量：

   cp .env.example .env
   # 编辑 .env 并添加你的 TUIST_LICENSE 和身份验证凭据

3. 启动所有服务：

   docker compose up -d
   # 或使用 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 指标：http://localhost:9091/metrics
• ClickHouse HTTP：http://localhost:8124

常用命令：

检查服务状态：

docker compose ps
# 或：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 - 环境变量示例文件

部署

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

ghcr.io/tuist/tuist

拉取 Docker 镜像

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

docker pull ghcr.io/tuist/tuist:latest

或拉取特定版本：

docker pull ghcr.io/tuist/tuist:0.1.0

部署 Docker 镜像

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]
  # 你的环境配置在这里
  # 或通过 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 指标

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

Finch HTTP 客户端指标

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
  • 桶：10ms、50ms、100ms、250ms、500ms、1s、5s、10s
• 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
  • 桶：10ms、50ms、100ms、250ms、500ms、1s、2.5s、5s
• 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
  • 桶：1ms、5ms、10ms、25ms、50ms、100ms、250ms、500ms、1s
• tuist_prom_ex_finch_send_idle_time_milliseconds - 连接在发送前空闲的时间（直方图）
  • 标签：finch_name、method、scheme、host、port、error
  • 桶：1ms、5ms、10ms、25ms、50ms、100ms、250ms、500ms

所有直方图指标都提供 _bucket、_sum 和 _count 变体以供详细分析。

其他指标

除了 Finch 指标外，Tuist 还公开以下指标：

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

运维

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

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