ONES 外置 Kubernetes 集群部署指南

本文档说明如何在已有的外部 Kubernetes 集群上部署 ONES 系统，包括前置要求、权限配置、存储准备、镜像+镜像仓库对接以及完整的部署流程。

本文档默认读者已具备 Kubernetes 基础运维能力，能够使用 kubectl 查询节点、Pod、Service、PVC、StorageClass 和事件信息等基本操作。

本文档是基于ONES已有的实践经验汇总而成，可能客户提供的 Kubernetes 集群在规范标准、语义理解上与ONES有所不同，为避免歧义，需客户提供如下规范待双方沟通确认：

类别	需要确认的内容
集群规范	K8s 版本、CCE/ACK/EKS/自建、节点规格、节点 OS、容器运行时
网络规范	VPC、子网、DNS、Ingress、SLB/ELB、域名、证书、出口访问、东西向访问
存储规范	是否允许动态 PVC、是否只允许静态 PV、NFS/云硬盘/SFS 使用原则、回收策略
镜像规范	镜像仓库地址、镜像同步方式、镜像扫描、安全准入
安全规范	namespace、RBAC、PodSecurity、root 权限、特权容器、hostPath、NetworkPolicy
运维规范	日志、监控、告警、备份、巡检、变更流程
高可用规范	副本数、反亲和、PDB、节点池隔离、故障恢复要求
资源规范	requests/limits、配额、命名规范、标签规范
交付规范	谁创建资源、谁审批、谁有权限、交付边界

---

1. 概述

1.1 适用场景

• 已有生产级 Kubernetes 集群（如 K8s、K3s 等）
• 需要将 ONES 部署到现有集群中，而非使用安装器内置的 K3s
• 希望复用现有的基础设施（存储、网络、镜像仓库等）

1.2 架构说明

说明：ONES 会在集群中创建多个 namespace：

• ones-installer：安装器资源
• ones-system：系统组件
• ones：业务组件

因此需要 Cluster Admin 权限。

---

2. 集群要求

2.1 基础要求

要求项	说明	验证命令
Kubernetes 版本	v1.22 - v1.35	kubectl version
集群状态	Healthy，所有节点 Ready	kubectl get nodes
节点操作系统	计划承载 ONES 的节点需为 Linux 64 位节点	kubectl get nodes -o wide
节点架构	计划承载 ONES 的节点 CPU 架构需保持一致，并与安装包/镜像架构一致（如 amd64 或 arm64）	kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{\"\\t\"}{.status.nodeInfo.architecture}{\"\\n\"}{end}'
kubectl 访问	具有集群管理权限	kubectl auth can-i '*' '*'
kubeconfig	可访问集群的 kubeconfig 文件	确保 $KUBECONFIG 或 ~/.kube/config 有效

部署前必须验证 kubectl 连接状态：

# 验证 kubectl 连接
kubectl cluster-info

# 验证集群状态
kubectl get nodes

# 验证是否有 cluster-admin 权限
kubectl auth can-i '*' '*' --all-namespaces
# 或验证关键权限
kubectl auth can-i create namespaces
kubectl auth can-i create deployments --all-namespaces
kubectl auth can-i create persistentvolumeclaims --all-namespaces

2.2 权限要求

ONES 安装器需要 Cluster Admin 权限，因为会在集群中创建和管理多个 namespace：

• ones-installer：安装器资源
• ones-system：系统组件
• ones：业务组件
• ones-telemetry：可观测组件

所需权限包括：

• 创建/管理多个 Namespace
• 部署工作负载（Deployment、StatefulSet、DaemonSet、Pod 等）
• 配置网络（Service、Ingress、NetworkPolicy）
• 管理存储（PV、PVC、StorageClass）
• 配置 RBAC（ServiceAccount、Role、RoleBinding）

2.3 存储要求

2.3.1 StorageClass 类型

ONES 需要两种类型的 StorageClass：

类型	用途	访问模式	回收策略
ReadWriteOnce (RWO)	数据库、单副本存储	RWO	Retain（推荐）
ReadWriteMany (RWX)	共享文件存储	RWX	Retain（推荐）

重要：回收策略选择

• Retain（推荐）：PVC 删除后，PV 和数据保留，避免数据丢失
• Delete：PVC 删除后，PV 和数据会被自动删除，存在数据丢失风险

建议：

• 生产环境务必使用 Retain 回收策略的 StorageClass
• 如果集群只有 Delete 策略的 StorageClass，建议先创建 Retain 策略的 StorageClass

检查现有 StorageClass：

kubectl get storageclass

必须验证 StorageClass 可实际创建 PVC：

仅看到 StorageClass 名称并不能说明集群满足要求，还需分别验证 RWO 和 RWX 的动态供给能力。

# 创建测试 namespace
kubectl create namespace ones-precheck

# 验证 RWO StorageClass（将 <your-rwo-storageclass> 替换为实际名称）
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: rwo-check
  namespace: ones-precheck
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: <your-rwo-storageclass>
EOF

# 验证 RWX StorageClass（将 <your-rwx-storageclass> 替换为实际名称）
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: rwx-check
  namespace: ones-precheck
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 1Gi
  storageClassName: <your-rwx-storageclass>
EOF

# 观察 PVC 是否成功绑定到 Bound
kubectl get pvc -n ones-precheck -w

# 验证完成后清理
kubectl delete namespace ones-precheck

说明：

• 不同环境中的 StorageClass 名称可能不同（如云厂商默认块存储类、文件存储类等）
• 用户需要根据自己集群的实际情况选择合适的 StorageClass
• 确保 StorageClass 的 provisioner 正常工作
• 如 PVC 长时间处于 Pending，说明存储类、底层存储或 CSI provisioner 仍未满足部署要求

2.3.2 生产资源规格建议

存储资源规格：

存储类型	最小容量	用途
S3 兼容对象存储	> 100G	业务附件存储
RWX 共享存储	≥ 100G	共享数据交换
RWO 块存储	总大小 > 500G	数据库、中间件等数据

说明：

• 对象存储用于存储业务附件、图片等文件
• RWX 共享存储用于跨节点数据共享和交换（如 NFS、CephFS 等）
• RWO 块存储用于数据库、中间件等需要独占访问的组件

2.3.3 配置 StorageClass

部署时通过环境变量指定：

# RWO 存储类（根据实际集群情况填写）
STORAGECLASS_NAME_FOR_READ_WRITE_ONCE=<your-rwo-storageclass>
STORAGECLASS_NAME_FOR_READ_WRITE_ONCE_WITH_RETAIN=<your-rwo-retain-storageclass>

# RWX 存储类（根据实际集群情况填写）
STORAGECLASS_NAME_FOR_READ_WRITE_MANY=<your-rwx-storageclass>
STORAGECLASS_NAME_FOR_READ_WRITE_MANY_WITH_RETAIN=<your-rwx-retain-storageclass>

示例（根据实际集群调整）：

# 示例 1：通用命名
STORAGECLASS_NAME_FOR_READ_WRITE_ONCE=standard
STORAGECLASS_NAME_FOR_READ_WRITE_MANY=nfs-storage

# 示例 2：AWS EKS
STORAGECLASS_NAME_FOR_READ_WRITE_ONCE=gp2
STORAGECLASS_NAME_FOR_READ_WRITE_MANY=efs

2.3.4 常见云厂商资源示例

云厂商	RWO 示例	RWX 示例	对象存储
华为云 CCE	EVS / csi-disk	SFS / SFS Turbo	OBS
阿里云 ACK	ESSD / disk	NAS	OSS
AWS EKS	EBS	EFS	S3

2.4 网络要求

2.4.1 集群网络能力

外置 Kubernetes 集群必须具备以下网络能力：

• 支持 Service 的 NodePort 类型：ONES 安装和安装后的默认对外访问方式均依赖 NodePort
• 允许访问节点 IP + NodePort：客户端、前置负载均衡或反向代理需要能够访问集群节点 IP 对应的 NodePort 端口
• 允许使用集群的 NodePort 端口范围：默认情况下 Kubernetes 的 NodePort 范围通常为 30000-32767，如集群修改了该范围，需确保下文涉及的端口已包含在实际可用范围内

集群节点之间网络要求：

• 延迟：< 50ms
• 带宽：> 100M
• 丢包率：< 0.1%
• 抖动：< 10ms

部署要求：

• 集群服务器须位于同一机房、同一交换机、同一网段
• 若部署于虚拟机，底层宿主机需满足相同条件
• 避免跨机房或跨网段部署集群，减少网络延迟和故障风险
• 如果是云主机，可采用按流量计费的带宽模式

2.4.2 端口要求

以下端口均通过 Kubernetes NodePort Service 对外暴露，不是额外独立的集群网络能力要求。

部署过程中需要通过 NodePort 暴露的端口：

• 30011：安装器 Web 界面（installer-web）
• 30012：安装器 API（installer-api）

安装完成后需要通过 NodePort 暴露的端口：

• 30011：业务访问端口（默认，可调整）

可选端口：

• 80/443：如通过 Ingress、负载均衡或反向代理对外提供标准 HTTP/HTTPS 访问，可按需使用
• 31380：监控端口（按需通过 NodePort 暴露）

说明：

• 文档中提到的 30011、30012、31380 等端口，均指 Kubernetes Service 的 NodePort
• 如果集群、云防火墙、安全组或前置网关限制了对应 NodePort 访问，需要提前放通
• 如使用负载均衡、Nginx 或其他网关统一入口，仍需保证其后端能够访问节点 IP 和对应 NodePort

验证端口：

kubectl get svc -A

2.4.3 域名要求

如需使用域名访问，需提前准备：

• 提前申请域名

• 对接企业微信场景：必须使用域名

2.4.4 SSL 证书要求

如需使用 HTTPS 访问，需提前准备 SSL 证书：

• 证书需来自可信 CA
• 证书链完整
• 匹配域名且未过期
• 准备 key 文件和 crt 文件

2.4.5 前置网关

提前确认是否需要以下前置网关设备：

• 防火墙
• Nginx 反向代理
• 负载均衡（LB）

这些设备会影响服务访问方式。如需统一入口，通常由这些设备对外提供访问地址，并将流量转发到 Kubernetes 节点 IP 对应的 NodePort 端口。

2.4.6 NTP 服务器

提供可用的 NTP 服务器，用于配置时间同步服务：

• 确保服务器的时间和时区正确
• 所有节点时间同步

2.4.7 DNS 要求

• CoreDNS 或 kube-dns 正常运行
• Pod 内部能够正常解析集群 Service 域名与外部依赖域名

2.4.8 外部依赖连通性

计划承载 ONES 的节点或 Pod，需要根据实际部署方式具备以下网络连通性：

• 镜像仓库：能够访问 DEST_IMAGE_REGISTRY
• 对象存储：如使用 S3 兼容对象存储，能够访问对象存储 Endpoint
• NFS/共享存储：如使用 RWX 共享存储，所有相关节点均可访问底层存储服务

如集群启用了严格的防火墙、安全组、NetworkPolicy 或出口代理，请提前验证这些依赖的连通性。

2.5 节点规划

** 重要建议**：

建议为 ONES 部署独立分配集群节点，原因如下：

• ONES 包含 DaemonSet 类型资源，会部署到集群所有节点
• 建议这批节点资源仅供 ONES 使用，或仅分配给 ONES 独享可见的节点资源
• 目前 ONES 编排层面尚未全面支持基于 Label 的调度策略，建议在集群层面进行节点隔离
• 如目标节点存在不可兼容的污点（Taint）、资源配额或准入限制，需在部署前提前处理，否则可能出现 Pod 无法调度或资源创建失败

注意：在云 Kubernetes 环境中，单节点可支持的 Pod 数量受节点规格限制。ONES 集群默认基础服务 Pod 数量约为 180 个左右，后续每安装一个插件通常会新增 1 个 Pod。因此，在规划集群节点规格时，应综合考虑基础服务 Pod 数量、插件数量以及未来扩展空间，选择满足 Pod 承载能力要求的节点规格，避免因节点 Pod 容量不足影响服务部署和扩容。

2.6 部署前检查清单

满足以下条件后，可基本判断当前 Kubernetes 集群满足 ONES 外置部署要求：

检查项	通过标准
Kubernetes 版本	位于 v1.22 - v1.32 范围内
节点状态	计划承载 ONES 的节点均为 Ready
节点架构	目标节点架构一致，且与所选安装包/镜像架构一致
权限	当前 kubeconfig 具备 cluster-admin 级别能力
RWO 存储	至少 1 个 RWO StorageClass 可成功创建并绑定 PVC
RWX 存储	至少 1 个 RWX StorageClass 可成功创建并绑定 PVC
NodePort 能力	集群允许创建并访问 NodePort Service
DNS	CoreDNS/kube-dns 正常，Pod 能解析集群内外域名
外部依赖连通性	能访问镜像仓库；如启用对象存储/NFS，也已验证连通
节点资源	至少 3 个符合建议规格的 Worker 节点可供 ONES 使用
调度限制	目标节点不存在会阻塞部署的污点、配额或准入策略

如以上任一项不满足，建议先补齐集群条件，再执行部署。

---

3. 镜像仓库配置

# 镜像仓库地址
DEST_IMAGE_REGISTRY=registry.example.com
DEST_IMAGE_USER=admin
DEST_IMAGE_PASSWD=password

# 镜像同步模式
INSTALL_IMAGE_SYNC_MODE=auto  # auto | syncer | skip

---

4. 部署流程

4.1 离线部署（推荐）

步骤 1：下载离线安装包（在有网络的机器上执行）

# 下载工具脚本
curl -O https://packages.ones.cn/release/latest/quickstart.sh

# 查看支持的版本
bash quickstart.sh --list-versions

# 下载指定版本的离线包
bash quickstart.sh --version v6.94.0 --download

# 下载完成后会提示安装包路径，如：ones_offline_pkg_v6.94.0_amd64.tar.gz

步骤 2：传输到目标服务器（离线环境）

# 将 quickstart.sh 和离线包复制到目标服务器
scp quickstart.sh ones_offline_pkg_v6.94.0_amd64.tar.gz user@target-server:/data/install/

步骤 3：执行部署

# 设置环境变量
export DEPLOY_MODE=external
export DEST_IMAGE_REGISTRY=registry.example.com
export DEST_IMAGE_USER=admin
export DEST_IMAGE_PASSWD=password
export INSTALLER_VOLUME_MODE=pvc
export INSTALLER_VOLUME_STORAGE_CLASS=<your-rwo-storageclass>
export STORAGECLASS_NAME_FOR_READ_WRITE_ONCE=<your-rwo-storageclass>
export STORAGECLASS_NAME_FOR_READ_WRITE_MANY=<your-rwx-storageclass>

# 执行安装
bash quickstart.sh --offline-file /data/install/ones_offline_pkg_v6.94.0_amd64.tar.gz

4.2 在线部署

DEPLOY_MODE=external \
DEST_IMAGE_REGISTRY=registry.example.com \
DEST_IMAGE_USER=admin \
DEST_IMAGE_PASSWD=password \
curl -sfL https://packages.ones.cn/release/latest/quickstart.sh | bash -

4.3 仅同步镜像

# 下载离线包（参考 4.1 步骤1）

# 仅同步镜像到镜像仓库
SYNC_ONLY=true \
DEST_IMAGE_REGISTRY=registry.example.com \
DEST_IMAGE_USER=admin \
DEST_IMAGE_PASSWD=password \
bash quickstart.sh --offline-file /data/install/ones_offline_pkg_v6.94.0_amd64.tar.gz

---

5. 初始化 ONES

5.1 验证安装器部署

# 检查 namespace
kubectl get namespaces | grep ones

5.2 进入安装器并初始化

# 拷贝配置文件
kubectl  -n ones-installer  cp /data/ones/ones-installer-pkg/config  `kubectl get pod -A|grep -i installer-api | awk '{print $2}' `:/data/ones/ones-ai-k8s/

# 进入 ONES 操作终端
ones-ai-k8s.sh

# 执行初始化配置
make init-config

按照提示完成以下配置：

1. 配置时区、语言：设置初始团队时区与语言
2. 创建团队：创建第一个团队并设置团队名称
3. 创建团队负责人：创建系统第一个用户（具有最高权限），请确保填写的邮箱地址能正常接收邮件

5.3 配置存储

编辑配置文件：

vi config/private.yaml

配置示例：

# StorageClass 配置（根据实际集群填写）
storageClassNameForReadWriteOnce: <your-rwo-storageclass>
storageClassNameForReadWriteOnceWithRetain: <your-rwo-retain-storageclass>
storageClassNameForReadWriteMany: <your-rwx-storageclass>
storageClassNameForReadWriteManyWithRetain: <your-rwx-retain-storageclass>

# 停用本地存储，使用 StorageClass provisioner 独立管理
localstorageForMysqlEnable: "false"
localstorageForElasticsearchEnable: "false"
localstorageForKafkaEnable: "false"
localstorageForZookeeperEnable: "false"
localstorageForClickhouseEnable: "false"
localstorageForPrometheusEnable: "false"
localstorageForTidbEnable: "false"
localstorageForMinioEnable: "false"
localstorageForApisixEtcdEnable: "false"
localstorageForDM8Enable: "false"
localstorageForOnesAipQdrantEnable: "false"
localstorageForOnesBackupInternalMinioEnable: "false"
localstorageForOnesAipEnable: "false"
localstorageForS3ProxyEnable: "false"
localstorageForOnesLoggingEnable: "false"
localstorageForOnesTelemetryCollectorEnable: "false"

# 对象存储配置（可选）
dataS3Endpoint: "https://<your-s3-endpoint>"
dataS3AccessKeyID: "<your-access-key-id>"
dataS3SecretAccessKey: "<your-access-key-secret>"
dataS3Region: "<your-s3-region>"
dataS3ForcePathStyle: false
dataS3PublicBucket: "ones-public-files"
dataS3PrivateBucket: "ones-private-files"
dataS3TmpBucket: "ones-tmp-files"

5.4 部署 ONES 服务

bash script/ones/deploy-ones.sh

首次启动过程将耗时 30 分钟不等（视实际硬件而定）。请监控终端以跟踪进度，一旦所有组件都运行起来，ONES 即可使用。

5.5 验证部署

# 检查所有组件状态
kubectl get pods -n ones

# 检查日志
kubectl logs -f deployment/installer-api -n ones-installer

5.6 登录 ONES

按照提示的访问方式，打开登录页面：

http://<node-ip>:30011

其中 <node-ip>:30011 表示某个可访问的 Kubernetes 节点 IP 与业务 Service 的 NodePort。如已配置负载均衡、反向代理或域名，也可直接使用对应的统一访问地址。

输入初始化过程设置的「团队负责人」账号密码登录系统。

---

6. 常见问题

6.1 镜像拉取失败

现象：Pod 状态为 ImagePullBackOff

解决：

# 检查镜像仓库 secret
kubectl get secret -n ones-system | grep registry

# 手动创建 secret
kubectl create secret docker-registry ones-registry-secret \
  --namespace=ones-system \
  --docker-server=registry.example.com \
  --docker-username=admin \
  --docker-password=password

# 验证镜像仓库访问
curl -u admin:password https://registry.example.com/v2/_catalog

6.2 PVC 绑定失败

现象：PVC 状态为 Pending

解决：

kubectl describe pvc <pvc-name> -n ones-system
kubectl get storageclass
kubectl get pv

6.3 权限不足

现象：部署时报错 Forbidden

解决：

# 验证权限
kubectl auth can-i '*' '*' --all-namespaces

# 授予 cluster-admin 权限
kubectl create clusterrolebinding ones-admin \
  --clusterrole=cluster-admin \
  --user=<your-user>

---

7. 最佳实践

7.1 节点规划（重要）

实施方案：

方案一：独立集群（推荐）

为 ONES 部署独立的 Kubernetes 集群，完全隔离资源。

优点：

-- 资源完全隔离

-- DaemonSet 不会跑到客户业务节点

-- 升级、重启、排障不会影响其他系统

-- 权限、网络、存储、监控边界清晰

-- 最符合生产交付和责任划分

缺点：

-- 成本更高

-- 客户需要多维护一个集群

方案二：独立节点池

在集群中划分独立的节点池，仅用于 ONES 工作负载：

# 为 ONES 专用节点打标签（便于识别和管理，不能单独作为强隔离手段。）
kubectl label nodes node1 node2 node3 dedicated=ones

# 查看节点
kubectl get nodes -l dedicated=ones

同时，对非 ONES 节点加 Taint，让 ONES Pod 无法调度过去。

8 生产环境建议

• 镜像仓库：使用企业级镜像仓库，若有HA需求满足HA需满足故障转移能力
• 存储：数据库使用高性能 SSD，文件使用 NFS 或 S3 兼容对象存储
• 网络：建议通过 Ingress、负载均衡器（LB）或反向代理对外提供统一入口，并将流量转发到业务 Service 对应的 NodePort（默认 30011）以实现负载均衡
• 监控：完成部署 Prometheus + Grafana，配置告警
• 节点：提供独立集群
• 权限：提供 Cluster Admin 权限