NewAPI 日志怎么看：定位请求失败在哪一环

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

自建 NewAPI 之后最难受的不是报错，而是不知道该去哪儿看。一次请求要穿过三段：客户端到网关、网关内部的令牌与渠道选择、网关到上游厂商，这三段的痕迹分别落在三个互不相通的地方——控制台里的用量日志（Usage Logs）记的是「这次调用算了多少额度」，容器进程日志记的是「服务本身活没活、请求进没进来」，而真正带上游报错细节的错误日志由 ERROR_LOG_ENABLED 这个环境变量控制、官方文档里标注的默认值是关闭（默认值以官方文档当前版本为准）。很多人翻了半天用量日志找不到失败原因，其实只是那个开关没打开。判断卡在哪一环的最快办法，是先拿报错文本去对照官方 FAQ 的分类，再决定要看哪一层日志。

先分清 NewAPI 有几种日志，它们不在一个地方

官方文档在功能指南里把控制台日志分成三类，各管各的事：

• Usage Logs（用量日志）：官方原文的描述是这里可以查看 API 调用的日志，能看到本次使用的令牌分组（Token Group）、模型和消耗。权限上，普通用户看自己的，管理员可以看别人的。
• Task Logs（任务日志）：官方写明这里查看的是 Suno 任务日志。
• Drawing Log（绘图日志）：官方写明这里查看的是 Midjourney 任务记录。

后两类是异步任务专用的。如果你接的是常规对话/补全类模型，日常只会用到第一类；反过来，如果调的是绘图或音乐类接口，这两类专用页面能看到任务维度的记录，是用量日志之外的补充视角。

管理员侧还有一个独立的日志管理入口，官方对它的描述是查看全平台的 API 调用日志与用户操作记录，功能点列的是查看全部日志、高级筛选、数据统计分析。注意这里的措辞是「API 调用日志与用户操作记录」——也就是说管理员看到的日志表里混着非调用类的条目。官方变更日志中出现过「修复新前端日志按登录类型（type=7）筛选失效」这样的条目，可以佐证日志记录是带类型字段的、前端按类型筛选是官方设计中的用法。

用量日志能回答什么、不能回答什么

按官方功能概览的列举，用量日志这块给的能力是：查看调用日志、搜索与筛选记录、数据统计图表、额度消耗分析。它的定位很清楚——回答「花了多少、走的哪个模型、算在哪个分组头上」，而不是回答「上游为什么拒了我」。

有几个跟排查直接相关的细节值得知道：

• 变更日志记录，v1.0.0-rc.23 起把请求是否为流式（stream）的状态暴露给了日志的归属者；v1.0.0-rc.21 的说明里提到日志新增了流式的时间指标与任务详情视图，目的就是让排查更清楚。所以在较新的版本上，你可以直接从日志里区分一次失败发生在流式还是非流式路径上，这一点在排查「响应中断」类问题时是关键区分。
• 变更日志还记录，v1.0.0-rc.25 起用量日志会一致地记录 reasoning effort；同一版本还让计费日志高亮出本次请求命中的那个条件倍率，官方给出的理由是让成本核算更容易审计。这一条对于排查「为什么这次比平时贵」非常实用，具体的倍率相乘规则可以看NewAPI 分组倍率是怎么算的。
• 筛选行为在 v1.0.0-rc.10 有过一次调整：官方说明是用量日志的筛选默认按精确值匹配，除非你显式使用通配符。这意味着你把模型名少打一个字符就什么都搜不到，不会像模糊匹配那样”顺便”给你结果。同一版本还提到过大的上游错误会被截断以保持日志可用——这也解释了为什么有时候日志里的错误信息看起来像被切了一半。

另外，个人设置的「其他设置」里有一个 IP 记录开关，官方描述是启用后日志中会显示 IP 地址。多客户端共用一个令牌时，它能帮你把某条失败记录对上具体调用方，默认状态以官方文档当前版本为准。

错误日志默认不记，先把开关打开

这是自建 NewAPI 排查时最容易踩的坑。官方环境变量文档里有一项：

ERROR_LOG_ENABLED    是否记录错误日志并在前端展示

文档标注的默认值是 false（以官方文档当前版本为准），官方给的示例是 ERROR_LOG_ENABLED=true；仓库根目录的 docker-compose.yml 里这一项是直接写成开启的，而 .env.example 里它是被注释掉的。也就是说，如果你不是照抄官方 compose 文件起的服务，很可能这项就是关着的，那么无论怎么翻前端页面都看不到上游返回的错误细节。改完环境变量需要重启容器才生效。

打开之后能拿到什么，变更日志里也有交代：v1.0.0-rc.22 的说明是当服务商返回的错误信息不清晰时，上游错误日志会提供更有用的兜底细节；对应的改动是当解析出来的上游错误消息为空时，直接记录响应体。这一条针对的正是那种「上游只回了个空壳错误」的情况。

upstream_request_id：向上游追溯时的唯一凭据

请求失败到底是网关的锅还是上游厂商的锅，光靠自己的日志很难说清。官方变更日志在 v1.0.0-rc.6 里给出了答案：该版本新增了在请求日志中记录上游请求 ID的能力，官方给的理由是便于追溯上游调用，同时避免意外覆盖响应头。

数据库层面，官方在升级提示里写得很具体：logs 表新增了 upstream_request_id 列（VARCHAR(128)）和对应索引 idx_logs_upstream_request_id。官方还专门提醒，如果你的 logs 表已经很大，建议在升级前用在线 DDL 预先加好这一列和索引，避免自动迁移过程漫长甚至阻塞——文档里 MySQL/InnoDB 用的是 ALGORITHM=INPLACE, LOCK=NONE，PostgreSQL 11+ 用的是 CREATE INDEX CONCURRENTLY。这算是官方少见的、把升级风险直接写进变更说明的例子，日志表大的部署方升级前务必看一眼。

实际用法很直白：当你需要向上游厂商提工单时，从这一列取到的 ID 就是对方能在他们系统里查到的那条记录的编号。没有它，你只能描述「大概几点几分有个请求失败了」，双方对不上。

容器日志：控制台都打不开的时候看这里

如果连管理后台都进不去，那就轮不到用量日志出场了，得回到进程层面。官方 Docker Compose 文档给了一整套查看命令：

# 所有服务的实时日志
docker compose logs -f

# 指定服务
docker compose logs -f new-api
docker compose logs -f postgres
docker compose logs -f redis

# 只看最后若干行
docker compose logs --tail=100 new-api

# 只看最近一段时间
docker compose logs --since=10m new-api

# 带时间戳
docker compose logs -f -t new-api

官方还给了前台模式调试的做法：直接 docker compose up（或 docker compose up new-api）随启动实时输出日志，按 Ctrl+C 退出——文档明确提示这会同时停掉对应服务，后台运行仍需加 -d。设置了 container_name 的情况下也可以直接 docker logs -f new-api。

还有一处细节容易被忽略：官方 docker-compose.yml 里 new-api 服务的启动命令是 command: --log-dir /app/logs，并且把 ./logs 挂载到了容器的 /app/logs。也就是说官方推荐的部署方式本身就会把日志落成宿主机文件，出问题时可以直接去这个目录翻，不必依赖 docker logs 的缓冲。本地开发调试同理，官方贡献指南里给的命令是 go run main.go --log-dir ./logs。部署相关的其余配置可以对照 NewAPI Docker 部署怎么做。

判断服务本身活没活着还有个更快的办法：官方 compose 的健康检查探的是 /api/status，判据是响应里能匹配到 "success": true。手工 curl 一下这个地址，就能把「服务挂了」和「服务活着但请求被拒」这两类问题分开。

按报错文本对照官方 FAQ，判断卡在哪一环

官方 FAQ 把常见报错按来源分了组，这份对照表本身就是一张「失败在哪一环」的地图：

• 提示额度不足，但账户额度明明够：官方解释是令牌额度与账户额度是分开的，令牌额度只用于设置最大使用上限，需要检查的是令牌那一侧。对应地，令牌配置里的「剩余额度」项官方描述为限制该令牌最多能消耗的额度、超出后自动禁用。这一环失败根本走不到上游，日志里看不到上游报错很正常。
• 提示没有可用渠道：官方给的检查顺序是三项——用户分组设置、渠道分组设置、渠道模型设置。这三者任意一处对不上，请求都在网关内部就被挡下了。
• 提示当前分组负载已饱和，请稍后再试：官方明确说明这表示上游渠道遇到了 429（Too Many Requests）。也就是说这条报错虽然是网关抛出来的，责任在上游，处理思路可以参考API 429 报错的通用处理方式。
• 渠道测试报 invalid character '<' looking for beginning of value：官方解释是返回值不是合法 JSON 而是一个 HTML 页面，最可能的原因是部署站点的 IP 或代理节点被 CloudFlare 拦了。这一条的判断价值在于——问题出在网络出口，不在配置。
• 渠道测试报倍率或价格未配置：官方原文的指引是检查「系统设置 - 运营设置 - 模型倍率设置」里是否配置了该模型的倍率或价格，或者在运营设置里启用自用模式。

还有一层是重试带来的干扰。README 里写明失败重试次数配置在「设置 → 运营设置 → 通用设置 → 失败重试次数」；渠道的高级配置里有「自动禁用」项，官方描述是启用后连续失败会自动禁用该渠道；模型行为设置里也有对应的自动禁用失败模型、失败阈值、自动恢复时间（分钟）三项。这些机制的存在意味着日志里的一条记录未必对应一次上游调用——可能是重试了若干轮之后的最终结果。官方变更日志里还专门提到过分层重试的计费会按最终选中的分组结算，包含发生了分组切换的重试。排查时如果发现日志条数和你以为的对不上，先想想是不是重试和自动禁用在中间做了事。

日志量大了之后：单独日志库与保留策略

日志规模上来之后怎么办，官方给了两条路：

一是把日志拆到独立数据库，环境变量是 LOG_SQL_DSN，文档对它的描述就是「日志表的单独数据库连接字符串」，默认不设。集群部署文档在「日志管理」一节直接建议大规模集群采用集中式日志管理，给的示例正是给 LOG_SQL_DSN 指一个独立的日志库。

二是换存储引擎。官方 docker-compose.yml 里注释掉的可选项显示 LOG_SQL_DSN 也可以填 ClickHouse 连接串（同时需要放开 depends_on 与 clickhouse 服务），变更日志在 v1.0.0-rc.15 里对应的说明是为需要可扩展日志存储与查询的部署新增了 ClickHouse 日志存储支持。配套还有 LOG_SQL_CLICKHOUSE_TTL_DAYS 控制保留天数，官方注释写明不设或设为 0 表示不自动删除，设成正整数则按对应天数保留。

清理侧，管理接口里有一个删除历史日志的接口（DELETE /api/log/，需要管理员权限）。同在 v1.0.0-rc.15，官方新增了带持久化清理进度跟踪的系统任务执行器，用于长时间运行的维护任务，并说明日志清理行为随之简化。

顺带说一下日志相关的接口权限分层，写监控脚本时会用到：GET /api/log/、GET /api/log/search、GET /api/log/stat 都标注需要管理员权限；GET /api/log/self、GET /api/log/self/search、GET /api/log/self/stat 标注为登录后的普通用户权限；而 GET /api/log/token 官方标注是无需鉴权、按令牌查询。最后这一条要格外注意——它意味着谁拿到令牌谁就能查到对应的日志，令牌的保管等级要按这个来定，相关做法见 API Key 安全管理。

多节点部署下，日志归谁

多机部署会额外引入一类困惑：这条日志到底是哪个节点写的。官方 compose 里有 NODE_NAME 环境变量，注释写明它是用于在审计日志中标识节点身份的节点名称，并建议多节点或容器部署时设置；变更日志在 v1.0.0-rc.15 补充了未设置时默认回落到机器 hostname 的行为。异步任务方面，v1.0.0-rc.16 修复过异步任务用量日志的归属问题，改为归到发起该任务的节点。

集群的排错思路和单机不同，官方在集群部署文档的 Troubleshooting 一节列的是节点间数据不同步、负载不均、会话丢失三类，检查项集中在所有节点的 SQL_DSN 是否指向同一个库、SESSION_SECRET 是否完全一致、Redis 拓扑与 SYNC_FREQUENCY 的缓存收敛窗口是否可接受。这几类问题在用量日志里是看不出来的，只能从进程日志和配置比对入手。

最容易栽的坑

把官方文档里这几处能确认的信息串起来，可以形成一条三步排查路径（顺序是本文归纳的，官方没有把它们写成一套流程）：先 curl /api/status 确认服务活着，再看用量日志确认请求有没有被记下来（记下来了说明已经进了网关、失败在网关内部或上游；根本没记说明请求压根没到），最后打开 ERROR_LOG_ENABLED 去拿上游的原始报错。

最容易栽的坑排第一的仍然是那个开关——错误日志默认不记，很多人在「日志里什么都没有」的状态下猜了半天，其实是自己没开。排第二的是把令牌额度和账户额度混为一谈，官方 FAQ 专门为此列了一条。排第三的是忘了重试与自动禁用会改变日志的形态，看到条数对不上就以为丢日志。

至于流式请求超时，官方 compose 注释里提到 STREAMING_TIMEOUT 控制流模式的无响应超时，并说明出现空补全时可以尝试调大——具体默认值以官方文档当前版本为准，注意官方 compose 注释与环境变量文档在这一项的默认值上表述并不一致，改之前建议以你部署的那个版本的文档为准。