MediaGo 3.5.0 Docker Compose 部署指南
MediaGo 3.5.0 服务端 Docker Compose 从零部署全流程实测：镜像选型、compose 编写、初始化账号、下载任务验证、数据持久化与服务端代理配置。
MediaGo 3.5.0 Docker Compose 部署指南
目标：在一台 Linux 服务器上用 Docker Compose 从零部署 MediaGo 3.5.0 服务端，完成初始化、首个下载任务验证、服务端代理配置与数据持久化，全部命令与回显均在真实服务器环境实测通过（服务器为 Linux amd64，Docker 28.3.3 / Compose v2.39.4，部署时间 2026-10-25）。
一、环境信息
本文所有命令与回显均在以下环境实测取得：
- 操作系统：Linux 服务器（amd64，内核 6.x），磁盘可用 20GB 以上
- Docker：28.3.3（
docker --version实测），Compose v2.39.4（docker compose version实测） - MediaGo：3.5.0 正式版（官方 Docker Hub 镜像
caorushizi/mediago:3.5.0，大小约 756MB） - 部署目录：
/opt/mediago（数据目录，挂载进服务） - Web 端口：8899（MediaGo 服务端固定监听端口）
- 演示管理账号：
admin/q1w2e3r4（首次初始化时在 Web 页面设置） - 组件背景与选型结论见 《MediaGo 3.5.0 介绍与选型指南》
docker --version && docker compose version
# 确认部署载体版本（实测回显）
# Docker version 28.3.3, build a3b0d1a
# Docker Compose version v2.39.4
二、镜像选型说明
MediaGo 服务端镜像在 Docker Hub 与 GHCR 双渠道同步发布，同一构建、任选其一：
| 渠道 | 引用 | 适用 |
|---|---|---|
| Docker Hub | caorushizi/mediago:3.5.0 | 默认首选，拉取通用 |
| GHCR | ghcr.io/caorushizi/mediago:3.5.0 | Hub 拉取慢时备用 |
| 版本标签 | :3.5.0 | 固定正式版，生产推荐 |
| 架构 | amd64 / arm64 | 服务器与 ARM NAS 均可 |
选型要点：生产固定 tag（:3.5.0）而非 latest，升级走「拉新 tag + 重建」，可随时回滚。镜像内置 5 个下载引擎（N_m3u8DL-RE、aria2c、yt-dlp、BBDown、mediago CLI）与 ffmpeg，无需额外安装任何依赖。本文实测拉取的镜像摘要为 sha256:fe4a68475cfd3aee6f375a27eacce1b7ae1201df654d009722642438dc2fd109，可用于部署后核对。
⚠️ 下载国外镜像慢时，Docker 已配置的代理会自动生效；GHCR 备用渠道在 Docker Hub 不可用时手动切换引用即可，两者摘要一致。
三、前置条件
- 服务器已安装 Docker 与 Compose 插件（
docker compose version可执行）； - 服务器 8899 端口空闲（
ss -ltn | grep 8899无输出；若被占用，将 compose 端口映射左侧改为其他端口即可，容器内恒为 8899）； - 数据盘可用空间 ≥ 10GB（镜像约 756MB，下载产物按需增长）；
- 规划好数据目录（本文用
/opt/mediago，可自定）； - 如需下载境外站点资源，准备一个 HTTP 代理地址（如
http://<代理IP>:<端口>），部署后通过 Web 界面或 API 配置（见七.4）。
ss -ltn | grep 8899 || echo "port 8899 free"
# 实测回显：port 8899 free
四、部署步骤
4.1 创建数据目录（关键：必须预建 downloads 子目录）
mkdir -p /opt/mediago/downloads
# 数据目录 + 下载子目录一步建好；downloads 子目录必须存在，原因见 4.5 排障实录
4.2 编写 docker-compose.yml
mkdir -p /opt/mediago && vi /opt/mediago/docker-compose.yml
name: mediago-3.5.0-stack
services:
mediago:
image: caorushizi/mediago:3.5.0
container_name: mediago-3.5.0-server
restart: unless-stopped
ports:
- "8899:8899"
volumes:
- /opt/mediago:/app/mediago
配置说明：
name: mediago-3.5.0-stack：显式指定 Compose 项目名，避免与其他项目的部署目录同名互扰；ports "8899:8899"：宿主 8899 → 服务 8899，左侧可改（如"8123:8899"），右侧固定；volumes：把/opt/mediago挂载为服务端数据目录/app/mediago，配置、数据库、日志、下载产物全部落在这里，重建服务不丢数据；restart: unless-stopped：开机自启、异常退出自动拉起。
4.3 拉取镜像并启动
cd /opt/mediago && docker compose up -d
# 实测回显：
# [+] Running 2/2
# ✔ Network mediago-35-stack_default Created
# ✔ Container mediago-3.5.0-server Started
4.4 启动验证
docker compose -f /opt/mediago/docker-compose.yml ps
# 实测回显：
# NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
# mediago-3.5.0-server caorushizi/mediago:3.5.0 "/usr/local/bin/dock…" mediago 9 seconds ago Up 8 seconds 0.0.0.0:8899->8899/tcp
看一眼启动日志，确认服务端口已监听：
docker logs mediago-3.5.0-server 2>&1 | grep -E 'MediaGo Downloader|Starting HTTP server|downloader:'
# 实测回显（节选）：
# INFO server/main.go:136 MediaGo Downloader Service Starting...
# INFO server/main.go:148 App store initialized at: /app/mediago/data/config.json
# INFO server/main.go:193 bilibili downloader: /app/deps/BBDown
# INFO server/main.go:193 direct downloader: /app/deps/aria2c
# INFO server/main.go:193 mediago downloader: /app/deps/mediago
# INFO server/main.go:193 youtube downloader: /app/deps/yt-dlp
# INFO server/main.go:193 m3u8 downloader: /app/deps/N_m3u8DL-RE
# INFO server/main.go:210 Task queue initialized (maxRunner=2)
# INFO server/main.go:260 Database opened: /app/mediago/data/mediago.db
# INFO server/main.go:281 Starting HTTP server on 0.0.0.0:8899
HTTP 健康检查：
curl -s http://127.0.0.1:8899/healthy
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":{"status":"ok"}}
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8899/
# 实测回显（Web 首页）：
# 200
4.5 ⚠️ 排障实录：未预建 downloads 子目录导致下载产物落到默认 HOME
首次部署时若只 mkdir -p /opt/mediago 而不建 downloads 子目录，服务启动日志会出现：
INFO server/main.go:173 Download dir "/app/mediago/downloads" unavailable, using system default: /root
此后所有下载产物会落到服务内部默认目录 /root（挂载目录之外），数据目录里看不到文件，重建后即丢。定位方法：docker logs 搜 Download dir；解决方法：宿主侧 mkdir -p /opt/mediago/downloads 后重启服务（docker compose restart），日志不再出现该告警。本文 4.1 已把预建步骤纳入标准流程。
4.6 初始化管理账号
浏览器访问 http://<服务器IP>:8899，首次进入初始化页面，设置管理账号。本文演示用 admin / q1w2e3r4。也可用 API 完成初始化（与页面等效）：
curl -s http://127.0.0.1:8899/api/auth/status
# 实测回显（未初始化时）：
# {"success":true,"code":200,"message":"OK","data":{"setuped":false}}
curl -s -X POST http://127.0.0.1:8899/api/auth/setup -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4"}'
# 实测回显（data 为登录令牌）：
# {"success":true,"code":200,"message":"OK","data":"77a934b1-a5bd-453d-afa1-45c6944d4c81"}
4.7 首个下载任务实测
用公开测试流验证下载链路（官方教学样本，无版权问题）。以下先登录拿令牌，再建一个 mp4 直链下载任务（direct 类型）：
TOKEN=$(curl -s -X POST http://127.0.0.1:8899/api/auth/signin -H 'Content-Type: application/json' -d '{"username":"admin","password":"q1w2e3r4"}' | sed 's/.*"data":"\([^"]*\)".*/\1/')
# 登录换取 Bearer 令牌（与初始化返回值一致）
curl -s -X POST http://127.0.0.1:8899/api/tasks -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"url":"https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4","name":"bbb-direct-test","type":"direct"}'
# 实测回显：
# {"success":true,"code":200,"message":"Task created successfully","data":{"id":"caea661f-c3e6-4c33-a0cc-63b4181294f9","message":"Task enqueued successfully","status":"downloading"}}
稍候查询任务状态（任务接口回显字段：id/type/url/name/status/percent/speed/isLive/error）：
curl -s "http://127.0.0.1:8899/api/tasks" -H "Authorization: Bearer $TOKEN"
# 实测回显（节选）：
# {"success":true,"code":200,"message":"OK","data":{"tasks":[{"id":"caea661f-...","type":"direct","url":"https://test-videos.co.uk/...","name":"bbb-direct-test","status":"success","percent":100,"speed":"","isLive":false}],"total":1}}
ls -la /opt/mediago/downloads/
# 实测回显：
# -rw-r--r-- 1 root root 991017 Oct 25 11:42 bbb-direct-test.mp4
# 产物 991017 字节，与源文件 Content-Length 一致，下载链路完整走通
Web UI 里同步可见任务列表、进度与内置播放器入口。
五、数据持久化说明
服务端一切状态都在挂载目录 /opt/mediago（对应服务内 /app/mediago）：
| 宿主路径 | 服务内路径 | 内容 |
|---|---|---|
/opt/mediago/data/config.json | /app/mediago/data/config.json | 运行配置存储（含账号哈希、代理等全部键） |
/opt/mediago/data/mediago.db | /app/mediago/data/mediago.db | SQLite 任务库（任务记录、历史） |
/opt/mediago/downloads/ | /app/mediago/downloads | 下载产物（按任务名分子目录/单文件） |
/opt/mediago/logs/ | /app/mediago/logs | 服务日志与任务日志（logs/tasks/<任务id>.log） |
备份即打包该目录（数据库为 SQLite 单文件，建议停服务后备份或直接复制 config.json + 指定任务产物）；迁移到新服务器 = 复制目录 + 用同一 compose 重建。升级版本同理：换 tag 重建即可，数据目录不动。
六、环境变量表
MediaGo 服务端无必填环境变量，配置走数据目录的 config.json（经 Web 设置页或 /api/config 接口修改，详见配置篇）。与部署相关的可选环境变量：
| 变量 | 默认 | 说明 |
|---|---|---|
GIN_MODE | release（镜像内已设） | Gin 框架运行模式；排障可设 debug 看全量路由日志 |
http_proxy / https_proxy | 未设置 | 进程级代理；不推荐用环境变量配代理——下载引擎的代理由 config.json 的 proxy+useProxy 键控制（见七.4） |
说明：随附引擎（aria2c/yt-dlp/N_m3u8DL-RE 等）的代理参数由 MediaGo 核心统一注入，改
config.json即可全局生效，这也是官方设计意图——不必在部署层散配代理。
七、配置参数说明
7.1 配置载体与查看方式
配置有三层：docker-compose.yml（部署层：端口、挂载、重启策略）→ /opt/mediago/data/config.json（应用配置存储）→ Web 设置页//api/config 接口（前两者的可视化/编程入口）。三处改任一处以 config.json 为最终事实（服务端启动与运行时都读写它）。
7.2 compose 层关键项
已在 4.2 逐项说明（name/ports/volumes/restart），需要扩容磁盘或换端口时只改 compose 重建即可。
7.3 config.json 常用键速查（部署后立即相关的）
cat /opt/mediago/data/config.json
# 实测回显（初始化后）：
# {
# "allowBeta": false,
# "apiKey": "",
# "audioMuted": true,
# "autoUpgrade": true,
# "blockAds": true,
# "deleteSegments": true,
# "downloadProxySwitch": false,
# "enableDocker": false,
# "language": "system",
# "local": "/app/mediago/downloads",
# "machineId": "0e794d8c-c78f-4233-9374-c1fda3b7fcbe",
# "maxRunner": 2,
# "passwordHash": "<初始化后自动生成>",
# "proxy": "",
# "theme": "system",
# "useProxy": false
# ...（完整 26 键逐项解释见配置篇）
# }
| 键 | 默认 | 作用 |
|---|---|---|
local | /app/mediago/downloads | 下载根目录，挂载目录内不要改到外面 |
maxRunner | 2 | 同时下载的任务数上限 |
deleteSegments | true | m3u8 合并成功后删除分片临时文件 |
proxy / useProxy | "" / false | 下载引擎全局代理（见 7.4） |
language / theme | system | 界面语言与主题 |
全部 26 个键的语义、取值与修改接口实测见配置篇。
7.4 服务端代理配置（实测）
下载境外站点慢或卡死时（实测直连 64KiB 后速度归 0），配置全局代理后即可正常下载：
curl -s -X PUT http://127.0.0.1:8899/api/config/proxy -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"value":"http://192.168.1.62:7897"}'
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":{"message":"Config key 'proxy' updated"}}
curl -s -X PUT http://127.0.0.1:8899/api/config/useProxy -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"value":true}'
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":{"message":"Config key 'useProxy' updated"}}
配置后新建任务实测：直连卡死的同一 URL 重新入队后恢复推进并完成（status":"success","percent":100，产物 991017 字节）。Web 设置页的「代理」项等价于此操作。
八、配置文件挂载
除整目录挂载外，如需把配置与产物分开（例如配置持久化到独立卷、产物落到大容量数据盘），把挂载粒度细化即可：
volumes:
- /opt/mediago/data:/app/mediago/data # 配置与数据库
- /opt/mediago/logs:/app/mediago/logs # 日志
- /data/mediago-downloads:/app/mediago/downloads # 产物单独落大数据盘
注意：拆分挂载时 downloads 路径仍须与 config.json 的 local 键一致，且目录必须存在（见 4.5 排障实录）。整目录挂载（本文 4.2 方案）最简单，无路径错位风险，推荐默认使用。
九、等价 docker run
与本文 compose 等价的最小部署命令（官方 README 原文形式）：
docker run -d --name mediago -p 8899:8899 -v /opt/mediago:/app/mediago caorushizi/mediago:3.5.0
# 等价于 compose 的 ports+volumes+image 三项；restart 策略需另加 --restart unless-stopped
compose 相比裸 docker run 的优势：项目名隔离、配置文件可版本化、up/down 一键运维，生产建议统一 compose。
十、常用运维命令
cd /opt/mediago
docker compose ps
# 查看服务状态（STATUS 应为 Up）
docker compose logs -f --tail 100 mediago
# 实时跟踪服务日志（Ctrl+C 退出，服务不受影响）
docker compose restart
# 重启服务（改 compose 或 config.json 后执行；实测约 3 秒恢复监听）
docker compose down
# 停止并移除部署（数据目录保留，删除的只是运行实例）
docker compose pull && docker compose up -d
# 升级：拉取 compose 中引用的新版本 tag 后重建（数据目录不动）
docker images caorushizi/mediago
# 实测回显：
# caorushizi/mediago 3.5.0 fe4a68475cfd 756MB
磁盘巡检：产物与分片临时目录都在 /opt/mediago/downloads，批量下载后关注 du -sh /opt/mediago/downloads。
十一、常见问题
Q1：任务一直 downloading 但速度为 0，最终不动了？
实测现象：直连境外源下载 64KiB 后 DL:0B 长期停滞。定位：任务日志（GET /api/tasks/<id>/logs 或 Web 任务详情）确认连接已建立但无进度。解决：按七.4 配置 proxy+useProxy 后重建任务；实测配置后同一 URL 顺利完成。
Q2：任务 failed，error: "exit status 22"？
实测现象：download.blender.org 等源返回 403。任务日志明示 errorCode=22 The response status is not successful. status=403。原因：aria2 引擎对源站 403（防盗链/IP 段拒绝/UA 校验）不重试直接失败。解决：换可公开访问的源验证链路；确实需要该源的，用支持自定义请求头的下载方式或服务端代理出口。
Q3：m3u8 任务显示 success，但目录里只有 .ts 分片、没有合并后的视频？
实测现象：任务日志有「调用ffmpeg合并中... Done」与「Task completed successfully」，但产物目录只有分片；手动执行随附 ffmpeg 处理任一分片复现 Segmentation fault (core dumped)（转封装与重编码路径均崩）。根因：镜像随附的 ffmpeg 为静态构建，个别 MPEG-TS 流在部分服务器环境触发崩溃，且上游 N_m3u8DL-RE 未校验 ffmpeg 退出码、仍报 Done。处置：① 立即可用的兜底是分片合并为完整 .ts（cat 0__*/*.ts > 完整.ts，MPEG-TS 可直接播放或后续转码）；② 根治是把服务内 /app/deps/ffmpeg 替换为发行版软件源的 ffmpeg（apt install ffmpeg 后复制 /usr/bin/ffmpeg 覆盖）；③ 反馈上游等待随附 ffmpeg 更新。
Q4：Web 页面打不开？
依次检查：docker compose ps 是否 Up → curl http://127.0.0.1:8899/healthy 是否返回 ok → ss -ltn | grep 8899 端口是否监听 → 云服务器安全组/防火墙是否放行 8899。
Q5：不想写 compose，有更简单的方式吗？
宝塔面板用户可在面板「Docker → 应用商店」搜索 MediaGo 一键安装（官方支持路径）；单机临时试用用九的 docker run 命令。
Q6：升级后账号和数据还在吗？
在。账号哈希在 config.json、任务记录在 mediago.db、产物在 downloads/，都在挂载目录里，换版本重建不影响；版本变化导致的配置项增减由服务端自动兼容。
十二、参考链接
- 官方 README（Docker 一键部署）：https://github.com/mediago-dev/mediago
- Docker Hub 镜像页：https://hub.docker.com/r/caorushizi/mediago
- GHCR 镜像：https://ghcr.io/caorushizi/mediago
- 官网部署说明：https://mediago.torchstellar.com/en/downloader
- 宝塔面板：https://www.bt.cn/new/download.html
- 站内同专栏：《MediaGo 3.5.0 介绍与选型指南》、《MediaGo 3.5.0 配置参数详解》、《MediaGo 3.5.0 常用 CLI 命令与工具详解》