自建家庭数据中心：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 目录，推荐三种传输方式：

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

四、常用运维命令汇总

五、踩坑总结

六、参考链接

• 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