kurtosis-tech/kurtosis
GitHub: kurtosis-tech/kurtosis
Kurtosis 是一个用于简化区块链临时开发和测试环境部署的平台。
Stars: 541 | Forks: 97
# 什么是Kurtosis？
您是否曾尝试基于同事的工作进行构建，或为开源项目做贡献，结果却在启动环境进行体验的第一步就卡住了？[Kurtosis](https://www.kurtosis.com) 处理了启动临时开发或测试环境的复杂性，让您可以专注于开发，而不是配置。
Kurtosis 由以下部分构成：
- 一个用于分发后端环境定义的打包系统，可以在 Docker 或 Kubernetes 上运行
- 一个带有逐环境文件管理系统的运行时，用于可重复地初始化您的环境状态
- 一套工具集，使开发者能够与其环境进行交互，就像在 Docker 或 k8s 上一样
# 为什么使用Kurtosis？
Kurtosis 最适合于：
# Kurtosis 与 Docker Compose 或 Helm 有何不同？
Kurtosis 运行在比 Docker Compose 或 Helm 更高的一层，它生成运行在底层引擎（Docker 引擎或 Kubernetes）之上的环境。
由于这层额外的抽象，我们能够引入一些特性来改善启动临时环境的体验：
- 一个逐环境文件管理系统，支持为开发或测试环境进行可移植的状态初始化
- 环境级参数化；用户拥有一种强大而灵活的方式（超越仅仅修改环境变量）来影响其环境的修改
- 一流的即插即用可组合性；期望用户将环境定义导入更大的环境中，并且此体验得到了优化
- 能够获得上述所有功能，但可运行在 _Docker 引擎或 K8s_ 上，由您选择
`注意：我们目前不推荐使用 Kurtosis 来部署长期的生产环境。任何与生产环境使用相关的问题/Discord帖子都将被关闭。`
# 如何开始？
要查看 Kurtosis 的实际效果，请首先按照[此处](https://docs.kurtosis.com/install)的说明进行安装。
然后，运行 [Redis 投票应用 Kurtosis 包](https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/redis-voting-app)：
```
kurtosis run github.com/kurtosis-tech/awesome-kurtosis/redis-voting-app
```
最后，在浏览器中打开最后一行打印的 `http` 链接。
如果您有任何问题或功能请求，我们非常乐意通过以下方式了解：
- 在我们的 [Github 讨论论坛](https://github.com/kurtosis-tech/kurtosis/discussions/new?category=q-a) 上发布您的问题
- [在我们的 Discord 服务器上寻求帮助][discord]
- 在我们的 [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) 上提交 issue（也可以通过 `kurtosis feedback --bug` 或 `kurtosis feedback --feature` 来完成）
- [在 Twitter 上给我们发消息][twitter]
### 进一步探索
要尝试更多类似这样的 Kurtosis 包，请查看 [`awesome-kurtosis` 仓库][awesome-kurtosis]！
要了解如何编写 Kurtosis 包，请查看我们的[快速入门指南][quickstart-reference]。
要了解 Kurtosis 的工作原理，请参阅[我们的文档][docs]。
要查看我们产品的发展路线图，请查看[这里](https://github.com/kurtosis-tech/kurtosis/wiki/Short%E2%80%90term-Roadmap)。
# Claude 代码技能
此仓库包含 [Claude Code](https://claude.ai/download) 技能，用于教导 Claude 如何与 Kurtosis 协作。技能是位于 `skills/` 目录中的结构化提示，向 Claude 提供关于构建、调试、部署和管理 Kurtosis 飞地的操作知识。
### 可用技能
| 技能 | 描述 |
|-------|------|
| `clean` | 清理飞地和工件 |
| `cli-local-build` | 从源代码构建 CLI |
| `cluster-manage` | 管理 Kurtosis 集群 |
| `context-manage` | 管理 Kurtosis 上下文 |
| `docker-debug` | 调试基于 Docker 的飞地 |
| `docker-local-build` | 本地构建和加载 Docker 镜像 |
| `dump` | 转储飞地状态以进行调试 |
| `enclave-inspect` | 检查正在运行的飞地 |
| `engine-manage` | 启动、停止和重启引擎 |
| `files-inspect` | 检查文件工件 |
| `gateway` | 管理 Kurtosis 网关 |
| `grafloki` | 查询 Grafana 和 Loki 可观测性 |
| `import-compose` | 导入 Docker Compose 文件 |
| `k8s-clean-cluster` | 从 K8s 清理 Kurtosis 资源 |
| `k8s-debug-pods` | 在 Kubernetes 上调试 Pod |
| `k8s-dev-deploy` | 构建并将开发镜像部署到 K8s |
| `lint` | 代码库检查 |
| `port-forward` | 从飞地转发端口 |
| `portal` | 管理 Kurtosis 门户 |
| `run-package` | 运行 Starlark 包 |
| `service-manage` | 管理飞地内的服务 |
| `starlark-dev` | 开发 Starlark 包 |
### 安装技能
当技能存在于项目的 `skills/` 目录中时，Claude Code 会自动发现它们。有几种安装方法：
#### 选项 2：将技能复制到您的项目中
将 `skills/` 目录复制到您希望 Claude 具备 Kurtosis 知识的任何项目中：
```
# 从 kurtosis 仓库中复制技能到你的项目
cp -r /path/to/kurtosis/skills /path/to/your-project/skills
```
#### 选项 3：从另一个项目创建符号链接
如果您希望将技能与 Kurtosis 仓库保持同步而不复制：
```
# 符号链接整个技能目录
ln -s /path/to/kurtosis/skills /path/to/your-project/skills
# 或符号链接单个技能
mkdir -p /path/to/your-project/skills
ln -s /path/to/kurtosis/skills/run-package /path/to/your-project/skills/run-package
```
#### 选项 4：为所有项目全局安装
要使 Kurtosis 技能对您的所有 Claude Code 项目可用，请将它们添加到您的全局 Claude 配置中：
```
# 复制技能到你的全局 Claude 配置
cp -r /path/to/kurtosis/skills ~/.claude/skills
```
### 使用技能
安装后，技能在 Claude Code 中作为斜杠命令调用：
```
/clean # Clean up enclaves
/run-package # Run a Starlark package
/docker-debug # Debug Docker containers
/k8s-debug-pods # Debug Kubernetes pods
```
您也可以在对话中自然地引用技能——当讨论 Kurtosis 主题时，Claude 会自动使用相关的技能上下文。
## 仓库结构
此仓库采用 monorepo 结构，包含以下项目：
- `container-engine-lib`：用于抽象 [飞地][enclave] 所使用的容器引擎的库。
- `core`：在 [飞地][enclave] 内启动的容器，用于协调其状态
- `engine`：启动用于协调[飞地][enclave]的容器
- `api`：定义 Kurtosis 平台（`engine` 和 `core`）的 API
- `cli`：生成 CLI 二进制文件，允许与 Kurtosis 系统进行交互
- `docs`：发布到 [docs.kurtosis.com](docs) 的文档
- `internal_testsuites`：端到端测试
## 开发依赖 (Nix)
安装 [Nix 包管理器](https://nixos.org/download)。
```
sh <(curl -L https://nixos.org/nix/install)
```
并启用一些 Nix 标志（或者您可以在每次调用 `nix` 命令时添加 `--extra-experimental-features 'nix-command flakes'`）：
```
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```
要启动环境，只需打开一个新的 shell 终端，转到仓库的根目录并运行：
```
nix develop
```
这将下载所有开发依赖并相应地设置环境。
您也可以使用 [`direnv`](https://direnv.net/) 在进入主文件夹或使用您首选 IDE 的插件时自动加载环境：
- `vscode`: [mkhl.direnv](https://github.com/direnv/direnv-vscode)
- `jet brains`: [Direnv integration](https://plugins.jetbrains.com/plugin/15285-direnv-integration)
Direnv 也可以通过 Nix 轻松安装（或者如果您愿意，也可以使用 [HomeBrew](https://formulae.brew.sh/formula/direnv)）：
```
nix-env -f '
4. 然后在“运行面板”中选择“CLI-remote-debug”运行配置
5. 按下“调试”按钮
6. 使用调试面板检查变量值并继续调试流程
用于通过 Delve 调试客户端运行 CLI：
1. 构建 CLI 开发二进制文件并运行您想要调试的命令（在此示例中为 kurtosis 版本），但首先将“dlv-terminal”作为第一个参数传递（这将在终端中启动 Delve 客户端）
```
cli/cli/scripts/build.sh
source ./scripts/set_kt_alias.sh
ktdebug dlv-terminal version
```
2. 您可以使用终端客户端和 `break` 命令添加新断点
```
(dlv) break version.run:1
```
3. 您可以使用 `continue` 命令将光标移动到上一步创建的断点
```
(dlv) continue
```
4. You can see [more Delve commands here][delve-docs]
用于通过 Golang 远程调试运行 Kurtosis engine：
1. 将主构建脚本的第一个参数 `debug_mode` 设置为 true。这将生成一个新的 Kurtosis engine 容器镜像，该镜像的名称中将包含 `debug` 后缀。
```
scripts/build.sh true
```
2. 在您希望光标停止的行添加断点
3. 使用 `ktdev engine start --debug-mode` 或 `ktdev engine restart --debug-mode` 命令在调试模式下运行 engine
```
source ./scripts/set_kt_alias.sh
ktdev engine start --debug-mode
```
4. 然后在“运行面板”中选择“Engine-remote-debug”运行配置
5. 按下“调试”按钮
6. 调用 engine 的服务器（您可以使用 Kurtosis CLI 或 Postman）以命中断点
7. 使用调试面板检查变量值并继续调试流程
8. 您可以通过使用 `ktdebug` 而不是前面提到的 `ktdev` 来运行，同时调试 CLI 和 Kurtosis engine 的服务器，请记住在 Goland IDE 中运行两个远程调试配置。
```
source ./scripts/set_kt_alias.sh
ktdebug engine start
```
如果您在 K8s 中调试 Kurtosis engine 的附加步骤：
1. 将用于调试的 engine 镜像上传到 K8s 集群
```
# 例如：
k3d image load kurtosistech/engine:5ec6eb-dirty-debug
```
2. 在 Goland 中按下调试按钮之前（在另一个终端实例中）运行端口转发脚本，将主机端口绑定到容器的调试服务器端口
```
scripts/port-forward-engine-debug.sh
```
3. 在调用 engine 的服务器后（也在另一个终端实例中）不要忘记运行 Kurtosis 网关
```
ktdev gateway
```
用于通过 Golang 远程调试运行 Kurtosis APIC：
1. 将主构建脚本的第一个参数 `debug_mode` 设置为 true。这将生成一个新的 Kurtosis APIC 容器镜像，该镜像的名称中将包含 `debug` 后缀。
```
scripts/build.sh true
```
2. 在您希望光标停止的行添加断点。
3. 根据您是否还想调试 engine，选择以调试模式运行 Kurtosis engine 或不运行。
```
source ./scripts/set_kt_alias.sh
ktdev engine start --debug-mode
OR
ktdev engine start # you will have to build the engine in the regular way `engine/scripts/build.sh` if you choose this version
```
4. 使用 `enclave add` 命令添加一个新的调试模式飞地，并传递 `debug-mode` 标志。这将创建一个新的 APIC 容器，其调试服务器端口已绑定并等待连接。
重要提示：目前您只能运行一个调试模式的飞地，如果您尝试运行另一个，将会失败，因为调试端口已被占用。
```
ktdev enclave add --debug-mode
```
5. 然后在“运行面板”中选择“APIC-remote-debug”运行配置
6. 按下“调试”按钮
7. 在主机上找到 APIC 的 GRPC 服务器端口（您可以在 Docker Desktop 中或使用 Docker CLI 查看，它是与容器的 7443 端口绑定的那个）
8. 调用 APIC 的服务器（您可以使用 Kurtosis CLI 或 Postman）以命中断点
9. 使用调试面板检查变量值并继续调试流程
10. 您可以通过使用 `ktdebug` 而不是前面提到的 `ktdev` 来运行，同时调试 CLI、Kurtosis engine 的服务器和 Kurtosis APIC 的服务器，请记住在 Goland IDE 中运行三个远程调试配置。
```
source ./scripts/set_kt_alias.sh
ktdev engine start --debug-mode
ktdebug enclave add
```
如果您在 K8s 中调试 Kurtosis APIC 的附加步骤：
1. 将用于调试的 APIC 镜像上传到 K8s 集群
```
# 例如：
k3d image load kurtosistech/core:5ec6eb-dirty-debug
```
2. 在 Goland 中按下调试按钮之前（在另一个终端实例中）运行端口转发脚本，将主机端口绑定到容器的调试服务器端口
```
scripts/port-forward-apic-debug.sh enclave-name
```
3. 在调用 APIC 的服务器后（也在另一个终端实例中）不要忘记运行 Kurtosis 网关
```
ktdev gateway
```
标签：Docker, EVTX分析, MITM代理, NIDS, SOC Prime, 临时环境, 区块链, 区块链开发, 参数化配置, 可组合性, 可视化界面, 启动工具, 基础设施, 堆栈管理, 子域名突变, 安全防御评估, 容器化, 容器编排, 工具集, 开发工具, 开发平台, 打包工具, 文件管理, 日志审计, 测试平台, 网络连接监控, 请求拦截, 运行时