企业官网建设流程全解析

最近又给家里的 Home Assistant 加了点东西。

这次轮到控客。

家里的空调、地暖、新风，本来就在控客系统里。我想要的也很直接：把它们接到 HA，在居家竖屏上点一下就能操作。开关、温度、模式、风速，都放在眼前，少来回找几个界面。

结果做下来，从 SSH、时间同步，到原厂服务、设备状态，再到温控圈和新风按钮，前前后后串了不少东西。

好在最后接起来了：6 台空调、5 路地暖、1 台新风，一共 12 个 HA 实体。

我把这次过程整理一下。想照着接的，可以直接看后面的安装部分；喜欢折腾的，前面这些排查过程应该也有点参考价值。

先看一下后来做的控制界面。

图 1：已实现的空调控制卡片，本地组件预览截图。温度圈、模式和风速都可以直接操作；图中数值不代表发布时的实时设备状态。

这次我也用了 Codex 帮忙查代码、梳理协议、写集成和改界面。我负责提出想要的操作方式，实际操作设备，再把不对劲的地方反馈回去。比如后面那个“新风明明动了，界面却说没响应”的问题，就是这样发现的。

先说我这套环境，免得照着折腾错型号

我这次用的是控客 KK-CC-G12W，HA 是Home Assistant OS，Core 2026.9.4。

设备分布很简单：

|
设备
|
实际接入数量
|
HA 中的类型
|
| — | — | — |
|
空调室内机
|
6 台
|climate|
|
地暖通道
|
5 路
|climate|
|
新风
|
1 台
|fan|

这里的数字是我家的实际情况，集成会读取主机里已经配置好的设备，不要求别人家也凑齐这个数量。

另外，这篇文章记录的是KK-CC-G12W 这一套环境。固件版本这次没有单独记录，其他型号、其他固件，我没测过。网上看到的 KK-SP3 智能插座资料，能提供一些 SSH 背景，但不能直接当成这台主机的完整说明书。

我没有刷机，也没有为了接入 HA 去替换控客原厂系统。最终用到的是主机现有的 SSH、原厂服务，以及原厂已经保存的设备状态。

第一件事：先登录，顺手把时间问题处理掉

一开始就发现，控客主机的时间不太对。

它当时慢了大约1 小时 33 分钟。

时间错着，后面看日志很容易绕晕：到底是刚刚发生的，还是一个小时前的？所以我先把这件事单独处理了。

我通过 SSH 登录主机。下面的命令适用于装了 OpenSSH 的电脑终端，地址和端口要换成自己的；这一步只建立管理连接，密码在提示时输入，不写进命令里。

ssh -p 22 root@<你的控客主机地址>

root是我这套环境用的管理账号。如果你自己的设备使用别的账号，就填实际账号。先确认这是自己有权限管理的设备，也别跳过主机公钥核对。

关于早期设备的登录背景，我参考过这个项目：

Kankun_KK-SP3：早期控客智能插座资料

具体凭据以自己的设备为准。特别是“空密码”，能否用来登录 SSH 还取决于服务配置，不能把 Telnet 的情况直接套过来。

登录后，我主要看了系统时间、UTC 时间、时区配置和 NTP 进程。下面这些是控客这类 OpenWrt/LEDE 环境下的只读排查命令，不会修改时间或配置：

date

date -u

uci show system | grep -E ‘timezone|zonename|ntp’

ps | grep ‘[n]tpd’

logread | grep -Ei ‘ntp|time.*sync|clock’ | tail -n 30

结果时区本身是对的，问题出在时间源这条路上。

原来配置的 NTP 域名，被解析到了198.18.0.x这一类地址。日志里也能看到，服务确实在向这些地址发起校时查询。

这个结果比较可疑，但光看到它，我还不能直接断言是谁改了 DNS，或者哪台设备在做映射。能确认的是：当前解析结果和校时表现有问题，需要换一条能实测收到响应的路径。

后面测试阿里云时间源，能收到响应，偏差到了毫秒级。检查过程中主机时间也恢复过一次，但我没有把那次恢复硬算成某一条命令的功劳，因为当时还有其他校时路径在运行。

继续查，发现除了常驻 NTP 服务，开机脚本里还单独调用了另一个时间源。于是先备份，再把常驻服务和开机校时一起调整到这次实测过的阿里云、腾讯时间源，最后只重启校时服务。

修完后，系统时间与参考时间一致，NTP 也返回了有效结果。

这里还有个边界要说清楚：这次没有重启整台控客主机。开机脚本做过语法检查，但重启后的自动同步，没有在这一步重新实测。

我没有把修时间这件事塞进 HA 集成。它是我这次接入前顺手处理的设备问题，别人家的控客如果时间正常，没必要跟着改一遍。

能 SSH 进去，不等于已经能控制空调

接下来才是接入的主体。

SSH 给了我一个进入主机的入口，但它不会直接告诉 HA：“这是空调，这是地暖，这是新风。”

我得先搞清楚三个问题：

1. 主机里有哪些已经配置好的设备？

2. 设备当前状态放在哪里？

3. 原厂到底通过什么方式下发控制？

这一步先做只读检查。我保留了本地排查材料，用来核对设备配置、状态缓存和原厂程序的调用关系。最后开源时，这些数据库、日志、设备快照和原厂二进制，都没有放进公开仓库。

在我这台主机上，几个关键位置是：

原厂 SQLite 程序

/rom/home/hj/smarthome/bin/sqlite3

设备配置数据库

/etc/dropbear/accessory/hj_db/kk_db.db

设备状态缓存

/tmp/zigbee_dev_status.db

这些路径是这次验证环境里的实际路径，不是所有控客型号都会一样。

配置和状态里比较关键的表，有all_node_config、all_central_ac_indoorunit和all_device_status。我先把它们之间的对应关系理清楚，再决定 HA 要创建哪些实体。

这里有个小细节：地暖网关还报告过一个额外地址，但主机配置里没有对应的地暖子设备。我最后只创建那 5 路已经配置好的地暖，没有因为网关提到了一个地址，就凭空多造一路出来。

还有一路地暖当时离线。我保留了它的实体，让它显示不可用，而不是把它隐藏掉，或者继续把旧温度当成当前值展示。

设备编号和房间名也没有硬猜。先用“空调 1”“地暖 2”这样的编号，等自己确认是哪一个房间，再在 HA 里改名字。

最后走通的方式：SSH 隧道，加原厂本地服务

理清楚以后，接入路径就比较明确了。

状态读取走只读查询，控制走原厂服务，网络通道走 SSH。

整个关系可以这样看：

Home Assistant

│

│ SSH 连接：核对并固定主机公钥

▼

控客主机

├─ 只读查询设备配置和状态缓存

│

└─ SSH direct-tcpip 转发

│

▼

127.0.0.1:5000

│

├─ HJ_CentralAC → 空调室内机

└─ HJ_Server → 地暖、新风

这里的127.0.0.1指的是控客主机自己的回环地址。

我没有把原厂这个控制端口直接开放到外面。HA 通过 SSH 建立转发通道，再访问控客内部的本地服务。

为了方便理解，下面是一条等价的手动转发示例。适用于装了 OpenSSH 的电脑，用来理解或排查这条通道；集成本身会建立通道，正常使用不需要另开这个命令。执行后会占用电脑的本地15000端口，按 Ctrl+C 可以结束。

ssh -N -L 127.0.0.1:15000:127.0.0.1:5000 -p 22 root@<你的控客主机地址>

端口转发只解决“能连过去”。原厂服务还有自己的登录和命令协议，不能建好隧道就随便发一段文本过去。

协议不长，但有几个地方真不能省

我这套原厂服务使用的消息形式是：

!JSON$

也就是前面一个!，后面一个$，中间放 JSON。

连接建立后，先走LC_LOGIN，再发送设备命令。命令里会有opcode、nodeid、arg、requester和reqId这些字段。

空调设置发给HJ_CentralAC，地暖和新风则经过HJ_Server。这几个名字听着像内部实现，但写集成时必须对应上，不然报文格式再漂亮也没用。

真正要留心的是 TCP 接收。

一次接收，不保证刚好等于一条消息。

一条 JSON 可能被拆成几段，也可能两条消息一起回来。所以实现里需要保留没有处理完的数据，按起止符持续组帧，还要处理连接关闭、超时和过大的消息。

另外，收到一条success也不能直接宣布“刚才那台设备控制成功”。至少要核对返回消息的节点和操作码，确认它对应这次等待的设备命令。

我最后加了离线测试，专门覆盖分片、多帧合并、连接中断这些情况。测试用模拟通道，不去动家里的真实设备。

改温度时，把其他设置原样保留下来

空调还有一个容易忽略的地方。

原厂设置命令里带的不只有温度，还有开关、工作模式和风速。我只想把温度从 20°C 调到 22°C，可不能顺手把本来关闭的空调打开，或者把中风改成自动。

所以控制前先读最新状态，把这些原字段保留下来，再覆盖这次真正改的那一项。

比如我只改温度：

原开关：保留

原模式：保留

原风速：保留

目标温度：改为这次选择的值

地暖和新风也按单设备、单设置来下发。操作地暖 2，就只发给地暖 2 对应的节点，不走一条范围含糊的网关批量指令。

这些听起来都是小事，但家里设备真的接上以后，我更在意“别误动另一台”，而不是少写几行代码。

变成 HA 原生实体，后面就好用了

通道和协议理清楚以后，我把它们整理成了一个自定义集成，域名叫：

konke_local

空调和地暖映射成climate，新风映射成fan。这样 HA 原生温控卡片、风扇卡片，以及标准动作都能用，不需要另外学一套专门的控制接口。

这版提供的功能是：

|
设备
|
控制能力
|
| — | — |
|
空调
|
开关、自动/制冷/制热/除湿/送风、自动/低/中/高风速，目标温度 16–32°C，步长 1°C
|
|
地暖
|
开关、制热，目标温度 5–45°C，步长 0.5°C
|
|
新风
|
开关、低/中/高三档风速
|

新风在 HA 中用百分比来表达档位，大致对应33%、67%、100%。原厂实际仍然是 1、2、3 档。

状态默认每 30 秒读取一次，控制后也会请求刷新。这里读到的是原厂缓存，所以它也会受原厂上报节奏影响。

当前温度和设定温度分开取值。原厂没有上报的“正在制热”之类状态，我没有凭空补上；不清楚含义的新风模式，也没有猜着映射。

一开始验证控制链路时，我先让设备维持原有值，核对服务返回和前后状态，避免为了测试接入，把家里的空调、地暖全折腾一遍。

后面我实际操作过新风，确认设备动作生效了。但空调制冷、地暖升温这种物理效果，这次没有做完整测试。能调用服务、能读回设定值，和房间真的降温升温，是两件需要分别验证的事。

接进来以后，我又开始嫌界面不顺手

实体出来，只算完成了一半。

我最后想用的地方，是独立的“居家竖屏”。它和原来的家居首页是两个页面，这一点中间还纠正过一次。后来按独立页面处理，原首页恢复，控客控制放到竖屏里。

初版已经能开关、加减温度、选模式、选风速了。

图 2：居家竖屏初版的本地组件预览。可以看到空调、地暖和新风分区，以及离线地暖通道。它记录的是界面演进过程，后面温控和新风样式又做了调整。

但我想要的是更接近平时温控面板的操作：中间一个大温度，外面一圈可以拖动，下面有加减按钮，模式和风速也别挤成两个小下拉框。

于是又改了一轮。

空调和地暖，都用温度调节圈

现在空调卡片顶部显示当前温度，圆弧中间放设定温度，下面保留−和+。

拖动温度圈时，先显示本地预览；松手之后再提交。不会手指一滑，就沿途连续发一串设备命令。

地暖也用了同样的交互，只是沿用自己的温度范围和 0.5°C 步长。

图 3：已实现的地暖卡片，本地组件预览截图。当前温度和设定温度分开显示，地暖没有空调风速选项。

圆弧后来还加了渐变，从蓝色、青绿色到暖橙色。它主要帮助区分温度调节的位置，不是在模拟设备正在制冷或制热。

空调的模式、风速则改成了带图标的两行卡片。第一眼先看懂现在选了什么，再点进去修改。

新风就做简单点，三档摆开

新风最常用的操作就是开关和风速。

我把低、中、高直接铺开，当前档位高亮。图标也改成气流线条，低速少一点，高速多一点，运行时有流动感。

之前用类似信号强度的图标，总感觉在看 Wi-Fi，后来换掉了。

图 4：已实现的新风卡片，本地组件预览截图。这里展示窄屏布局，低、中、高三档可以直接点选。

这部分是我家的独立仪表盘界面。开源仓库目前只包含控客集成和安装文档，没有把这套居家竖屏一起打包进去。先把设备接进 HA，用原生卡片照样能控制。

最烦的一个问题：设备已经动了，界面还说没响应

新风接上后，我实际操作过，设备已经生效，但界面偶尔还会提示“设备无响应”。

这个体验挺别扭：设备在动，页面却让我怀疑刚才那一下到底算不算成功。

后来把界面交互分开处理了。

我点一个档位，或者修改目标温度，界面先把这次选择显示出来，后台异步发送和同步状态。与此同时，还得防着旧的状态回传把刚选的新值覆盖掉。

比如我先点中速，又很快点高速。晚到的“中速”反馈，不能再把页面拉回去；前一次请求的失败，也不能把后一次操作一起回滚。

这部分处理了每台设备的请求顺序，以及每个字段的新旧关系。

“已发送”“等待设备反馈”“设备状态已更新”这一串常规提示，我都去掉了。同步超时这类情况也不再直接冒出“设备无响应”来打断操作；明确的命令拒绝或其他实际失败，仍然保留简短错误反馈。

这里说的是竖屏界面的交互策略。底层集成还是读取设备实际状态，不会因为页面先显示了 22°C，就对外宣称设备已经确认了 22°C。

这个改完，比再加一层装饰效果更有用。

如果你也想接，下面是现在的安装方式

前面是我实际走过的排查过程。现在组件整理好了，同型号、同类环境就不用再从协议分析开始了。

先准备几样东西：

• 一个正常运行的 HA，先做好备份。

• 控客主机的地址、SSH 端口和实际登录凭据。

• 已独立核对过的 SSH 主机公钥。

• HA 能访问控客 SSH 端口，且账号允许读取相关数据库、建立 SSH 转发。

我排查和部署时用过现有的 SSH 跳板环境，不过发布的集成不内置跳板机功能。正常运行时，需要HA 自己能访问控客的 SSH 端口，不能只有我的电脑能连上。

方式一：手动安装

打开发布页：

下载 home-assistant-konke v0.1.0

下载里面的home-assistant-konke-v0.1.0.zip，解压到 HA 配置目录。这个目录通常和configuration.yaml在一起。

最后的目录应该长这样：

HA 配置目录/

├─ configuration.yaml

└─ custom_components/

└─ konke_local/

├─ __init__.py

├─ client.py

├─ climate.py

├─ config_flow.py

├─ entity.py

├─ fan.py

├─ manifest.json

├─ strings.json

├─ translations/

└─ brand/

最重要的是确认：custom_components/konke_local/manifest.json这个路径确实存在。

不要解压完变成“仓库文件夹里面又套一层仓库文件夹”，HA 在正确位置找不到集成，后面刷新多少次也没用。

然后重启 HA，进“设置 → 设备与服务 → 添加集成”，搜索“控客”。首次加载会安装paramiko==3.5.1，HA 需要能访问依赖下载源。

方式二：HACS 自定义仓库

已经装了 HACS 的话，在自定义存储库里添加：

https://github.com/YyyQq-C/home-assistant-konke

类别选择集成，下载“控客 Konke”，重启 HA，再去设备与服务里添加。

也可以用这个快捷入口：

在自己的 HA 中打开本项目 HACS 页面

My Home Assistant 可能会先让你确认自己的 HA 地址。HACS 要已经装好，这个链接不会替你安装 HACS。

目前支持的是HACS 自定义仓库安装，还不是“打开 HACS 默认列表就一定能搜到”。

主机公钥这一步，别只复制个密码就往下走

配置项里需要填：主机地址、SSH 端口、SSH 用户、SSH 密码，以及已核对的主机公钥。

主机公钥的格式是：

算法名 Base64公钥

例如算法可能是ssh-rsa，后面接你自己核对过的完整 Base64 公钥。不要把设备地址也一起粘进去。

下面的命令适用于装了 OpenSSH 的电脑，只采集公钥和显示指纹；地址、端口都要替换成自己的。它不会修改控客配置，但网络采集结果还需要独立核对，不能直接当作可信身份。

ssh-keyscan -p <SSH端口> <控客地址> > gateway-host-keys.txt

ssh-keygen -lf gateway-host-keys.txt

再用设备控制台、之前已经信任的连接，或其他可信渠道拿到的指纹进行比对。核对一致以后，才把对应的算法名和公钥填到集成里。

密码解决的是“我有没有权限登录”，主机公钥解决的是“我连到的到底是不是自己的设备”。我这版固定了主机公钥，匹配不上就拒绝连接。

提交配置时只查询设备，不发送开关或调温命令。验证通过后，HA 会创建读到的设备实体。

装完先小范围核对，别直接全屋自动化

我建议先挑一台设备，核对它的名称、在线状态、当前温度、目标温度，再试一个自己能现场确认的操作。

HA 里可以使用原生卡片，也可以到“开发者工具 → 动作”选择标准动作：

• climate.set_temperature

  ：空调或地暖目标温度。

• climate.set_hvac_mode

  ：温控设备模式。

• climate.set_fan_mode

  ：空调风速。

• fan.set_percentage

  ：新风档位。

这里我不放一段直接执行的全屋控制配置，免得有人复制过去就把一屋子设备打开了。选自己实际的实体，单台确认，更容易知道哪里出了问题。

如果出现问题，我会按下面这个顺序查：

|
表现
|
我会先核对什么
|
| — | — |
|
HA 添加集成失败
|
HA 到 SSH 的网络、端口、账号密码、主机公钥及转发权限
|
|
能 SSH，但没有发现设备
|
原厂是否已配置相关设备，数据库路径、表结构是否一致
|
|
某一路显示不可用
|
原厂应用中的在线状态，是否存在有效设备缓存
|
|
设定值没立刻变化
|
原厂缓存的上报节奏，控制后是否完成刷新
|
|
控制超时，但设备已经动作
|
先核对实际状态和日志，不急着连续重发
|
|
只有自己的电脑能登录
|
HA 本身是否有到控客的网络路径
|

需要看集成日志时，关注custom_components.konke_local。发日志求助之前，把凭据、家庭地址、节点标识等个人信息先处理掉，数据库和完整快照也别直接贴出来。

更新和卸载，我也留了条能退回去的路

更新之前先备份 HA 配置。手动安装的，替换custom_components/konke_local；HACS 安装的，通过 HACS 更新，再重启 HA。

如果已经装过我前面的版本，就保留原配置项、网关地址和实体注册表。集成域名和实体唯一标识算法没有改，没必要为了更新先把集成删一遍。实体名字和自动化引用，能保留就尽量保留。

当前还没有单独的凭据编辑界面。假如你改了 SSH 密码、主机公钥或者地址，需要核对新值后重新添加配置项；操作前先记录原来的实体和自动化引用，完成后再检查一遍。

不想用了，也可以先在设备与服务中删除集成，再从 HACS 卸载，或者删除对应的组件目录，最后重启 HA。控客原厂的设备配置不随这个 HA 集成一起删除。

最后，整理成一个能给别人用的项目

这次接完，我就把集成单独开源了：

GitHub：https://github.com/YyyQq-C/home-assistant-konke

许可证是 MIT，首版是v0.1.0。

整理的时候没有把整个临时工作目录推上去。我另外建了独立仓库，只放运行源码、离线测试、安装说明、许可证、图标和自动检查。

现场数据库、日志、家庭配置、部署备份、设备快照、原厂程序，都留在本地。公开文档里引用的早期登录资料单独标了来源，不把它当成所有型号的登录保证。

现在的离线测试一共 7 项，覆盖了消息分帧、单设备隔离、离线拒绝、温度边界、未修改设置保留，以及固定主机公钥的拒绝策略。仓库还会检查发布文件名单，并验证安装包内容。

发布时，我核对过 GitHub 自动检查结果，也把上传的安装包重新下载下来，比对了内容和 SHA256。

写到这里，这次接入里我比较满意的，倒不是“又多了 12 个实体”这个数字。

而是现在想调温度、换模式、改新风档位，能在那个竖屏上直接完成。背后还是原来的控客设备，前面终于能按我习惯的方式用了。

后面要是继续折腾，就从实际使用里不顺手的地方接着改。先让这一版好好用起来。

相关地址

• 项目与最新安装文档：https://github.com/YyyQq-C/home-assistant-konke

• v0.1.0 发布页：https://github.com/YyyQq-C/home-assistant-konke/releases/tag/v0.1.0

• 早期 KK-SP3 资料：https://github.com/yurt-page/Kankun_KK-SP3

• HACS 快捷入口：https://my.home-assistant.io/redirect/hacs_repository/?owner=YyyQq-C&repository=home-assistant-konke&category=integration

本文记录本次实际接入过程。界面配图来自已实现组件的本地预览，图中读数用于展示界面，不代表发布时实时状态。兼容范围以项目文档为准，尚未验证其他控客型号。