单节点 k3s 快速部署

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

适用场景

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

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

不提供的能力

维度	单节点 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

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. 安装

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

与标准部署的关键差异

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

字段	标准默认	单节点
`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 支持的内核镜像，再重新执行安装。

注意事项

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