项目介绍
Emby Toolkit 用于管理 Emby 媒体库和相关任务。下文提供旧版 Emby Toolkit 与 PostgreSQL 的完整部署步骤。旧版项目已归档,后续开发迁往 ETKvNext;两者的数据结构和安装方式需要分别对照,不能直接共用数据库。
version: '3.8'
services:
# --- 1. Emby-Toolkit 主程序 ---
emby-toolkit:
image: hbq0405/emby-toolkit:latest
container_name: emby-toolkit
network_mode: bridge # 网络模式
ports:
- "5257:5257" # 管理端口
- "8097:8097" # 反代端口,虚拟库用,冒号前面是实际访问端口,冒号后面是管理后台设置的反代监听端口
volumes:
- /path/emby-toolkit:/config # 将宿主机的数据目录挂载到容器的 /config 目录
- /path/tmdb:/tmdb # 映射神医本地TMDB目录,非神医Pro用户可以留空
- /var/run/docker.sock:/var/run/docker.sock # 一键更新用,不需要可以不配置
environment:
- APP_DATA_DIR=/config # 持久化目录
- TZ=Asia/Shanghai # 设置容器时区
- AUTH_USERNAME=admin # 用户名可任意设置,密码在程序首次运行会生成初始密码:请设置自己的密码
- PUID=1000 # 设置为你的用户ID,建议与宿主机用户ID保持一致
- PGID=1000 # 设置为DOCKER组ID (一键更新用,‘grep docker /etc/group’可以查询)
- UMASK=022 # 设置文件权限掩码,建议022
- DB_HOST=172.17.0.1 # 数据库服务的地址
- DB_PORT=5433 # 数据库服务的端口
- DB_USER=请设置自己的密码 # !!! (可选) 修改为你自己的数据库用户名
- DB_PASSWORD=请设置自己的密码 # !!! (必填) 请修改为一个强密码 !!!
- DB_NAME=请设置自己的密码 # !!! (可选) 修改为你自己的数据库名
- CONTAINER_NAME=emby-toolkit # 以下两项都是一键更新用,不需要可以不配置
- DOCKER_IMAGE_NAME=hbq0405/emby-toolkit:latest
restart: unless-stopped
depends_on: # 确保主程序只在数据库健康检查通过后才启动
db:
condition: service_healthy
# --- 2. PostgreSQL 数据库服务 ---
db:
image: postgres:16-alpine
container_name: emby-toolkit-db
restart: unless-stopped
network_mode: bridge
volumes:
# 将数据库的持久化数据存储在名为 'postgres_data' 的Docker卷中
# 这可以确保即使删除了容器,数据库数据也不会丢失
- postgres_data:/var/lib/postgresql/data
environment:
# --- 数据库认证配置 (核心) ---
# 这些值必须与上面的 'emby-toolkit' 服务中的环境变量完全匹配
- POSTGRES_USER=请设置自己的密码 # !!! (可选) 修改,与上面保持一致
- POSTGRES_PASSWORD=请设置自己的密码 # !!! (必填) 修改,与上面保持一致 !!!
- POSTGRES_DB=请设置自己的密码 # !!! (可选) 修改,与上面保持一致
ports:
# 将数据库端口映射到宿主机,方便使用Navicat等工具连接调试
- "5433:5432"
healthcheck:
# 健康检查,确保数据库服务已准备好接受连接
test: ["CMD-SHELL", "pg_isready -U 请设置自己的密码 -d 请设置自己的密码"]
interval: 10s
timeout: 5s
retries: 5
volumes:
postgres_data: # 创建一个Docker卷持久化保存数据库数据项目地址:
https://github.com/hbq0405/emby-toolkit
补充:部署与使用
群晖 Compose 安装
本节对应你原参考中的 Emby ToolKit 旧版。上游已归档,并将后续开发迁往 ETKvNext;这里保留旧版双服务部署供原教程复现,不把旧版容器当作新版,旧库也不能直接交给新版容器迁移。
1. 创建项目目录
群晖先安装并启动 Container Manager。通过 SSH 登录后执行下列命令,只为本项目准备目录:
sudo -i
mkdir -p /volume1/docker/emby-toolkit /volume1/docker/emby-toolkit/config /volume1/docker/emby-toolkit/postgres
cd /volume1/docker/emby-toolkit
if [ ! -s .env ]; then
umask 077
{
printf 'ETK_DB_PASSWORD=%s\n' "$(openssl rand -hex 24)"
} > .env.initializing
mv .env.initializing .env
fi
chmod 600 .env
cat .env
.env 中的密码和密钥由命令随机生成,已有文件不会覆盖。可以在自己的终端用 cat .env 查看初始密码,但不要将输出公开。将其保存在自己的密码管理器中;更新时继续使用原值,不要重新生成导致旧数据无法解密。
2. 保存完整 Compose
在 /volume1/docker/emby-toolkit/compose.yaml 保存下面的配置。在 Container Manager 中新建项目时,项目路径选择 /volume1/docker/emby-toolkit 并导入该文件;有 .env 的项目要保留它与 Compose 在同一目录。
services:
emby-toolkit:
image: hbq0405/emby-toolkit:latest
container_name: emby-toolkit
restart: unless-stopped
ports:
- 5257:5257
- 8097:8097
volumes:
- /volume1/docker/emby-toolkit/config:/config
environment:
APP_DATA_DIR: /config
TZ: Asia/Shanghai
DB_HOST: db
DB_PORT: '5432'
DB_USER: 请设置自己的密码
DB_NAME: 请设置自己的密码
PUID: '0'
PGID: '0'
UMASK: '022'
DB_PASSWORD: ${ETK_DB_PASSWORD}
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: 请设置自己的密码
POSTGRES_DB: 请设置自己的密码
POSTGRES_PASSWORD: ${ETK_DB_PASSWORD}
volumes:
- /volume1/docker/emby-toolkit/postgres:/var/lib/postgresql/data
healthcheck:
test:
- CMD-SHELL
- pg_isready -U 请设置自己的密码 -d 请设置自己的密码
interval: 10s
timeout: 5s
retries: 10
挂载参数冒号左侧是群晖的实际目录,右侧是应用内目录。以上只挂载本项目所需的数据;若已有同类数据,请先备份再调整路径。端口冲突时只改宿主机一侧,应用内端口保持不变。
3. 检查、拉取与启动
cd /volume1/docker/emby-toolkit
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100
浏览器访问 http://群晖IP:5257。群晖IP 替换为自己的 NAS 局域网地址;首次启动时先等待初始化,再检查日志。若群晖仍使用旧 Docker 套件且只有 docker-compose,将命令中的 docker compose 替换为对应命令。
首次使用与验证
访问 5257 管理页完成初始化,配置自己的 Emby、网盘与资料服务。虚拟库需要在后台确认反代监听端口 8097。先处理一个小目录;旧版与新版不同时操作同一批媒体。
先保存一条测试数据或完成一次最小任务,再执行 docker compose restart,确认设置及应该持久化的数据仍在。无服务端持久化目录的纯前端工具,应通过自身导出功能保存工作结果。
常见问题
- 页面打不开:运行
docker compose ps检查状态;查看日志里的初始化错误,核对端口冲突和 DSM 防火墙。不要把容器的 IP 当作固定访问地址。 - 数据目录为空:应用内应填写 Compose 冒号右侧的目录;核对宿主机文件是否已放到对应左侧目录。
- 目录无法写入:先查看日志和目录权限,仅为对应数据目录授予镜像实际运行用户需要的权限,不对整个
/volume1设置 777。 - 拉取镜像失败:先排查 Container Manager 的仓库网络;应用自己的 HTTP 代理设置与 Docker 守护进程拉取镜像的代理设置是两件事。
更新、备份与停止
更新前保存 compose.yaml、.env,并备份上面映射的项目数据。数据库服务应先使用自身的数据库备份,或停止整个项目后复制完整数据目录,不能只复制运行中的单个数据库文件。
cd /volume1/docker/emby-toolkit
docker compose pull
docker compose up -d
docker compose logs --tail=100
临时停止使用 docker compose stop,重新启动使用 docker compose start。卸载容器用 docker compose down,不要附加 -v,也不要直接删除宿主机数据目录。涉及数据库迁移的升级,先保留原镜像版本和完整备份,再安排维护窗口。