seristack

Seristack

一份 YAML 配置即可提供命令行命令、HTTP 端点和 MCP 工具。

Seristack 是一款轻量级自动化引擎，面向 DevOps、平台工程、SRE 和云团队。

使用 YAML 定义基于 shell 的工作流，管理依赖项和变量，在本地或通过 HTTP 执行工作流，并将选定的堆栈作为 MCP 工具提供给 AI Agent 和 IDE 集成使用。

GitHub 仓库

为什么选择 Seristack？

运维工作流通常以 shell 脚本、操作手册、CI 任务和未记录流程的形式存在。

Seristack 提供统一的配置层，可将这些工作流转化为可重复使用的执行堆栈，这些堆栈可以：

• 从命令行运行
• 作为 HTTP 端点提供
• 作为 MCP 工具提供
• 使用每个堆栈独立的授权进行保护
• 通过结构化 JSON 日志进行审计
• 使用依赖项和共享结果进行组合

文档

• 配置参考

功能

• 🚀 通过单个 YAML 配置运行多个命令堆栈
• 🔁 按顺序或并发执行堆栈
• 🔢 按可配置的次数重复执行堆栈
• 🔗 定义堆栈之间的依赖关系
• 🧩 支持带验证规则的变量替换
• 📦 在有依赖关系的堆栈之间共享输出和结果
• 🌐 将堆栈作为 HTTP 端点提供
• 🔐 使用身份标头进行每个堆栈独立的授权
• 📋 结构化 JSON 审计日志
• 🧠 作为 MCP 服务运行，为 AI Agent 和 IDE 集成提供支持
• 🛠 支持 mvdan shell、Bash、sh 和 PowerShell
• ⏱ 每个堆栈均可设置执行超时
• 📁 可配置工作目录
• 🛡 支持针对堆栈变量的允许和拒绝规则

---

安装

Homebrew — macOS 和 Linux

brew install TechXploreLabs/tap/seristack

Linux — 安装程序

curl -fsSL https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.sh | bash

Linux — 发布归档

1. 前往 Seristack 发布页面。
2. 下载最新版本：

seristack_VERSION_linux_ARCH.tar.gz

例如：

seristack_0.4.1_linux_amd64.tar.gz

3. 解压归档：

tar -xzf seristack_VERSION_linux_ARCH.tar.gz

4. 安装二进制文件：

sudo mv seristack /usr/local/bin/
sudo chmod +x /usr/local/bin/seristack

5. 验证：

seristack --help

Windows — 安装程序

以具有安装二进制文件权限的用户身份运行 PowerShell：

irm https://raw.githubusercontent.com/TechXploreLabs/seristack/main/install.ps1 | iex

Windows — 发布归档

1. 前往 Seristack 发布页面。
2. 下载 Windows 发布归档：

seristack_VERSION_windows_ARCH.tar.gz

例如：

seristack_0.4.1_windows_amd64.tar.gz

3. 使用支持 .tar.gz 的工具解压归档。

4. 将 seristack.exe 放入 %PATH% 中包含的目录。

5. 验证：

seristack --help

---

配置

Seristack 使用 YAML 定义执行堆栈。

有关所有配置字段的完整说明，请参阅配置参考。

示例

stacks:

  - name: stack1
    workDir: ./
    description: Print welcome message
    method: GET
    urlPath: /show
    continueOnError: false
    count: 3
    timeouts: 1h
    executionMode: PARALLEL

    vars:
      - name: samplekey
        value: samplevalue
        required: true
        allowed_value:
          - samplevalue
          - devvalue

    cmds:
      - |
        export samplekey={{.Vars.samplekey}}
        echo $samplekey
        echo "count={{.Count.index}}"
        echo "Hey I'm Seristack!"

  - name: stack2
    workDir: ./
    continueOnError: false
    count: 3
    executionMode: SEQUENTIAL

    vars:
      - name: env
        value: Dev

    dependsOn:
      - stack1

    cmds:
      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metadata\", \"status\": \"ok\"}"

      - |
        echo "{\"index\": {{.Count.index}}, \"step\": \"metrics\", \"value\": $((RANDOM % 100))}"

    output: |
      echo "--- Aggregation Summary ---"
      echo '{{.Self.result}}' | grep "^{" | jq -s '{
        total_records: length,
        environment: "{{.Vars.env}}",
        results: .
      }'

---

运行堆栈

触发所有堆栈

seristack trigger -c config.yaml

触发指定堆栈

seristack trigger -c config.yaml -s stack1

启动 HTTP 服务

seristack run -c config.yaml

启动 MCP 服务

seristack mcp -t streamableHTTP

---

HTTP 服务

HTTP 服务会将已配置的堆栈作为 HTTP 端点提供。

例如：

stacks:
  - name: system-health
    method: GET
    urlPath: /health
    cmds:
      - echo "system-health is good"

启动服务：

seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080

反向代理（如 nginx 或 Caddy）可以将服务暴露到外部，同时 Seristack 仍绑定到 localhost。

---

生产环境部署

Seristack 会执行 shell 命令，因此不应直接暴露到公共互联网。

推荐的架构如下：

Client
  │
  ▼
nginx / Caddy
  │
  ├── TLS termination
  ├── Authentication
  ├── Rate limiting
  │
  ▼
Seristack
127.0.0.1
  │
  ├── Authorization
  └── Command execution

在 localhost 上启动 Seristack：

seristack run \
  --config config.yaml \
  --addr 127.0.0.1 \
  --port 8080

对于远程 MCP 部署，也可以采用相同的模式：

AI Agent / IDE
      │
      ▼
    HTTPS
      │
      ▼
nginx / oauth2-proxy
      │
      ├── TLS
      ├── OIDC authentication
      └── Identity headers
      │
      ▼
Seristack MCP
127.0.0.1:8081
      │
      ├── Stack authorization
      └── Command execution

身份验证应由身份感知型代理或网关处理，而 Seristack 则在单个堆栈级别执行授权。

---

按堆栈授权

Seristack 可以使用经过身份验证的反向代理转发的身份标头，限制对各个堆栈的访问。

例如：

stacks:

  - name: deploy-production
    method: POST
    urlPath: /deploy/production

    matchAccess: ANY

    access:
      - headerName: X-Auth-Request-Groups
        headerValue:
          - sre
          - platform

      - headerName: X-Auth-Request-Roles
        headerValue:
          - admin

    count: 1

    cmds:
      - ./deploy.sh

访问匹配

matchAccess 用于控制如何评估多个访问规则。

ANY

matchAccess: ANY

至少匹配一条访问规则时，即授予访问权限。

这是 OR 逻辑。

ALL

matchAccess: ALL

只有匹配所有访问规则时，才授予访问权限。

这是 AND 逻辑。

无访问规则

如果堆栈未定义 access 块，则不会限制堆栈级别的访问。

在生产环境中，身份验证层仍应保护服务本身。

身份标头

实际使用的标头取决于身份验证提供商和反向代理。

身份提供商	常见代理	身份信息示例
Entra ID / Azure AD	oauth2-proxy	X-Auth-Request-Groups、X-Auth-Request-Roles、X-Auth-Request-Email
GCP	IAP	X-Goog-Authenticated-User-Email
AWS Cognito	ALB	X-Amzn-Oidc-Data
OCI IAM	nginx + oauth2-proxy	X-Auth-Request-Groups、X-Auth-Request-Email
Okta / Auth0	oauth2-proxy	由代理配置的身份标头

只有当这些标头来自经过身份验证的代理时，才应配置并信任它们。

不要允许不受信任的外部客户端直接提供授权标头。

---

审计日志

Seristack 可以为堆栈执行写入结构化 JSON 审计日志。

启用审计日志：

seristack run \
  --config config.yaml \
  --audit-log /var/log/seristack/audit.log

审计条目包含以下信息：

• 时间戳
• 事件
• 堆栈名称
• HTTP 路径和方法
• 可用时的源 IP
• 身份标头
• 变量
• 成功/失败
• 执行时长
• 输出
• 错误信息

示例：

{
  "timestamp": "2026-09-19T10:00:00Z",
  "event": "stack_executed",
  "stack": "system-health",
  "success": true,
  "duration_ms": 42,
  "output": "system-health is good"
}

使用 logrotate 或等效的日志系统管理日志轮转。

不要在堆栈变量中放入机密

变量可能会包含在审计记录中。

避免将密码、令牌、API 密钥或其他机密作为堆栈变量传递。

建议使用：

• 环境变量
• 机密管理器
• 工作负载身份
• 外部凭据提供商

---

MCP 服务

Seristack 可以将已配置的堆栈作为 MCP 工具公开。

启动 Streamable HTTP MCP 服务：

seristack mcp \
  -t streamableHTTP \
  --addr 127.0.0.1 \
  --port 8081

带有 description 的堆栈可以作为 MCP 工具公开。

AI Agent 和兼容 MCP 的 IDE 随后可以发现并调用可用的堆栈。

生产部署应将 MCP 服务置于 HTTPS 和身份验证层之后：

MCP Client
    │
    ▼
HTTPS
    │
    ▼
nginx / oauth2-proxy
    │
    ├── Authentication
    ├── TLS
    └── Identity headers
    │
    ▼
Seristack MCP
127.0.0.1:8081
    │
    ▼
Per-stack authorization
    │
    ▼
Shell execution

---

变量验证

变量可以定义验证和授权规则。

vars:

  - name: env
    value: staging
    required: true
    allowed_value:
      - staging
      - production

  - name: version
    required: true
    allowed_regex: regex("^[a-zA-Z0-9._-]+$")

  - name: command
    denied_regex: regex("(?i)rm|delete|drop")

只有在 vars 中声明的变量才能通过 HTTP 请求或 MCP 参数覆盖。

通过外部输入提供的未声明变量将被忽略。

验证规则可以包括：

• required
• allowed_value
• denied_value
• allowed_regex
• denied_regex

---

依赖项

堆栈可以依赖其他堆栈：

stacks:

  - name: build
    cmds:
      - ./build.sh

  - name: test
    dependsOn:
      - build
    cmds:
      - ./test.sh

  - name: deploy
    dependsOn:
      - test
    cmds:
      - ./deploy.sh

Seristack 会在执行前解析依赖顺序。

这样便可通过较小的可复用堆栈组合出更大型的工作流。

---

执行模式

可以将堆栈配置为顺序执行或并发执行。

顺序执行

executionMode: SEQUENTIAL

命令或重复执行会依次运行。

并行执行

executionMode: PARALLEL

相互独立的执行可以并发运行。

示例：

stacks:

  - name: health-check
    executionMode: PARALLEL
    count: 3

    cmds:
      - |
        echo "health check {{.Count.index}}"

---

命令执行

Seristack 支持使用已配置的 Shell 执行机制来运行 Shell 命令。

例如：

cmds:
  - echo "hello"

多行命令：

cmds:
  - |
    echo "Starting"
    ./script.sh
    echo "Finished"

可用的 Shell 语法取决于配置的执行环境。

---

测试

运行完整测试套件：

go test ./...

强制执行测试，不使用 Go 的测试缓存：

go test -count=1 ./...

查看详细输出和各项测试的执行时间：

go test -count=1 -v ./...

运行特定包的测试：

go test -count=1 -v ./pkg/opsy

运行竞态检测器：

CGO_ENABLED=1 go test -race ./...

在受支持的平台上，竞态检测器需要可用的 C 编译器／工具链。

---

seristack run 命令参考

seristack run [flags]

Flags:

  -c, --config string
        config file (default "config.yaml")

  -a, --addr string
        bind address (default "127.0.0.1")

  -p, --port string
        server port (default "8080")

      --audit-log string
        path to audit log file
        enables audit logging when set

      --identity-header strings
        map identity header to a key:
        "user=X-Auth-Request-Email"
        repeatable

运行：

seristack run --help

查看当前命令和标志参考。

---

安全注意事项

Seristack 会在其运行所在的主机上执行命令。

在生产环境中部署之前：

1. 将 Seristack 绑定到 localhost 或专用网络。
2. 在可从外部访问的端点前部署经过身份验证的反向代理或网关。
3. 远程访问时使用 HTTPS/TLS。
4. 不要信任客户端直接提供的身份标头。
5. 限制可以执行敏感堆栈的用户或组。
6. 避免将机密信息放入堆栈变量中。
7. 查看并轮换审计日志。
8. 以满足需求的最低操作系统权限运行 Seristack。
9. 尽可能限制文件系统和网络权限。
10. 通过 HTTP 或 MCP 暴露 shell 命令之前，请仔细检查这些命令。

MCP 访问应采用与 HTTP API 相同的安全注意事项，因为 MCP 客户端可以调用服务公开的工具。

---

支持项目

如果 Seristack 能帮助你的团队将 shell 脚本或运维手册转化为可复用的 CLI 命令、HTTP API 或 MCP 工具，不妨：

• ⭐ 为仓库点星
• 🐛 提交问题
• 💡 分享反馈
• 🧪 添加示例和测试
• 🔧 贡献改进

GitHub 仓库

---

许可证

Apache License 2.0