刚入行运维时,我最先学会的不是什么高深命令,而是老老实实把 Jumpserver 堡垒机部署起来。那时我以为,照着一篇教程敲命令就行,真正操作才发现:几乎每个人都栽过跟头,而且栽得大同小异。
相关服务:美国高防服务器租用
有人卡在 Docker 版本上,有人把数据库目录挂在临时盘上重启一次数据就没了,有人在页面上创建完用户却发现没有资产可用,还有人部署完根本不知道怎么验证审计有没有真的生效。等我把这些坑都趟过一遍,重新回看那些部署教程,才意识到一件更重要的事: Jumpserver 部署真正的难点,不是命令,而是命令背后的部署规划。
网上关于 Jumpserver 的教程确实不少,但很多都是把官方文档简化成一个“照抄”流程。这类教程往往忽略了你自己的环境差异、组件依赖关系和账号模型逻辑。而这恰恰是生产环境中部署成败的关键。
这篇文章不会停留在“复制粘贴能跑通”的层面。我会先讲清楚部署前必须想明白的那几件事,再走一遍实际部署流程,然后说透最容易出问题但又很少有人讲的环节,最后给出一套可以复用的排查链路和长期维护建议。如果你正准备把 Jumpserver 放进企业环境,这篇文章能帮你少走很多弯路。

1. 单看部署命令的人,大多会卡在同一个地方
我先说一个可能和直觉相反的观点:Jumpserver 部署本身不复杂,复杂的是 理解它到底由什么组成、数据落在哪里、账号之间是什么关系 。这三件事没想清楚,命令敲得再顺,后面也一定会遇到莫名其妙的问题。
1.1 不是一个服务,而是一组服务
很多人第一次部署 Jumpserver 时,以为它只是一个独立的 Web 服务。实际上,用 docker-compose 方式部署时,你自己看一眼目录就明白了:服务不止一个。
常见的一套组件至少包括:
- Core :Jumpserver 的核心后端,负责处理用户认证、授权、API、会话管理等核心逻辑。
- Koko :负责处理 Web 终端和 SSH 协议的连接,是用户通过浏览器登录资产的关键中间层。
- Lion :负责处理 RDP、VNC 等图形化协议的连接,用来访问 Windows 资产。
- MySQL :存放用户、资产、授权策略、操作日志等核心元数据。
- Redis :缓存会话状态、用户 token 以及部分临时数据。
- Nginx :负责 Web 端口的反向代理和静态文件服务。
这些组件之间是依赖关系。Core 挂了,用户登录不了;Koko 挂了,SSH 连不上;数据库坏了,所有资产、授权和审计记录都可能丢。所以,第一步不是急着跑
docker-compose up -d
,而是先弄清楚这几个容器各自负责什么。
我在实际项目中见过一个很典型的例子:部署完成后,浏览器能打开登录页,但一点“连接”就卡住,过一会儿报连接超时。排查了半天,最后发现是 Koko 容器没有正常启动,因为宿主机上的某个端口已经被其他服务占用了。如果只看 Core 容器还活着,就很容易误判为系统正常。
1.2 搭建三个账号体系同时出现在一个平台里,这是最容易迷糊的地方
Jumpserver 有一个让人又爱又恨的设计: 账号模型分三层 。
第一层是 Jumpserver 平台用户 ,也就是运维人员登录堡垒机的账号。第二层是 Jumpserver 的系统用户 ,这个“系统用户”不是 Linux 系统里的用户,而是你想让运维人员以什么身份去连接目标资产,本质上是资产侧的登录凭据。第三层是 目标资产本身的账号 。
这三层账号的关系,简单说就是:一个运维人员登录 Jumpserver,被授权使用某个系统用户去连接某台资产。系统用户决定了他在资产上是 root、是普通用户,还是专用运维账号。
很多新手在这里会犯一个错误:创建完用户以后,发现用户能登录 Jumpserver,但“资产列表”是空的。其实原因很简单,你只创建了平台用户,还没有把系统用户和资产关联到授权策略里。用户有账号,不代表他有权限连资产。
部署完以后,建议先花点时间把这三层关系记牢。否则后面排查“登录不上资产”“能登录但没权限”“权限过大不安全”这类问题时,会浪费大量的时间。
1.3 部署方式选择:docker-compose 是当前最适合大多数团队的方式
Jumpserver 的部署方式主要有几种:源码安装、一体化部署脚本、docker-compose 部署和 Kubernetes 部署。
从工程经验看,我不建议新手一上来就去动源码安装。除非你是要深入做二次开发,否则这套方案依赖太多、升级成本高、排查链路长,对普通运维团队来说性价比太低。
一体化部署脚本确实方便,但它更像一个“黑盒”,出了问题你不好判断是哪一层的问题,而且它把很多路径和参数写死在脚本里,个性化调整时需要改动的点比较多。
docker-compose 部署是我更推荐的方式。它用一个配置文件把每个组件的镜像、端口、数据目录和依赖关系都定义清楚,既有一定透明度,又比 Kubernetes 简单得多。如果团队规模不大、资产数量在几百台以内,这个方案完全够用。等真的到了需要大规模调度、多集群管理的阶段,再考虑往 Kubernetes 迁移也不迟。
也就是说,部署前先明确环境变量文件里的配置,比如
SECRET_KEY
、
BOOTSTRAP_TOKEN
、数据库密码、端口映射和数据持久化路径。以下是常见配置字段的解释,方便你对照检查。
2. 部署之前,先花半小时做规划,比多花三小时排错划算
这个章节是很多教程不会展开讲的,但它恰恰决定你能不能从“本机能跑”走到“生产可用”。
2.1 把域名、HTTPS 和访问端口提前定好,而不是装完再改
如果你只是在自己电脑上装一个测试环境,那么用 IP 加端口访问没什么问题。但如果要放进企业环境,就必须提前定好两件事: 用什么域名访问、HTTPS 证书怎么解决 。
不建议跳过 HTTPS。堡垒机上走的都是运维操作,明文传输意味着账号口令和操作内容都可能被截获。没有 HTTPS 的堡垒机,就像把数据库密码写在便利贴上贴在工位上,方便是方便,但风险太大了。
可以用企业内部 CA 签发证书,也可以用公网可信证书。重要的是在部署阶段就把证书文件准备好,避免部署完之后再改 Nginx 配置。改了之后要重启容器、重新加载证书,万一中间有路径写错,排查起来又是一轮时间。
端口方面也要提前规划。默认配置里,Web 访问端口、SSH 端口和数据库端口可能都有默认值,但这些端口在真实环境里很容易被防火墙策略限制,或者和已有服务冲突。提前列一张端口清单,确认哪些端口要对外放开、哪些只允许内网访问,能省下不少事。
2.2 磁盘和数据目录:先回答“数据坏了能不能承受”这个问题
Jumpserver 里有三类数据不能丢:数据库里的用户、资产和授权信息,Redis 里的会话缓存,以及操作审计录像和日志。
审计录像尤其容易忽略。等你真正用起来,每天有几十上百次运维会话,录像文件增长速度并不慢。如果数据目录是放在一个很小的磁盘分区上,那么大概率会在某一天突然写满,导致新录像无法保存,甚至影响组件运行。
部署之前,建议你按这个思路做磁盘规划:
- 单独确认一块数据盘,不要和系统盘混用。
- 把 Jumpserver 的数据目录整体放到数据盘上,并保证有充足余量。
- 提前想好录像和日志的归档策略,可以定期导出到备份服务器或对象存储。
- 做好目录权限控制,不要让普通用户随意读写部署目录。
这里我特意把“提前”两个字加粗了。因为如果装完才发现磁盘不够,再迁移数据目录,不仅要停服务,还要小心翼翼处理文件读写和权限,风险比一开始规划好大得多。
2.3 版本选择和镜像拉取:不要追最新,稳定优先
Jumpserver 的发布节奏比较快,但“新版本”不等于“生产可用”。在真实环境里,我更建议关注社区和官方文档里的长期支持版本,而不是每次发版都立刻升级。
镜像拉取也是新手容易忽略的一环。很多机器拉取 Docker Hub 镜像很慢,或者根本拉不下来,导致部署脚本卡在下载阶段。这时候可以先配置镜像加速地址,或者在有网络代理的机器上提前把镜像拉下来再导入。注意,这里说的代理是指企业内部网络访问代理,用于拉取公共镜像,这是合规的企业网络操作手段。
另外,一定要核对镜像标签和 docker-compose 配置文件里的版本是否一致。有些教程写的是最新版镜像,过一段时间再参照时,镜像已经被新的 latest 标签覆盖了,配置文件和实际镜像版本对不上,就会跑出各种诡异的问题。
3. 完整部署流程:从换源到验证,一步都不能省
下面是基于 docker-compose 方式部署 Jumpserver 的完整参考流程。你需要根据自己的环境和版本,先确认适配情况再执行。
3.1 环境准备:确认系统、Docker 和资源占用
一个最基础的 Jumpserver 环境,建议至少准备 4 核 CPU、8GB 内存、100GB 可用磁盘。如果资产量较大,或者经常有并发会话,建议把资源规格再往上提。
Linux 系统建议使用较新的稳定发行版,比如 Ubuntu 22.04 LTS、Debian 12 或 Alibaba Cloud Linux 3 等。开始之前,先确认 Docker 和 Docker Compose 已经安装,并检查版本,确保 docker compose 插件可用:
docker --version
docker compose version
如果确认版本没问题,就可以创建工作目录并下载部署配置文件。这里的路径可以根据你的情况调整,但要保证后续所有数据和配置都放在同一个管理目录下,方便备份和升级。
# 示例:创建一个部署目录
sudo mkdir -p /opt/jumpserver
cd /opt/jumpserver
接下来,你需要准备一个
.env
环境变量文件,内容至少包含数据库密码、Redis 密码、SECRET_KEY、BOOTSTRAP_TOKEN 等字段。这里给出的是示例结构,实际部署时务必替换成你自己的强随机值并妥善保存,因为后面恢复和升级都会用到。
# 这是简单示例,生产环境请使用更长的随机值
SECRET_KEY=your-random-secret-key-here
BOOTSTRAP_TOKEN=your-bootstrap-token-here
DB_HOST=mysql
DB_PORT=3306
DB_USER=jumpserver
DB_PASSWORD=your-strong-db-password
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-strong-redis-password
3.2 启动组件:观察容器状态而不是只看“命令执行完”
执行以下命令拉起所有服务:
docker compose up -d
注意,这里的
docker compose
是插件写法。如果你使用的是旧版
docker-compose
,就需要把命令换成
docker-compose up -d
。版本之间有一些差异,先确认好了再执行。
启动后不要急着登录页面,先检查一下容器状态:
docker compose ps
正常状态下,各组件应该是
running
状态。但即使显示
running
,也不代表服务已经就绪。容器在启动初期有一个初始化过程,数据库要完成建表,Core 要执行初始化脚本,这些都完成以后,Web 页面才能访问。
这是很多新手容易踩的坑:容器显示运行中,就立刻打开浏览器,结果页面打不开,就开始怀疑部署有问题。其实只是还没初始化完。建议等一两分钟,再通过日志确认:
docker compose logs -f core
看到类似“Startup complete”或者服务监听正常的关键日志,再去访问 Web 页面。有一种更可靠的验证方式,是等初始化完成后看整个堆栈的健康状态,而不是只看某个容器。
3.3 初始化管理员账号:第一次登录会触发创建过程
浏览器访问
http://你的服务器IP
,第一次访问会进入管理员账号初始化页面。你要在这里设置 Jumpserver 管理员的邮箱和密码。
很多教程会把这一步写得很简单,但我要提醒一件事: 管理员密码一定要放进密码管理器里保存 。这个账号拥有整个堡垒机的管理权限,如果丢了,恢复起来相当麻烦,可能需要直接操作数据库来重置。
初始化完成后,用管理员账号登录。进入页面后先不要急着创建资产或用户,先观察几个关键菜单,比如“用户管理”“资产列表”“授权规则”“会话审计”。如果这些菜单都能正常访问,说明 Core、数据库和 Web 前端都正常工作了。
到这一步,你的 Jumpserver 已经完成了基本部署。但真正的挑战才刚刚开始。
注意:这里有一个容易被忽略的点——数据库密码、SECRET_KEY 和 BOOTSTRAP_TOKEN 一旦部署完成并初始化数据,就不要随意修改。否则会导致 Core 和其他组件之间认证失败,出现“登录不了”“组件离线”等不明问题。
3.4 添加资产、系统用户和授权策略:三层关系打通
你有一个管理员账号,但还不能用它直接连接任何资产。因为管理员只是“平台管理员”,不是“资产连接凭据的拥有者”。
先到“资产列表”里添加一台 Linux 资产:
- 填写资产 IP、主机名。
- 选择协议,SSH 默认端口是 22。
-
在“系统用户”部分,新建一个系统用户,比如
ops,并填写这台 Linux 机器上真实的 SSH 登录账号名和密码(或私钥)。 - 保存资产后,回到“授权规则”,新建一条规则:给某个 Jumpserver 用户或用户组,授权使用刚才那个系统用户,访问那台资产。
之后让那个用户在“Web 终端”里选择目标资产,Jumpserver 会通过 Koko 组件发起 SSH 连接,以系统用户的身份帮用户登录到资产上。
很多教程停在这一步就结束了,但我会提醒你把验证链路走完,因为这才是部署是否成功的真正分界线。
4. 部署成功从来不是“页面能打开”,而是“审计链路完整可用”
我见过不少团队,部署完以后页面能打开、用户能登录、资产能连接,就觉得一切正常。直到有一次审计需要调一份操作录像,才发现录像文件根本没有生成。
堡垒机的核心价值,在于“所有运维操作可管、可控、可审计”。如果审计链路没有打通,前面的部署就没有完成。
4.1 验证用户登录、资产连接、录像生成三层闭环
部署完成后,建议按下面三步做完整验证。
第一步,验证平台用户登录 :用管理员创建的一个普通用户,从浏览器登录 Jumpserver,确认登录成功,确认该用户看不到不属于他的资产。
第二步,验证资产连接 :进入该用户的“Web 终端”,点击目标资产,确认能通过堡垒机成功 SSH 登录到目标机器。注意观察页面顶部的会话连接信息,确认当前会话确实是由 Koko 组件代理建立。
第三步,验证录像和日志生成
:在 SSH 会话里执行几条简单命令,比如
ls
、
whoami
,然后退出会话。回到管理后台的“会话审计”或“操作审计”菜单,查看刚才那次会话是否有记录,尝试回放录像。
如果录像回放不出画面,先不要急着判定系统有问题,先按这个顺序排查:
- 会话结束后,录像文件是否已经落盘到数据目录。
- Core 服务是否有权限访问录像目录。
- 浏览器是否限制了本地存储或弹窗。
- 当前浏览器是否支持回放所需的组件。
只有打通这三步,你的 Jumpserver 才算真正完成部署。
4.2 系统用户复用与密钥管理模式
当资产数量超过几十台后,逐一在资产上创建系统用户会变得很繁琐。更常见的做法是,将系统用户做成一个“运维账号模板”,并通过批量下发 SSH 密钥的方式,让目标资产信任堡垒机上的某个密钥。
这个方法的关键是:堡垒机上有几个“系统用户”,每个系统用户对应一种登录身份,比如
root
、
deploy
、
readonly
。这些运维账号在目标资产上真实存在,并且使用堡垒机生成的公钥或密码进行认证。
我在实际项目里比较推荐的做法是:
- 所有需要 root 权限的操作,尽量收敛到单独的授权规则里。
- 普通日常操作,用低权限系统用户。
- 系统用户的私钥由堡垒机集中托管,不允许运维人员导出私钥。
- 一旦有人离职,只需要在 Jumpserver 里禁用该用户,而不用逐台服务器改账号密码。
这套模式一旦建立,你对服务器访问权限的控制能力,会比以前“每台机器一个密码”的时代强出很多。
5. 最容易出问题的五个环节,以及一条完整排查链路
Jumpserver 的部署成功,往往不是因为某个步骤有多高级,而是因为你知道问题可能出在哪一层。下面这五个环节是我见到的故障高发区。
5.1 用户登录不了,先别怀疑密码,先看用户状态
“能打开登录页,但登录失败”是常见问题。很多人第一反应是密码错了。其实要先排查三点:
- 用户状态是否正常,有没有被锁定或禁用。
- 用户是否指定了可选登录方式,例如 MFA 验证未通过。
- Core 日志里有没有更具体的报错信息。
如果日志里出现数据库连接失败或 Redis 连接失败,那问题大概率不在账号,而在基础设施层。
5.2 资产连接不上,不要只看网络,先看 Koko 日志
Web 终端连不上资产时,很多人的第一反应是测目标机器的 22 端口通不通。这当然重要,但 从堡垒机到目标资产的路径 才是关键。
应该先看 Koko 容器的日志:
docker compose logs -f koko
如果日志里提示认证失败,检查系统用户的账号密码或密钥是否正确。如果提示连接超时,检查网络策略是否放行了从跳板机到目标资产的安全组或防火墙。如果提示系统用户不存在,检查系统用户与资产的关联关系。
5.3 组件之间“链接断断续续”,先查时间和时间同步
Jumpserver 依赖 Token 和 Session 机制,如果宿主机的系统时间和容器内部时间偏差过大,会出现登录后很快掉线、API 鉴权失败、审计数据时间错乱等问题。
生产环境一定要配置 NTP 时间同步。部署完成后,可以用这条命令检查时间状态:
timedatectl status
如果
System clock synchronized
显示为
no
,或者时间偏差明显,先修时间同步,再验证 Jumpserver 登录和会话。
5.4 数据目录和备份:不要等数据丢了才后悔
我见过最惨的情况,不是 Jumpserver 崩溃,而是宿主机磁盘损坏后,发现唯一的数据还在同一块盘上,没有备份。堡垒机的数据库里存着所有账号、资产、授权规则和审计索引,录像文件更是运维审计的直接证据。
建议至少做到:
- 每天备份数据库,可以用定时任务执行 mysqldump 导出到备份服务器或对象存储。
- 定期备份录像目录,可以写一个增量同步脚本。
- 备份文件保留一定的周期,不要只留一天。
5.5 排查链路:从现象到根因,按层来
当 Jumpserver 出现问题时,可以先按下面这个顺序排查,不要一上来就去看配置文件,更不要来回重启容器:
- 看现象 :是登录页打不开,还是登录后资产列表为空,还是资产能连但无录像,还是速度特别慢。
- 看容器 :所有组件是否都在运行,有没有频繁重启。
- 看日志 :Core、Koko、Nginx 日志里近期有没有 ERROR 或 WARN。
- 看基础设施 :磁盘空间、内存占用、时间同步是否正常。
- 看配置和权限 :.env 文件是否被意外修改,数据目录权限是否正确。
这套链路不针对某个具体 bug,但它能帮你把“我系统好像坏了”这种模糊感觉,快速定位到某一层。
6. 生产环境长期使用,还需要补上这几块拼图
部署完成只是开始。如果 Jumpserver 要在企业环境长期稳定运行,以下问题你越早想清楚越好。
6.1 升级和维护:不要只在出问题时才想起它
Jumpserver 社区和商业版的迭代速度都比较快,安全修复和功能更新会定期发布。但升级之前,我强烈建议你走一遍这个流程:
- 先备份数据目录和数据库导出文件。
- 在测试环境跑一遍新版本的升级流程。
- 确认测试环境里的录像回放、Web 终端、授权规则都没有问题。
- 再在生产环境操作,并预留回滚时间窗口。
在主版本跨版本升级时,要特别关注依赖组件是否有变化,比如 MySQL 大版本、Redis 大版本是否变化。升级过程如果数据库结构发生变更,又没做好备份,一次失败可能就是一次事故。
6.2 高可用和分布式:什么场景才需要考虑
如果你的团队规模不大,一台机器部署的 Jumpserver 完全够用。但如果公司有几十上百台资产,且运维审计不能中断,就需要考虑更可靠的部署方式。
这里要先说清楚一个边界: docker-compose 单机部署适合中小规模场景,不适合需要高可用的核心运维中枢 。一旦宿主机宕机,Jumpserver 服务就会中断。对于这类需求,需要把 MySQL、Redis 等依赖组件分离出来,使用外部高可用数据库和缓存服务,核心组件本身也需要考虑多节点部署。
这不是一个简单工程。我的建议是:先单机跑起来,验证资产和授权模型,再逐步演进。不要一开始就在架构上叠加复杂度,因为那样你根本分不清是业务问题还是架构问题。
6.3 从“部署成功”到“制度落地”之间,还差一步
这里我想讲一个经常被忽略的事情。很多团队装好 Jumpserver 以后,就默认“以后运维操作都会被审计了”。但实际情况是,如果之前没有形成运维操作规范,大家还是会直接 SSH 跳过堡垒机,或者用其他跳板机出口直连服务器。
堡垒机要真正发挥作用,需要在制度层面做一件事: 所有运维操作必须通过 Jumpserver 进行 。
从技术手段上可以做这些配合:
- 在防火墙或安全组层面,限制运维人员从办公网直连生产服务器的 22 端口。
- 通过防火墙只允许堡垒机的 IP 访问目标资产的运维端口。
- 在目标资产的 SSH 配置里,限制允许登录的来源 IP 为堡垒机。
但从长期看,比“堵”更重要的,是让大家感受到堡垒机带来的好处:比如不用每台机器分别管理密码、访问授权更清晰、出了问题能回溯会话。当一个工具能做到这一步,大家才会真正愿意用。
7. 我的建议:先把最小闭环跑通,再去做“看起来很厉害”的规划
最后回到文章开头那句话。Jumpserver 部署的主要难点不是命令,而是 你有没有真正理解它由哪些组件组成、数据落在哪里、账号关系是什么、验证标准是什么 。
如果你现在正准备部署,我最想给你的建议是: 先不要急着研究高可用、分布式、复杂权限制度 。先把一台机器、一个运维用户、一台资产资产、一条授权规则、一次带录像回放的 SSH 连接跑通。等你亲手经历了“登录 → 授权 → 连接 → 审计”这个完整链路,你已经比大多数只看了教程的人强很多了。
然后把关键配置、初始密码、数据目录、备份方式记录下来,固化成一页交接文档。这一步的价值会在半年后显现:当团队加入新人,或者其他同事需要了解堡垒机时,你不需要把脑子里零散记忆重新整理一遍,直接查看文档就能获得完整上下文。
再往后,你可以逐步把用户分组、资产分组、命令过滤规则、高危操作审批、MFA 二次认证想起来。这些功能 Jumpserver 大多都有,但要在基础设施稳定和账号模型清晰之后再引入。
Jumpserver 这类工具的长期价值,不是让你“多了一个管理系统”,而是让运维工作从依赖个人记忆和经验,逐步走向可管理、可审计、可交接的工程化状态。这个过程不会很快,但每往前走一步,团队对系统的掌控力都会提高一点。