基于Docker部署JumpServer堡垒机的实操避坑指南

跳板机不是堡垒机，堡垒机也不是一个只能用来跳来跳去的工具。我第一次接触JumpServer，是团队里服务器权限乱成一锅粥的时候——root密码在五六个人手里传来传去，生产环境今天有人改个配置，明天有人跑个脚本，出了故障谁也说不清楚是谁干的。后来下定决心上堡垒机，对比了一圈开源方案，最后还是用Docker把JumpServer拉了起来。到今天我已经在生产环境跑了一年多，中间经历过版本升级、组件故障、录像盘被塞满，也帮两个朋友从零搭过完整环境。

这篇文章不聊虚的，直接讲清楚三件事：为什么用Docker部署JumpServer、完整落地一台堡垒机的实操过程、以及我踩过的那些坑和对应的排查方法。适合刚接触堡垒机的运维、安全同学，也适合已经在用但想梳理清楚原理的人。

1. 为什么选JumpServer：先搞清楚堡垒机到底解决了什么问题

1.1 没有堡垒机的运维现场有多混乱

想象一下你们公司的服务器密码管理方式：可能是一个Excel表格，可能是某个聊天软件置顶消息，更可能是每个人脑子里记一份。开发要上服务器看日志，运维要改配置，外包同事要部署代码，所有人都拿着生产环境的账号直接连。

这个模式最大的问题不是密码泄露，而是“无法追溯”。线上出了故障，你问了一圈谁改过配置，大概率没人承认。就算查登录日志，也只能看到一堆IP和用户名，同一个账号多个人用的时候，根本无法定位到具体的人。还有更麻烦的——高权限操作没有审批流程，删库跑路的新闻大家听得够多了。

堡垒机就是解决这个问题的中间层。它不再是让你直接连服务器，而是让你先连堡垒机，再通过堡垒机跳转到目标服务器。所有连接都会被记录、审计，高权限操作可以加审批，命令可以过滤，全程录像回放。说得直白点：堡垒机就是一个带监控和门禁的“运维中转站”。

1.2 JumpServer这个开源项目为什么能打

开源堡垒机里，JumpServer是我目前见过综合能力最均衡的一个。它从资产纳管、账号管理、授权控制，到会话审计、命令过滤、录像回放，核心功能一应俱全，而且支持Linux、Windows、数据库、Kubernetes这些常见资产类型。

为什么选它而不是自己基于STS写一套？因为堡垒机看起来简单，做起来很繁琐。你不仅要处理SSH、RDP、VNC这些协议，还要做录像、命令解析、文件传输审计，更别提用户权限体系和工单流程。JumpServer把这些都封装好了，而且Docker镜像发布很规律，版本迭代快，社区活跃，遇到问题基本都能搜到答案。

我实际用下来的感受是：中小团队直接上社区版就够用，不需要一开始就买商业堡垒机。等资产规模上去了、有合规审计要求了，再考虑专业版也完全来得及。

1.3 为什么用Docker部署而不是源码编译

JumpServer的源码部署方式，需要你准备Python、Node.js、Rust等一堆编译环境，还要手工处理Celery、KoKo、Lion这些子组件之间的调用关系。我第一次尝试源码安装时，光编译KoKo就花了大半天，中间还遇到依赖包版本冲突，实在痛苦。

用Docker Compose部署则完全是另一回事。官方把整个堡垒机拆分成了Web、Core、KoKo、Lion、Celery等容器，一个编排文件就能全部拉起来。组件之间通过容器网络通信，依赖关系由编排文件管理，升级的时候只需要拉新镜像然后重启容器。这对于生产环境维护来说，省下的时间不是一点半点。

还有一点很多人忽略：堡垒机这种系统，最怕的就是“装完不敢动”。源码部署的堡垒机，升级一次可能要重新编译、改配置、折腾环境，而Docker部署的升级路径非常清晰，备份数据目录然后拉新镜像启动就够了。我后来能持续升级小版本，靠的就是Docker这套部署方式。

2. 部署前的软硬件与版本选型

2.1 硬件配置要多少才够

先说结论，再讲原因。

我最初在一台2核4G的旧服务器上跑，纳管了30多台机器，日常并发连接10个以内，运行很流畅。后来加到一百多台资产、并发到了三四十个，内存就会明显吃紧，尤其是KoKo组件处理SSH连接时CPU占用会上去。

磁盘是很多人容易忽略的点。堡垒机的录像文件会持续写入磁盘，会话越多录像越多。一台Linux主机的Web终端录像，一天就算只有两小时会话，30天累积下来也要几个GB。所以建议数据盘和系统盘分开，把录像目录放到独立挂载的大容量磁盘上，后面我会讲到具体配置。

2.2 版本选型：社区版v3的正确打开方式

JumpServer现在的主流版本是v3.x系列，和老的v2.x相比，前端界面、API体系、工单流程都有很大变化。新部署我强烈建议直接用v3最新稳定版，不要装v2。

有一个关键点很多人不知道：v3版本首次登录需要上传License文件。社区版License是免费的，在官网用邮箱就能申请，但申请时要选择对应的版本号。我第一次就是没注意版本号，申请了个旧版本的License，上传时提示不匹配，还得重新申请。后面我会在部署实操里详细说这个流程。

2.3 环境准备：Docker、时区和防火墙

部署之前先把基础环境准备好。我这里以CentOS 7和Ubuntu 22.04为例，其他发行版同理。

安装Docker和Compose插件：

# CentOS 7 yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # Ubuntu 22.04 apt update && apt install -y docker.io docker-compose-v2

装完设置开机自启：

systemctl enable --now docker docker --version docker compose version

然后设置时区，堡垒机的录像时间和日志时间依赖这个：

timedatectl set-timezone Asia/Shanghai

防火墙放行端口。JumpServer默认用到三个关键端口：80（Web访问）、2222（SSH协议入口，用来给用户通过SSH客户端连堡垒机）、25011（内部组件通讯端口，KoKo、Lion等组件注册用）。

firewall-cmd --permanent --add-port=80/tcp --add-port=2222/tcp --add-port=25011/tcp firewall-cmd --reload

注意：25011这个端口我一开始没放行，结果页面打开正常，但点“连接”之后一直转圈，最后排查了半天才发现是这个端口被防火墙挡住了。

3. 部署实操：从拉取编排文件到完成激活

3.1 目录规划与编排文件下载

部署服务器上我建议创建一个固定的数据目录，这样将来升级、备份、迁移都方便。我习惯用/opt/jumpserver作为根目录，在这个目录下存放编排文件和持久化数据。

cd /opt mkdir -p jumpserver cd jumpserver

然后从JumpServer官方GitHub Release页面下载当前稳定版本的docker-compose.yml。下载地址在Release页面里能找到，用curl或wget都行。

# 以某个v3.x版本为例，实际使用时替换为你选择的版本号 curl -sSL https://github.com/jumpserver/Dockerfile/releases/download/v3.x.x/docker-compose.yml -o docker-compose.yml

下载完成先不急着启动，把镜像提前拉好，避免启动时超时：

docker compose pull

这个步骤会把镜像仓库里的Core、KoKo、Lion、Celery等镜像全部拉下来，第一次大概有2-3G的流量，根据网络情况需要几分钟到几十分钟不等。

3.2 docker-compose.yml的关键配置解读

拉下来的编排文件里，有几个点值得认真看一下，这决定了你后面会不会踩坑。

端口映射部分，默认是这样的：

ports: - "80:80" - "2222:2222" - "443:443" - "25011:25011"

如果你服务器上80端口已经被Nginx占了，可以把宿主机端口改掉，比如"8080:80"。但是要注意，2222端口改掉之后，你通过SSH客户端连接堡垒机时的端口就变了，客户端那边也要做相应修改。另外，改端口映射之后，页面里的“连接配置”向导显示的地址也会变，需要同步更新。

环境变量部分，最关键的是这三个：

如果编排文件里没有显式定义这两个值，第一次启动时会自动生成，生成后会被写入.env文件。我的建议是部署完成后，立刻把.env文件备份一份到安全的地方。

数据持久化部分，编排文件会把容器内的数据目录映射到宿主机：

• config：Core和组件的配置文件
• data：数据库文件
• media：会话录像、文件传输记录

这三个目录将来就是你的备份重点。

3.3 启动与初始化

环境准备好、编排文件就位后，启动其实只有一条命令：

docker compose up -d

首次启动时，会先运行一个init容器，它负责初始化数据库表结构、写入初始数据。初始化需要二十秒左右，不用担心。启动过程中可以随时查看状态：

docker compose ps

正常情况下你会看到core、koko、lion、celery、web、redis、mysql这些容器都处于running状态。我见过的最常见问题，是首次启动时看core容器一会儿启动一会儿退出，这大概率是数据库还没初始化完，init容器还在跑。等一分钟再docker compose ps看看，不要慌着删容器。

3.4 首次登录、改密和License激活

打开浏览器访问http://你的服务器IP，会看到JumpServer的登录页面。默认账号是admin，默认密码是admin。

首次登录后会强制要求修改密码，这个没什么好说的，直接改。改完密码会重新跳回登录页，很多人到这里以为出问题了，其实是正常的，用新密码登录就行。

登录进去之后，页面会引导你上传License文件。社区版License去官网申请：填写一个能收到邮件的邮箱地址和你的组织名称，然后选择版本号。这里就是前面提醒过的坑——选择的版本号必须和你部署的版本一致，比如你部署的是v3.10.x，就选v3.10.x。

提交申请后，License文件会很快发到邮箱里。下载下来，上传到页面，激活成功后就能看到完整的管理界面了。

注意：License是绑定版本号的，将来升级大版本（比如v3.10升到v3.11）之后，需要重新申请对应版本的License。不过社区版申请免费，流程也不复杂，提前准备好就行。

4. 把第一台Linux主机纳管起来：资产-账号-授权-连接

4.1 “资产”到底是个什么概念

JumpServer里，“资产”是一个统称，既可以是一台Linux/Windows服务器，也可以是一个MySQL实例，还可以是一台网络设备。管理入口在左侧菜单“资产管理”里。

点击“创建资产”，最核心的字段就几个：

• 主机名：给资产起个好识别的名字，建议用业务名+IP的格式，比如“订单中心-db-01”
• IP地址：堡垒机能够访问到的地址
• 协议：Linux选SSH，Windows选RDP
• 端口：默认SSH是22，RDP是3389

创建完之后，页面会显示资产的连通性状态（在线/离线），但要注意：这个在线状态是跳转组件去探测的，如果探测不通，先检查网络和防火墙，不一定是资产管理本身有问题。

4.2 账号体系：特权账号与系统用户

资产创建好之后，下一步是往资产里填账号。JumpServer的账号体系分为两层，我花了一段时间才彻底理清。

第一层叫“特权账号”，也常称为管理账号。它保存的是你在目标服务器上的真实账号（通常是root或带sudo权限的账号），堡垒机用它来登录目标机器、收集信息。点击资产的“账号”标签页，添加账号时填上真实的用户名和密码，或者SSH Key。

第二层叫“系统用户”，是JumpServer内部定义的用户，它决定了用户以什么身份登录资产。系统用户可以绑定资产上的真实账号。比如你创建一个系统用户叫“ops-admin”，指定它使用某台资产的root账号登录，然后给团队成员授权时选择这个系统用户，大家登录资产时看到的就是同一个账号身份。

说得更直白点：特权账号是“堡垒机替你保管的钥匙”，系统用户是“你发给员工的通行证”。钥匙只有堡垒机自己有，员工只接触到系统用户。

4.3 授权规则与Web终端实测

账号准备好后，在“权限管理”里创建授权规则，把“用户”和“资产”关联起来。

创建授权规则时，选择要授权的用户或用户组，再选择资产，然后设定登录账号（选择前面创建的系统用户）。提交之后，授权即时生效，不需要重启任何组件。

接下来验证一下整个链路。打开“会话管理”里的“Web终端”，界面上会列出当前用户有权限访问的资产列表。点击任意一台Linux主机，浏览器会打开一个终端窗口，这就是KoKo组件在处理SSH连接。如果配置正确，你会直接进入目标机器的命令行界面。

我初次验证时最“顺滑”的感受是：从入口选择资产到拿到shell，整个过程几秒钟，跟直接SSH连过去几乎没区别。而且右侧能看到会话时长、当前登录用户，这些信息在传统直连方式下是完全没有的。

4.4 SSH客户端接入：2222端口的玩法

不是所有场景都适合开Web页面。很多老运维习惯用终端工具，JumpServer也支持标准的SSH协议接入，这也是2222端口存在的意义。

在你的电脑上执行：

ssh 用户名@堡垒机IP -p 2222

这里填的是JumpServer上的用户账号，不是目标机器的账号。回车后会进入一个交互式列表，显示你有权限访问的资产，输入对应的序号就能建立连接。

这个方式的好处是不用装任何客户端，系统自带的ssh命令就行。对用户来说，体验从“记一堆服务器密码”变成了“只记一个堡垒机账号”，而且所有操作照旧会被审计。

5. 避坑实录：我部署和用了一年踩过的坑

5.1 组件状态不健康/离线怎么排查

用过一段时间后，在“系统状态”页面看到某个组件状态变成红色，是最常见的告警。我遇到最多的是koko组件离线。

第一步看容器本身是否正常：

docker compose ps docker compose logs koko --tail 100

常见原因一是网络不通，二是组件注册token不匹配。如果是升级之后出现的离线，多半是BOOTSTRAP_TOKEN变了，导致组件无法注册到Core。这时候需要把旧的token恢复回去，或者统一更新所有组件的token。

还有个容易被忽略的点：如果你的服务器有过重启，容器因为某种原因没有自动恢复。检查一下Docker的开机自启策略是否配置正确。

5.2 Web终端连不上目标机器，但直连是通的

这个现象很有迷惑性：你在自己的电脑上直接SSH目标机器完全正常，但通过堡垒机的Web终端连接时提示超时或者连接失败。

一般排查顺序是这样的：

• 确认目标机器的22端口能连通（堡垒机到目标机器的网络是否通）
• 确认资产创建时填的端口没错
• 确认用的系统用户没有绑定错误的账号
• 确认账号有没有过期、密码有没有改过

我遇到过最隐蔽的一个问题，是目标机器的防火墙限制了来源IP，只放行了办公网段，堡垒机不在放行范围内。排查时绕了很大一圈，最后在目标机器上看了防火墙日志才定位到。

5.3 转圈半天打不开会话，端口被防火墙挡了

前面提到过，25011端口是组件通讯端口。如果你页面打开正常，组件状态显示在线，但点“连接”之后浏览器一直转圈，大概率是这个端口没放行。

这种“部分功能正常”的故障最容易被忽略，因为80端口通了会让你觉得服务没问题。实际上Web页面和会话连接走的是不同链路，页面访问走80，而会话转发要经过25011。所以部署完成后，建议一次性把80、2222、25011三个端口都放行。

5.4 磁盘被录像和日志塞满

堡垒机跑久了，最容易被忽视的就是磁盘。我有一台服务器，部署时给了80G磁盘，前三个月一切正常，第四个月开始频繁告警，一看/opt/jumpserver/media目录已经吃掉了50多G。

录像文件是持续增长的，这个问题只能靠“转储”和“清理”两条腿走路。我在日志轮转上做了调整，同时给录像目录配了定期任务，超过90天的录像归档到独立存储，再定期清理更老的视频文件。如果你有合规要求需要保存更长时间，就把录像目录放到专门的大容量存储上。

5.5 License过期了连登录都进不去

有次我帮朋友检查一套部署很久的JumpServer，发现登录页面一直提示License过期，导致管理员都无法进入后台。这个问题的根源是当时部署的版本太旧，License到期后没有及时更新。

处理办法不复杂：在登录页找到License上传入口（通常有“本地上传”或“离线更新”按钮），把新申请的License文件传上去就行。如果连上传入口都没法显示，最后的手段是进入容器内部修改License文件，但不建议在不知道具体路径的情况下乱试，还是优先走官方流程。

5.6 升级前不备份的代价

JumpServer的Docker部署做得很方便，以至于有人会忽视备份。我见过一次升级翻车：从v3.x的一个旧版本直接跳到新版本，数据库结构变化比较大，升级后部分资产数据异常，最后只能恢复旧数据从头再来。

任何升级之前，把config、data、media三个目录完整备份一遍，再顺手备份一下.env文件。用Docker跑起来的服务，备份起来其实非常单纯——打包目录就行。恢复时先停掉旧容器，把备份目录解压回原路径，再重新启动。

6. 生产化落地：从“能用”到“好用”的几个关键调整

6.1 把内置MySQL和Redis换成外部的

Docker Compose默认会拉起内置的MySQL和Redis容器，测试环境完全没问题，但生产环境建议尽早切换为外部独立部署的MySQL和Redis。

原因是多方面的：内置数据库跟着容器生命周期走，一旦容器异常，数据恢复的复杂度会上升；外置数据库可以单独设置备份策略和性能参数，也能配合监控体系做实时告警。切换到外置时，在.env文件里指定外部数据库的地址、账号、端口和库名，然后重启Core相关容器即可，原来的数据可以先通过工具迁移过去。

MySQL的版本建议用8.x，Redis建议用6.x以上。数据库账号单独建一个，不要用root直接连，密码强度要求高一点。

6.2 会话录像放到独立存储

前面讲了录像文件会膨胀，生产环境更建议把media目录直接映射到NFS、NAS这类独立存储上。

具体做法是在宿主机挂载NFS目录，然后把docker-compose.yml里media的volume映射源改成NFS挂载点。这样有两个好处：一是录像文件的增长不再占用系统盘空间；二是多节点部署时，各个组件的录像可以集中存储，审计查询更容易。

我实际改过一次，需要注意NFS挂载的超时参数和并发能力。如果堡垒机的并发会话比较多，NFS性能跟不上会导致录像写入延迟，进而影响会话体验。所以网络存储的设备选型和链路质量要关注。

6.3 备份策略与恢复演练

我在生产环境的备份策略供参考：

• 每晚对MySQL数据目录进行逻辑备份，保留最近7天
• 每晚对config目录和.env文件做增量备份
• 每周对media目录做快照归档
• 每月做一次完整的恢复演练——真的找一台临时机器，把备份目录解压，启动容器，验证数据可用

恢复演练这件事很多人觉得麻烦，实际做一次就会发现“备份了但恢复不了”的风险真实存在。我有次做演练，发现备份脚本漏了.env文件，导致恢复到新机器上时，组件注册token对不上，折腾了两个小时才解决。从那之后，备份清单里就死死盯着这几个文件。

6.4 上线节奏：先小范围试点再全量推广

如果你想在生产环境平稳落地堡垒机，我个人的建议是不要一上来就强制所有人切换。

先在开发环境跑通Linux资产的纳管和授权，让两三个运维同事先试用，收集反馈。等大家习惯了“先进堡垒机再连服务器”的流程，再把Windows资产、数据库资产逐步接入，最后再考虑停掉原生的SSH直连端口。我见过一个团队为了推堡垒机，一刀切关停了所有直连端口，结果当天就有人因为不熟悉流程影响了线上排查进度。堡垒机是管控手段，但不是给运维制造障碍的，节奏要缓，推广过程中不断优化授权规则和会话体验，效果反而最好。

最后再分享一个我个人的小经验：堡垒机上线之后，定期去翻一翻“会话记录”和“命令记录”。我之前通过命令记录发现有个同事在测试环境执行了rm -rf高危命令，虽然没造成事故，但提醒我及时加上了命令过滤规则，后来正式环境里类似的风险操作就被有效拦截了。堡垒机这种东西，装上之后才是开始，持续优化规则和流程，才能真正把价值发挥出来。