应用配置参考

查阅应用 API 的环境变量、默认值与校验限制。下方字段直接来自真实 Settings 的 JSON Schema，不读取你当前的环境变量，也不连接 Runtime。它不包含 ComfyUI 或模型环境配置。

选择独立的应用数据目录

在仓库根目录操作。Node、pnpm、uv 与独立 API 环境的准备见客户端指南。以下可选示例仅启动隔离的 fake 应用 API，适合练习业务操作；fake 不产生模型音乐。

$env:MUSIC_API_RUNTIME_MODE = "fake"
$env:MUSIC_API_DATA_DIR = "data/reference-example-fake"
uv run --project services/api --no-sync music-api serve --port 8000

从 /health 的 runtime.mode 核对模式，再创建 Project；退出自己的 API 进程后，本地数据仍保留。运行时变量不通过此文档写入。若数据目录已属于其他模式，选择新的目录；不要把 fake 项目目录切成真实模式。真实模式需要独立目录和新鲜的 owner receipt，按诊断指南准备。完整操作与失败恢复见生成与保存、重启恢复。

读取元数据

事实来源是应用 Settings；生成器复用 Settings metadata 的字段与环境变量映射。${REPOSITORY} 表示当前 checkout 根目录；生成器从实际 Path 默认值推导这个可移植标记，不公开机器绝对路径。JSON 区块保留类型、默认值、可选值与数值边界；没有默认值时不编造默认值。

data_dir 下的 app.sqlite 与 assets/ 是 Settings 派生的应用存储位置。上传字节/秒数预算不代表模型支持相同时长，实际能力见当前能力。读取配置不刷新 Runtime 诊断证据。变量不满足字段约束时，API 启动会拒绝配置；修正变量后重新启动自己的进程。生效值还可能由启动命令的显式参数覆盖，例如 --data-dir。

环境变量索引

• MUSIC_API_DATA_DIR
• MUSIC_API_MAX_UPLOAD_BYTES
• MUSIC_API_MAX_AUDIO_SECONDS
• MUSIC_API_RUNTIME_MODE
• MUSIC_API_RUNTIME_URL
• MUSIC_API_RUNTIME_TIMEOUT_SECONDS
• MUSIC_API_RUNTIME_EVIDENCE_PATH
• MUSIC_API_DIAGNOSTICS_MAX_AGE_SECONDS
• MUSIC_API_RECOVERY_CONFIRMATION_WINDOW_SECONDS
• MUSIC_API_RECOVERY_MAX_ATTEMPTS
• MUSIC_API_RECOVERY_POLL_INTERVAL_SECONDS
• MUSIC_API_RECOVERY_MAX_POLL_INTERVAL_SECONDS

MUSIC_API_DATA_DIR

Settings 字段: data_dir.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": "${REPOSITORY}/data",
  "format": "path",
  "title": "Data Dir",
  "type": "string"
}

MUSIC_API_MAX_UPLOAD_BYTES

Settings 字段: max_upload_bytes.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 67108864,
  "exclusiveMinimum": 0,
  "title": "Max Upload Bytes",
  "type": "integer"
}

MUSIC_API_MAX_AUDIO_SECONDS

Settings 字段: max_audio_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 600,
  "exclusiveMinimum": 0,
  "title": "Max Audio Seconds",
  "type": "number"
}

MUSIC_API_RUNTIME_MODE

Settings 字段: runtime_mode.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": "fake",
  "description": "Identifiable Runtime mode; each mode owns an isolated data namespace.",
  "enum": [
    "fake",
    "comfyui"
  ],
  "title": "Runtime Mode",
  "type": "string"
}

MUSIC_API_RUNTIME_URL

Settings 字段: runtime_url.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": "http://127.0.0.1:8188",
  "description": "Loopback ComfyUI URL, used only in explicit comfyui mode.",
  "title": "Runtime Url",
  "type": "string"
}

MUSIC_API_RUNTIME_TIMEOUT_SECONDS

Settings 字段: runtime_timeout_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 10,
  "description": "Bounded native HTTP timeout.",
  "exclusiveMinimum": 0,
  "title": "Runtime Timeout Seconds",
  "type": "number"
}

MUSIC_API_RUNTIME_EVIDENCE_PATH

Settings 字段: runtime_evidence_path.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "anyOf": [
    {
      "format": "path",
      "type": "string"
    },
    {
      "type": "null"
    }
  ],
  "default": null,
  "description": "Read-only owner receipt; reading it does not renew its source timestamps.",
  "title": "Runtime Evidence Path"
}

MUSIC_API_DIAGNOSTICS_MAX_AGE_SECONDS

Settings 字段: diagnostics_max_age_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 300,
  "description": "Freshness policy for observed readiness and immutable owner evidence.",
  "exclusiveMinimum": 0,
  "title": "Diagnostics Max Age Seconds",
  "type": "number"
}

MUSIC_API_RECOVERY_CONFIRMATION_WINDOW_SECONDS

Settings 字段: recovery_confirmation_window_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 300,
  "description": "Durable confirmation budget for uncertain original Runtime work; API restarts do not renew it.",
  "exclusiveMinimum": 0,
  "title": "Recovery Confirmation Window Seconds",
  "type": "number"
}

MUSIC_API_RECOVERY_MAX_ATTEMPTS

Settings 字段: recovery_max_attempts.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 30,
  "description": "Persisted attempt limit when original Runtime work is unconfirmed.",
  "exclusiveMinimum": 0,
  "title": "Recovery Max Attempts",
  "type": "integer"
}

MUSIC_API_RECOVERY_POLL_INTERVAL_SECONDS

Settings 字段: recovery_poll_interval_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 1,
  "description": "Initial bounded recovery polling interval.",
  "exclusiveMinimum": 0,
  "title": "Recovery Poll Interval Seconds",
  "type": "number"
}

MUSIC_API_RECOVERY_MAX_POLL_INTERVAL_SECONDS

Settings 字段: recovery_max_poll_interval_seconds.

来自 Settings 的类型、默认值、可选值与验证限制：

{
  "default": 10,
  "description": "Maximum recovery polling interval.",
  "exclusiveMinimum": 0,
  "title": "Recovery Max Poll Interval Seconds",
  "type": "number"
}

源码版本: 1ce3268正文来源: docs/reference/settings.md