十、检查部署是否成功
检查要分成两层。
第一层检查“本地程序是否正常启动”；第二层检查“是否已经成功连接你的 Suno 账号”。
10.1 检查容器状态
Windows 和 macOS 都输入：
```bash
docker compose ps
```
等待一会儿后，`suno-api` 的状态应该包含：
```text
Up
```
并最终显示：
```text
healthy
```
刚启动时显示 `health: starting` 属于正常现象。等待 30 到 60 秒，再执行一次 `docker compose ps`。
10.2 检查本地文档页
在浏览器打开：
```text
http://127.0.0.1:3000/docs
```
如果能看到 `Suno API Final / Pure HTTP Rewrite` 和接口列表，说明：
- Docker 容器正在运行；
- 本地 3000 端口可以访问；
- 项目本身已经成功启动。
这个页面能打开，不代表 Cookie 一定有效，还要继续下一步。
10.3 检查 Suno 登录和额度
在浏览器打开：
```text
http://127.0.0.1:3000/api/get_limit
```
成功时会看到一段 JSON，常见字段包括：
```json
{
"credits_left": 1000,
"period": "...",
"monthly_limit": 10000,
"monthly_usage": 9000
}
```
数字只是示意，以你的账号实际结果为准。
只要返回的是账号额度信息，而不是 `error`，就说明：
- `.env` 已经被容器读取；
- Cookie 可以建立 Suno 登录会话；
- 本地 API 已经能连接 Suno 后台。
10.4 如果提示 Cookie 失效
常见错误类似：
```text
Failed to get session id, you may need to update SUNO_COOKIE
```
请：
1. 回到 Chrome；
2. 确认 Suno 仍然处于登录状态；
3. 重新按照第六章获取完整 Cookie；
4. 更新 `.env` 中的 `SUNO_COOKIE`；
5. 保存；
6. 回到项目文件夹执行：
```bash
docker compose up -d --force-recreate
```
然后重新打开额度接口检查。
---
十一、检查 Create 前的验证码状态
这个检查不会生成歌曲，也不会消耗一次歌曲生成任务。
11.1 Windows PowerShell
输入：
```powershell
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:3000/api/create_precheck" | ConvertTo-Json -Depth 10
```
11.2 macOS 终端
输入：
```bash
curl -sS -X POST
http://127.0.0.1:3000/api/create_precheck
```
11.3 如何看结果
如果看到：
```json
{
"required": false,
"ready_for_create": true
}
```
表示 Suno 当前没有要求验证码。
如果看到：
```json
{
"required": true,
"captcha_provider": "turnstile",
"ready_for_create": false
}
```
表示当前 Create 进入验证码分支。这个诊断接口只报告状态，不会提前解题。真正的 Create 请求会在同一个 API 实例中尝试解题并立即提交。
如果是 hCaptcha 图片挑战，可能需要在已登录的 Suno 浏览器中手动完成一次验证，再重新尝试。Suno 的验证策略会变化，不能保证一次人工验证可以维持多久。
---
十二、可选：提交一次真正的歌曲生成测试
> 这一节会真实调用 Suno，并可能消耗账号额度。
第一次测试建议：
- 生成纯音乐；
- 不手动指定模型，让 API 使用当前默认值；
- 只提交一次；
- 等待返回结果；
- 不要因为终端暂时没有输出就连续重复提交。
### 12.1 Windows PowerShell
先输入：
```powershell
$body = @{
prompt = "A short bright instrumental theme with piano, strings and gentle drums"
make_instrumental = $true
wait_audio = $true
} | ConvertTo-Json
```
再输入：
```powershell
Invoke-RestMethod `
-Method Post `
-Uri "http://127.0.0.1:3000/api/generate" `
-ContentType "application/json" `
-Body $body | ConvertTo-Json -Depth 20
```
12.2 macOS 终端
输入：
```bash
curl -X POST
http://127.0.0.1:3000/api/generate \
-H 'Content-Type: application/json' \
-d '{
"prompt": "A short bright instrumental theme with piano, strings and gentle drums",
"make_instrumental": true,
"wait_audio": true
}'
```
12.3 成功标准
Create 的最终成功标准是返回结果中出现非空的歌曲 clip ID。
如果已经拿到 clip ID，后续轮询或下载失败时，应继续查询这些已有 ID，不要直接再次 Create，否则可能重复消耗额度。
查询一个 clip：
```text
http://127.0.0.1:3000/api/clip?id=把_CLIP_ID_放在这里
```
12.4 为什么第一次测试不指定模型
Suno 可用模型会随账号权限和官方更新发生变化。
项目允许请求中传入 `model` 字符串，但模型名称属于上游观察值，不是长期不变的官方契约。
第一次只测试部署是否可用时，省略 `model` 最稳妥。确认基础流程正常后，再根据项目 README 和你的账号实际可用模型指定版本。
---
十三、让本机 Agent 调用
只要 Agent 与 Suno API 运行在同一台电脑，就可以把下面信息交给 Agent：
```text
本机 Suno API Base URL:
http://127.0.0.1:3000
接口说明:
http://127.0.0.1:3000/docs
调用前先用 GET /api/get_limit 检查登录状态。
Create 拿到 clip ID 后必须保存 ID；后续失败优先轮询已有 ID，不要盲目重复 Create。
```
不要把 `.env` 文件或 Suno Cookie 交给不可信 Agent。
不要为了让远程 Agent 访问而直接把：
```text
SUNO_API_BIND=127.0.0.1
```
改成：
```text
SUNO_API_BIND=0.0.0.0
```
项目本身没有为公开互联网暴露场景提供完整的登录认证、TLS、限流和访问控制。新手应保持只允许本机访问。
---
十四、可选：下载自己账号中的歌曲
Docker 部署后，可以调用已经运行的：
```text
POST /api/archive_account
```
来执行曲库归档，不需要另外安装 Node.js。
14.1 先做 5 首歌曲的只读预检
Windows PowerShell
先输入：
```powershell
$archiveBody = @{
dry_run = $true
target_complete = 5
output_dir = "/app/output/archive-preflight"
} | ConvertTo-Json
```
再输入：
```powershell
Invoke-RestMethod `
-Method Post `
-Uri "http://127.0.0.1:3000/api/archive_account" `
-ContentType "application/json" `
-Body $archiveBody | ConvertTo-Json -Depth 20
```
macOS 终端
```bash
curl -X POST
http://127.0.0.1:3000/api/archive_account \
-H 'Content-Type: application/json' \
-d '{
"dry_run": true,
"target_complete": 5,
"output_dir": "/app/output/archive-preflight"
}'
```
这一步会列出歌曲并写入归档记录，但不会下载音频。
14.2 测试下载 5 首完整歌曲
Windows PowerShell
```powershell
$archiveBody = @{
target_complete = 5
output_dir = "/app/output/archive-test5"
} | ConvertTo-Json
```
```powershell
Invoke-RestMethod `
-Method Post `
-Uri "http://127.0.0.1:3000/api/archive_account" `
-ContentType "application/json" `
-Body $archiveBody | ConvertTo-Json -Depth 20
```
macOS 终端
```bash
curl -X POST
http://127.0.0.1:3000/api/archive_account \
-H 'Content-Type: application/json' \
-d '{
"target_complete": 5,
"output_dir": "/app/output/archive-test5"
}'
```
默认会尝试下载 MP3 和 WAV。
WAV 可能需要先触发 Suno 后台转换，再轮询等待 WAV 准备完成，因此通常比 MP3 慢。
14.3 下载整个账号曲库
确认 5 首测试正常后再执行。
Windows PowerShell
```powershell
$archiveBody = @{
output_dir = "/app/output/suno-account-archive"
} | ConvertTo-Json
```
```powershell
Invoke-RestMethod `
-Method Post `
-Uri "http://127.0.0.1:3000/api/archive_account" `
-ContentType "application/json" `
-Body $archiveBody | ConvertTo-Json -Depth 20
```
macOS 终端
```bash
curl -X POST
http://127.0.0.1:3000/api/archive_account \
-H 'Content-Type: application/json' \
-d '{
"output_dir": "/app/output/suno-account-archive"
}'
```
请求 JSON 中不填写 `limit` 或 `target_complete` 字段时，会继续扫描到账号曲库列表末尾，但仍受安全页数上限保护。
完整曲库可能运行很久。请保持 Docker Desktop 运行，不要关闭终端或让电脑进入深度睡眠。即使终端连接中断，也不要立即重复提交；先查看下面的归档状态。
在浏览器打开：
```text
http://127.0.0.1:3000/api/archiv ... uno-account-archive
```
这个只读接口会显示该输出目录当前保存的状态。
下载结果会出现在项目文件夹的：
```text
output/suno-account-archive
```
其中包括：
```text
manifest.json
runs/
clips/
```
`manifest.json` 是长期归档记录。以后再次执行相同命令时，默认会跳过已经存在并通过检查的文件，只处理新增或缺失内容。
只有明确想重新下载已有文件时，才在请求 JSON 中增加：
```json
{
"skip_existing": false
}
```
不要同时运行两个指向同一个输出文件夹的归档任务。
---
十五、日常停止、启动和查看日志
以下命令都要在项目文件夹中执行。
查看当前状态
```bash
docker compose ps
```
停止服务
```bash
docker compose stop
```
这不会删除下载文件。
再次启动
```bash
docker compose start
```
重启
```bash
docker compose restart
```
修改 `.env` 后重新创建容器
```bash
docker compose up -d --force-recreate
```
查看最近 100 行日志
```bash
docker compose logs --tail=100 suno-api
```
持续查看日志
```bash
docker compose logs -f suno-api
```
按：
```text
Ctrl + C
```
可以退出日志查看，不会停止 API。
删除容器但保留本地文件
```bash
docker compose down
```
项目的 `output` 和 `studio-state` 文件夹仍会保留。
不要随意使用带 `-v` 的删除命令，也不要随意删除 `output`、`studio-state`、`manifest.json` 或任务进行中的 `.part` 文件。
---
十六、以后如何升级项目
使用 ZIP 部署的新手，可以这样升级。
第 1 步：停止旧版本
在旧项目文件夹执行：
```bash
docker compose down
```
第 2 步：备份私人数据
至少保留：
```text
.env
output
studio-state
```
不要把 `.env` 上传到网盘公开链接。
第 3 步：重新下载最新版 ZIP
从 GitHub 项目页面重新选择：
```text
Code > Download ZIP
```
解压到一个新的文件夹。
第 4 步：迁移本机配置和数据
把旧项目中的以下内容移动或复制到新项目对应位置：
```text
.env
output
studio-state
```
如果新版 `.env.example` 增加了配置项，建议先比较新版模板，再把自己的私人配置填写到新的 `.env` 中。
第 5 步：重新构建
在新项目文件夹执行：
```bash
docker compose up -d --build
```
然后重新检查：
```text
http://127.0.0.1:3000/docs
```
```text
http://127.0.0.1:3000/api/get_limit
```
十七、常见问题排查
问题 1：提示找不到 `docker`
常见信息：
```text
docker: command not found
```
或：
```text
docker 不是内部或外部命令
```
处理方法：
1. 确认 Docker Desktop 已安装；
2. 完全退出并重新打开 PowerShell 或终端；
3. 启动 Docker Desktop；
4. 再执行 `docker --version`。
问题 2：提示无法连接 Docker daemon
常见原因是 Docker Desktop 没有启动完成。
先打开 Docker Desktop，等它显示 Engine running，再执行启动命令。
问题 3：`docker compose up` 下载或构建失败
如果错误中出现：
```text
timeout
TLS handshake timeout
failed to fetch
npm install
node:lts-bookworm
```
通常是 Docker 下载镜像或依赖时的网络问题。
处理顺序：
1. 确认浏览器可以访问 GitHub 和 Docker Hub；
2. 在 Docker Desktop 设置中检查 Proxies；
3. 如果使用代理软件，让 Docker Desktop 使用正确的 HTTP/HTTPS 代理；
4. 重新执行：
```bash
docker compose up -d --build
```
`.env` 中的 `DOCKER_HTTP_PROXY` 主要用于已经启动的容器访问外网，不一定能解决镜像拉取和构建阶段的问题。构建阶段优先检查 Docker Desktop 自己的代理设置。
问题 4：容器启动了，但访问不了 3000 端口
先执行：
```bash
docker compose ps
```
再查看日志：
```bash
docker compose logs --tail=100 suno-api
```
如果电脑上的 3000 端口已经被其他程序占用，在 `.env` 中把：
```text
SUNO_API_PORT=3000
```
改成：
```text
SUNO_API_PORT=3001
```
保存后执行：
```bash
docker compose up -d --force-recreate
```
新的访问地址是：
```text
http://127.0.0.1:3001/docs
```
后续所有示例中的 `3000` 也要相应改成 `3001`。
### 问题 5：文档页正常，但额度接口报错
这说明本地程序已经启动，问题集中在：
- Cookie 不完整；
- Cookie 已过期；
- 复制了错误请求的 Cookie；
- `.env` 没有保存；
- 容器没有在修改 `.env` 后重新创建；
- 容器无法访问 Suno 或 Clerk。
重新获取 Cookie 后，执行：
```bash
docker compose up -d --force-recreate
```
问题 6：Cookie 中有 `$`
使用英文单引号包住完整 Cookie：
```text
SUNO_COOKIE='完整 Cookie'
```
这种写法会把 `$` 按原样传入容器，不需要改动 Cookie 内容。
如果 Docker Compose 仍然报告变量插值错误，请检查：
1. 两端是否真的是英文半角单引号 `'`；
2. 是否漏掉了末尾单引号；
3. 是否误用了中文弯引号 `‘’`；
4. Cookie 是否被粘贴成了多行。
不要因此把 Cookie 发给别人检查。
问题 7：容器访问 Suno 需要本机代理
假设你的代理软件提供 HTTP 或 mixed 端口 `7890`，可以在 `.env` 中填写：
```text
DOCKER_HTTP_PROXY=http://host.docker.internal:7890
DOCKER_HTTPS_PROXY=http://host.docker.internal:7890
```
端口 `7890` 只是示例，必须换成你自己的实际端口。
容器里的 `127.0.0.1` 指向容器自己，不是宿主电脑，所以不要写：
```text
DOCKER_HTTP_PROXY=http://127.0.0.1:7890
```
部分代理软件还需要允许来自 Docker 虚拟环境的连接。只开放必要范围，不要把本地代理直接暴露到公网。
修改后执行：
```bash
docker compose up -d --force-recreate
```
问题 8：Create 提示没有配置 2Captcha
常见错误：
```text
CAPTCHA_SOLVE_FAILED: 2Captcha API key not configured
```
表示 Suno 当前要求验证码，但 `.env` 中没有有效的：
```text
TWOCAPTCHA_API_KEY
```
配置并保存后，重新创建容器。
问题 9：提示 `BROWSER_CAPTCHA_REQUIRED`
这不是 Docker 安装失败。
它表示 Suno 当前要求在同一浏览器环境中完成图片 hCaptcha，而本地纯 HTTP Create 流程不能把一次独立解题安全地冒充成同一浏览器上下文。
可以尝试：
1. 在 Chrome 中登录同一个 Suno 账号；
2. 在 Suno Create 页面手动完成一次验证码；
3. 再重新调用 API；
4. 如果仍然失败，保留返回内容和脱敏日志，等待适配当前 Suno 验证策略。
不要公开 Cookie、验证码 token 或完整请求头。
问题 10：2Captcha 显示解题完成，但没有歌曲
“解题完成”只是中间状态。
真正成功必须同时满足：
- Suno 接受 Create；
- 返回非空 clip ID。
如果请求已经返回 clip ID，后续只轮询这些 ID。
如果没有 clip ID，查看：
```bash
docker compose logs --tail=200 suno-api
```
分享日志前必须检查并遮盖账号、项目、歌曲和凭证相关私人信息。
问题 11：生成模型报错
第一次测试请不要传 `model`。
模型可用性由 Suno 当前服务和账号权限控制。某个模型字符串曾经可用，不代表以后仍然可用，也不代表所有账号都能使用。
问题 12：下载 WAV 比 MP3 慢
这是正常情况之一。
MP3 通常可以直接从歌曲媒体地址下载。WAV 可能需要：
1. 请求 Suno 准备或转换 WAV；
2. 轮询处理状态；
3. 等 `wav_file_url` 准备完成；
4. 再开始下载。
归档中某一首 WAV 暂时失败，不会抹掉已经成功下载的 MP3。以后重新执行相同归档命令，会继续处理缺失项目。
---
十八、部署完成后的安全检查
请逐项确认：
- [ ] `.env` 没有发给任何人；
- [ ] Cookie 没有出现在截图、帖子或聊天记录中；
- [ ] `TWOCAPTCHA_API_KEY` 没有公开；
- [ ] API 仍然绑定 `127.0.0.1`；
- [ ] 没有把 3000 端口直接映射到公网；
- [ ] 只使用自己的 Suno 账号；
- [ ] 只上传和处理自己有权使用的音频；
- [ ] Create 拿到 clip ID 后会保存 ID，不盲目重复提交；
- [ ] `output` 和 `manifest.json` 被视为私人曲库资料；
- [ ] 分享日志前已经检查并移除私人数据。
如果 Cookie 意外泄露，应立即终止相关登录会话，并重新登录 Suno 获取新的 Cookie。
---
十九、最常用命令速查
所有命令都在项目文件夹中执行。
第一次构建并启动
```bash
docker compose up -d --build
```
查看状态
```bash
docker compose ps
```
查看日志
```bash
docker compose logs --tail=100 suno-api
```
停止
```bash
docker compose stop
```
启动
```bash
docker compose start
```
重启
```bash
docker compose restart
```
修改 `.env` 后应用配置
```bash
docker compose up -d --force-recreate
```
重新编译最新版代码
```bash
docker compose up -d --build
```
本地文档
```text
http://127.0.0.1:3000/docs
```
检查额度
```text
http://127.0.0.1:3000/api/get_limit
```
下载整个账号曲库
```text
POST
http://127.0.0.1:3000/api/archive_account
JSON:
{"output_dir":"/app/output/suno-account-archive"}
```
---
二十、判断是否真正部署成功
同时满足下面四项，才算完成了基础部署：
1. `docker compose ps` 显示 `suno-api` 正在运行并最终健康；
2. `
http://127.0.0.1:3000/docs` 可以打开；
3. `
http://127.0.0.1:3000/api/get_limit` 返回自己账号的额度信息；
4. 日志中没有持续重复出现的认证或网络错误。
Create 属于下一层验收。它还会受到账号额度、模型权限和 Suno 当前验证码策略影响。基础部署成功，不等于每一次上游 Create 都一定不会遇到验证或服务变化。
