{"id":19715446,"url":"https://github.com/unblockneteasemusic/server-rust","last_synced_at":"2025-05-16T19:04:07.597Z","repository":{"id":36974904,"uuid":"408175882","full_name":"UnblockNeteaseMusic/server-rust","owner":"UnblockNeteaseMusic","description":"Rust 版本的 UnblockNeteaseMusic/server ，以效能、穩定性及可維護性為目標。","archived":false,"fork":false,"pushed_at":"2024-06-08T02:32:36.000Z","size":1892,"stargazers_count":274,"open_issues_count":22,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-16T19:02:32.843Z","etag":null,"topics":["netease","rust","unblock"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UnblockNeteaseMusic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-19T16:17:54.000Z","updated_at":"2025-05-07T09:50:16.000Z","dependencies_parsed_at":"2024-06-19T17:12:51.112Z","dependency_job_id":"4571b336-275a-409f-bcff-769478620af9","html_url":"https://github.com/UnblockNeteaseMusic/server-rust","commit_stats":{"total_commits":504,"total_committers":3,"mean_commits":168.0,"dds":0.1527777777777778,"last_synced_commit":"b8fc46976cec8c5cea92616c9fae2723713cfe3d"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnblockNeteaseMusic%2Fserver-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnblockNeteaseMusic%2Fserver-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnblockNeteaseMusic%2Fserver-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UnblockNeteaseMusic%2Fserver-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UnblockNeteaseMusic","download_url":"https://codeload.github.com/UnblockNeteaseMusic/server-rust/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254592368,"owners_count":22097011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["netease","rust","unblock"],"created_at":"2024-11-11T22:38:25.142Z","updated_at":"2025-05-16T19:04:07.564Z","avatar_url":"https://github.com/UnblockNeteaseMusic.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `UnblockNeteaseMusic/server-rust`\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FUnblockNeteaseMusic%2Fserver-rust.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FUnblockNeteaseMusic%2Fserver-rust?ref=badge_shield)\n\nRust 版本的 [UnblockNeteaseMusic/server](https://github.com/UnblockNeteaseMusic/server)，以效能、穩定性及可維護性為目標。\n\n\u003e 目前使用者文件及開發文件 **仍在撰寫**，在此之前有任何問題，歡迎開 Discussion 詢問。\n\n## ⚠️ 免責聲明 Disclaimer\n\n- 本函式庫僅供 **個人學習及研究** Rust 網路服務之使用，並 **未用於營利用途**。\n- 除授權條款列載之事項，您亦已知將此函式庫用於商業或其他競爭行為上，**有可能會引來法律風險**。\n- 若您認為本函式庫侵犯您的智慧財產權，**請發出 PR、Issue 或 DMCA 請求，表達您想移除相關引擎或程式碼之意願**。\n\n## 架構\n\n\u003e 註：目前 UnblockNeteaseMusic/server 只實作 engine/resolver 的部分。\n\n- `crypto`：與加密相關的函式庫，如 md5、aes128 等。\n- `engine-base`：Engine 的抽象部分，包含一個 Engine 應有的介面、整合所有 Engines 的 Executor 等。\n- `engines`\n  - 這目錄底下的是官方提供的引擎，所有引擎都是選擇性依賴、使用的。\n  - 您可以自行實作其他平台，並發佈到 crates.io（當然也歡迎發 PR 讓引擎納入本 codebase 一併管理）。\n  - 每個 Engine 都有 `examples` 方便測試單一引擎模組。如您是開發者，可仿造其它引擎，撰寫自己的 example。\n- `api-utils`：用來開發 UNM 的實用工具。\n- `request`：UNM 的 reqwest 封裝，自動帶上 `User-Agent` 等 headers。\n- `selector`：包含選擇最適音樂項目的演算法。\n- `types`：UNM 的各種基礎類型（如 `Song`、`Artist`⋯⋯）\n- `test-utils`：方便撰寫測試方法及 demo 的工具集。\n- `napi`：Node.js 的 UNM (Rust) 綁定。\n  - 這個綁定因 napi 限制，目前不像 Rust 版一樣有方便的擴充系統。\n  - 原則上是啟用 `engines/` 底下的所有引擎。\n- `rest-api`：UNM 的 RESTful API\n  - 因安全性疑慮，目前不考慮為 RESTful API 提供不修改程式碼的擴充方案。\n  - 原則上是啟用 `engines/` 底下的所有引擎。\n- `demo`：用來測試及展示 UNM (Rust) 的 demo 程式。\n  - 啟動 Demo：`cargo run --release --bin unm_engine_demo`\n\n## 使用\n\n### Rust 函式庫\n\n\u003e 可以參考 `engine-demo` 的用法～\n\n首先，您需要從 \u003chttps://crates.io\u003e 引用至少三個元件：\n\n- `unm_engine`：包含並行查詢音源結果的 Executor。\n- `unm_engine_[想要的引擎]`：用來從音源搜尋的引擎。\n- `unm_types`：UNM 的基礎類型。撰寫函數時十分需要。\n\n然後，我們可以註冊音源：\n\n```rust\nuse unm_engine::executor::Executor;\nuse unm_engine_bilibili::{BilibiliEngine, ENGINE_ID as BILIBILI_ENGINE_ID};\n\nlet mut executor = Executor::new();\nexecutor.register(BILIBILI_ENGINE_ID, BilibiliEngine::new());\n\n// 您也可以直接使用官方預設的引擎集，免去手動註冊的麻煩。\n// 首先得引入 `unm_api_utils`，然後就可以：\n\nuse unm_api_utils::executor::build_full_executor;\nlet executor = build_full_executor();\n```\n\n接著就可以直接使用 executor 提供的方法搜尋及取回結果了：\n\n```rust\nuse unm_types::{Song, Artist, Context};\n\nlet context = Context::default();\n\nlet search_result = executor.search(\u0026[BILIBILI_ENGINE_ID], Song {\n  id: \"\".to_string(),\n  name: \"TT\",\n  artists: vec![\n    Artist {\n      id: \"\".to_string(),\n      name: \"Twice\",\n    },\n  ],\n}, \u0026context).await?;\n\nlet result = executor.retrieve(\u0026search_result, \u0026context).await?;\n```\n\n### TypeScript (JS) 函式庫\n\n請參考 [napi 的 README.md](https://github.com/UnblockNeteaseMusic/server-rust/blob/main/napi/README.md)。\n\n### RESTful API\n\n請參考 [UNM REST API 的 README.md](https://github.com/UnblockNeteaseMusic/server-rust/blob/main/rest-api/README.md)\n\n## 設定\n\n### 支援的所有引擎\n\nN-API 和 RESTful API 支援的引擎（以下簡稱「預設引擎集」）與我們上架到 \u003chttps://crates.io\u003e 的引擎略有差異。\n\n| 名稱             | 引擎 ID    | 注意事項                                                        | 預設引擎集 |\n| ---------------- | ---------- | --------------------------------------------------------------- | ---------- |\n| Bilbili Music    | `bilibili` |                                                                 | ✅         |\n| 酷狗音乐         | `kugou`    |                                                                 | ✅         |\n| 酷我音乐         | `kuwo`     | 目前僅支援 320kbps MP3                                          | ✅         |\n| 咪咕音乐         | `migu`     |                                                                 |            |\n| JOOX             | `joox`     | 需要設定 `joox:cookie`，見引擎文件。                            | ✅         |\n| YtDl             | `ytdl`     | 預設使用的 `youtube-dl` 後端是 `yt-dlp`，可設定 `ytdl:exe` 調整 | ✅         |\n| 第三方網易雲 API | `pyncm`    |                                                                 | ✅         |\n| QQ音乐          | `qq`       | 需要設定 `qq:cookie`，見引擎文件。                              | ✅         |\n\n- `migu` 的 API 壞掉了。等到有更好的 API 會再更新。\n\n#### 引擎文件\n\n- JOOX 引擎：\u003chttps://docs.rs/unm_engine_joox\u003e\n- YtDl 引擎：\u003chttps://docs.rs/unm_engine_ytdl\u003e\n- QQ 引擎：\u003chttps://docs.rs/unm_engine_qq\u003e\n\n### 設定全域通用設定（`Context`）\n\n全域通用設定（`Context`）包含以下這些設定：\n\n- `proxy_uri`：要在引擎使用的 Proxy 伺服器。選填。\n- `enable_flac`：是否抓取 FLAC 音訊？預設值是 `false`。\n- `search_mode`：搜尋模式\n  - 可以設定是以「速度為主」（FastFirst）或者是以「順序為主」（OrderFirst）進行搜尋\n  - 範例請見 \u003chttps://docs.rs/unm_types/0.2.0-pre.4/unm_types/enum.SearchMode.html\u003e\n- `config`：各引擎設定，見下〈設定引擎特定設定（`Config`）〉\n\n假如您使用 Rust 版，您可以使用 [`ContextBuilder`](https://docs.rs/unm_types/latest/unm_types/struct.ContextBuilder.html) 建構 Context：\n\n```rs\nuse unm_types::{ContextBuilder, SearchMode};\n\nlet context = ContextBuilder::default()\n  .proxy_uri(\"https://www.google.com\")\n  .search_mode(SearchMode::OrderFirst)\n  .build();\n```\n\n如果是使用 JavaScript 版，您可以根據 [UNM 的類型定義（VS Code 會提供補全建議）](https://github.com/UnblockNeteaseMusic/server-rust/blob/main/napi/index.d.ts) 建構 `Object` 即可：\n\n```js\nconst UNM = require(\"@unblockneteasemusic/rust-napi\");\n\n// TS 的語法是 `const context: UNM.Context = {}`\n/** @type {UNM.Context} */\nconst context = {\n  proxyUri: \"https://www.google.com\",\n  searchMode: UNM.SearchMode.OrderFirst,\n};\n```\n\n#### 設定引擎特定設定（`Config`）\n\n「引擎特定設定」是每個引擎針對自己的需要，從 `Config` 取得需要的設定。\n設定方法請見 [`engines/README.md`](https://github.com/UnblockNeteaseMusic/server-rust/blob/main/engines/README.md)\n\n## 貢獻\n\n### 檢查程式碼的相關命令\n\n```bash\ncargo check  # 檢查程式碼是否合法 (valid)\ncargo test   # 執行本 codebase 的所有 Tests\ncargo clippy # Rust linter\n```\n\nUNM (Rust) 的 CI 也會在程式碼 push 後自動執行上述命令，\n進行程式碼測試與檢查。\n\n### 貢獻引擎後的建議事項\n\n引擎的 crate 名稱格式是：`unm_engine_[引擎名稱]`，放置在 `/engines/[引擎名稱]` 目錄。\n\n建議仿照其它引擎，在 `engine-demo` 和 `napi` 註冊自己的音源。\n註冊音源有 macro 協助，語法目前是這樣的：\n\n```rust\npush_engine!([引擎名稱]: [引擎實體]);\n```\n\n範例如下：\n\n```rust\npush_engine!(bilibili: BilibiliEngine);\n```\n\n## 授權條款\n\nThis project is licensed under [LGPL-3.0-only](https://spdx.org/licenses/LGPL-3.0-only.html).\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FUnblockNeteaseMusic%2Fserver-rust.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FUnblockNeteaseMusic%2Fserver-rust?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funblockneteasemusic%2Fserver-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funblockneteasemusic%2Fserver-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funblockneteasemusic%2Fserver-rust/lists"}