鸿蒙 hdc-remote-kit：USB 鸿蒙设备远程 `hdc tconn`

哲豪 · 2026年07月21日 · 69 次阅读

背景：为什么要做这个

很多公司做鸿蒙 / OpenHarmony 真机验证时，设备并不是「人手一台、随时插在开发者电脑上」：

真机、样机往往集中在机房、实验室或统一调试机上，由测试 / 平台侧统一管理
出于资产、安全、机型稀缺或版本管控，不方便、也不适合把设备长期借给每位开发者本地插着用
开发、联调、自动化和 CI 却发生在办公网电脑、笔记本或构建节点上——人和设备天然分离

结果是：设备在机房里是「有的」，但对日常开发来说常常「够不着」。常见权宜之计也各有问题：

远程桌面进机房机器再开 hdc：能应急，但体验差，脚本和流水线不好接
排队去机房 / 等设备外借：流程重，反馈周期长，不适合高频小改动验证
上完整设备云或中控平台：能力强，但建设和维护成本高；不少团队其实只想继续用官方 hdc，把机房里的设备安全地接到办公网或指定环境

更现实的目标通常是：

设备仍留在机房 / 统一管理节点，不打乱现有资产与管控方式
开发者或 CI 在自己的环境里，用熟悉的 hdc tconn / hdc -t host:port ... 做 shell、传文件、装包、抓 hilog 等
优先覆盖公司内网；跨机房、VPN 或受控公网接入时，能用来源白名单收口

于是做了 hdc-remote-kit：部署在插着 USB 设备的那台机器（常见就是机房调试机）上，自动发现在线设备并分配稳定代理端口；客户端继续走标准 HDC，不引入私有协议，也尽量不改变现有 hdc 使用习惯。

hdc tconn <host>:<port>
hdc -t <host>:<port> shell echo ok


项目	yabi-zzh/hdc-remote-kit
版本	`v0.1.0`
预编译包	GitHub Releases（Linux / macOS / Windows，amd64 与 arm64）

欢迎试用；觉得有用的话，给仓库点个 Star，也方便我们按反馈排优先级。当前为 v0.1.0 首版，能力与稳定性仍在迭代，文末有简要说明。

项目简介

hdc-remote-kit 是纯 Go、无第三方依赖的 HDC 远程调试服务：把本机 USB 设备的调试能力，以标准 HDC daemon 入口的形式暴露到网络上。无 Web 控制面，无需手工登记设备。

主要特点：

自动发现：检测在线 USB 设备并自动开启转发
标准协议：客户端继续使用 hdc tconn / hdc -t host:port ...，现有脚本与工具链改动小
端口稳定：同一设备尽量复用同一代理端口；映射可落盘，进程重启后按当时在线设备重新开启
网络灵活：默认适配本机与局域网；公网或 VPN 可按来源 CIDR 放行，并建议配合防火墙
基础管控：连接并发上限、命令策略与审计日志

服务启动后，日志会打印可直接复制的连接命令：

INFO forwarding ready serial=4ABVB24A10014201 connect="hdc tconn 192.168.1.8:50000"

边界也说清楚：这不是带控制台的设备管理平台，也不另起私有调试协议；目标是远程可连、尽量接近本地 hdc，并保持实现轻量。

流程与逻辑

整体架构

┌────────────┐     USB      ┌──────────────────────────────────────────┐
│ 鸿蒙 / OH  │<------------>│ 调试机（机房 / 统一管理节点）               │
│ 真机设备   │              │ hdc server (如 127.0.0.1:8710)            │
└────────────┘              │          ▲                               │
                            │          │ host channel                  │
                            │          ▼                               │
                            │ hdc-remote-kit                           │
                            │ · 扫设备 / 维护 Binding + Lease           │
                            │ · 每台 USB → 稳定 TCP 代理端口             │
                            │ · CIDR 准入 · 策略 · 审计 · 协议桥         │
                            │          ▲                               │
                            └──────────┼───────────────────────────────┘
                                       │ 局域网 / 公网 / VPN
                                       │ hdc tconn host:port
                            ┌──────────┴───────────────────────────────┐
                            │ 开发机 / CI / 远程客户端                  │
                            │ 标准 hdc 命令与工具链                     │
                            └──────────────────────────────────────────┘

自动转发主流程

             启动 hdc-remote
                     │
                     ▼
┌────────────────────────────────────────┐
│ 周期性扫描主 HDC 设备列表                │
│ (host channel，不调用外部 hdc CLI)      │
└────────────────────┬───────────────────┘
                     │
       ┌─────────────┼─────────────┐
       ▼             ▼             ▼
       online        offline       stale
       │             │             │
       ▼             ▼             ▼
       分配/复用端口 冻结入口      按策略处理
       开启 Lease    停掉转发
       打印 connect=
       │
       ▼
       客户端 hdc tconn host:port
       │
       ▼
       CIDR / 并发 / channel 上限校验
       │
       ▼
       daemon 握手 → 协议桥（shell / 文件 / 转发 / 安装 / hilog …）
       │
       ▼
       命令策略检查 → 通过则桥接；拒绝则 fail-closed 并写审计

一次客户端请求（逻辑）

hdc 客户端          hdc-remote 代理         主 HDC / 设备
│                   │                       │
│ TCP 连 host:port  │                       │
├─────────────────► │ CIDR/连接数检查        │
│                   ├─────────────────────► │
│ 握手/keepalive    │ 打开 target            │
│◄────────────────► │◄────────────────────► │
│ shell/file/fport  │ 协议桥分流             │
├─────────────────► ├─────────────────────► │
│◄───────────────── │◄───────────────────── │

功能详解

1. 设备发现与自动转发

服务通过 HDC host channel 协议直接读 USB / TCP target 列表，不在外再包一层 hdc CLI。

状态机：online / offline / stale
在线 USB 自动开转发，离线自动冻结
扫描周期、stale 阈值可配（默认 2s / 10s）

插拔设备后，日志会跟着变；多设备场景靠 serial 一眼区分。

2. 稳定端口（Binding）与租约（Lease）

这是「远程调试好不好用」的关键体验点：

概念	含义
Binding	设备 ↔ 稳定端口的持久映射，主/备 JSON 快照落盘，重启可恢复映射关系
Lease	当前进程内的转发租约与活跃连接；不跨进程硬恢复，重启后按当时在线设备重新开启

默认端口池：50000–50500
租约保险 TTL 默认 8h（运行期持续刷新；异常停止刷新后到期自动关入口）
就绪时打印可直接复制的 connect="hdc tconn ..."；客户端连上后再打 connection accepted

3. 网络接入：局域网与公网

监听默认 0.0.0.0。能不能连上，看白名单，不看「是不是局域网」——局域网默认就能用；公网只要网络打通并放行来源，同样可以。

场景	做法
本机 / 公司局域网	默认即可（loopback + `10/8`、`172.16/12`、`192.168/16`）
指定办公网段	设置 `HDC_REMOTE_ALLOWED_SOURCE_CIDRS`
公网 / 跨公网 VPN	把客户端出口 IP/网段写入白名单；`HDC_REMOTE_PUBLIC_HOST` 设为公网 IP 或域名，让日志里的连接命令可复制；防火墙只开代理端口

export HDC_REMOTE_PUBLIC_HOST=debug.example.com
export HDC_REMOTE_ALLOWED_SOURCE_CIDRS=127.0.0.1/32,::1/128,203.0.113.10/32
./hdc-remote
# 客户端：hdc tconn debug.example.com:50000

说明：公网可用，但会把设备调试面暴露到网络；请收紧 CIDR，并配合防火墙。不建议对全网 0.0.0.0/0 开放。

4. Daemon 会话与 Shell

hdc tconn 建立的是标准 HDC daemon TCP 会话：

握手、keepalive
交互式 shell
一次性命令：hdc -t host:port shell echo ok

远程侧体验尽量贴近「设备插在本机」。

5. Unity 协议桥

独立 target channel 流式转发（超时默认 30m）：

能力	用途
`hilog`	抓日志
`jpid`	JDWP 进程列表
`track-jpid`	JDWP 进程跟踪
`bugreport`	导出 bugreport

6. 文件传输

file send / file recv
单文件上限默认 2 GiB，临时空间默认 4 GiB，超时默认 10m
暂不支持：压缩传输、目录整包（会明确拒绝，避免静默踩坑）

7. 端口转发

fport / rport
端点：tcp、localabstract、localreserved、localfilesystem

适合把设备侧服务映射到客户端可达的端口，做联调或自动化。

8. 应用安装 / 卸载

install / uninstall 经 App 协议桥到设备
压缩包安装等未支持选项会 fail-closed，直接报错而不是半成功

9. 准入、限流与命令策略

握手前三道闸：

来源 CIDR
单设备并发连接（默认 2）
单连接 channel 数（默认 64）

命令策略 HDC_REMOTE_POLICY_PROFILE：

档位	行为
`studio-debug`（默认）	拦已知高危，放行常规调试
`restricted`	额外禁网络下载 / 外连类工具等

还可用 HDC_REMOTE_EXTRA_DENIED_EXECUTABLES 追加禁止的 shell 可执行名（只能加严）。

重启、刷写、root/runmode、改 HDC daemon 状态等会 fail-closed。注意：策略是尽力而为黑名单，不是完备沙箱，不能代替网络安全。

10. 审计

决策写入 STATE_DIR/audit.jsonl（默认 ./data/audit.jsonl），不含文件内容与完整命令行，便于事后核对「谁在什么时候被放行/拒绝」。

11. 日志与排障

./hdc-remote -v
./hdc-remote -log-level=debug

debug 下可看到：设备扫描、租约续期、主 HDC dial/open target、daemon 帧路由（命令名/channel）、握手与 shell 打开等。连不上时先看是否被 CIDR 挡住、端口是否通、日志里的 serial / connect 是否抄对。

客户端常用命令示例

设 HOST:PORT 来自日志中的 connect=：

hdc tconn HOST:PORT
hdc -t HOST:PORT shell
hdc -t HOST:PORT shell echo ok
hdc -t HOST:PORT file send ./local.txt /data/local/tmp/local.txt
hdc -t HOST:PORT file recv /data/local/tmp/local.txt ./local.txt
hdc -t HOST:PORT install ./app.hap
hdc -t HOST:PORT uninstall <bundleName>
hdc -t HOST:PORT hilog
hdc -t HOST:PORT fport tcp:8080 tcp:8080

子命令以本机 hdc 为准；服务端按协议桥转发，未实现能力会返回明确失败信息。

快速使用

服务端（插 USB 的机器）

# 本机 hdc server 已运行，且至少一台 USB 在线
go run ./cmd/hdc-remote
# 或下载 Release 对应平台二进制直接运行

客户端（任意能访问代理端口的机器）

hdc tconn <日志中的 host:port>
hdc -t <host:port> shell echo ok

常用环境变量：

变量	默认	作用
`HDC_REMOTE_HDC_ADDR`	`127.0.0.1:8710`	主 HDC server
`HDC_REMOTE_PROXY_PORT_MIN` / `MAX`	`50000` / `50500`	代理端口范围
`HDC_REMOTE_PUBLIC_HOST`	自动探测（优先私网）	日志展示的连接主机
`HDC_REMOTE_ALLOWED_SOURCE_CIDRS`	loopback + 私网	来源白名单
`HDC_REMOTE_POLICY_PROFILE`	`studio-debug`	命令策略档位
`HDC_REMOTE_MAX_CONNECTIONS`	`2`	单设备并发连接上限

完整配置表见仓库 README。

关于 v0.1.0（首版说明）

当前是第一个公开发布版本，日常路径（自动发现、hdc tconn、shell、文件收发、安装卸载、hilog、端口转发等）已能跑通，但仍请按「早期版本」预期使用：

不同机型、hdc 客户端版本、网络环境下，个别命令或边界场景可能还有问题
协议覆盖按优先级推进，未支持能力会明确失败，而不是静默成功
已知能力边界包括：自动转发仅针对在线 USB（可列出 TCP target，但不对其自动开代理）；文件侧暂不支持压缩传输与目录整包；无账号体系 / Web 控制台，安全依赖 CIDR、并发限制、命令策略与审计
公网务必收紧白名单；命令策略不能替代防火墙

欢迎把复现步骤、日志和期望行为反馈回来，后续版本会按真实使用优先修。

反馈

项目地址：https://github.com/yabi-zzh/hdc-remote-kit

欢迎试用。遇到异常、兼容问题，或希望补齐某条能力，可提 Issue / PR（尽量带上 hdc 版本、机型与日志），也可以直接在本帖留言。若觉得有用，欢迎点个 Star。

暂无回复。

需要登录后方可回复, 如果你还没有账号请点击这里注册。