原文
内部服务与上游边界
本页用于服务端维护，不是公网客户端接入说明。内部主机名只在部署网络中解析；不要暴露端口8770/8780内部路径，或向第三方发送内部密钥。
1. 管理内部统计
基地址 http://watch-music-admin:8780。均为POST，头 X-Admin-Internal: <INTERNAL_SECRET>；JSON对象，Content-Length明确，最多65536字节。非POST或密钥不匹配返回404，不向未授权请求暴露内部功能。
1.1 POST /internal/events
body {events: Event[]}，最多128条；网关正常批次最多64条。
Event字段：ip有效IPv4/IPv6、device可选32位小写hex实例ID、version最多保留32字符、variant最多保留16字符。不提供关键词、播放内容、媒体URL或硬件标识。
200 {ok:true}。无效事件可跳过；events不是数组或超128条为400。此接口信任内部网关已验证设备令牌，不让客户端直接上报任意设备ID。
无设备的IP以私有HMAC派生活动ID，kind=legacy_ip；有设备kind=device。撤回实例单向哈希标记存在时过滤该事件。活动最多50000行并保留30天，审计最多10000行并清理30天前内容。
1.2 POST /internal/register
body {ip:string,consent:true,version?:string,variant?:string}。
200 {token,device_id,online_window_seconds:300,retention_days:30}，与公开register结果相同。400IP/consent错误；403IP被禁；429每IP每小时5次。服务器生成随机实例与HMAC令牌。
1.3 POST /internal/forget
body {token:string}。200 {ok:true}；400凭证无效。删除实例统计并写30天单向哈希撤回标记，不解封设备/IP。
网关调用超时2秒；事件队列失败允许丢失，不无界重试。注册/撤回错误会转给公开调用者。内部密钥与管理员Cookie、CSRF、SSH密码都不是同一概念。
2. LX运行时
基地址 http://watch-music-lx:8770。当前协议本身没有公网认证；安全依赖私有网络、不暴露端口、网关只允许已知注册脚本及服务器歌曲。
2.1 GET /plugins
精确路径，无query合同。200：{plugins:Plugin[],runtime:"quickjs-isolated-process",notice:string}。
注册表仅列启用项，校验schema/id/完整哈希；条目含id/name/version/sha256/imported和进程内最近status/detail/sources/checked_at。此内部目录没有网关追加的默认别名；网关再过滤启用策略并投影最近取流状态。
其他路径404。目录生成异常不保证统一JSON错误，应由网关处理为503。
2.2 POST /run
| body字段 | 类型 | 要求 |
|---|---|---|
plugin |
string | 当前注册且启用的真实插件ID，不是默认别名 |
action |
string | probe/musicUrl/lyric/pic |
source |
string | 非probe通常需要wy/tx/kg/kw/mg，必须在脚本初始化声明中 |
quality |
string | 默认128k；musicUrl要求在声明qualitys中 |
musicInfo |
object | 服务器构造的歌曲元数据；probe无需 |
示例：
{"plugin":"0123456789abcdef","action":"musicUrl","source":"wy","quality":"128k","musicInfo":{"name":"示例歌曲","singer":"示例歌手","id":"123456","songmid":"123456","albumName":"示例专辑","interval":"240"}}
网关基础musicInfo包括name/singer/songmid/id/albumName/interval；kg加hash、mg加copyrightId，并仅复制内部extra中的albumId/albumMid/strMediaMid/albumAudioId/_types/types/hash/songmid/copyrightId等允许字段。公开客户端不应构造这些字段绕过歌曲索引。
200正常业务结果：
{"ok":true,"value":"https://public-audio.example.invalid/example.mp3"}
这里URL只是说明；内部可能返回value对象，实际不可假定总是字符串。probe成功为{ok:true,state:"initialized",sources,detail}。
内部HTTP200可能业务失败：{ok:false,detail,error?}，例如执行失败、超时或资源超限。网关probe转422并保留结果；resolve/lyric转422 {error:detail}。body长度非法/插件或动作无效400；双槽忙429；未预期异常500。非/run路径404。
运行时虽接受pic，当前公开网关没有plugin_pic接口；不能把内部动作枚举当作公网可调用接口。
2.3 隔离限制
每次创建工作进程，超时28秒，CPU8秒、地址空间180MiB、输出文件1MiB、文件描述符32；QuickJS上下文内存40MiB、栈1MiB。脚本最多14个外部请求，支持GET/POST/HEAD，body小于128KiB，响应最多2MiB，单请求超时1..8秒。
外部请求通过safenet公共网络校验；不允许任意内网访问。运行时结果不能证明完整音频有效，音频字节由网关在真正取流时验证。脚本初始化/质量声明也不是授权凭证。
3. go-music-dl上游
默认前缀 /music，端口8080。它的HTML片段路由、配置、本地文件、登录及收藏功能是上游应用能力，并未等价公开为Wristhyme接口。
3.1 网关实际使用的路由
| 方法/上游路径 | 参数 | 典型响应/用途 |
|---|---|---|
GET /music/search |
q/sources/type/page_size/page | song/playlist的HTML片段，网关提取data-* |
GET /music/playlist |
source/id/page_size/page | 歌曲HTML及当前页/总页数标记 |
GET /music/recommend |
sources | 公开推荐HTML，轻量网关去重切页 |
GET /music/inspect |
id/source/duration/extra等服务器歌曲字段 | JSON valid/url/size/bitrate，网关移除url |
GET /music/lyric |
服务器歌曲字段、format=lrc | 原始歌词文本 |
GET /music/download |
服务器歌曲字段、stream=1 | 音频；可转发Range |
netease_catalog通过专用Go helper执行官方元数据搜索，不要求通用上游HTML支持相同search_signals；hot_charts访问固定官方主机，不能据此增加任意外部API代理能力。
3.2 上游源码路由索引
下表仅为本地vendor路由盘点，便于维护者定位源码，不是宣称生产上游已部署同版或已对公网开放。上游配置/登录/文件接口的完整细节应在单独维护上游项目时按其当前版本核对，不复用Wristhyme的Cookie/CSRF/设备头。
| 文件（vendor/go-music-dl/internal/web/） | 已注册相对路径和方法 |
|---|---|
| music.go | GET /、/recommend、/user_playlists、/playlist_categories、/category_playlists、/search、/playlist、/album、/album_jump、/inspect、/switch_source、/cover_proxy、/lyric |
| music.go | GET/POST /download、/download_lrc、/download_cover；GET/DELETE /api/downloads/records；POST /api/downloads/precheck |
| local_music.go | GET /local_music_page、/local_music、/local_music/duplicates；GET/POST /local_music/cover；POST /local_music/upload、/local_music/batch_match、/local_music/auto_cache、/local_music/reindex；DELETE /local_music |
| collection.go | GET /my_collections、/collection；收藏分组/collections下GET/POST空路径、POST /import、PUT/DELETE /:id、GET/POST/DELETE /:id/songs、POST /:id/songs/batch |
| local_music.go | 收藏分组下POST /:id/local_music、/:id/local_music/batch |
| auth.go | GET/POST /setup、/login；POST /logout |
| qr_login.go | GET/POST /qr_login/:source |
| update.go | GET /app_update/check、/github_proxy/test |
| server.go | GET /healthz、/render、/cookies、/settings及静态资源；POST /cookies、/settings |
拼接前缀后例如/music/api/downloads/records，不是/api/downloads/records。不要把vendor登录、Cookies读写、本地音乐上传/删除代理成公开接口；这些有不同的安全边界。
4. 反向代理与部署
已找到的Caddy配置：/admin及子路径代理8780；/downloads/*静态服务；/和/LICENSE静态服务；其他路径代理8766。代理覆盖X-Real-IP并移除外来X-Admin-Internal。
后台body代理限制1500KB，其他网关body4KB；后台响应头等待15秒，音乐55秒。这些是配置证据，不是当前线上已重新核验的数值。发布feed的缓存处理也可能有后续改动，以生产Caddy文件为准。
只有公开文档中的路径可作为客户端合同；运行时内部/run、管理/internal、go-music-dl配置等不应因代理兜底或源码存在被当作已开放API。