Skip to content

About

SSH-compatible CLI surface over Lark messages.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

36 Commits

Folders and files

Repository files navigation

exec-over-lark

exec-over-lark 是一个用飞书话题群传输命令输入和执行输出的远程命令工具。它提供接近 ssh host command、ssh host 和 ssh -t host command 的命令行体验,但不实现 SSH wire protocol。

核心模型:

  • 本地用户运行 elark CLI。
  • 本地 elarkd 读取 host 配置,通过本地 Unix socket 接收 CLI 请求,并用 client bot 在飞书话题群里创建 root message。
  • 远端 elarkd 使用 server bot 监听飞书消息,校验 bot 提及和群后,在远端机器执行命令或 PTY shell。
  • 每个飞书 root message 对应一个连接,后续输入、输出、心跳和退出状态都通过该 root message 的回复消息传输。

功能边界

支持:

  • 非交互命令:elark macmini 'uname -a'
  • 默认登录 shell:elark macmini
  • 强制 PTY:elark -t macmini 'vim file'
  • stdin/stdout/stderr 与远端 exit code 传递
  • 双 bot 身份、群成员关系、可选 chat 白名单
  • 发送限流、同连接消息聚合和大输出拆分

不支持:

  • SSH wire protocol
  • scp、sftp、rsync -e ssh
  • SSH port forwarding、agent forwarding
  • 把飞书当作高吞吐 TCP 隧道
  • daemon 停机期间的飞书历史消息恢复

第一版协议不做应用层 ACK,也不做额外加密。消息正文只做 base64 编码,访问控制依赖飞书 bot 身份、群成员关系和配置中的 sender/chat 校验。

安装

从 Release 安装

推荐使用一键安装脚本。脚本会检测 macOS/Linux 和 CPU 架构,从 GitHub latest release 选择匹配的归档,安装 elark 和 elarkd,默认执行 elarkd install 注册后台服务,并在结束时输出安装位置、生成初始配置的命令和启动后台进程的命令。

curl -fsSL https://raw.githubusercontent.com/hachiwii/exec-over-lark/main/scripts/install.sh | sh

也可以先下载脚本再执行,或指定安装目录:

curl -fsSL https://raw.githubusercontent.com/hachiwii/exec-over-lark/main/scripts/install.sh -o install.sh
sh install.sh
ELARK_INSTALL_DIR="$HOME/.local/bin" sh install.sh
sh install.sh --system
sh install.sh --no-install

脚本优先安装到已经在 PATH 中的 $HOME/.local/bin,其次选择已有可写 PATH 目录;如果没有可写 PATH 目录,会创建 $HOME/.local/bin 并提示把它加入 PATH。 传入 --system 时,脚本会用 sudo elarkd install --system 安装系统级 daemon,但 daemon 进程会以触发安装的当前用户运行,并在 ~/.elark/install.json 记录安装位置;后续 sudo elarkd start、sudo elarkd stop、elarkd status 等命令可以从记录中推断 system 模式,不需要再显式传 --system。传入 --no-install 时只安装二进制,不自动注册 daemon。

如果还没有发布 GitHub release,releases/latest 会返回 404;先发布一个包含对应系统归档的 release 后再执行脚本。

手动安装时,在 GitHub Releases 下载与你的系统匹配的压缩包,例如:

  • exec-over-lark_vX.Y.Z_darwin_amd64.tar.gz
  • exec-over-lark_vX.Y.Z_darwin_arm64.tar.gz
  • exec-over-lark_vX.Y.Z_linux_amd64.tar.gz
  • exec-over-lark_vX.Y.Z_linux_arm64.tar.gz

解压后把 elark 和 elarkd 放到 PATH 中:

tar -xzf exec-over-lark_vX.Y.Z_linux_amd64.tar.gz
mkdir -p "$HOME/.local/bin"
cp exec-over-lark_vX.Y.Z_linux_amd64/elark "$HOME/.local/bin/elark"
cp exec-over-lark_vX.Y.Z_linux_amd64/elarkd "$HOME/.local/bin/elarkd"
chmod 0755 "$HOME/.local/bin/elark" "$HOME/.local/bin/elarkd"

确认安装:

elark --help
elarkd init --help

生成初始配置并启动本地后台进程:

elarkd init --client
elarkd start

远端机器通常生成 server 配置并安装或前台运行 elarkd:

elarkd init --server
elarkd install
elarkd start
elarkd run --config ~/.elark/config.toml

从源码安装

需要 Go 1.24 或更高版本。

git clone https://github.com/hachiwii/exec-over-lark.git
cd exec-over-lark
go install ./cmd/elark ./cmd/elarkd

也可以直接构建本地二进制:

go build -o ./bin/elark ./cmd/elark
go build -o ./bin/elarkd ./cmd/elarkd

飞书准备

部署需要两个飞书 bot:

  • client bot:本地侧使用,负责发送命令和接收输出。
  • server bot:远端侧使用,负责接收命令和发送输出。

准备步骤:

  1. 创建两个飞书应用并启用 bot。
  2. 为两个应用配置接收消息事件,至少需要消息接收事件;server bot 还需要 bot 入群事件用于 bootstrap。
  3. 把两个 bot 都拉入同一个飞书话题群。
  4. 在远端 elarkd 启动后,server bot 入群时会发送:
exec-over-lark server ready
chat_id: oc_xxx
bot_openid: ou_server_bot

把其中的 chat_id 和 bot_openid 写入本地侧 host 配置。

配置文件

默认配置路径是:

~/.elark/config.toml

elark 和 elarkd 都可以通过 --config PATH 使用其它配置文件。配置文件会保存飞书应用密钥,权限必须收紧:

chmod 700 ~/.elark
chmod 600 ~/.elark/config.toml

如果配置不存在,先生成模板:

elarkd init --client
elarkd init --server
elarkd init --client --config ./client.toml
elarkd init --server --config ~/.elark/server.toml --force

init 只生成模板,不连接飞书,不校验 app_id / app_secret,也不会打印 secret。目标文件已存在时默认拒绝覆盖,只有传 --force 才会覆盖。

本地侧配置示例

node_name = "local"
default_host = "macmini"

[ipc]
enabled = true
socket_path = "~/.local/run/exec-over-lark/elarkd.sock"

[lark]
app_id = "cli_client_xxx"
app_secret = "client_secret_xxx"
send_cooldown = "500ms"
lark_text_request_limit_bytes = 153600

[connection]
heartbeat_interval = "10s"
heartbeat_timeout = "30s"
sequence_gap_timeout = "30s"

[exec]
enabled = false

[hosts.macmini]
chat_id = "oc_xxx"
peer_bot_open_id = "ou_server_bot"
shell = "/bin/zsh"
stream_chunk_bytes = 12000
default_cwd = "/Users/you"

[hosts.devbox]
chat_id = "oc_yyy"
peer_bot_open_id = "ou_server_bot_yyy"
shell = "/bin/bash"
stream_chunk_bytes = 12000

本地侧字段说明:

  • node_name:当前节点名,用于诊断输出。
  • default_host:默认 host 名称。
  • ipc.enabled = true:启动本地 client 服务,允许 elark CLI 通过本地 Unix socket 调用本地 daemon。
  • ipc.socket_path:本地 daemon socket 路径,所在目录权限不能宽于 0700。
  • lark.app_id / lark.app_secret:client bot 的凭据。
  • lark.send_cooldown:同一 chat 内两次飞书发送之间的最小间隔,默认 "500ms";不同 chat 的发送冷却彼此独立。
  • lark.lark_text_request_limit_bytes:飞书文本消息请求体上限,第一版固定为 153600。
  • connection.heartbeat_interval:连接空闲多久后发送 heartbeat,默认 "10s"。
  • connection.heartbeat_timeout:声明给对端的超时时间,默认 "30s"。
  • connection.sequence_gap_timeout:收到跳号 frame 后等待缺失序号的最长时间,默认 "30s"。
  • exec.enabled = false:不启动远端 server 执行服务,因此不会接受飞书消息触发本机命令执行。
  • hosts.<name>.chat_id:该 host 使用的话题群 ID。
  • hosts.<name>.peer_bot_open_id:该 host 的 server bot OpenID,本地只处理它发出的返回消息。
  • hosts.<name>.shell:远端默认 shell。
  • hosts.<name>.stream_chunk_bytes:流式输出进入协议层前的切片大小,默认 12000。
  • hosts.<name>.default_cwd:可选。未通过 --cwd 覆盖时作为远端默认工作目录;不配置则远端使用执行用户 home。

远端侧配置示例

node_name = "macmini"

[ipc]
enabled = false
socket_path = "~/.local/run/exec-over-lark/elarkd.sock"

[lark]
app_id = "cli_server_xxx"
app_secret = "server_secret_xxx"
send_cooldown = "500ms"
lark_text_request_limit_bytes = 153600

[connection]
heartbeat_interval = "10s"
heartbeat_timeout = "30s"
sequence_gap_timeout = "30s"

[exec]
enabled = true
default_shell = "/bin/zsh"
max_sessions = 8
stream_chunk_bytes = 12000
# 不设置表示允许所有 chat;设置后只处理列表内 chat。
# allowed_chat_ids = ["oc_xxx", "oc_yyy"]

远端侧字段说明:

  • ipc.enabled = false:不启动本地 client 服务,因此远端只作为 server 执行命令;如果设为 true,同一个 daemon 会同时启动 client 和 server 两侧。
  • lark.app_id / lark.app_secret:server bot 的凭据。
  • exec.enabled = true:启动远端 server 执行服务,允许飞书消息触发本机命令执行。
  • exec.default_shell:非交互命令使用的默认 shell。
  • exec.max_sessions:远端同时执行的 session 上限,默认 8。
  • exec.stream_chunk_bytes:远端 stdout/stderr 切片大小,默认 12000。
  • exec.allowed_chat_ids:可选 chat 白名单。不配置表示允许所有 chat。

ipc.enabled 和 exec.enabled 是两个独立开关:只开 ipc.enabled 是 client-only daemon,只开 exec.enabled 是 server-only daemon,两个都开时 daemon 会同时运行 client 和 server 模式,并共享同一个飞书 websocket。共享 websocket 意味着这一份配置只能对应一个 bot 身份;如果 client 和 server 使用两个不同 bot app,仍需要分别启动两个 daemon。

所有时间字段都使用字符串,支持 ms、s、m、h、d,例如 "1000ms"、"10s"、"5m"、"1h"。

使用方法

启动 daemon

本地侧:

elarkd install
elarkd start
elarkd status
elark doctor

也可以直接运行:

elarkd run --config ~/.elark/config.toml

远端侧通常用 systemd、launchd 或进程管理器长期运行:

elarkd install
elarkd start
elarkd status

查看和诊断

列出本地配置里的 host:

elark hosts

输出本地 CLI doctor 报告。elark doctor 只检查本地配置是否有效、ipc.enabled 是否开启、本地 daemon socket 是否可连接,以及 daemon 返回的 event/outbound 状态;它不会刷新 Lark token、不会查询 bot/chat/peer bot/bootstrap,也不会向群里发送 ping 或其他消息:

elark doctor

检查 elarkd 自身能否正常启动时使用 elarkd doctor。它会检查配置文件并刷新 Lark tenant token 来校验 app_id/app_secret 是否有效,不发送消息:

elarkd doctor

执行命令

非交互命令:

elark macmini 'uname -a'
elark macmini 'cd /srv/app && docker compose ps'

传递 stdin:

echo hello | elark macmini 'cat | wc -c'

指定远端工作目录:

elark --cwd /srv/app macmini 'git status --short'

指定超时:

elark --timeout 30s macmini 'long-running-command'

交互式 shell:

elark macmini

强制 PTY:

elark -t macmini
elark -t macmini 'vim file'

禁用 PTY:

elark -T macmini 'env | sort'

请求关闭连接:

elark kill om_xxx

当前 CLI 也保留了 elark sessions、elark attach <conn_id> 和 elark daemon stop 命令入口;它们依赖后续 daemon control RPC,在 IPC v1 中尚未开放完整能力。

协议摘要

飞书 text 消息中的协议 frame 格式为:

EOL1 <seq> <type> <base64_payload>

一条飞书消息可以包含多个 frame,每行一个。conn_id 不放在 payload 中,固定由飞书 root message ID 决定。

常见 frame 类型:

  • start:创建远端命令或 PTY session。
  • start_ack:远端接受 session,并声明 heartbeat 设置。
  • stdin / stdout / stderr:流式输入输出。
  • resize:PTY 窗口大小变化。
  • signal:转发 INT、TERM 等信号。
  • heartbeat:连接保活。
  • exit:远端进程退出码。
  • error:协议或执行错误。
  • close:请求关闭连接。

序列号按连接和方向单独递增,只用于进程内去重和顺序检查,不用于 ACK 或重传。

安全建议

  • 始终保持配置文件权限为 0600,配置目录权限为 0700。
  • 远端侧建议显式配置 exec.allowed_chat_ids。
  • 不要把 server bot 拉入不可信群。
  • 不要在群里发送不希望群成员、管理员或合规审计看到的命令和输出。
  • 不要把 lark.app_secret 写入日志、截图或公开文档。
  • 远端 elarkd 以哪个系统用户启动,命令就以哪个用户执行。

开发

运行测试:

go test ./...

构建两个入口:

go build ./cmd/elark
go build ./cmd/elarkd

项目主要包:

  • cmd/elark:命令行入口。
  • cmd/elarkd:统一 daemon 入口。
  • internal/config:TOML 配置、默认路径、模板生成和权限检查。
  • internal/ipc:本地 Unix socket 协议。
  • internal/lark:飞书 OpenAPI client、token、bot OpenID、bot 入群检查和消息发送。
  • internal/outbound:按 chat 共享的发送调度、限流、聚合、重试和 heartbeat。
  • internal/protocol:EOL1 frame 编解码。
  • internal/session:连接、序列窗口、peer timeout 和 session 分发。
  • internal/remoteexec:远端非交互命令执行。
  • internal/pty:Unix PTY 和终端控制。
  • internal/bootstrap:server bot 入群 bootstrap 消息。
  • internal/doctor:配置和运行状态诊断。

License

MIT

About

SSH-compatible CLI surface over Lark messages.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages