外部 API

本页说明 DLC 管理器当前已实现的外部 API。

API 同时支持：

• 客户端
• 服务端

启用 API

在 config.dc 或 config-server.dc 中配置 [api]：

[api]
apiEnabled = true
apiPort = 10086
apiToken = "your_token_here"

字段说明：

• apiEnabled：是否启用 API 服务
• apiPort：API 端口，默认 10086
• apiToken：鉴权用 Bearer Token

鉴权

所有接口都需要：

Authorization: Bearer <apiToken>

如果 apiToken 为空，所有请求都会被拒绝。

通用规则

• 基础路径：/api
• 返回格式：

成功：

{
  "ok": true,
  "data": {}
}

失败：

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Unknown API route."
  }
}

• 支持 OPTIONS 预检
• 已启用 CORS，Access-Control-Allow-Origin: *

基础接口

GET /api/ping

健康检查。

返回字段：

• service
• running
• mode

GET /api/version

返回 DLC/info/version.dc 的当前版本信息。

返回字段：

• base
• dlc
• rollback_from
• changelog_shown
• label

GET /api/state

返回 API 与运行时状态摘要。

返回字段：

• serverRunning
• dedicatedServer
• totalItems
• enabledItems
• counts

GET /api/dlc/list

返回按类型分组的 DLC 列表。

每个条目可能包含：

• id
• identifier
• name
• type
• enabled
• baselineEnabled
• pending
• hidden
• configType
• alarm
• allowEnableByAll
• appliedTarget
• sourcePath
• sourcePaths
• displayNames
• tips
• dependencies
• conflicts

GET /api/dlc/pending

返回当前待应用的 DLC 改动。

返回字段：

• count
• items
  • id
  • identifier
  • name
  • type
  • enabled
  • baselineEnabled
  • pending

DLC 根目录 / 配置文件接口

GET /api/dlc/root/list

列出 DLC 根目录下可编辑的 .dc 文件。

当前可访问范围限制为：

• <DLC>/info/**/*.dc
• <DLC>/remote/**/*.dc
• <DLC>/required/**/*.dc
• <DLC>/preset/**/*.dc
• <DLC>/update/**/*.dc
• <DLC>/notice.dc

返回字段：

• rootCount
• roots
  • rootIndex
  • rootPath
  • files
    • name
    • path
    • type
    • supported

POST /api/dc/detect-type

根据路径/文件名/内容识别配置类型。

请求体：

{
  "name": "example.dc",
  "path": "remote/example.dc",
  "content": "..."
}

返回字段：

• type
• supported

POST /api/dc/validate

校验 dc 配置内容。

请求体：

{
  "type": "remote",
  "content": "..."
}

返回字段：

• type
• supported
• valid
• issues

Issue 字段：

• severity
• source
• field
• message

POST /api/dc/read

从 DLC 工作区读取指定 dc 文件。

请求体：

{
  "path": "remote/example.dc",
  "rootIndex": 0
}

返回字段：

• name
• path
• rootIndex
• type
• supported
• content

POST /api/dc/write

向 DLC 工作区写入 dc 文件。

请求体：

{
  "path": "remote/example.dc",
  "rootIndex": 0,
  "type": "remote",
  "content": "..."
}

说明：

• 对当前支持的配置类型，写入前会先尝试解析。
• 工作区之外的路径会被拒绝。

返回字段：

• name
• path
• rootIndex
• type
• supported
• written

POST /api/notice/content

请求体：

{
  "url": "https://example.com/notice.md"
}

返回字段：

• url
• content

文件接口

POST /api/file/add

请求体：

{
  "path": "mods/example.jar",
  "content": "..."
}

或：

{
  "path": "config/example.txt",
  "contentBase64": "SGVsbG8="
}

或：

{
  "path": "mods/example.jar",
  "source": "downloads/example.jar"
}

创建目录：

{
  "path": "tmp/example",
  "directory": true
}

返回字段：

• path
• created
• directory

POST /api/file/del

请求体：

{
  "path": "mods/example.jar"
}

返回字段：

• path
• deleted

POST /api/file/mv

请求体：

{
  "from": "mods/example.jar",
  "to": "mods/example-disabled.jar"
}

返回字段：

• from
• to
• moved

POST /api/file/rename

请求体：

{
  "path": "mods/example.jar",
  "name": "example-disabled.jar"
}

返回字段：

• from
• to
• renamed

POST /api/file/upload

向游戏工作区内目标路径上传原始二进制文件内容。

参数：

• path：上传后的目标保存路径，位于游戏目录内，例如 mods/example.jar 或 config/example.txt

请求体：

• 原始二进制 body

支持的目标路径来源：

• 查询参数 path
• 请求头 X-Dlc-Path

返回字段：

• path
• uploaded
• size

DLC 应用接口

POST /api/dlc/enable

请求体：

{
  "id": "mod:...|a.jar"
}

或：

{
  "ids": ["mod:...|a.jar", "unknown:...|b.zip"]
}

也支持直接传 identifier：

{
  "identifier": "example_mod"
}

{
  "identifiers": ["example_mod", "example_pack"]
}

返回字段：

• enabled
• changes
• linkedChanges
• unknownIds
• unknownIdentifiers

POST /api/dlc/disable

请求体：

{
  "id": "mod:...|a.jar"
}

或：

{
  "ids": ["mod:...|a.jar", "unknown:...|b.zip"]
}

也支持直接传 identifier：

{
  "identifier": "example_mod"
}

{
  "identifiers": ["example_mod", "example_pack"]
}

返回字段：

• enabled
• changes
• linkedChanges
• unknownIds
• unknownIdentifiers

POST /api/dlc/apply

只应用当前已经处于待应用状态的 DLC 改动。

请求体：

{
  "mode": "restart"
}

支持的 mode：

• restart
• reload

返回字段：

• mode
• changedCount
• requiresRestart
• hotReloaded
• appliedChanges
• messages

Remote 接口

GET /api/remote/list

返回当前缺失的 remote 条目。

可选请求头：

X-Dlc-Lang: zh_cn

POST /api/remote/download

立即下载当前所有缺失的 remote 条目。

返回字段：

• success
• downloaded
• error

POST /api/remote/download/start

启动指定 key 的 remote 下载任务。

请求体：

{
  "keys": ["remote:key1", "remote:key2"],
  "lang": "zh_cn"
}

返回字段：

• status

GET /api/remote/download/status

返回当前 remote 下载任务状态。

可选请求头：

X-Dlc-Lang: zh_cn

Required 接口

GET /api/required/list

返回 required 资源条目列表。

可选请求头：

X-Dlc-Lang: zh_cn

POST /api/required/download/start

启动指定 id 的 required 下载任务。

请求体：

{
  "ids": ["id_a", "id_b"],
  "lang": "zh_cn"
}

返回字段：

• status

GET /api/required/download/status

返回当前 required 下载任务状态。

可选请求头：

X-Dlc-Lang: zh_cn

POST /api/required/download/cancel

取消当前 required 下载任务。

返回字段：

• canceled

POST /api/required/uninstall

卸载指定 required 资源。

请求体：

{
  "ids": ["id_a", "id_b"]
}

返回字段：

• removed

POST /api/required/apply

按 id 应用指定 required 资源。

请求体：

{
  "ids": ["id_a", "id_b"]
}

返回字段：

• applied

Update 接口

GET /api/update/state

返回当前更新状态与回滚历史。

返回字段：

• rollbackFrom
• rolledBack
• history

GET /api/update/list

返回当前可应用的更新包列表。

返回字段：

• hasUpdates
• updates

每个更新条目可能包含：

• name
• platform
• base
• base_new
• dlc
• dlc_new
• hidden
• changelog

POST /api/update/apply

应用更新。

若不传版本对，则默认应用当前检测到的整条更新链。

请求体：

{
  "baseOld": "1.0.0",
  "dlcOld": "1.0.0",
  "baseNew": "1.0.1",
  "dlcNew": "1.0.2"
}

返回字段：

• success
• missing
• message
• missingPaths
• addedRequired
• addedRemote

POST /api/update/rollback

回滚到目标版本。

请求体：

{
  "target": "1.0.0+1.0.0"
}

返回字段：

• success
• message
• version

POST /api/update/import

从游戏目录内已有 zip 导入更新包。

请求体：

{
  "path": "downloads/example-update.zip"
}

返回字段：

• success
• path

POST /api/update/import-url

从 URL 下载更新包后再导入。

请求体：

{
  "url": "https://example.com/update.zip",
  "fileName": "update.zip"
}

返回字段：

• success
• message
• downloadedPath