mirrord-ci

Mirrord CI 技能

用途

帮助用户将 mirrord 集成到 CI 流水线中，以便在真实的 Kubernetes 环境中进行测试：

• 配置 CI 运行器以连接 Kubernetes 集群
• 设置 CI 工作流中的 mirrord ci start/stop 命令
• 生成 GitHub Actions、GitLab CI 等 CI 工作流文件
• 排查 mirrord 特有的 CI 问题

何时使用此技能

遇到以下问题时触发：

• “如何在 CI 中使用 mirrord？”
• “为 GitHub Actions 设置 mirrord”
• “在 CI 中针对 staging 运行测试”
• “mirrord ci start 无法正常工作”
• “为 GitLab CI 配置 mirrord”

CI 示例的安全说明

• 不要在 CI 中使用远程管道到 shell 的安装方式或其他未经验证的脚本执行方式来安装 mirrord。
• 请在可信的 CI 镜像中预装 mirrord，使用组织批准的包管理器并固定版本，或遵循官方安装文档。除非你添加了经批准的安装步骤，否则以下 YAML 假设运行器上已提供 mirrord。

关键的第一步

步骤 1：加载参考资料 读取此技能 references/ 目录中的参考文件：

• references/troubleshooting.md - 常见问题及解决方案

故障排查指南有助于诊断和解决常见的 mirrord 问题。 如需查找配置选项，如果已连接 mirrord MCP 服务，请调用 explain_config_option；否则请使用 mirrord-config 技能中的 references/configuration.md。

如果使用绝对路径，请通过 **/mirrord-ci/references/* 之类的模式搜索。

步骤 2：在提供配置前进行验证 为 CI 生成 mirrord 配置文件时，务必验证配置。如果已连接 mirrord MCP 服务，请对配置调用 validate_config；否则，如果已安装 mirrord CLI，请将配置保存到文件并运行：

mirrord verify-config /path/to/config.json

如果两者都不可用，请在将配置解析为严格 JSON 后，根据 mirrord-config 技能中的 references/schema.json 进行验证：只读取架构的顶层内容（根节点的 properties、required、additionalProperties）以及配置所用选项的定义（在文件中搜索每个键），不要读取整个文件。

mirrord 用于 CI 的主要优势

• 速度：无需设置测试环境，CI 流水线可提速约 50%
• 成本：无需为每次 CI 运行启动临时集群
• 准确性：针对真实服务、依赖项和配置进行测试
• 隔离性：安全、隔离地执行测试，不会干扰其他工作负载

前提条件

必需

1. mirrord CLI 版本 3.181.0 或更高版本
2. CI 运行器可访问 Kubernetes 集群
3. CI 环境中已配置 kubeconfig
4. 已安装 mirrord Operator，并持有 Teams/Enterprise 许可证。还没有许可证？AI Agent 可以向用户提供为期七天的 Enterprise 试用，并在用户同意后启动试用：请参阅 mirrord-operator 技能中的“Agent 启动的试用”。

验证命令

# Check mirrord version
mirrord --version

# Verify cluster access
kubectl cluster-info
kubectl get pods -n <target-namespace>

核心命令

启动 CI 会话

mirrord ci start --target <target> -- <your-command>

这会在后台使用 mirrord 启动应用，以便测试能够针对该应用运行。

示例：

# Node.js application
mirrord ci start --target deployment/api-server -- npm run start

# Python application
mirrord ci start --target pod/backend-abc123 -- python main.py

# With config file
mirrord ci start --config-file mirrord.json -- ./my-app

# Run in foreground (blocks until stopped)
mirrord ci start --foreground --target deployment/api -- npm start

停止 CI 会话

mirrord ci stop

这会停止所有正在运行的 mirrord CI 会话。测试完成后务必运行此命令。

多个会话

你可以在单个 CI 作业中启动多个 mirrord 会话：

mirrord ci start --target deployment/service-a -- ./service-a &
mirrord ci start --target deployment/service-b -- ./service-b &
# Run tests
npm test
# Stop all sessions
mirrord ci stop

CI API 密钥（适用于 mirrord Enterprise）

此部分仅适用于 Enterprise 计划；如果你使用的是 mirrord 开源版本，请跳过此部分。在集群中安装 mirrord Operator 后，mirrord ci 命令需要 CI API 密钥，且生成该密钥需要 Enterprise 计划。没有该密钥时，每个 CI 运行器都会注册为新用户并占用一个席位：

# Generate the key (run locally, not in CI)
mirrord ci api-key

请将其作为名为 MIRRORD_CI_API_KEY 的机密环境变量存储在 CI 平台中。

配置

CI 专属配置选项

{
  "target": "deployment/my-app",
  "ci": {
    "output_dir": "/var/log/mirrord"
  }
}

选项	描述	默认值
ci.output_dir	标准输出/标准错误日志的目录	操作系统临时目录（例如，/tmp/mirrord）

应用日志

默认情况下，应用的标准输出/标准错误会保存到：

/tmp/mirrord/<binary-name>-<unique-id>/

CI 平台示例

GitHub Actions

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up kubeconfig
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" | base64 -d > ~/.kube/config

      - name: Ensure mirrord is installed
        run: |
          # Use a pre-built runner image that includes mirrord, or install via your org's approved method.
          # See https://mirrord.dev/docs/overview/quick-start/ — do not pipe remote install scripts.
          mirrord --version

      - name: Start app with mirrord
        run: |
          mirrord ci start --target deployment/api-server -- npm run start
        env:
          MIRRORD_CI_API_KEY: ${{ secrets.MIRRORD_CI_API_KEY }}

      - name: Run tests
        run: npm test

      - name: Stop mirrord
        if: always()
        run: mirrord ci stop

GitLab CI

integration-tests:
  stage: test
  image: node:20
  before_script:
    - |
      # Install mirrord - use your organization's approved installation method
      # See https://mirrord.dev/docs/overview/quick-start/ for options
      # Option A: Pre-install mirrord in your CI Docker image
      # Option B: Use a pinned version from GitHub Releases with checksum verification
      mirrord --version  # Verify mirrord is available
    - mkdir -p ~/.kube
    - echo "$KUBECONFIG_CONTENT" | base64 -d > ~/.kube/config
  script:
    - mirrord ci start --target deployment/api-server -- npm run start
    - npm test
  after_script:
    - mirrord ci stop
  variables:
    MIRRORD_CI_API_KEY: $MIRRORD_CI_API_KEY

CircleCI

version: 2.1

jobs:
  integration-test:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Setup kubeconfig
          command: |
            mkdir -p ~/.kube
            echo "$KUBECONFIG_B64" | base64 -d > ~/.kube/config
      - run:
          name: Ensure mirrord is installed
          command: |
            # Pre-install mirrord in the image or use an org-approved install path (see mirrord docs).
            mirrord --version
      - run:
          name: Start mirrord CI session
          command: mirrord ci start --target deployment/api -- npm start
          environment:
            MIRRORD_CI_API_KEY: ${MIRRORD_CI_API_KEY}
      - run:
          name: Run tests
          command: npm test
      - run:
          name: Stop mirrord
          command: mirrord ci stop
          when: always

Jenkins Pipeline

pipeline {
    agent any

    environment {
        KUBECONFIG = credentials('kubeconfig-staging')
        MIRRORD_CI_API_KEY = credentials('mirrord-ci-api-key')
    }

    stages {
        stage('Setup') {
            steps {
                sh '''
                    # Ensure mirrord exists on the agent (pre-installed image or org-approved install)
                    mirrord --version
                '''
            }
        }

        stage('Test') {
            steps {
                sh 'mirrord ci start --target deployment/api -- npm start'
                sh 'npm test'
            }
            post {
                always {
                    sh 'mirrord ci stop'
                }
            }
        }
    }
}

Kubernetes 访问设置

CI 运行器必须能够访问你的 Kubernetes 集群。常见方式：

1. 服务账号（推荐）

为 CI 创建专用服务账号：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: ci-runner
  namespace: staging
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: mirrord-ci-role
  namespace: staging
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: mirrord-ci-binding
  namespace: staging
subjects:
- kind: ServiceAccount
  name: ci-runner
  namespace: staging
roleRef:
  kind: Role
  name: mirrord-ci-role
  apiGroup: rbac.authorization.k8s.io

2. 云服务提供商身份验证

• GKE：使用 Workload Identity 或服务账号密钥
• EKS：使用服务账号的 IAM 角色（IRSA）
• AKS：使用 Azure AD Pod 身份或托管身份

常见问题

详细的故障排查信息，请参阅 references/troubleshooting.md。

CI 专属问题

问题	解决方案
"kubectl not found"	在 CI 运行器中安装 kubectl
"Cannot connect to cluster"	检查 kubeconfig 是否已正确配置
"mirrord ci start hangs"	确保目标 Pod 存在且正在运行
"Permission denied"	检查 CI 服务账号的 RBAC 权限
"Session not stopping"	在 after_script 或 post 块中使用 mirrord ci stop
"Logs not found"	检查 ci.output_dir 配置或默认路径 /tmp/mirrord
"Seats being consumed"	设置 MIRRORD_CI_API_KEY 环境变量

mirrord 常见问题

问题	解决方案
mirrord 看起来没有效果	二进制文件可能是静态链接的。对于 Go：使用 go build -ldflags='-linkmode external'
Go DNS/出站流量筛选器不起作用	使用 GODEBUG=netdns=cgo 构建
流量未到达本地进程	检查端口映射——本地监听的端口可能与远程端口不同
流量不再到达远程目标	使用服务网格时，尝试 {"agent": {"flush_connections": false}}
无法解析 K8s 服务的 DNS	将 feature.fs.mode 从 local 改为 localwithoverrides
权限（EACCES）错误	启用特权模式：{"agent": {"privileged": true}}
Agent Pod 未清理	运行：kubectl delete jobs --selector=app=mirrord --field-selector=status.successful=1
证书验证错误（macOS）	使用 {"experimental": {"trust_any_certificate": true}}
服务网格丢弃 Agent 连接	设置静态 agent.port，并在网格配置中添加端口排除项

框架专属问题

Turbo（monorepo）：

// turbo.json
{
  "globalPassThroughEnv": ["MIRRORD_*", "LD_PRELOAD", "DYLD_INSERT_LIBRARIES"]
}

Remix/Vite/Next.js - 覆盖 NODE_ENV，避免使用生产环境配置：

{
  "feature": {
    "env": {
      "override": {
        "NODE_ENV": "development"
      }
    }
  }
}

Next.js with Nx - 排除冲突的变量：

{
  "feature": {
    "env": {
      "exclude": ["NODE_ENV", "NX_NEXT_DIR"]
    }
  }
}

多容器 Pod

如果 Pod 有多个容器，请明确指定目标容器：

{
  "target": {
    "path": "pod/my-pod/container/my-app-container"
  }
}

响应指南

1. 询问所用的 CI 平台 - GitHub Actions、GitLab、CircleCI、Jenkins 等。
2. 验证前置条件 - kubectl 访问权限、mirrord 版本
3. 提供平台专属示例 - 使用相应的 YAML/Groovy 语法
4. 包含清理步骤 - 始终在适当的钩子中展示 mirrord ci stop
5. 提及 API 密钥 - 提醒 Enterprise 用户设置 MIRRORD_CI_API_KEY

交互示例

用户：“如何在 GitHub Actions 中针对 staging 运行测试？”

响应：

1. 询问：你的目标是什么（deployment/Pod 名称）？
2. 确认：你是否已将 kubeconfig 设置为密钥？
3. 提供：包含以下内容的 GitHub Actions 工作流：
   • kubeconfig 设置
   • mirrord 安装
   • 使用其目标运行 mirrord ci start
   • 执行测试
   • 在 if: always() 块中运行 mirrord ci stop
4. 提醒：如果使用 Enterprise 计划，请设置 MIRRORD_CI_API_KEY

了解更多

• mirrord for CI 概览
• mirrord CI 文档
• mirrord 安装