Kranz

一个以键盘操作为先的本地服务编排器，配备专注的终端 UI。

Kranz（德语意为“花环”）将项目的本地服务、日志、健康检查和监听端口集中在一个地方。其带编号的面板导航遵循与 lazygit 相同的工作模型：左侧显示服务和详细信息，右侧显示当前聚焦服务的输出。

## 功能 - 集中化的启动、停止、重启和关闭 - 五种依赖条件：已启动 (started)、健康 (healthy)、已完成 (completed)、成功完成 (successful completion) 和日志就绪 (log-ready) - 带有退避策略和重启限制的自动恢复策略 - 支持自定义命令、信号、超时以及进程/父进程目标的有序关闭 - 基于 tag 的选择和分组启动 - 端口冲突检测，区分 Kranz/外部所有权，显示 PID 和进程详情 - HTTP、TCP 和命令健康检查 - 彩色日志、可选的捕获时间戳、正则表达式过滤/高亮、换行、暂停/跟随模式以及未读计数器 - 19 种注重对比度的主题，支持独立的主题、强调色和终端自适应背景源 - 面板、选择、操作栏、搜索和模态窗口的全面鼠标控制 - `Ctrl+O` 命令行 shell 交接，无需停止受管服务 - 针对常见 `process-compose.yaml` 项目的安全兼容模式 - 自动配置热重载，并具有“已知良好”回退机制 - 支持多个合并的配置文件以及 `.env` 和针对单个服务的 `env_file` - 应用内通知和操作状态 - 在按下 `q`、`Ctrl+C`、`SIGTERM`、`SIGHUP` 以及发生 TUI 错误时进行进程组清理 ## 安装 ### Homebrew ``` brew install kranz-org/tap/kranz ``` Homebrew 会下载适用于当前操作系统和架构的预构建存档，并校验其 checksum。对于每次稳定的 GitHub release，该 tap 都会自动更新。 ### GitHub release 从 [GitHub Releases](https://github.com/kranz-org/kranz/releases) 下载适合您操作系统和架构的存档，使用 `checksums.txt` 进行校验，然后将 `kranz` 放置到您的 `PATH` 中。 ### 从源码构建 ``` git clone https://github.com/kranz-org/kranz.git cd kranz make build ./bin/kranz ``` ### 使用 Go 安装 直接安装最新的公开 release 版本： ``` go install github.com/kranz-org/kranz/cmd/kranz@latest kranz --version ``` 对于本地检出代码，`make install` 会将当前源码版本安装到 `GOBIN` 或 `GOPATH/bin`： ``` make install kranz ``` ## 配置 在项目目录中创建 `kranz.yaml`： ``` project: MyProject version: "1.0" ui: theme: tokyo-night accent: "#7AA2F7" background: terminal color_mode: auto defaults: dir: . shell: /bin/bash env_files: [.env.shared] services: server: command: bun run --watch src/main.ts ports: [3801, 3802] tags: [backend, core] healthcheck: readiness: type: http url: http://localhost:3801/ready interval: 5s liveness: type: http url: http://localhost:3801/live interval: 10s web: command: npm run dev dir: apps/web ports: [3000] tags: [frontend] depends_on: [server] dependency_conditions: server: condition: process_healthy availability: restart: on_failure backoff: 2s max_restarts: 5 shutdown: signal: 15 timeout: 10s ``` 从该目录运行 Kranz，或者显式传入配置路径： ``` kranz kranz path/to/kranz.yaml kranz -f kranz.yaml -f kranz.local.yaml ``` 在没有显式指定路径的情况下，Kranz 会依次查找 `kranz.yaml`、`kranz.yml`、`process-compose.yaml` 和 `process-compose.yml`。 对于 Process Compose 项目，如果存在匹配的 `process-compose.override.yaml` 或 `process-compose.override.yml`，它们会被自动合并。显式指定的文件会从左到右进行合并。 Kranz 会读取第一个配置文件旁边的 `.env` 文件，用于变量展开和设置进程环境默认值。同时也支持 `defaults.env_files`、服务的 `env_files` 以及 Process Compose 的 `env_file`/`is_dotenv_disabled` 条目。直接定义的服务环境变量具有最高优先级。配置和环境文件会受到监控；有效的修改会自动进行调和，而无效的修改将保持已知的良好 runtime 不变。按下 `Ctrl+L` 可立即重新加载。 ### Process Compose 兼容性 Kranz 能够加载一个实用且经过刻意安全设计的 Process Compose 配置子集： - 进程命令、描述、工作目录、namespace（作为 tag）、环境变量、`env_file` 以及 `disabled`/`is_disabled` 状态 - `process_started`、`process_healthy`、`process_completed`、`process_completed_successfully` 和 `process_log_ready` 依赖项 - HTTP 和 exec readiness/liveness 探针，包括时序、header、状态码以及推断出的 HTTP 端口 - `ready_log_line`、额外的成功退出码、重启/退避/退出策略以及自定义关闭行为 - 项目级别的 name、version 和环境变量 - 支持多个 `-f` 文件、常规的 override 发现机制以及实时的 `Ctrl+L` 重载 不受支持的执行模型会被直接拒绝，而不会被静默错误解析：例如 replica 数量大于 1、schedule、以及 daemon/TTY/交互式/前台模式。远程/无头控制、扩缩容、定时任务、提权/交互式执行以及持久化文件日志基础设施均被刻意排除在此兼容层之外。被禁用的进程保持可见，并且可以手动启动。在通知中心会报告所配置的 Process Compose 文件日志被忽略。 ### 主题与用户设置 内置主题：`kranz`、`tokyo-night`、`dracula`、`nord`、`gruvbox-dark`、`catppuccin-mocha`、`rose-pine`、`solarized-dark`、`monokai`、`everforest`、`one-dark`、`github-dark`、`ocean`、`forest`、`amber`、`high-contrast`、`github-light`、`solarized-light` 和 `cream`。 每个内置主题都有浅色和深色变体。`ui.color_mode` 可选择 `auto`（默认）、`dark` 或 `light`。Auto 模式会在启动时检测终端背景，跟随 macOS 以及受支持的 Linux 系统外观变化，并在终端重新获得焦点时检查独立的终端配置文件变化。`Ctrl+L` 仅作为手动回退方案。 背景所有权与颜色模式相互独立。将 `ui.background` 设置为 `terminal`（默认）可保持画布不进行着色，以便终端配置文件提供其确切的背景。使用 `theme` 则会绘制所选主题当前的浅色或深色表面。例如，设置 `theme: cream`、`background: theme` 以及 `color_mode: auto`，会在浅色终端中绘制温暖的奶油色，而在深色终端中绘制该主题的深暖棕色变体。画布和面板表面始终共享一个基础色，而不是产生外部灰、内部白的割裂感。 按下 `Ctrl+T` 打开实时主题选择器。使用方向键导航可预览选定的主题。`p` 可在项目主题和选定主题之间切换，`a` 可在项目主题和默认强调色之间切换，`b` 可在终端/主题背景所有权之间切换，`m` 可循环切换 Auto/Dark/Light。这四个选择相互独立，并且摘要始终准确显示将要保存的内容。 按下 `Enter` 可将其作为个人用户覆盖设置全局保存。用户设置会以仅限当前用户的权限，以原子方式写入平台配置目录：macOS 上为 `~/Library/Application Support/kranz/settings.yaml`，Linux 上通常为 `~/.config/kranz/settings.yaml`。按下 `c` 则会将相同的外观保存到项目的原生 Kranz YAML 中，使其成为项目默认设置并清除匹配的全局覆盖。选择器会显示这两个目标路径。当存在多个 `-f` 层时，Kranz 会更新最后一个原生配置层，因为它具有最高优先级。Process Compose 文件永远不会被重写；当需要持久化项目主题时，请使用原生的 Kranz 配置层。按下 `Esc` 可关闭选择器而不进行保存。 ## 控制 在支持鼠标的终端中，可见的控件均可点击：面板标题、服务/tag 行和复选框、底部操作栏、搜索控件、模态操作以及完整的主题选择器。鼠标滚轮可滚动聚焦的内容和模态列表。键盘快捷键依然是最快捷的方式。 | 按键 | 操作 | |---|---| | `1`、`2`、`3` | 聚焦 Services/Tags、Details 或 Logs；当列表处于焦点时，`1` 切换 Services/Tags | | `Shift+3` | 在活动日志面板上方固定/取消固定当前聚焦的服务日志 | | `Tab` / `Shift+Tab` | 聚焦下一个/上一个面板，包括固定日志（如果存在） | | `↑` / `↓`、`j` / `k` | 在聚焦的面板内移动或滚动 | | `←` / `→` | 在第一个面板处于焦点时循环切换 Services/Tags | | `Space` | 将当前聚焦的服务或 tag 添加到选择中，或从中移除 | | `s` | 启动目标及其所需依赖，或者停止目标及其依赖项 | | `Shift+S` | 仅启动或停止选定/聚焦的目标，忽略依赖扩展 | | `r` | 重启选定的服务 | | `a` | 选择所有服务，或清除全部选择 | | `A` | 停止所有服务 | | `R` | 重启当前正在运行的服务 | | `t` | 在 Services 和 Tags 之间切换第一个面板 | | 在 Tags 中按 `Enter` | 展开/折叠当前聚焦 tag 下方的服务 | | `T` | 清除 tag 选择 | | `h` | 显示健康检查记录 | | `n` | 打开通知 | | `/` | 对聚焦的日志进行正则表达式过滤；在编辑器中按 `Tab` 切换到高亮模式 | | `n` / `N` | 在高亮模式下跳转到下一个/上一个匹配项 | | `w` | 切换长日志行的换行显示 | | `i` | 显示或隐藏每行日志被捕获的时间 | | `f` | 暂停或恢复日志跟随 | | `c` | 确认后清除聚焦或固定的服务日志 | | `q` | 退出（首先会停止所有受管进程） | | `Ctrl+C` | 立即停止所有受管进程并退出 | | `Ctrl+T` | 预览主题并将其保存到用户设置或项目配置中 | | 在 Themes 中的 `p` / `a` / `b` / `m` | 切换主题、强调色、背景所有权或 Auto/Dark/Light 模式 | | 在 Themes 中的 `Enter` / `c` | 全局保存/保存到项目配置 | | `Ctrl+L` | 重新加载配置并立即检测终端外观 | | `Ctrl+O` | 打开命令行 shell；再次按 `Ctrl+O` 返回 Kranz | | `?` | 打开帮助 | 当没有勾选任何服务或 tag 时，`s` 会针对当前聚焦的行进行操作。选定的 tag 会展开为所有匹配的服务，因此像 `frontend` 这样的 tag 可以作为一个目标进行启动或停止。在 Tags 面板中，按下 `Enter` 会内联展开匹配的服务；这些子行可以像常规服务一样被聚焦和选定，而在该 tag 上再次按下 `Enter` 则会将它们折叠。启动操作会包含所需的依赖项。停止操作会包含所有传递依赖项，并按照相反的依赖顺序进行处理，因此停止后端服务会首先停止依赖它的前端服务和 worker。不相关的服务将继续运行。正在等待依赖门控的服务会显示一个黄色圆点和明确的 `queued` 标签；Details 面板会列出它正在等待的依赖项。一旦所有目标都处于活动或排队状态，下一次按下 `s` 就会取消/停止它们——即使就绪状态仍在等待中也是如此。Enter 键永远不会控制服务的生命周期。 `Shift+S` 是一个显式的双向依赖覆盖操作。对于已停止的目标，它会精确启动选定的服务（如果未选定任何内容，则启动当前聚焦的服务），而不会启动或等待其依赖项。对于正在运行的目标，它会精确停止这些目标，而不会停止依赖于它们的其他服务。端口冲突和进程所有权安全检查依然保持启用状态。 若要进行完整的批处理，请按下 `a`，然后按下 `s`：已停止的服务会被启动，而完全处于活动状态的选择集则会被停止。再次按下 `a` 可清除选择。大写的 `A` 始终是立即停止所有服务的快捷键。 当配置的端口被占用时，Kranz 会区分监听器是由另一个受管服务拥有，还是由外部进程拥有。对于外部冲突，可以使用 `k` 停止该确切的 PID 并重试。在发送信号之前，Kranz 会再次扫描该端口，如果 PID 已更改或变为 Kranz 拥有，则会拒绝执行该操作。它会首先尝试发送 `SIGTERM`，只有在宽限期过后才会升级措施。 紧凑服务列表下方的 Details 面板会分别显示 readiness 和 liveness 状态，每个检查目标各占一行，此外还显示端口、tag、类型化的依赖项、恢复状态、重启次数和限制、上次启动时间、uptime、上次退出状态、关闭行为、环境变量文件、工作目录、命令和 PID。当操作系统公开了活动监听器的信息时，它们会包含检测到的协议和绑定地址例如 `tcp://127.0.0.1:3801`）。当其内容超过可用高度时，请聚焦面板 `2` 并使用方向键进行滚动。 每个日志标题都包含一个颜色编码的服务状态圆点和可读的状态。Kranz 会为进程启动、停止、退出和恢复尝试插入视觉上截然不同的 `[Kranz]` 生命周期边界。普通进程输出使用主题的中性文本颜色，而源前缀和调试输出会被柔和化。日志搜索会将输入的文本编译为正则表达式，并仅将其应用于聚焦服务的有限内存日志缓冲区。过滤模式是默认模式，它会隐藏不匹配的行，同时继续跟随新的匹配输出。在正则表达式编辑器中按 `Tab` 可选择高亮模式，该模式会保持所有行可见，并支持 `n`/`N` 导航。可选的时间戳属于捕获元数据，永远不会成为可搜索文本的一部分。子进程的终端控制序列在渲染前会被剥离，因此服务无法清除或重新定位 Kranz 界面。它不会搜索磁盘上的日志文件。 `readiness` 和 `liveness` 是相互独立的可选块。每个配置的块都必须声明其自身的 `type`（`http`、`tcp` 或 `command`）；空的 `healthcheck` 块会被拒绝。 ## 开发 要求：Go 1.24 或更高版本，macOS 或 Linux。 ``` make build # Build for the current platform make test # Run tests with the race detector and coverage make verify # Format-check, vet, test, and build make lint # Run golangci-lint make run # Build and run make install # Install into GOPATH/bin make snapshot # Build local Darwin/Linux release archives make clean # Remove build output ``` Kranz 采用语义化版本控制，使用带有注释的 `vMAJOR.MINOR.PATCH` 标签，并使用自动化的 GitHub release。有关常规的贡献流程，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)；有关一次性公开仓库设置和维护者发布检查清单，请参阅 [docs/RELEASING.md](docs/RELEASING.md)。 项目布局： ``` cmd/kranz/ CLI entry point and signal lifecycle internal/config/ Configuration loading and validation internal/service Process and service lifecycle ownership internal/health/ Readiness and liveness checks internal/port/ Port inspection on macOS and Linux internal/log/ Log parsing and search internal/ui/ Bubble Tea terminal UI pkg/ringbuffer/ Concurrent bounded log storage ``` ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：EVTX分析, MITM代理, SOC Prime, TUI, 开发工具, 日志审计, 本地服务编排, 终端UI