hostpanel

hostpanel

hostpanel 负责管理单台主机：Docker 守护进程和容器状态、Compose 项目、主机基本信息、文件搜索、ZFS 池以及日志日志。它通过两个 action-router 工具 flux 和 scout 提供所有这些功能，命令行中也提供相同的两个路由器。一个二进制文件同时支持这两种使用方式。

这是更大的文档化功能范围中的一个标注核心子集。下文列出了已实现的操作；其他所有文档中列出的操作均不属于此子集，并会在构建报告和规范测试夹具中注明，而不会被悄悄移除。

仅提供本地主机服务。如果提供 host 参数，则必须为 local；此子集不包含远程 SSH 目标。启动进程时只使用参数数组，不会有任何命令字符串经由 shell 执行。

安装

npx @reneturcios/hostpanel help

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/hostpanel

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI；如果希望 flux 操作访问真实守护进程，请挂载 Docker 套接字。

CLI

hostpanel flux docker info
hostpanel flux docker version
hostpanel flux container list --params '{"state":"running"}'
hostpanel flux container inspect --params '{"container_id":"abc123"}'
hostpanel flux host info
hostpanel flux compose list

hostpanel scout nodes
hostpanel scout exec --params '{"command":"hostname"}'
hostpanel scout exec --params '{"command":"cat","args":["/etc/hostname"]}'
hostpanel scout find --params '{"path":"/srv","pattern":"*.log","limit":20}'
hostpanel scout zfs pools
hostpanel scout logs journal --params '{"unit":"docker","lines":50}'

hostpanel help
hostpanel --version

调用成功时会输出一个 JSON 对象，其中包含已执行的 argv 以及捕获的 stdout、stderr 和 exitCode；nodes 和 help 操作会直接输出本地响应。退出码：成功时为 0；调用失败时为 1（包括拒绝执行命令或子进程退出码非零）；用法错误时为 2。

MCP 服务

npx -y @reneturcios/hostpanel mcp

MCP 客户端配置：

{
  "mcpServers": {
    "hostpanel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/hostpanel", "mcp"]
    }
  }
}

工具

两个工具都需要 action，并可选提供 subaction 和 params 对象。params 中的参数名称遵循各操作原有的参数表（host、container_id、state、name_filter、image_filter、label_filter、path、pattern、depth、limit、command、args、pool、lines、unit、priority、since、until、grep）。

工具	操作	子操作	功能
flux	docker	info	Docker 守护进程信息（docker info）。
flux	docker	version	Docker 版本（docker version）。
flux	container	list	列出容器（docker ps），可选按状态、名称、镜像和标签筛选。
flux	container	inspect	检查单个容器（docker inspect）；需要提供 container_id。
flux	host	info	操作系统、内核和架构信息（uname -a）。
flux	compose	list	列出 Compose 项目（docker compose ls）。
flux	help	—	在本地返回 flux 操作参考。
scout	nodes	—	已配置的主机：此子集中仅有 local。
scout	exec	—	运行一个允许的只读命令；需要提供 command，可选提供 args。
scout	find	—	按 glob 查找文件（find <path> -name <pattern>）；需要提供 path 和 pattern。
scout	zfs	pools	列出 ZFS 池（zpool list），可选按 pool 筛选。
scout	logs	journal	读取 systemd 日志（journalctl），可选提供 lines、unit、priority、since、until 和 grep。
scout	help	—	在本地返回 scout 操作参考。

exec 允许列表

scout exec 只运行只读检查命令。完整允许列表共包含 18 个命令：cat、head、tail、grep、rg、ls、tree、wc、uniq、diff、stat、file、du、df、pwd、hostname、uptime 和 whoami。其他任何命令——包括 git、shell、解释器和具有修改功能的工具——都会在启动任何进程前被拒绝。命令必须是单个名称；参数分别放在 args 数组中传递，并作为 argv 传入，绝不会插入 shell 命令字符串中。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake executor only
npm run dev     # run the CLI from source via tsx

测试会注入一个伪执行器，因此测试套件会记录每个操作将运行的 argv，并验证被拒绝的命令绝不会到达执行器。测试不需要 Docker 守护进程、ZFS 池或日志，也不会声称测试套件提供了任何实时主机结果。

许可证

MIT — 参见 LICENSE。