日志

日志用于排查设备智能体创建、设备接入、对话控制、定时任务、IM 接入、语音和视觉等运行问题。日常确认结果时应先查看对应功能的状态或执行历史，需要更底层的运行上下文时再使用日志。本地模式与平台均可在控制台查看和筛选记录；本地模式还可以直接读取日志文件。

打开日志页面

在控制台左侧导航点击日志，进入 /workspace/logs。页面主要分为两部分：

区域	用途
日志文件	查看当前可用的文件或平台归档，文件名通常类似 `device-agent-2026-05-11.log`；平台还显示服务来源与实例。
日志记录	查看选中文件里的最近记录，默认加载最近 200 条。

本地模式中，如果页面提示“文件日志已关闭”，点击右上角 日志配置，启用文件日志并保存。启用后，新记录会开始写入日志文件；启用前的历史记录不会补写。平台的归档与保留策略由部署管理员维护，页面不提供本地文件日志配置。

日志页面

平台日志

平台运行服务将结构化日志归档到共享数据库，控制台通过同一个日志入口查看。替换运行实例后，仍可读取保留期内已归档的记录，无需进入容器寻找本地文件。

日志列表中的来源类似 worker/instance-001/device-agent-2026-05-11.log，依次表示服务角色、实例标识和文件名。这是归档来源标识，不是服务器文件路径。api、worker、ingress 分别标识请求服务、智能体执行服务和设备接入服务。不同实例可能有同名日期文件，应结合请求或设备标识查看相关来源。

新记录归档存在短暂延迟，操作后可刷新查看。列表为空或归档不可用时，先确认所选来源与日期，再请管理员检查日志采集及数据库连接。

平台日志按保留策略清理，重要排查记录应及时下载。保留天数与采集策略由管理员按运维管理中的流程维护；本页后续本地目录、命令和文件配置仅适用于本地模式。

本地日志文件

文件日志默认写入运行时目录下的 logs 子目录：

运行方式	默认目录
仓库源码开发	`<repo>/.device_agent/logs`
已安装的生产二进制	`~/.device_agent/logs`

Agent Gateway 启动时会打印 Runtime Home。LOG_DIR=logs 会相对这个目录解析；如果 LOG_DIR 是绝对路径，则直接写入该路径。注意目录名是 .device_agent。

同一天日志按大小切分，文件名如下：

text

device-agent-2026-05-11.log
device-agent-2026-05-11.001.log
device-agent-2026-05-11.002.log

device-agent-YYYY-MM-DD.log 是当天第一个文件；超过 LOG_MAX_SIZE_MB 后继续写入 .001.log、.002.log 等分片。日志页面只列出符合这个命名规则的文件。

日志记录格式

日志文件是 JSON Lines，每行是一条完整 JSON 记录。

json

{
  "time": "2026-05-11T05:20:12.123Z",
  "level": "info",
  "module": "MQTT",
  "msg": "device connected",
  "requestId": "req-...",
  "productId": "product-001",
  "deviceId": "device-001",
  "topic": "device-agent/product-001/device/device-001/out",
  "args": [{ "durationMs": 18 }]
}

常用字段如下：

字段	说明
`time`	ISO 时间，始终按 UTC 写入。
`level`	`debug`、`info`、`warn` 或 `error`。
`module`	产生日志的后端模块，例如 `Gateway`、`HTTP`、`MQTT`、`Agent`、`Timer`、`Workflow`、`Tools`、`Skills`、`Voice`、`NTP`、`A2A-Channel`。
`msg`	日志消息。
`requestId` / `sessionId` / `traceId`	串联一次请求、对话或工具调用。
`namespace` / `productId` / `deviceId` / `topic`	定位租户、设备和 MQTT 主题。
`method` / `path` / `statusCode` / `durationMs`	HTTP 或服务调用相关信息。
`provider` / `tool`	模型服务、语音服务或工具执行相关信息。
`args` / `error`	补充上下文和异常信息，已做脱敏和截断。

包含 apiKey、authorization、cookie、password、secret、token、privateKey 等敏感含义的字段会写成 [redacted]。普通业务数据不会自动移除，分享日志前仍要检查设备 ID、主题、状态值和第三方用户 ID。

本地排查命令

在源码开发环境中，从仓库根目录查看日志：

bash

ls -lh .device_agent/logs
tail -n 200 .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.level == "error")' .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.deviceId == "device-001") | {time, level, module, msg, topic}' \
  .device_agent/logs/device-agent-2026-05-11.log
jq 'select(.requestId == "req-...")' .device_agent/logs/device-agent-2026-05-11.log

日志页面使用这些本地接口：

接口	用途
`GET /api/logs/files`	列出可读日志文件。
`GET /api/logs/tail?file=device-agent-2026-05-11.log&lines=200`	读取指定文件末尾记录，`lines` 最大为 `1000`。
`GET /api/logs/tail?file=device-agent-2026-05-11.log&before=<offset>`	继续读取更早记录，`before` 使用上一次响应里的 `nextBeforeOffset`。
`GET /api/logs/download?file=device-agent-2026-05-11.log`	下载指定日志文件。

查看和筛选记录

选中一个日志文件后，可以用以下方式定位问题：

操作	适合场景
刷新	设备刚上线、刚下发命令或刚完成一次对话后，刷新查看最新记录。
查看更早记录	当前 200 条不够时，继续加载更早的记录。
按级别筛选	只看 `warn` 或 `error`，快速定位异常。
按消息搜索	搜索错误关键词、平台名称、MQTT 主题或模型服务返回信息。
按模块筛选	只看某类能力的记录，例如 MQTT、HTTP、Timer、Workflow、Voice、Tools、A2A。
按请求 ID 搜索	对一次 HTTP 请求、对话或工具调用做链路排查。
按设备 ID 搜索	只查看某台设备的上报、命令和响应记录。

每条记录都可以展开查看完整 JSON。需要分享单条记录时，点击右侧复制按钮；需要导出当前文件时，点击右上角下载按钮。

筛选仅作用于已加载记录；检查更早时间或其他运行实例时，加载更早记录或切换文件。平台读取与下载请求还需携带来源角色和实例标识，见 API 参考。

日志级别

级别	说明
`debug`	最详细，适合临时排查复杂问题。记录量较大，不建议长期打开。
`info`	默认推荐级别，记录启动、连接、请求和主要运行状态。
`warn`	只记录可能影响功能但未必导致失败的问题。
`error`	只记录失败和异常。

日常使用建议保持 info。如果某个问题难以复现，可以临时切到 debug，复现后再调回 info。本地模式通过日志配置调整；平台由部署管理员按运行配置流程调整，并确认是否需要重启。

配置日志

本地模式中，在日志页面点击 日志配置，可以调整：

配置	作用
级别	控制记录多少日志。
控制台日志	是否在服务启动终端中输出日志。
文件日志	是否写入可在日志页面查看和下载的日志文件。
日志目录	文件日志保存位置。相对路径会放在设备智能体数据目录下。
单文件上限	单个日志文件达到上限后会自动切分。
保留天数	超过保留天数的旧日志会自动清理。
总容量上限	所有日志文件超过上限后，会优先删除更旧的文件。
文件日期时区	控制日志文件名按系统时区还是 UTC 日期生成。

保存后的日志配置会写入本地配置。.env 中的同名配置仍会在服务启动时覆盖控制台保存的值。

常用 .env 配置如下：

bash

LOG_LEVEL=info
LOG_CONSOLE_ENABLED=true
LOG_FILE_ENABLED=true
LOG_DIR=logs
LOG_MAX_SIZE_MB=50
LOG_RETENTION_DAYS=14
LOG_MAX_TOTAL_SIZE_MB=1024
LOG_TIMEZONE=system

配置入口见配置。

常见排查路径

问题	建议查看
设备没有出现在列表中	按设备 ID 搜索，确认设备是否连接 MQTT、上报在线状态或遥测。
对话控制没有生效	搜索设备 ID 或请求 ID，查看命令是否下发、设备是否返回响应。
定时任务失败或看起来没有执行	先查看定时任务的执行历史；需要更多上下文时，搜索任务 ID 或筛选 `Timer` 模块，再结合设备或 MQTT 记录确认设备动作。
IM 机器人没有回复	按模块或平台名称搜索，查看平台凭证、白名单、消息接收和回复是否正常。
语音没有识别或没有播报	按语音相关模块筛选，查看语音服务、会话和识别结果。
工具或技能没有执行	按工具相关模块筛选，查看工具加载、权限和执行结果。
模型服务返回异常	按 `error` 或模型服务名称搜索，查看请求失败、鉴权失败或超时信息。

下载或分享日志前，按日志记录格式核对业务数据中的敏感信息。

日志 ​

打开日志页面 ​

平台日志 ​

本地日志文件 ​

日志记录格式 ​

本地排查命令 ​

查看和筛选记录 ​

日志级别 ​

配置日志 ​

常见排查路径 ​

日志