那天晚上 11 点，我在火车上 SSH 到服务器查日志。手机浏览器切了个微信回来，tab 被 kill 了，session 断了，查了一半的日志全没了。
我翻了翻手机上所有终端 app——Termius 、Blink Shell 、ServerCat——它们都有同一个问题：你不能真的"保持连接"。系统杀后台、网络切换、锁屏省电，随便哪个都能把你的 SSH 掐断。
那能不能反过来？让 shell 在远程服务器上一直跑，手机只是个"显示器"——断了就断了，重连回来输出还在。
这就是 Corterm （云枢终端）的出发点：session 不是连接，是状态。
先把架子搭起来
思路很直接：
- Worker — 装在远程机器上的轻量 agent ，管 PTY 生命周期。你断了连，shell 照跑。
- Gateway — 中间层，管认证、路由、session 协调。Worker 和 Client 之间不直接通信。
- Client — 纯渲染层。断了重连时，Gateway 把 Worker 上的 scrollback buffer 吐给你，无缝衔接。
Client (Browser/iOS/Android/HarmonyOS)
↕ SignalR
Gateway (.NET 10)
↕ SignalR
Worker (.NET 10 + PTY)
Gateway 和 Worker 用 .NET 10 + SignalR ，Client 端浏览器用 React + xterm.js ，iOS/Android 用 MAUI 。浏览器、手机 App 都跑通了，接下来是鸿蒙。
手搓 SignalR：1091 行 ArkTS 的协议实现
鸿蒙端的第一道坎：SignalR 。
Corterm 的 Gateway 是 .NET 写的，实时通信用的 SignalR 。iOS/Android 那边有官方 SDK ，浏览器更不用说。但鸿蒙……我翻了半天文档，没有。连第三方实现都没有。
两条路：要么在 Gateway 加一层 WebSocket 中间层，要么直接在 ArkTS 里实现 SignalR 协议。前者意味着改服务端，所有客户端都得测。后者意味着我要在一个 TypeScript 的严格子集里，手写一个协议栈。
我选了后者。
Negotiate 握手
SignalR 连接的第一步不是 WebSocket ，而是一个 HTTP POST negotiate 请求。服务端返回一个 connectionToken，后续 WebSocket 连接必须带上这个 token 。
// HttpConnection.ets
private async negotiate(accessToken: string): Promise<string> {
const negotiateUrl = `${this.url}/negotiate?negotiateVersion=1`;
const httpClient = http.createHttp();
const headers: Record<string, string> = {
'Accept': 'application/json',
'Content-Type': 'application/json',
};
if (accessToken.length > 0) {
headers['Authorization'] = `Bearer ${accessToken}`;
}
const response = await httpClient.request(negotiateUrl, {
method: http.RequestMethod.POST,
header: headers,
connectTimeout: 15000,
readTimeout: 15000,
});
const body = response.result as string;
const negotiateResponse = JSON.parse(body) as NegotiateResponse;
this.connectionId = negotiateResponse.connectionId ?? '';
return negotiateResponse.connectionToken ?? '';
}
鸿蒙的网络 API 是 @kit.NetworkKit 里的 http.createHttp() 和 webSocket.createWebSocket()，用法跟 Node.js 的差不多，但所有东西都得显式类型声明。
WebSocket 连接
拿到 token 后，拼 URL ，建 WebSocket：
// HttpConnection.ets
private async connectWebSocket(accessToken: string): Promise<void> {
const wsUrl = this.url
.replace('https://', 'wss://')
.replace('http://', 'ws://');
let fullUrl = wsUrl;
const params: string[] = [];
if (this.connectionToken.length > 0) {
params.push(`id=${encodeURIComponent(this.connectionToken)}`);
}
if (accessToken.length > 0) {
params.push(`access_token=${encodeURIComponent(accessToken)}`);
}
if (params.length > 0) {
fullUrl += '?' + params.join('&');
}
this.ws = webSocket.createWebSocket();
const ws = this.ws;
const openPromise = new Promise<void>((resolve, reject) => {
ws.on('open', () => resolve());
ws.on('error', (err: Error) => {
if (!this.stopRequested) reject(new Error(`WebSocket error: ${err.message}`));
});
});
ws.on('message', (_err: Error, data: string | ArrayBuffer) => {
let text: string;
if (typeof data === 'string') {
text = data;
} else {
text = buffer.from(data).toString('utf-8');
}
if (this.onreceive !== null) {
this.onreceive(text);
}
});
await ws.connect(fullUrl, { header: connectHeaders });
await openPromise;
}
Hub 协议层
SignalR 不是裸 WebSocket 。它有自己的消息格式——我打开 C# 源码看了下，其实就 5 种消息类型：
- Type 1 — InvocationMessage （双向 RPC 调用）
- Type 2 — StreamItemMessage （流式结果）
- Type 3 — CompletionMessage （ RPC 响应）
- Type 6 — Ping （心跳）
- Type 7 — Close （关闭）
消息之间用 0x1E（ ASCII record separator ）分隔。processIncomingData 是整个消息分发管道的入口：
// HubConnection.ets
private processIncomingData(data: string): void {
// 第一条消息是 handshake response
if (this.handshakePromise !== null) {
this.protocol.decodeHandshakeResponse(data);
const promise = this.handshakePromise;
this.handshakePromise = null;
promise.resolve();
return;
}
// 常规消息
const messages = this.protocol.decodeMessages(data, this.logger);
for (const message of messages) {
this.dispatchMessage(message);
}
}
private dispatchMessage(message: HubMessageBase): void {
this.resetServerTimeout();
switch (message.type) {
case 1: { // Invocation
const invocation = message as InvocationMessage;
this.invokeHandler(invocation.target, invocation.arguments);
break;
}
case 2: { // StreamItem
const pending = this.streamManager.getInvocation(streamItem.invocationId);
if (pending !== undefined) pending.resolve(streamItem.item);
break;
}
case 3: { // Completion
const pending = this.streamManager.removeInvocation(completion.invocationId);
if (pending !== undefined) {
if (completion.error.length > 0) pending.reject(new Error(completion.error));
else pending.resolve(completion.result);
}
break;
}
case 6: break; // Ping
case 7: this.handleCloseMessage(close); break;
}
}
Keepalive 和重连
心跳每 15 秒发一次 Ping ，服务端 30 秒没消息就判定超时：
private resetKeepAlive(): void {
this.pingTimer = setInterval(() => {
const ping = new PingMessage();
const encoded = this.protocol.encodeMessage(ping);
this.httpConnection.send(encoded);
}, this.keepAliveIntervalInMilliseconds) as number; // 15000ms
}
private resetServerTimeout(): void {
clearTimeout(this.serverTimeoutTimer);
this.serverTimeoutTimer = setTimeout(() => {
this.httpConnection.stop(new Error('Server timeout'));
}, this.serverTimeoutInMilliseconds) as number; // 30000ms
}
重连策略是 SignalR 的经典配置 [0, 2000, 5000, 10000, 30000]——先立即重试，然后 2 秒、5 秒、10 秒、30 秒。但官方 SDK 试完这 5 次就放弃了。我的实现改成了循环重试，延迟数组里的最后一个值（ 30 秒）会一直用下去，最多 15 次之后才真正断开：
private scheduleReconnect(): void {
if (this.stopRequested) return;
const delayIndex = Math.min(this.reconnectAttempt, this.reconnectDelays.length - 1);
const delay = this.reconnectDelays[delayIndex];
this.reconnectTimer = setTimeout(() => this.attemptReconnect(), delay) as number;
}
ArkTS 的那些坑
写 SignalR 客户端最痛的不是协议本身，而是 ArkTS 的限制。它是 TypeScript 的严格子集：
- 不能用
as const— 只能用class X { static readonly A = '...' } - 不能写无类型对象字面量 —
{ key: value }直接报错，必须声明类型 - 不能用解构赋值 —
const [k, v] of Object.entries(obj)编译不过 - throw 只能抛 Error — catch 到的任意值不能直接 throw
每一条都是我在编译报错后才学到的。
在 ArkWeb 里跑 xterm.js
终端渲染的答案很明确：xterm.js 。问题是它跑在浏览器里，而我要在 HarmonyOS 的原生 app 里用它。
HarmonyOS 提供了 ArkWeb （ WebView 组件），有 WebMessagePort 做双向通信。我先试了 javaScriptProxy，崩溃不断，换成 WebMessagePort 才稳定下来。
核心逻辑：创建一对 MessagePort ，Port 0 发给 HTML 端，Port 1 留在 native 端监听：
// XtermWebview.ets
private initMessagePort() {
this.msgPorts = this.webviewController.createWebMessagePorts();
// Port 1 留在 native 端
this.msgPorts[1].onMessageEvent((result: webview.WebMessage) => {
const msg = JSON.parse(result as string) as Record<string, Object>;
const type = msg['type'] as string;
if (type === 'input') {
this.onInput(msg['data'] as string);
} else if (type === 'resize') {
const cols = msg['cols'] as number;
const rows = msg['rows'] as number;
this.onResize(cols, rows);
}
});
// Port 0 发给 HTML 端
this.webviewController.postMessage('__init_port__', [this.msgPorts[0]], '*');
}
输出方向反过来：native 拿到 Worker 的输出，base64 编码后调 runJavaScript 写入 xterm：
writeOutput(base64Payload: string) {
const escaped = base64Payload.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
this.webviewController.runJavaScript(`writeBase64Output("${escaped}")`);
}
为什么用 base64 ？因为终端输出包含二进制数据（ ANSI 转义序列、控制字符），直接当 JSON 字符串传会炸。
整个终端页面的生命周期是一个 9 状态的状态机：Disconnected → Connecting → Replaying → Live → Reconnecting → ...。重连时 Gateway 先 replay scrollback buffer ，然后切到 Live 模式，用户感觉不到断过。
手机上怎么按 Ctrl+C
终端有了，但我怎么在手机上发 SIGINT ？
没有键盘的设备用终端，这是所有移动端终端 app 的噩梦。
我的解法是 VirtualKeyBar——一个水平可滚动的虚拟按键条。关键是 Sticky Modifier：Ctrl 和 Alt 是 latch 按键，按一下变亮（激活），再按下一个字符键时才发送组合键。
// VirtualKeyBar.ets — LatchButton 组件
@Component
struct LatchButton {
label: string = ''
@Prop latched: boolean = false
onToggle: () => void = () => {}
build() {
Button(this.label)
.backgroundColor(this.latched ?
$r('app.color.terminal_secondary_container') :
$r('app.color.terminal_surface_container_high'))
.onClick(() => {
clickHaptic();
this.onToggle();
})
}
}
Ctrl + 字母的映射藏在 handleVirtualKey 里：
// TerminalPage.ets
private handleVirtualKey(key: string) {
if (key.startsWith('Ctrl+')) {
const label = key.substring(5);
// a-z → 0x01-0x1A
const ch = label.toLowerCase().charCodeAt(0);
if (ch >= 97 && ch <= 122) {
this.sendInput(String.fromCharCode(ch - 96));
}
}
// Escape sequences
const inputMap: Record<string, string> = {
'ArrowUp': '\x1b[A',
'ArrowDown': '\x1b[B',
'ArrowRight': '\x1b[C',
'ArrowLeft': '\x1b[D',
};
}
'c'.charCodeAt(0) 是 99 （ 0x63 ），减 96 得 3 ，String.fromCharCode(3) 就是 \x03——SIGINT 。一行数学运算解决了所有 Ctrl+字母的映射。
CI/CD 十五连跪
6 月 8 号，我开始写 harmony-release.yml。
然后接下来的 3 天里，我推了这个文件 15 次。
Pipeline 长这样：
Tag push (harmony-v*) → 版本提取 → 签名准备 → hvigor 构建
→ AGConnect 认证 → OBS 上传 → 编译轮询 → 提审
踩坑中最惨的几个：
AGConnect API 文档是解谜游戏。 /upload-url/for-obs 端点文档只写了入参，没告诉你返回的 header 要原样传给 OBS 的 PUT 请求。我是抓包才搞明白的。
编译状态要轮询。 华为的服务端编译一个 .app 文件要 60 秒以上，API 没有回调，只能 30 秒一次轮询，最多 20 次：
- name: Query compile status
run: |
for i in $(seq 1 20); do
SUCCESS_STATUS=$(curl -s ... | jq -r '.pkgStateList[0].successStatus')
if [ "$SUCCESS_STATUS" = "0" ]; then
echo "Compile successful"
exit 0
fi
sleep 30
done
自托管 runner 的脏文件。 有一次构建失败，查了半天发现是 /tmp 下残留了上次的 .app 文件，签名步骤拿错了文件。于是加了一行 rm -rf 在 pipeline 开头。
每次看到 GitHub Actions 红叉，我都觉得自己在跟华为的文档玩解谜游戏。
53 天的数字
425 次提交。53 天。1 个人。5 个平台。
其中鸿蒙端：
- 8645 行 ArkTS
- 1091 行 手写 SignalR 客户端
- 9 个 HAR 模块（ 1 entry + 5 feature + 3 common ）
- 5 月 8 日 第一个鸿蒙 commit → 6 月 11 日 上架华为应用市场
接下来要做的：文件传输、端口转发、多 tab 、命令片段。
如果你也觉得手机上应该有个不中断的终端，来看看：github.com/monster-echo/CortexTerminal2
Docker 一键体验：
docker run -d -p 5000:5000 ghcr.io/monster-echo/cortex-terminal:latest
1
Select Language