{"id":50419796,"url":"https://github.com/songloft-org/songloft","last_synced_at":"2026-06-09T05:01:53.851Z","repository":{"id":338341421,"uuid":"1151210358","full_name":"songloft-org/songloft","owner":"songloft-org","description":"🎵 面向个人用户的自托管音乐服务器","archived":false,"fork":false,"pushed_at":"2026-05-29T04:01:45.000Z","size":1407,"stargazers_count":221,"open_issues_count":19,"forks_count":18,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-29T04:05:33.344Z","etag":null,"topics":["docker","docker-compose","home-server","mimusic","music","music-player","music-server","nas","xiaomusic"],"latest_commit_sha":null,"homepage":"http://mimusic.hanxi.cc/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/songloft-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["hanxi"],"custom":["https://afdian.com/a/imhanxi"]}},"created_at":"2026-02-06T07:20:42.000Z","updated_at":"2026-05-29T03:44:50.000Z","dependencies_parsed_at":"2026-03-24T11:03:19.641Z","dependency_job_id":"c721587d-aa3f-447b-9bce-e1cbb99e36e1","html_url":"https://github.com/songloft-org/songloft","commit_stats":null,"previous_names":["mimusic-org/mimusic","songloft-org/songloft"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/songloft-org/songloft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/songloft-org%2Fsongloft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/songloft-org%2Fsongloft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/songloft-org%2Fsongloft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/songloft-org%2Fsongloft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/songloft-org","download_url":"https://codeload.github.com/songloft-org/songloft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/songloft-org%2Fsongloft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33723549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["docker","docker-compose","home-server","mimusic","music","music-player","music-server","nas","xiaomusic"],"created_at":"2026-05-31T08:00:35.454Z","updated_at":"2026-05-31T08:00:40.853Z","avatar_url":"https://github.com/songloft-org.png","language":"Go","funding_links":["https://github.com/sponsors/hanxi","https://afdian.com/a/imhanxi"],"categories":[],"sub_categories":[],"readme":"# 🎵 Songloft 快速使用指南\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/songloft-org/songloft/main/docs/public/social-preview.png\" alt=\"Songloft\" width=\"640\"\u003e\n\u003c/p\u003e\n\n[![GitHub License](https://img.shields.io/github/license/songloft-org/songloft)](https://github.com/songloft-org/songloft)\n[![Docker Image Version](https://img.shields.io/docker/v/songloft/songloft?sort=semver\u0026label=docker%20image)](https://hub.docker.com/r/songloft/songloft)\n[![Docker Pulls](https://img.shields.io/docker/pulls/songloft/songloft)](https://hub.docker.com/r/songloft/songloft)\n[![GitHub Release](https://img.shields.io/github/v/release/songloft-org/songloft)](https://github.com/songloft-org/songloft/releases)\n[![Visitors](https://api.visitorbadge.io/api/daily?path=songloft-org%2Fsongloft\u0026label=daily%20visitor\u0026countColor=%232ccce4\u0026style=flat)](https://visitorbadge.io/status?path=songloft-org%2Fsongloft)\n[![Visitors](https://api.visitorbadge.io/api/visitors?path=songloft-org%2Fsongloft\u0026label=total%20visitor\u0026countColor=%232ccce4\u0026style=flat)](https://visitorbadge.io/status?path=songloft-org%2Fsongloft)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🎵 面向个人用户的自托管音乐服务器 — 仅管理你合法拥有的音乐\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003e 📣 **关于改名**：本项目自 v2.0 起由 **MiMusic** 更名为 **Songloft**（内核与功能不变，仅品牌升级）。老的 `mimusic-org` GitHub 组织与 `hanxi/mimusic` Docker 镜像保留至少一年作跳转，但不再更新。详见 [GitHub Releases](https://github.com/songloft-org/songloft/releases)。\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/songloft-org/songloft\"\u003e🏠 GitHub\u003c/a\u003e •\n  \u003ca href=\"https://github.com/songloft-org/songloft/releases\"\u003e📥 下载\u003c/a\u003e •\n  \u003ca href=\"https://songloft.hanxi.cc\"\u003e📖 文档\u003c/a\u003e •\n  \u003ca href=\"https://github.com/songloft-org/songloft/issues\"\u003e💬 问题反馈\u003c/a\u003e •\n  \u003ca href=\"https://github.com/songloft-org/songloft/issues/2\"\u003e👥 微信群\u003c/a\u003e •\n  \u003ca href=\"https://github.com/songloft-org/songloft/issues/6\"\u003e📸 截图\u003c/a\u003e\n\u003c/p\u003e\n\n\n## ✨ 核心功能\n\n- 🎵 **本地音乐管理** — 扫描本地目录，自动提取 MP3/FLAC/WAV/APE/OGG/M4A 等格式的封面和元数据\n- 🧩 **JS 插件体系** — 基于 QuickJS 沙箱运行，支持权限模型、健康检查、热更新，可自由扩展音源 / 元数据 / 设备控制等能力\n- 📱 **跨平台客户端** — Flutter 客户端支持 Android、iOS、macOS、Windows、Linux、Web 六端\n- 🌐 **Web 界面** — 完整版内置 Web 前端，开箱即用\n- 🔑 **JWT 认证** — 双 Token 机制（Access Token + Refresh Token），支持多设备管理\n- 📡 **网络歌曲 \u0026 电台** — 支持添加你已合法获取的网络音频 URL 与电台\n- 🔁 **歌单转本地** — 把你**已合法持有的**网络音频 URL 离线落盘到本地音乐库，按歌单分目录、可读文件名命名，转换后回写元数据 / 封面 / 歌词。⚠️ 仅限本人合法持有使用权的内容；下载未授权的版权资源属于侵权，由使用者自行承担责任\n- 🔌 **完整 REST API** — 内置 Swagger 文档，方便集成和二次开发\n- ⚡ **轻量高效** — Go 编写，CGO-free，无外部依赖，适合 NAS / 树莓派等低功耗设备\n\n## ⚖️ 版权与免责声明\n\nSongloft 是一款**面向个人用户的自托管工具**，定位为帮助用户管理自己合法拥有的音乐文件。在使用本项目前，请务必阅读并理解以下条款：\n\n- 🚫 **不提供任何音乐内容** — Songloft 本身不内置、不分发、不存储任何受版权保护的音乐资源，仅是一个供你管理本地音乐库的开源软件\n- ✅ **请仅管理合法来源的音乐** — 用户应仅使用 Songloft 管理自己合法获得的音乐文件，包括但不限于：\n  - 自行购买并下载的数字音乐\n  - 从实体唱片转录的个人备份\n  - 自己创作或录制的作品\n  - 公有领域（Public Domain）作品\n  - 明确以 CC（Creative Commons）等开源协议授权的作品\n- 🔌 **第三方插件免责** — JS 插件由第三方社区维护，**主仓库不预置、不分发任何第三方音源插件成品**。插件接入的任何网络音源、元数据、歌词内容版权均归原权利人所有。**使用网络音源、歌单转本地等功能下载或转存内容时，用户须自行承担版权合规责任**，并遵守所在国家 / 地区的法律法规\n- 🏠 **仅供个人非商业使用** — 严禁将本项目用于商业用途、对外公开分发版权内容，或搭建面向不特定多数人的公共服务\n- ⚠️ **责任自担** — 因不当使用本项目（包括但不限于侵犯第三方版权）所引发的任何法律责任、纠纷或损失，均由使用者本人承担，本项目作者及贡献者不承担任何责任\n- ™️ **商标声明** — 本项目及内置插件中提到的所有品牌、协议、产品名称（包括但不限于「MIoT」「Bluetooth」「Android」「iOS」「macOS」「Windows」「Docker」等）均归各自商标权人所有。相关名称的出现仅出于互操作和指示性合理使用目的，**Songloft 与上述商标持有人无任何关联，也未获得任何形式的授权或背书**。详见 [NOTICE](./NOTICE)\n- 🔒 **隐私** — Songloft 服务端**不内置任何遥测**，所有数据保存在你本地。详见 [PRIVACY.md](./PRIVACY.md)\n\n\u003e 💡 我们尊重并支持知识产权保护。如果你喜欢某位艺术家的作品，请通过正版渠道购买或订阅以支持创作者。\n\n## 📋 版本说明\n\nSongloft 提供两种版本，满足不同使用场景：\n\n| 版本 | 后缀 | 说明 | 适用场景 |\n|------|------|------|----------|\n| 🌟 **完整版** | 无后缀 | 包含 Web 前端，开箱即用 | 推荐初次使用，访问服务地址即可看到 Web 界面 |\n| 📦 **精简版** | `-lite` | 不包含 Web 前端，体积更小 | 配合 Flutter 桌面/移动客户端，或前后端分离部署 |\n\n\u003e 💡 **推荐**：初次使用直接下载默认的 **完整版**，开箱即用，无需额外配置前端。\n\n## 🖥️ 平台支持\n\n### 📦 二进制文件\n\n#### 🌟 完整版（推荐）\n\n包含 Web 前端，开箱即用：\n\n| 平台 | 架构 | 下载链接 |\n|------|------|--------|\n| 🐧 Linux | x86_64 | [songloft-linux-amd64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64) |\n| 🐧 Linux | ARM64 | [songloft-linux-arm64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-arm64) |\n| 🐧 Linux | ARMv7 | [songloft-linux-armv7](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-armv7) |\n| 🍎 macOS | x86_64 (Intel) | [songloft-darwin-amd64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-amd64) |\n| 🍎 macOS | ARM64 (Apple Silicon) | [songloft-darwin-arm64](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-arm64) |\n| 🪟 Windows | x86_64 | [songloft-windows-amd64.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-amd64.exe) |\n| 🪟 Windows | ARM64 | [songloft-windows-arm64.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-arm64.exe) |\n\n#### 📦 精简版（Lite）\n\n不包含 Web 前端，体积更小：\n\n| 平台 | 架构 | 下载链接 |\n|------|------|--------|\n| 🐧 Linux | x86_64 | [songloft-linux-amd64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64-lite) |\n| 🐧 Linux | ARM64 | [songloft-linux-arm64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-arm64-lite) |\n| 🐧 Linux | ARMv7 | [songloft-linux-armv7-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-armv7-lite) |\n| 🍎 macOS | x86_64 (Intel) | [songloft-darwin-amd64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-amd64-lite) |\n| 🍎 macOS | ARM64 (Apple Silicon) | [songloft-darwin-arm64-lite](https://github.com/songloft-org/songloft/releases/latest/download/songloft-darwin-arm64-lite) |\n| 🪟 Windows | x86_64 | [songloft-windows-amd64-lite.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-amd64-lite.exe) |\n| 🪟 Windows | ARM64 | [songloft-windows-arm64-lite.exe](https://github.com/songloft-org/songloft/releases/latest/download/songloft-windows-arm64-lite.exe) |\n\n### 🐳 Docker 镜像\n\n#### 🌟 完整版（推荐）\n\n| 平台 | 下载链接 |\n|------|--------|\n| 🐧 Linux x86_64 | [songloft-docker-linux-amd64.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar) |\n| 🐧 Linux ARM64 | [songloft-docker-linux-arm64.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm64.tar) |\n| 🐧 Linux ARMv7 | [songloft-docker-linux-arm-v7.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm-v7.tar) |\n\n#### 📦 精简版（Lite）\n\n| 平台 | 下载链接 |\n|------|--------|\n| 🐧 Linux x86_64 | [songloft-docker-linux-amd64-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64-lite.tar) |\n| 🐧 Linux ARM64 | [songloft-docker-linux-arm64-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm64-lite.tar) |\n| 🐧 Linux ARMv7 | [songloft-docker-linux-arm-v7-lite.tar](https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-arm-v7-lite.tar) |\n\n### 📱 Flutter 客户端\n\n除了 Web 界面，Songloft 还提供功能更强大的跨平台 Flutter 客户端，支持后台播放、本地缓存、媒体控制（耳机/锁屏/通知栏）等服务端 Web 界面无法实现的能力，覆盖 iOS、Android、macOS、Windows、Linux 和 Web 六端。\n\n🔗 **GitHub 仓库**：[songloft-org/songloft-player](https://github.com/songloft-org/songloft-player)\n📥 **下载**：[GitHub Releases](https://github.com/songloft-org/songloft-player/releases/latest)\n\n\u003e 💡 使用 **精简版（-lite）** 服务端时，推荐直接搭配 Flutter 客户端使用（无需额外部署 Web 前端）；如确实需要独立 Web 前端，可参考 [songloft-player](https://github.com/songloft-org/songloft-player) 仓库的 `flutter build web` 流程自行构建并由 Nginx 等反向代理静态托管。\n\n## 🚀 快速开始\n\n\u003e 🔐 **安全提示（必读）**：默认管理员账号是 `admin / admin`，**仅适用于本地测试**。任何对外网暴露或多设备访问的部署，请务必通过环境变量 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 设置强密码后再启动；否则你的音乐库可能被陌生人访问。\n\n### 📦 方式一：直接运行二进制文件\n\n#### 🐧 Linux / 🍎 macOS\n\n```bash\n# 1️⃣ 下载对应平台的二进制文件（默认即完整版）\n# 例如 Linux x86_64:\nwget https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64\nmv songloft-linux-amd64 songloft\n\n# 2️⃣ 添加执行权限\nchmod +x songloft\n\n# 3️⃣ 创建必要目录\nmkdir -p music data\n\n# 4️⃣ 启动（推荐通过环境变量传入凭证，避免出现在 shell history / 进程列表中）\nADMIN_USERNAME=admin ADMIN_PASSWORD='your_strong_password' ./songloft\n```\n\n\u003e 🍎 **macOS 用户注意**：从 GitHub 下载的二进制带有 Gatekeeper 隔离属性，首次运行会被拦截。运行前请先执行：\n\u003e ```bash\n\u003e xattr -d com.apple.quarantine ./songloft\n\u003e ```\n\n#### 🪟 Windows\n\n```powershell\n# 1️⃣ 下载对应平台的二进制文件（默认即完整版），并重命名为 songloft.exe\n# 例如 Windows x86_64: songloft-windows-amd64.exe\n\n# 2️⃣ 创建必要目录\nmkdir music\nmkdir data\n\n# 3️⃣ 设置环境变量并启动（PowerShell）\n$env:ADMIN_USERNAME = \"admin\"\n$env:ADMIN_PASSWORD = \"your_strong_password\"\n.\\songloft.exe\n```\n\n### 🐳 方式二：Docker 部署\n\n#### 🌐 从 Docker Hub 拉取（推荐）\n\n```bash\n# 🌟 完整版（推荐，包含 Web 前端，:latest 即完整版）\ndocker pull songloft/songloft:latest\n\n# 📦 精简版（不含 Web 前端，需搭配 Flutter 客户端使用）\ndocker pull songloft/songloft:lite\n\n# 运行容器\ndocker run -d \\\n  --name songloft \\\n  -p 58091:58091 \\\n  -v /path/to/music:/app/music \\\n  -v /path/to/data:/app/data \\\n  -e ADMIN_USERNAME=admin \\\n  -e ADMIN_PASSWORD='your_strong_password' \\\n  songloft/songloft:latest\n```\n\n#### 📥 从 Release 离线导入镜像\n\n适合无法直接访问 Docker Hub 的环境：\n\n```bash\n# 1️⃣ 下载对应平台的 Docker 镜像 tar 文件（默认即完整版）\nwget https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar\n\n# 2️⃣ 导入镜像\ndocker load -i songloft-docker-linux-amd64.tar\n\n# 3️⃣ 查看导入的镜像标签\ndocker images | grep songloft\n\n# 4️⃣ 使用上一节的 docker run 命令启动即可（注意替换为导入的镜像标签）\n```\n\n#### 🐙 Docker Compose 部署（推荐）\n\n使用 Docker Compose 可以更方便地管理容器配置：\n\n```yaml\nversion: '3.8'\n\nservices:\n  songloft:\n    image: songloft/songloft:latest\n    container_name: songloft\n    restart: always\n    ports:\n      - \"58091:58091\"\n    volumes:\n      - /path/to/music:/app/music\n      - /path/to/data:/app/data\n    environment:\n      - ADMIN_USERNAME=admin\n      - ADMIN_PASSWORD=your_strong_password\n      - LISTEN_PORT=58091\n```\n\n将上述内容保存为 `docker-compose.yml` 文件，然后运行：\n\n```bash\n# 启动服务\ndocker-compose up -d\n\n# 查看日志\ndocker-compose logs -f\n\n# 停止服务\ndocker-compose down\n```\n\n## 📋 使用流程\n\n### 1️⃣ 启动服务\n\n服务启动后，访问 `http://localhost:58091` 即可打开 Web 界面（仅完整版内置；精简版请使用 [Flutter 客户端](#-flutter-客户端) 连接）。\n\n### 2️⃣ 登录系统\n\n使用配置的管理员账号密码登录。\n\n### 3️⃣ 配置音乐目录\n\n首次登录后，进入「设置」页面配置音乐文件目录（`music_path`）。Docker 部署时通常配置为 `/app/music`。\n\n### 4️⃣ 扫描音乐\n\n在 Web 界面中点击\"扫描\"按钮，系统会自动扫描音乐目录中的音频文件并提取元数据。\n\n### 5️⃣ 播放音乐\n\n扫描完成后，即可在界面中浏览和播放音乐。\n\n## ⚙️ 配置说明\n\nSongloft 仅依赖少量启动期配置（凭证、端口、数据库路径）通过环境变量或命令行参数指定，其余业务配置（音乐目录、扫描规则、封面存储等）都保存在数据库 `config` 表中，启动后通过 Web 界面管理。\n\n### 🌍 环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `ADMIN_USERNAME` | 👤 管理员用户名 | admin |\n| `ADMIN_PASSWORD` | 🔐 管理员密码 | admin |\n| `LISTEN_PORT` | 🔌 服务端口 | 58091 |\n| `DB_PATH` | 💾 数据库文件路径 | data/songloft.db |\n| `BASE_PATH` | 🔗 URL 基础路径（反向代理子路径部署用，如 `/songloft`） | 空（根路径） |\n\n\u003e 📁 Docker 镜像中音乐目录与数据目录固定为 `/app/music` 与 `/app/data`，通过 `-v` 挂载即可，无需额外环境变量。\n\n### 💻 命令行参数\n\n```bash\n# 查看帮助\n./songloft -help\n\n# 指定端口\n./songloft -port 8080\n\n# 指定数据库文件路径\n./songloft -db data/songloft.db\n\n# 指定管理员账号（不推荐，密码会出现在 shell history 和 ps 进程列表中）\n./songloft -username admin -password your_password\n\n# 指定子路径（反向代理部署时使用）\n./songloft -base-path /songloft\n```\n\n\u003e ⚙️ **优先级**：命令行参数 **高于** 环境变量。若两者均未提供，则回退到默认值（管理员账号为 `admin/admin`）。\n\u003e ⚠️ **参数格式**：Songloft 使用单横杠参数（如 `-help`），不支持双横杠参数（如 `--help`）。\n\u003e 🔐 **密码安全**：推荐通过环境变量 `ADMIN_PASSWORD` 传入密码，避免 `-password` 在进程列表中明文暴露。\n\n## 🌐 反向代理子路径部署\n\n如果你通过 Nginx 等反向代理将 Songloft 挂在子路径下（如 `https://nas.example.com/songloft/`），需要配置 `BASE_PATH` 环境变量。\n\n### 配置步骤\n\n**1. 启动 Songloft 时指定 BASE_PATH：**\n\n```bash\n# 环境变量方式\nBASE_PATH=/songloft ./songloft\n\n# 或命令行参数方式\n./songloft -base-path /songloft\n\n# Docker 方式\ndocker run -d \\\n  --name songloft \\\n  -p 58091:58091 \\\n  -v /path/to/music:/app/music \\\n  -v /path/to/data:/app/data \\\n  -e ADMIN_USERNAME=admin \\\n  -e ADMIN_PASSWORD='your_strong_password' \\\n  -e BASE_PATH=/songloft \\\n  songloft/songloft:latest\n```\n\n**2. 配置 Nginx 反向代理：**\n\n```nginx\nlocation /songloft/ {\n    proxy_pass http://127.0.0.1:58091;\n    proxy_read_timeout 52w;\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n}\n```\n\n\u003e ⚠️ **注意**：`proxy_pass` 末尾**不要**加斜杠。Nginx 会将完整路径（含 `/songloft/`）转发给后端，由 Songloft 自行处理前缀剥离。\n\n### 客户端连接\n\n| 客户端类型 | 服务器地址填写 |\n|-----------|--------------|\n| 内置 Web 前端 | 浏览器直接访问 `https://nas.example.com/songloft/`，自动工作 |\n| Flutter 桌面/移动客户端 | 填写 `https://nas.example.com/songloft` |\n\n### Docker Compose 示例\n\n```yaml\nversion: '3.8'\n\nservices:\n  songloft:\n    image: songloft/songloft:latest\n    container_name: songloft\n    restart: always\n    ports:\n      - \"58091:58091\"\n    volumes:\n      - /path/to/music:/app/music\n      - /path/to/data:/app/data\n    environment:\n      - ADMIN_USERNAME=admin\n      - ADMIN_PASSWORD=your_strong_password\n      - BASE_PATH=/songloft\n```\n\n## 💻 系统要求\n\n| 项目 | 要求 |\n|------|------|\n| **操作系统** | 🐧 Linux / 🍎 macOS / 🪟 Windows |\n| **架构** | x86_64 / ARM64 / ARMv7 |\n| **可选依赖** | 🔧 ffprobe（用于获取音频技术参数，不安装也可正常运行） |\n\n## ✅ 校验文件完整性\n\n每个 Release 都包含 `checksums.txt` 文件，用于验证下载文件的完整性：\n\n```bash\n# 下载校验和文件\nwget https://github.com/songloft-org/songloft/releases/latest/download/checksums.txt\n\n# 验证文件\nsha256sum -c checksums.txt\n```\n\n## 📌 版本检查\n\n```bash\n# 查看版本信息（含 Git Commit / 构建时间 / 构建类型）\n./songloft -version\n\n# 查看完整帮助\n./songloft -help\n\n# 通过 API 检查版本\ncurl http://localhost:58091/api/v1/version\n```\n\n输出示例：\n\n```text\nSongloft Version: x.y.z\nGit Commit: abc1234\nBuild Time: 2026-01-01_00:00:00\nBuild Type: full\n```\n\n## 🔌 插件系统\n\nSongloft 内置 JS 插件引擎，插件运行在 QuickJS 沙箱中，支持权限模型、健康检查与热更新，可自由扩展音源 / 元数据 / 设备控制等能力。\n\n### 🎯 插件获取\n\n每个插件在自己的 GitHub 仓库下分发：进到对应仓库的 Releases 页下载最新版的 `.jsplugin.zip`，再到 Songloft 客户端的「插件管理」页上传即可启用。可在 [插件合集 Issue](https://songloft.hanxi.cc/issues/4) 找到当前可用的插件清单。\n\n\u003e 想看更多插件或共建？欢迎在 [插件合集 Issue](https://songloft.hanxi.cc/issues/4) 留言。\n\n\u003e ⚠️ **版权提示**：第三方插件接入的任何网络音源、歌词、封面等内容，版权均归原权利人所有。请仅将插件用于访问你本人享有合法使用权的内容，下载 / 转存 / 二次分发等行为请遵守所在国家或地区的法律法规。详见上文 [版权与免责声明](#️-版权与免责声明)。\n\n### 🛠️ 插件开发\n\n如需开发自定义插件，请参考以下资源：\n\n- **开发工具链**: [songloft-org/plugin-toolchain](https://github.com/songloft-org/plugin-toolchain) — `@songloft/plugin-sdk` + `@songloft/plugin-builder` + 脚手架\n- **快速开始**: `pnpm create songloft-plugin \u003cname\u003e`，详见 [JS 插件开发指南](./docs/js-plugin-development-guide.md)\n\n## 📖 API 文档\n\n完整的 API 文档（Swagger/OpenAPI 格式）可在以下地址查看：\n\n- **Swagger API 文档**: [swagger.json](https://github.com/songloft-org/songloft/blob/main/docs/swagger.json)\n- **Swagger UI 在线查看**: [petstore.swagger.io](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/songloft-org/songloft/refs/heads/main/docs/swagger.json)\n- **本地查看**: 启动服务后访问 `http://localhost:58091/swagger/index.html`\n\n### 主要接口概览\n\n| 接口组 | 路径 | 说明 |\n|--------|------|------|\n| 认证 | `/api/v1/auth/*` | 登录、刷新 Token、登出、Token 管理 |\n| 歌曲 | `/api/v1/songs/*` | 歌曲 CRUD、封面、播放、歌词 |\n| 歌单 | `/api/v1/playlists/*` | 歌单 CRUD、歌单歌曲管理、网络歌曲转本地 |\n| JS 插件 | `/api/v1/jsplugins/*` | 插件上传、启用、禁用、删除、检查更新 |\n| 扫描 | `/api/v1/scan/*` | 音乐库扫描 |\n| 配置 | `/api/v1/configs/*` | 系统配置管理 |\n| 版本 | `/api/v1/version` | 版本信息 |\n\n## ❓ 常见问题\n\n遇到问题？请查看 [常见问题与解决方案](https://songloft.hanxi.cc/faq) 💬\n\n## 🛠️ 技术支持\n\n- **GitHub**: [songloft-org/songloft](https://github.com/songloft-org/songloft)\n- **Issues**: [问题与反馈](https://github.com/songloft-org/songloft/issues)\n- 💬 加入微信群交流：[微信群二维码](https://github.com/songloft-org/songloft/issues/2)\n- 🐧 QQ群: 979995241\n\n## 📝 更新日志\n\n详细的版本更新记录请查看 [CHANGELOG.md](CHANGELOG.md)。\n\n---\n\n## 📄 许可证\n\n本项目基于 [Apache-2.0 License](LICENSE) 开源。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsongloft-org%2Fsongloft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsongloft-org%2Fsongloft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsongloft-org%2Fsongloft/lists"}