---
title: 单节点 k3s 快速部署
description: 在单个 k3s 节点上拉起 Neutree Agent Platform —— 面向资源受限的内部测试与演示，无高可用。镜像从公共 registry 拉取。
---

在单节点 k3s 集群上安装 Neutree Agent Platform，所有镜像都直接从公共 registry 拉取。**仅适用于**资源受限场景下的快速试用、内部演示和 PoC 验证；**请勿**用于生产环境 —— 控制面、数据和存储全部塌缩到一台机器上，节点宕机即全停。

## 适用场景

- **PoC / 演示** —— 给干系人一个能快速访问的实例，验证平台能力
- **内部测试 / 集成** —— 团队需要一个稳定的共享环境，但不想搭多节点 k8s
- **资源受限部署** —— 只有一台机器可用，但仍想跑通完整流程

如果是真实的生产需求（多用户、SLA、容灾），请走标准[部署指南](/self-host/)中的多节点路径。

## 不提供的能力

| 维度 | 单节点 k3s | 多节点标准部署 |
| --- | --- | --- |
| 控制面 HA | 无 —— 单 k3s server，节点宕机即全停 | 有 —— 多 master |
| Postgres HA | 无 —— 单实例（CNPG `instances: 1`） | 有 —— 3 副本 + 同步复制 |
| 共享存储 | 无 —— 集群内 NFS pod，节点宕机即不可用 | 有 —— 外部 NFS / 企业级 CSI |
| Workspace 容器磁盘 | RWO `local-path`，绑定到节点 | RWX CSI，可跨节点迁移 |
| 横向扩展 | 无 —— 加节点意味着重装 | 有 —— 添加 worker |
| 滚动升级 | 镜像滚动期间短暂中断 | 多副本下无缝升级 |

推荐配置：**8 vCPU / 32 GB / 200 GB 磁盘**，约可支撑 **10 个并发 workspace**。低于此配置，workspace 容易因 CPU / 内存争用被 OOMKilled；高于此则需要更多机器，走多节点路径。

## 联网单节点

一个直接从公共 registry 拉取所有镜像的单节点 k3s —— 与完整 profile 一致，只是把 `PG_INSTANCES=1`，并用集群内 NFS server 提供 RWX 存储（单节点没有外部 NFS）。**没有**集群内 registry，也**没有**离线 tarball；节点必须能访问公共 registry（`ghcr.io` / `docker.io` / `registry.k8s.io`）。

> 对于完全隔离的单节点站点，请使用独立的离线安装器，它附带镜像 tarball、k3s 二进制以及主机预处理步骤。

## 部署

在一台已就绪的 k3s 主机上执行，其 kubeconfig 位于 `/etc/rancher/k3s/k3s.yaml`（单节点示例中的默认路径）。

### 1. 准备 values.env

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

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

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

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

### 2. 安装

```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 拉取。

### 3. 登录

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

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

下表仅列出与[部署指南](/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 支持的内核镜像，再重新执行安装。
:::

## 注意事项

- **确实没有 HA** —— 节点重启、内核 panic、磁盘卡顿都是用户可感知的中断。演示前先确认机器健康
- **`local-path` 数据绑定到节点** —— 删除节点或重装系统盘会丢失所有 PVC 数据。备份需依赖快照 / 应用层导出
- **AFS 跑在集群内 NFS pod 上** —— 其数据位于 `local-path` PVC，绑定到节点磁盘。机器损坏或磁盘故障，所有 agent 共享文件随之丢失
- **`install.sh` 必须在节点上运行** —— 单节点 profile 把镜像拉到本地集群；operator 无法从另一台机器运行
- **升级走滚动重启** —— cp / browser / sandbox 在镜像更新期间有短暂不可用窗口（多节点部署没有这个窗口）。升级流程与[标准升级](/self-host/#upgrade)一致：重新执行 `./install.sh --profile=single-node`
- **一旦出现生产需求** —— 不要试图把单节点打补丁改成 HA；迁移到多节点。运维心智上的差异比配置上的差异更大