配置与环境变量

设置的来源与优先级复制锚点链接

生效的设置由四层合并而成，后面的覆盖前面的：

1. 内置默认值；
2. settings.toml（默认在数据文件夹中）；
3. 环境变量 MIZUOTO_<GROUP>__<FIELD>；
4. 嵌入方固定的值（Mizuoto 在另一个程序里运行时才有，见 在 Python 中使用）。

环境变量和固定值只在内存中生效，不会写回 settings.toml，也不能在网页界面或接口中修改。网页界面中被环境变量覆盖的设置标注 由环境变量设置，被嵌入方固定的标注 由运行 Mizuoto 的应用程序设置；mizuoto config set 修改一个被环境变量覆盖的设置时会提示 An environment variable overrides this setting.。

数据文件夹与设置文件复制锚点链接

数据文件夹存放设置、数据库、模型、音色和结果。默认位置：

用环境变量 MIZUOTO_DATA_DIR 或 mizuoto webui --data-dir <路径> 换到别处。settings.toml 默认在数据文件夹里；MIZUOTO_CONFIG_DIR 或 webui --config-dir 可以把它放到另一个文件夹（数据仍在数据文件夹中）。网页界面 设置 › 关于 显示 数据文件夹 和 设置文件。

想让 mizuoto config、mizuoto speak 等命令与服务器使用同一个数据文件夹，用环境变量最方便：--data-dir 只是 webui 的选项。

文件夹结构复制锚点链接

<数据文件夹>/
├── settings.toml        设置
├── mizuoto.db            数据库：任务、结果、参考音频、转写缓存、预设……
├── server.json          正在运行的服务器的地址和进程号（服务器退出时删除）
├── models/              模型，<引擎>/<模型>/；共享文件在 models/_assets/<引擎>/<名称>/
├── voices/              音色库，每个音色一个文件夹
├── outputs/             合成结果，按月份分文件夹 outputs/<yyyy-mm>/
├── datasets/            数据集
├── experiments/         训练实验，<引擎>/<名称>/
├── projects/            项目
├── cache/               参考音频、音色缓存、各引擎的临时文件、远程文件缓存
├── uploads/             上传的文件
├── jobs/                任务日志 <任务 id>.log
└── trash/               系统没有回收站时，删除的音色、结果等移到这里

paths.* 设置可以把模型、音色、结果、数据集、实验、项目和缓存分别放到别处；留空表示在数据文件夹里。

用命令行查看和修改复制锚点链接

mizuoto config path                              # settings.toml 的路径
mizuoto config show                              # 生效的全部设置（JSON）
mizuoto config get tts.default_model
mizuoto config set tts.default_model qwen3tts/1.7b-custom-voice
mizuoto config set compute.unload_after_minutes 0
mizuoto config set paths.browse_roots '["/srv/audio", "/mnt/datasets"]'
mizuoto config set engines.qwen3tts.device cuda:1
mizuoto config set engines.cosyvoice.load_options.fp16 true
mizuoto config set tts.model_aliases.tts-1 qwen3tts/1.7b-custom-voice
mizuoto config set server.access_token "一个足够长的随机字符串"
mizuoto config set server.access_token null      # 清除令牌

• 键用点分隔，值按 JSON 解析（数字、true/false、列表、对象），解析不了时作为字符串；null 清除可以为空的设置。写入前整体校验，取值超出范围、类型不对或键不存在时报错（退出码 4），文件不变。
• 字典类的设置可以添加新键：engines.<引擎 id>.<字段>、engines.<引擎 id>.load_options.<选项>、tts.model_aliases.<别名>。mizuoto config set 不检查加载选项的名称和取值；网页界面和接口会按引擎清单检查。
• config show 和 config get 不显示令牌，只显示 access_token_configured、token_configured 是否已设置；config set 修改令牌后显示 (hidden)。config show 还列出 resolved_paths（留空的文件夹实际使用的路径）、env_overrides（生效的环境变量）和 pinned（嵌入方固定的设置）。
• 正在运行的服务器约 1 秒内读到文件的改动，打开的网页界面随之刷新；之后在网页界面保存设置时，会在文件当前内容的基础上合并，不会冲掉命令行的改动。文件写坏时服务器日志会警告 Ignored a change to … settings.toml，继续使用原来的设置。server.host、server.port 和证书要在下次启动服务器时生效；修改 engines.<id>.* 会卸载该引擎的模型，下次使用时按新设置加载。
• 读取 settings.toml 时，Mizuoto 不认识的键会被忽略。

环境变量复制锚点链接

mizuoto env vars 列出 Mizuoto 读取的环境变量，以及当前已设置的 MIZUOTO_* 变量：

覆盖设置的规则：

• 去掉前缀 MIZUOTO_ 后转为小写，__（两个下划线）表示下一级：MIZUOTO_COMPUTE__GPU_JOBS 对应 compute.gpu_jobs，MIZUOTO_ENGINES__QWEN3TTS__DEVICE 对应 engines.qwen3tts.device，MIZUOTO_REMOTE__AGENT__PORT 对应 remote.agent.port。
• 值能按 JSON 解析就按 JSON 解析（数字、true/false、列表、对象），否则作为字符串；null 或 none 表示空值。
• 只有名称中含 __ 的 MIZUOTO_* 变量才是设置覆盖。

export MIZUOTO_DATA_DIR=/data/mizuoto
export MIZUOTO_DOWNLOADS__SOURCE=hf-mirror
MIZUOTO_SERVER__PORT=8000 mizuoto webui

全部设置复制锚点链接

下表的"界面"一栏是网页界面 设置 中对应的位置；引擎相关的设置在 模型 › 引擎 的引擎卡片上。

server：服务器复制锚点链接

访问令牌、来源检查和 Host 检查见 HTTP 接口。

paths：文件夹复制锚点链接

compute：计算复制锚点链接

downloads：下载复制锚点链接

详见 模型下载与镜像。

tts：语音复制锚点链接

微批处理的条件见 性能与加速。

engines.<id>：每个引擎复制锚点链接

<id> 是引擎 id：qwen3tts、cosyvoice、f5tts、gptsovits、omnivoice、fishspeech、indextts、asr。没有出现在文件里的引擎使用默认值。

[engines.cosyvoice]
device = "cuda:1"
pinned_models = ["cosyvoice/cosyvoice2-0.5b"]

[engines.cosyvoice.load_options]
fp16 = true

training：训练复制锚点链接

outputs：结果复制锚点链接

remote：远程主机复制锚点链接

详见 远程主机。

远程主机在网页界面的 设置 › 远程主机 中添加，用 mizuoto remote add 更方便：它会检查主机是否响应。

示例 settings.toml复制锚点链接

[server]
host = "0.0.0.0"
port = 7869
access_token = "换成你自己的长随机字符串"

[downloads]
source = "hf-mirror"

[compute]
unload_after_minutes = 60
max_resident_models = 2

[tts]
default_model = "qwen3tts/1.7b-custom-voice"

[tts.model_aliases]
tts-1 = "qwen3tts/1.7b-custom-voice"

[engines.qwen3tts]
device = "cuda:0"

[engines.indextts]
device = "gpu-box/cuda:0"

[remote.hosts.gpu-box]
address = "192.168.1.20:7870"
token = "agent 打印出的令牌"