$ mkdir -p /opt/kyoo && cd /opt/kyoo
$ wget -q https://github.com/zoriya/kyoo/releases/latest/download/docker-compose.yml
$ wget -q -O .env.example https://github.com/zoriya/kyoo/releases/latest/download/env.example
$ ls -l
total 20
-rw-r--r-- 1 root root 6110 Oct 29 01:04 docker-compose.yml
-rw-r--r-- 1 root root 4854 Oct 29 01:04 .env.example

$ cp .env.example .env

# 媒体库根目录（相对路径则相对 docker-compose.yml 所在目录）
LIBRARY_ROOT=./video
# 转码缓存目录（transcoder 可写，清理后可自动重建）
CACHE_ROOT=./cache
# 图片下载目录
IMAGES_PATH=./images
# 忽略扫描的路径正则（默认忽略 Downloads 目录）
LIBRARY_IGNORE_PATTERN=.*/[dD]ownloads?/.*
# 硬件加速档位：cpu / vaapi / qsv / nvidia
COMPOSE_PROFILES=cpu
# 转码 preset：越慢画质越好（vaapi 档不支持 preset）
GOCODER_PRESET=fast
# 对外访问地址（参与 JWT 签发，必须与浏览器实际访问地址一致）
PUBLIC_URL=http://localhost:8136
# 元数据库连接（默认值即可用；生产环境务必改密码）
PGUSER=kyoo
PGPASSWORD=q1w2e3r4
PGDATABASE=kyoo
PGHOST=postgres
PGPORT=5432

$ cd /opt/kyoo && docker compose pull

 71ffe5b63607 Extracting 1B
 fe5f3d0ae371 Pull complete 0B
 71ffe5b63607 Pull complete 0B
 Image ghcr.io/zoriya/kyoo_scanner:5.2 Pulled

$ docker compose up -d

$ docker compose ps --format 'table {{.Name}}\t{{.Status}}'
NAME                    STATUS
kyoo-5.2.1-api          Up 48 minutes
kyoo-5.2.1-auth         Up 48 minutes
kyoo-5.2.1-front        Up 48 minutes
kyoo-5.2.1-postgres     Up 48 minutes (healthy)
kyoo-5.2.1-scanner      Up 12 seconds
kyoo-5.2.1-traefik      Up 48 minutes
kyoo-5.2.1-transcoder   Up 48 minutes

$ curl -s http://localhost:8136/api/health && echo && curl -s http://localhost:8136/api/ready && echo && curl -s http://localhost:8136/auth/ready && echo
{"status":"healthy"}
{"status":"healthy","database":"healthy"}
{"status":"healthy","database":"healthy"}

$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8136/
200

$ curl -s -w "\n[%{http_code}]\n" -X POST http://localhost:8136/auth/users \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","email":"admin@example.com","password":"q1w2e3r4"}'
{"id":"3dcefdeb-254b-40f9-beeb-e1d7dd547241","createdDate":"2026-10-29T10:13:23.469473Z","lastUsed":"2026-10-29T10:13:23.469473Z","device":"curl","token":"W5zY5ejXbN56Ugj5goFkNkWjNapfZxfJ6_BnQ77EBzjeFWmWoO-Ygs74MGidjqOfuU8md1n2V-G4m7Rfd25_Rw"}
[201]

$ docker exec kyoo-5.2.1-postgres pg_dump -U kyoo -d kyoo > kyoo-meta-$(date +%F).sql
$ ls -lh kyoo-meta-*.sql
-rw-r--r-- 1 root root 58K Oct 29 18:26 kyoo-meta-2026-10-29.sql
--
-- PostgreSQL database dump
--

- "traefik.http.middlewares.phantom-token.forwardauth.address=http://auth:4568/auth/jwt"
- "traefik.http.middlewares.phantom-token.forwardauth.authRequestHeaders=Authorization,Cookie,X-Api-Key,Sec-WebSocket-Protocol"
- "traefik.http.middlewares.phantom-token.forwardauth.authResponseHeaders=Authorization"

depends_on:
  postgres:
    condition: service_healthy
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U ${PGUSER} -d ${PGDATABASE}"]
  interval: 5s
  retries: 5

$ docker inspect kyoo-5.2.1-scanner --format 'RestartCount={{.RestartCount}}'
RestartCount=99

aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host
api4.thetvdb.com:443 ssl:default [Connect call failed ('199.59.148.6', 443)]
ERROR   Application startup failed. Exiting.

$ curl -s -w "\n[%{http_code}]\n" -X POST http://localhost:8136/auth/keys \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
    -d '{"name":"docdemo","permissions":["core.read"]}'
{"status":500,"message":"","details":null}
[500]

$ curl -s -X POST http://localhost:8136/auth/keys \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
    -d '{"name":"docdemo","claims":{"permissions":["core.read","core.play"]}}'
{"id":"ee1691bb-0946-4e90-81a3-8b176121282a","name":"docdemo","claims":{"permissions":["core.read","core.play"]},"token":"y8WgTX_qztDG-uJQbW8vZCp2aVN4g9Y82DE9Ml8HnPsNggaR-DAvPUNnJ_3mIqlagUBDUXwjwxpbwAxqAv3E9w"}

$ curl -s -w "\n[%{http_code}]\n" http://localhost:8136/scanner/openapi.json
Bad Gateway
[502]

$ docker compose up -d --force-recreate api auth

# 0. 公共前置：网络与数据卷
docker network create --subnet 10.89.60.0/24 kyoo-5.2.1-net
docker volume create kyoo-521-stack_db

# 1. postgres（healthcheck 与 compose 一致）
docker run -d --name kyoo-postgres --network kyoo-5.2.1-net \
  -e POSTGRES_USER=kyoo -e PGPASSWORD=q1w2e3r4 -e POSTGRES_PASSWORD=q1w2e3r4 \
  -e POSTGRES_DB=kyoo -e POSTGRES_HOST_AUTH_METHOD=trust \
  -v kyoo-521-stack_db:/var/lib/postgresql \
  --health-cmd "pg_isready -U kyoo -d kyoo" \
  postgres:18

# 2. auth（依赖 postgres healthy，挂 JWT 密钥相关环境）
docker run -d --name kyoo-auth --network kyoo-5.2.1-net \
  -e PGUSER=kyoo -e PGPASSWORD=q1w2e3r4 -e PGDATABASE=kyoo -e PGHOST=postgres -e PGPORT=5432 \
  -e PUBLIC_URL=http://localhost:8136 \
  -e EXTRA_OIDC_REDIRECT_URLS=kyoo \
  -v kyoo-521-stack_profile_pictures:/profile_pictures \
  -l "traefik.enable=true" \
  -l "traefik.http.routers.auth.rule=PathPrefix(`/auth/`) || PathPrefix(`/.well-known/`)" \
  ghcr.io/zoriya/kyoo_auth:5.2

# 3. api
docker run -d --name kyoo-api --network kyoo-5.2.1-net \
  -e PGUSER=kyoo -e PGPASSWORD=q1w2e3r4 -e PGDATABASE=kyoo -e PGHOST=postgres -e PGPORT=5432 \
  -e JWT_ISSUER=http://localhost:8136 -e IMAGES_PATH=/images \
  -v kyoo-521-stack_images:/images \
  -l "traefik.enable=true" \
  -l "traefik.http.routers.api.rule=PathPrefix(`/api/`)" \
  ghcr.io/zoriya/kyoo_api:5.2

# 4. transcoder（cpu 档）
docker run -d --name kyoo-transcoder --network kyoo-5.2.1-net \
  -e JWKS_URL=http://auth:4568/.well-known/jwks.json \
  -v /opt/kyoo/video:/video:ro -v /opt/kyoo/cache:/cache \
  -v kyoo-521-stack_transcoder_metadata:/metadata \
  -l "traefik.enable=true" \
  -l "traefik.http.routers.transcoder.rule=PathPrefix(`/video`)" \
  ghcr.io/zoriya/kyoo_transcoder:5.2

# 5. scanner（外网可达时才能稳定运行，见 9.1）
docker run -d --name kyoo-scanner --network kyoo-5.2.1-net \
  -e KYOO_URL=http://traefik:8901/api \
  -e KYOO_APIKEY="$KEIBI_APIKEY_SCANNER" \
  -e JWKS_URL=http://auth:4568/.well-known/jwks.json \
  -e JWT_ISSUER=http://localhost:8136 \
  -v /opt/kyoo/video:/video:ro \
  ghcr.io/zoriya/kyoo_scanner:5.2

# 6. front
docker run -d --name kyoo-front --network kyoo-5.2.1-net \
  -e KYOO_URL=http://api:5000/api \
  -l "traefik.enable=true" \
  -l "traefik.http.routers.front.rule=PathPrefix(`/`)" \
  -l "traefik.http.services.front.loadbalancer.server.port=8901" \
  ghcr.io/zoriya/kyoo_front:5.2

# 7. traefik（挂 docker.sock 做 label 发现）
docker run -d --name kyoo-traefik --network kyoo-5.2.1-net \
  -p 8136:8901 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  traefik:v3.7 \
  --providers.docker=true --providers.docker.exposedbydefault=false \
  --entryPoints.web.address=:8901 --accesslog=true

# 状态与日志
docker compose ps                                  # 全栈状态（含 health）
docker compose logs -f api                          # 跟看 api 日志（-f 跟随）
docker compose logs --tail 50 transcoder            # 最近 50 行

# 生命周期
docker compose restart scanner                      # 单服务重启
docker compose up -d --force-recreate api auth      # 改 PUBLIC_URL 后重建
docker compose down                                 # 停栈（保留卷）
docker compose down -v                              # 停栈并删卷（彻底重置，谨慎）

# 升级（官方口径：更新两份文件后）
docker compose pull && docker compose up -d         # 拉新镜像并滚动重建

# 进入容器排查
docker exec -it kyoo-5.2.1-postgres psql -U kyoo -d kyoo   # 进元数据库
docker exec -it kyoo-5.2.1-transcoder ffmpeg -version      # 查 ffmpeg 版本

$ docker compose restart scanner
[+] Restarting 1/1
 ✔ Container kyoo-5.2.1-scanner  Started