T3FAP 部署实战：从 Compose 编排到 SSH 一键安装

前言

T3FAP（全称 T3MT Film Auto Platform）是一个面向影视自动化场景的服务平台。根据其 GitHub 仓库（qq85423296/T3FAP）的描述，它提供以下核心能力：

资源发现：聚合多个影视资源站的目录与搜索能力
网盘接入：对接网盘资源与下载
任务编排：自动化任务流程调度
插件扩展：通过插件机制灵活扩展功能

从定位上看，T3FAP 更偏向”影视资源的自动化采集与整理平台”，适合配合 Emby、Jellyfin 等媒体服务器使用。

一、先明确一个前提：两种数据库方案并存

在写具体命令前，需要先厘清一个容易踩坑的点——你的 docker-compose.yml 用的是 SQLite，而 T3FAP 官方推荐的是 MySQL。

方案	数据库	适用场景	官方态度
方案 A（你的 compose）	SQLite	快速演示、轻量单机、临时测试	支持但不推荐长期
方案 B（官方 compose）	MySQL 8.0	长期运行、正式使用	推荐

下面的内容会两种方案都给，你可以按需选择。一键脚本默认采用方案 B（MySQL），更贴合官方推荐。

二、方案 A：基于你现有 compose 的 SQLite 部署

2.1 `docker-compose.yml`

services:
  t3fap:
    image: ghcr.io/qq85423296/t3fap:v2.1.7
    container_name: t3fap
    restart: always
    ports:
      - "8521:8521"
    environment:
      - TZ=Asia/Shanghai
      - T3MT_ENV=production
      - T3MT_LOG_LEVEL=INFO
      - T3MT_PUBLIC_BASE_URL=http://192.168.4.8:8521
      - T3MT_DATABASE_URL=sqlite:////app/storage/runtime/t3mt-next.db
      - T3MT_ENABLE_QQBOT_GATEWAY=0
    volumes:
      - /vol1/1000/Docker/t3mt/logs:/app/storage/logs
      - /vol1/1000/Docker/t3mt/packages:/app/storage/packages
      - /vol1/1000/Docker/t3mt/runtime:/app/storage/runtime
      - /vol1/1000/strm/t3fap:/app/backend/downloads
    security_opt:
      - apparmor:unconfined

启动：

docker compose up -d

⚠️ 注意 T3MT_PUBLIC_BASE_URL 必须改成你实际访问的地址（局域网 IP 或域名），否则生成的播放链接会指向错误地址。

三、方案 B：官方推荐的 MySQL 部署

3.1 `compose.yaml`（官方默认结构）

services:
  mysql:
    image: mysql:8.0
    container_name: t3fap-mysql
    restart: always
    environment:
      - TZ=Asia/Shanghai
      - MYSQL_DATABASE=t3fap
      - MYSQL_USER=t3fap
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
    volumes:
      - ./mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 20

  t3fap:
    image: ghcr.io/qq85423296/t3fap:latest
    container_name: t3fap
    restart: always
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - "8521:8521"
    environment:
      - TZ=Asia/Shanghai
      - T3MT_ENV=production
      - T3MT_PUBLIC_BASE_URL=${T3MT_PUBLIC_BASE_URL}
      - T3MT_DATABASE_URL=mysql+pymysql://t3fap:${MYSQL_PASSWORD}@mysql:3306/t3fap
    volumes:
      - ./data:/app/storage
      - ./downloads:/app/backend/downloads
    security_opt:
      - apparmor:unconfined

3.2 `.env` 文件

T3MT_PUBLIC_BASE_URL=http://192.168.4.8:8521
MYSQL_PASSWORD=ChangeMe_StrongPass123
MYSQL_ROOT_PASSWORD=ChangeMe_RootPass456

实际数据库连接串需以官方 .env.example 为准，不同版本变量名可能略有差异，部署前请 cat .env.example 核对。

四、SSH 一键部署命令

下面给出一键脚本，适合在远程服务器（如 NAS、VPS）上通过 SSH 执行。脚本设计为幂等（可重复执行），并带有基本检查。

4.1 方案 A：SQLite 一键脚本（对应你的 compose）

ssh user@192.168.4.8 'bash -s' <<'EOF'
set -euo pipefail

BASE=/vol1/1000/Docker/t3mt
STRM=/vol1/1000/strm/t3fap

echo ">>> 创建目录..."
mkdir -p "$BASE/logs" "$BASE/packages" "$BASE/runtime" "$STRM"

echo ">>> 写入 docker-compose.yml..."
cat > "$BASE/docker-compose.yml" <<'YAML'
services:
  t3fap:
    image: ghcr.io/qq85423296/t3fap:v2.1.7
    container_name: t3fap
    restart: always
    ports:
      - "8521:8521"
    environment:
      - TZ=Asia/Shanghai
      - T3MT_ENV=production
      - T3MT_LOG_LEVEL=INFO
      - T3MT_PUBLIC_BASE_URL=http://192.168.4.8:8521
      - T3MT_DATABASE_URL=sqlite:////app/storage/runtime/t3mt-next.db
      - T3MT_ENABLE_QQBOT_GATEWAY=0
    volumes:
      - /vol1/1000/Docker/t3mt/logs:/app/storage/logs
      - /vol1/1000/Docker/t3mt/packages:/app/storage/packages
      - /vol1/1000/Docker/t3mt/runtime:/app/storage/runtime
      - /vol1/1000/strm/t3fap:/app/backend/downloads
    security_opt:
      - apparmor:unconfined
YAML

echo ">>> 拉取镜像并启动..."
cd "$BASE"
docker compose pull
docker compose up -d

echo ">>> 等待启动..."
sleep 8

echo ">>> 健康检查..."
curl -fsS http://127.0.0.1:8521/api/health && echo "" || echo "健康检查未通过，请查看日志: docker logs t3fap"

echo ">>> 完成。容器状态:"
docker ps --filter name=t3fap
EOF

4.2 方案 B：MySQL 一键脚本（官方推荐）

ssh user@192.168.4.8 'bash -s' <<'EOF'
set -euo pipefail

BASE=/vol1/1000/Docker/t3mt
STRM=/vol1/1000/strm/t3fap
PUBLIC_URL="http://192.168.4.8:8521"
MYSQL_PASS="ChangeMe_StrongPass123"
MYSQL_ROOT_PASS="ChangeMe_RootPass456"

echo ">>> 创建目录..."
mkdir -p "$BASE/mysql-data" "$BASE/data" "$STRM"

echo ">>> 写入 .env..."
cat > "$BASE/.env" <<ENV
T3MT_PUBLIC_BASE_URL=$PUBLIC_URL
MYSQL_PASSWORD=$MYSQL_PASS
MYSQL_ROOT_PASSWORD=$MYSQL_ROOT_PASS
ENV

echo ">>> 写入 compose.yaml..."
cat > "$BASE/compose.yaml" <<'YAML'
services:
  mysql:
    image: mysql:8.0
    container_name: t3fap-mysql
    restart: always
    environment:
      - TZ=Asia/Shanghai
      - MYSQL_DATABASE=t3fap
      - MYSQL_USER=t3fap
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
    volumes:
      - ./mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 20

  t3fap:
    image: ghcr.io/qq85423296/t3fap:latest
    container_name: t3fap
    restart: always
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - "8521:8521"
    environment:
      - TZ=Asia/Shanghai
      - T3MT_ENV=production
      - T3MT_PUBLIC_BASE_URL=${T3MT_PUBLIC_BASE_URL}
      - T3MT_DATABASE_URL=mysql+pymysql://t3fap:${MYSQL_PASSWORD}@mysql:3306/t3fap
    volumes:
      - ./data:/app/storage
      - ./downloads:/app/backend/downloads
    security_opt:
      - apparmor:unconfined
YAML

echo ">>> 启动..."
cd "$BASE"
docker compose pull
docker compose up -d

echo ">>> 等待数据库迁移与启动（最长 60s）..."
for i in $(seq 1 12); do
  if curl -fsS http://127.0.0.1:8521/api/health >/dev/null 2>&1; then
    echo ">>> 健康检查通过"
    break
  fi
  echo "    等待中... ($i/12)"
  sleep 5
done

curl -fsS http://127.0.0.1:8521/api/health || echo ">>> 健康检查未通过，请 docker logs t3fap 排查"
echo ""
echo ">>> 完成。访问: $PUBLIC_URL"
EOF

五、脚本要点说明

设计点	作用
`set -euo pipefail`	任一步失败立即退出，避免半成品部署
`<<'YAML'` 单引号 heredoc	防止本地/远程 shell 展开变量（`$` 保持不变）
`mkdir -p`	幂等创建目录，重复执行不报错
`depends_on: service_healthy`	确保 MySQL 真正就绪后才启动应用，避免迁移失败
循环健康检查	兼容首次启动较慢的情况（尤其 MySQL 初始化）
`docker compose pull`	先拉新镜像再启动，避免旧镜像残留

六、升级与备份

升级（两方案通用）：

cd /vol1/1000/Docker/t3mt
docker compose pull
docker compose up -d

备份（大版本升级前必做）：

# 方案 A
tar czf t3fap-backup-$(date +%F).tar.gz -C /vol1/1000/Docker/t3mt logs packages runtime
tar czf t3fap-strm-$(date +%F).tar.gz -C /vol1/1000/strm t3fap

# 方案 B
tar czf t3fap-backup-$(date +%F).tar.gz -C /vol1/1000/Docker/t3mt mysql-data data
tar czf t3fap-strm-$(date +%F).tar.gz -C /vol1/1000/strm t3fap

⚠️ 千万不要执行 docker compose down -v，-v 会删除卷数据。T3FAP 默认用本地目录挂载虽不受影响，但养成习惯可防后续切换 named volume 时误删。

七、常见问题排查

现象	排查方向
页面能开，但播放/下载链接不对	`T3MT_PUBLIC_BASE_URL` 是否写成了真实访问地址，而非 `127.0.0.1`
健康检查超时	`docker logs t3fap` 看是否卡在数据库迁移；MySQL 方案需确认 `service_healthy` 已触发
端口冲突	检查 `8521` 是否被占用：`ss -lntp \	grep 8521`
权限报错（AppArmor）	已加 `security_opt: apparmor:unconfined`，若仍报错可检查宿主机 AppArmor 状态
数据”丢失”	检查挂载路径是否正确映射到宿主机目录，不要误用 `down -v`

八、小结

你的原 compose 是 SQLite 方案，适合快速验证；长期运行建议切到官方 MySQL 方案。
SSH 一键脚本采用 heredoc 内嵌配置，远程执行即可完成”建目录 → 写配置 → 拉镜像 → 启动 → 健康检查”全流程。
两个关键红线：T3MT_PUBLIC_BASE_URL 写真实地址、别用 docker compose down -v。
升级走 pull + up -d，备份以 tar 打包对应持久化目录即可。

按需选择方案 A 或 B，把脚本里的 user@192.168.4.8、密码、PUBLIC_URL 替换成你的实际值，即可一键落地。

参考链接

项目地址：https://github.com/qq85423296/T3FAP
插件目录：https://github.com/qq85423296/T3FAP/tree/main/plugins