webthingsio/gateway

WebThings Gateway Docker镜像文档

一、镜像概述与主要用途

基于Debian Bookworm构建的Docker镜像，用于运行https://github.com/WebThingsIO/gateway%EF%BC%88%E7%89%A9%E8%81%94%E7%BD%91%E7%BD%91%E5%85%B3%EF%BC%89%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E6%94%AF%E6%8C%81AMD64%E3%80%81ARMv7%E5%92%8CARMv8%EF%BC%88AArch64%EF%BC%89%E6%9E%B6%E6%9E%84%EF%BC%8C%E6%8F%90%E4%BE%9B%E8%B7%A8%E5%B9%B3%E5%8F%B0%E7%9A%84%E7%89%A9%E8%81%94%E7%BD%91%E8%AE%BE%E5%A4%87%E7%AE%A1%E7%90%86%E8%83%BD%E5%8A%9B%E3%80%82

二、核心功能与特性

• 多架构支持：兼容AMD64、ARMv7、ARMv8架构，适用于服务器、嵌入式设备（如树莓派）等多种硬件环境。
• 持久化存储：通过数据卷挂载实现用户配置、附加组件、日志等数据的持久化保存。
• 灵活网络配置：支持主机网络模式（--network="host"）以满足部分附加组件的网络需求，同时也支持端口映射模式。
• 时区自定义：通过环境变量配置容器时区，确保日志和定时任务时间准确。

三、兼容性说明

• 网络模式限制：部分附加组件需依赖本地网络访问能力，建议使用--network="host"（主机网络模式）。但该模式在Docker for Mac和Docker for Windows中不适用，原因是https://github.com/docker/for-mac/issues/68%E5%92%8Chttps://github.com/docker/for-win/issues/543%E3%80%82

四、使用方法

4.1 Linux系统

shell
docker run \
    -d \
    -e TZ=Asia/Shanghai \
    -v /path/to/local/data:/home/node/.webthings \
    --network="host" \
    --log-opt max-size=1m \
    --log-opt max-file=10 \
    --name webthings-gateway \
    webthingsio/gateway:latest

4.2 Windows/macOS系统

（因不支持--network="host"，需手动映射端口）

shell
docker run \
    -d \
    -p 8080:8080 \
    -p 4443:4443 \
    -e TZ=Asia/Shanghai \
    -v /path/to/local/data:/home/node/.webthings \
    --log-opt max-size=1m \
    --log-opt max-file=10 \
    --name webthings-gateway \
    webthingsio/gateway:latest

五、参数说明

六、配置说明

6.1 修改--network="host"模式下的端口

当使用主机网络模式时，默认端口为HTTP 8080、HTTPS 4443。如需修改，需创建local.json配置文件并挂载到容器中：

1. 在主机的持久化目录（即/path/to/local/data）下创建config/local.json文件，内容如下：

   json
   {
     "ports": {
       "https": 8081,  // 自定义HTTPS端口
       "http": 8080    // 自定义HTTP端口
     }
   }
   

2. 重启容器使配置生效。

6.2 使用docker-compose部署

创建docker-compose.yml文件（示例配置，根据实际环境调整）：

yaml
version: '3'
services:
  webthings-gateway:
    image: webthingsio/gateway:latest
    container_name: webthings-gateway
    restart: always
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - /path/to/local/data:/home/node/.webthings
    network_mode: host  # Linux系统推荐；Windows/macOS需替换为ports配置
    # ports:  # Windows/macOS使用时取消注释并配置
    #   - "8080:8080"
    #   - "4443:4443"
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "10"

启动容器：

shell
docker-compose up -d

七、访问方法

容器运行后，通过以下URL访问WebThings Gateway管理界面：
http://<主机IP地址>:<HTTP端口>
（默认端口为8080，若已自定义端口则使用修改后的端口）

八、自行构建镜像

如需本地构建镜像，步骤如下：

1. 克隆源码仓库：

   shell
   git clone https://github.com/WebThingsIO/gateway
   cd gateway
   

2. 构建镜像（可添加构建参数）：

   shell
   docker build \
     --build-arg "gateway_url=https://github.com/<你的仓库>/gateway" \  # 可选，自定义网关源码地址
     --build-arg "gateway_branch=<你的分支>" \  # 可选，自定义源码分支
     --build-arg "gateway_addon_version=<你的版本>" \  # 可选，自定义附加组件版本
     -t gateway .
   

3. 运行构建的镜像：

   shell
   docker run \
     -d \
     -e TZ=Asia/Shanghai \
     -v /path/to/local/data:/home/node/.webthings \
     --network="host" \
     --log-opt max-size=1m \
     --log-opt max-file=10 \
     --name webthings-gateway \
     gateway
   

九、高级配置与注意事项

9.1 硬件设备访问（Zigbee/Z-Wave等）

若需使用依赖物理硬件的附加组件（如Zigbee、Z-Wave适配器），需将主机设备挂载到容器，并确保设备权限：

shell
docker run \
  ...  # 其他参数
  --device /dev/ttyACM0:/dev/ttyACM0  # 挂载USB设备（需替换为实际设备路径）
  ...

容器内设备需属于GID 20（对应dialout用户组），可通过主机udev规则配置设备权限。

9.2 GPIO访问（如树莓派）

在树莓派等支持GPIO的设备上运行时，需添加以下参数之一：

• 特权模式：--privileged
• 挂载sysfs文件系统：-v /sys:/sys

GPIO节点需属于GID 997（对应容器内gpio用户组）。

9.3 蓝牙访问

若需使用蓝牙功能：

1. 禁用主机蓝牙服务：systemctl disable bluetooth
2. 容器运行时添加特权模式：--privileged