MediaGo 3.5.0 配置参数详解

目标：逐项讲清 MediaGo 3.5.0 服务端的应用配置存储（config.json）全部 25 个键与服务端启动结构化配置的含义、默认值、取值与修改方式，并给出按场景分组的生产配置模板。所有键值、接口回显均在真实服务器实测取得（MediaGo 3.5.0 服务端，Linux amd64，实测日期 2026-10-25）。

一、环境信息

组件：MediaGo 服务端 3.5.0（官方镜像 caorushizi/mediago:3.5.0，部署与验证过程见部署篇）
系统：Linux 服务器 amd64，Web 端口 8899
数据目录：/opt/mediago（服务内路径 /app/mediago），配置存储位于 /opt/mediago/data/config.json
演示管理账号：admin / q1w2e3r4（已初始化，Bearer 令牌见各接口示例）
前置部署与任务实测：见《MediaGo 3.5.0 Docker Compose 部署指南》；组件定位见《MediaGo 3.5.0 介绍与选型指南》

cat /opt/mediago/data/config.json
# 实测回显（初始化 + 配置代理后；25 个键全量）：
# {
#   "allowBeta": false,
#   "apiKey": "77a934b1-a5bd-453d-afa1-45c6944d4c81",
#   "audioMuted": true,
#   "autoUpgrade": true,
#   "blockAds": true,
#   "closeMainWindow": false,
#   "deleteSegments": true,
#   "dockerUrl": "",
#   "downloadProxySwitch": false,
#   "enableDocker": false,
#   "enableMobilePlayer": false,
#   "isMobile": false,
#   "language": "system",
#   "local": "/app/mediago/downloads",
#   "machineId": "0e794d8c-c78f-4233-9374-c1fda3b7fcbe",
#   "maxRunner": 2,
#   "openInNewWindow": false,
#   "passwordHash": "$2a$10$i5JwzdlC8Uff6Cp2u/nTHOT6xh2XKf89geK6dF5mrtnayhMxETqlm",
#   "privacy": false,
#   "promptTone": true,
#   "proxy": "http://192.168.1.62:7897",
#   "showTerminal": false,
#   "theme": "system",
#   "useExtension": false,
#   "useProxy": true
# }

二、前置条件

已按部署篇完成 3.5.0 服务端部署并通过 /healthy 健康检查；
已初始化管理账号（未初始化时部分配置键尚为初始值，如 apiKey 为空、passwordHash 为空）；
熟悉一个 JSON 编辑入口（本文用 /api/config 接口演示，Web 设置页等效）。

三、参数查看与修改方式

3.1 两种修改入口与生效关系

配置有两个修改入口，写的是同一份 config.json：

Web 设置页：浏览器打开 http://<服务器IP>:8899 → 设置，图形化修改，适合人工调整；
HTTP API：GET /api/config（全量读取）、GET /api/config/:key（单键读取）、PUT /api/config/:key（单键写入，body 为 {"value": <新值>}），适合脚本化运维。

API 修改即时写入磁盘、即时生效（下一任务创建即按新值执行），无需重启服务；个别键（如 local 下载目录）语义上要求目录存在，修改前先在服务器上建好目录。

3.2 单键读取与写入实测

TOKEN=77a934b1-a5bd-453d-afa1-45c6944d4c81   # 登录接口返回的管理令牌

curl -s http://127.0.0.1:8899/api/config/maxRunner -H "Authorization: Bearer $TOKEN"
# 实测回显：
# {"success":true,"code":200,"message":"OK","data":2}

curl -s -X PUT http://127.0.0.1:8899/api/config/maxRunner -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"value":4}'
# 实测回显：
# {"success":true,"code":200,"message":"Config updated","data":{"message":"Config key 'maxRunner' updated"}}

curl -s http://127.0.0.1:8899/api/config/maxRunner -H "Authorization: Bearer $TOKEN"
# 实测回显（新值已生效）：
# {"success":true,"code":200,"message":"OK","data":4}

字符串型键同理（实测 language 从 system 改为 zh-CN，回读 data":"zh-CN"）。改回默认值重复 PUT 即可。

3.3 服务端启动结构化配置（只读，不在 config.json）

服务启动日志会打印一次「Final Config」——这是程序内部结构化配置，来源为内置默认值 + 环境推断，不能通过 config.json 修改，排障时用于核对服务实际生效的运行参数：

INFO	server/main.go:137	Final Config: &{GinMode:release Host:0.0.0.0 Port:8899 LogLevel:info LogDir:/app/mediago/logs SchemaPath:configs/config.json DepsDir:/app/deps MaxRunner:2 LocalDir:/app/mediago/downloads DeleteSegments:true Proxy: UseProxy:false DBPath:/app/mediago/data/mediago.db ConfigDir:/app/mediago/data EnableAuth:true StaticDir:/app/static}

字段	实测值	含义
GinMode	release	Gin 框架模式（镜像内已设 `GIN_MODE=release`）
Host / Port	0.0.0.0 / 8899	HTTP 监听地址与端口（镜像固定，改端口靠部署层映射）
LogLevel	info	日志级别
LogDir	/app/mediago/logs	日志目录（任务日志在其下 `logs/tasks/`）
DepsDir	/app/deps	随附引擎目录（5 个引擎 + ffmpeg）
MaxRunner	2	并发下载上限（与 config.json 的 `maxRunner` 同源）
LocalDir	/app/mediago/downloads	下载根目录（与 `local` 同源）
DBPath	/app/mediago/data/mediago.db	SQLite 任务库路径
ConfigDir	/app/mediago/data	配置目录（config.json 所在）
EnableAuth	true	认证开关（服务端固定开启）
StaticDir	/app/static	Web 前端静态资源目录

💡 技术拓展：应用配置的持久化方式常见三种——环境变量注入（12-Factor 风格，改配置需重建实例）、INI/YAML 文件（如 nginx.conf）、JSON 键值存储（服务负责读写与热更）。MediaGo 选的是第三种：config.json 由服务自己生成与维护，Web 设置页与 API 都是它的前端，用户手工编辑虽可行但容易与服务写回冲突，因此官方推荐入口是页面与 API。本文因 API 可实测留痕，均以 API 演示。

四、参数总览

25 个键按作用域分四类（服务端部署场景下真正需要关心的是前两类）：

分组	键	默认值
下载行为	`local`、`maxRunner`、`deleteSegments`、`downloadProxySwitch`	`/app/mediago/downloads`、`2`、`true`、`false`
网络代理	`proxy`、`useProxy`	`""`、`false`
账号与安全	`apiKey`、`passwordHash`、`privacy`、`blockAds`	`""`（初始化后为令牌）、`""`（初始化后为 bcrypt 哈希）、`false`、`true`
界面与桌面遗留	`language`、`theme`、`audioMuted`、`promptTone`、`openInNewWindow`、`closeMainWindow`、`showTerminal`、`enableMobilePlayer`、`isMobile`、`useExtension`、`enableDocker`、`dockerUrl`、`autoUpgrade`、`allowBeta`、`machineId`	见各键详解

说明：MediaGo 是「桌面 + 服务端」双形态同源配置，config.json 中相当一部分键服务于桌面窗口行为（窗口关闭动作、提示音等），在无界面服务端形态下保留默认值即可、不产生副作用。参数表之后紧跟解读，逐组见下。

五、核心参数分类详解

5.1 下载行为组

local：下载根目录，字符串。服务端默认 /app/mediago/downloads（部署篇已把该路径挂载持久化）。修改前必须保证目标目录存在——实测若启动时该目录不存在，服务会回退到 /root 并打日志 Download dir "/app/mediago/downloads" unavailable, using system default: /root（产物落到挂载之外，排障实录见部署篇 4.5）。指向大容量数据盘时先 mkdir -p 再改此键。

maxRunner：并发下载任务上限，整数，默认 2。实测改为 4 后回读生效（见 3.2）。取值建议：CPU 与带宽充裕的 NAS 可调 3–5；m3u8 类任务单任务内还有 8 线程分片并发（引擎默认），maxRunner 不宜过大挤占带宽。

deleteSegments：m3u8 任务合并成功后是否删除分片临时文件，布尔，默认 true。保持 true 省磁盘；排障合并问题（见部署篇 Q3）时可临时改 false 保留分片供手动合并。

downloadProxySwitch：下载引擎代理的总开关（布尔，默认 false）。与 proxy/useProxy 的关系：useProxy 控制全局代理注入，downloadProxySwitch 在部分版本界面上作为下载侧代理开关存在，服务端实测保持默认即可，代理配置以 proxy+useProxy 为准（见 5.2）。

5.2 网络代理组（境外源实测关键项）

proxy：全局 HTTP 代理地址，字符串，默认空。格式 http://<IP>:<端口>（实测 http://192.168.1.62:7897）。写入方法（实测回显）：

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"}}

useProxy：是否启用上述代理，布尔，默认 false。实测置 true 后，新任务由下载引擎（aria2c/yt-dlp/N_m3u8DL-RE 等）携带代理参数执行。

两者配套生效的实测结论：直连境外源下载 64KiB 后停滞（DL:0B）→ 配置 proxy + useProxy=true → 重建任务恢复正常推进并完成（产物字节数与源文件一致）。只改 proxy 不开 useProxy 不会生效。

5.3 账号与安全组

apiKey：管理令牌（API Key），字符串。初始部署为空字符串；执行账号初始化（POST /api/auth/setup）后自动写入本次生成的管理令牌（实测 77a934b1-a5bd-453d-afa1-45c6944d4c81，与登录接口返回值一致）。所有 /api/* 接口以 Authorization: Bearer <apiKey> 鉴权。该键等价于「当前登录凭据」，不要手工改值——重新初始化或重新登录会刷新。

passwordHash：管理账号口令的 bcrypt 哈希（实测 $2a$10$i5JwzdlC8Uff6Cp2u/nTHOT6xh2XKf89geK6dF5mrtnayhMxETqlm）。由服务端在初始化/改密时生成，文件中只有哈希没有明文；忘记口令时删除 data/config.json 中 passwordHash 与 apiKey 两键（或整个文件）并重启服务，重新走初始化流程（产物与任务库不受影响）。

privacy：隐私模式，布尔，默认 false。开启后界面隐藏敏感信息（任务 URL 等），适合演示/投屏场景。

blockAds：嗅探时过滤广告资源，布尔，默认 true。保持默认；若发现某站点的正片被误过滤可临时关闭验证。

5.4 界面与桌面遗留组（服务端形态保持默认即可）

键	默认	作用	服务端建议
`language`	`system`	界面语言（实测可改 `zh-CN`，界面三语：en/zh/it）	团队统一体验可显式设 `zh-CN`
`theme`	`system`	主题（system/light/dark）	默认
`audioMuted`	`true`	内置播放器静音	默认
`promptTone`	`true`	任务完成提示音（桌面端生效）	默认
`openInNewWindow`	`false`	打开链接新窗口（桌面端）	默认
`closeMainWindow`	`false`	关窗最小化到托盘（桌面端）	默认
`showTerminal`	`false`	显示下载终端输出窗口（桌面端）	默认
`enableMobilePlayer`	`false`	移动端播放器开关	默认
`isMobile`	`false`	移动端布局标记（自动检测）	默认
`useExtension`	`false`	浏览器扩展连接开关（桌面端）	默认
`enableDocker` / `dockerUrl`	`false` / `""`	桌面端连接远程 Docker 服务的遗留项	默认
`autoUpgrade`	`true`	检查更新提示（服务端升级走镜像 tag，见部署篇）	默认
`allowBeta`	`false`	是否接受 beta 版本更新	生产保持 `false`
`machineId`	自动生成 UUID	实例唯一标识（初始化时生成，如 `0e794d8c-...`）	不可改，用于实例识别

六、生产配置模板

模板一：家庭 NAS / 小团队自用（8GB 内存、机械盘或 SATA SSD、带宽 ≤ 100Mbps，夜间挂机批量下载）：

{
  "local": "/app/mediago/downloads",
  "maxRunner": 2,
  "deleteSegments": true,
  "proxy": "http://<代理IP>:<端口>",
  "useProxy": true,
  "blockAds": true,
  "allowBeta": false
}

要点：并发保守（2），机械盘避免多任务同时写；境外源必须配代理；分片自动清理开。

模板二：大带宽独立下载服务器（16GB 内存、NVMe SSD、千兆以上带宽、代理出口稳定）：

{
  "local": "/app/mediago/downloads",
  "maxRunner": 4,
  "deleteSegments": true,
  "proxy": "http://<代理IP>:<端口>",
  "useProxy": true,
  "blockAds": true,
  "allowBeta": false,
  "language": "zh-CN"
}

要点：并发提到 4；NVMe 扛多任务随机写；language 显式中文便于多人共用。

模板三：排障临时配置（复现合并问题、保留现场）：

{
  "deleteSegments": false,
  "maxRunner": 1
}

要点：单任务串行 + 保留分片，便于对照任务日志与分片产物定位合并故障（配合部署篇 Q3 的手动合并兜底）。

三份模板中 <代理IP>:<端口> 为占位：请替换为你网络内真实可用的 HTTP 代理地址；不使用代理的封闭内网环境把 useProxy 设回 false 并清空 proxy。

七、常见问题

Q1：改了 config.json 没生效？ 服务运行中手工编辑文件会与服务写回竞争（Web 页/API 的修改会覆盖文件）。用 API 或页面改；确需手工编辑时，先 docker compose down（部署篇命令），改完 up -d。

Q2：PUT /api/config/:key 返回错误或 401？ 401 检查 Bearer 令牌（与 apiKey 一致）；未知键名返回错误信息「Config key not found」类提示，先 GET /api/config 全量确认键名拼写（区分驼峰大小写）。

Q3：代理配置后任务还是不走代理？ 三个检查点：useProxy 是否 true（实测只设 proxy 不生效）→ 代理地址是否服务端可达（curl -x http://<代理>:<端口> https://目标站 -I 验证）→ 新建任务才用新配置，旧任务需停止重建。

Q4：想换下载目录到数据盘？ 先 mkdir -p /data/mediago-downloads 并确认部署层挂载覆盖该路径，再 PUT local，最后用一个小任务实测产物落位（ls 目标目录）。目录不存在会触发部署篇 4.5 的回退问题。

Q5：服务端和桌面版的配置文件能互拷吗？ 不建议。两形态键集合有差异（桌面端多窗口/托盘相关状态），跨形态拷贝可能引入无效键；服务端配置以本文 25 键为准。

八、参考链接

官方 README（配置与 Docker 部署）：https://github.com/mediago-dev/mediago
文档站：https://downloader.caorushizi.cn/documents.html
官网：https://mediago.torchstellar.com/en/downloader
站内同专栏：《MediaGo 3.5.0 介绍与选型指南》、《MediaGo 3.5.0 Docker Compose 部署指南》、《MediaGo 3.5.0 常用 CLI 命令与工具详解》