自建家庭数据中心：Docker 部署 Immich + Jellyfin 全流程与踩坑实录- 惊觉

前言

在云服务会员费逐年上涨、数据隐私顾虑增加的当下，自建本地相册与影音服务器成为越来越多技术爱好者的选择。本文记录了在 Ubuntu Server 上通过 Docker 部署 Immich（智能相册）与 Jellyfin（影音流媒体）两套服务的完整过程，包含从网络排错到密码重置、硬件加速开启的全部真实踩坑经验，全程可复现。

Immich：对标 Google Photos 的自托管照片备份方案，支持人脸/语义搜索、多端自动备份、RAW 格式支持
Jellyfin：开源影音流媒体服务器，支持多终端播放、硬件转码、元数据自动刮削
硬件环境：Ubuntu 26.04 Server + NVIDIA GTX 1650 Mobile（支持 CUDA/NVENC 硬件加速）

一、前置环境准备

服务器基础环境已配置完成：

操作系统：Ubuntu 26.04 Server
Docker 与 Docker Compose 已安装
NVIDIA 显卡驱动 + nvidia-container-toolkit 已配置（用于 GPU 硬件加速）
服务器内网 IP：192.168.1.7
内网环境关闭系统防火墙（ufw inactive）

二、Immich 智能相册部署与访问排坑

2.1 基础部署

创建部署目录并编写 docker-compose.yml，包含核心服务、向量数据库与 Redis 缓存：

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:v3.2.2
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - 2283:2283
    depends_on:
      - redis
      - immich-db
    restart: always

  redis:
    container_name: immich_redis
    image: docker.io/redis:6.2-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      start_period: 10s
      timeout: 5s
      retries: 5
    volumes:
      - redis-data:/data
    restart: always

  immich-db:
    container_name: immich_postgres
    image: tensorchord/pgvecto-rs:pg14-v0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

volumes:
  pgdata:
  redis-data:

配套 .env 文件配置基础参数后，启动服务：

docker compose up -d

2.2 浏览器无法访问的完整排查流程

服务启动后，Chrome 浏览器访问 http://192.168.1.7:2283 报错 ERR_ADDRESS_UNREACHABLE，这是内网服务部署最常见的问题，按以下层级逐步定位：

第一步：确认服务与端口监听

在服务器本机执行，优先排除容器启动失败：

# 查看容器运行状态
docker compose ps
# 查看端口映射情况
docker port immich-server
# 服务器本机 curl 验证页面返回
curl http://127.0.0.1:2283

结果：容器状态 healthy，端口映射 0.0.0.0:2283，curl 能正常返回完整 HTML 页面 → 服务本身完全正常。

第二步：网络连通性验证

在客户端（Mac）执行网络层与传输层测试：

# 测试 IP 层可达性
ping 192.168.1.7
# 测试 TCP 端口连通性
nc -zv 192.168.1.7 2283

结果：ping 丢包率 0%，端口连接成功 → 网络层与传输层均无问题。

第三步：定位问题根源

既然 IP、端口、服务都正常，问题锁定在浏览器应用层。

原因：Chrome 的代理插件、Service Worker 缓存或安全策略拦截了内网静态资源加载，导致 HTML 骨架返回但 JS 资源加载失败，最终渲染为“无法访问”。
解决方案：使用 Safari 无痕模式直接访问，页面正常加载；Chrome 可通过清除站点数据、关闭代理插件解决。

💡 避坑提示：内网服务访问优先使用系统原生浏览器，排除第三方插件与代理干扰，能节省大量排查时间。

2.3 可选：AI 智能识别服务

日志中出现 Machine learning server became unhealthy 是因为缺少机器学习容器，该服务负责人脸识别、语义搜索，不影响基础照片备份功能。如需开启，在 compose 中追加 immich-machine-learning 服务并使用 CUDA 镜像即可利用显卡加速。

三、Jellyfin 影音服务器部署

3.1 Docker Compose 配置（含 NVENC 硬件加速）

创建 /opt/jellyfin 目录，编写 docker-compose.yml，直接挂载 NVIDIA 显卡实现硬件转码：

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    user: 1000:1000
    ports:
      - "8096:8096"    # Web 管理与播放端口
      - "7359:7359/udp" # 局域网设备自动发现
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /mnt/media:/media:ro  # 媒体目录，:ro 只读防止服务误删原文件
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,video,utility
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, video]
    restart: unless-stopped

启动服务：

mkdir -p /mnt/media
docker compose up -d

3.2 管理员密码重置方案

初始化后如果忘记管理员密码，直接修改 system.xml 会被服务启动时自动覆写，正确稳定的方案是直接操作 SQLite 数据库：

停止容器，避免数据写入冲突

docker compose down

查询当前管理员用户名

sqlite3 ./config/data/jellyfin.db "SELECT Username,Id FROM Users;"

清空密码与登录失败计数

sqlite3 ./config/data/jellyfin.db "UPDATE Users SET Password=NULL WHERE Username='你的用户名';"
sqlite3 ./config/data/jellyfin.db "UPDATE Users SET InvalidLoginAttemptCount=0 WHERE Username='你的用户名';"

启动容器，使用用户名+空密码登录，登录后立即在个人设置中配置新密码。

3.3 开启 GTX 1650 NVENC 硬件转码

进入后台控制台 → 播放 → 转码，按以下参数配置：

硬件加速选择 NVIDIA NVENC
勾选「启用硬件编码」
硬件解码勾选 H.264、HEVC（GTX 1650 不支持 AV1 硬解，请勿勾选）
开启「硬件色调映射」

播放视频时在服务器执行 nvidia-smi，看到 GPU 编码占用率上升即代表硬解生效。

3.4 媒体文件上传方式

Jellyfin 不支持网页端直接上传视频，需将文件放入服务器 /mnt/media 目录，推荐三种传输方式：

Mac 访达 SFTP：访达 → 前往 → 连接服务器 → 输入 sftp://用户名@192.168.1.7，拖拽即可传输
命令行 scp：适合小文件，命令示例：scp 本地文件路径用户名@192.168.1.7:/mnt/media
FileZilla：适合 4K 大文件批量传输，图形化界面操作直观

文件传输完成后，在 Jellyfin 媒体库点击「扫描所有媒体」即可自动识别并加载元数据。

四、常用运维命令汇总

操作	Immich 命令	Jellyfin 命令
启动服务	`docker compose up -d`	`docker compose up -d`
停止服务	`docker compose down`	`docker compose down`
实时查看日志	`docker compose logs -f immich-server`	`docker compose logs -f jellyfin`
更新镜像	`docker compose pull && docker compose up -d`	`docker compose pull && docker compose up -d`
查看运行状态	`docker compose ps`	`docker compose ps`

五、踩坑总结

ERR_ADDRESS_UNREACHABLE 不等于服务挂了：优先排查网络连通性与浏览器环境，不要盲目重启容器
Jellyfin 密码重置不要改 XML 配置：服务启动会自动覆写配置，直接操作数据库最稳妥
硬件加速不要盲目全开：根据显卡能力勾选解码格式，AV1 硬解需较新显卡支持
内网访问优先排除代理干扰：浏览器插件、系统代理是内网服务访问异常的高频原因

六、参考链接

Immich 官方文档：Immich
Immich GitHub 仓库：GitHub - immich-app/immich: High performance self-hosted photo and video management solution. · GitHub
Jellyfin 官方文档：Introduction | Jellyfin
Jellyfin GitHub 仓库：GitHub - jellyfin/jellyfin: The Free Software Media System - Server Backend & API · GitHub
NVIDIA Docker 安装指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/weixin_66243333/article/details/166645298

自建家庭数据中心：Docker 部署 Immich + Jellyfin 全流程与踩坑实录

前言