feat(device): 设备端源码独立成 device/,可脱离具体服务器编译运行

- 模块名去掉私有域名(agent-device),import 路径中性化
- 二进制不内置任何服务器地址与 token,-server 必填
- 新增 -config:token 可放 JSON 文件,避免 ps 泄露
- scripts/build.sh 只做本地构建(有 Go 用 Go,没 Go 用 docker 镜像)
- README 面向使用者,部署细节不进仓库
This commit is contained in:
2026-11-19 17:21:12 +08:00
parent 7d855454a8
commit 4333a53dd3
12 changed files with 1034 additions and 0 deletions
+3
View File
@@ -22,3 +22,6 @@ app/server/version.json
# 部署配置真身(含密钥,模板见 scripts/deploy.conf.example); # 部署配置真身(含密钥,模板见 scripts/deploy.conf.example);
deploy.conf deploy.conf
relay/config.json relay/config.json
# 设备端编译产物(交叉编译后本地生成,不入库)
device/bin/
+107
View File
@@ -0,0 +1,107 @@
# agent-device:远端设备执行端
把一台机器(Linux 盒子、Windows、macOS)变成 agent 的一双“手”:**主动出站**连到 core 的
WebSocket 端点,接收 shell 命令、流式回传输出与退出码、上报主机指标。
设备不需要公网 IP、不需要开任何入站端口,NAT、公司网络、随身热点都能用。
> 这不是通用 agent,只是执行端。会话、模型、记忆都在服务端;这里只负责“在那台机器上跑东西”。
## 二进制里没有服务器地址
`-server` 与 token 都**没有默认值**,不显式给就启动失败。所以拿到的二进制不会连到别人的服务器上——
它只连你指定的那一台。
## 安装
### 自己编译
需要 Go 1.22+:
```sh
git clone <本仓库> && cd device
go build -trimpath -ldflags "-s -w" -o bin/agent ./cmd/agent
```
交叉编译(一次出五个平台):
```sh
sh scripts/build.sh all
```
脚本只做构建:不联网、不推送、不依赖任何特定服务器。本机没有 Go 但装了 docker 时,
会自动用 `golang:1.23-alpine` 容器编译。
### 下载预编译
从本仓库的 Releases 页面取对应平台的文件(`agent-linux-arm64`、`agent-windows-amd64.exe` 等),
`chmod +x` 即可,静态链接、无运行时依赖,一个文件约 5.5 MB。
## 运行
```sh
# 直接给参数
./agent -server wss://your-host.example/dev/ws -token <TOKEN> -root /var/agent-work -name box-01
# 或走配置文件(token 不出现在 ps 里)
./agent -config agent.json
```
`agent.json`:
```json
{
"server": "wss://your-host.example/dev/ws",
"token": "…",
"root": "/var/agent-work",
"name": "box-01"
}
```
优先级:**命令行显式参数 > 环境变量 `NODE_TOKEN`(仅 token)> 配置文件 > 默认值**。
| 参数 | 说明 |
|---|---|
| `-server` | core 的接入地址,`wss://…/dev/ws` |
| `-token` | Bearer token,须与服务端 `DEVICE_TOKEN` 一致 |
| `-root` | 工作根目录,命令的 `cwd` 必须落在它之内(默认 `~/agent-work`,会自动建) |
| `-name` | 设备名,服务端用它区分设备(默认 hostname) |
| `-shell` | `sh` / `cmd` / `powershell`,默认按平台 |
| `-insecure` | 跳过证书校验(自签证书调试用) |
| `-fix-clock` | 证书报错时用服务器 `Date` 头校准本机时间(小设备没有 RTC 时用,Linux 需 root) |
设备名重复时后接入的会顶掉前一个连接(换机、重装不留僵尸连接)。
## 协议
一条 WebSocket 上全是 JSON 文本帧,`t` 区分类型:
| 方向 | 消息 |
|---|---|
| 设备 → core | `{t:"hello", ver, name, os, arch, shell, shell_path, shell_ver, root}` |
| core → 设备 | `{t:"exec", id, cmd, cwd, timeout_ms}` · `{t:"kill", id}` · `{t:"ping"}` · `{t:"health", id}` |
| 设备 → core | `{t:"chunk", id, out:"out"\|"err", chunk:<base64>}` · `{t:"exit", id, code, killed_by, ms, truncated}` · `{t:"pong"}` · `{t:"health", …}` |
- 保活:core 每 20 秒发 `ping`,设备回 `pong`;90 秒无任何消息即断开重连。
- 断线:指数退避 1s → 2s → 4s → … 上限 30s,连上后重置。
- 超时:命令超过 `timeout_ms` 由设备侧杀**进程组**,回 `killed_by:"timeout"`。
- 输出:单流超过上限截断并置 `truncated`。
- `shell` 报的是实际解释器(`/bin/sh` 可能是 dash / bash / busybox),连同版本,供模型决定命令语法。
## 安全边界
- 设备主动出站,服务端不需要知道设备 IP;
- token 走 `Authorization: Bearer`,与业务 token 分开;
- `cwd` 只约束**起始目录**,命令内部仍可 `cd` 到别处——给了 shell 就是这个语义,需要强隔离请用容器/namespaces;
- 同一个 token 可被多台设备共用(当前设计),吊销需换 token 并重启所有设备。
## 实测
| 用例 | 结果 |
|---|---|
| exec 基本 | cwd 自动创建,stdout/stderr 分流,退出码透传 |
| 超时 | 杀进程组,`killed_by=timeout` |
| 起始 cwd 越界 | 拒绝 |
| 断线重连 | 1s→2s→4s 退避,恢复后自动注册 |
在 Linux / macOS / Windows 三平台编译验证(amd64 + arm64)。
+81
View File
@@ -0,0 +1,81 @@
//go:build !windows
package main
// 主机指标:Linux 走 /proc,macOS 只取内存总量与磁盘,其余给 -1(不支持的平台别编数据)。
import (
"os"
"os/exec"
"runtime"
"strconv"
"strings"
"syscall"
)
type healthInfo struct {
HostUptimeSec int64
Load1, Load5, Load15 float64
MemTotalMB, MemFreeMB int64
DiskTotalGB, DiskFreeGB float64
TempC float64
}
func hostHealth() healthInfo {
h := healthInfo{
HostUptimeSec: -1, Load1: -1, Load5: -1, Load15: -1,
MemTotalMB: -1, MemFreeMB: -1, DiskTotalGB: -1, DiskFreeGB: -1, TempC: -1,
}
switch runtime.GOOS {
case "linux":
if b, err := os.ReadFile("/proc/uptime"); err == nil {
if f := strings.Fields(string(b)); len(f) > 0 {
if v, err := strconv.ParseFloat(f[0], 64); err == nil {
h.HostUptimeSec = int64(v)
}
}
}
if b, err := os.ReadFile("/proc/loadavg"); err == nil {
if f := strings.Fields(string(b)); len(f) >= 3 {
h.Load1, _ = strconv.ParseFloat(f[0], 64)
h.Load5, _ = strconv.ParseFloat(f[1], 64)
h.Load15, _ = strconv.ParseFloat(f[2], 64)
}
}
if b, err := os.ReadFile("/proc/meminfo"); err == nil {
for _, line := range strings.Split(string(b), "\n") {
f := strings.Fields(line)
if len(f) < 2 {
continue
}
kb, _ := strconv.ParseInt(f[1], 10, 64)
switch f[0] {
case "MemTotal:":
h.MemTotalMB = kb / 1024
case "MemAvailable:":
h.MemFreeMB = kb / 1024
}
}
}
if b, err := os.ReadFile("/sys/class/thermal/thermal_zone0/temp"); err == nil {
if v, err := strconv.ParseFloat(strings.TrimSpace(string(b)), 64); err == nil {
h.TempC = v / 1000
}
}
case "darwin":
// macOS 没有 /proc;内存总量走 sysctl(调用很少,允许 fork 一次)
if out, err := exec.Command("sysctl", "-n", "hw.memsize").Output(); err == nil {
if v, err := strconv.ParseInt(strings.TrimSpace(string(out)), 10, 64); err == nil {
h.MemTotalMB = v / (1 << 20)
}
}
}
var st syscall.Statfs_t
if err := syscall.Statfs("/", &st); err == nil {
h.DiskTotalGB = float64(st.Blocks) * float64(st.Bsize) / (1 << 30)
h.DiskFreeGB = float64(st.Bavail) * float64(st.Bsize) / (1 << 30)
}
return h
}
+67
View File
@@ -0,0 +1,67 @@
//go:build windows
package main
// Windows 指标:GetTickCount64(开机时长)+ GlobalMemoryStatusEx + GetDiskFreeSpaceExW。
// 负载/温度在 Windows 上没有等价指标,返回 -1。
import (
"syscall"
"unsafe"
)
type healthInfo struct {
HostUptimeSec int64
Load1, Load5, Load15 float64
MemTotalMB, MemFreeMB int64
DiskTotalGB, DiskFreeGB float64
TempC float64
}
var (
kernel32 = syscall.NewLazyDLL("kernel32.dll")
procTick = kernel32.NewProc("GetTickCount64")
procMem = kernel32.NewProc("GlobalMemoryStatusEx")
procDiskF = kernel32.NewProc("GetDiskFreeSpaceExW")
)
type memStatusEx struct {
Length uint32
MemoryLoad uint32
TotalPhys uint64
AvailPhys uint64
TotalPageFile uint64
AvailPageFile uint64
TotalVirtual uint64
AvailVirtual uint64
AvailExtendedVirtual uint64
}
func hostHealth() healthInfo {
h := healthInfo{
HostUptimeSec: -1, Load1: -1, Load5: -1, Load15: -1,
MemTotalMB: -1, MemFreeMB: -1, DiskTotalGB: -1, DiskFreeGB: -1, TempC: -1,
}
if r, _, _ := procTick.Call(); r != 0 {
h.HostUptimeSec = int64(r / 1000)
}
var m memStatusEx
m.Length = uint32(unsafe.Sizeof(m))
if r, _, _ := procMem.Call(uintptr(unsafe.Pointer(&m))); r != 0 {
h.MemTotalMB = int64(m.TotalPhys >> 20)
h.MemFreeMB = int64(m.AvailPhys >> 20)
}
if p, err := syscall.UTF16PtrFromString("C:\\"); err == nil {
var free, total, totalFree uint64
if r, _, _ := procDiskF.Call(
uintptr(unsafe.Pointer(p)),
uintptr(unsafe.Pointer(&free)),
uintptr(unsafe.Pointer(&total)),
uintptr(unsafe.Pointer(&totalFree)),
); r != 0 {
h.DiskTotalGB = float64(total) / (1 << 30)
h.DiskFreeGB = float64(free) / (1 << 30)
}
}
return h
}
+411
View File
@@ -0,0 +1,411 @@
// node-agent:跑在盒子 / Windows / 任意 Linux 上,主动出站连 core 的 wss,接收并执行命令。
//
// node-agent -server wss://your-host.example/dev/ws -token <TOKEN> -root /var/agent/work
// node-agent -config agent.json # 同上,但 token 不落在命令行(ps 看不见)
//
// 设计约束(对齐 files/print/agent):
// - 只出站,服务器不需要任何入站端口
// - 断线指数退避重连,半开连接靠读超时兜底
// - 单机不依赖 Node / 不装运行时,一个二进制跑起来
package main
import (
"context"
"encoding/json"
"errors"
"flag"
"io"
"log"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"sync/atomic"
"time"
"agent-device/pkg/proto"
"agent-device/pkg/wsnode"
)
const version = "0.1.0"
var (
maxOutBytes = int64(4 << 20) // 单条命令回传上限,超出截断并标记
maxParallel = 4 // 同机并发执行数
)
type proc struct {
cmd *exec.Cmd
mu sync.Mutex
kln string // 终止原因:cancelled / timeout
}
func (p *proc) kill(reason string) {
p.mu.Lock()
if p.kln == "" {
p.kln = reason
}
p.mu.Unlock()
killProc(p.cmd)
}
func (p *proc) killed() string {
p.mu.Lock()
defer p.mu.Unlock()
return p.kln
}
// fileConfig 是 -config 读的 JSON,字段全部可选:没写的落到命令行/默认值。
// 之所以需要它:token 写在命令行会被 ps 看见。
type fileConfig struct {
Server string `json:"server"`
Token string `json:"token"`
Root string `json:"root"`
Name string `json:"name"`
Shell string `json:"shell"`
Insecure *bool `json:"insecure"`
}
var startedAt = time.Now()
type runner struct {
conn *wsnode.Conn
root string
shell string
sem chan struct{}
mu sync.Mutex
procs map[string]*proc
}
func main() {
server := flag.String("server", "", "core 的接入地址,如 wss://your-host.example/dev/ws")
token := flag.String("token", "", "Bearer token(或环境变量 NODE_TOKEN,或写在 -config 里)")
root := flag.String("root", "", "工作根目录(默认 ~/agent-work),命令的 cwd 必须落在它之内")
shellName := flag.String("shell", "", "sh | cmd | powershell(默认按平台)")
name := flag.String("name", "", "设备名(默认 hostname)")
configPath := flag.String("config", "", "JSON 配置文件:server/token/root/name/shell/insecure;命令行参数优先于它")
insecure := flag.Bool("insecure", false, "跳过证书校验")
fixClock := flag.Bool("fix-clock", false, "证书失败时用服务器时间校准本机(Linux 需 root)")
flag.Parse()
// 优先级:命令行显式参数 > 环境变量(仅 token)> 配置文件 > 默认值。
// 配置文件的意义是把 token 从命令行拿掉——ps aux 能看见所有参数。
set := map[string]bool{}
flag.Visit(func(f *flag.Flag) { set[f.Name] = true })
if *configPath != "" {
var fc fileConfig
b, err := os.ReadFile(*configPath)
if err != nil {
log.Fatalf("读配置失败:%v", err)
}
if err := json.Unmarshal(b, &fc); err != nil {
log.Fatalf("配置 %s 不是合法 JSON:%v", *configPath, err)
}
if !set["server"] && fc.Server != "" {
*server = fc.Server
}
if !set["token"] && fc.Token != "" {
*token = fc.Token
}
if !set["root"] && fc.Root != "" {
*root = fc.Root
}
if !set["name"] && fc.Name != "" {
*name = fc.Name
}
if !set["shell"] && fc.Shell != "" {
*shellName = fc.Shell
}
if !set["insecure"] && fc.Insecure != nil {
*insecure = *fc.Insecure
}
}
if *token == "" {
*token = os.Getenv("NODE_TOKEN")
}
if *server == "" {
log.Fatal("缺少 -server(或配置文件里的 server)")
}
if *token == "" {
log.Fatal("缺少 token:用 -token / NODE_TOKEN / 配置文件")
}
r := &runner{
root: *root,
shell: *shellName,
sem: make(chan struct{}, maxParallel),
procs: map[string]*proc{},
}
if r.root == "" {
home, _ := os.UserHomeDir()
r.root = filepath.Join(home, "agent-work")
}
r.root = filepath.Clean(r.root)
if err := os.MkdirAll(r.root, 0o755); err != nil {
log.Fatalf("工作根不可用:%v", err)
}
if r.shell == "" {
r.shell = defaultShell()
}
host, _ := os.Hostname()
if *name != "" {
host = *name
}
log.Printf("node-agent %s 启动:root=%s shell=%s → %s", version, r.root, r.shell, *server)
shPath, shVer := shellInfo(r.shell)
log.Printf("shell:%s(%s %s)", r.shell, shPath, shVer)
cfg := wsnode.Config{URL: *server, Token: *token, Insecure: *insecure, FixClock: *fixClock}
err := wsnode.Run(context.Background(), cfg,
func(c *wsnode.Conn) error {
r.conn = c
if err := c.Send(proto.Msg{
T: proto.TKindHello, Ver: version, Name: host,
OS: runtime.GOOS, Arch: runtime.GOARCH,
Shell: r.shell, ShellPath: shPath, ShellVer: shVer, Root: r.root,
}); err != nil {
return err
}
log.Printf("已连上 hub(%s/%s shell=%s %s)", runtime.GOOS, runtime.GOARCH, shPath, shVer)
return nil
},
func(c *wsnode.Conn, t string, raw []byte) {
var m proto.Msg
if json.Unmarshal(raw, &m) != nil {
return
}
switch t {
case proto.TKindExec:
go r.run(m)
case proto.TKindKill:
if p := r.lookup(m.ID); p != nil {
p.kill("cancelled")
}
case proto.TKindPing:
_ = c.Send(proto.Msg{T: proto.TKindPong})
case proto.TKindHealth:
h := hostHealth()
m := proto.Msg{
T: proto.TKindHealth, ID: m.ID,
UptimeSec: int64(time.Since(startedAt).Seconds()), HostUptimeSec: h.HostUptimeSec,
Load1: h.Load1, Load5: h.Load5, Load15: h.Load15,
MemTotalMB: h.MemTotalMB, MemFreeMB: h.MemFreeMB,
DiskTotalGB: h.DiskTotalGB, DiskFreeGB: h.DiskFreeGB, TempC: h.TempC,
OS: runtime.GOOS, Arch: runtime.GOARCH, Name: host,
}
_ = c.Send(m)
}
})
log.Printf("退出:%v", err)
}
func (r *runner) lookup(id string) *proc {
r.mu.Lock()
defer r.mu.Unlock()
return r.procs[id]
}
func (r *runner) send(m proto.Msg) { _ = r.conn.Send(m) }
func (r *runner) exit(id string, code int, killed, errMsg string, truncated bool, ms int64) {
m := proto.Msg{T: proto.TKindExit, ID: id, Code: &code, Killed: killed, Err: errMsg, MS: ms, Truncated: truncated}
r.send(m)
}
// run 执行一条命令:并发闸门 → cwd 校验 → 起进程组 → 流式回传 → 退出码。
func (r *runner) run(m proto.Msg) {
select {
case r.sem <- struct{}{}:
case <-time.After(30 * time.Second):
r.exit(m.ID, -1, "", "节点忙:排队超过 30 秒", false, 0)
return
}
defer func() { <-r.sem }()
dir, err := r.resolveCwd(m.Cwd)
if err != nil {
r.exit(m.ID, -1, "", err.Error(), false, 0)
return
}
tmo := time.Duration(m.TimeoutMS) * time.Millisecond
if tmo <= 0 {
tmo = 5 * time.Minute
}
ctx, cancel := context.WithTimeout(context.Background(), tmo)
defer cancel()
sh, shArgs := shellCmd(r.shell)
cmd := exec.CommandContext(ctx, sh, append(shArgs, m.Cmd)...)
cmd.Dir = dir
if len(m.Env) > 0 {
cmd.Env = append(os.Environ(), flatten(m.Env)...)
}
cmd.Cancel = func() error { killProc(cmd); return nil } // 超时/取消时整组杀,不只杀 sh
setupProc(cmd)
outPipe, err1 := cmd.StdoutPipe()
errPipe, err2 := cmd.StderrPipe()
if err1 != nil || err2 != nil {
r.exit(m.ID, 127, "", "取管道失败", false, 0)
return
}
p := &proc{cmd: cmd}
r.mu.Lock()
r.procs[m.ID] = p
r.mu.Unlock()
defer func() {
r.mu.Lock()
delete(r.procs, m.ID)
r.mu.Unlock()
}()
started := time.Now()
if err := cmd.Start(); err != nil {
r.exit(m.ID, 127, "", "启动失败:"+err.Error(), false, 0)
return
}
var sent atomic.Int64
var truncated atomic.Bool
var wg sync.WaitGroup
pump := func(rd io.Reader, stream string) {
defer wg.Done()
buf := make([]byte, 32<<10)
for {
n, rerr := rd.Read(buf)
if n > 0 {
if sent.Load() >= maxOutBytes {
truncated.Store(true)
} else {
chunk := make([]byte, n)
copy(chunk, buf[:n])
sent.Add(int64(n))
r.send(proto.Msg{T: proto.TKindChunk, ID: m.ID, Out: stream, Stream: chunk})
}
}
if rerr != nil {
return
}
}
}
wg.Add(2)
go pump(outPipe, "out")
go pump(errPipe, "err")
wg.Wait()
werr := cmd.Wait()
code := 0
if werr != nil {
var ee *exec.ExitError
if errors.As(werr, &ee) {
code = ee.ExitCode()
} else {
code = 127
}
}
killed := p.killed()
if killed == "" && ctx.Err() == context.DeadlineExceeded {
killed = "timeout"
}
if killed != "" && code == 0 {
code = -1
}
r.exit(m.ID, code, killed, "", truncated.Load(), time.Since(started).Milliseconds())
}
// resolveCwd:hub 已把服务器路径重写成节点路径,这里只保证落在 root 之内并自动建目录。
func (r *runner) resolveCwd(raw string) (string, error) {
if raw == "" {
return r.root, nil
}
if !filepath.IsAbs(raw) {
return "", errors.New("cwd 必须是绝对路径:" + raw)
}
cwd := filepath.Clean(raw)
rel, err := filepath.Rel(r.root, cwd)
if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
return "", errors.New("cwd 超出工作根:" + cwd)
}
if err := os.MkdirAll(cwd, 0o755); err != nil {
return "", errors.New("建目录失败:" + err.Error())
}
return cwd, nil
}
func flatten(env map[string]string) []string {
out := make([]string, 0, len(env))
for k, v := range env {
out = append(out, k+"="+v)
}
return out
}
func defaultShell() string {
if runtime.GOOS == "windows" {
return "cmd"
}
return "sh"
}
func shellCmd(name string) (string, []string) {
switch name {
case "cmd":
return "cmd", []string{"/c"}
case "powershell", "pwsh":
return name, []string{"-NoProfile", "-NonInteractive", "-Command"}
default:
if runtime.GOOS == "windows" {
return "cmd", []string{"/c"}
}
if _, err := os.Stat("/bin/sh"); err == nil {
return "/bin/sh", []string{"-c"}
}
return "sh", []string{"-c"}
}
}
// shellInfo 探测实际解释器与版本。这是模型写命令的唯一入口,所以路径要解开符号链接
// (/bin/sh 可能是 dash / bash / busybox),版本拿不到就留空(dash、busybox 不支持 --version)。
func shellInfo(name string) (string, string) {
bin, _ := shellCmd(name)
p, err := exec.LookPath(bin)
if err != nil {
return "", ""
}
if real, err := filepath.EvalSymlinks(p); err == nil {
p = real
}
ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
defer cancel()
var out []byte
switch name {
case "cmd":
out, _ = exec.CommandContext(ctx, "cmd", "/c", "ver").Output()
case "powershell", "pwsh":
out, _ = exec.CommandContext(ctx, bin, "-NoProfile", "-NonInteractive", "-Command",
"$PSVersionTable.PSVersion.ToString()").Output()
default:
out, _ = exec.CommandContext(ctx, p, "--version").Output()
}
ver := ""
if s := strings.TrimSpace(string(out)); s != "" {
if i := strings.IndexByte(s, '\n'); i > 0 {
s = s[:i]
}
s = strings.TrimSpace(s)
if len(s) > 60 {
s = s[:60] + "…"
}
ver = s
}
return p, ver
}
+21
View File
@@ -0,0 +1,21 @@
//go:build !windows
package main
import (
"os/exec"
"syscall"
)
// setupProc 让命令自成一个进程组,后面才能整组杀(sh 拉起的子进程一起收)。
func setupProc(cmd *exec.Cmd) {
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
}
// killProc 负号 = 整个进程组。忽略错误:进程可能已自行退出。
func killProc(cmd *exec.Cmd) {
if cmd == nil || cmd.Process == nil {
return
}
_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
}
+24
View File
@@ -0,0 +1,24 @@
//go:build windows
package main
import (
"os/exec"
"strconv"
"syscall"
)
const createNewProcessGroup = 0x00000200
// setupProc 让命令自成一组,taskkill /T 才能连子进程一起收。
func setupProc(cmd *exec.Cmd) {
cmd.SysProcAttr = &syscall.SysProcAttr{CreationFlags: createNewProcessGroup}
}
func killProc(cmd *exec.Cmd) {
if cmd == nil || cmd.Process == nil {
return
}
_ = exec.Command("taskkill", "/T", "/F", "/PID", strconv.Itoa(cmd.Process.Pid)).Run()
_ = cmd.Process.Kill()
}
+5
View File
@@ -0,0 +1,5 @@
module agent-device
go 1.22
require github.com/gorilla/websocket v1.5.3
+2
View File
@@ -0,0 +1,2 @@
github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+58
View File
@@ -0,0 +1,58 @@
// Package proto 定义 hub 与节点之间的消息。一条连接上全是 JSON 文本帧,
// 用 t 字段区分类型;二进制数据(命令输出)走 chunk 字段,encoding/json 自动 base64。
package proto
// 消息类型
const (
TKindHello = "hello" // 节点 → hub:上线自报家门
TKindExec = "exec" // hub → 节点:执行一条命令
TKindKill = "kill" // hub → 节点:终止某条命令
TKindChunk = "chunk" // 节点 → hub:输出片段
TKindExit = "exit" // 节点 → hub:命令结束
TKindPing = "ping" // hub → 节点:保活
TKindPong = "pong" // 节点 → hub:保活回应
TKindHealth = "health" // 双向:hub 要指标 / 节点回指标
)
// Msg 是双向通用信封:不同 t 只用其中一部分字段,其余 omitempty。
type Msg struct {
T string `json:"t"`
// hello
Ver string `json:"ver,omitempty"`
Name string `json:"name,omitempty"`
OS string `json:"os,omitempty"`
Arch string `json:"arch,omitempty"`
Shell string `json:"shell,omitempty"` // 逻辑名:sh / cmd / powershell
ShellPath string `json:"shell_path,omitempty"` // 实际解释器路径(符号链接已解开)
ShellVer string `json:"shell_ver,omitempty"` // 版本首行(拿不到就留空)
Root string `json:"root,omitempty"`
// exec / kill
ID string `json:"id,omitempty"`
Cmd string `json:"cmd,omitempty"`
Cwd string `json:"cwd,omitempty"`
TimeoutMS int `json:"timeout_ms,omitempty"`
Env map[string]string `json:"env,omitempty"`
// chunk / exit
Stream []byte `json:"chunk,omitempty"` // 原始字节,JSON 里是 base64
Out string `json:"out,omitempty"` // "out" | "err"
Code *int `json:"code,omitempty"`
Killed string `json:"killed_by,omitempty"` // cancelled | timeout
MS int64 `json:"ms,omitempty"`
Err string `json:"err,omitempty"`
Truncated bool `json:"truncated,omitempty"`
// health(hub 请求 / 节点回报共用)
UptimeSec int64 `json:"uptime_sec,omitempty"` // 本进程已运行秒数
HostUptimeSec int64 `json:"host_uptime_sec,omitempty"` // 主机开机秒数(不支持为 -1)
Load1 float64 `json:"load1,omitempty"`
Load5 float64 `json:"load5,omitempty"`
Load15 float64 `json:"load15,omitempty"`
MemTotalMB int64 `json:"mem_total_mb,omitempty"`
MemFreeMB int64 `json:"mem_free_mb,omitempty"`
DiskTotalGB float64 `json:"disk_total_gb,omitempty"`
DiskFreeGB float64 `json:"disk_free_gb,omitempty"`
TempC float64 `json:"temp_c,omitempty"`
}
+210
View File
@@ -0,0 +1,210 @@
// Package wsnode 是「节点主动出站 + 断线重连 + 心跳保活」的最小 WebSocket 基座。
// 语义与 files/print/agent 一致:节点在 NAT 后面也能被驱动,服务器不需要任何入站端口。
package wsnode
import (
"context"
"crypto/tls"
"crypto/x509"
"encoding/json"
"fmt"
"log"
"net"
"net/http"
"net/url"
"os"
"os/exec"
"runtime"
"time"
"github.com/gorilla/websocket"
)
// ReadTimeout 多久没收到服务器任何消息(含 ping)就认定连接已死。
// hub 每 20s ping 一次,正常情况下永远触发不到;半开连接会在这里超时并触发重连。
const ReadTimeout = 90 * time.Second
type Config struct {
URL string // wss://host/ws
Token string // Authorization: Bearer <token>
Insecure bool // 跳过证书校验(自签环境)
CAFile string // 额外信任的 CA
FixClock bool // 证书校验失败时用服务器 Date 头校时(盒子无 RTC 时有用)
}
type Conn struct {
ws *websocket.Conn
mu chan struct{} // 容量 1 的信号量:gorilla 不允许并发写
cfg Config
}
func (c *Conn) Send(v any) error {
b, err := json.Marshal(v)
if err != nil {
return err
}
c.mu <- struct{}{}
defer func() { <-c.mu }()
return c.ws.WriteMessage(websocket.TextMessage, b)
}
func (c *Conn) Close() { _ = c.ws.Close() }
// Wrap 把已升级的底层连接包成 Conn(hub 服务端用;客户端走 Run/Dial)。
func Wrap(ws *websocket.Conn) *Conn {
ws.SetReadLimit(4 << 20)
return &Conn{ws: ws, mu: make(chan struct{}, 1)}
}
// Run 持续维持连接:拨号 → onOpen → 读循环 → 断开 → 退避重连,直到 ctx 结束。
func Run(ctx context.Context, cfg Config, onOpen func(*Conn) error, onMsg func(*Conn, string, []byte)) error {
backoff := time.Second
for {
start := time.Now()
err := once(ctx, cfg, onOpen, onMsg)
if ctx.Err() != nil {
return ctx.Err()
}
// 稳定连过 60s 才把退避重置,避免「连上就断」时疯狂重试
if time.Since(start) > 60*time.Second {
backoff = time.Second
}
if err != nil {
log.Printf("连接中断:%v;%s 后重连", err, backoff)
}
select {
case <-time.After(backoff):
case <-ctx.Done():
return ctx.Err()
}
if backoff < 30*time.Second {
backoff *= 2
if backoff > 30*time.Second {
backoff = 30 * time.Second
}
}
}
}
func once(ctx context.Context, cfg Config, onOpen func(*Conn) error, onMsg func(*Conn, string, []byte)) error {
d := websocket.Dialer{
HandshakeTimeout: 15 * time.Second,
TLSClientConfig: tlsConf(cfg),
Proxy: http.ProxyFromEnvironment,
NetDial: (&net.Dialer{
Timeout: 15 * time.Second,
KeepAlive: 30 * time.Second,
}).Dial,
}
hdr := http.Header{}
if cfg.Token != "" {
hdr.Set("Authorization", "Bearer "+cfg.Token)
}
ws, resp, err := d.DialContext(ctx, cfg.URL, hdr)
if err != nil {
if resp != nil {
return fmt.Errorf("%s 拒绝连接:%s", cfg.URL, resp.Status)
}
if cfg.FixClock && !cfg.Insecure && isCertErr(err) {
log.Printf("证书校验失败,可能是系统时间不对(%v),尝试用服务器时间校准", err)
syncClock(cfg.URL)
}
return err
}
defer ws.Close()
ws.SetReadLimit(4 << 20)
c := &Conn{ws: ws, mu: make(chan struct{}, 1), cfg: cfg}
if err := onOpen(c); err != nil {
return err
}
for {
_ = ws.SetReadDeadline(time.Now().Add(ReadTimeout))
_, data, err := ws.ReadMessage()
if err != nil {
return err
}
var head struct {
T string `json:"t"`
}
if json.Unmarshal(data, &head) != nil {
continue
}
onMsg(c, head.T, data)
}
}
func isCertErr(err error) bool {
for _, k := range []string{"certificate", "x509", "tls:"} {
if contains(err.Error(), k) {
return true
}
}
return false
}
func contains(s, sub string) bool {
for i := 0; i+len(sub) <= len(s); i++ {
if s[i:i+len(sub)] == sub {
return true
}
}
return false
}
func tlsConf(cfg Config) *tls.Config {
t := &tls.Config{InsecureSkipVerify: cfg.Insecure}
if cfg.CAFile != "" {
if pem, err := os.ReadFile(cfg.CAFile); err == nil {
pool := x509.NewCertPool()
if pool.AppendCertsFromPEM(pem) {
t.RootCAs = pool
}
} else {
log.Printf("读 CA 失败:%v(忽略)", err)
}
}
return t
}
// syncClock 用服务器 Date 头把本机时间拨回来(只对 Linux 的 date 生效,Windows 一般有 RTC 不需要)。
// 证书本身可能是「因为时间错才失败」,所以这里刻意不校验证书。
func syncClock(rawURL string) {
u, err := url.Parse(rawURL)
if err != nil {
return
}
scheme := "http"
if u.Scheme == "wss" || u.Scheme == "https" {
scheme = "https"
}
req, err := http.NewRequest("HEAD", scheme+"://"+u.Host+"/", nil)
if err != nil {
return
}
client := &http.Client{
Timeout: 10 * time.Second,
Transport: &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}},
}
resp, err := client.Do(req)
if err != nil {
log.Printf("校时请求失败:%v", err)
return
}
defer resp.Body.Close()
t, err := http.ParseTime(resp.Header.Get("Date"))
if err != nil {
log.Printf("服务器 Date 头不可解析:%v", err)
return
}
log.Printf("本地时间偏差约 %s(服务器 %s)", time.Since(t).Truncate(time.Second), t.Format(time.RFC3339))
if runtime.GOOS == "windows" {
return
}
out, err := exec.Command("date", "-u", "-s", t.UTC().Format("2006-01-02 15:04:05")).CombinedOutput()
if err != nil {
log.Printf("设置系统时间失败(需要 root):%v %s", err, out)
return
}
log.Printf("已校时到 %s", t.UTC().Format(time.RFC3339))
}
+45
View File
@@ -0,0 +1,45 @@
#!/bin/sh
# 交叉编译设备端二进制到 ./bin(纯本地动作:不联网、不推送、不依赖任何特定服务器)。
#
# sh scripts/build.sh # 编当前平台
# sh scripts/build.sh all # 编 linux-arm64 / linux-amd64 / windows-amd64 / darwin-amd64 / darwin-arm64
#
# 有本机 Go 就用本机;没有但有 docker 就用 golang 镜像;都没有就报错。
set -e
cd "$(dirname "$0")/.."
TARGETS="$(uname -s | tr 'A-Z' 'a-z')/$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
[ "${1:-}" = "all" ] && TARGETS="linux/arm64 linux/amd64 windows/amd64 darwin/amd64 darwin/arm64"
build_with_go() {
mkdir -p bin
for t in $TARGETS; do
os=${t%/*}; arch=${t#*/}; ext=""
[ "$os" = windows ] && ext=.exe
echo "build $os/$arch"
GOOS=$os GOARCH=$arch CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" \
-o "bin/agent-$os-$arch$ext" ./cmd/agent
done
}
if command -v go >/dev/null 2>&1; then
build_with_go
elif command -v docker >/dev/null 2>&1; then
echo "本机没有 Go,改用 golang:1.23-alpine 容器编译"
docker run --rm -v "$PWD":/w -w /w \
-e CGO_ENABLED=0 -e TARGETS="$TARGETS" \
golang:1.23-alpine sh -c '
mkdir -p bin
for t in $TARGETS; do
os=${t%/*}; arch=${t#*/}; ext=""
[ "$os" = windows ] && ext=.exe
echo "build $os/$arch"
GOOS=$os GOARCH=$arch go build -trimpath -ldflags "-s -w" \
-o "bin/agent-$os-$arch$ext" ./cmd/agent
done'
else
echo "需要 Go 或 docker 才能编译" >&2
exit 1
fi
ls -lh bin