K3s轻量集群住宅机器部署AI中转服务

如果你手头有几台闲置的家里电脑或迷你主机，想跑一个AI中转服务（比如统一管理多个大模型API的One API），又不想折腾完整的Kubernetes，那K3s就是最适合你的选择。
本文从零开始，一步步带你在住宅机器上搭起K3s集群并部署AI中转服务。

为什么家庭服务器推荐K3s而不是完整Kubernetes

K3s是经过CNCF认证的轻量级Kubernetes发行版，二进制文件不到100MB，内存占用仅为512MB就能跑。
对家庭服务器来说，它把etcd换成了SQLite（也可以换成外部数据库），去掉了许多云原生场景用不到的组件，安装和运维都简单不少。
用它跑AI中转服务，你可以轻松管理多个副本、自动重启、负载均衡，而且迁移或扩容都非常方便。

部署前需要准备哪些软硬件

• 至少两台x86或ARM架构的Linux机器（推荐Ubuntu 22.04 LTS或Debian 11），一台做主节点（Master），其他做工作节点（Agent）。如果只有一台机器，也可以单节点运行。
• 每台机器需要静态内网IP，或者通过路由器DHCP分配固定IP。
• 建议每台机器至少有2GB内存、20GB磁盘空间。
• 如果你打算从外网访问AI中转服务，需要有一个公网IP（或使用DDNS）和域名，以及开放相应端口。
• 提前安装好curl、openssl等基础工具。

在Linux上快速搭建K3s主节点和工作节点

在主节点上执行以下命令（要用root或sudo）：

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

安装完成后，K3s会自动启动并生成一个token，用来让工作节点加入集群。
查看token：

sudo cat /var/lib/rancher/k3s/server/node-token

记下这个token和主节点的内网IP（比如192.168.1.10）。

然后到每一台工作节点上执行加入命令：

curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.10:6443 K3S_TOKEN=刚刚记下的token sh -

等待几秒后，在主节点上运行 kubectl get nodes，应该能看到所有节点状态为Ready。

注意：如果工作节点和主节点不在同一子网，需要确保6443端口可达，并且主节点防火墙放行该端口。

使用Helm部署AI中转服务（以One API为例）

K3s默认没有安装Helm，需要手动装一下：

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

接着添加One API的Helm仓库（这里用一个社区维护的chart，你也可以直接使用Docker镜像部署）：

helm repo add oneapi https://charts.one-api.com
helm repo update

创建一个命名空间并将部署文件放到 oneapi-values.yaml 中：

replicaCount: 2
service:
  type: NodePort
  port: 3000
persistence:
  enabled: true
  size: 2Gi

执行安装：

helm install ai-proxy oneapi/one-api -n ai-proxy --create-namespace -f oneapi-values.yaml

等待Pod启动：

kubectl get pods -n ai-proxy -w

看到所有Pod都处于Running状态后，可以通过 kubectl get svc -n ai-proxy 获取NodePort暴露的端口（默认为3000，但会被映射到集群节点的某个随机端口）。
你可以用 192.168.1.10:NodePort 访问UI，默认账号 root、密码 123456，首次登录后立即修改密码。

开放外网访问并配置SSL证书

如果你希望从公网访问AI中转服务，建议在K3s集群前面加一个Nginx反向代理或使用K3s自带的Traefik Ingress Controller。
K3s安装时默认启用了Traefik，可以用Ingress来暴露服务。
创建一个 ingress.yaml：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ai-proxy-ingress
  namespace: ai-proxy
  annotations:
    kubernetes.io/ingress.class: traefik
spec:
  rules:
  - host: ai.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: one-api
            port:
              number: 3000

然后应用它：

kubectl apply -f ingress.yaml

再配上SSL证书，可以用cert-manager自动申请Let's Encrypt证书，或者手动上传证书到K3s的Secret，这里不再展开。

常见问题与避坑

• 节点加入失败：检查防火墙是否放行了6443端口，以及工作节点是否可以解析主节点主机名。建议直接用IP。
• Token过期：K3s的node-token不会过期，但如果重新安装了主节点，token会变。
• Pod卡在Pending：多半是因为资源不足（CPU/内存），或PV没有绑定。One API默认使用PVC，如果K3s没有配置存储类，可以改用emptyDir或hostPath。
• 外网访问慢：家庭宽带上行带宽有限，建议限制并发连接数或使用CDN中转。
• 忘记录入token：可以在工作节点上重新执行安装命令时带上正确的token。

检查服务是否正常

在所有节点就绪、Pod运行后，用浏览器打开 http://你的主节点IP:节点端口，应该看到One API的登录页面。
登录后添加一个AI厂商的API Key，然后用 curl 测试一下：

curl http://192.168.1.10:NodePort/v1/models -H "Authorization: Bearer 你的token"

如果能返回模型列表，说明AI中转服务已经成功跑在K3s集群上了。

如果你在部署过程中遇到集群启动失败或服务无法访问的问题，建议先回头检查节点状态和Pod日志（kubectl logs pod名称 -n ai-proxy），大部分问题都出在网络或资源不足上。
按照本文的步骤操作，你的家庭K3s集群就能稳定运行AI中转服务了。