非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

Kubernetes 部署

本指南介绍如何使用官方 Helm chart在 Kubernetes 上部署 Jellyfin。

先决条件

• Kubernetes 集群 (v1.19+)

• 已安装 Helm 3.x

• 已配置集群的 kubectl

• 充足的媒体文件和配置存储空间

• 外部访问所需的 Ingress 控制器（例如 traefik，本教程必需，替代方案参见官方文档）

安装步骤

1. 添加 Helm 仓库

helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
helm repo update

2. 自定义安装

完整安装说明和配置选项请参阅官方 Jellyfin Helm chart 仓库。

创建自定义配置文件 values.yaml：

# values.yaml
replicaCount: 1

image:
  pullPolicy: IfNotPresent

persistence:
  config:
    enabled: true
    size: 5Gi
    storageClass: ''
  media:
    enabled: true
    size: 100Gi
    storageClass: ''

ingress:
  enabled: true
  className: 'traefik'
  hosts:
    - host: jellyfin.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 500m
    memory: 1Gi

nodeSelector: {}
tolerations: []
affinity: {}

使用自定义值安装：

helm install jellyfin jellyfin/jellyfin -f values.yaml

配置选项

服务类型

本指南仅覆盖内部访问的 ClusterIP 服务类型（默认），外部访问通过 Ingress 控制器实现。替代方案包括 LoadBalancer 和 NodePort 服务。

持久化存储

使用现有持久卷声明 (PVC)

persistence:
  config:
    enabled: true
    existingClaim: 'jellyfin-config-pvc'
  media:
    enabled: true
    existingClaim: 'jellyfin-media-pvc'

通过 Helm 创建新 PVC

persistence:
  config:
    enabled: true
    size: 5Gi
    storageClass: 'fast-ssd'
  media:
    enabled: true
    size: 100Gi
    storageClass: 'slow-hdd'

Ingress

基础 Ingress 配置

ingress:
  enabled: true
  className: 'traefik'
  hosts:
    - host: jellyfin.example.com
      paths:
        - path: /
          pathType: Prefix

带 TLS 的高级 Ingress

ingress:
  enabled: true
  className: 'traefik'
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.middlewares: default-jellyfin-buffering@kubernetescrd
  hosts:
    - host: jellyfin.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: jellyfin-tls
      hosts:
        - jellyfin.example.com

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: jellyfin-buffering
  namespace: default
spec:
  buffering:
    maxRequestBodyBytes: 0

访问 Jellyfin

端口转发（开发环境）

kubectl port-forward svc/jellyfin 8096:8096

访问地址：http://localhost:8096

外部访问

配置 Ingress 后，通过设定域名访问 Jellyfin（例如 https://jellyfin.example.com）。

监控

健康检查

该 chart 包含就绪性和存活性探针：

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 5
  periodSeconds: 5

指标监控

启用 Prometheus 指标（如可用）：

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

故障排除

常见问题

1. 权限拒绝：确保为媒体访问配置正确的安全上下文

2. 存储问题：验证持久卷声明是否已绑定

3. 网络访问：检查服务类型和 Ingress 配置

调试命令

# Check pod status
kubectl get pods -l app.kubernetes.io/name=jellyfin

# View logs
kubectl logs -f deployment/jellyfin

# Check service
kubectl get svc jellyfin

# Describe pod for events
kubectl describe pod -l app.kubernetes.io/name=jellyfin

升级

# Update repository
helm repo update

# Upgrade installation
helm upgrade jellyfin jellyfin/jellyfin

# Check upgrade status
helm status jellyfin

卸载

# Remove Helm release
helm uninstall jellyfin

# Clean up persistent volumes (if needed)
kubectl delete pvc -l app.kubernetes.io/name=jellyfin

高级配置

硬件加速

启用 GPU 加速需添加设备访问权限和安全上下文：

securityContext:
  privileged: true

resources:
  limits:
    gpu.intel.com/i915: 1
    # or nvidia.com/gpu: 1

extraVolumes:
  - name: dri
    hostPath:
      path: /dev/dri

extraVolumeMounts:
  - name: dri
    mountPath: /dev/dri

多媒体源

通过附加卷挂载多个媒体源：

volumes:
  - name: movies
    persistentVolumeClaim:
      claimName: movies-pvc
  - name: tv
    persistentVolumeClaim:
      claimName: tv-pvc

volumeMounts:
  - name: movies
    mountPath: /movies
  - name: tv
    mountPath: /tv

自定义环境变量

extraEnvVars:
  - name: JELLYFIN_PublishedServerUrl
    value: 'https://jellyfin.example.com'
  - name: JELLYFIN_CACHE_DIR
    value: '/cache'

更多配置选项请参阅 Jellyfin Helm chart 文档。