---
title: 单节点 k3s 快速部署
description: 在一台机器上用 k3s 拉起完整的 Neutree Agent Platform —— 最快的安装路径，联网与隔离网络皆可。
---

import AirgapBlock from '../../../../components/self-host/AirgapBlock.tsx'

在单节点 k3s 集群上安装 Neutree Agent Platform —— 让完整平台跑起来的最快方式。单节点 profile 与完整 profile 一致，只是 PostgreSQL 为单实例、共享存储由集群内 NFS server 提供。

同一条流程覆盖两类节点。**联网**时，所有镜像都从公共 registry（`ghcr.io` / `docker.io` / `registry.k8s.io`）拉取。若节点**完全无法访问互联网**，额外步骤以可折叠的 **隔离网络** 块内嵌在流程中 —— 展开一个即全部保持展开；该路径通过集群内仓库从镜像包安装，全程不从互联网拉取任何镜像。

推荐配置：**8 vCPU / 32 GB / 200 GB 磁盘**，约可支撑 **10 个并发 workspace**。需要 HA 或横向扩展时，走[生产部署](/nap/zh-cn/self-host/)，其中也覆盖[安装进已有 Kubernetes 集群](/nap/zh-cn/self-host/#install)。

## 一行命令安装（联网）

在一台可访问互联网的裸 Linux 主机上，**不需要**预装 k3s，脚本会自动安装。以 root 执行：

```bash
curl -sfL https://docs.neutree.ai/nap/get.sh | sudo sh -
```

脚本会在缺失时安装 k3s，生成全部 secret，自动探测节点 IP，随机生成 admin 密码，完成后打印登录 URL 和凭据。配置落在 `/opt/nap/values.env`；重复执行同一行命令即为原地升级。

常用覆盖方式：

```bash
# 自行指定节点 IP / admin 密码
curl -sfL https://docs.neutree.ai/nap/get.sh \
  | sudo NAP_HOST=192.168.1.10 NAP_ADMIN_PASSWORD=your-password sh -

# 只生成 values.env —— 人工确认或修改后，去掉该 flag 重新执行即开始安装
curl -sfL https://docs.neutree.ai/nap/get.sh \
  | sudo sh -s -- --prepare-only
```

`get.sh --help` 列出全部 flag（`--version=` 固定发布版本、`--dir=` 更换安装目录）。隔离网络节点无法执行一行命令 —— 走下面的手动流程。

## 手动安装

与一行命令等价的分步流程，便于逐项掌控 —— 也是隔离网络节点的安装路径。所有步骤都在节点本机执行。

### 1. 获取部署物料

```bash
git clone https://github.com/neutree-ai/agent-platform
cd agent-platform/self-host
```

如果你已经跑过一行命令（哪怕只是 `--prepare-only`），同样的目录已在 `/opt/nap/self-host` —— 直接在那里操作即可。

<AirgapBlock client:load locale="zh-CN" summary="在联网机器上构建两个物料包，再拷到节点就位">

在任意联网机器上，进入 `self-host/` 目录：

```bash
./offline/save-images.sh                         # → offline/nap-images.tar.gz + 前置 chart
./single-node-prep/package-prep.sh --arch amd64  # → k3s + helm/envsubst/crane + airgap 镜像
```

`save-images.sh` 产出 `offline/nap-images.tar.gz`（全部第一方、第三方镜像及 `registry:2`）以及 `prereqs/` 下的 CNPG / NFS provisioner chart。`package-prep.sh` 打包 k3s 二进制、其 airgap 镜像和 `install.sh` 依赖的 CLI 工具 —— 按目标节点架构选择 `--arch`（`amd64` / `arm64`）。若厂商已交付这些物料包，可跳过此步。

把 `self-host/` 目录（内含 `offline/nap-images.tar.gz`）和 prep 包一起拷到隔离节点，并把 prep 包解压到 **`self-host/` 内部**，使其落在 `self-host/single-node-prep/` —— `preinstall.sh` 会按 `../offline/nap-images.tar.gz` 查找镜像包（解压成 `self-host/` 的同级目录也可以，脚本两种布局都会检查）。

</AirgapBlock>

### 2. 准备 values.env

```bash
cp values.env.single-node.example values.env
./gen-secrets.sh        # fills random JWT / PG / TURN / SANDBOX secrets
vi values.env           # set NAP_HOST + ADMIN_PASSWORD
```

`values.env.single-node.example` 已经内置了单节点默认值，所以你只需要改两处：

- `NAP_HOST` —— 节点对外可达的 IP；pod 和登录入口都使用它
- `ADMIN_PASSWORD` —— 初始 admin 密码

其余所有项（PG 副本数、storage class、NFS 后端）都已按单节点形态预置。

<AirgapBlock client:load locale="zh-CN" summary="NAP_HOST 必须在下一步之前设好">

请在第 3 步**之前**设好 `NAP_HOST` —— `preinstall.sh` 会写入让节点通过 HTTP 访问集群内仓库的 containerd 配置，而它需要该 host。

</AirgapBlock>

### 3. 准备节点（k3s）

安装需要一个可用的 k3s，kubeconfig 位于 `/etc/rancher/k3s/k3s.yaml`（默认路径）。若节点还没有 k3s：

```bash
curl -sfL https://get.k3s.io | sh -
```

<AirgapBlock client:load locale="zh-CN" summary="preinstall.sh 从物料包安装 k3s 并导入镜像，全程离线">

不使用在线 k3s 安装器，改为执行：

```bash
cd single-node-prep
sudo ./preinstall.sh
cd ..
```

它会从物料包安装 k3s，放入 `helm` / `envsubst` / `crane`，把 `nap-images.tar.gz` 导入 k3s containerd（预置 `registry:2` 和第三方镜像），并配置 containerd 将集群内仓库视为纯 HTTP。修改 `values.env` 后可随时重跑。

</AirgapBlock>

### 4. 安装

```bash
./install.sh --profile=single-node
```

`install.sh` 会先拉起集群内 NFS server（`nap-nfs-server` pod，以 `local-path` 为后端），安装 CloudNativePG operator 和 NFS subdir provisioner，渲染并应用 manifest，然后初始化（seed）admin 用户、OAuth client 和 MCP 目录。联网时，所有镜像都从公共 registry 拉取。

<AirgapBlock client:load locale="zh-CN" summary="镜像包的存在会让 install.sh 切换到集群内仓库">

由于 `offline/nap-images.tar.gz` 存在，`install.sh` 会启动集群内 `nap-registry`、用镜像包填充，并把所有工作负载指向它 —— 无需外部仓库、不碰互联网。其余流程与联网时完全一致。

</AirgapBlock>

### 5. 登录

```
http://<NAP_HOST>:30080
admin / <ADMIN_PASSWORD>
```

`30080` 是 `values.env.single-node.example` 内置的 `NAP_NODE_PORT` 默认值。

## 与标准部署的关键差异

下表仅列出与[部署指南](/nap/zh-cn/self-host/)默认值不同的配置；其余沿用标准默认：

| 字段 | 标准默认 | 单节点 |
| --- | --- | --- |
| `DEPLOY_PROFILE` | `multi-node`（隐式） | `single-node` |
| `PG_INSTANCES` | 3 | 1 |
| `PG_STORAGE_CLASS` | 任意 RWO CSI | `local-path` |
| `AGENT_STORAGE_CLASS` | NFS / RWX CSI | `local-path` |
| `NFS_SERVER` / `NFS_PATH` | 外部 NFS | 集群内 NFS pod（`nap-nfs-server`），由 `install.sh` 计算得出 |

这些都已写入 `values.env.single-node.example`，无需手动填写。

:::caution[主机必须启用 NFS 内核模块]
集群内 NFS 使用主机内核：`nap-nfs-server` pod 启动时挂载 `nfsd`，nfs-subdir provisioner 挂载时需要 `nfs` 客户端模块。若模块缺失，`nap-nfs-server` pod 起不来，AFS PVC 会一直 `Pending`。

检查是否已加载：

```bash
lsmod | grep -E 'nfs|nfsd'
```

如果没有任何输出，手动加载两者：

```bash
sudo modprobe nfs
sudo modprobe nfsd
lsmod | grep -E 'nfs|nfsd'   # confirm loaded
```

如果 `modprobe` 报 `module not found`，说明内核缺少 NFS 模块包 —— 先安装它（例如 `apt-get install linux-modules-extra-$(uname -r)`）或换成带 NFS 支持的内核镜像，再重新执行安装。
:::

## 注意事项

- **数据在节点上** —— PVC（含 AFS 共享文件）使用 `local-path`，绑定节点磁盘；重要数据请做外部备份
- **安装器在节点本机运行** —— 单节点 profile 把镜像拉到本地集群
- **升级会重启 pod** —— 镜像滚动期间有短暂窗口。联网时：重跑一行命令，或更新 repo（`git pull`）后重跑 `./install.sh --profile=single-node`

<AirgapBlock client:load locale="zh-CN" summary="隔离网络节点升级需要新的物料包">

在联网机器上按新版本重新构建镜像包（`./offline/save-images.sh`；prep 包通常不变），把新的 `self-host/` 目录连同镜像包拷到节点，重跑 `sudo ./preinstall.sh` 导入新镜像，再执行 `./install.sh --profile=single-node`。

</AirgapBlock>

## 下一步

你现在是一个全新空平台的 admin。两篇短指南带你走到第一个能干活的 Agent：

1. **[配置 API 供应商](/nap/zh-cn/guides/1-setup/)** —— 接入大模型 API，让 Agent 能「思考」。全新安装的供应商列表是空的，创建第一个只需一分钟。
2. **[第一个 Agent](/nap/zh-cn/guides/2-first-agent/)** —— 创建 Workspace 并完成第一次对话，5 分钟以内。

之后可以读[概念](/nap/zh-cn/concepts/overview/)理解各个组成部分，其余指南覆盖触发、多 Agent 协作和规模化运营。