> ## 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.

# 检查启动准备情况

> 检查已安装控制台的启动配置与依赖，不启动应用，也不更改部署状态。

在启动新安装的控制台前，或排查启动失败时，运行 `tuneplane-server preflight`。
它检查已安装的服务端及其启动环境，不启动应用、不执行迁移、不创建应用数据或探测文件、不拉取镜像，
也不修改数据库记录或 Redis 键。

该命令随 `tuneplane-server` 提供。使用已安装的服务端环境或控制台镜像即可，
不需要源码检出、Node.js 或额外的诊断工具。

## 在服务端环境中运行

使用与服务端进程相同的环境变量、`.env`、工作目录、存储挂载、用户和用户组。
在宿主机上以 root 运行，可能得到与容器内控制台服务用户不同的结果。

对于已安装的服务端环境：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tuneplane-server preflight
tuneplane-server preflight --connect --timeout 5
tuneplane-server preflight --connect --json
```

对于已有的 [Docker Compose 部署](/zh-Hans/ops/install-compose)，
在 `app` 容器内调用已安装的可执行文件：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
docker compose exec -T app tuneplane-server preflight
docker compose exec -T app tuneplane-server preflight --connect --json
```

如果应用已停止，可以使用现有部署的 Compose 配置，将正常启动命令替换为预检：

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
docker compose run --rm --no-deps --pull never app tuneplane-server preflight --connect --json
```

这会启动一个临时诊断容器，不会启动应用或其依赖服务。镜像、网络和挂载必须已准备好；
使用 `--connect` 时，PostgreSQL 和已配置的 Redis 服务必须已经可达。
随产品提供的镜像使用 `uvicorn` 作为默认命令，没有会先于预检启动应用的 entrypoint。
在其他容器平台上调整命令时，请保留部署的环境、挂载和服务用户。

## 选择检查范围

| 选项                  | 行为                                                  |
| ------------------- | --------------------------------------------------- |
| 不带选项                | 检查启动配置与本地安装资源，不建立网络连接                               |
| `--connect`         | 额外连接 PostgreSQL，只读检查版本与数据库迁移版本；已配置 Redis 时发送 `PING` |
| `--json`            | 输出供运维人员或自动化使用的结构化报告                                 |
| `--timeout SECONDS` | 设置每项网络探测的超时，取 1 到 60 的整数秒，默认 5 秒                    |

超时分别作用于各项网络探测，不是整个命令的运行期限，
也无法限制因 NFS 挂载无响应而阻塞的文件系统调用。
PostgreSQL 和 Redis 分别探测，两者的累计等待时间可能接近所配置超时的两倍。

预检**只检查环境变量和 dotenv 启动配置**，不加载保存在数据库中的设置，也不检查已登记的
Fleet 配置。将报告与控制台运行时的实际设置对照时，请参考[配置](/zh-Hans/ops/configuration)。

## 报告检查哪些内容

| 范围                          | 检查依据                           |
| --------------------------- | ------------------------------ |
| 启动配置                        | 提供的设置能否加载并通过校验                 |
| 发布版本兼容性                     | 已安装的客户端、节点和契约与控制台内置发布清单是否兼容    |
| 身份认证与密钥                     | 配置的认证方式、持久化 JWT 签名密钥和凭据加密配置    |
| 安装资源                        | 前端入口文件与内置作业运行器是否存在             |
| 本地存储                        | 挂载与权限元数据，以及文件系统报告的可用容量；不创建探测文件 |
| PostgreSQL，使用 `--connect` 时 | 连接情况、服务端版本，以及数据库结构版本与当前安装版本的关系 |
| Redis，使用 `--connect` 时      | 已配置 Redis 时的 `PING` 响应         |

禁用认证或未配置持久化 JWT 密钥会导致预检失败。缺少凭据加密配置会产生警告；
如果启用了 Hugging Face 集成，则会检查失败。确认运行器存在不等于验证其完整性，
也不能证明它可以成功执行。

本地存储检查不能证明应用能够成功写入。它不测试远程存储、保存在数据库中的凭据、
远程文件系统执行的配额限制，也不验证恢复操作。

对于 PostgreSQL，未检测到 TunePlane 核心表（`users` 或 `jobs`）及数据库结构版本时，
会产生警告；预检不会初始化数据库。这不代表数据库中没有其他表。
能识别的旧数据库结构版本会产生待迁移警告。
未知版本、已有 TunePlane 核心表但没有结构版本，或已有结构版本但缺少这些核心表，
都会检查失败。预检不会对这些情况执行迁移。
迁移版本检查不验证列、索引或数据完整性；报告会将数据库结构标记为 `not_checked`。
迁移版本检查成功也不能证明升级或回滚安全；请遵循变更流程，并验证[备份与恢复](/zh-Hans/ops/backup)。

## 理解结果

JSON 报告包含 `schema_version: 1`、`scope: "bootstrap"`、顶层 `status` 和 `checks` 数组。
每项检查包含 `id`、`status`、`message` 和 `remediation`。
检查状态为 `pass`、`fail`、`warning` 或 `not_checked`。
自动化应读取状态字段，不要匹配英文消息文本。

| 总体状态                   | 含义                        |
| ---------------------- | ------------------------- |
| `blocked`              | 至少一项检查失败；在依赖该配置前，先按修复提示处理 |
| `incomplete`           | 报告中有未执行的检查                |
| `passed_with_warnings` | 已执行的检查通过，但有需要注意的条件        |
| `passed`               | 报告中的所有检查均通过               |

总体状态按表中顺序决定：有失败项时为 `blocked`；否则，只要有 `not_checked` 项，
就为 `incomplete`，即使同时存在警告。本版本始终包含运行时设置、存储验收和工作负载这些
未检查项，因此没有失败项的报告会显示 `incomplete`，并以退出码 0 结束。

| 退出码 | 含义                             |
| --- | ------------------------------ |
| `0` | 没有检查失败；仍可能有警告或 `not_checked` 项 |
| `1` | 至少一项检查失败                       |
| `2` | 命令用法不正确，例如超时值超出范围              |

**退出码 0 不代表可以上线。** 请逐项检查结果，并将报告保存在部署记录中。
报告不包含原始异常、URL、主机名、文件系统路径或密钥值；修复提示会指出需要检查的设置或运维操作。

## 单独完成部署验收

报告会将这些范围标记为 `not_checked`：已登记 Fleet 的健康状况、Worker 到 ingest 的连通性、
对象存储、实际存储写入与恢复、GPU 执行，以及离线环境准备情况。
这些检查需要在目标基础设施上运行工作负载或进行运维演练。

解决启动配置问题后，使用有代表性的作业验证目标 Fleet 和数据路径。
[冒烟测试](/zh-Hans/ops/smoke-test)介绍基于源码的 CPU 执行测试工具，它是独立的端到端检查。
请在目标硬件上验证 GPU 执行，演练从备份恢复；无法访问外网时，遵循[离线部署](/zh-Hans/ops/airgapped)流程。