Meting-API
于 Hono.js 的多平台音乐 API 代理服务,封装 @meting/core 提供的统一音乐 API。
特性
🎵 支持多个音乐平台:网易云、QQ音乐、酷狗、百度、酷我
🚀 基于 Hono.js 高性能框架
💾 内置 LRU 缓存机制,减少上游 API 调用
🔐 HMAC-SHA1 令牌鉴权,保护敏感接口
🐳 Docker 部署支持
📝 结构化 JSON 日志输出
支持的平台
快速开始
一键部署
本地运行
# 安装依赖
yarn install
# 配置环境变量(可选)
cp .env.example .env
# 编辑 .env 文件配置参数
# 开发模式(热重载)
yarn dev
# 生产模式
yarn startDocker 部署
# 构建镜像
docker build -t meting-api .
# 运行容器
docker run -d \
-p 80:80 \
-e METING_URL=https://your-domain.com \
-e METING_TOKEN=your-secret-token \
--name meting-api \
meting-api使用 Docker Compose:
version: '3.8'
services:
meting-api:
image: ghcr.io/metowolf/meting-api:latest
ports:
- "80:80"
environment:
- METING_URL=https://your-domain.com
- METING_TOKEN=your-secret-token
restart: unless-stoppedHTTPS 配置
开发环境
使用自签名证书进行本地调试:
mkdir -p certs
openssl req -x509 -nodes -days 365 \
-newkey rsa:2048 \
-keyout certs/local.key \
-out certs/local.crt \
-subj "/CN=localhost"在启动服务时配置:
HTTPS_ENABLED=true \
SSL_KEY_PATH=certs/local.key \
SSL_CERT_PATH=certs/local.crt \
yarn start生产环境
推荐使用 Let's Encrypt 提供的免费证书,通过 Certbot 自动签发与续期。例如在 Nginx 部署的服务器上:
sudo apt install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d your-domain.com证书获取后,将 fullchain.pem 和 privkey.pem 文件路径配置到对应环境变量。
Docker HTTPS 部署示例
docker run -d \
-p 80:80 \
-p 443:443 \
-v /etc/letsencrypt/live/your-domain.com:/certs:ro \
-e HTTPS_ENABLED=true \
-e SSL_KEY_PATH=/certs/privkey.pem \
-e SSL_CERT_PATH=/certs/fullchain.pem \
-e METING_URL=https://your-domain.com \
--name meting-api \
meting-api反向代理推荐
生产环境可搭配 Nginx 或 Caddy 作为反向代理,实现自动证书管理和负载均衡:
环境变量配置
创建 .env 文件或通过环境变量传递:
API 接口文档
基础接口
GET /api
请求参数
操作类型说明
响应格式
列表数据 (search/song/album/artist/playlist):
[
{
"title": "歌曲名称",
"author": "艺术家1 / 艺术家2",
"url": "https://your-domain.com/api?server=netease&type=url&id=xxx&auth=xxx",
"pic": "https://your-domain.com/api?server=netease&type=pic&id=xxx&auth=xxx",
"lrc": "https://your-domain.com/api?server=netease&type=lrc&id=xxx&auth=xxx"
}
]歌词数据 (lrc):
[00:00.000] 歌词第一行
[00:05.123] 歌词第二行 (翻译内容)
[00:10.456] 歌词第三行
音频/图片 (url/pic):
成功:302 重定向到实际资源 URL
失败:404 Not Found
请求示例
搜索歌曲:
curl "http://localhost:80/api?server=netease&type=search&id=周杰伦"获取歌曲详情:
curl "http://localhost:80/api?server=netease&type=song&id=歌曲ID"获取歌词(需要 token):
curl "http://localhost:80/api?server=netease&type=lrc&id=歌曲ID&auth=计算的token"鉴权机制
敏感操作(lrc、url、pic)需要提供 HMAC-SHA1 签名的 token:
// Token 计算公式
token = HMAC-SHA1(METING_TOKEN, server + type + id)示例(使用 Node.js):
const crypto = require('crypto');
function generateToken(server, type, id, secret = 'token') {
const message = `${server}${type}${id}`;
return crypto.createHmac('sha1', secret).update(message).digest('hex');
}
const token = generateToken('netease', 'url', '123456');缓存策略
默认缓存容量:1000 条记录
缓存时长:
url类型:10 分钟其他类型:1 小时
响应头
x-cache:miss:缓存未命中,调用上游 API无此头:缓存命中
Cookie 配置
部分音乐平台的 API 需要登录态才能访问完整数据。可以通过以下两种方式配置 Cookie:
方式一:环境变量(推荐)
通过环境变量 METING_COOKIE_大写平台名 配置:
# Docker 部署示例
docker run -d \
-p 80:80 \
-e METING_COOKIE_NETEASE="your_netease_cookie" \
-e METING_COOKIE_TENCENT="your_tencent_cookie" \
--name meting-api \
meting-api方式二:文件存储
在项目根目录 cookie/ 文件夹下创建以平台名命名的文件(无扩展名):
cookie/
├── netease # 网易云音乐 Cookie
├── tencent # QQ音乐 Cookie
├── kugou # 酷狗音乐 Cookie
└── ...
每个文件存储对应平台的 Cookie 字符串。
Cookie 优先级
优先从环境变量读取(
METING_COOKIE_NETEASE等)环境变量不存在时从文件读取(
cookie/netease等)
Cookie 缓存
Cookie 内容会在内存中缓存 5 分钟,减少文件系统读取
使用文件存储时,修改 cookie 文件会自动清除缓存,立即生效
环境变量方式需要重启服务才能更新
Referrer 白名单
通过 METING_COOKIE_ALLOW_HOSTS 环境变量限制哪些来源可以使用 Cookie:
# 仅允许特定域名使用 Cookie
METING_COOKIE_ALLOW_HOSTS=example.com,music.example.com不设置时不限制来源。这可以防止 Cookie 被第三方滥用。
错误处理
API 返回标准 HTTP 状态码:
错误信息通过响应头 x-error-message 返回。
开发
代码规范
项目使用 ESLint Standard 规范:
yarn lint技术栈
运行时: Node.js 22+ (ES Module)
框架: Hono 4.x
核心库: @meting/core 1.5+
缓存: lru-cache 11.x
日志: pino (JSON 格式)
加密: hash.js (HMAC-SHA1)
许可证
MIT License
相关项目
@meting/core - Meting 核心库
Meting - PHP 版本