jpbeaudet/inspect
GitHub: jpbeaudet/inspect
一款安全优先的 SSH 集群运维调试 CLI，通过无 agent 架构实现跨主机日志搜索、安全变更（带审计和回滚）以及声明式多步迁移编排。
Stars: 0 | Forks: 0
# inspect
[](https://github.com/jpbeaudot/inspect/actions/workflows/ci.yml)
[](https://github.com/jpbeaudot/inspect/actions/workflows/release.yml)
[](LICENSE)
[](#stability)
`inspect` 是一款用于通过 SSH 连接的服务器集群的运维调试 CLI 工具。
只需一款工具，即可跨多台机器**搜索** (search) 日志和配置，**诊断** (diagnose) 运行状态，
通过内置的审计和回滚记录**安全应用** (safely apply) 热修复，并通过回滚机制**编排** (orchestrate) 声明式的多步迁移。
- **本地优先。** 无需 agent、daemon 或中央服务器。只需 SSH
（以及远程主机上的 `docker` / `systemctl`）。
- **默认试运行。** 每个修改命令都会预览 diff；
`--apply` 是执行更改的唯一方式。每次应用都会被审计，
并且可以通过 `inspect revert ` 进行回滚。
- **稳定的 JSON 信封。** 每个命令都可以输出一个版本化的
`summary | data | next` 信封（`--json`），适合通过管道传递给
`jq`、脚本或其他工具。
- **LogQL 风格搜索。** 一种类似 Loki 的熟悉查询语言，用于跨
日志、文件和主机状态进行 grep、解析和聚合。
- **Bundle 编排。** 声明式 YAML 迁移，包含 preflight / postflight 检查、
并行矩阵步骤、逐步和 bundle 级别的回滚，所有内容在审计日志中按 `bundle_id` 分组。
- **阻塞直到满足条件。** `inspect watch` 等待日志行、SQL
断言、HTTP 探测或任意命令 —— 匹配时退出代码为 0，
超时为 124。支持与 `&&` 组合并可嵌入 bundles 中。
- **内置手册。** `inspect help`、`inspect help ` 和
`inspect help search ` 均可离线工作 —— 无需 man pages，无需
网络。
## 目录
- [安装](#install)
- [快速入门](#quickstart)
- [工作原理](#how-it-works)
- [Bundles](#bundles)
- [Watch](#watch)
- [文档](#documentation)
- [从源码构建](#building-from-source)
- [稳定性](#stability)
- [贡献](#contributing)
- [安全](#security)
- [许可证](#license)
## 安装
### 单行命令安装（推荐）
```
curl -fsSL https://raw.githubusercontent.com/jpbeaudet/inspect/main/scripts/install.sh | sh
```
固定版本、更改安装根目录或跳过 cosign 验证：
```
curl -fsSL https://raw.githubusercontent.com/jpbeaudet/inspect/main/scripts/install.sh \
| sh -s -- --version v0.1.2 --prefix /usr/local
```
安装程序会：
1. 解析最新的 release 标签（或您指定的版本）。
2. 为您的主机三元组下载正确的 tarball。
3. 验证 SHA-256 校验和。
4. 如果 `$PATH` 中存在 `cosign`，则针对
GitHub OIDC 颁发者验证无密钥签名。
5. 以原子方式将二进制文件安装到 `$PREFIX/bin`（默认为
`~/.local/bin`）。
### Homebrew (自定义 tap)
```
brew tap jpbeaudet/tap
brew install inspect
```
有关 formula 的发布方式，请参阅 [packaging/homebrew/inspect.rb](packaging/homebrew/inspect.rb) 和
[docs/RELEASING.md](docs/RELEASING.md)。
### Cargo
```
cargo install inspect-cli
```
### 预编译二进制文件
从 [GitHub Releases](https://github.com/jpbeaudet/inspect/releases) 下载。
每个存档都附带用于 cosign 无密钥验证的 `.sha256`、`.sig` 和 `.pem` —— 参见 [docs/RUNBOOK.md](docs/RUNBOOK.md) §1.2。
一级平台：Linux (musl, x86_64 + aarch64)、macOS (Intel +
Apple Silicon)。
## 快速入门
```
# 1. 注册服务器（交互式 — 使用你的 ~/.ssh/config）
inspect add arte
# 2. 为后续工作打开一个持久 SSH 会话
inspect connect arte
# 3. 发现服务器上正在运行的内容
inspect setup arte
inspect ps arte
inspect status arte
# 4. 在集群中搜索，LogQL 风格
inspect search '{server="arte", source="logs"} |= "error"' --tail 100 --json
# 5. 预览 hot-fix，然后应用它
inspect edit arte/atlas:/etc/atlas.conf 's/timeout=30/timeout=60/'
inspect edit arte/atlas:/etc/atlas.conf 's/timeout=30/timeout=60/' --apply --reason "raise atlas timeout for batch run"
# 6. 如果出现问题则回滚
inspect audit ls --limit 5
inspect revert --apply
# 7. 等待远程条件（block-until-true）
inspect watch arte/atlas-api --until-log 'Started server' --timeout 60s
# 8. 运行声明式多步 migration
inspect bundle plan ops/migrations/phase-0-snapshot.yaml
inspect bundle apply ops/migrations/phase-0-snapshot.yaml --apply --reason "atlas centralization phase 0"
# 9. 内置手册 — 支持离线使用
inspect help
inspect help search
inspect help bundle
inspect help watch
```
更详细的引导教程位于 **[docs/MANUAL.md](docs/MANUAL.md)**。
## 工作原理
```
you ──► inspect (local) ──► ssh ControlMaster ──► remote host
│ │
│ ├── docker / podman
│ ├── systemctl
│ └── POSIX coreutils
▼
~/.inspect/
├── profiles/.yaml # discovered topology, mode 0600
├── audit// # snapshot + diff per mutation
└── audit/bundles// # bundle-grouped audit entries
```
- **每个主机一个 SSH 会话。** OpenSSH 的 `ControlMaster` 会在您的 shell 生命周期内保持
单一的身份验证通道处于打开状态。
只需输入一次密码。
- **配置文件已缓存。** `inspect setup ` 会将每个
容器、卷、网络和监听端口快照保存到
`~/.inspect/profiles/.yaml`。下次使用时会检测到配置漂移。
- **变更可回滚。** 在执行写入之前，原始状态会被
快照保存到 `~/.inspect/audit/` 下。`inspect revert `
会重放该快照。
- **Bundles 相互关联。** `inspect bundle apply` 中的每一步在审计日志中都共享一个 `bundle_id`；`inspect audit ls --bundle
` 可重建整个事务。
- **密钥已脱敏。** 输出在打印或记录之前会通过确定性的
脱敏器进行过滤。`--show-secrets` 可选择退出此功能。
## Bundles
`inspect bundle` 运行一个由 YAML 描述的包含 `exec` / `run` /
`watch` 步骤并带有回滚语义的序列。以下是在实际
迁移中行之有效的结构：
```
name: atlas-phase-0-snapshot
host: arte
reason: "Phase 0 pre-flight snapshot"
vars:
snapshot_dir: /srv/snapshots/2026-04-27
services: { clients: [atlas-api, nexus-api, onyx-api] }
preflight:
- check: disk_free
path: /srv/snapshots
min_gb: 50
- check: docker_running
services: [atlas-pg, aware-milvus]
steps:
- id: stop-clients
exec: docker compose -f /srv/atlas/docker-compose.yml stop {{ services.clients }}
on_failure: abort
- id: dump-pg-atlas
exec: docker exec atlas-pg pg_dumpall -U postgres | gzip > {{ snapshot_dir }}/atlas-pg.sql.gz
requires: [stop-clients]
on_failure: { rollback_to: stop-clients }
- id: tar-volumes
parallel: true
matrix:
volume: [atlas_milvus, atlas_etcd, aware_milvus]
exec: docker run --rm -v {{ matrix.volume }}:/src -v {{ snapshot_dir }}:/dst alpine tar czf /dst/{{ matrix.volume }}.tar.gz -C /src .
rollback:
- exec: docker compose -f /srv/atlas/docker-compose.yml start {{ services.clients }}
postflight:
- exec: sha256sum {{ snapshot_dir }}/* > {{ snapshot_dir }}/MANIFEST.sha256
- check: services_healthy
services: [atlas-api, nexus-api]
timeout: 60s
```
`inspect bundle plan ` 始终执行试运行（解析变量，
运行 preflight 检查，不进行远程写入）。必须使用 `inspect bundle apply
--apply` 才能执行破坏性步骤。一等公民检查包括：`disk_free`、`docker_running`、`services_healthy`、`http_ok`、
`sql_returns`，以及一个 `exec` 逃生舱口。
`inspect help bundle` 涵盖了完整的表面。
## Watch
`inspect watch` 是 bundles 所使用的同步原语。它同样可以
独立用于“服务恢复了吗？” / “队列清空了吗？”等检查：
```
# 等待日志行
inspect watch arte/atlas-api --until-log 'Started server on 0.0.0.0:8000' --timeout 60s
# 等待 SQL 谓词
inspect watch arte/atlas-pg \
--until-sql "SELECT count(*) = 0 FROM pg_stat_activity WHERE state = 'active'" \
--interval 2s --timeout 5m
# 等待 HTTP 响应
inspect watch arte/onyx-api --until-http https://localhost:8080/health --match 'status == 200' --timeout 90s
# 等待任意命令的输出
inspect watch arte/temporal --until-cmd 'pending_jobs' --equals 0 --timeout 10m
```
退出代码：`0` 匹配，`124` 超时（与 `timeout(1)` 一致），`130`
已取消，`2` 错误。每次 watch 都会写入一条审计记录，其中包含
断言、耗时以及匹配值（或在超时时的最后一次观察值）。
## 文档
| 文档 | 受众 | 内容 |
|---|---|---|
| [docs/MANUAL.md](docs/MANUAL.md) | 最终用户 | 实践用户手册：安装、注册主机、所有命令、搜索 DSL、配方、bundles、watch、故障排除。 |
| [docs/RUNBOOK.md](docs/RUNBOOK.md) | 维护者 / 值班人员 | 版本发布、事件响应、热修复流程、支持矩阵、当前限制。 |
| [docs/RELEASING.md](docs/RELEASING.md) | 维护者 | 如何打标签、发布流程执行内容、如何更新 Homebrew tap。 |
| [CHANGELOG.md](CHANGELOG.md) | 所有人 | 每次发布的变更（保持更新日志格式）。 |
| [INSPECT_ROADMAP_TO_v01.3.md](INSPECT_ROADMAP_TO_v01.3.md) | 所有人 | 达到 v0.2.0 稳定性契约的路线图（Kubernetes，锁定的 CLI 接口）。 |
| [INSPECT_v0.1.3_BACKLOG.md](INSPECT_v0.1.3_BACKLOG.md) | 所有人 | 下一个版本的活跃待办事项。 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献者 | 开发设置、lint/测试门禁、PR 规则。 |
| [SECURITY.md](SECURITY.md) | 报告者 | 如何报告漏洞。 |
| `inspect help ` | 最终用户 | 相同的手册内容，内嵌在二进制文件中，无需网络。 |
内置主题：`quickstart`、`selectors`、`aliases`、`search`、
`formats`、`write`、`safety`、`fleet`、`recipes`、`bundle`、`watch`、
`discovery`、`ssh`、`examples`。
## 从源码构建
要求：Rust 1.75+（固定在 [rust-toolchain.toml](rust-toolchain.toml) 中），
加上运行时的 OpenSSH 客户端。
```
cargo build --release
cargo test
```
同时提供了一个静态的 musl Docker 镜像：
```
docker build -t inspect:dev .
docker run --rm -it -v ~/.ssh:/home/inspect/.ssh:ro inspect:dev help
```
CI 门禁：`cargo fmt --all -- --check`、`cargo clippy --all-targets
-- -D warnings`、完整的测试套件（在 v0.1.2 版本中包含 27 个套件，555+ 个测试），
无模块范围的 lint 抑制。
## 稳定性
`inspect` 遵循 semver，但有一个明确的 1.0 版本前的警告：**契约
从 v0.2.0 开始**。在此之前，任何版本都可能出现破坏性更新。当前规划：
| 版本 | 包含内容 |
|---|---|
| v0.1.0 | 首次公开发布：12 个读取命令、12 个写入命令、LogQL 解析器、选择器、别名、发现、审计、快照、回滚、10 种输出格式、fleet、配方、原因、连通性、帮助。 |
| v0.1.1 | `run` 命令，`--follow`，`--merged`，`--match` / `--exclude`，`--since-last`，密钥掩码，`--reason`，进度，退出代码展示，幽灵服务修复。 |
| v0.1.2 | Bundle 编排 (B9)，`watch` 命令 (B10)，field-feedback 补丁 B1–B8，防御性强化阶段（审计 fsync、http 超时、panic 安全的矩阵）。 |
| v0.1.3 (开发中) | 密码认证 + 会话 TTL + `ssh add-key` 助手，可选操作系统密钥环，审计日志保留，header / PEM / URL 脱敏，参数化别名，每分支矩阵回滚，TUI 模式。 |
| v0.1.4 | 预稳定扫描：CLI 接口审计，配置 / JSON schema 冻结，帮助审计，README 重写，死代码 + 依赖审计，安全审计。**无新功能。** |
| v0.2.0 | 稳定性契约开始。Kubernetes 支持以附加方式加入（混合 Docker + k8s 集群）。 |
v0.2.0 之后：CLI 命令名、标志名、选择器语法、LogQL 语法、
`--json` schema（版本化）、配置格式、bundle YAML、配方 YAML、审计日志 schema、退出代码和帮助主题名称都是**稳定的**。内部 API、错误措辞、性能特征、
发现启发式方法和 TUI 按键绑定仍处于不稳定状态。
有关完整计划，请参见 [INSPECT_ROADMAP_TO_v01.3.md](INSPECT_ROADMAP_TO_v01.3.md)，
有关始终保持更新的已知限制列表，请参见 [docs/RUNBOOK.md](docs/RUNBOOK.md) §6。
## 贡献
欢迎提交 Bug 报告和 PR。请阅读
[CONTRIBUTING.md](CONTRIBUTING.md) 以了解开发循环、编码规则（
`-D warnings`、`dead_code = "deny"`、无模块范围的 lint
抑制），以及合并的测试契约。
## 安全
如果您发现漏洞，**请勿**公开提 issue。请参见
[SECURITY.md](SECURITY.md) 了解披露流程。
## 许可证
[Apache-2.0](LICENSE)。
## 开发历史
推动 v0.1.0 → v0.1.2 版本构建的实施计划、设计“圣经”、审计清单和
实地踩坑目录被存档在 [archives/](archives/) 中供参考。它们属于历史资料，
不属于受维护的公开部分；活跃的文档是 `docs/` 下的所有内容以及二进制内的 `inspect help`。
标签：Awesome, Docker, HTTP工具, Linux服务器, Loki, SSH, YAML, 分布式系统, 可视化界面, 命令行界面, 响应大小分析, 回滚机制, 基础架构管理, 声明式配置, 安全修复, 安全库, 安全防御评估, 审计日志, 提示注入, 故障诊断, 无代理, 无线安全, 日志搜索, 系统管理, 自动化运维, 请求拦截, 运维工具, 通知系统, 集群管理