Jumpserver 堡垒机是目前国内企业运维环境里使用非常广泛的开源堡垒机方案。它解决的不是“有没有一条通道能跳到服务器”，而是三件事：统一身份认证、精细权限授权、全程操作审计。服务器数量上来之后，谁在几点登录过哪台机器、执行过什么命令、有没有趁人不备改过系统配置，这些都要留痕可查。这篇文章就是一份完整的部署实操记录，适合刚接触堡垒机的运维工程师，也适合正在补安全合规能力的中小团队。下面按实际落地顺序拆：部署前的规划、环境准备、Docker Compose 安装、初始化配置、添加资产和授权、审计验证、常见报错排查，最后再说生产化建议。
1. 部署 Jumpserver 之前，先想清楚这四件事
1.1 堡垒机不是高级跳板机
很多人把堡垒机理解成“一台用来跳转登录的服务器”，这个理解不完整。跳板机只解决网络可达的问题，而 Jumpserver 这类堡垒机解决的是权限和审计的问题。它完整覆盖三层能力：
- 认证：所有运维人员都从同一个入口登录，账号密码之外还可以叠加 MFA 动态口令。
- 授权：用“用户 + 资产 + 系统用户”三个维度组合出授权规则，控制谁能登录哪台机器、以什么身份登录。
- 审计：Web 终端和 SSH 客户端的会话录像、命令记录、操作回放，全部保留在堡垒机里。
如果只是搞一台 Linux 服务器做 SSH 跳转，那确实不需要堡垒机。但当你需要回答“昨晚那个 root 操作是谁干的”这种问题时，没有审计记录就只能靠猜，猜不到就只能背锅。所以企业采购和部署堡垒机，核心诉求永远是审计合规，而不是一个转发入口。
1.2 用 Docker Compose 方式之前，先判断规模
Jumpserver 有多种部署方式：源码部署、一键部署脚本、Docker Compose、Kubernetes、分布式组件。对大多数第一次接触的人，官方推荐且社区教程最集中的是 Docker Compose 方式，这个选择适合以下场景：
- 单机部署，服务器规模在几十台到几百台之间。
- 团队不大，并发会话数不高。
- 快速交付，没有专门的运维平台团队。
- 学习演示，想先在测试环境里跑通完整流程。
反过来，如果公司资产上千台、多个机房、多个区域，或者对高可用和横向扩展有硬性要求，那 Docker Compose 的单机模式就不够用了。这时候应该研究分布式版或 Kubernetes 部署，而不是硬扛。我见过不少团队用单机堡垒机扛大流量，结果堡垒机自己先卡死，连登录都登录不进去，最后只能重启容器，审计数据还丢了一部分。
1.3 版本选择先看官方，不要照搬老教程
Jumpserver 有大版本迭代，不同版本的组件名称、安装脚本参数、容器列表都有差异。网上大量教程是基于老版本写的，很多命令换到新版本上根本跑不通。
安装前一定要做两件事：第一，到官方 releases 页面确认你准备安装的当前 release 版本；第二，到官方文档里找到对应该版本的部署说明。不要随便找一个第三方脚本就执行，也不要直接 clone 别人的配置文件。我之前排查过一个问题：用户的部署包是 v3 系，但他照着 v2 的教程去修改 .env，结果 core 组件一直连不上数据库，报错信息完全看不懂。
1.4 端口、数据目录和备份策略要提前规划
部署前先规划好三件事，能少踩一半的坑：
| 规划项 | 默认值 | 说明 |
|---|---|---|
| Web 访问端口 | 80 / 443 | 如果本机已有 Web 服务会冲突 |
| SSH 接入端口 | 2222 | 运维人员通过该端口登录堡垒机 |
| 数据目录 | /opt 下卷目录 | 建议放到独立数据盘 |
| 数据库 | 内置 MySQL | Compose 方式自带，不必单独安装 |
其中数据目录最容易忽略。录像文件、会话日志、数据库文件会持续增长，尤其是录像，几台服务器跑一个月下来就能占掉不少磁盘空间。如果系统盘本来就紧张，建议把 VOLUME_DIR 指向单独挂载的数据盘。备份策略至少覆盖两块：MySQL 数据库文件，以及录像和日志目录。这两个恢复不了，审计能力就等于没了。
2. 环境准备：系统、Docker、资源占用和常用命令确认
2.1 配置要求到底怎么判断
Jumpserver 本身对 CPU 的要求不算苛刻，但它内部还跑着 MySQL、Redis、Celery、Koko、Lion 这一堆组件，这些组件一起吃内存和磁盘。我一般按这个标准来评估：
| 场景 | CPU | 内存 | 磁盘说明 |
|---|---|---|---|
| 学习验证 | 2 核 | 4 GB | 系统盘剩余 20 GB 以上即可 |
| 小团队生产 | 4 核 | 8 GB | 数据目录单独挂盘 |
| 资产多、并发高 | 8 核以上 | 16 GB 以上 | 建议评估分布式方案 |
低配机器能不能跑？能跑，但只能当学习环境。判断标准很简单：同时在线会话数上来以后，Web 页面卡不卡、SSH 登录快不快、录像能不能按时生成。如果这些指标开始恶化，不是调参数能解决的，是资源真的不够了。这里不要急着开最大并发去压测，先在小规模下把流程跑通。
2.2 先确认 Docker 和 Docker Compose 版本
很多人在部署过程中卡在“docker-compose: command not found”或者“docker compose 命令不存在”，这两个不是一回事。新版本 Docker 推荐使用 docker compose 插件，老版本则是独立的 docker-compose 二进制。部署前先用下面命令确认：
docker --version docker compose version # 如果没有 docker compose，再试 docker-compose --version如果只装了 docker-ce 而没装 compose 插件，Jumpserver 启动脚本会报错。另外注意，网上很多教程还在写docker-compose，新部署包里可能用的是docker compose，两者参数格式有小差异。遇到 compose 相关报错，先看命令是否存在、版本是否匹配，不要急着改配置文件。这个检查顺序比任何参数调优都优先。
2.3 时区、防火墙、端口冲突一起处理
时区要设置成 Asia/Shanghai，否则录像时间、会话时间和业务日志对不上。排查问题时发现时间差了 8 小时，那基本就是时区没设置。
防火墙要放行 Web 端口（80 或 443）和 SSH 接入端口（2222）。如果堡垒机部署在云服务器上，安全组规则也要同步放行，光改系统防火墙不够。
端口冲突是最隐蔽的坑。Compose 部署会启动自己的 MySQL 和 Redis 容器，如果宿主机上已经装了 MySQL 占用 3306，或者 Redis 占用 6379，容器会起不来或者启动后反复重启。同一条命令里，如果 Web 端口 80 已经被 Nginx 占用，网站页面会一直打不开。准备环境时先检查这些端口：
ss -tlnp | grep -E ':(80|443|2222|3306|6379)\b'发现占用后，要么停掉旧服务，要么在 .env 里修改 Jumpserver 的对外端口。注意 MySQL 和 Redis 的容器端口一般保持内部使用，优先改宿主机的 Web 端口和 SSH 端口。
3. Docker Compose 部署 Jumpserver 完整流程
3.1 获取官方部署包
先到 Jumpserver 官方 releases 页面下载 docker-compose 部署包，不要从第三方博客或个人仓库下载。下载后解压到 /opt 目录下：
cd /opt # 文件名以你下载到的实际文件为准 tar xf jumpserver-docker-compose-xxx.tar.gz cd jumpserver-docker-compose-xxx ls -la正常解压后，目录里应该能看到 docker-compose.yml、.env 示例文件、jmsctl.sh 管理脚本等。如果你看到的文件结构和官方文档对不上，先停下来，确认下载的版本是否正确。
3.2 修改 .env 核心参数
部署包通常自带一个 .env 示例文件，复制一份作为正式配置：
cp config.example.txt .env下面这些参数是部署时最需要关注的：
| 参数 | 作用 | 说明 |
|---|---|---|
| VOLUME_DIR | 数据目录 | 改成独立数据盘路径，不要放系统盘 |
| SECRET_KEY | 加密密钥 | 首次安装生成后，升级时不能随意改 |
| BOOTSTRAP_TOKEN | 组件间认证 Token | 各组件靠它互相认证，同样不能随意改 |
| MYSQL_DB | 数据库名 | 内置 MySQL 使用 |
| MYSQL_USER | 数据库用户 | 内置 MySQL 使用 |
| MYSQL_PASSWORD | 数据库密码 | 如果手动修改，注意和 MySQL 容器初始化保持一致 |
| REDIS_PASSWORD | Redis 密码 | 同上，改了要保证组件能连上 |
| HTTP_PORT | Web 端口 | 默认 80，可按需修改 |
| SSH_PORT | SSH 接入端口 | 默认 2222，可按需修改 |
这里重点强调 SECRET_KEY 和 BOOTSTRAP_TOKEN。很多新手喜欢每次部署都重新生成一遍，觉得这样更安全。但对于已经运行过的环境，这两个值一旦变化，core、koko、celery 这些组件之间的认证会全部失败，最直观的表现就是组件状态一直不健康。第一次安装用自动生成的值没问题，但要把它记到内部维护文档里，升级和迁移时保持一致。
3.3 安装并启动服务
配置文件改好后，执行安装和启动：
./jmsctl.sh install ./jmsctl.sh start ./jmsctl.sh statusinstall 会做容器初始化、创建数据目录、生成默认密码。start 之后不要急着打开浏览器，先看 status 的输出，确认所有组件都处于 healthy 状态。再用 docker compose 查看容器列表：
docker compose ps正常情况下，容器组会包含 nginx、core、koko、lion、magnus、celery、web、redis、mysql 这一组。看到全部 up 且没有 restarting，才算基本正常。只要有一个容器反复重启，就先停下来查日志，不要继续往下配。
3.4 创建管理员账号并登录
服务起来以后，在浏览器访问 http://服务器IP，首次访问会引导你创建管理员账号和密码。创建完成后建议立即开启 MFA 动态口令，尤其是生产环境。管理员账号登录后第一件事不是添加资产，而是去“设置”里看组件状态，确认 koko、lion、magnus 这些组件都正常注册。组件不注册，后面 Web 终端和 SSH 接入都会出问题。
创建管理员这一步有个细节：密码策略。Jumpserver 对密码有复杂度要求，如果设置完提示密码强度不够，按提示组合大小写字母、数字和特殊字符即可。不要为了好记而把密码设置得太简单，堡垒机本身是安全设备，它的管理密码反而是最容易被人忽略的薄弱点。
4. 首次登录后的核心配置：用户、资产、系统用户和授权规则
4.1 创建用户并理解登录方式
登录堡垒机之后，第一个要建的是用户。可以先创建一个测试用户，不要一直拿 admin 去连生产服务器。用户创建时要注意：
- 用户来源：本地用户、LDAP、AD 等。中小团队本地用户就够了，企业级可以对接统一认证。
- 登录方式：密码、SSH Key、MFA。SSH Key 更安全，但要维护好私钥。
- 用户状态：新建用户默认启用，如果有 H3 状态异常，先看这里。
这里有一个常见误区：堡垒机的“用户”和你要登录的目标服务器上的“系统用户”不是一回事。堡垒机用户是运维人员的账号，系统用户是目标机器上真实存在的账号，比如 root 或者普通运维账号。Jumpserver 通过授权规则把这两者关联起来。
4.2 添加 Linux 资产
在资产管理里点击创建资产，填写以下核心信息：
- IP 地址：目标服务器的 IP 或主机名。
- 协议：选 SSH。
- 端口：目标服务器上的 SSH 端口，默认 22。这里的端口不是堡垒机的 2222，初学者经常搞混。
- 系统用户：选择或创建目标服务器上的账号。可以手动录入密码或上传 SSH Key，也可以配置自动推送。
自动推送的价值在于：不需要提前在每台服务器上手工创建账号，Jumpserver 会选择合适的时机把系统用户和密钥推送到目标机器。但自动推送依赖网络连通和账号权限，建议先在单台机器上验证推送成功，再批量操作。不要一上来就全选服务器，否则一堆失败任务会让你不知道怎么排查。
4.3 配置授权规则
授权规则是整个权限体系的核心。一个完整的授权由三个维度组成：
- 用户：谁能用。
- 资产：能用哪台机器。
- 系统用户：以什么身份登录。
创建授权规则时，把测试用户、测试资产、目标系统用户绑定在一起，设置生效时间。这里最容易犯的错误是：资产和用户都建好了，但登录时提示没有权限。十有八九是授权规则没配，或者系统用户选成了堡垒机用户。登录机制其实很简单：堡垒机先验证运维人员的账号，再按照授权规则找到对应的系统用户，最后替你登录到目标服务器上。任何一环没对应上，都登录不进。
4.4 验证两条登录链路
配置完成后，要同时验证 Web 终端和 SSH 客户端两条链路。
Web 终端验证：在资产列表里点击连接，如果浏览器能弹出终端并出现目标机器的提示符，说明 Web 链路通了。
SSH 客户端验证：
ssh -p 2222 用户名@堡垒机IP登录后如果是多资产用户，会看到资产选择列表，选择资产后进入目标机器。判断标准是：两条链路都能正常登录，并且在“会话管理”里能看到活动会话。如果只有 Web 通而 SSH 不通，优先查防火墙是否放行 2222 端口，再确认堡垒机的 SSH 接入端口是否配置正确。
注意：这里不要急着把所有资产和用户都导进去。先用一条授权、一台资产、一个用户把链路跑通，再进入批量阶段。
5. 审计能力实测：录像回放、命令记录和命令过滤
5.1 录像回放怎么看
Jumpserver 的审计能力最直观的体现是会话录像。在“会话管理 - 会话记录”里能找到历史会话，点击回放即可看到当时的操作画面。检查录像是否完整有个简单方法：打开后拖动进度条，如果能从头播放到结束，说明录像完整；如果只有开头没有结尾，或者播放到一半卡住，说明会话异常中断或录像组件出了问题。
录像出现问题通常集中在三块：
- 磁盘空间不够，录像写不进去。
- Koko 组件异常，会话没有正常录制。
- 录像文件被第三方工具清理，但数据库记录还在。
所以部署完成后，我建议专门做一轮“审计验证”：用测试账号登录一台测试服务器，随便执行几条命令，退出后去会话记录里确认录像是否生成。这一步一定要做，不要等出了安全事故才想起来翻录像，结果发现根本没录上。
5.2 命令记录和命令过滤
除了录像，命令记录是另一个重要的审计维度。在会话详情里可以看到用户执行过的每一条命令，这比录像更容易检索。比如要确认是否有人执行过危险命令，直接搜索关键字就行。
命令过滤功能可以设置高危命令黑名单，比如 userdel、iptables -F、rm -rf 这类。配置时要注意边界：过滤规则如果设置得太宽，会把正常运维操作也拦住。建议先用“记录模式”运行一段时间，观察实际运维中哪些命令频繁出现、哪些真正高危，再启用拦截。另一个原则是：拦截规则要能解释、能回溯，不能说某个命令今天突然被禁了，运维同事还不知道为什么。
5.3 审计日志的保存周期
录像和命令记录会持续占用磁盘。保存周期取决于你的合规要求和存储成本：
- 最小要求：至少覆盖最近 3 个月的录像。
- 常见做法：半年到一年，超出周期做归档或删除。
- 合规严格的环境：可能需要更长时间，同时要求归档文件不可篡改。
建议提前设计好目录结构和归档策略。比如每月把上个月的录像打包归档到对象存储或独立备份盘，Jumpserver 的数据目录里只保留最近一个月的数据。这样既能控制磁盘占用，又能满足追溯需求。没有归档策略的话，时间一长磁盘必然爆掉。
6. 常见报错与排查链路
6.1 组件状态不健康怎么办
Jumpserver 页面里会显示核心组件状态，如果不健康，按下面的顺序排查：
- 先执行 docker compose ps，看哪个容器处于 not healthy 或 restarting 状态。
- 再执行 docker compose logs 查看具体容器日志，core 和 celery 的日志信息量最大。
- 确认为什么组件之间连不上：最常见的是 MySQL 或 Redis 密码不一致。
- 检查 .env 里的数据库密码、Redis 密码和容器实际初始化值是否一致。
这里有个高频场景：手动修改了 .env 里的 MYSQL_PASSWORD，但 MySQL 容器里的实际密码没有同步修改，导致 core 组件连接数据库失败，组件一直 unhealthy。先别急着重置数据，优先确认密码一致性。
如果容器全部正常但组件仍不健康，再查网络和卷目录权限。卷目录权限不够会导致 MySQL 初始化失败，容器虽然启动了但数据写不进去。遇到这种问题看日志比猜快得多。
6.2 Web 终端打不开或一直转圈
Web 终端依赖 koko 组件，koko 负责把浏览器里的终端请求转发到目标服务器。koko 状态异常时，页面会一直转圈或者提示连接失败。排查链路：
- 先看 koko 容器日志，确认它是否正常注册到核心组件。
- 再看目标服务器 SSH 服务是否开启，比如 systemctl status sshd。
- 确认堡垒机到目标服务器的网络通不通。
- 检查系统用户登录方式：如果目标服务器禁用了密码登录，但授权规则里选的是密码认证，就会登录失败。
还有一个隐蔽问题：目标服务器的 SSH 端口不是默认的 22，但你在资产里忘了改，导致连接超时。这类问题和堡垒机本身关系不大，但误判率极高。遇到连接失败，先确认资产配置里的 IP、端口、协议、系统用户四项，再考虑是不是堡垒机故障。
6.3 登录失败和管理问题
用户反馈“登录不上堡垒机”时，按这些方向排查：
- 用户是否被禁用。
- 密码是否过期。
- MFA 动态口令是否同步，手机时间和服务端时间差太多会导致验签失败。
- 如果对接了 LDAP，还要确认 LDAP 服务和网络连通。
时间不同步是最容易被忽视的。用户绑定 MFA 之后登录一直提示验证码错误，但手机上的时间比服务器慢了几十秒，改完时间就恢复了。建议在服务器上配置 NTP 时间同步，堡垒机和手机令牌都依赖准确时间。
6.4 升级和数据恢复的坑
升级前必须备份三样东西：.env 配置文件、MySQL 数据库、录像目录。使用 jmsctl.sh upgrade 之前，先读官方升级文档。跨大版本升级尤其要谨慎，先备份，再在测试机上演练一遍。生产环境直接升级出问题的话，重启服务不一定能解决，可能需要回滚。
恢复数据库时，先停止核心服务，避免写入冲突。恢复完成后启动服务，再到会话记录里抽查录像是否能正常播放。如果录像打不开，说明录像目录和数据库记录对不上，通常是目录路径配置错误导致。
7. 生产环境落地后的几点经验和长期维护建议
7.1 备份恢复要真的演练一次
每周备份但从不恢复，等于没有备份。找一台测试机，把数据库 dump 和录像目录完整恢复一遍，确认服务能起来、录像能播放、授权规则还在。这个过程花不了多少时间，但它能暴露很多问题：备份文件不完整、恢复脚本路径写死、录像目录恢复后权限不对。真正出故障时你才有把握。
7.2 长期使用要盯的指标
堡垒机跑起来之后，日常维护关注这几个指标：
- 磁盘使用率：录像和日志增长最快，建议监控并设置告警。
- 组件健康状态：定时检查，组件挂掉要能及时发现。
- MySQL 连接数和慢查询：会话多起来后数据库压力会上升。
- HTTPS 证书有效期：Web 服务用 HTTPS 的话，证书到期前要提前替换。
- 会话高峰时段的登录耗时：如果明显变慢，说明资源可能要扩容了。
这些指标不需要等到出问题再看，最好在部署时就整理成一张检查清单，每周或每月过一遍。
7.3 接入更多资产前的规划
当资产数量从几台增长到几百台时，提前做好规划能让后续维护顺手很多：
- 统一系统用户命名规范，比如 operator、deploy 这类账号要按业务线区分。
- 资产按业务线分组，授权规则跟着组走，而不是给每个用户单独配资产。
- 定期清理离职人员的授权，撤销账号或禁用状态。
- 高危命令过滤规则保持“可解释、可回溯”，每次调整都记录原因。
Jumpserver 部署本身并不复杂，真正的复杂度在后续的权限管理和审计数据维护上。很多问题不是工具能力不够，而是前置环境没准备好，或者授权规则没有按业务线整理清楚。如果你刚开始接触，先把单机版从安装跑到录像回放，确认链路完整，再研究分布式、自动推送和更细粒度的合规配置。把基础链路稳住，后续扩展就不会手忙脚乱。
