零基础通关：keep完全离线部署指南 — 本地化环境安装与配置全流程

你是否在无网络环境下部署开源工具时屡屡碰壁？本文将带你一步步完成keep平台的本地化部署，无需依赖外部网络，从镜像构建到服务验证全程实操，让你在隔离环境中也能轻松搭建企业级告警管理系统。读完本文你将掌握：离线环境准备清单、Docker镜像本地化构建、配置文件深度优化、服务启动与状态验证、常见问题排查方案。

环境准备与文件清单

在开始部署前，需确保目标服务器满足以下条件：已安装Docker 20.10+和Docker Compose v2+，至少2GB内存和10GB磁盘空间。从项目仓库获取完整源码后，重点关注以下部署相关文件：

• 核心配置文件：docker-compose.yml、docker-compose.common.yml
• 构建脚本：start.sh（位于项目根目录）
• Dockerfile：docker/Dockerfile.api（后端API）、docker/Dockerfile.ui（前端界面）
• 持久化存储：需提前创建./state目录用于数据持久化

本地化镜像构建流程

1. 后端API镜像构建

使用项目内置的Dockerfile在本地构建后端服务镜像，避免从外部仓库拉取：

docker build -f docker/Dockerfile.api -t keep-api:local .

该过程会基于Python环境构建FastAPI服务，包含所有依赖安装与配置打包。构建完成后可通过docker images | grep keep-api验证镜像是否存在。

2. 前端UI镜像构建

同样使用本地文件构建Next.js前端镜像：

docker build -f docker/Dockerfile.ui -t keep-ui:local .

构建完成后，需修改docker-compose.yml中的镜像引用，将原远程镜像地址替换为本地镜像：

services:
  keep-frontend:
    image: keep-ui:local  # 替换为本地构建镜像
    # 其他配置保持不变
    
  keep-backend:
    image: keep-api:local  # 替换为本地构建镜像
    # 其他配置保持不变

图1：后端服务容器配置示例（来源于项目部署文档）

离线配置优化

1. 网络隔离调整

在离线环境下需禁用所有外部网络请求，修改docker-compose.yml添加网络隔离配置：

services:
  keep-backend:
    # 原有配置...
    networks:
      - isolated_network
      
  keep-frontend:
    # 原有配置...
    networks:
      - isolated_network

networks:
  isolated_network:
    driver: bridge
    internal: true  # 启用网络隔离

2. 认证模式配置

默认配置使用NO_AUTH模式，适合离线环境快速部署。如需启用认证，可修改环境变量：

services:
  keep-backend:
    environment:
      - AUTH_TYPE=LOCAL  # 本地认证模式
      - LOCAL_USERS=admin:password123  # 配置管理员账户

图2：认证服务配置界面示意图

服务启动与状态验证

1. 启动服务集群

使用修改后的docker-compose配置启动所有服务：

docker compose up -d

首次启动需初始化数据库，可通过查看日志确认启动状态：

docker compose logs -f keep-backend

当出现Application startup complete日志时，表示服务已成功启动。

2. 功能验证步骤

1. 前端访问：通过服务器IP:80（默认端口）访问UI界面，使用配置的本地账户登录
2. API健康检查：执行curl http://localhost:8080/api/health，返回{"status":"healthy"}表示后端正常
3. 数据持久化测试：在UI中创建测试告警规则，重启服务后检查数据是否保留在./state目录

图3：前端服务容器部署架构示意图

常见问题解决方案

1. 权限问题处理

若出现state目录权限错误，可执行项目提供的权限修复脚本：

chmod +x start.sh
./start.sh  # 脚本会自动修复目录权限

2. 镜像构建失败

• 依赖问题：检查pyproject.toml中的Python依赖是否完整
• 网络限制：确保构建环境能访问基础镜像仓库（可提前导入基础镜像）

3. 服务启动超时

修改docker-compose.yml增加启动超时配置：

services:
  keep-backend:
    restart: on-failure:3  # 最多重试3次
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

部署后配置建议

1. 维护窗口设置

通过UI创建定期维护窗口，避免服务运行中自动更新：

图4：维护窗口创建界面

2. 监控集成方案

如需在隔离环境中添加监控，可启用内置Prometheus服务（需在docker-compose中启用grafana profile）：

docker compose --profile grafana up -d

访问http://localhost:3001可打开Grafana监控面板，默认账户admin/admin。

总结与后续优化

通过本文步骤，你已成功在离线环境部署keep平台核心服务。后续可关注：

1. 配置备份：定期备份./state目录和docker-compose.yml配置
2. 镜像管理：使用docker save导出构建好的镜像用于多服务器部署
3. 安全加固：参考docs/deployment/authentication文档配置高级认证

如需进一步功能扩展，可查阅项目官方部署文档docs/deployment/docker.mdx获取更多配置示例。