zwave-js-server-docker

一个极简的Docker容器，用于运行Z-Wave JS Server。此容器仅提供可用的Z-Wave JS Server，其他功能较少。

如需同时提供服务器和更多功能的应用，请使用Z-Wave JS UI。

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可配置驱动记录日志到文件。
• LOGFILENAME: 配置驱动日志文件名（仅当LOGTOFILE为true时使用）。默认值为/logs/zwavejs，生成文件名格式为zwavejs_%DATE%.log。驱动会自动按日期轮转日志文件。
• LOGMAXFILES: 配置保留日志文件的最大数量。Z-Wave JS每天轮转一次日志，因此此值对应保留日志的天数。
• LOGLEVEL: 配置驱动日志级别，详见文档。
• 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: 无线电调谐的RF区域。设置后，驱动会确保区域为指定值。默认未设置，控制器保持当前区域。
• USB_PATH: Z-Wave USB控制器的设备路径。默认为/dev/zwave。若主机设备路径已映射为/dev/zwave，则无需此变量。
• FIRMWARE_UPDATE_API_KEY: 用于访问Z-Wave JS固件更新服务的API密钥。默认未配置。通常无需配置，除非是商业用户。详见固件更新API密钥部分。
• ENABLE_DNS_SD: 设置为true启用DNS服务发现。默认禁用。仅在使用主机网络时生效。

目录

• /cache - 驱动的缓存目录。必须挂载卷或绑定挂载此目录，以在容器重启间持久化网络信息。
• /cache/config - 驱动的设备配置优先级目录。用于加载自定义设备配置文件。若/cache是命名卷，此目录会自动创建；否则需手动创建或挂载。
• /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的密钥管理文档。

至少需要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环境变量指定的路径。

更多信息见维基页面)。

用户设备配置文件

使用/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禁用软重置。详见softReset和ZWaveOptions文档。

若禁用软重置后仍有问题，可能需要禁用无响应控制器恢复功能。通过设置ZWAVEJS_DISABLE_UNRESPONSIVE_CONTROLLER_RECOVERY环境变量，或设置unresponsiveControllerRecovery驱动功能选项为false。详见ZWaveOptions文档。

缓存锁文件

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提供在线Web服务获取设备固件更新信息，需API密钥。Z-Wave JS组织为该项目提供了非商业用途的密钥；商业用户必须申请并配置自己的密钥。

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

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

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

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