软硬件环境需求说明书
飞书 Wiki 同步子文档，revision 2。
本说明以 40 台采集设备并发为规划示例；最终规格须根据设备型号、每日采集时长、数据保留周期和专项压测结果确认。
**存储测算适用范围：**当前文档中的容量示例基于第 5 节所述 RD001 无本体设备、3 路摄像头 teleop 采集数据。其他设备类型的存储测算后续另行补充。
**CPU 配置待验证建议：**针对有本体解析的 CPU 需求，本次评审建议将承担解析任务的节点 CPU 按现有配置约 2 倍进行规划。该建议尚未经专项压测验证；第 2～4 节列出的有本体解析增强规格均属于这一规划建议，最终规格及可支持的并发量需根据具体设备型号和专项压测结果确认。
部署模式说明
| 部署模式 | 物理服务器 | 节点拓扑 | 适用场景与可用性 |
|---|---|---|---|
| 单物理机虚拟化 | 1 台 | 至少 3 台 VM，建议 1 server + 2 agent | 适用于试点、离线部署和压测；宿主机仍是单点，不属于物理高可用。 |
| 多物理节点集群 | 至少 3 台 | 1 server + 2 个及以上 agent | 工作负载可跨物理节点调度和扩容，但控制面只有 1 个 server 时不属于控制面 HA。 |
| 生产 HA 集群 | 至少 3 台 | 3 server/control-plane + N agent；最小可采用 3 台融合节点 | 3 个 server 分布在不同物理机并组成 etcd 多数派，可容忍单个控制面节点故障；状态组件和存储仍需分别实现高可用。 |
两节点部署限制
- 当前项目如果仅配置 2 台物理服务器，可以用于试点、功能验证或过渡部署，但不得定义为生产高可用架构。
- 两台物理服务器无法为 embedded etcd 提供可靠的多数派容错。任一物理节点故障，都可能导致控制面不可用、业务计算能力显著下降或存储副本不足。
- 生产控制面高可用应至少配置 3 台独立物理服务器，并在不同物理故障域上部署 3 个
server/control-plane节点，组成 etcd 多数派。控制面节点数量应采用奇数，通常为 3 个或 5 个；agent/worker节点数量不受奇数限制。 1 server/control-plane + 2 agent/worker虽然共有 3 个节点，但仍然只有一个控制节点，因此不属于控制面高可用
**CPU 口径：**服务器 CPU 数量均指整机物理核心总数，不是线程数，也不等同于 CPU 插槽或处理器颗数；第 7 节外部数据库规格明确使用 vCPU。虚拟化场景应为宿主机保留至少 20% CPU 调度余量和 24 GB 内存。
单物理机虚拟化配置
| 项目 | 建议规格 | 说明 |
|---|---|---|
| 数量 | 物理服务器 1 台 | 塔式或机架式均可；当前方案采用塔式服务器。 |
| 虚拟化 | KVM 兼容平台，如 Proxmox VE | 开启 AMD-V/VT-x；至少创建 1 个 server/control-plane VM 和 2 个 agent/worker VM。 |
| CPU—无本体解析基线 | x86_64，48 个物理核心以上 | 建议 48 核 / 96 线程；数据解析、虚拟机和压测共享计算资源。 |
| CPU—有本体解析 | x86_64，不低于96个物理核心 | 相对当前基线提升至约2倍，最终以具体设备型号压测为准 |
| 内存 | 192 GB ECC 以上 | 宿主机至少预留 24 GB；不得将全部内存分配给虚拟机。 |
| 系统盘 | 2 × 960 GB企业级SSD，RAID1 | 用于虚拟化平台、操作系统、程序及必要系统日志 |
| Infra数据盘 | 独立企业级SSD/NVMe，建议RAID1 | 用于镜像仓库、容器缓存、平台日志、etcd及基础组件数据 |
| 数据库盘 | 独立企业级SSD/NVMe，建议RAID1 | 仅在本地部署数据库时需要，不得与系统盘共用 |
| 业务数据盘 | 按第5节容量公式核算 | 用于原始数据、解析数据和业务文件，应与系统盘及Infra盘分离 |
| 备份存储 | 独立存储设备或独立故障域 | 不得将同一节点上的另一目录视为有效备份 |
| 网络 | 10 GbE 以上，推荐双 10 GbE | 承载设备上传、虚拟节点、镜像分发和存储流量。 |
| 管理 | IPMI/BMC 或等效带外管理 | 用于离线现场远程控制台、硬件监控和故障处理。 |
**存储分层配置说明：**现有 2 × 960 GB SSD 组成 RAID1 后，标称可用容量约 960 GB（格式化后更少），作为系统盘使用；若采购要求坚持 RAID1 后不少于 1 TB，应提高单盘容量。另增独立企业级 SSD/NVMe 作为 Infra 数据盘，承载容器缓存、镜像仓库、平台日志及实际部署的基础组件数据，建议采用 RAID1 或经验证的等效冗余方案。本地部署数据库时，其数据盘至少与系统盘物理隔离，生产环境建议进一步与 Infra 分盘。原始及解析数据使用独立业务存储，备份目标位于独立故障域。仅分目录、逻辑分区或在同一组物理盘上划分虚拟磁盘，不能隔离物理磁盘故障和 IO 竞争。新增数据盘容量按实际落盘组件、日志保留期、解析临时空间和峰值 IO 核算，在采购清单中明确。
**可用性边界：**宿主机、电源、主板或物理网卡故障会导致全部虚拟节点同时不可用。在同一宿主机内创建多个 control-plane VM 只能验证集群拓扑，不能形成物理故障域隔离。
有本体解析场景下，虚拟机、解析任务、数据管线和压测任务共享宿主机 CPU。宿主机除满足虚拟机分配外，还必须保留至少 20%的 CPU 调度余量。
多物理节点集群配置（非控制面 HA）
本节要求至少 3 台物理服务器，即 1 台
server/control-plane和至少 2 台agent/worker。当前如仅有 2 台服务器，则尚未满足本节推荐拓扑，只能采用临时的1 server + 1 agent部署。两节点临时部署不具备控制面高可用，任一节点故障后均可能出现控制面不可用或剩余计算能力不足，不应作为正式生产目标架构
| 节点角色 | 数量 | 单节点建议规格 | 说明 | 采购补充要求 |
|---|---|---|---|---|
| server/control-plane | 1 台 | 16 核 CPU、64 GB ECC、系统盘采用2 × 960 GB企业级SSD RAID1或更高规格、10 GbE、etcd、平台日志和基础组件数据使用独立企业级SSD/NVMe Infra数据盘 | 运行 K3s server/etcd 和控制面；该节点故障会影响集群管理与调度。 | 2U 机架式；整机至少 16 个物理核心、主频不低于 2.0 GHz，配置不低于 64 GB ECC 内存；具体 CPU 型号和颗数以整机核心总数及兼容性核验为准。系统盘采用 2 × 960 GB 企业级 SSD RAID1 或更高规格；Infra 另配独立企业级 SSD/NVMe，建议 RAID1；网络建议双口 10 GbE。 |
| agent/worker | 至少 2 台 | 无本体解析基线：32 个物理核心、128 GB ECC；有本体解析建议：不低于 64 个物理核心，内存按压测确认。系统盘 2 × 960 GB 企业级 SSD RAID1 或更高规格；10 GbE；额外配置独立企业级 SSD/NVMe Infra 数据盘，承载解析缓存、容器缓存、平台日志和临时数据；原始及解析数据使用独立业务存储。 | 运行解析、数据管线和业务服务；需要扩容时继续增加 worker。 | 按整机物理核心总数采购：无本体基线至少 32 核，有本体解析建议至少 64 核；处理器型号、颗数及内存搭配按压测和整机兼容性确认。 |
| 数据存储 | 1 套 | 按第 5 节核算 | 可以采用客户 StorageClass、冗余 NFS/SAN/对象存储，或节点本地企业级 NVMe 配合分布式存储。 | 见 数据盘容量计算 |
该模式是多物理节点工作负载集群，但只有 1 个 server/control-plane，因此不得描述为控制面高可用。
**CPU 与磁盘配置补充：**CPU 约 2 倍增强主要适用于承担解析任务的 worker；独立控制节点未调度解析任务时可保留 16 核基线。各节点应分别配置系统盘和独立 Infra 物理数据盘；本地数据库盘至少与系统盘分离，生产环境建议与 Infra 进一步分盘。磁盘用途、冗余和容量口径按第 2 节存储分层说明落实。
生产 HA 集群配置
生产 HA 最少需要 3 个 K3s server/control-plane，分别部署在 3 台独立物理服务器上并组成 etcd 多数派。40 台设备场景可先采用 3 台控制面与工作节点融合的紧凑拓扑；业务规模增加后再扩展独立 worker。
3 个 server/control-plane 必须分别运行在 3 台独立物理服务器上。不得在 2 台物理服务器上通过创建 3 个虚拟机的方式宣称实现物理高可用，因为其中一台宿主机故障仍可能同时造成两个控制面实例失效。
| 节点角色 | 数量 | 单节点建议规格 | 说明 |
|---|---|---|---|
| server/control-plane + worker 融合节点 | 3 台 | 无本体解析基线：32 个物理核心、128 GB ECC；有本体解析建议：不低于 64 个物理核心，内存按压测确认。系统盘 2 × 960 GB 企业级 SSD RAID1 或更高规格；独立企业级 SSD/NVMe Infra 数据盘，建议 RAID1；双 10 GbE。 | 3 个节点同时承担控制面和业务工作负载。无本体基线合计不低于 96 个物理核心、384 GB 内存；有本体解析建议合计不低于 192 个物理核心，内存按压测确认。需验证任一节点故障后剩余资源能够承载约定业务负载，CPU 翻倍不等同于并发能力承诺。 |
| 扩展 agent/worker | 按需增加 | 无本体基线：32～48 个物理核心、128～192 GB ECC；有本体解析按所选基线约 2 倍规划，即 64～96 个物理核心，最终以压测确认。系统盘 2 × 960 GB 企业级 SSD RAID1 或更高规格；独立企业级 SSD/NVMe Infra 数据盘，建议 RAID1；双 10 GbE。 | 用于增加解析并发、数据管线吞吐和扩缩容余量。 |
| 高可用数据存储 | 1 套 | 按第 5 节核算，节点和磁盘跨故障域 | Longhorn 至少双副本，或使用客户高可用 StorageClass/对象存储；备份目标必须位于独立故障域。 |
**HA 节点存储分层：**每台融合节点分别配置系统盘 RAID1 和独立 Infra 数据盘；业务存储磁盘与上述物理盘组分离。Longhorn 或外部 StorageClass 的业务卷不能替代节点本地系统盘及 Infra 盘。etcd、容器缓存、日志和数据库的实际落盘路径需在部署时验证；本地数据库按第 7 节条件配置。磁盘冗余不能替代跨节点高可用和独立备份，节点故障后的计算承载、存储副本可用性和重建空间均需验证。
**HA 范围：**Kubernetes 控制面 HA 不等于数据库、Redis、对象存储和备份已经高可用。所有状态组件必须根据客户 SLA、RPO 和 RTO 分别确认架构、容量及恢复方案。
RD001 数据盘容量计算
按 RD001 无本体设备 3 路摄像头 teleop 采集（合计约 9～10 Mbps）的现有实测数据外推，单台设备每小时约产生 5 GB 上传数据和 5 GB 解析后数据。以下数据仅供规划，最终以客户真实样本和压测结果为准。
**适用范围：**本节仅为 RD001 无本体设备现有样本的规划模型。其他设备类型和有本体设备的数据速率、解析后体量暂不作容量承诺，待取得实测数据后补充。每小时数据量应以完整采集文件和解析产物实测为准，视频码率仅用于辅助校验。
| 数据层 | 每设备小时数据量 | 每 1,000 采集小时数据量 |
|---|---|---|
| 上传数据（视频 MP4） | 约 5 GB | 约 5 TB |
| 解析后数据 | 约 5 GB | 约 5 TB |
| 原始和解析均留存 | 约 10 GB | 约 10 TB |
| 建议业务可用容量 | 约 13 GB | 约 13 TB |
逻辑数据量 = 设备数 × 单设备小时数据量 × 每日采集小时数 × 保留天数
建议业务可用容量 = 逻辑数据量 × 1.3
采购裸容量 = 建议业务可用容量 × RAID/副本/纠删码系数“1,000 采集小时”指所有设备累计产生的 1,000 个 device-hours。例如 40 台设备各采集 25 小时即为 1,000 采集小时，不是 1,000 小时自然时间。
| 40 台设备示例 | 逻辑数据量 | 说明 |
|---|---|---|
| 同时采集 1 小时 | 约 400 GB | 原始和解析数据均保留。 |
| 累计采集 25 小时 | 约 10 TB | 对应约 1,000 device-hours。 |
| 每天采集 8 小时、保留 30 天 | 约 96 TB | 建议业务可用容量约 125 TB，尚未计入存储副本。 |
因此，“数据盘 12 TB”只能代表较短保留窗口。采用 Longhorn 双副本时，每写入 1 TB 逻辑数据约占用 2 TB 集群裸容量，并需要额外保留运行水位；数据库备份、对象备份和异地容灾容量须单独核算。
年度容量与 1.5 PB 适用边界
采购前由客户确认 RD001 数量、每设备每日实际采集小时数、白班/夜班安排、每年采集天数，以及原始和解析数据各自的保留周期；同时确认中间文件、重复解析、备份及异地容灾要求。本文 GB/TB/PB 按十进制计算。
逻辑容量 = 设备数 × 每设备每日采集小时数 ×（原始数据 GB/小时 × 原始保留天数 + 解析数据 GB/小时 × 解析保留天数）。建议业务可用容量 = 逻辑容量 × 1.3。原始和解析均保留 365 天、40 台 RD001 每天采集 8 小时、合计 10 GB/device-hour 时，逻辑容量为 1.168 PB，建议业务可用容量为 1.5184 PB（约 1.52 PB）。
因此，1.5 PB 若指业务可用容量，已略低于上述含 30% 规划余量的示例；若指裸容量，还需扣除 RAID、副本或纠删码开销。双班应使用实际总采集小时数重新计算，不默认每天仅采集 8 小时。该示例不适用于其他设备型号。
裸容量应按实际存储架构逐层换算：建议业务可用容量 × 适用的 RAID/副本/纠删码综合开销系数；采用 Longhorn 双副本且无其他冗余开销时约为 3.04 PB。备份和异地容灾按各自副本及保留策略另算；如果同时采用底层 RAID 和上层副本，需计入两层开销。1.3 系数已包含 30% 规划余量，采购时需说明其中是否覆盖临时空间、运行水位及故障重建空间，不足部分单独补足，避免重复计提或遗漏。
操作系统和运行时
| 场景 | 操作系统 | 运行时 |
|---|---|---|
| 单物理机虚拟化 | KVM 兼容虚拟化平台；虚拟机使用 Ubuntu 24.04 LTS | K3s 自带 containerd，不要求虚拟机额外安装 Docker。 |
| 多物理节点 K3s | 各节点使用 Ubuntu 24.04 LTS 或交付版本明确认证的 64 位 Linux | K3s 自带 containerd。 |
| Compose 交付 | Ubuntu 24.04 LTS 或交付版本明确认证的发行版 | Docker Engine 24 以上，Docker Compose v2 2.20 以上。 |
Compose 与 Kubernetes 属于不同交付模式，不得把 Docker Compose 作为 K3s 集群的统一必备中间件。全离线部署的安装和运行均不得依赖公网、公共 DNS 或外部镜像仓库。
数据库
**数据库部署与磁盘边界：**标准交付由客户提供外部 MySQL，计算节点无需为该外部 MySQL 重复配置本地数据库盘；外部数据库环境应满足本节的 SSD/NVMe 容量、扩容、备份及约定可用性要求。如项目例外地在本地节点部署数据库，需在交付范围中明确，并配置独立企业级 SSD/NVMe 数据盘，至少与系统盘物理隔离，生产环境建议与 Infra 进一步分盘，采用 RAID1 或经验证的等效冗余方案。数据库外置不取消计算节点的独立 Infra 数据盘要求。
| 类别 | 要求 |
|---|---|
| 数据库类型 | 标准 MySQL |
| 版本 | MySQL 8.0.x |
| 建议规格 | ≥8 vCPU、32 GB |
| 存储 | 企业级 SSD，建议≥200 GB，并支持在线扩容；数据库备份空间另行计算 |
| 端口 | TCP 3306，或双方确认的自定义端口 |
| 访问地址 | 提供稳定的内网 IP、VIP 或 DNS 地址；不得使用可能变化的临时地址 |
| 网络 | 所有业务节点必须能够访问数据库端口；建议数据库与集群位于同一局域网或 VPC，网络延迟尽量低于 5 ms |
| 时区 | Asia/Shanghai |
| 最大连接数 | 建议不低于 500；实际值按各服务连接池上限×副本数，再预留至少 30% |
| 数据包大小 | max_allowed_packet 建议不低于 64 MB |
| 认证方式 | 当前基线采用 mysql_native_password；使用其他认证插件前须完成兼容性验证 |
| TLS | 跨网络访问建议启用；当前交付版本是否支持外部 MySQL TLS，须在项目实施前确认 |
| 监控 | 应监控 CPU、内存、连接数、慢查询、磁盘容量、IOPS、复制延迟和备份状态 |
网络和现场前置条件
- 所有节点使用固定内网地址并保持双向可达；节点网络最低 10 GbE，HA 和分布式存储场景推荐双 10 GbE。
- 管理网络、业务入口和存储网络建议逻辑隔离；条件允许时采用独立 VLAN 或独立物理网卡。
- 所有节点使用统一 NTP/Chrony 时钟源，节点间时钟偏差应小于 2 秒。
- Pod CIDR、Service CIDR、节点网段、客户 LAN/VPN 和设备网段不得重叠。
- 启用 Longhorn 时，每个存储节点必须安装并启用 iSCSI initiator/iscsid，并满足 Longhorn/CSI 的内核模块、mount 工具、multipath 和节点间通信要求。
- **MySQL 数据库为客户前置准备项，不包含在本项目标准交付范围内。**客户应在安装前自行部署 MySQL，或采购并开通兼容的 MySQL 云数据库服务。客户负责数据库资源、版本兼容、网络连通、账号权限、容量规划、备份恢复及高可用保障，双方须在安装前完成连接与权限验收。具体版本及配置要求以对应交付版本的兼容性清单为准。
| 端口 | 协议 | 用途 | 放通范围 |
|---|---|---|---|
| 22 | TCP | 节点初始化和自动加入 | 采用 SSH 自动加入节点时，由管理节点访问其他节点。 |
| 2379～2380 | TCP | etcd 通信 | 仅 3 个 server/control-plane 节点互通。 |
| 6443 | TCP | Kubernetes API | 管理端和所有节点访问。 |
| 8472 | UDP | Flannel VXLAN | 所有集群节点互通。 |
| 9345 | TCP | K3s supervisor | agent/worker 和其他 server 访问 server/VIP。 |
| 10250 | TCP | Kubelet API | 控制面访问所有节点。 |
| 80/443 | TCP | 平台 HTTP/HTTPS | 客户终端或负载均衡入口访问。 |
| 1883/8883 | TCP | MQTT/MQTTS | 设备网络访问。 |
| 30500 | TCP | 离线站点镜像仓库 | 所有节点访问首节点或站点 VIP。 |
以上为当前交付基线端口。最终应以对应交付版本的完整端口矩阵和 Site Contract 为准；防火墙、安全组或交换机 ACL 不得阻断集群及存储数据面。
外部数据库和存储（如客户自备）
- MySQL、PostgreSQL：由客户提供版本、连接地址、容量、备份、恢复和高可用 SLA；生产环境建议主备或等效高可用架构。
- Redis：根据业务 SLA 采用主从哨兵或集群模式，并确认持久化和备份要求。
- NFS、SAN、对象存储或 Kubernetes StorageClass：由客户提供业务可用容量、冗余方式、吞吐、IOPS、扩容能力和恢复 SLA。
- 外部服务的 DNS、网络路由、防火墙、安全组和账号权限由双方在安装前共同验收。
交付前检查和能力边界
安装前必须核对服务器数量与角色、磁盘绝对可用容量、全部端口、跨节点连通、CIDR 冲突、NTP、DNS、iSCSI、multipath、外部依赖和备份目标。当前自动预检只覆盖其中部分项目，未覆盖项必须执行人工硬门禁并留存验收结果；任一硬门禁不满足时不得开始生产安装。
当前标准多节点自动化路径为“1 server + 多 agent”，可以实现工作负载多节点，但不属于控制面 HA。客户要求生产 HA 时，应使用客户已有且通过契约检查的 Kubernetes 集群，或由项目单独完成 3 server/control-plane 的安装、升级、备份、恢复、节点替换和故障演练验证后交付。
硬件规格必须结合真实设备数据和专项压测确定。压测报告至少应记录软件版本、设备模型、并发量、持续时间、CPU、内存、磁盘 IOPS/延迟、网络水位、失败率和恢复结果，未经压测的数据不得作为容量承诺。
本次配置补充对应验收项
- **节点拓扑：**按选择的交付模式核对物理机数量和角色。第 3 节至少 1 server + 2 agent；生产 HA 核对 3 个 server/control-plane 分布在 3 台独立物理机，不能以两台宿主机上的 3 个 VM 替代。只有两台物理机或单个 server 时，不得按生产 HA 验收。
- **CPU：**有本体解析按增强档核对整机物理核心总数；用具体设备型号样本测试目标并发、解析速度、任务积压、CPU/内存、IO 延迟及恢复时间。HA 场景验证单节点故障后的剩余承载能力，最终容量以双方确认的压测结果为准。
- **RD001 容量：**客户确认设备数、实际采集小时数、班次、保留周期和冗余策略，区分裸容量与业务可用容量。上述参数未确认前，不承诺 1.5 PB 可保存一年；其他设备容量待实测后补充。
- **存储分层：**留存系统盘、Infra 盘、本地数据库盘（如有）及业务盘的物理盘/RAID 组、挂载路径和可用容量映射；验证高 IO 数据实际落盘位置、RAID/磁盘健康、IOPS及延迟、容量告警、备份目标和恢复结果。仅划分目录或同盘逻辑分区不能作为物理隔离验收依据；外部数据库由客户提供对应存储与恢复能力证明。