故障排查

先确认问题发生在哪一层：Melso 服务、守护进程、运行时，还是 AI 编程工具。下面几条命令通常足以找到第一条有效错误：

melso version
melso auth status
melso daemon status --output json
melso daemon logs --lines 100

自托管实例还可以直接检查服务：

curl -i https://api.example.com/health
curl -i https://api.example.com/readyz

/health 只说明 API 进程正在响应；/readyz 还会检查数据库和 migration。问题反馈包含报错、相关日志、CLI 版本和操作系统；令牌、邮箱等敏感信息在提交前移除。

守护进程连接失败

先运行：

melso auth status
melso daemon status --output json
melso daemon logs --lines 100

常见原因包括：

• CLI 尚未登录，或本机保存的令牌已经失效；
• 守护进程连接了错误的 Melso 服务；
• 执行电脑无法访问 API，或 DNS、TLS、防火墙拦截了连接；
• 当前账号已经不在目标工作区中；
• 本机没有安装任何受支持的 AI 编程工具，守护进程因此无法启动。

重新登录并重启守护进程：

melso login
melso daemon restart

自托管部署还需要从执行电脑请求 API 的 /health——服务器本机测试无法暴露执行电脑侧的 DNS、TLS 或防火墙问题。需要修改地址时，重新运行 melso setup self-host，或检查当前 profile 的 server_url：

melso config show

Issue 未开始执行

打开 issue 的执行日志，先看执行任务的当前状态和等待原因。

queued 状态

queued 表示执行任务还在等待运行时领取。依次检查：

1. 智能体绑定的运行时是否在线；
2. 运行时是否检测到了该智能体配置的 AI 编程工具；
3. 智能体是否还有可用并发额度；
4. 守护进程是否还有全局执行容量。

智能体默认最多同时执行 6 条执行任务；单个守护进程默认最多同时执行 20 条。达到上限时，新执行任务会留在队列中，等已有执行结束后再开始。运行时离线时，执行任务也会继续排队；超过 2 小时仍未领取才会失败。

melso daemon status --output json
melso agent get <agent-id>
melso issue runs <issue-id>

如果运行时列表缺少预期工具，先在同一个系统账号和 PATH 中确认工具可以运行并且已经登录，再执行 melso daemon restart。

waiting_local_directory 状态

这表示另一条在途执行任务正在使用同一个本地目录。Melso 会等待目录锁释放，避免两个智能体同时修改同一份文件。

这种等待只存在于目录的 in_place（“原地”）模式。如果这个目录是 git 仓库，把资源切到 worktree（“并行”）就没有队列了：每条任务拿到自己的 worktree，并以分支形式交回结果，谁都不用等谁。见项目资源。

否则通常只需等前一条执行任务结束。若前一条已经卡住，可以从它的执行日志中停止；也可以为当前智能体选择其他本地目录。这个目录互斥由守护进程在内存中维护，不写磁盘锁文件；怀疑锁状态异常时运行 melso daemon restart 即可释放，没有需要手动删除的文件。

AI 编程工具启动失败

守护进程在线不代表工具本身可用。打开这次执行的详细记录，重点检查：

• 工具是否已经完成登录；
• API key、额度或模型权限是否可用；
• 智能体选择的模型和思考级别是否被该工具支持；
• 本地工作目录是否存在并且可写；
• 智能体的自定义参数或环境变量是否有效。

先在执行电脑的终端中直接运行同一款工具。工具自身也无法开始时，先修复工具登录或配置，再从执行日志重试执行任务。

实时更新失效

任务仍能执行、但评论和状态不能实时出现，通常是 WebSocket 没有连通。

在浏览器开发者工具的 Network → WS 中查看 /ws 连接。自托管部署重点检查：

• FRONTEND_ORIGIN 是否和浏览器实际打开的地址一致；
• HTTPS 页面是否通过 wss:// 连接；
• 反向代理是否转发 WebSocket 的 Upgrade 请求；
• 浏览器登录是否已经过期。

容器只在创建时读取 .env，修改后需要重新创建：

docker compose -f docker-compose.selfhost.yml up -d

完整的反向代理示例见自托管快速上手。

验证码与邀请邮件未送达

先查看 backend 启动日志。日志会说明当前使用 SMTP relay、Resend API 还是 DEV mode：

docker compose -f docker-compose.selfhost.yml logs backend \
  | grep "EmailService:"

• DEV mode：邮件不会发出，验证码和邀请链接只写入 backend 日志；
• Resend：确认 API key 有效，且发件地址的域名已经验证；
• SMTP：确认主机、端口、凭据和发件地址，并从错误日志判断失败发生在连接、TLS、认证还是投递阶段。

SMTP_HOST 和 Resend 同时配置时，Melso 会优先使用 SMTP。配置方式见登录与注册。

附件上传或下载失败

先检查 backend 日志和响应状态码。常见原因是：

• 反向代理限制了请求体大小；
• 本地上传目录不可写或没有挂载持久化卷；
• S3 bucket、region、endpoint 或凭据不匹配；
• 下载地址经过代理后使用了错误的公开域名或协议。

使用 Docker Compose 时，默认的 backend_uploads volume 保存本地附件。重建容器不会删除它，但 docker compose down -v 会删除数据卷。S3 相关配置见环境变量。

用量（Usage）为 0

Usage 页面读取按小时汇总的数据，不直接读取每条执行任务的原始用量。先确认原始数据和汇总表：

SELECT count(*) FROM task_usage;
SELECT count(*) FROM task_usage_hourly;

SELECT plan_time, status, error_code, error_msg
FROM sys_cron_executions
WHERE job_name = 'rollup_task_usage_hourly'
ORDER BY plan_time DESC
LIMIT 20;

如果 task_usage 有数据、汇总表为空，并且调度记录显示失败，先确认 migration 已经全部应用；升级被 migration 103 拒绝执行的情况见下一节。也可以手动执行一次汇总来区分 SQL 和调度问题：

SELECT rollup_task_usage_hourly();

手动执行后数字正常，说明汇总函数可用，问题在 backend 的定时调度；手动 SQL 只补一次汇总，不会恢复调度。按小时汇总由 backend 内置调度执行，不需要自行配置 pg_cron。

升级时 migration 103 拒绝执行

正常升级不需要为 103 做任何事：migrate up 在应用它之前会自动回填历史用量数据——空库直接通过，有历史数据的实例自动按月补齐后继续。

如果 backend 启动仍报 refusing to drop legacy daily rollups，说明自动回填没有完成（例如回填中途失败，或没有通过 migrate up 而是直接应用了 SQL）。此时手动运行回填命令，完成后重启 backend：

cd server
DATABASE_URL='postgres://...' go run ./cmd/backfill_task_usage_hourly

常用 flag：--dry-run 只预览不写入；--sleep-between-slices 在切片之间加间隔，降低对繁忙实例的读压。命令按月切片、幂等，中断后可以直接重跑；它持有 advisory lock，与服务端的定时汇总互斥，不会产生重复或不一致的汇总数据。完成后重启 backend，用 /readyz 确认 migrations 为 ok。

端口占用

本地常用端口包括 API 的 8080、Web 的 3000 和守护进程健康检查端口。先找出占用者：

lsof -nP -iTCP:8080 -sTCP:LISTEN   # macOS / Linux
netstat -ano | findstr :8080       # Windows

如果它是另一个 Melso checkout，先在那个目录运行 make stop。否则正常停止占用端口的程序，或修改当前服务端口。公网 80/443 由 Caddy、Nginx 等反向代理监听。

日志位置

哪个文件是当前活跃的日志，取决于守护进程启动时使用的 profile；早前守护进程残留的旧日志同样能正常读出来，最容易让人调错文件。不要靠猜去开文件：melso daemon logs 会在输出日志内容前先打印它解析到的绝对路径。读命名 profile 的日志时加上 --profile <name>。

需要直接观察守护进程启动过程时，可以改为前台运行：

melso daemon stop
melso daemon start --foreground

仍然无法定位时，到 GitHub Issues 搜索已有问题或提交新的 issue。

接下来

• 守护进程与运行时 — 运行时注册与在线状态机制。
• 执行任务 — 状态、超时与失败原因参考。
• 环境变量 — 自托管配置的完整参考。