适配器Node IPC
生命周期和错误
处理 Node IPC 会话、守护进程重启和结构化错误。
本页介绍守护进程启动、残留套接字清理、连接断开行为和错误码。
守护进程启动
守护进程启动时依次执行:
- 将精确连接目标解析为套接字路径
- 验证路径安全性与长度
- 检查运行目录的安全性
- 检查套接字路径是否已存在
- 在安全的前提下清理失效的残留套接字文件
- 开始监听
无法确定某项安全检查是否通过时,启动会失败,不会猜测后继续执行。
与正在运行的守护进程冲突
如果另一个进程已占用套接字并接受连接,启动会失败并返回:
E_IPC_ADDRESS_IN_USE这可避免新进程使用相同的 appId 和 instance 抢占已有守护进程。
清理残留套接字
进程崩溃后,Unix 套接字文件可能残留。
适配器会探测已有套接字;确认它已失效后,才会在监听前移除残留文件。
只有套接字文件可参与这类清理,普通文件和符号链接不会被移除。
清理失败时返回:
E_IPC_STALE_SOCKET_CLEANUP_FAILED连接生命周期
底层套接字连接建立后,Nexus Core 执行逻辑握手。
只有完成以下步骤,连接才可用:
- 若配置了适配器预认证,认证通过
- 完成 Core 握手消息交换
- 若配置了
policy.canConnect,连接获准通过
握手超时可避免无限等待那些只接受套接字连接、却不完成 Nexus 握手的对端。
守护进程重启
守护进程关闭或重启后,客户端已有的代理会失效。
Nexus 句柄绑定到会话:
- 旧连接上的代理调用会失败
- 旧远程引用失效
- 开始新任务前,需要重新连接并获取新代理
这是明确的生命周期边界。Nexus 不会自动将旧代理转向守护进程的新会话。
错误代码
Node IPC 适配器错误:
| Code | 含义 |
|---|---|
E_IPC_ADDRESS_INVALID | 连接目标或解析结果无法产生有效套接字地址。 |
E_IPC_ADDRESS_IN_USE | 套接字已被正在运行的守护进程占用。 |
E_IPC_PATH_TOO_LONG | 文件系统套接字路径超过平台长度限制。 |
E_IPC_CONNECT_FAILED | 底层套接字连接失败。 |
E_IPC_AUTH_FAILED | 共享密钥预认证失败或超时。 |
E_IPC_PROTOCOL_ERROR | 消息分帧或预认证协议格式错误。 |
E_IPC_STALE_SOCKET_CLEANUP_FAILED | 无法安全移除失效的残留套接字文件。 |
Node IPC 中常见的 Core 授权错误:
| Code | 含义 |
|---|---|
E_AUTH_CONNECT_DENIED | policy.canConnect 拒绝握手。 |
E_AUTH_CALL_DENIED | policy.canCall 拒绝服务调用。 |
调试清单
启动失败时:
- 打印解析出的套接字路径。
- 检查是否已有使用相同
appId和instance的守护进程。 - 检查目录所有权和权限。
- 检查套接字路径是否被普通文件或符号链接占用。
- 检查路径是否超过 Unix 套接字的长度限制。
调用失败时:
- 检查适配器预认证是否成功。
- 检查
policy.canConnect。 - 检查
policy.canCall。 - 检查代理是否在守护进程重启之前获取。
- 重新连接并获取新代理。