跳到主要内容

量产线安装

用于处理生产线中 100 ~ 1000 台设备的情况。操作员仅需填写一个屏幕提示(prompt)，即可自动完成 EDGE_ID / hostname / 凭证 / Docker / cosign verify / 容器启动。 每台设备耗时 30 秒。

本页为量产线 SOP

如果是单台设备 / 现场安装 (SI 员工)，请先参阅 单线安装 页面。量产线与现场安装的区别仅在于 入口点，最终结果相同。

0. 概览​

sudo -i
mkdir -p /home/kopens
curl -fsSL https://product.kopens.io/plantpulse-edge/plantpulse-edge-docker.tar.gz \
    | tar xz -C /home/kopens
cd /home/kopens/plantpulse-edge-docker/bin
sudo bash factory.sh

factory.sh 将自动执行：

  1. LAN1 NIC MAC 自动检测 — 使用 MAC 最后 6 位生成 EDGE_<HEX6> (例如：EDGE_3F8A21)。
  2. 主机名同步 — 将 hostname 也更改为 edge-<hex6> (RFC 1123, 小写+连字符)。
  3. 5 字段提示 — SITE_ID / SERVER_HOST / SERVER_API_KEY / LAN1 NIC / LAN2 NIC。
  4. install.sh 委派 — Docker / cosign / random secret / app.properties / 容器启动。
  5. 打印 factory-label.txt — 用于设备粘贴。打印后密封。
  6. 追加 factory-inventory.csv — 在生产线末端回收 → 公司 inventory DB。

1. ID / hostname 自动生成​

EDGE_ID — EDGE_<HEX6>​

LAN1 NIC eth1 MAC = 00:1a:2b:3f:8a:21
                              ─────
                              마지막 6 자 (HEX6) = 3F8A21
EDGE_ID  = EDGE_3F8A21
hostname = edge-3f8a21

为何使用 MAC?

  • hostname 在每次安装 OS 时可能会更改 (cloud-init / hostnamectl)，且可能发生冲突。
  • MAC 固化在硬件中，可保证每台设备唯一。
  • 24-bit 最后 6 位 → 约 1670 万种组合。在 1000 台量产中，冲突概率约为 0.003% (基于生日悖论，处于安全范围)。

强制执行域规则 (产品仓库的 CLAUDE.md)：

标识符正则表达式示例
EDGE_ID^EDGE_[A-Z0-9_]{1,60}$EDGE_3F8A21
SITE_ID^SITE_[A-Z0-9_]{1,60}$SITE_FAB1_042
hostname (RFC 1123)小写 + 连字符edge-3f8a21

factory.sh 在上述 regex 验证后进行 — 若未通过则立即中止(abort)。

MAC 冲突 / 无 NIC 设备​

  • 冲突可能性 — 若 /data1/factory-inventory.csv 中已存在相同的 EDGE_ID，则立即中止 (防止静默重复)。可自动检测同一设备重复配置或 MAC 冲突情况。
  • 无 MAC 设备 (如虚拟 NIC) — derive_edge_id_from_mac 失败 → install.sh 将基于 hostname 进行回退(fallback)。这种情况在生产线中极少发生。

2. Prompt 5 字段​

操作员在生产线输入：

══════════════════════════════════════════════════════════════════════
  PlantPulse Edge — Factory Provisioning
══════════════════════════════════════════════════════════════════════
  Detected NIC eth1 MAC : 00:1a:2b:3f:8a:21
  Auto EDGE_ID          : EDGE_3F8A21
  Auto hostname         : edge-3f8a21
══════════════════════════════════════════════════════════════════════
  Site ID (^SITE_[A-Z0-9_]+) [SITE_00001]: SITE_FAB1_042
  Platform server host       [192.168.0.41]: 10.10.0.5
  Platform API key           []: kFa7bGz8pQrN3xMv9wT2sLcEjY1uV6oH
  LAN1 NIC (PLC)             [eth1]:                                 ← Enter = default
  LAN2 NIC (WAN)             [eth2]:                                 ← Enter = default
══════════════════════════════════════════════════════════════════════
  Summary
  EDGE_ID         : EDGE_3F8A21
  hostname        : edge-3f8a21
  SITE_ID         : SITE_FAB1_042
  SERVER_HOST     : 10.10.0.5
  SERVER_API_KEY  : kFa7…(32 chars)
  LAN1 NIC (PLC)  : eth1
  LAN2 NIC (WAN)  : eth2
══════════════════════════════════════════════════════════════════════
  Proceed with install.sh? [y/N]

点击 y 后，install.sh 将运行 5 ~ 10 分钟 (含首次拉取 3 GB 镜像)，随后打印标签。

3. 自动生成的凭证 (G2)​

install.sh 为每台设备生成不同的随机密码 (详见下载的 plantpulse-edge-docker/README.md 中 密码 / API 密钥 (Secrets) 章节)：

变量长度位置
ADMIN_PASS (UI 登录)随机 14 位+!/etc/kopens/credentials.txt
API_KEY (REST)随机 16 位上述文件 + env.sh.generated
MQTT_PASS (HiveMQ)随机 14 位+!上述文件
OPCUA_PASS随机 14 位+!上述文件
CERT_PASS (SSL keystore)随机 14 位+!上述文件

/etc/kopens/env.sh.generated (chmod 0600 root) 是所有后续脚本 (upgrade.sh / restart.sh) 引用(source)的侧车文件 — 重启后仍维持相同的凭证。

4. 镜像签名验证 (G3)​

install.sh 自动安装 cosign + 配置 cosign.pub + 在 docker pull 后立即自动验证。

[install] Installing cosign ...
[install] OK — cosign installed (cosign version 3.1.3)
[install] cosign.pub installed — image verification enabled
[install] docker pull — docker.kopens.io/pe/plantpulse-edge:2026.11-20261103-1006
[install] OK — Pull complete
[cosign]  OK — signature verified for docker.kopens.io/pe/plantpulse-edge:2026.11-20261103-1006

镜像签名采用 cosign 3 格式，因此 cosign 2.x 无法找到签名。若 install.sh 与 upgrade.sh 中不存在 cosign 或版本低于 3，则从 github.com 下载固定版本 3.1.3，在核对校验和后安装 (不使用发行版软件包)。若已安装 3.x 版本则直接使用。若安装阶段下载失败仅保留警告，但若无法验证签名，升级将 不启动。

隔离网络设备

安装时使用 Bundle 附带的 cosign (tools/cosign-linux-amd64)。升级时通过 pe upgrade --bundle <파일> [--cosign <cosign-linux-amd64>] 在无互联网环境下验证签名 — 隔离网络升级。

若 cosign.pub 仍为占位符 (运维团队尚未生成 keypair)，则仅发出 WARN 警告，安装继续进行。参考下载的 plantpulse-edge-docker/README.md 中 镜像签名 (Cosign) 章节。

5. 标签 + 资产清单​

/etc/kopens/factory-label.txt — 设备粘贴用​

安装结束后在屏幕输出 + 保存至 chmod 0600 文件。生产线员工使用标签打印机打印后粘贴于设备并密封：

══════════════════════════════════════════════════════════════════════
  PlantPulse Edge — Factory Label
══════════════════════════════════════════════════════════════════════
  EDGE_ID     : EDGE_3F8A21
  hostname    : edge-3f8a21
  SITE_ID     : SITE_FAB1_042
  build_date  : 2026-05-19 14:25:33
──────────────────────────────────────────────────────────────────────
  LAN1 (PLC)  : eth1  MAC=00:1a:2b:3f:8a:21
  LAN2 (WAN)  : eth2  MAC=00:1a:2b:3f:8a:22
──────────────────────────────────────────────────────────────────────
  UI admin    : admin / aBcD1234EfGh!
  REST API    : kFa7bGz8pQrN3xMv9wT2sLcEjY1uV6oH
  (full credentials → /etc/kopens/credentials.txt — root only)
══════════════════════════════════════════════════════════════════════

/data1/factory-inventory.csv — 生产线回收用​

每台设备追加一行。在生产线末端由操作员回收 → 上传至公司 inventory DB：

edge_id,hostname,site_id,server_host,lan1_iface,lan1_mac,lan2_iface,lan2_mac,build_date,iso8601
EDGE_3F8A21,edge-3f8a21,SITE_FAB1_042,10.10.0.5,eth1,00:1a:2b:3f:8a:21,eth2,00:1a:2b:3f:8a:22,2026-05-19 14:25:33,2026-05-19T05:25:33Z
EDGE_5B7C03,edge-5b7c03,SITE_FAB1_043,10.10.0.5,eth1,00:1a:2b:5b:7c:03,eth2,00:1a:2b:5b:7c:04,2026-05-19 14:28:12,2026-05-19T05:28:12Z

6. 线末批量回收​

# 라인 마지막 박스 처리 후 회수 워크스테이션에서
scp root@edge-3f8a21:/data1/factory-inventory.csv ./inventory-line1-$(date +%F).csv

# 회수한 CSV 들을 사내 inventory DB 로 업로드 (예: scripts/import-inventory.py)
python3 import-inventory.py inventory-line1-2026-05-19.csv

或者可以添加钩子(hook)，在设备启动时自动推送(push)至 Platform 端 (Phase 1 — 引入公司内部 provisioning REST API 时)。

7. 常见误区​

现象原因对策
EDGE_ID '...' fails ^EDGE_[A-Z0-9_]{1,60}$LAN1 NIC 的 MAC 为非 ASCII 的虚拟 NIC如 NET1_IFACE=enp1s0 bash factory.sh 般明确指定
already_in_inventory: EDGE_3F8A21 already provisioned同一台设备重复执行或 MAC 冲突通过 vi /data1/factory-inventory.csv 删除对应行后重新执行。若为 MAC 冲突，停止生产线并汇报
cosign verify FAILED (COSIGN_REQUIRE=1)镜像未签名 或 cosign.pub 错误确认构建服务器 sign-image.sh 调用是否遗漏，更新 cosign.pub
hostnamectl set-hostname failed在容器内执行 / 无权限factory.sh 强制要求 root — sudo bash factory.sh
提示(prompt)不可见 (标签未打印)install.sh 在中途失败检查 journalctl -u plantpulse-edge.service -n 50 后参阅 安装问题解决

8. 相关文档​

  • plantpulse-edge-docker/README.md — 运维场景 (量产 / SI / CI) 章节 (包含在发布包内)
  • plantpulse-edge-docker/README.md — 镜像签名 (Cosign) 章节 (keypair 生成 · 部署 · 轮转)
  • 单线安装
  • 安装后巡检
  • 隔离网络安装