单节点 k3s 快速部署

在单节点 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 或横向扩展时，走生产部署，其中也覆盖安装进已有 Kubernetes 集群。

一行命令安装（联网）

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

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

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

常用覆盖方式：

# 自行指定节点 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. 获取部署物料

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

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

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

./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/ 的同级目录也可以，脚本两种布局都会检查）。

2. 准备 values.env

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 后端）都已按单节点形态预置。

3. 准备节点（k3s）

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

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

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

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

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

4. 安装

./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 拉取。

5. 登录

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

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

与标准部署的关键差异

下表仅列出与部署指南默认值不同的配置；其余沿用标准默认：

字段	标准默认	单节点
`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，无需手动填写。

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

检查是否已加载：

lsmod | grep -E 'nfs|nfsd'

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

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

下一步

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

配置 API 供应商 —— 接入大模型 API，让 Agent 能「思考」。全新安装的供应商列表是空的，创建第一个只需一分钟。
第一个 Agent —— 创建 Workspace 并完成第一次对话，5 分钟以内。

之后可以读概念理解各个组成部分，其余指南覆盖触发、多 Agent 协作和规模化运营。