modbender 🎵 Suno AI 音乐创作助手（Headless Linux 专用版）
专为 无图形界面的 Linux 云服务器 设计，通过 Xvfb 虚拟显示 在没有显示器的环境下运行 Chrome GUI 模式，绕过 Google 反自动化检测。
两大核心能力：账号登录（通过 Google OAuth）和 歌曲创作（自定义歌词+风格+下载）。
零、前置检查
每次操作前必须先执行环境检查：
bash {baseDir}/suno-headless/check_env.sh
返回码：0 = 正常已登录 → 可直接创建歌曲；1 = 缺少依赖 → 安装依赖；2 = 未登录 → 登录流程。
一、安装依赖（仅首次）
1.1 系统依赖
# Xvfb 虚拟显示（核心依赖，无 GUI 环境必装）
sudo apt update && sudo apt install -y xvfb
# Google Chrome 浏览器
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable
# 中文字体支持（歌词含中文时需要）
sudo apt install -y fonts-noto-cjk
1.2 Python 依赖
cd {baseDir}/suno-headless
pip3 install -r requirements.txt
playwright install
二、登录流程
⚠️ 重要：不要在 skill 代码中硬编码账号密码！必须先询问用户的凭据。
提供两种登录方式：
- 方式 A: Cookie 导入（🌟 推荐！完美绕过 Google 安全验证）
- 方式 B: 邮箱密码直接登录（可能触发 Google 安全验证）
2.1 方式 A: Cookie 导入（推荐）
这是云服务器上最稳定的登录方式，完全绕过 Google 的安全验证。
操作步骤：
当需要登录时，向用户说明：
🍪 推荐使用 Cookie 导入方式登录（绕过 Google 安全验证）：
步骤 1: 在你的本地电脑（有浏览器的）上运行：
pip install playwright && playwright install python3 export_cookies.py这会打开浏览器，你手动登录 Suno，登录成功后自动导出 Cookie 文件。
步骤 2: 把导出的 Cookie 文件上传到服务器固定路径：
scp <本地导出的Cookie文件> user@your-server:/root/suno_cookie/suno_cookies.json步骤 3: 上传完成后告诉我，我来导入。
用户上传文件后，执行导入。脚本会自动检测 /root/suno_cookie/suno_cookies.json 是否存在，存在则自动导入，无需额外指定参数：
cd {baseDir}/suno-headless
python3 suno_login.py
也可以显式指定 Cookie 文件路径：
python3 suno_login.py --import-cookies /path/to/cookies.json
2.2 方式 B: 邮箱密码登录
⚠️ 注意：云服务器上可能触发 Google 安全验证，推荐优先使用方式 A。
当需要登录时，必须先向用户询问：
需要登录 Suno.com（通过 Google 账号）。请提供：
- Gmail 邮箱地址
- Gmail 密码
⚠️ 你的凭据仅用于本次登录，不会被存储或传输到任何第三方。
用户提供邮箱和密码后：
cd {baseDir}/suno-headless
python3 suno_login.py --email "<用户邮箱>" --password "<用户密码>"
Headless Linux 模式说明：
- 脚本会自动检测无 GUI 环境（无
$DISPLAY变量） - 自动启动 Xvfb 虚拟显示，在内存中模拟一个假显示器
- Chrome 以 GUI 模式运行（
headless=False），但屏幕上不显示任何东西 - 这样可以绕过 Google 对 headless 浏览器的检测拦截
2.3 检查登录状态
cd {baseDir}/suno-headless
python3 suno_login.py --check-only
退出码 0 = 已登录，2 = 未登录。
2.4 强制重新登录
# 方式 A: 重新导入 Cookie
cd {baseDir}/suno-headless
python3 suno_login.py --import-cookies "<新的Cookie文件>"
# 方式 B: 邮箱密码重新登录
cd {baseDir}/suno-headless
python3 suno_login.py --email "<邮箱>" --password "<密码>" --force-login
三、创建歌曲
3.1 前置条件
- 已完成登录（
suno_login.py --check-only返回 0） - 需要 Gemini API Key（用于自动解决 hCaptcha 验证码）
3.2 获取 Gemini API Key
如果用户没有 Gemini API Key，引导用户获取：
创建歌曲时 Suno 会弹出验证码，需要 Gemini API Key 来自动解决。
- 访问 https://aistudio.google.com/app/apikey
- 点击 "Create API key"
- 复制生成的 Key
获取后保存到环境文件：
mkdir -p ~/.suno
echo "GEMINI_API_KEY=<用户的key>" > ~/.suno/.env
或通过环境变量：
export GEMINI_API_KEY="<用户的key>"
3.3 hCaptcha 兼容补丁
首次使用前需运行一次（Suno 使用自定义 hCaptcha 域名，需打补丁）：
cd {baseDir}/suno-headless
python3 patch_hcaptcha.py
3.4 创建歌曲命令
cd {baseDir}/suno-headless
python3 suno_create_song.py \
--lyrics "<歌词内容>" \
--style "<音乐风格标签>" \
--title "<歌曲标题>" \
--output-dir "<下载目录>"
也可以从文件读取歌词：
cd {baseDir}/suno-headless
python3 suno_create_song.py \
--lyrics-file "<歌词文件路径>" \
--style "<音乐风格标签>" \
--title "<歌曲标题>"
Headless 模式说明：
suno_create_song.py会自动检测无 GUI 环境- 自动启动 Xvfb 虚拟显示，Chrome 以 GUI 模式在虚拟显示中运行
- 脚本结束后自动关闭虚拟显示，无需手动操作
3.5 参数说明
| 参数 | 说明 | 必填 | 默认值 |
|---|---|---|---|
--lyrics |
歌词内容（与 --lyrics-file 二选一） |
✅ | - |
--lyrics-file |
歌词文件路径（与 --lyrics 二选一） |
✅ | - |
--style |
音乐风格标签（英文，逗号分隔） | ❌ | rock, electric guitar, energetic, male vocals |
--title |
歌曲标题 | ❌ | My Song |
--output-dir |
MP3 下载目录 | ❌ | {baseDir}/output_mp3 |
--gemini-key |
Gemini API Key（也可通过环境变量或 ~/.suno/.env） | ❌ | 自动读取 |
--verbose / -v |
详细输出模式（实时打印所有中间步骤） | ❌ | 关闭（默认只输出最终摘要） |
📋 输出行为说明：默认情况下，所有脚本（
suno_create_song.py、suno_login.py、export_cookies.py）只在完成时输出一条简洁的摘要，中间步骤的详细日志写入{baseDir}/suno-headless/logs/目录。如需实时查看所有中间步骤，请添加--verbose或-v参数。
3.6 音乐风格标签参考
常用风格标签（英文，可自由组合）：
- 流派: rock, pop, jazz, blues, electronic, hip-hop, R&B, classical, folk, metal, country, reggae, latin, indie
- 乐器: electric guitar, acoustic guitar, piano, synthesizer, drums, bass, violin, saxophone, trumpet
- 情绪: energetic, emotional, melancholic, upbeat, dark, dreamy, aggressive, peaceful, romantic
- 人声: male vocals, female vocals, choir, rap, whisper, powerful vocals, falsetto
- 语言: chinese, japanese, korean, english, spanish
- 其他: fast tempo, slow tempo, instrumental, lo-fi, cinematic, epic
示例：
- 摇滚:
rock, electric guitar, energetic, male vocals, chinese - 抒情:
pop, piano, emotional, female vocals, slow tempo, chinese - 电子:
electronic, synthesizer, upbeat, fast tempo, dance - 说唱:
hip-hop, rap, bass, drums, energetic, chinese
四、完整使用示例
示例：在 Linux 云服务器上创建中文摇滚歌曲
# 1. 检查环境（会自动检测 Xvfb、Chrome 等）
bash {baseDir}/suno-headless/check_env.sh
# 2. 如果未登录，使用 Cookie 导入方式登录（推荐）
# 步骤 1: 在本地电脑运行 export_cookies.py 导出 Cookie
# 步骤 2: scp <Cookie文件> user@server:/root/suno_cookie/suno_cookies.json
# 步骤 3: 服务器上运行登录脚本（自动检测默认路径并导入）
cd {baseDir}/suno-headless
python3 suno_login.py
# 或者使用邮箱密码方式（可能触发 Google 安全验证）
# python3 suno_login.py --email "user@gmail.com" --password "password123"
# 3. 确保 hCaptcha 补丁已应用
python3 patch_hcaptcha.py
# 4. 创建歌曲（自动使用 Xvfb 虚拟显示）
python3 suno_create_song.py \
--lyrics "窗外的麻雀 在电线杆上多嘴
你说这一句 很有夏天的感觉
手中的铅笔 在纸上来来回回
我用几行字形容你是我的谁" \
--style "rock, electric guitar, energetic, male vocals, chinese" \
--title "七里香摇滚版"
五、与原版 suno skill 的区别
| 特性 | suno（原版） | suno-headless（本版） |
|---|---|---|
| 目标环境 | macOS / 有 GUI 的 Linux | 无 GUI 的 Linux 云服务器 |
| 显示方式 | 弹出真实 Chrome 窗口 | Xvfb 虚拟显示（内存模拟） |
| 额外依赖 | 无 | xvfb + PyVirtualDisplay |
| 登录 Xvfb | ✅ 已支持 | ✅ 已支持 |
| 创建歌曲 Xvfb | ❌ 不支持 | ✅ 已支持 |
| 环境检查 | 基础检查 | 增加 Xvfb/Chrome/字体检查 |
六、技术原理
Xvfb 虚拟显示方案
┌─────────────────────────────────────────┐
│ Linux 云服务器（无显示器） │
│ │
│ ┌─────────────┐ ┌────────────────┐ │
│ │ Xvfb │ │ Chrome │ │
│ │ (虚拟显示器) │◄───│ (GUI 模式) │ │
│ │ :99 1280x800│ │ headless=False │ │
│ └─────────────┘ └────────────────┘ │
│ ▲ │ │
│ │ 自动操作 Suno.com │
│ PyVirtualDisplay │ │
│ 自动管理生命周期 ▼ │
│ ┌────────────────┐ │
│ │ 歌曲生成+下载 │ │
│ └────────────────┘ │
└─────────────────────────────────────────┘
- 为什么不用 headless=True？ Google OAuth 会检测到 headless 浏览器并拒绝登录
- Xvfb 方案：在内存中创建虚拟 X11 显示，Chrome 以为自己有真实 GUI，Google 无法检测到自动化
- 自动检测：脚本检查
$DISPLAY环境变量，无 GUI 时自动启用 Xvfb - 资源占用：Xvfb 仅占用极少内存，脚本结束后自动释放
登录方案
- 使用 Playwright + 真实 Chrome 浏览器 (
channel='chrome') persistent context保持浏览器状态（cookies、localStorage）headless=False+ Xvfb 虚拟显示绕过 Google 反自动化- 首次登录后 persistent context 自动保持会话
歌曲创建方案
- 浏览器自动化操作 suno.com/create 页面
- hcaptcha-challenger + Gemini API 自动解决 hCaptcha 验证码
- 通过拦截浏览器网络响应捕获新生成的 clip ID
- 通过 Suno 内部 API (
studio-api.prod.suno.com) 轮询歌曲生成状态 - 生成完成后自动下载 MP3 文件
文件结构
suno-headless/
├── suno_login.py # 登录工具（Google OAuth / Cookie 导入 + Xvfb）
├── suno_create_song.py # 歌曲创建+下载工具（Xvfb 支持）
├── export_cookies.py # Cookie 导出工具（在本地电脑上运行）
├── output_manager.py # 输出管理器（控制日志和摘要）
├── patch_hcaptcha.py # hCaptcha 域名兼容补丁
├── check_env.sh # 环境检查脚本（含 Xvfb/Chrome 检查）
├── requirements.txt # Python 依赖（含 PyVirtualDisplay）
└── SKILL.md # 本文档
七、注意事项
- 不要硬编码账号密码 — 每次都需要询问用户（推荐优先使用 Cookie 导入方式）
- 必须安装 Xvfb —
sudo apt install -y xvfb，否则无法在无 GUI 环境运行 - 必须安装真实 Chrome — Playwright 自带的 Chromium 可能被 Google 检测
- Suno 免费账号每天有积分限制，每首歌消耗约 100 积分
- 歌曲生成通常需要 1-3 分钟
- 每次创建会生成 2 首不同版本的歌曲
- 如果遇到 Google 登录被拒（rejected），等待 10-30 分钟后重试
- Gemini API 免费额度：每分钟 15 次请求，每天 1500 次
- hCaptcha 可能需要多次尝试，成功率取决于 Gemini 模型的图片识别能力
八、故障排查
# 检查环境（含 Xvfb 状态）
bash {baseDir}/suno-headless/check_env.sh
# 手动测试 Xvfb 是否正常
Xvfb :99 -screen 0 1280x800x24 &
DISPLAY=:99 google-chrome --no-sandbox --version
kill %1
# 查看登录截图
ls -la /tmp/suno_debug_*.png
# 检查 persistent context
ls -la ~/.suno/chrome_gui_profile/
# 查看 cookies
python3 -c "import json; d=json.load(open('$HOME/.suno/cookies.json')); print(f'{len(d)} cookies')"
# 查看 Gemini API Key
cat ~/.suno/.env
# 查看下载的歌曲
ls -la {baseDir}/output_mp3/