jumpserver/koko

KoKo 技术文档

镜像概述和主要用途

KoKo 是 JumpServer 的终端组件，主要用于连接各类字符协议服务，支持 SSH、TELNET、MySQL、Redis 等协议。该组件采用 Golang 开发后端，Vue 开发前端，名称源自 Dota 英雄 Kunkka。作为 JumpServer 生态的重要组成部分，KoKo 提供了字符协议连接的核心能力，是实现资产访问和管理的关键组件。

核心功能与特性

• 多协议支持：兼容 SSH、TELNET、MySQL、Redis 等主流字符协议
• 文件传输：支持 SFTP 协议进行文件上传与下载
• Web 终端：提供基于 Web 的终端访问界面，便于浏览器直接操作
• Web 文件管理：通过 Web 界面实现文件的可视化管理

使用场景与适用范围

KoKo 适用于需要通过 JumpServer 平台管理和访问各类字符协议资产的场景，包括但不限于：

• 服务器运维：通过 SSH/TELNET 协议管理 Linux/UNIX 服务器
• 数据库访问：连接 MySQL、Redis 等数据库服务进行管理操作
• 远程文件操作：通过 SFTP 或 Web 文件管理功能操作服务器文件
• 开发与测试环境：作为 JumpServer 生态的终端组件，支持开发环境的快速部署与测试

详细使用方法和配置说明

1. 下载与编译

1.1 下载项目源码

shell
git clone https://github.com/jumpserver/koko.git

1.2 编译应用

在项目根目录执行编译命令：

shell
make

编译成功后，项目根目录会生成 build 文件夹，包含当前分支各架构版本的压缩包。默认构建版本格式为 [branch name]-[commit]。若依赖下载缓慢，可设置代理：export GOPROXY=https://goproxy.io

2. 部署与运行（以 Linux amd64 服务器为例）

2.1 拷贝压缩包至目标服务器

编译生成的压缩包命名格式为：koko-[branch name]-[commit]-linux-amd64.tar.gz，需将其传输至目标服务器。

2.2 解压压缩包

shell
tar xzvf koko-[branch name]-[commit]-linux-amd64.tar.gz

2.3 创建配置文件

需手动创建 config.yml，配置参数参考 https://github.com/jumpserver/koko/blob/master/config_example.yml%EF%BC%9A

shell
touch config.yml

2.4 启动 KoKo

shell
cd koko-[branch name]-[commit]-linux-amd64
./koko

3. 配置文件说明

配置文件 config.yml 为核心配置项，关键参数说明如下：

• CORE_HOST：JumpServer Core 服务地址，格式为 http://<core-ip>:<port>（如 http://127.0.0.1:8080）
• BOOTSTRAP_TOKEN：与 JumpServer Core 一致的引导令牌，用于组件间认证（如 PleaseChangeMe，需与 Core 配置保持一致）
• 其他参数（如日志级别、端口等）可参考 config_example.yml 进行自定义配置

开发环境搭建

1. 后端服务运行

1.1 准备配置文件

shell
cp config_example.yml config.yml

1.2 修改核心配置

编辑 config.yml，配置 Core 地址和引导令牌：

yaml
CORE_HOST: http://127.0.0.1:8080  # JumpServer Core 地址
BOOTSTRAP_TOKEN: PleaseChangeMe  # 需与 Core 配置一致

1.3 启动后端

shell
go run cmd/koko/koko.go

依赖 Go 环境，若未安装，需从 golang.org 下载安装。

2. 前端服务运行

2.1 安装依赖

shell
cd ui
yarn install

2.2 启动开发服务器

shell
npm run serve

3. 开发测试

在 Luna 界面访问 Linux 资产，复制 iframe 地址并将端口修改为 9530；或通过 Nginx 配置将 /koko 路径映射至前端服务端口。

Docker 镜像构建与部署

1. 构建 Docker 镜像

需依赖 Docker 19.03+ 及 docker buildx 插件，用于构建多平台镜像：

shell
make docker

构建成功后，生成 koko 镜像。

2. Docker 部署示例

2.1 使用 docker run 部署

shell
docker run -d \
  --name koko \
  -p 9530:9530 \
  -v /path/to/config.yml:/opt/koko/config.yml \
  --restart always \
  jumpserver/koko:latest

2.2 使用 docker-compose 部署

创建 docker-compose.yml：

yaml
version: '3'
services:
  koko:
    image: jumpserver/koko:latest
    container_name: koko
    ports:
      - "9530:9530"
    volumes:
      - ./config.yml:/opt/koko/config.yml
    environment:
      - CORE_HOST=http://jumpserver-core:8080  # 替换为实际 Core 地址
      - BOOTSTRAP_TOKEN=PleaseChangeMe  # 替换为实际引导令牌
    restart: always

启动服务：

shell
docker-compose up -d

参考链接

• 项目源码：https://github.com/jumpserver/koko
• 配置示例：https://github.com/jumpserver/koko/blob/master/config_example.yml