Helm部署JumpServer完全实战指南
背景
JumpServer 是开源的堡垒机系统,支持通过 Helm 部署到 Kubernetes 集群。本文覆盖 v2.x 和 v4.x 两个主要版本的部署流程,以及 HTTPS 证书配置。
版本选择建议:
| 特性 | v2.x(如 v2.26.1) | v4.x(如 v4.10.16) |
|---|---|---|
| SAML2 认证 | 社区版支持 | 企业版(X-Pack) |
| OIDC/OAuth2 | 社区版支持 | 企业版(X-Pack) |
| CAS/LDAP | 支持 | 支持 |
| 飞书/钉钉/企微 | 社区版支持 | 企业版(X-Pack) |
如果需要 SAML2/OIDC 单点登录且无企业版 License,选 v2.x。
前提条件
- Kubernetes 1.20+
- Helm 3.0+
- Ingress Controller(如 nginx-ingress)
- 支持 ReadWriteMany 的 StorageClass(如 NAS/NFS/CephFS)
- 支持 ReadWriteOnce 的 StorageClass(如云盘,用于 MySQL)
1. 公共准备工作
1.1 添加 Helm 仓库
helm repo add jumpserver https://jumpserver.github.io/helm-charts
helm repo update jumpserver
1.2 创建 Namespace
kubectl create ns jumpserver
1.3 生成密钥
安装后不可更改,务必保存好:
# secretKey(50位)
cat /dev/urandom | LC_ALL=C tr -dc A-Za-z0-9 | head -c 50
# bootstrapToken(24位)
cat /dev/urandom | LC_ALL=C tr -dc A-Za-z0-9 | head -c 24
1.4 部署 MySQL
JumpServer 的 Helm Chart 不内置数据库,需要自行部署。
# jumpserver-mysql.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: jms-mysql
namespace: jumpserver
spec:
replicas: 1
selector:
matchLabels:
app: jms-mysql
template:
metadata:
labels:
app: jms-mysql
spec:
containers:
- name: mysql
image: docker.m.daocloud.io/library/mysql:8.0 # 国内集群用 daocloud 代理
env:
- name: MYSQL_ROOT_PASSWORD
value: "YourRootPassword"
- name: MYSQL_DATABASE
value: "jumpserver"
- name: MYSQL_USER
value: "jumpserver"
- name: MYSQL_PASSWORD
value: "YourDBPassword"
ports:
- containerPort: 3306
args:
- "--character-set-server=utf8mb4"
- "--collation-server=utf8mb4_unicode_ci"
volumeMounts:
- name: mysql-data
mountPath: /var/lib/mysql
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 2000m
memory: 2Gi
volumes:
- name: mysql-data
persistentVolumeClaim:
claimName: jms-mysql-data
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: jms-mysql-data
namespace: jumpserver
spec:
accessModes:
- ReadWriteOnce
storageClassName: alicloud-disk-essd # 按集群实际 SC 修改
resources:
requests:
storage: 50Gi
---
apiVersion: v1
kind: Service
metadata:
name: jms-mysql
namespace: jumpserver
spec:
selector:
app: jms-mysql
ports:
- port: 3306
targetPort: 3306
1.5 部署 Redis
# jumpserver-redis.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: jms-redis
namespace: jumpserver
spec:
replicas: 1
selector:
matchLabels:
app: jms-redis
template:
metadata:
labels:
app: jms-redis
spec:
containers:
- name: redis
image: docker.m.daocloud.io/library/redis:7.0
command: ["redis-server", "--requirepass", "YourRedisPassword"]
ports:
- containerPort: 6379
resources:
requests:
cpu: 200m
memory: 256Mi
limits:
cpu: 1000m
memory: 1Gi
---
apiVersion: v1
kind: Service
metadata:
name: jms-redis
namespace: jumpserver
spec:
selector:
app: jms-redis
ports:
- port: 6379
targetPort: 6379
部署并等待就绪:
kubectl apply -f jumpserver-mysql.yaml
kubectl apply -f jumpserver-redis.yaml
kubectl rollout status deployment/jms-mysql -n jumpserver --timeout=120s
kubectl rollout status deployment/jms-redis -n jumpserver --timeout=120s
镜像拉取注意:国内集群无法直连 Docker Hub,需将镜像前缀改为
docker.m.daocloud.io/library/。可通过查看集群已有 Pod 使用的 registry 来确认可用的代理地址。
2. 部署 JumpServer v2.26.1(社区版含 SAML2)
2.1 创建 values.yaml
# jumpserver-values-v2.yaml
global:
imageRegistry: docker.m.daocloud.io # 国内镜像代理
imageTag: v2.26.1
storageClass: "alibabacloud-cnfs-nas" # 支持 RWX 的 SC
externalDatabase:
engine: mysql
host: jms-mysql.jumpserver.svc.cluster.local
port: 3306
user: root
password: "YourRootPassword"
database: jumpserver
externalRedis:
host: jms-redis.jumpserver.svc.cluster.local
port: 6379
password: "YourRedisPassword"
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: nginx
nginx.ingress.kubernetes.io/proxy-body-size: "4096m"
nginx.ingress.kubernetes.io/configuration-snippet: |
proxy_set_header Upgrade "websocket";
proxy_set_header Connection "Upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
hosts:
- "jms.example.com"
core:
enabled: true
config:
secretKey: "<你生成的50位密钥>"
bootstrapToken: "<你生成的24位Token>"
debug: false
log:
level: ERROR
replicaCount: 1
env:
SESSION_EXPIRE_AT_BROWSER_CLOSE: true
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 50Gi
koko:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
lion:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
magnus:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
web:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 1Gi
xpack:
enabled: false
2.2 安装
helm install jms-k8s jumpserver/jumpserver --version 2.26.1 -n jumpserver -f jumpserver-values-v2.yaml
2.3 验证
kubectl get pods -n jumpserver
所有 pod 状态为 Running 即部署成功。默认账号 admin / admin。
3. 部署 JumpServer v4.x(最新版)
3.1 创建 values.yaml
v4 相比 v2 的变化:
global.imageTag改为global.imageOwner- 新增
chen、kael组件 - 移除
magnus的 oracle 端口 - Ingress annotation 使用
server-snippets代替configuration-snippet - 数据库默认引擎改为 PostgreSQL(仍支持 MySQL)
# jumpserver-values-v4.yaml
global:
imageRegistry: docker.m.daocloud.io
imageOwner: jumpserver
storageClass: "alibabacloud-cnfs-nas"
externalDatabase:
engine: mysql
host: jms-mysql.jumpserver.svc.cluster.local
port: 3306
user: root
password: "YourRootPassword"
database: jumpserver
externalRedis:
host: jms-redis.jumpserver.svc.cluster.local
port: 6379
password: "YourRedisPassword"
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: nginx
nginx.ingress.kubernetes.io/proxy-body-size: "4096m"
nginx.ingress.kubernetes.io/server-snippets: |
proxy_set_header Upgrade "websocket";
proxy_set_header Connection "Upgrade";
hosts:
- "jms.example.com"
core:
enabled: true
config:
secretKey: "<你生成的50位密钥>"
bootstrapToken: "<你生成的24位Token>"
debug: false
log:
level: ERROR
replicaCount: 1
env:
SESSION_EXPIRE_AT_BROWSER_CLOSE: true
DOMAINS: "jms.example.com"
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 50Gi
koko:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
lion:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
magnus:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
chen:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
kael:
enabled: true
replicaCount: 1
persistence:
storageClassName: alibabacloud-cnfs-nas
accessModes:
- ReadWriteMany
size: 10Gi
web:
enabled: true
replicaCount: 1
xpack:
enabled: false # 设为 true 可开启企业版功能(SAML2/OIDC等)
3.2 安装
helm install jms-k8s jumpserver/jumpserver -n jumpserver -f jumpserver-values-v4.yaml
默认账号 admin / ChangeMe。
4. 配置 HTTPS
4.1 准备证书 Secret
如果集群中已有证书(如其他 namespace),可以复制过来:
# 从其他 namespace 复制证书
kubectl get secret diezhi.net -n blueking -o yaml \
| sed 's/namespace: blueking/namespace: jumpserver/' \
| kubectl apply -n jumpserver -f -
如果需要新建证书 Secret:
kubectl create secret tls jms-tls \
--cert=./fullchain.pem \
--key=./privkey.pem \
-n jumpserver
4.2 配置 Ingress TLS
方式一:通过 helm upgrade 添加
helm upgrade jms-k8s jumpserver/jumpserver --version <版本号> \
-n jumpserver -f jumpserver-values.yaml \
--set 'ingress.tls[0].secretName=diezhi.net' \
--set 'ingress.tls[0].hosts[0]=jms.example.com'
方式二:直接在 values.yaml 中配置
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: nginx
nginx.ingress.kubernetes.io/proxy-body-size: "4096m"
nginx.ingress.kubernetes.io/ssl-redirect: "true"
nginx.ingress.kubernetes.io/configuration-snippet: |
proxy_set_header Upgrade "websocket";
proxy_set_header Connection "Upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
hosts:
- "jms.example.com"
tls:
- secretName: diezhi.net
hosts:
- jms.example.com
然后执行:
helm upgrade jms-k8s jumpserver/jumpserver --version <版本号> -n jumpserver -f jumpserver-values.yaml
4.3 验证 HTTPS
kubectl get ingress -n jumpserver
# PORTS 列应显示 80, 443
浏览器访问 https://jms.example.com 确认证书生效。
5. 常用运维操作
查看部署状态
helm list -n jumpserver
kubectl get pods -n jumpserver
查看日志
kubectl logs -f deploy/jms-k8s-jumpserver-jms-core -n jumpserver
完全卸载
helm uninstall jms-k8s -n jumpserver
# 清理残留 PVC
kubectl delete pvc -l app.kubernetes.io/instance=jms-k8s -n jumpserver
# 清理 MySQL/Redis
kubectl delete -f jumpserver-mysql.yaml
kubectl delete -f jumpserver-redis.yaml
kubectl delete ns jumpserver
6. 常见问题
镜像拉取失败(ImagePullBackOff)
国内集群无法访问 Docker Hub,解决方案:
- 将
global.imageRegistry改为docker.m.daocloud.io - MySQL/Redis 镜像前缀加
docker.m.daocloud.io/library/
PVC 绑定失败
确认 StorageClass 存在且支持对应的 accessMode:
- JumpServer 组件需要
ReadWriteMany(NAS/NFS) - MySQL 使用
ReadWriteOnce(云盘即可)
v4 社区版没有 SAML2/OIDC
JumpServer v3 开始,SAML2、OIDC、OAuth2 移至企业版(X-Pack)。解决方案:
- 降级到 v2.x(社区版原生支持)
- 购买企业版 License
- 使用 CAS 协议替代(社区版支持)
secretKey 和 bootstrapToken
- 安装前必须生成并填写
- 安装后不可更改,否则已有数据无法解密
- 多次部署(如卸载重装)必须使用相同的 key