云光伏监控DREAMS并网验收：基于JavaScript的联测存储库

简介：面向光伏监控系统测试人员的DREAMS云端对接测试程式，用于验证云光伏电站监控系统是否满足台电DREAMS规范。其核心能力是通过DNP 3.0将发电数据上传至台电DREAMS系统，同时接收台电下发的控制指令，调整变流器的有功/无功功率、功率因数上限或VPset设定，可帮助监控业者对旗下电站完成合规接入验证。资源包共147个文件，压缩后仅351KB，文件以JavaScript、JSON、C++头文件/源文件（hpp/cpp）、Shell脚本及Dockerfile为主，覆盖前端交互、通信逻辑、容器化部署与环境配置等用途。目前已有141人学习/下载，适合需要开展DNP 3.0对接测试或排查通信细节的光伏监控开发与测试人员。包内除完整测试程序源码外，还提供Docker编排配置、SSL证书/密钥样例、监听事件处理模块及消息发送工具脚本，便于快速搭建Linux测试环境并验证实功/虚功调节等关键场景。

1. 云光伏监控系统过 DREAMS 验收：先过这套 JavaScript 联测存储库

某电网集团的 DREAMS 并网验收系统，是云光伏监控系统并网前必须过的一道闸。很多开发团队在验收前夜才发现问题：本地测试一切正常，DREAMS 侧看到的却是曲线断断续续、控制指令超时、补报窗口不达标。这类问题背后的共性是——测试停留在"功能正常"层面，没有站在 DREAMS 的视角去验证规约、字段和时间窗口。这个存储库就是干这个的：一套以 JavaScript 和 Node.js 为主的联测脚手架，把并网验收规范转成可重复执行的脚本、模拟器和断言用例。适合并网接入工程师、云监控后端开发、测试工程师直接拿去改造成自己项目的验收基线。

2. 拆验收域、定测试栈：DREAMS 联测为什么用 JavaScript 与 Jest

DREAMS 这类并网验收系统，校验的不是界面长什么样，而是云光伏监控系统能不能按规约把数据送上来、按指令把功率调下去。换句话说，这是规约验收，不是功能验收。所以拿到存储库之后，第一步不是看代码，而是把验收要覆盖的数据域拆开，再对照你自己接入省份发布的并网技术规范逐项勾选。拆完域，选型理由自然就清楚了。

2.1 验收到底验什么：五个数据域和两条通信链路

我把 DREAMS 联测相关的验收内容梳理成五个数据域，这是我拿到一套新规范时习惯性的整理方式，具体字段定义以你接入的省级并网技术规范为准。

两条链路分别指上行和下行：上行链路负责把监控数据从云平台推到 DREAMS 侧，下行链路把 DREAMS 的功率控制指令拉到逆变器。很多验收不通过，问题不在功能实现，而在两条链路之间某个字段的映射对不上。比如上行链路里时间戳字段格式不统一，或者下行链路里回执和结果状态码合在一个字段里，都会导致 DREAMS 侧判定异常。

这里有一个可以少走弯路的思路：把五个数据域映射成用例的优先级，不要平均用力。我一般先做实时运行数据和断点续传，因为这两个域是验收退回的高发区，而且很容易用自动化用例覆盖；功率控制域放到第二步，因为它强依赖模拟器和指令下发链路；数据质量域则穿插在前两个域的用例里，用异常注入的方式去验证。

2.2 为什么选 JavaScript 而不是"跑一遍就扔"的脚本

这个存储库以 JavaScript 为主，选型理由有三点。

第一，云光伏监控系统的后端如果是 Node.js，测试脚本和业务服务共用一套调试栈，联调时可以直接在同一个进程里打断点，比跨语言切换省很多事。第二，Node.js 对 TCP、WebSocket、HTTP/2 的支持比较完整，后面要模拟 Modbus TCP 采集器或者轮询式网关，不用再引一大堆底层依赖。第三，Jest 的参数化测试和假时钟在时间窗口类用例里很好用，正好命中超时判定和断点续传这两个高频场景。

这不是说 JavaScript 一定比其他语言强。Python 写协议脚本也有优势，但这个存储库的定位是跟着业务后端走，所以选了 Node.js。如果你所在团队的后端是 Java 或 Go，把 testcases 目录里的脚本换成对应语言也可以，目录结构和用例设计思路是一样的。关键是别为了换成"团队更熟的语言"而丢掉配置驱动和黄金报文比对这两个核心设计。

2.3 仓库结构拆解：每个目录对应一个验收域

把存储库解压后，目录结构大致是这样。我按"一个目录解决一个验收域"的原则组织，避免所有脚本堆在根目录里：

joint-tester/ ├── config/ # 环境配置与验收阈值 │ ├── default.json │ └── acceptance-prod.json ├── protocols/ # 报文编解码与协议适配 │ ├── iec104.js │ ├── modbus-tcp.js │ └── timestamps.js ├── simulators/ # 设备与电网侧模拟器 │ ├── inverter-sim.js │ └── gateway-sim.js ├── testcases/ # Jest 用例 │ ├── report.spec.js │ ├── control.spec.js │ └── complement.spec.js ├── fixtures/ # 黄金报文与 JSON Schema │ ├── schemas/ │ └── golden/ ├── reports/ # 测试报告输出 └── scripts/ ├── smoke.sh └── verify-golden.js

config 目录放环境参数，protocols 目录处理规约编解码，simulators 里是模拟器，fixtures 里的 golden 文件是从 DREAMS 规范里摘出来的样例报文，后面做回归基线时主要靠它。testcases 目录里每个 spec 文件对应一个数据域，report 对应实时上报，control 对应功率控制，complement 对应断点补报。

用例编号规范也要从第一天就建立。我在 testcases 里用的是 TC-RPT-3.1.2 这种格式，前缀表示数据域，后面的数字直接映射验收规范的章节号。验收评审时，专家看到用例编号就能定位到对应规范条款，比解释一堆文件名省事得多。这个习惯是某次验收评审被问"这条用例对应规范哪一条"之后养成的，从那以后所有联测仓库都强制带规范章节号。

3. 搭联测脚手架：Node.js + Jest 跑通第一条逆变器上报用例

这一章直接进入可执行的部分。目标很明确：初始化一个能跑、能出报告的最小仓库，然后跑通第一条逆变器实时数据上报用例。

3.1 初始化仓库：依赖、Node 版本、锁定文件

新建目录后，先写 package.json。依赖控制在四个以内，太多会引入版本漂移问题：

{ "name": "dreams-cloud-joint-tester", "version": "0.1.0", "private": true, "engines": { "node": ">=20.0.0" }, "scripts": { "test": "jest --runInBand", "test:report": "jest --runInBand --reporters=default --reporters=jest-junit", "verify:golden": "node scripts/verify-golden.js" }, "devDependencies": { "jest": "^29.7.0", "jest-junit": "^16.0.0" }, "dependencies": { "ajv": "^8.12.0", "axios": "^1.7.0" } }

逻辑说明：jest 负责用例执行，axios 负责从云监控 API 拉数据，ajv 负责按 JSON Schema 校验上报字段。jest-junit 只在 test:report 时启用，把结果输出成 JUnit XML，方便接入 CI 和生成验收材料。engines 字段指定 Node 20 以上，因为下面模拟器用到了较新的 Buffer 和流式 API，版本太低会在启动时报错。

参数说明：--runInBand 强制用例串行执行。这个仓库里的用例会启动 TCP 模拟端口，并行跑容易互相抢端口，串行虽然慢一点，但结果稳定。所以 package.json 里所有 test 脚本都带上了 --runInBand，这是一个有意的设计，不是为了省事。

依赖锁定是必须做的一步。package-lock.json 要提交进仓库，换环境跑用例时用 npm ci 而不是 npm install，能避免"本地全绿、CI 环境翻车"的版本漂移问题。我在第 5 章会专门讲一条和这个相关的踩坑记录。

3.2 配置驱动的分层设计：环境、账号、验收阈值分开

config/default.json 是仓库的默认配置。这里把环境参数和验收阈值分开存放，联调环境、预验收环境、正式验收环境切换时只改环境变量，不改用例代码：

{ "cloudApi": { "baseUrl": "http://localhost:8080", "timeoutMs": 10000, "clientId": "joint-tester", "clientSecret": "change-me" }, "dreams": { "endpoint": "tcp://127.0.0.1:2404", "remoteUnitId": 1, "commonAddress": 1 }, "acceptance": { "reportIntervalSec": 300, "complementWindowMin": 15, "timestampFormat": "ISO8601" } }

逻辑说明：cloudApi 指向被测的云光伏监控系统，dreams 指向本地的 DREAMS 网关模拟器，acceptance 段落里放验收阈值。这里最值得注意的字段是 complementWindowMin，它是断点补报窗口，单位是分钟，验收规范里如果写的是"不小于 15 分钟"，那配置就应该填 15，而不是 10。很多验收退回就是栽在这个默认值上。

参数说明：remoteUnitId 和 commonAddress 分别是 104 规约里的远动单元地址和公共地址，具体值由接入点配置决定，不要照抄样例。配置加载我一般写成 loadConfig() 函数，先用 default.json，再用 process.env 覆盖，这样不用改代码就能切换环境。如果你有多个环境，还可以再加一个 acceptance-prod.json，把正式验收环境的阈值单独放一份，避免污染开发环境。

3.3 第一条上报断言用例：用 AJV 校验字段结构

testcases/report.spec.js 是第一批要跑通的用例。它做三件事：请求云监控系统自身的 API、拿到一台逆变器的实时数据、按照规范定义的 JSON Schema 做结构校验：

const axios = require('axios'); const Ajv = require('ajv'); const loadConfig = require('../config/loadConfig'); const inverterReportSchema = require('../fixtures/schemas/inverter-report.schema.json'); describe('TC-RPT-3.1.2 逆变器实时数据上报', () => { const config = loadConfig(); test('单台逆变器上报字段满足 DREAMS 数据订阅要求', async () => { const resp = await axios.get( `${config.cloudApi.baseUrl}/api/v1/inverters/INV-001/realtime`, { timeout: config.cloudApi.timeoutMs } ); expect(resp.status).toBe(200); const ajv = new Ajv(); const validate = ajv.compile(inverterReportSchema); const valid = validate(resp.data); expect(valid).toBe(true); if (validate.errors) { console.error(JSON.stringify(validate.errors, null, 2)); } }); });

逻辑说明：这里拿到的 resp.data 是云监控系统自己接口返回的实时数据，还没到 DREAMS 侧。为什么先测这一层？因为如果云监控自身的接口字段都不满足规范，那后面推给 DREAMS 的报文必然有问题。在这一层拦截，联调成本最低，也最容易定位问题。

参数说明：timeoutMs 用的是 config 里的值，避免用例之间同步超时配置。schema 文件放在 fixtures/schemas 下，从 DREAMS 规范的字段定义表转成 JSON Schema，这一步是体力活，但转完一次后面所有上报用例都能复用。URL 路径/api/v1/inverters/INV-001/realtime是示例路径，真实环境要以云监控系统的接口文档为准，建议把路径也放进 config，不要在用例代码里到处写死。

3.4 执行与报告：JUnit XML 和 Allure 的落地配置

跑用例的姿势要固定，先安装依赖，再执行带报告的脚本：

npm ci npm run test:report

jest.config.js 里把 JUnit reporter 的输出路径指到 reports 目录：

module.exports = { testEnvironment: 'node', testTimeout: 30000, reporters: [ 'default', ['jest-junit', { outputDirectory: 'reports/junit', outputName: 'joint-test.xml', classNameTemplate: '{filepath}', titleTemplate: '{title}' }] ] };

逻辑说明：testTimeout 设 30000 毫秒，是因为里面有用例要模拟断网等待和补报窗口，太短会导致用例误报。outputDirectory 和 outputName 指定 JUnit XML 的落盘位置，这类文件是整个验收材料里最直接的自动化证据。

参数说明：classNameTemplate 用 {filepath}，titleTemplate 用 {title}，这样 XML 里能直接看到用例来源文件和标题，评审时不用再翻源码定位。跑完以后看 reports/junit/joint-test.xml，用 Allure 或任何能渲染 JUnit 的工具打开。我习惯的检查顺序是先看失败用例属于哪个数据域，再对照第 2 章的五个域定位是配置问题、字段映射问题还是模拟器问题，不要一上来就改代码。

4. 写模拟器与异常注入：没有真实逆变器也能压出链路问题

云光伏监控系统的联调难点之一是现场没有真实设备时，DREAMS 验收没法做。这个存储库用模拟器代替真实逆变器和采集网关，把链路先跑起来。下面讲怎么用 Node.js 内置的 net 模块写一个最小可用的 Modbus TCP 逆变器模拟器。

4.1 手写一个 Modbus TCP 逆变器模拟器

Modbus TCP 帧由 MBAP 头加 PDU 组成，读取保持寄存器的功能码是 0x03。模拟器只需要监听一个端口，收到读请求后按寄存器地址返回对应的有功、无功、发电量数值：

const net = require('net'); const registers = { 0: 5000, // 有功功率，0.1kW 单位，实际值 500.0kW 1: 200, // 无功功率，0.1kVar 2: 125000, // 日发电量，0.1kWh 3: 9800 // 功率因数，0.0001，实际 0.98 }; const server = net.createServer((socket) => { socket.on('data', (buf) => { if (buf.length < 8) return; const transactionId = buf.readUInt16BE(0); const protocolId = buf.readUInt16BE(2); const unitId = buf.readUInt8(6); const functionCode = buf.readUInt8(7); if (protocolId !== 0 || functionCode !== 0x03) return; const startAddress = buf.readUInt16BE(8); const quantity = buf.readUInt16BE(10); const byteCount = quantity * 2; const response = Buffer.alloc(9 + byteCount); response.writeUInt16BE(transactionId, 0); response.writeUInt16BE(protocolId, 2); response.writeUInt16BE(byteCount + 3, 4); response.writeUInt8(unitId, 6); response.writeUInt8(functionCode, 7); response.writeUInt8(byteCount, 8); for (let i = 0; i < quantity; i++) { const value = registers[startAddress + i] || 0; response.writeUInt16BE(value, 9 + i * 2); } socket.write(response); }); }); server.listen(5020, '127.0.0.1', () => { console.log('inverter simulator listening on 5020'); });

逻辑说明：这段代码的核心是构造 Modbus TCP 响应帧。transactionId 必须原样带回，客户端靠它匹配请求和响应，很多联调问题就出在这个字段被模拟器改了。长度字段 byteCount + 3 表示 unitId、functionCode、byteCount 加上寄存器数据的总字节数，写错会导致客户端解析错位，这是手写协议栈最容易翻车的地方。

参数说明：registers 对象的地址映射是典型的逆变器保持寄存器布局，具体厂商可能用不同的地址表。常见做法是把这个地址表放到配置文件里，模拟器启动时读取，换设备型号不用改代码。如果你要模拟多台逆变器，就让模拟器监听多个端口，每个端口对应一台设备的地址表。

启动脚本可以写成这样，把模拟器进程和测试串起来：

#!/usr/bin/env bash set -euo pipefail node simulators/inverter-sim.js --port 5020 & SIM_PID=$! sleep 1 npm run test:report kill $SIM_PID

set -euo pipefail防止脚本中途静默失败；sleep 1 是等端口监听就绪，端口如果被占用，模拟器会直接抛异常退出，测试也不会继续。kill 放在测试结束之后，保证端口不残留。

4.2 异常注入：时间戳漂移、负功率和乱序重复帧

模拟器能跑正常链路后，下一步是让它产出坏数据，验证云监控系统能否识别和规避。我一般把异常注入做成独立的 mutator 函数，测试时传入帧数据，返回篡改后的帧：

function mutateFrame(frame, mutationType) { const copy = Buffer.from(frame); switch (mutationType) { case 'negative_power': copy.writeUInt16BE(0xFFFF, 9); // 补码表示 -1 break; case 'reversed_order': return Buffer.concat([copy.slice(6), copy.slice(0, 6)]); case 'duplicate_frame': return Buffer.concat([copy, copy]); default: return copy; } }

逻辑说明：negative_power 用例把有功寄存器写到 0xFFFF，在补码表示里就是 -1，云监控侧应该把这个值判定为无效或触发告警；reversed_order 把 MBAP 头和 PDU 对调，测试协议解析器的容错能力；duplicate_frame 直接拼两帧同样的数据，测试云端会不会重复入库。

参数说明：timestamp_drift 在 Modbus 链路里改不了，因为 Modbus 本身没有时间戳。真正要测时间戳漂移，应该在应用层上报接口做注入，比如云监控的 REST API 或消息队列里把 timestamp 字段偏移几分钟。这个用例更适合放在第 3 章的上报断言用例里，配合 mock 数据源来跑。

4.3 用 test.each 把异常用例参数化

Jest 的 test.each 很适合把"正常帧加多种异常帧"放进一张参数表。每个用例只描述期望行为，输入数据和期望值分开维护：

describe('异常帧容错', () => { test.each([ ['negative_power', '应用层应判定为无效功率'], ['reversed_order', '协议层应丢弃错序帧'] ])('%s：%s', async (mutationType) => { const client = await connectToSimulator(); const normalFrame = createReadRequestFrame(0, 4); const mutated = mutateFrame(normalFrame, mutationType); client.write(mutated); const response = await waitForResponse(client, 3000); if (mutationType === 'reversed_order') { expect(response.length).toBe(0); } else { expect(response.length).toBeGreaterThan(0); } }); });

逻辑说明：mutateFrame 根据 mutationType 决定怎么改帧，测试用例只描述期望结果。reversed_order 期望协议层丢弃错序帧，即响应为空；negative_power 期望模拟器正常响应，不做底层拦截，因为负功率能不能被识别为无效，要由云监控的上层逻辑决定，这个用例断言的是链路没有被异常帧打挂。

参数说明：waitForResponse 的 3000 毫秒是超时上限，具体值需要根据被测系统的处理链路调整，链路长就调大。connectToSimulator 每次用例重新建连，避免前一个用例的 socket 状态影响下一个，这也是整个测试必须用 --runInBand 串行跑的另一个原因。

5. 联测避坑手记：五条验收翻车记录与排查顺序

联测阶段有些问题看起来像玄学，查到最后基本都是配置、字段映射或依赖版本的问题。下面这几条算得上血泪经验，每条都按现象、原因、解决三个顺序写，方便你对着排查。

5.1 数据类避坑：超时判定、时区换算、断点补报窗口

第一条，DREAMS 界面频繁提示"数据超时"，本地看上报日志却一直正常。原因通常是上报周期本身有抖动，云监控按固定周期加固定容忍窗口判定，一旦某次上报晚了几秒，就进入超时状态。解决方式是改成滑动窗口统计，在配置里把容忍窗口从 5 秒放宽到上报周期的一半，比如 300 秒周期配 150 秒容忍窗口，同时增加上报成功率的监控指标，别等 DREAMS 侧先报警。

第二条，跨天之后曲线断档。界面曲线每天零点前后缺一段，数据明细里却查得到记录。原因是云监控内部按北京时间生成时间戳，上报后按 UTC 存库，界面没有再按本地时区回显，导致跨天那一小时看起来是空的。解决方式是统一时间戳格式为 ISO8601 并带上时区偏移，界面展示层按操作员时区换算，存储层一律 UTC，不混用。这条排查起来很费时间，因为它涉及存储、上报和展示三层，建议把时间戳格式直接写进 JSON Schema 的 format 字段，从用例层拦住。

第三条，断线恢复后，DREAMS 侧看到的是缺了一截而不是连续数据。原因基本是补报窗口配小了。不少平台默认补报窗口是 10 分钟，但验收规范写的是不小于 15 分钟。解决方式是先把 acceptance.complementWindowMin 改成 15 甚至更大，然后重启云监控的采集服务，观察补报任务的日志，确认缓存数据全部按序上送。这条我在第 1 章开头提到的场景里实际踩过，当时连续折腾了几个通宵，最后只是改一个配置值。

5.2 链路类避坑：指令回执、依赖锁定、多连接并发窗口

第四条，功率控制指令在本地模拟环境里响应正常，一进验收环境就超时。排查后发现，云监控把"指令已收到"和"指令已执行"合成一个字段上报，DREAMS 侧期望的是两个独立事件，先收到回执再等执行结果。解决方式是拆事件流：收到指令后立刻上报 receipt 事件，执行完成后上报 result 事件，两个事件的状态码分开定义。这个坑的隐蔽之处在于本地模拟器没有严格校验事件流，验收侧才暴露出来。

第五条，同一套用例在 CI 环境跑不过，本地几乎全绿。这种情况优先怀疑依赖，不是业务代码。package-lock.json 没有提交，导致 npm install 在不同时间解析出不同版本，某个私有依赖升级后改变了报文校验逻辑，长度校验失败。解决方式是提交 package-lock.json，在 CI 里改用 npm ci 而不是 npm install，同时在 .nvmrc 里固定 Node 主版本。从那以后，我所有联测仓库都强制提交 lock 文件，并在 CI 的第一条检查 Node 版本。

排查顺序建议是：当 DREAMS 联测失败时，先看时间戳格式和补报窗口配置，再看指令回执状态拆分，最后查依赖版本。前两个是业务侧最容易改错的点，最后一个是环境侧最容易背锅的点。按这个顺序排查，大多数问题都能在一轮内定位。

6. 进阶用法：黄金报文比对让每次发布自带并网体检报告

联测用例跑通只是第一步，更重要的价值是把它变成回归基线。我常用的进阶做法是黄金报文比对：把 DREAMS 规范里的样例报文整理成 fixtures/golden 目录下的 JSON 文件，每次被测系统上报后，把实际报文和 golden 文件做结构化比对。

// scripts/verify-golden.js const fs = require('fs'); const path = require('path'); const goldenDir = path.join(__dirname, '../fixtures/golden'); const actualPath = path.join(__dirname, '../reports/last-upload.json'); const golden = JSON.parse(fs.readFileSync(path.join(goldenDir, 'realtime.json'), 'utf8')); const actual = JSON.parse(fs.readFileSync(actualPath, 'utf8')); function diffKeys(a, b, prefix = '') { const problems = []; for (const key of Object.keys(a)) { if (JSON.stringify(a[key]) !== JSON.stringify(b[key])) { problems.push(`${prefix}${key}`); } } return problems; } const problems = diffKeys(golden, actual); if (problems.length > 0) { console.error('golden mismatch:', problems.join(', ')); process.exit(1); } console.log('golden check passed');

逻辑说明：这个脚本只做一层 key 比对，真实场景建议用 deepStrictEqual 或专门的 JSON diff 库。重点是比对基线不是代码 Reviewer 人肉定的，而是从规范文档里整理出来的样例，这样每次更新字段映射后跑一遍，能自动发现不兼容改动。我在 scripts 里还挂了一个 verify:golden 的 npm script，和 Jest 用例并行跑。

参数说明：process.exit(1) 让脚本在 CI 里失败时能阻断发布流程。reports/last-upload.json 是被测系统最近一次上报的原始报文，可以来自云监控的调试接口，也可以从上报日志里取最近一条。拿到存储库时第一件事是把 fixtures/golden 目录清空，换成你自己接入省份规范的样例报文，再去改 config 里的阈值。

从那以后，我每次改完上报逻辑，都会强制走一遍 verify:golden 再提测，这个习惯帮我挡掉了至少三次字段映射回归。希望帮到你。

本文还有配套的精品资源，点击获取