> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuneplane.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境要求

> 安装之前需要准备什么——从一台 GPU 机器到一个受集中治理的集群。

TunePlane 的设计目标是在一台 GPU 服务器上和在受集中治理的多节点集群上都能工作，
而不是为两者各出一个产品。两者之间变的只是「下面这些东西你真正需要哪几样」。

## 无论如何都需要

| 东西                           | 说明                                                                                |
| ---------------------------- | --------------------------------------------------------------------------------- |
| Python 3.14（控制平面）、3.12+（CLI） | 控制台镜像内置 3.14。`tuneplane` CLI 与节点守护进程仍支持 3.12 及以上——升级服务端不会强迫研究员的笔记本和 GPU 节点跟着升解释器。 |
| 一个容器运行时                      | Docker 或 Podman。裸进程模式是给开发用的，没有任何隔离                                                |
| 存储                           | 一个控制台和每个节点看到完全一致的路径——见[存储布局](/zh-Hans/ops/storage)                                |
| 至少一张 GPU                     | 除了平台自己那套跑在仿真模式下的测试之外                                                              |

## 团队部署还需要

| 东西                                 | 为什么                                             |
| ---------------------------------- | ----------------------------------------------- |
| **Postgres**                       | SQLite 是单写。两个控制台副本争抢同一个文件不叫部署                   |
| **Redis**                          | 共享缓存、分布式锁、限流、token 即时吊销。没有它，后台任务会停掉，而不是跨副本不安全地跑 |
| **S3 兼容对象存储**                      | 作业包、产物、数据集、归档。没有它这些全部回落到共享盘路径                   |
| **固定的 `TUNEPLANE_WEB_JWT_SECRET`** | 否则每次重启都换一把密钥，全员掉线                               |
| **一个 https 域名**                    | `TUNEPLANE_PUBLIC_URL`。没有它单点登录无法工作              |

<Note>
  **控制台用哪个 psycopg。** 发布镜像里编译的是 `psycopg[c]`，链基础镜像的 libpq——所以连接
  托管 Postgres 时 TLS 校验用的是镜像信任的那套证书，libpq 的安全修复也随下一次镜像重建到位。
  `psycopg[binary]` 是同一份 C 代码，只是把 libpq 和它自己的 OpenSSL 打包进了 wheel，开发环境
  用它，因为不需要编译器。自己装 wheel 时二选一：`tuneplane-server[c]`（需要 `libpq-dev` 和
  编译器）或 `tuneplane-server[binary]`。两个都不装也能跑，psycopg 会退回纯 Python 绑定：更慢，
  但不会坏。
</Note>

<Warning>
  控制台副本多于一个又没有 Redis 的部署，后台角色是被禁用的——存储记账、诊断、
  每日日报和看门狗根本不会运行。[定时任务页](/zh-Hans/console/admin-tasks)有横幅提示，
  但很容易被忽略。
</Warning>

## 按执行器分

<Tabs>
  <Tab title="local">
    一台机器。Docker 或 Podman，真正的 GPU 直通还需要 NVIDIA 容器运行时。别的都不需要。
    即使是团队，这也是正确的起点——之后换执行器是改一项设置，不是一次迁移。
  </Tab>

  <Tab title="agent">
    多台裸机，每台跑一个 `tuneplane-node`。要求存储根以同一路径挂载到控制台和每个节点，
    并且两侧都持有同一个 Bearer token。缺 token 会拒绝启动，而不是无鉴权运行。
  </Tab>

  <Tab title="kuberay">
    一个装了 KubeRay operator 的 Kubernetes 集群、一个 GPU device plugin，
    以及一个承载存储根的 RWX PVC。RWO 的 claim 不会直接失败——
    它给每个 Pod 各自一个卷，于是 checkpoint 分片散落在不同节点上，这次 run 再也续不了。
  </Tab>

  <Tab title="slurm">
    能通过 REST 访问的 `slurmrestd`，带 JWT。控制平面绝不回退到 `sbatch` 或 SSH。
    容器镜像必须通过 `TUNEPLANE_RUNTIME_REGISTRY_FILE` 以 SIF 或 SQSH 提供，
    容器运行时 profile 必须显式选择。
  </Tab>
</Tabs>

## 网络

| 方向          | 用于                                                                          |
| ----------- | --------------------------------------------------------------------------- |
| 用户 → 控制台    | Web 控制台和 API                                                                |
| 集群 → 控制台    | Ingest。训练要回传日志和指标，所以 `TUNEPLANE_INGEST_URL` 必须**从集群内部**可达——绝不能是 `127.0.0.1` |
| 控制台 → 执行器   | Kubernetes API、slurmrestd，或 agent 节点                                        |
| 集群 → 镜像仓库   | 拉训练镜像                                                                       |
| 集群 → 模型 hub | 拉权重，或走内网镜像——见[离线内网](/zh-Hans/ops/airgapped)                                 |

第二行是最容易被忽略的。用户能访问到的控制台，不等于 worker 节点也能访问到。

## 可选项，以及缺了各自会失去什么

| 缺什么                | 后果                                     |
| ------------------ | -------------------------------------- |
| 对象存储               | 没有 `tp dataset push`，没有训练后自动评测         |
| 一个 LLM 端点          | 没有 AI 诊断、没有 Ask Agent、没有 LLM 裁判、没有每日日报 |
| 沙箱镜像               | 需要运行模型生成代码的环境会被拒绝，而不是退化成在训练容器里跑        |
| Argilla            | 没有偏好标注闭环                               |
| Hugging Face OAuth | 读不了受限模型，推不了导出结果                        |