kpine/zwave-js-server

zwave-js-server-docker

一个极简的Docker容器，用于运行https://github.com/zwave-js/zwave-js-server/%E3%80%82%E6%AD%A4%E5%AE%B9%E5%99%A8%E4%BB%85%E6%8F%90%E4%BE%9B%E5%8F%AF%E7%94%A8%E7%9A%84Z-Wave JS Server，其他功能较少。

如需同时提供服务器和更多功能的应用，请使用https://github.com/zwave-js/zwave-js-ui%E3%80%82

Docker配置

Z-Wave JS驱动将Z-Wave网络信息存储在一组缓存文件中。服务器重启时，驱动会从缓存加载网络信息。若无此信息，网络无法立即完全使用。因此，容器重启之间必须持久化缓存文件。

以下docker run示例使用环境文件提供所有Z-Wave网络密钥。

shell
$ cat .env
S2_ACCESS_CONTROL_KEY=7764841BC794A54442E324682A550CEF
S2_AUTHENTICATED_KEY=66EA86F088FFD6D7497E0B32BC0C8B99
S2_UNAUTHENTICATED_KEY=2FAB1A27E19AE9C7CC6D18ACEB90C357
S0_LEGACY_KEY=17DFB0C1BED4CABFF54E4B5375E257B3
LR_S2_ACCESS_CONTROL_KEY=61BEF779F9DF0827CD9870B719D074BB
LR_S2_AUTHENTICATED_KEY=905B869063266296AE5159EEDBEE038D
RF_REGION=USA (Long Range)

使用卷挂载运行

shell
# 创建持久卷用于驱动缓存
$ docker volume create zjs-storage

# 启动服务器并使用卷作为持久缓存目录
$ docker run -d -p 3000:3000 --name=zjs -v zjs-storage:/cache --env-file=.env --device "/dev/serial/by-id/usb-0658_0200-if00:/dev/zwave" ghcr.io/kpine/zwave-js-server:latest

使用绑定挂载运行

shell
# 启动服务器并使用本地文件夹作为持久缓存目录
$ docker run -d -p 3000:3000 --name=zjs -v "$PWD/cache:/cache" --env-file=.env --device "/dev/serial/by-id/usb-0658_0200-if00:/dev/zwave" ghcr.io/kpine/zwave-js-server:latest

Docker Compose配置

Docker Compose是维护容器配置的简单方式。

最小化docker-compose.yaml文件示例：

yaml
services:
  zjs:
    container_name: zjs
    image: ghcr.io/kpine/zwave-js-server:latest
    restart: unless-stopped
    environment:
      - "S2_ACCESS_CONTROL_KEY=7764841BC794A54442E324682A550CEF"
      - "S2_AUTHENTICATED_KEY=66EA86F088FFD6D7497E0B32BC0C8B99"
      - "S2_UNAUTHENTICATED_KEY=2FAB1A27E19AE9C7CC6D18ACEB90C357"
      - "S0_LEGACY_KEY=17DFB0C1BED4CABFF54E4B5375E257B3"
      - "LR_S2_ACCESS_CONTROL_KEY=61BEF779F9DF0827CD9870B719D074BB"
      - "LR_S2_AUTHENTICATED_KEY=905B869063266296AE5159EEDBEE038D"
      - "RF_REGION=USA (Long Range)"
    devices:
      - "/dev/serial/by-id/usb-0658_0200-if00:/dev/zwave"
    volumes:
      - ./cache:/cache
    ports:
      - "3000:3000"

环境变量

• LOGTOFILE: 设置为true可https://zwave-js.github.io/node-zwave-js/#/api/driver?id=logconfig%E9%A9%B1%E5%8A%A8%E8%AE%B0%E5%BD%95%E6%97%A5%E5%BF%97%E5%88%B0%E6%96%87%E4%BB%B6%E3%80%82
• LOGFILENAME: 配置驱动日志文件名（仅当LOGTOFILE为true时使用）。默认值为/logs/zwavejs，生成文件名格式为zwavejs_%DATE%.log。驱动会自动按日期轮转日志文件。
• LOGMAXFILES: 配置保留日志文件的最大数量。Z-Wave JS每天轮转一次日志，因此此值对应保留日志的天数。
• LOGLEVEL: 配置驱动日志级别，详见https://zwave-js.github.io/node-zwave-js/#/api/driver?id=logconfig%E3%80%82
• S2_ACCESS_CONTROL_KEY: S2访问控制安全类的网络密钥。
• S2_AUTHENTICATED_KEY: S2认证安全类的网络密钥。
• S2_UNAUTHENTICATED_KEY: S2未认证安全类的网络密钥。
• S0_LEGACY_KEY: S0（传统）安全类的网络密钥。
• LR_S2_ACCESS_CONTROL_KEY: 长距离S2访问控制安全类的网络密钥。
• LR_S2_AUTHENTICATED_KEY: 长距离S2认证安全类的网络密钥。
• RF_REGION: 无线电调谐的https://github.com/zwave-js/node-zwave-js/blob/0c2e03ea57490f1b361f600b32d595b25f26c1a6/packages/core/src/capabilities/RFRegion.ts#L2-L14%E3%80%82%E8%AE%BE%E7%BD%AE%E5%90%8E%EF%BC%8C%E9%A9%B1%E5%8A%A8%E4%BC%9A%E7%A1%AE%E4%BF%9D%E5%8C%BA%E5%9F%9F%E4%B8%BA%E6%8C%87%E5%AE%9A%E5%80%BC%E3%80%82%E9%BB%98%E8%AE%A4%E6%9C%AA%E8%AE%BE%E7%BD%AE%EF%BC%8C%E6%8E%A7%E5%88%B6%E5%99%A8%E4%BF%9D%E6%8C%81%E5%BD%93%E5%89%8D%E5%8C%BA%E5%9F%9F%E3%80%82
• USB_PATH: Z-Wave USB控制器的设备路径。默认为/dev/zwave。若主机设备路径已映射为/dev/zwave，则无需此变量。
• FIRMWARE_UPDATE_API_KEY: 用于访问Z-Wave JS固件更新服务的API密钥。默认未配置。通常无需配置，除非是商业用户。详见固件更新API密钥部分。
• ENABLE_DNS_SD: 设置为true启用DNS服务发现。默认禁用。仅在使用主机网络时生效。

目录

• /cache - 驱动的https://zwave-js.github.io/node-zwave-js/#/api/driver?id=zwaveoptions%E3%80%82%E5%BF%85%E9%A1%BB%E6%8C%82%E8%BD%BD%E5%8D%B7%E6%88%96%E7%BB%91%E5%AE%9A%E6%8C%82%E8%BD%BD%E6%AD%A4%E7%9B%AE%E5%BD%95%EF%BC%8C%E4%BB%A5%E5%9C%A8%E5%AE%B9%E5%99%A8%E9%87%8D%E5%90%AF%E9%97%B4%E6%8C%81%E4%B9%85%E5%8C%96%E7%BD%91%E7%BB%9C%E4%BF%A1%E6%81%AF%E3%80%82
• /cache/config - 驱动的https://zwave-js.github.io/node-zwave-js/#/api/driver?id=zwaveoptions%E3%80%82%E7%94%A8%E4%BA%8E%E5%8A%A0%E8%BD%BD%E8%87%AA%E5%AE%9A%E4%B9%89%E8%AE%BE%E5%A4%87%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E3%80%82%E8%8B%A5%60/cache%60%E6%98%AF%E5%91%BD%E5%90%8D%E5%8D%B7%EF%BC%8C%E6%AD%A4%E7%9B%AE%E5%BD%95%E4%BC%9A%E8%87%AA%E5%8A%A8%E5%88%9B%E5%BB%BA%EF%BC%9B%E5%90%A6%E5%88%99%E9%9C%80%E6%89%8B%E5%8A%A8%E5%88%9B%E5%BB%BA%E6%88%96%E6%8C%82%E8%BD%BD%E3%80%82
• /logs - 启用文件日志时，驱动日志文件的存储目录。挂载卷或绑定挂载此目录可在容器外访问和保存日志文件。

端口

• 3000 - zwave-js-server的WebSocket端口。外部应用（如Home Assistant）需连接此端口与服务器交互。

详细说明

网络密钥

所有网络密钥必须是16字节的十六进制字符串（32字符）。生成随机网络密钥的简单命令：

shell
$ < /dev/urandom tr -dc A-F0-9 | head -c32 ; echo
8387D66323E8209C58B0C317FD1F4251

所有密钥应唯一；多个安全类共享密钥存在安全风险。详见Z-Wave JS的https://zwave-js.github.io/node-zwave-js/#/getting-started/security-s2?id=key-management%E6%96%87%E6%A1%A3%E3%80%82

至少需要S0（传统）网络密钥，否则zwave-js-server将无法启动。S2密钥可选但强烈推荐；若未指定，将无法使用S2包含。

USB路径

建议将USB控制器设备路径映射到容器的/dev/zwave，而非使用USB_PATH环境变量。

控制器固件更新（OTW）

Docker镜像包含@zwave-js/flash命令行工具，支持控制器的有线（OTW）固件更新。下载控制器对应的固件文件，执行以下命令（更新前需停止Z-Wave JS服务器）：

shell
docker run --rm -it -v "$PWD/fw:/fw" --device "/dev/ttyUSB0:/dev/zwave" ghcr.io/kpine/zwave-js-server:latest flash /fw/fw.gbl

命令默认使用/dev/zwave设备路径，或USB_PATH环境变量指定的路径。

更多信息见https://github.com/kpine/zwave-js-server-docker/wiki/700-series-Controller-Firmware-Updates-(Linux)%E3%80%82

用户设备配置文件

使用/cache/config目录可轻松测试新设备配置文件或修改现有文件。此目录中的文件会补充或覆盖内置设备配置数据库。容器重启后，驱动日志会指示加载的文件：

text
2021-06-19T06:19:18.506Z CNTRLR   [Node 007] 已加载内置设备配置
2021-06-19T06:21:43.793Z CNTRLR   [Node 008] 已加载用户提供的设备配置

串行软重置

Z-Wave JS在启动时及NVM备份/恢复等操作中会对Z-Wave控制器执行软重置（重启）。部分控制器可能因软重置导致USB断开，影响容器运行时或主机配置。若观察到USB设备无法识别，可通过设置ZWAVEJS_DISABLE_SOFT_RESET环境变量，或设置驱动功能选项softReset为false禁用软重置。详见https://zwave-js.github.io/node-zwave-js/#/api/driver?id=softreset%E5%92%8Chttps://zwave-js.github.io/node-zwave-js/#/api/driver?id=zwaveoptions%E6%96%87%E6%A1%A3%E3%80%82

若禁用软重置后仍有问题，可能需要禁用无响应控制器恢复功能。通过设置ZWAVEJS_DISABLE_UNRESPONSIVE_CONTROLLER_RECOVERY环境变量，或设置unresponsiveControllerRecovery驱动功能选项为false。详见https://zwave-js.github.io/node-zwave-js/#/api/driver?id=zwaveoptions%E6%96%87%E6%A1%A3%E3%80%82

缓存锁文件

Z-Wave JS使用目录作为锁文件，防止多个进程同时修改缓存文件，避免缓存损坏。锁文件位于缓存目录中，与实际缓存文件相邻。锁机制每约1秒更新锁文件的mtime（修改时间）。若存储介质（如SD卡）对频繁写入敏感，可将锁文件移至tmpfs等目录。通过设置ZWAVEJS_LOCK_DIRECTORY环境变量指定替代路径（建议为主机的tmpfs）。Compose文件示例片段：

yaml
services:
  zjs:
    environment:
      ZWAVEJS_LOCK_DIRECTORY: "/run/lock/zwave-js"
    volumes:
      - /run/lock/zwave-js:/run/lock/zwave-js

环境变量指示Z-Wave JS将锁文件存储在/run/lock/zwave-js。卷配置将主机的/run/lock/zwave-js（通常为tmpfs）映射到容器相同路径。最终锁文件存储在主机的tmpfs中。/run/lock通常挂载为tmpfs，/tmp/zwave-js也是可选路径。

注意：主机上集中存储锁文件可确保多个相同配置的容器感知锁机制。但若其他Z-Wave JS实例未配置相同锁目录，将绕过锁保护，可能导致缓存损坏。默认位置的锁文件对所有默认配置实例可见，使用此功能时需谨慎。

固件更新API密钥

Z-Wave JS提供https://github.com/zwave-js/firmware-updates/%E8%8E%B7%E5%8F%96%E8%AE%BE%E5%A4%87%E5%9B%BA%E4%BB%B6%E6%9B%B4%E6%96%B0%E4%BF%A1%E6%81%AF%EF%BC%8C%E9%9C%80API%E5%AF%86%E9%92%A5%E3%80%82Z-Wave JS组织为该项目提供了非商业用途的密钥；商业用户必须https://github.com/zwave-js/firmware-updates#api-keys%E5%B9%B6%E9%85%8D%E7%BD%AE%E8%87%AA%E5%B7%B1%E7%9A%84%E5%AF%86%E9%92%A5%E3%80%82

若使用Home Assistant的Z-Wave集成，无需启用或安装API密钥——集成访问固件更新API时会提供密钥。其他客户端应用若自带密钥也无需配置。

若客户端不支持自带密钥且为非商业用户，可将FIRMWARE_UPDATE_API_KEY设为-启用内置密钥，此时即表示您是非商业用户。

商业用户需将FIRMWARE_UPDATE_API_KEY设为自行申请的密钥。

默认FIRMWARE_UPDATE_API_KEY为空，不配置密钥。此时客户端应用需自行设置密钥，否则固件更新服务可能无法使用或受更严格的速率限制。