Node-RED 服务器安装与配置

开始前准备

项目	需要准备	说明
Home Assistant	`http://你的HA地址:8123`	用于接收 Node-RED 写入的凯迪仕实体。
Node-RED	`http://你的Node-RED地址:1880`	用于运行凯迪仕流程。
长期访问令牌	Home Assistant 用户页面创建	用于 Node-RED 连接 Home Assistant。

部署说明 Node-RED 可以和 Home Assistant 安装在同一台服务器，也可以安装在另一台服务器；只要 Node-RED 能访问 Home Assistant 地址，并配置正确的长期访问令牌即可。

完成后应该得到什么

能力	实体或位置	成功表现
最近门锁事件	`sensor.kaadas_last_content`	显示“门已上锁”“指纹开锁”等最近事件。
门关闭状态	`binary_sensor.kaadas_door_closed`	`on` 代表门关闭，`off` 代表门未关闭或未知。
电池电量	`sensor.kaadas_battery_big` / `sensor.kaadas_battery_small`	显示大电池、小电池百分比，例如 `85%`、`88%`。
HomeKit 百分比显示	`sensor.kaadas_big_battery_percent` / `sensor.kaadas_small_battery_percent`	伪装成湿度百分比，方便 Apple 家庭显示。
人员状态	`binary_sensor.kaadas_user1` 到 `binary_sensor.kaadas_user4`	最近一次开锁人员对应的实体为 `on`，其他人为 `off`。

1. 进入 Node-RED 服务器

如果还没有 Node-RED，需要先登录准备用来安装 Node-RED 的服务器。如果已经有可用的 Node-RED，可以跳到第 4 步。

# 进入服务器。第一次连接会询问 yes/no，输入 yes。
ssh 用户名@你的服务器IP

# 预期结果：终端提示符变成服务器上的 shell。
# 例如看到 root@debian:~# 就代表登录成功。

成功判断 能执行 hostname、pwd、ls，并看到服务器返回内容，说明已经进入服务器。

2. 安装或确认 Docker

如果服务器已经安装 Docker，先直接检查版本。

# 查看 Docker 客户端和服务端版本。
docker version

# 预期结果：能看到 Client 和 Server 两段信息。
# 真实示例：Client: Docker Engine - Community 27.3.1
# 真实示例：Server: Docker Engine - Community 27.3.1

如果提示 docker: command not found，再执行安装命令。

# 更新软件源。
apt update

# 安装 Docker 所需依赖。
apt install -y ca-certificates curl gnupg

# 创建 Docker GPG key 目录。
install -m 0755 -d /etc/apt/keyrings

# 下载 Docker 官方 GPG key。
curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# 添加 Docker 软件源。
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list

# 安装 Docker。
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 再次检查版本。
docker version

成功判断 docker version 同时显示 Client 和 Server，代表 Docker 命令和 Docker 服务都正常。如果只有 Client 没有 Server，通常是 Docker 服务没启动。

3. 安装 Node-RED 服务

推荐用 Docker 安装，并开启自动重启。服务器重启后，Node-RED 会自动恢复。

# 创建 Node-RED 数据目录。流程、插件、配置都会保存在这里。
mkdir -p /root/Configs/NodeRED

# Node-RED 容器内默认用户是 1000，目录需要给它写入权限。
chown -R 1000:1000 /root/Configs/NodeRED

# 启动 Node-RED。
# --restart unless-stopped 表示除非你手动停止，否则开机后自动重启。
# -p 1880:1880 表示把服务器的 1880 端口开放为 Node-RED 网页。
# -v /root/Configs/NodeRED:/data 表示配置持久化保存。
docker run -d \
  --name nodered \
  --restart unless-stopped \
  -p 1880:1880 \
  -v /root/Configs/NodeRED:/data \
  ghcr.io/node-red/node-red:latest

安装 Home Assistant 节点插件。

# 在 Node-RED 数据目录里安装 HA WebSocket 节点。
docker exec -u node-red -w /data nodered npm install node-red-contrib-home-assistant-websocket

# 重启 Node-RED，让新插件加载。
docker restart nodered

检查 Node-RED 是否已经运行。

# 只查看名为 nodered 的容器。
docker ps --filter name=nodered

# 真实成功示例：
# NAMES     IMAGE                              PORTS                                       STATUS
# nodered   ghcr.io/node-red/node-red:latest   0.0.0.0:1880->1880/tcp, :::1880->1880/tcp   Up 3 hours (healthy)

成功判断 STATUS 里出现 Up 代表容器正在运行；出现 healthy 更好，代表健康检查正常；PORTS 里有 0.0.0.0:1880->1880/tcp 代表外部可以通过 1880 端口访问 Node-RED。

4. 打开 Node-RED Web 界面

浏览器打开 Node-RED 地址。

# 浏览器地址栏输入：
http://你的Node-RED服务器IP:1880

# 预期结果：
# 能看到 Node-RED 编辑器，右上角有“部署”按钮。

Node-RED 编辑器主界面截图 — 步骤 4 截图：Node-RED 编辑器主界面。右上角“部署”按钮存在，说明 Web 界面已打开。

5. 生成 Node-RED JSON

打开凯迪仕流程生成器。
选择或拖入凯迪仕 HAR 文件。
填写 Home Assistant 地址，例如 http://你的HA地址:8123。
粘贴 Home Assistant 长期访问令牌。
输入卡密。
点击 校验卡密并下载 JSON。

凯迪仕流程生成器截图 — 步骤 5 截图：凯迪仕配置生成页面。HAR 合格后，下载按钮会变成可用。

成功判断 下载得到的 JSON 文件里已经包含凯迪仕请求头、wifiSN/esn、uid、Home Assistant 地址和长期令牌。这个文件要自己保管，不要发给别人。

6. 导入 Node-RED 流程

从空白导入到可部署，按下面步骤做。

在 Node-RED 右上角点击三横线主菜单。
选择导入。
在弹窗中选择 剪贴板 或 导入节点文件。
如果用剪贴板，就把生成的 JSON 内容粘贴进去。
如果用文件，就选择刚下载的 JSON 文件。
看到导入按钮从灰色变成可点击后，点击导入。
流程出现在画布上后，点击右上角部署。

Node-RED 主菜单里导入入口截图 — 步骤 6-1 截图：右上角主菜单打开后，选择“导入”。

Node-RED 空白导入弹窗截图 — 步骤 6-2 截图：空白导入弹窗。可以粘贴 JSON，也可以选择本地 JSON 文件。

Node-RED 导入按钮可用截图 — 步骤 6-3 截图：JSON 被识别后，“导入”按钮会变成可点击。点击后再按右上角“部署”。

成功判断 部署后右上角按钮不再提示未部署修改；调试窗口不持续报红色错误；Home Assistant 里开始出现 kaadas 实体。

7. 加入 HA 模板实体

Node-RED 负责拉取凯迪仕数据；门关闭、电池百分比和 HomeKit 伪装百分比由 Home Assistant 模板实体生成。下载模板：

下载 kaadas_template.yaml

# 在 Home Assistant 的 configuration.yaml 中加入：
template: !include kaadas_template.yaml

# 如果你已经有 template:，不要重复写 template:。
# 只把 kaadas_template.yaml 里的 - sensor: 和 - binary_sensor: 合并进去。

实体	来源	用途
`binary_sensor.kaadas_door_closed`	由 `sensor.kaadas_last_content` 推导	显示门是否关闭。适合加入 HomeKit。
`sensor.kaadas_battery_big`	`sensor.kaadas_info` 的 `battery1` 属性	大电池真实百分比。
`sensor.kaadas_battery_small`	`sensor.kaadas_info` 的 `battery2` 属性	小电池真实百分比。
`sensor.kaadas_big_battery_percent`	把大电池伪装成湿度百分比	给 Apple 家庭显示百分比用。
`sensor.kaadas_small_battery_percent`	把小电池伪装成湿度百分比	给 Apple 家庭显示百分比用。
`binary_sensor.kaadas_user1` - `binary_sensor.kaadas_user4`	凯迪仕记录里的 `pwdNum`	判断最近一次开锁对应哪个人员。

8. 验证和排错

Home Assistant 里打开开发者工具，搜索 kaadas。如果能看到门锁事件、电池电量、门状态和人员实体，说明流程已经跑通。

# 查看 Node-RED 最近日志。
docker logs --tail=80 nodered

# 预期结果：
# 没有持续出现连接 HA 失败、401、403、接口超时等错误。

# 确认 Node-RED 自动重启策略。
docker inspect nodered --format '{{.HostConfig.RestartPolicy.Name}}'

# 预期结果：
# unless-stopped

常见问题 如果没有实体，先确认 Node-RED 已点“部署”；如果电池和门状态没有出现，确认 HA 模板已加入并重启或重载模板；如果人员对不上，查看最近记录里的 pwdNum，0 对应 User1，1 对应 User2，依次类推。

Node-RED 服务器安装与配置。