更夫 Gengfu

主题

关于本页

本页介绍更夫所基于的开源内核 Keep 的通用能力。更夫在其上提供国内化增强：钉钉/企业微信/飞书通知、国产大模型接入、LDAP 认证与值班管理。部署与上手请看快速上手。

Docker-compose 开发镜像 ​

您可以使用 docker-compose.dev.yaml 以开发模式启动 Keep。

首先，克隆 Keep 仓库：

git clone https://github.com/keephq/keep.git && cd keep

然后运行

docker compose -f docker-compose.dev.yml up

安装 Keep CLI ​

首先，克隆 Keep 仓库：

shell
git clone https://github.com/keephq/keep.git && cd keep

安装 Keep CLI

shell
poetry install

要访问 Keep CLI，请激活环境并从 shell 进入。

shell
poetry shell

从现在开始，Keep 应该已本地安装并可从命令行访问，通过执行以下命令测试：

keep version

启用自动补全 ​

Keep 的 CLI 支持 shell 自动补全，这可以让您的生活变得更轻松 😌

如果您使用的是 zsh

shell
eval "$(_KEEP_COMPLETE=zsh_source keep)"

如果您使用的是 bash

bash
eval "$(_KEEP_COMPLETE=bash_source keep)"

使用 eval 意味着每次启动 shell 时都会调用和评估该命令，这可能会延迟 shell 的响应速度。要加快速度，请将生成的脚本写入文件，然后 source 该文件。

测试 ​

运行单元测试：

bash
poetry run coverage run --branch -m pytest --ignore=tests/e2e_tests/

运行端到端测试（请先在本地运行 Keep）：

bash
poetry run playwright install;
poetry run coverage run --branch -m pytest -s tests/e2e_tests/

数据库迁移 ​

数据库迁移在服务器启动时自动执行。创建迁移：

bash
alembic -c keep/alembic.ini revision --autogenerate -m "Your message"

提示：请确保您的模型已导入到 ./api/models/db/migrations/env.py 中，以便自动生成器能够识别它们。

VS Code（或 Cursor） ​

通过将以下配置添加到您的 .vscode/launch.json，在克隆仓库后从 VS Code（或 Cursor）运行 Keep：

json
{
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Keep Backend",
        "type": "debugpy",
        "request": "launch",
        "program": "keep/cli/cli.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "args": ["--json", "api","--multi-tenant"],
        "env": {
            "PYDEVD_DISABLE_FILE_VALIDATION": "1",
            "PYTHONPATH": "${workspaceFolder}/",
            "PUSHER_APP_ID": "1",
            "SECRET_MANAGER_DIRECTORY": "./state/",
            "PUSHER_HOST": "localhost",
            "PUSHER_PORT": "6001",
            "PUSHER_APP_KEY": "keepappkey",
            "PUSHER_APP_SECRET": "keepappsecret",
            "LOG_FORMAT": "dev_terminal",
        }
      },
      {
        "name": "Keep Simulate Alerts",
        "type": "debugpy",
        "request": "launch",
        "program": "scripts/simulate_alerts.py",
        "console": "integratedTerminal",
        "justMyCode": false,
        "python": "venv/bin/python",
        "env": {
          "PYDEVD_DISABLE_FILE_VALIDATION": "1",
          "PYTHONPATH": "${workspaceFolder}/",
          "KEEP_API_URL": "http://localhost:8080",
          "KEEP_API_KEY": "some-api-key"
        }
      },
      {
        "name": "Keep Frontend",
        "type": "node-terminal",
        "request": "launch",
        "command": "npm run dev",
        "cwd": "${workspaceFolder}/keep-ui",
      }
    ]
}

安装依赖：

python3.11 -m venv venv;
source venv/bin/activate;
pip install poetry;
poetry install;
cd keep-ui && npm i && cd ..;

设置前端环境变量：

cp keep-ui/.env.local.example keep-ui/.env.local;
echo "\n\n\n\nNEXTAUTH_SECRET="$(openssl rand -hex 32) >> keep-ui/.env.local;

启动 Pusher（soketi）容器并行运行：

bash
docker run -d -p 6001:6001 -p 9601:9601 -e SOKETI_USER_AUTHENTICATION_TIMEOUT=3000 -e SOKETI_DEFAULT_APP_KEY=keepappkey -e SOKETI_DEFAULT_APP_SECRET=keepappsecret -e SOKETI_DEFAULT_APP_ID=1 quay.io/soketi/soketi:1.4-16-debian

VS Code（或 Cursor）+ Docker ​

INFO

要使本指南正常工作，需要安装 VS Code Docker 扩展。

TIP

在气隙环境（air-gapped environments）中，您可以考虑在一台连接互联网的计算机上构建容器，使用 docker save 导出镜像，然后在气隙环境中使用 docker load 加载镜像，最后使用运行配置。

在某些情况下，如果您无法直接在本地笔记本电脑上运行 Keep（例如使用 Windows），或者无法访问其所有依赖项（例如在气隙环境中），您仍然可以使用 VS Code（或 Cursor）和 Docker 来完成开发。

为此，请按照以下步骤操作：

  1. 克隆 Keep 并用 VS Code（或 Cursor）打开
  2. 创建一个 tasks.json 文件来构建和运行 Keep API 和 Keep UI 容器
  3. 创建一个 launch.json 配置来启动容器并附加调试器
  4. 完美。

克隆 Keep 并用 VS Code（或 Cursor）打开 ​

git clone https://github.com/keephq/keep.git && cd keep
code .

创建 tasks.json ​

包括构建容器 ​

{
    "version": "2.0.0",
    "tasks": [
        // API 和 UI 容器需要在同一个 docker 网络中
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        // 构建 API 容器
        {
            "label": "docker-build-api-dev",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.api",
                "tag": "keep-api-dev:latest"
            }
        },
        // 运行 API 容器
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-build-api-dev", "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        // 构建 UI 容器
        {
            "label": "docker-build-ui",
            "type": "docker-build",
            "dockerBuild": {
                "context": "${workspaceFolder}",
                "dockerfile": "${workspaceFolder}/Docker/Dockerfile.dev.ui",
                "tag": "keep-ui-dev:latest"
            }
        },
        // 运行 UI 容器
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-build-ui", "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // 取消注释以进行完整调试
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB",
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}

不构建容器 ​

TIP

要启动 Keep 而不构建容器，您需要将 keep-api-dev 和 keep-ui-dev 镜像加载到您的 docker 中。

{
    "version": "2.0.0",
    "tasks": [
        # API 和 UI 需要在同一个 docker 网络中
        {
            "label": "docker-create-network",
            "type": "shell",
            "command": "docker network create keep-network || true",
            "problemMatcher": []
        },
        # 运行 API 容器
        {
            "label": "docker-run-api-dev",
            "type": "docker-run",
            "dependsOn": [
                "docker-create-network"
            ],
            "python": {
                "args": [
                    "api"
                ],
                "file": "./keep/cli/cli.py"
            },
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-api-dev:latest",
                "containerName": "keep-api",
                "ports": [
                    {
                        "containerPort": 8080,
                        "hostPort": 8080
                    }
                ],
                "env": {
                    "DEBUG": "1",
                    "SECRET_MANAGER_TYPE": "FILE",
                    "USE_NGROK": "false",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}"
                    }
                ]
            }
        },
        # 运行 UI 容器
        {
            "type": "docker-run",
            "label": "docker-run-ui",
            "dependsOn": [
                "docker-create-network"
            ],
            "dockerRun": {
                "network": "keep-network",
                "image": "keep-ui-dev:latest",
                "containerName": "keep-ui",
                "env": {
                    // 取消注释以进行完整调试
                    // "DEBUG": "*",
                    "NODE_ENV": "development",
                    "API_URL": "http://keep-api:8080",
                    "AUTH_TYPE": "DB"
                },
                "volumes": [
                    {
                        "containerPath": "/app",
                        "localPath": "${workspaceFolder}/keep-ui"
                    }
                ],
                "ports": [
                    {
                        "containerPort": 9229,
                        "hostPort": 9229
                    },
                    {
                        "containerPort": 3000,
                        "hostPort": 3000
                    }
                ],
                "command": "npm run dev",
            },
            "node": {
                "package": "${workspaceFolder}/keep-ui/package.json",
                "enableDebugging": true
            }
        }
    ]
}

创建 launch.json ​

{
        "name": "Docker: Keep API",
        "type": "docker",
        "request": "launch",
        "preLaunchTask": "docker-run-api-dev",
        "removeContainerAfterDebug": true,
        "containerName": "keep-api",
        "python": {
          "pathMappings": [
            {
              "localRoot": "${workspaceFolder}",
              "remoteRoot": "/app"
            }
          ],
          "module": "keep.cli.cli"
        }
      },
      {
        "name": "Docker: Keep UI",
        "type": "docker",
        "request": "launch",
        "removeContainerAfterDebug": true,
        "preLaunchTask": "docker-run-ui",
        "containerName": "keep-api",
        "platform": "node",
        "node": {
          "package": "${workspaceFolder}/keep-ui/package.json",
          "localRoot": "${workspaceFolder}/keep-ui"
        }
      },

基于 MIT 协议开源的 Keep · 由更夫社区维护

© 2025-2026 更夫 Gengfu