4.1 API 概述与认证

LPPLC 服务器对外只暴露 HTTP POST 端点，没有 REST 风格的多路径设计，也没有 /api/ 前缀。所有操作都往同一个地址 POST 一段 JSON，用 JSON 里的 cmd 字段区分要做什么。

4.1.1 端点

方法	路径	用途
POST	/web	统一调用入口，前端和外部程序都用这个
POST	/JSON	早期通道，仍兼容
POST	/ccb	水电气计费专用通道

项	值
HTTP	http://{服务器IP}/web（端口 80）
HTTPS	https://{服务器IP}/web（端口 443）
请求方法	POST
请求体	JSON，UTF-8

4.1.2 认证

没有 Token，没有独立登录接口。每个请求都在 body 里明文带 username 和 password：

{
  "cmd": "get_real",
  "username": "linpan",
  "password": "你的密码",
  "project": "main",
  "data": ["车间1/1号机/温度"]
}

关键字段是 cmd，不是 function

操作名字段是 cmd。服务器按 cmd 的值分发到对应处理函数，写成 function 或 action 都不会被识别。

部分接口还支持这两个可选字段：

字段	用途
userson	子账号名。username/password 仍填主账号，userson 用于记录是哪个子账号做的操作
id	请求标识，服务器会原样带回响应，用于在长连接上做请求-响应配对

4.1.3 响应结构

所有响应都是 JSON，靠 cmdreq 字段判断结果：

{ "cmdreq": "ok", "data": [ ... ] }

cmdreq	含义
ok	成功
error	通用失败（多数是账号密码错，或参数不合法）
noMore	查询没有更多数据（分页到底、关键字无匹配）
no id	缺少 id 字段（设备类接口没指定目标设备）
user error	认证失败

判断成功需看 cmdreq，不能只看 HTTP 状态码：业务失败时 HTTP 状态码通常仍是 200。

4.1.4 明文与 AES 两种传输模式

服务器同时支持明文和加密两种请求体：

明文模式（推荐用于自己的后台程序对接）

Content-Type: application/json

{"cmd":"get_real","username":"...","password":"...","data":["点名"]}

AES 模式（云组态前端用的就是这种）

请求头带 lp 标记，body 整体是加密后的字符串：

Content-Type: text/plain
lp: aes

<AES-128-ECB 加密并 Base64 编码后的 JSON 字符串>

算法为 AES-128-ECB + Base64，请求和响应都加密。密钥是服务器与前端约定的固定值，需要用 AES 模式对接的请联系技术支持获取。

自己写程序对接就用明文

AES 模式的存在是为了让浏览器端的请求体不至于明文可读，并不构成真正的安全边界（密钥是固定的）。外部程序对接直接用明文模式即可，真正的传输安全靠 HTTPS。

4.1.5 安全建议

username/password 明文出现在每个请求体里，所以：

• 公网部署必须用 HTTPS，不要使用 80 端口明文传输
• 给对接程序单独开一个子账号，不要用主账号
• 不要把账号密码硬编码在前端页面或客户端 App 里，这等同于公开发布

HTTPS 配置见 2.3 HTTPS 证书配置。

4.1.6 接口分类去哪看

需求	章节
读写实时数据点、直读直写 PLC 寄存器	4.3 实时数据接口
查历史数据	4.4 历史数据接口
组态工程的增删改查	4.2 组态管理接口
完整可运行示例（curl / Python / Node.js）	4.5 调用示例
设备端用 HTTP 上报数据	4.6 设备端 HTTP 上报

4.1.7 常见错误

现象	原因
连接被拒绝	HTTP 服务未启动，或 80/443 被其它程序占用
返回 error	账号密码错；或必填字段缺失
返回 user error	认证失败
返回 no id	设备类接口没带 id（设备 ID）
请求发出去没反应	用了 function 而不是 cmd，服务器找不到对应操作
返回乱码	请求未按 UTF-8 编码，或误用了 AES 模式解析明文响应

---