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。

前提条件

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 的变化:

# 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,解决方案:

PVC 绑定失败

确认 StorageClass 存在且支持对应的 accessMode:

v4 社区版没有 SAML2/OIDC

JumpServer v3 开始,SAML2、OIDC、OAuth2 移至企业版(X-Pack)。解决方案:

secretKey 和 bootstrapToken