核心概念

Cratenaut 的概念数量有意保持精简。理解项目、服务器、Crate、实例和资源，就能读懂一份完整配置

Cratenaut 这个名称

Cratenaut 是 crate 与 naut 的组合名称

crate 原意可以是用于运输物品的货箱
naut 来自表示航行者的词尾，例如 astronaut

这个名称表达的是：把服务需要的部署内容整理成边界明确的单元，再让工具按照经过审查的计划把它们送到目标服务器

它只是项目品牌名称，不会要求用户学习一套太空主题术语。命令输出和文档仍然使用服务器、容器、文件、数据目录等行业通用词语

Crate

在 Cratenaut 中，Crate 专指一个可复用的部署单元定义

它通常包含：

用户可以填写的配置选项
选项的类型、默认值和校验规则
需要创建的容器、文件、目录、持久化存储和任务
配置变化对应的风险等级
Crate 自身的语义化版本和升级兼容范围

以 PostgreSQL Crate 为例，它会把 PostgreSQL 镜像、数据库名称、密码文件、数据目录、端口、健康检查和版本升级风险放在一起。用户使用它时只需要关心数据库部署需要的选项

Crate 不是正在运行的容器，也不是服务器上的目录。它更接近一个带类型和安全规则的部署模板

Crate 实例

把 Crate 放进服务器配置时，会创建一个实例：

const database = postgres({
  id: "database",
  description: "订单系统数据库",
  options: {
    database: "orders",
    password: secret.env("POSTGRES_PASSWORD"),
  },
});

这里：

postgres 是可复用的 Crate 定义
database 是本次配置中的 Crate 实例
id 是实例在服务器中的稳定标识
description 是给维护者看的用途说明
options 是这个实例自己的配置

同一个 Crate 可以创建多个实例，例如 orders-database 和 analytics-database。它们拥有独立的容器、状态和数据目录

项目

项目由 naut.config.ts 中的 project 标识。项目标识会进入服务器目录、Docker 网络和容器名称，因此发布后应当保持稳定

export default defineConfig({
  project: "commerce",
  servers: [],
});

服务器

服务器是本次部署的目标，可以是当前计算机，也可以通过 SSH 连接：

{
  id: "production",
  description: "生产环境应用服务器",
  connection: {
    kind: "ssh",
    host: "server.example.com",
    user: "deploy",
  },
  crates: [],
}

每台服务器拥有自己的 Crate 实例列表和部署状态。服务器 id 也是长期稳定标识

资源

资源是 Crate 声明的具体托管对象。当前包括：

资源	作用
目录	创建具有固定权限的服务器目录
文件	写入配置、脚本或敏感信息文件
持久化存储	为数据库和应用数据提供稳定目录
容器	声明镜像、端口、挂载、环境变量和健康检查
任务	在容器内执行验证、迁移或配置重载命令

普通配置用户通常不需要直接操作资源；只有编写自定义 Crate 时才会声明它们

部署计划

部署计划来自三份信息：

当前 naut.config.ts 描述的期望状态
上次成功部署保存的状态
服务器上容器和托管文件的实际状态

因此 Cratenaut 能够区分：配置确实发生变化、服务器资源被手工修改，以及配置已经删除但服务器仍然存在的资源

没有隐式依赖图

Crate 实例不会通过输出值自动建立依赖关系，也不会生成隐藏的拓扑图。服务器配置中的数组提供清晰、可见的处理顺序；服务本身仍应当容忍其他服务尚未就绪，并依靠健康检查和重试恢复

同一服务器中的容器会加入项目服务器网络，可以使用 实例标识-容器资源标识 形式的网络别名互相访问，例如 code-server:3000

核心概念 ​

Cratenaut 这个名称 ​

Crate ​

Crate 实例 ​

项目 ​

服务器 ​

资源 ​

部署计划 ​

没有隐式依赖图 ​