Entrixy v2 —— 最终架构

1. 隐私：服务器一无所知（默认）

所有敏感数据只保存 在手机上。主人可以选择让其中一部分经过服务器——并会收到明确警告。

2. 四种对象类型

添加对象时，主人先选连接类型。随后打开该类型的设置窗口。

后两种类型的固件配置器： /controller/ （BLE 与“联网”，在浏览器中）。

在用户看来，各种类型长得都一样：一张卡片、一个“呼叫”按钮、一个状态。不同的只是投递机制。

3. Webhook（URL）详解

两种发送模式

Webhook 设置窗口提供一个切换项，利弊直接写在屏幕上：

数据存在哪里

请求协议

安全性：HMAC 签名。设备与 Entrixy 共享一个 webhook_secret.

POST https://device-url.com/open
Content-Type: application/json

{
  "action": "open",
  "object_id": 42,
  "timestamp": 1713020000,
  "nonce": "a1b2c3",
  "signature": "hmac-sha256(secret, timestamp + nonce + action)"
}

设备会核验签名有效、时间戳不超过 30 秒、nonce 不是重复值。一切正常就执行并回复：

{"status": "ok", "message": "Door opened"}
or
{"status": "error", "message": "Lock jammed"}

状态会在应用中显示给用户。

数据流（手机模式）

The guest presses Call
  → the server receives the request
  → sends it to the owner over the WebSocket: {type: "do_webhook", ...}
  → the owner's phone makes the HTTP call to the device
  → receives the JSON response
  → sends it to the server: {type: "webhook_result", status, message}
  → the server passes it to the guest
  → both see the status in the log

Logging

两种模式下，主人和访客手机上的日志都会记下：谁、何时、哪个对象、返回了什么状态。

4. 设备（ESP32 / ESP8266，WebSocket）详解

工作原理

控制器——支持 ESP32、ESP32-S3、ESP32-C3 与 ESP8266——没有公网 IP。它与 Entrixy 服务器保持一条出站 WebSocket 连接，跟主人的手机一样。

固件与配置器位于 /esp/socket/。源码： ESP32, ESP8266.

设备的 WebSocket 协议

// Device → server: connect
{"type": "device_hello", "device_key": "xyz789", "device_secret": "..."}

// Server → device: OK
{"type": "device_ok"}

// Server → device: command
{"type": "device_command", "action": "open", "command_id": "abc123"}

// Device → server: result
{"type": "device_response", "command_id": "abc123", "status": "ok", "message": "Opened"}

服务器通过各自的 WebSocket 连接把状态转发给客户端——主人与访客。

注册设备

1. 主人在应用中选择“添加对象”→ 类型“设备”
2. 于是生成 device_key + device_secret
3. 显示带固件参数的二维码
4. 用户为 ESP32 或 ESP8266 刷入程序（见 configurator），设备随即连接到 wss://entrixy.com/ws

Indication

对象卡片会显示设备的连接状态，在线或离线，就像访客看到主人的状态一样。

4a. BLE 控制器（ESP32）详解

工作原理

基于 ESP32、S3、C3、C6 或 H2 的控制器，触发时既不需要 Wi-Fi 也不需要服务器。它处于深度睡眠，每秒醒来约 200 毫秒，广播一条带签名计数器的 BLE 通告。当持有有效密钥的手机靠近，Android——或前台运行的应用——捕获该通告，通过 GATT 连接，发送带一次性 nonce 的 fire 命令，控制器便以短脉冲闭合继电器。对于双稳态驱动和门锁，另有一种“开”“关”分离并跟踪位置的模式，其中“开/关”以加密字节随通告一同发送。

Entrixy 服务器不参与这条通道。 只有在创建访客密钥时才需要它：主人签署一个 GuestToken，经端到端加密通道交给访客。此后访客即可离线工作。

BLE 协议简述

• Pair-flow ——手机与控制器之间的 ECDH X25519。共享密钥经 HKDF-SHA256 派生，密钥本身绝不上空口。
• Advertise ——厂商自定义数据，18 字节：公司 ID + device_id + 计数器 + HMAC-SHA256(secret, device_id||counter)。
• Fire（主人） ——READ nonce → WRITE [nonce || HMAC(secret, nonce)]。
• Fire（访客） ——WRITE [GuestToken || owner_sig || nonce || guest_sig]。GuestToken 带有存活期，控制器会用本地 RTC 校验。
• Time-sync ——主人用一条经签名的命令校正 RTC。

完整的协议规范、位布局和测试向量见 entrixy.com/ble。威胁模型见 单独的文档.

什么时候 BLE 胜过 WebSocket

• 驱动装置没有可靠的 Wi-Fi——野外的大门，或隔着一米混凝土的道闸。
• 必须靠电池工作，附近没有插座。
• 你不希望开门那一刻还要依赖互联网和我们的服务器。
• 访客需要离线开门——控制器自己校验令牌。

什么时候 WebSocket 胜过 BLE

• 你需要远程开启，而不必开到门口。
• Wi-Fi 存在且可靠，插座也有。
• 方便：添加设备，在应用里拿到 device_key 与密钥，把程序装进控制器。

同一台驱动装置可以同时装 BLE 与 WebSocket——在应用里显示为两个独立对象。BLE 用于近处无网开启，WebSocket 用于你人在远方的时候。

注册设备

1. 主人在应用中选择“添加对象”→ 类型“BLE 控制器”
2. 应用扫描空口，寻找处于配对模式的设备（名称为 entrixy-pair)
3. 选定设备后通过 GATT 进行 ECDH 交换；共享密钥保存在手机的 Prefs 和控制器的 NVS 中
4. 既不用二维码也不用按按钮——程序装好后，新设备自己就进入配对模式

固件与配置器位于 /esp/ble/。源码： /esp32-example/.

Indication

在对象卡片上：灰色表示空口不可见，太远或已关闭；橙色表示可见但自动化尚未触发；绿色表示已触发或正在触发；灰色带绿边表示刚刚触发过，点一下可以再开一次。

Database

CREATE TABLE devices (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  host_id INT UNSIGNED NOT NULL,
  device_key VARCHAR(64) NOT NULL UNIQUE,
  secret_hash VARCHAR(64) NOT NULL,
  label VARCHAR(128) DEFAULT '',
  last_seen DATETIME NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

In server.php 新增第三种 WebSocket 角色： device （与 host 与 guest).

5. 触发器：GPS 与 Wi-Fi

GPS 与 Wi-Fi 各自独立工作。两者都配置时，谁先满足谁触发。两次触发之间的公共冷却为 20 秒。

GPS——目前的样子

• 坐标、半径和自适应更新间隔
• 指示：“312 米”

Wi-Fi——两种模式

模式 1：Wi-Fi 画面（指纹）

• 用户点击“记住 Wi-Fi”，随即扫描所有可见网络
• 保存的是 BSSID——唯一的 MAC 地址。界面上显示 SSID，但留存的是 BSSID
• 显示找到的网络数量
• 用户设定“最少匹配数”阈值，默认 5
• 若找到的网络太少，会出现警告
• 触发条件：至少能看到 N 个已记住的网络 → 触发
• 指示：📶 显示信号格——0 到 4 格，取决于匹配数与阈值的比例

模式 2：已连接到网络

• 绑定某个具体的 Wi-Fi 网络（BSSID 与 SSID）
• 触发条件：手机连上该网络
• 零电量开销——依托系统广播
• 指示：📶 绿色或灰色

能耗

• WifiManager.getScanResults() ——缓存结果，不做新的扫描；我们在每次 GPS 更新时免费调用它
• 连接模式使用 NetworkCallback，完全不做扫描

存储（Prefs，绝不离开手机）

wifi_trigger_<actionKey> = {
  "mode": "fingerprint" | "connect",
  "bssids": ["AA:BB:CC:DD:EE:FF", ...],
  "min_match": 5,
  "connect_bssid": "AA:BB:CC:DD:EE:FF",
  "connect_ssid": "TP-Link_5G",
  "enabled": true
}

6. 三级确认

由主人决定是否需要确认。 具体如何确认身份由客户端决定，取决于设备提供了什么。

“确认”并不是多余的一步。 通知会在恰当的时刻自己出现在通知栏。不用找应用、不用解锁、不用翻出对象。点一下，门就开了。

身份确认方式的优先级

1. 有传感器时用生物识别 → BiometricPrompt
2. 没有生物识别时用手机的 PIN 或密码 → KeyguardManager
3. 设备未设锁时用应用自带的 PIN → 我们自己的对话框

时间窗口——额外的一重因素

主人设定“允许时段：07:00–23:00”。窗口之外，条件会被静默忽略。跨夜区间同样有效（22:00–06:00）。

三重相互独立的防护因素

1. WHERE ——GPS、Wi-Fi 指纹或已连接网络
2. WHO ——自动、确认或生物识别
3. WHEN ——时间窗口

7. 主人与访客——设置的分工

8. 应用界面

添加对象（SettingsScreen）

第一步是选择连接类型：

┌────────────────────────────┐
│  Connection type           │
│                            │
│  📞  Call                  │
│  Opening with a phone      │
│  call                      │
│                            │
│  🌐  URL                   │
│  Sending a command to      │
│  a device address          │
│                            │
│  📟  Device                │
│  Connected through Entrixy │
│  (ESP32, Arduino)          │
└────────────────────────────┘

选定之后，打开该类型的设置窗口。

展开的对象卡片（ActionCard）

┌──────────────────────────────────────────┐
│  Corner barrier             📶 3/5  312m │
│  Mine • ●                                │
├──────────────────────────────────────────┤
│  [Edit]  [Icon]                          │
│  ─────────────────────────               │
│  [📍 Geo]   [📶 Wi-Fi]                   │
└──────────────────────────────────────────┘

📍“定位”窗口

• 半径（10–500 米的滑块）
• “获取坐标”按钮
• 距离，Google 地图
• 时间窗口：[07:00] — [23:00]
• 确认：自动 / 确认 / 确认身份

📶 Wi-Fi 窗口

◉ 按 Wi-Fi 画面

• “记住网络” → “找到 N 个网络”
• 匹配阈值，由用户决定

○ 按连接到网络

• 当前网络 → “绑定”

下方：时间窗口与确认，与“定位”共用

Webhook 窗口（🌐 URL）

• 设备地址
• 密钥，自动生成或手工输入
• 发送模式（带说明的切换项）：

折叠卡片上的指示

9. 套餐限制

内部套餐。不向用户展示，但限制照样生效。

超出时给出温和的提示：“对象数量有限。如需提高，请联系支持。”

CREATE TABLE plans (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(64) NOT NULL,
  max_numbers INT NOT NULL DEFAULT 10,
  max_keys INT NOT NULL DEFAULT 10
);
INSERT INTO plans (name) VALUES ('default');

ALTER TABLE hosts ADD COLUMN plan_id INT UNSIGNED DEFAULT 1;

10. 数据库——全部改动

-- Plans
CREATE TABLE plans (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(64) NOT NULL,
  max_numbers INT NOT NULL DEFAULT 10,
  max_keys INT NOT NULL DEFAULT 10
);
INSERT INTO plans (name) VALUES ('default');

ALTER TABLE hosts ADD COLUMN plan_id INT UNSIGNED DEFAULT 1;

-- Object type and settings
ALTER TABLE numbers
  ADD COLUMN type ENUM('call','webhook','device') DEFAULT 'call',
  ADD COLUMN radius INT DEFAULT 80,
  ADD COLUMN time_from TIME NULL,
  ADD COLUMN time_to TIME NULL,
  ADD COLUMN security_level ENUM('auto','confirm','identity') DEFAULT 'auto',
  ADD COLUMN geo_available TINYINT(1) DEFAULT 1,
  ADD COLUMN wifi_available TINYINT(1) DEFAULT 1,
  ADD COLUMN wifi_min_match INT DEFAULT 5,
  ADD COLUMN share_lat DOUBLE NULL,
  ADD COLUMN share_lon DOUBLE NULL,
  ADD COLUMN webhook_url VARCHAR(512) NULL,
  ADD COLUMN webhook_secret VARCHAR(64) NULL,
  ADD COLUMN webhook_mode ENUM('phone','server') DEFAULT 'phone',
  ADD COLUMN device_id INT UNSIGNED NULL;

-- Devices (ESP32)
CREATE TABLE devices (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  host_id INT UNSIGNED NOT NULL,
  device_key VARCHAR(64) NOT NULL UNIQUE,
  secret_hash VARCHAR(64) NOT NULL,
  label VARCHAR(128) DEFAULT '',
  last_seen DATETIME NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

share_lat / share_lon ——只有当主人启用了“与访客分享坐标”时才填写。

webhook_url / webhook_secret ——仅在服务器模式下填写。手机模式下它们存放在 Prefs 里。

11. 给访客看的对象图标

主人给对象设置了自定义图标，访客应当能看到。但是 图标并不存放在服务器上 ——服务器只当邮差：送到即忘。

主人侧的准备

设置时图标会立刻缩小为 64×64 PNG （约 3–5 KB），并本地存于 Prefs 或文件中。

它如何传输

1. The guest connects
   → guest_ok carries has_avatar: true for objects that have an icon

2. The guest client checks: has_avatar=true but no icon locally?
   → Yes → it asks the server

3. The server has no icon
   → it asks the owner over the WebSocket: {type: "avatar_request", number_id: 42}

4. The owner's phone
   → reads the local file
   → sends: {type: "avatar_data", number_id: 42, data: "base64..."}

5. The server passes it to the guest
   → {type: "avatar_data", number_id: 42, data: "base64..."}

6. The guest stores it locally and never asks again

7. The server stored nothing — the data merely passed through

边界情况

12. 负载预测

一位活跃主人会产生

• 1 条常驻 WebSocket 连接，每 30 秒一次 ping/pong
• 启动时 1 次 HTTP host_sync
• 每 15 分钟 1 次 HTTP promo（cache_ttl）
• 每天 5–10 次呼叫，每次一帧 WebSocket

一位活跃访客

• 1 条 WebSocket 连接
• 每天 1–3 次呼叫

Scaling

单个工作进程上的 Workerman：5000–10000 条并发连接，每条约 20 KB。

Webhook 与设备

• 来自服务器的 Webhook ——每次呼叫一个 HTTP 请求。10000 位订户 × 每天 5 次 = 每天 50000 次请求，约每秒 0.6 次
• 设备 ——每台设备额外一条常驻 WebSocket 连接

瓶颈

在 MySQL，而不在 WebSocket。可每天 25 万次插入——5 万订户 × 5 次呼叫——对 SSD 上的 MySQL 来说不值一提。

13. 实施计划

1. Database ——套餐、numbers 与 hosts 的新列、devices 表
2. 服务端限制 ——在 number_add 与 key_create 中做校验
3. 对象类型 ——添加时选择类型，配以不同对话框
4. API ——带新档案字段的 host_sync 与 guest_ok
5. Webhook ——HMAC 协议、两种发送模式、响应状态
6. 设备 WS ——server.php 中的 device_hello、device_command 与 device_response
7. Wi-Fi 触发器 ——指纹与连接
8. 时间窗口 ——time_from/time_to
9. 确认 ——三个层级：自动、确认、确认身份
10. Icons ——经 WebSocket 过境投递，压缩到 64×64
11. UI ——“定位”与 Wi-Fi 按钮、对话框、指示器、类型选择器
12. 分享坐标 ——一个带警告的选项
13. 构建与发布