私有化部署架构说明

本文面向客户方技术负责人与现场实施人员，说明 NanoCloud 私有化部署由哪些部分组成、数据如何流转、对客户环境有哪些要求，以及交付、验收与后续维护如何分工。

---

1. 私有化部署解决什么

NanoCloud 把设备管理、数据采集、解析与后续数据处理部署到客户自有的服务器或集群中，业务在客户内网完成，采集数据与业务数据保存在客户环境内。

私有化部署与在线服务同源：业务能力来自同一套平台，私有化额外提供客户现场独立运行所需的基础组件编排、站点配置、离线安装包与运维工具。

先明确三条边界：

• 能力按项目选择。 解析、标注、运营分析等模块可按项目启用或不启用，启用范围在方案中确定。
• 离线可运行，但内网必须连通。 镜像与依赖随交付包提供，不依赖公网；域名解析、网络可达性、存储与设备接入仍需在客户环境内就绪。
• 容量与可用性按项目验证。 节点规格、保留周期与故障影响面取决于实际负载与部署拓扑，由项目的容量评估与验收确认，不使用通用数值代替。

2. 平台组成

图片：飞书图片未同步

2.1 平台能力

能力域	主要职责	启用方式
身份与权限	用户、租户、角色与资源授权，统一登录与鉴权	必选
设备与远程接管	设备注册与状态、控制器管理、标定、固件升级、远程接管	必选
数据采集与质检	采集任务创建与审核、分发与领取、采集回收、质量检验（下称质检）、标签体系	必选
数据处理	采集结果解析、产物生成与异步调度	必选
人工标注	标注任务分配、人工处理、结果回写与复核	可选
运营分析	数据汇总、统计看板与定时统计	可选

2.2 基础组件

组件	在系统中的作用	供给方式
MySQL、PostgreSQL	保存业务数据与元数据	随交付包提供，或按项目外接客户已有实例
Redis	缓存、锁与异步协作	随交付包提供
RustFS（S3 兼容）	保存采集文件与处理产物	随交付包提供，或按项目外接客户已有对象存储
EMQX	设备消息（MQTT）连接与传递	随交付包提供
Kafka、ClickHouse	运营分析链路的消息传递与统计查询	随运营分析模块启用
Fluent Bit	收集运行日志，供排查与巡检使用	随交付包提供

组件版本由交付版本固定。外接客户已有实例需要在方案阶段确认版本、网络与账号权限。

3. 一条数据如何经过平台

以“创建一次采集任务，最终在平台查看结果并完成质检”为例：

阶段	发生了什么	产出
创建任务	运营人员创建采集任务并完成审核	有权限归属的采集任务
分发与领取	任务分发给采集人员与设备	待执行的作业
设备采集	设备执行采集，状态经消息通道上报	设备状态与采集文件
上传与登记	文件写入对象存储，业务记录同步登记	可定位的文件与处理状态
解析处理	异步解析采集结果并生成产物	可供后续使用的解析产物
查看与质检	在平台查看采集结果并给出质检结论	质检结果与问题记录
后续处理	按启用范围进入标注、统计分析	标注结果或统计看板

文件与业务状态分开存放：对象存储保存采集文件与产物，数据库保存任务、权限与处理状态。
“上传完成”“解析完成”“质检通过”是三个不同阶段；平台安装完成后，仍需用真实设备验证整条链路。

4. 访问入口与网络要求

图片：飞书图片未同步

四类入口按协议分开，任何一类不可达都会导致对应业务不可用：

• 业务与管理页面：HTTPS，供业务与运营人员使用，站点域名需在使用侧可解析、证书受客户端信任。
• 业务 API：HTTPS，由网关统一鉴权与路由，按角色控制可访问范围。
• 对象存储：S3 接口。客户端拿到的上传与下载地址必须从设备与客户端所在网络可达，
  该项在现场最常被遗漏，需在方案阶段逐条确认。
• 设备消息：MQTT over TLS，独立通道，不经过 HTTP 反向代理。

需要客户提供或确认的内容：域名与解析、TLS 证书、端口放通范围、各节点时钟同步、运维访问方式
与变更窗口。开发调试端口不等于现场开放端口，实际开放范围以站点方案与安全评审结论为准。

5. 部署形态与环境要求

平台以 Kubernetes 形态交付，按客户现场条件分两种情况：

情况	说明	需要确认的内容
客户已有 Kubernetes 集群	平台作为应用部署到现有集群	集群版本、存储类、入口方式、资源配额、镜像拉取方式
客户没有集群	交付方随包提供运行底座并完成安装	服务器数量与规格、操作系统版本、磁盘与网络规划

关于部署规模：

• 单节点部署适用于试点与小规模站点，节点本身即单点，故障影响面与恢复时间需在方案中写明。
• 多节点部署按项目单独评估。 节点数量增加并不自动等于高可用；控制面、入口与存储的高可用需要单独设计与验证，不在默认交付范围内。
• 容量规划依据实际设备数量、采集量、保留周期与并发处理量确定，由项目的容量评估给出。

离线要求：镜像与依赖随交付包提供，安装过程不需要访问公网；但域名解析、节点之间的网络、存储与设备接入必须在客户环境内可用。

6. 安全与许可

方面	做法
用户访问	登录后按令牌鉴权，令牌有效期受限；按角色与租户控制数据可见范围
设备与外部系统	使用独立凭据，与用户会话隔离
服务间调用	仅在集群内部网络进行，不经公网
传输加密	页面、API 与设备消息使用 TLS；证书由客户提供或使用站点自建证书
凭据保管	数据库、对象存储与消息组件的账号密码由客户环境保管，不随交付包分发
数据归属	业务数据与采集文件全部保存在客户环境内

许可采用离线往返方式：由集群导出环境申请文件，交付方签发授权后带回集群安装。日常业务校验在客户集群内完成，不需要访问外部网络。许可决定可启用的功能范围与配额上限，

7. 交付与验收流程

图片：飞书图片未同步

步骤	主要输入	应交出的结果
01 确认范围与容量	业务范围、环境与网络调查、设备型号与版本、容量需求	冻结的站点方案与版本、环境准备清单
02 构建端准备	冻结的版本与能力组合	离线交付包（含镜像与依赖）
03 等效环境验证	离线交付包	安装与业务链路验证结论、恢复准备检查结果
04 传递离线交付包	验证通过的交付包	按约定介质或内网通道完成传递的记录
05 现场复核与安装	交付包与站点配置	安装记录、部署状态与版本信息
06 真实设备试采	约定的设备、任务与数据样本	分阶段业务验收证据（采集、上传、解析、查看、质检）
07 验收与维护交接	操作手册、备份恢复方案、遗留事项清单	验收记录、维护范围与联系人

每个阶段以约定的输入、输出与验证证据衔接；上一阶段未通过不进入下一阶段。

8. 运维与保障边界

交付方提供安装、状态查询、升级、回滚、备份与恢复的操作手册与工具。需要事先明确的边界：

• 程序回滚不恢复数据。 回滚只把应用版本切回上一版本；数据库与对象存储的数据恢复需要单独的备份方案，并在项目中演练确认。
• 存储快照不等于数据库备份。 两者用途不同，需要并存。
• 恢复能力以演练结果为准。 备份策略、恢复目标时间与数据丢失窗口在方案阶段约定，并通过一次实际演练确认。
• 变更需要窗口。 升级与配置变更需要约定的停机或低峰窗口以及回退方案。

责任分工建议如下，具体以合同与维护协议为准：

事项	交付方	客户
软件包、安装与升级工具、操作手册	提供	—
服务器、操作系统、网络、域名、证书	提出要求并核验	提供与维护
现场安装与业务验证	执行或指导	配合提供设备、账号与场地
日常巡检与告警处理	按维护协议范围	按维护协议范围
备份执行与介质保管	提供方案与工具	执行与保管
数据内容与账号权限管理	—	负责

9. 客户准备清单

类别	需要准备	确认标准
服务器	数量、CPU/内存/磁盘、操作系统版本	与方案中的规格一致，磁盘独立于系统盘
网络	节点互通、对外访问端口、防火墙策略	按站点方案放通，且仅开放必要端口
域名与证书	业务、管理、API 与对象存储域名，TLS 证书	在使用侧可解析；证书在客户端受信任
存储	数据盘容量与扩容方式	满足容量评估结论并预留增长空间
设备	参与验收的设备型号、数量与固件版本	与方案一致，且可接入站点网络
人员	现场配合人员、运维接口人	明确到人，覆盖安装与验收窗口
时间	安装窗口、验收窗口、变更窗口	书面确认

10. 术语

术语	含义
站点	一次私有化部署所对应的客户环境
采集任务	一次数据采集的工作单元，包含范围、要求与验收条件
采集回收	设备完成采集后，数据与元信息进入平台的过程
解析	把原始采集文件转换为可供后续使用的结构化产物
派生文件	由原始采集文件加工得到的小文件，便于按需检索与下载
控制器	随设备部署、负责本地采集控制与数据上报的计算单元
质检	对采集结果进行人工或规则判定，决定是否合格
对象存储	保存文件的存储服务，通过 S3 接口上传与下载
MQTT	设备消息协议，用于设备状态、任务下发与回执
离线交付包	包含镜像与依赖、可在无公网环境安装的交付物
许可	决定站点可启用功能范围与配额的授权文件，现场离线校验