Darra PROFINET IO Device 发布手册

Name: Prof. Net — Darra PROFINET IO Device
Author: Darra

适用范围: Darra_Profinet_Slave 仓 发布链\release.ps1 一键发布流水线。本手册与 release.ps1 七阶段 / 参数 / 产物路径一一对应; 发布前逐项核对 发布检查清单.md, 发布中按本手册各阶段口径操作。

产品定位(简化级): RT Class 1 常规周期(周期下限 1ms 起以实测为准), 无核隔离 / TSC 校准 / 72h soak, 测试走基础模块。发布链为 ETH 七阶段的简化版, 能力缺口如实报错, 绝不静默跳过。

1. 流水线总览

Stage 1 BUILD      → Stage 2 COLLECT → Stage 3 VERIFY → Stage 4 TEST
                   → Stage 5 PACK    → Stage 6 OUTPUT → Stage 7 FINALIZE

阶段依赖链:build → collect → verify → test → pack → output / finalize。
每阶段完成写版本戳 _Stage\stamp_<stage>.txt(内容 Version|Channel|时间), -Skip* 跳阶段 / -Only 单跑阶段均须校验前序戳与目标版本一致, 否则 throw。
全程日志:_Stage\release_<版本>_<渠道>.log + progress.txt(进度流, tail 即可见)。
版本三源:CMakeLists.txt(project(DarraProfinet VERSION X.Y.Z)) + version\core.txt·driver.txt·sdk.txt + -Version 参数, 全链前后各校验一次。

2. 七阶段流程详解

Stage 1 BUILD — 构建全部交付物

项	内容
输入	源码树 + `-Version` / `-Channel`(入口已做版本三源校验)
1.1	`工具\build-all.ps1 -Configuration Release` — 核心 / 服务 / GUI / SDK C#
1.2	`Darra_Pnet_Kernel\Windows\scripts\build-driver.ps1 -Configuration Release -Platform x64` — `DarraRT_Pnet.sys`
1.3	SDK 其余 5 语言:C/C++ 走 MSBuild vcxproj; Java 走 `mvn package`; Python 走 `python -m build --wheel`; Rust 走 `cargo build --release`。工具链缺失(msbuild/mvn/python/cargo 不在 PATH)如实 throw
1.4	核心测试构建:`cmake --build out\tests --config Release`(测试工程未配置过 CMake 时仅告警, Stage 4 会如实报错)
输出	各组件构建产物(见 §3 产物清单)
版本戳	完成后写 `stamp_build.txt`
失败处理	任一步 ExitCode≠0 → `throw`, 流水线中止; 修复源码后重跑本阶段(`-Only build` 或全量)

Stage 2 COLLECT — 收集产物到 `_Stage\Payload\`

项	内容
输入	Stage 1 产物(前置戳 `stamp_build.txt`)
动作	清空重建 `_Stage\Payload\`, 按 §3 清单收集并改名对齐安装器契约
改名契约	核心 `darra_pnet.dll` → `DarraPnet.dll`(P/Invoke 与安装器契约运行名);
GUI `Darra_Pnet_GUI.exe` → `Darra.Pnet.GUI.exe`(`InstallEngine.cs GuiExeFileName`)
剔除	GUI 与 SDK 目录剔除 `.pdb` / `.xml`; SDK 剔除 `bin/obj/target/build/dist/.idea/__pycache__` 后按产物清单补回真实构建产物
可选件	驱动 `cat`(存在才收集)、`样例\`(目录存在才收集)、SDK 缺失构建产物如实 throw
输出	`_Stage\Payload\` 平铺载荷
版本戳	完成后写 `stamp_collect.txt`
失败处理	任何必需产物缺失(核心 dll / sys / inf / Service exe / GUI 主程序 / SDK 6 语言产物)→ throw 并指明缺什么, 先回 Stage 1 构建

Stage 3 VERIFY — sha256 校验清单 + 完整性校验

项	内容
输入	`_Stage\Payload\`(前置戳 `stamp_collect.txt`)
3.1	生成 `Payload\sha256-manifest.json`(schema `darra.pnet.payload-manifest.v1`, 含 package_version / channel / 逐文件 path+sha256+size)
3.2	调 `check-payload.ps1 -StageDir -Channel -Version`: ① 根级 5 项必需件存在; ② 清单逐文件重新哈希比对(缺文件 / 哈希不一致 → 失败); ③ 清单版本/通道与传入一致(防混版本)
输出	`sha256-manifest.json` + 校验通过记录
版本戳	完成后写 `stamp_verify.txt`
失败处理	哈希不一致 / 缺文件 → throw 并列出差异; 载荷被篡改, 重新 COLLECT 或排查拷贝路径

Stage 4 TEST — 发布前测试门

项	内容
输入	核心测试产物 + 配置测试(前置戳 `stamp_verify.txt`)
4.1	核心测试:`Darra_Pnet_Core\out\tests\Release\test_pnet_*.exe` 逐个运行, 任一退出码≠0 → throw
4.2	TEST_Config 冒烟:配置生成 → 校验 → 回读 → 三端闭环; 未构建时自动 `dotnet build -c Release`; 退出码≠0 → throw
定位	在 PACK 之前 —— 未验证产物禁止进安装包。测试只读产物, 不装驱动 / 不启服务(设计文档 §2.5)
输出	测试通过记录(全部退出码 0)
版本戳	完成后写 `stamp_test.txt`
失败处理	测试失败 = 不得发布。`-SkipTest` 可跳过(需前置戳校验, 不推荐)。核心测试实测 `test_pnet_core` 8/8 通过(2026-08-07 复核), 已无待修用例

Stage 5 PACK — 打 Payload.zip 并嵌入安装包

项	内容
输入	`_Stage\Payload\` + `sha256-manifest.json`(前置戳 `stamp_test.txt`, `-Only pack` 时强制校验 test 戳 —— 未测试不得打包)
5.1	`ZipFile.CreateFromDirectory` 打 `_Stage\Payload.zip`(条目保持相对结构)
5.2	条目结构校验:根级 5 项必需件 `DarraPnet.dll / DarraRT_Pnet.sys / DarraRT_Pnet.inf / Darra.Pnet.Service.exe / Darra.Pnet.GUI.exe` 缺一 throw(安装器解压契约)
5.3	覆盖嵌入 `安装包\Resources\Payload.zip`, 嵌入文件 SHA256 必须与 `_Stage\Payload.zip` 一致
输出	`_Stage\Payload.zip` + 已嵌入的安装包资源
版本戳	末尾写 `stamp_pack.txt`
失败处理	条目缺件 / SHA256 不一致 → throw; 修好后再 PACK

Stage 6 OUTPUT — 安装器 + SDK 发布副本

项	内容
输入	安装包 csproj + 嵌入后的 Resources\Payload.zip(前置戳 `stamp_pack.txt`)
6.1	`dotnet publish 安装包\安装包.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true`(AssemblyName=DarraPnetSetup)
6.2	拷到 `_Stage\Installer\`:Test 渠道 `DarraPnetSetup-<ver>-test.exe`, Formal 渠道 `DarraPnetSetup-<ver>.exe`
6.3	SDK 发布副本:`_Stage\SDK\`(从 `Payload\SDK` 复制)
输出	安装器 EXE(单文件自包含, 装到 `C:\DARRA\Profinet_Slave`) + SDK 发布副本
版本戳	本阶段不写戳(output 可重复跑, 由 finalize 收口)
失败处理	publish 失败 → throw; `-SkipOutput` 可跳过(仅出载荷与摘要)

Stage 7 FINALIZE — 版本戳最终强校验 + 发布摘要

项	内容
输入	全链产物(前置戳 `stamp_pack.txt`, 摘要引用安装器)
7.1	版本三源最终强校验:CMakeLists / version\core.txt·driver.txt·sdk.txt / `-Version` 全对, 缺任一 throw(防构建中途被改版 / 混版本)
7.2	发布摘要:版本 / 渠道 / 安装器路径 + 大小 + SHA256 / 载荷 Payload.zip 大小 + 文件数 / 版本戳清单 / 日志路径
输出	发布摘要(控制台 + 日志)
版本戳	末尾写 `stamp_finalize.txt`(全链闭环标记)
失败处理	版本漂移 → throw, 跑 `version\sync-versions.ps1` 同步后重来

3. 产物清单(真实产物名)

3.1 核心

产物	源码位置	收集后名称	说明
`darra_pnet.dll`	`Darra_Pnet_Core\out\Release\`(候选含 out\build\Release / out\build\x64-release\main\win64 / out\Debug)	`DarraPnet.dll`	C 核心, P-Net 集成 + win32 pnal 移植, 序数导出; P/Invoke 与安装器契约运行名

3.2 驱动

产物	源码位置	说明
`DarraRT_Pnet.sys`	`Darra_Pnet_Kernel\Windows\Pnet\bin\Release\x64\`	NDIS 协议驱动, 数据面(周期 PPM/CPM + 过程映像 + 看门狗 + 0x8892/0x88CC 帧环)
`DarraRT_Pnet.inf`	`Darra_Pnet_Kernel\Windows\Pnet\`	驱动 INF(`RequireExclusiveBinding=1`)
`DarraRT_Pnet.cat`	驱动 bin 目录(存在才收集)	Stage 1 不跑 inf2cat; 装机走测试签名流程生成, 测试机签名流程产出的 cat 一并收集

3.3 服务

产物	源码位置	说明
`Darra.Pnet.Service.exe`	`Darra_Pnet_Service\bin\Release\net8.0-windows\`	Windows Service(控制面:PNIO-CM / DCP / LLDP / Alarm / SNMP / P-Net 状态机 + Web API 18840)
`Darra.Pnet.Service.dll` + `appsettings.json`	同上	服务装配与配置

3.4 GUI

产物	源码位置	收集后名称	说明
`Darra_Pnet_GUI.exe`	`Darra_Pnet_GUI\bin\Release\net8.0-windows\`	`Darra.Pnet.GUI.exe`	配置工具(输出 GSDML + 运行配置 XML + 授权激活窗体); 改名对齐 `InstallEngine.GuiExeFileName`
依赖 dll	同上目录 `*.dll`	原样	DevExpress 等依赖; pdb/xml 剔除

3.5 SDK 6 语言(进 `Payload\SDK\<语言>\`, 源整体拷贝 + 产物补回)

语言	真实构建产物	构建入口(Stage 1.3)
CSharp	`DarraPnet.dll`(netstandard2.0, `bin\Release\netstandard2.0\`)	build-all.ps1
C	`Darra.Pnet.SDK.C.lib`(`x64\Release\`, vcxproj ProjectName=Darra.Pnet.SDK.C)	MSBuild `Darra_C_SDK.vcxproj`
CPP	无库产物(header-only, 源拷贝即交付)	MSBuild `Darra_CPP_SDK.vcxproj`(仅自检)
Java	`darra-pnet-slave-<v>.jar`(`target\`)	`mvn package -DskipTests`
Python	`darra_pnet_sdk-<v>-*.whl`(`dist\`)	`python -m build --wheel`
Rust	无二进制产物([lib] 仅 rlib, 未声明 cdylib; 源码即交付, 消费者按 README 自行构建)	`cargo build --release`(仅自检)

3.6 样例与安装器

产物	说明
`样例\`(Payload 内)	样例工程(目录存在才收集, 骨架阶段允许缺)
`Payload.zip`(`_Stage\` + 嵌入 `安装包\Resources\`)	载荷压缩包, 安装器解压到 `C:\DARRA\Profinet_Slave`
`DarraPnetSetup-<ver>[-test].exe`(`_Stage\Installer\`)	安装器, SelfContained 单文件; Test 渠道带 `-test` 标记, Formal 不带

4. 版本戳机制(防混版本)

写入: 每阶段完成写 _Stage\stamp_<stage>.txt, 内容一行 Version|Channel|时间 (例:1.0.0|Test|2026-08-07 11:30:00)。
校验: -Skip* 跳阶段、-Only 单跑阶段时, 必须校验该阶段(或前序阶段)戳以 Version|Channel 开头, 不一致 throw —— 提示"混版本风险, 先全量重跑或删旧产物"。
依赖链: build → collect → verify → test → pack(→ output / finalize)。
防混版本场景: 上次发布 1.0.0 的载荷未清理, 本次发 1.0.1 直接 -SkipCollect → 戳校验必失败, 杜绝旧轮产物混入新包。
清场方法: 删除 _Stage\stamp_*.txt(或整个 _Stage\ 目录)后全量重跑。

5. 回滚流程(发布失败恢复)

5.1 发布中途失败

流水线任何阶段 throw 即中止, 已写入的版本戳保留(可追溯走到哪一步):

读 _Stage\release_<ver>_<ch>.log 末段, 定位失败阶段与错误。
按失败阶段处理:
- BUILD / TEST 失败: 源码问题, 修复后 -Only build(或 -Only test)重跑该阶段, 前序戳校验通过即可续跑, 不必全量。
- COLLECT / VERIFY 失败: 产物缺失或哈希不一致, 清 _Stage\Payload\ 后 -Only collect → -Only verify 重跑。
- PACK / OUTPUT 失败: -Only pack → -Only output 重跑。
续跑完成后 -Only finalize 收口出摘要。

5.2 版本回退(发错版本 / 需要重发)

安全回退: 不做任何 git reset / 回档。发布链是构建流程, 不是版本库操作; 要发旧版本, 用 git log 找到旧版源码, git worktree add 或新分支检出, 再跑发布链 -Version <旧版本>。_Stage\ 内不同版本产物靠版本戳隔离, 互不覆盖。
脏载荷清理: 换版本重发前, 删除 _Stage\ 下该版本全部 stamp + Payload + Payload.zip, 全量重跑, 防旧版本戳污染新版本。

5.3 装机回退(测试机 / 客户机)

安装包内置卸载(UninstallService, 装到 C:\DARRA\Profinet_Slave), 卸载后重装旧版安装包即可。
驱动回退: 驱动签名链(测试签名流程)与系统版本相关, 回退驱动须走 install-pnet.ps1 卸载旧绑定后再装目标版本(只读引用驱动 README 口径)。

6. 授权发布(设计文档 §2A)

授权链路: GUI 激活 → 激活成功证书落盘 → Service 启动加载证书并绑定校验。授权代码按 §2A 落地中(发布链阶段不含授权), 以下为发布操作流程。

6.1 授权后台部署(一次性)

授权后台/(Cloudflare Worker + D1)配置三表: pnet_personal_codes(个人激活码)/ pnet_enterprise_codes(企业激活码)/ pnet_enterprise_devices(企业设备)。
API 面:POST /api/v1/license/activate(激活码 + 设备指纹 → 签发证书)、 GET /api/v1/license/status、POST /api/v1/license/deactivate、管理 API (企业码签发/吊销)。
证书签名 HMAC-SHA256(secret) — secret 当前为占位, 正式发布前必须更换为强随机值并经安全通道配置。

6.2 签发激活码(每次销售交付)

管理 API 生成激活码:pnet_personal_codes(个人)或 pnet_enterprise_codes(企业, 绑定设备数)。
激活码交付客户(邮件 / 纸质, 走商务流程)。
登记发放记录(客户 / 码 / 有效期 / 设备指纹), 与后台台账一致。

6.3 客户端激活(客户现场)

安装发布链产出的安装包(装到 C:\DARRA\Profinet_Slave)。
打开 GUI → 授权管理器 → 激活窗体:输入激活码 → 点激活。
激活成功:GUI 调后台验签, 证书写入注册表 HKLM\SOFTWARE\Darra\Profinet\License (值 Certificate, 不落文件防篡改)。
Service 启动时 PnetLicenseService 加载证书 → 校验(HMAC 签名 + 机器码绑定 + 状态)→ 通过才运行从站; 未激活 / 证书失效 → 日志 Error + 拒绝启动。
查询:GET /api/license/status(Web API 18840)。

6.4 吊销 / 失效

后台吊销激活码(管理 API)→ 客户端下次 GET /api/license/status 或激活校验返回失效 → Service 拒绝启动。
设备更换:后台解绑旧设备指纹(管理 API)→ 新设备重新激活。

7. 发布前检查清单(速查)

逐项核对 发布检查清单.md 全文, 摘要:

版本三源一致(CMakeLists.txt / version\*.txt / -Version), 需要时先跑 version\sync-versions.ps1。
构建 0 error(核心 / 驱动 / 服务 / GUI / SDK 6 语言, 工具链就绪)。
测试门全 PASS(核心 test_pnet_*.exe + TEST_Config 冒烟), 已知缺口如实登记。
载荷完整(Payload 5 项根级必需件 + SDK 6 语言产物 + 样例)。
证书 / 密钥就绪:驱动签名(测试证书或后续 EV)、授权后台 HMAC secret 已换、安装器签名策略明确。
渠道命名:Test 带 -test 标记, Formal 不带; Formal 发布必须过全链 + 签名。

8. 已知缺口(如实登记, 不伪装)

#	缺口	现状	解除条件
1	ENCRYPT(加壳)未实现	VMP / Reactor 加壳不在本版发布链, 安装器/核心不加密	`Darra_Pnet_Publish` 建立, 参照 `Darra_ETH_Publish\Scripts\release.ps1` 补齐
2	SIGN(签名)未实现	本版不签驱动 / 安装器; 驱动装机走 `install-pnet.ps1` 测试签名流程	`Darra_Pnet_Publish` 补齐 EV / 测试签工具链
3	驱动 cat 无闭环	Stage 1 不跑 inf2cat, cat 存在才收集	发布链补 inf2cat + cat↔sys 闭环校验
4	发布链目录非 symlink	设计文档规划 symlink 到 `Darra_发布专用仓库\Darra_Pnet_Publish`, 该仓尚不存在	建立后整体替换 + 脚本迁入 `Scripts\`
5	授权代码落地中	§2A 授权链路(GUI 激活 / 证书落盘 / Service 绑定)按设计文档实施中	各授权组件(后台 / SDK 授权类 / GUI 激活 / Service 绑定)完成 + rig 真测

注:test_pnet_core 平台自检曾登记为"待修"缺口, 2026-08-07 复核实测 8/8 通过(无失败), 已从缺口表移除, Stage 4 不再对该用例特殊报错。

9. 常用操作速查

# 全量 Test 发布
powershell -ExecutionPolicy Bypass -File 发布链\release.ps1 -Version 1.0.0 -Channel Test

# 全量 Formal 发布(先过检查清单)
powershell -File 发布链\release.ps1 -Version 1.0.0 -Channel Formal

# 复用上轮构建产物续跑(仅改了一处, 跳构建/收集/校验)
powershell -File 发布链\release.ps1 -Version 1.0.0 -Channel Test -SkipBuild -SkipCollect -SkipVerify

# 修完测试后只重跑测试门
powershell -File 发布链\release.ps1 -Version 1.0.0 -Channel Test -Only test

# 单独校验载荷完整性
powershell -File 发布链\check-payload.ps1 -StageDir .\_Stage -Channel Test -Version 1.0.0

1. 流水线总览​

2. 七阶段流程详解​

Stage 1 BUILD — 构建全部交付物​

Stage 2 COLLECT — 收集产物到 _Stage\Payload\​

Stage 3 VERIFY — sha256 校验清单 + 完整性校验​

Stage 4 TEST — 发布前测试门​

Stage 5 PACK — 打 Payload.zip 并嵌入安装包​

Stage 6 OUTPUT — 安装器 + SDK 发布副本​

Stage 7 FINALIZE — 版本戳最终强校验 + 发布摘要​

3. 产物清单(真实产物名)​

3.1 核心​

3.2 驱动​

3.3 服务​

3.4 GUI​

3.5 SDK 6 语言(进 Payload\SDK\<语言>\, 源整体拷贝 + 产物补回)​

3.6 样例与安装器​

4. 版本戳机制(防混版本)​

5. 回滚流程(发布失败恢复)​

5.1 发布中途失败​

5.2 版本回退(发错版本 / 需要重发)​

5.3 装机回退(测试机 / 客户机)​

6. 授权发布(设计文档 §2A)​

6.1 授权后台部署(一次性)​

6.2 签发激活码(每次销售交付)​

6.3 客户端激活(客户现场)​

6.4 吊销 / 失效​

7. 发布前检查清单(速查)​

8. 已知缺口(如实登记, 不伪装)​

9. 常用操作速查​

1. 流水线总览

2. 七阶段流程详解

Stage 1 BUILD — 构建全部交付物

Stage 2 COLLECT — 收集产物到 `_Stage\Payload\`

Stage 3 VERIFY — sha256 校验清单 + 完整性校验

Stage 4 TEST — 发布前测试门

Stage 5 PACK — 打 Payload.zip 并嵌入安装包

Stage 6 OUTPUT — 安装器 + SDK 发布副本

Stage 7 FINALIZE — 版本戳最终强校验 + 发布摘要

3. 产物清单(真实产物名)

3.1 核心

3.2 驱动

3.3 服务

3.4 GUI

3.5 SDK 6 语言(进 `Payload\SDK\<语言>\`, 源整体拷贝 + 产物补回)

3.6 样例与安装器

4. 版本戳机制(防混版本)

5. 回滚流程(发布失败恢复)

5.1 发布中途失败

5.2 版本回退(发错版本 / 需要重发)

5.3 装机回退(测试机 / 客户机)

6. 授权发布(设计文档 §2A)

6.1 授权后台部署(一次性)

6.2 签发激活码(每次销售交付)

6.3 客户端激活(客户现场)

6.4 吊销 / 失效

7. 发布前检查清单(速查)

8. 已知缺口(如实登记, 不伪装)

9. 常用操作速查