部署Chutes过程中出现 403_FORBIDDEN 等错误的各种原因

部署Chutes过程中出现 403_FORBIDDEN 等错误的各种原因

在 chutes-api 的 router.py 中，有多个地方会抛出 403``403等问题。这些场景通常代表 权限不足、验证失败或非法操作。所有可能导致 错误提示（主要是 HTTPException） 的情况可以分为以下类别（包含详细触发条件与排查方向）

根据 最新 router.py 文件，所有可能导致 错误提示（主要是 HTTPException） 的情况可以分为以下类别（包含详细触发条件与排查方向）：

1️⃣ 访问控制与黑名单

场景 状态码 提示内容 触发条件 排查建议
热键未在 metagraph 注册 404 Miner with hotkey {hotkey} not found in metagraph _check_blacklisted() 找不到矿工节点 确认 hotkey 是否正确且已在网络注册
热键在黑名单中 403 Your hotkey has been blacklisted: {reason} mgnode.blacklist_reason 不为空 检查黑名单原因，与管理员确认解除

2️⃣ Chute/实例 相关限制

场景 状态码 提示内容 条件 排查
Chute 不存在 404 Chute {chute_id} not found _load_chute() 未查到记录 检查 chute_id 是否正确
Chute 滚动更新中无配额 423 Chute {chute_id} is currently undergoing a rolling update... _check_scalable() 检查到正在更新 等待滚动更新完成
Chute 容量已满 423 Chute {chute_id} has reached its target capacity... _check_scalable() 当前实例数≥目标容量 确认容量配置或等待资源释放
私有 Chute 无活跃赏金 423 Private chute {chute_id} has no active bounty and cannot be scaled. _check_scalable_private() 发布赏金或启用公有化

3️⃣ 作业(Job) 处理错误

场景 状态码 提示内容 条件 排查
Job 不存在 404 Job {job_id} for chute {chute_id} not found get_launch_config() 查询为空 检查 job_id 是否有效
Job 已有过多矿工竞争 423 Job {job_id} for chute {chute_id} is already in a race between ... miners 竞争数 ≥15 等待或选择其他任务
同一矿工重复尝试 403 Your hotkey has already attempted to claim job_id= hotkey 已在 job.miner_history 不要重复提交同 job

4️⃣ Envdump 与环境验证失败

场景 状态码 提示内容 条件 排查
解密失败 403 Unable to verify: {exc} envdump 解密出错 检查传输的 args.env 和 args.code 是否完整
启动命令不匹配 403 You are not running the correct command, sneaky devil: {exc} verify_expected_command 或 code 不一致 确认启动命令和 chute.code
非 K8S 环境 403 Failed kubernetes environment check. is_kubernetes_env() 返回 False 确认运行环境为 Kubernetes
文件系统哈希不匹配 403 File system verification failure, mismatched hash generate_fs_hash 校验失败 确保镜像文件未被更改

5️⃣ 端口与网络验证失败

场景 状态码 提示内容 条件 排查
IP 不一致 400 Egress and ingress IPs much match for jobs actual_ip != args.host 确认网络配置一致
端口映射无效 403 Invalid port mappings provided: {expected} {received} 端口集合不匹配 核对端口映射
日志访问权限不足 403 You may only view logs for your own chutes... 查看他人日志且未启用 logging_enabled 使用自己的 chute 或获得 affine admin 权限
Backfill 参数无效 400 `backfill` must be between 0 and 10000 超出范围 修正 backfill 值
端口验证失败 403 Failed port verification on {port_map} verify_port_map() 失败 确认端口可用并响应正确数据

6️⃣ GPU 节点验证失败

场景 状态码 提示内容 条件 排查
GPU 未验证 400 GPU {node_id} is not yet verified node.verified_at 为空 等待节点验证完成
GPU 已被占用 409 GPU {node_id} is already assigned to instance 已在 instance_nodes 表 使用未被占用的 GPU
GPU 与 node selector 不匹配 400 Node {node_id} is not compatible with chute node selector! is_suitable() 失败 确认 GPU 满足要求
主机名不匹配 400 Instance hostname does not match... node_hosts 与 host 不一致 检查 miner 主机名

7️⃣ PoVW 与文件系统验证失败（启动验证阶段）

场景 状态码 提示内容 条件 排查
响应超时 403 PoVW encrypted response ... exceeding maximum estimate 超过时间窗口 检查 miner 性能与延迟
响应解密无效 403 PoVW encrypted response ... was invalid 解密失败或内容错误 确认返回的加密响应
PoVW 工作量证明失败 403 PoVW proof failed verify_proof 失败 检查 GPU 计算结果
文件系统挑战失败 403 Filesystem challenge failed 哈希校验失败 核对镜像文件完整性

8️⃣ 其他提示

场景 状态码 提示内容 条件 排查
Launch config 重复验证 400 Launch config has already been verified launch_config.verified_at 存在 避免重复提交
Launch config 已失败 403 Launch config failed verification: ... launch_config.failed_at 存在 查明失败原因并重新申请
实例消失 404 Instance disappeared (did you update gepetto reconcile?) 关联实例被删除 检查 gepetto 同步状态
实例删除 404 Instance with {chute_id} {instance_id} associated with {hotkey} not found 删除接口查询不到实例 检查实例 ID 是否正确

📌 新增/变更点（相较旧版）

  • 新增：check_instance_logging_server() 的日志探测，但目前未启用 403，仅做错误日志记录。
  • 其余与旧版一致，新增代码未引入新的 HTTPException。

✅ 排查顺序建议

  1. 确认 Hotkey → 黑名单、注册状态。
  2. 检查 Chute → ID 是否正确、是否容量满、是否滚动更新。
  3. 验证 Job → 确认 job_id 有效、竞争数量。
  4. 核对 EnvDump 和命令 → 校验解密、命令、K8S 环境。
  5. 端口和网络 → 确认端口映射、IP、日志权限。
  6. GPU 节点 → 验证 GPU 是否空闲且匹配。
  7. PoVW 和文件系统 → 检查加密响应、哈希与证明。

这份清单涵盖了文件中所有明确的错误提示和触发条件，可作为排查 403 及相关错误的完整参考。