[Bug] Docker + NapCat 接收语音消息时报错：Voice processing failed: not a valid file: xxx.amr

[AmeiMiao]

What happened / 发生了什么

通过 NapCat 接收 QQ 语音消息时，AstrBot 会报错：
Voice processing failed: not a valid file: ecfafc876dcddeac9afdad3fdfe2fc92.amr

相关日志:
[Core] [INFO] [core.event_bus:61]: [default] [个人QQ(aiocqhttp)] Sense/3*****28: [ComponentType.Record]
[Core] [WARN] [v4.23.2] [preprocess_stage.stage:81]: Voice processing failed: not a valid file: ecfafc876dcddeac9afdad3fdfe2fc92.amr

排查结果
NapCat 侧实际上已经成功把语音文件下载到了本地，例如：
/opt/1panel/apps/Astrbot/ntqq/nt_qq_253aed7e0b8a3e5ea712a7ff1a9d2b39/nt_data/Ptt/2026-04/Ori/ecfafc876dcddeac9afdad3fdfe2fc92.amr

也就是说，这不是“语音文件没有下载成功”的问题。
问题更像是： AstrBot 在处理 Record 组件时，只拿到了 file 字段里的文件名或一个当前容器内不可访问的路径，然后直接判定为无效文件。

怀疑的根因
问题位置大概率在：
astrbot/core/message/components.py

具体是：
Record.convert_to_file_path
Record.convert_to_base64
当前 Record 的处理逻辑主要依赖 self.file，而没有像 Image 一样优先使用：self.url or self.file

在 Docker + NapCat 场景下，这会导致：file 只是文件名，或者是 NapCat 容器内路径。AstrBot 容器无法直接访问，于是报错 not a valid file

建议修复
建议让 Record 组件和 Image 组件保持一致，在以下两个函数中优先使用：url = self.url or self.file

涉及函数：
Record.convert_to_file_path
Record.convert_to_base64

例如应从类似：
if not self.file:
raise Exception(...)
调整为：
url = self.url or self.file
if not url:
raise Exception(...)
并后续统一使用 url 处理。

本地验证结果
本地修改 astrbot/core/message/components.py 后，让 Record 使用 self.url or self.file，该报错不再出现，语音消息可以继续进入后续 STT 流程。

Reproduce / 如何复现？

复现步骤

1. 使用 Docker 部署 AstrBot。
2. 使用 NapCatQQ 作为个人QQ协议端，通过 aiocqhttp / OneBot 链路接入 AstrBot。
3. 确保 QQ 语音消息可以正常从 NapCat 上报到 AstrBot。
4. 给机器人发送一条 QQ 语音消息。
5. 查看 AstrBot 日志。

AstrBot 收到语音消息后，日志中出现：
[Core] [INFO] [core.event_bus:61]: [default] [个人QQ(aiocqhttp)] Sense/3*******8: [ComponentType.Record]
[Core] [WARN] [v4.23.2] [preprocess_stage.stage:81]: Voice processing failed: not a valid file: ecfafc876dcddeac9afdad3fdfe2fc92.amr

额外验证
此时在 NapCat/NTQQ 数据目录中可以找到对应语音文件，例如：
/opt/1panel/apps/Astrbot/ntqq/nt_qq_253aed7e0b8a3e5ea712a7ff1a9d2b39/nt_data/Ptt/2026-04

AstrBot version, deployment method (e.g., Windows Docker Desktop deployment), provider used, and messaging platform used. / AstrBot 版本、部署方式（如 Windows Docker Desktop 部署）、使用的提供商、使用的消息平台适配器

• AstrBot 版本：v4.23.2
• 部署方式：Docker
• 平台适配器：个人QQ（aiocqhttp）
• 协议端：NapCatQQ

OS

Linux

Logs / 报错日志

相关日志:
[Core] [INFO] [core.event_bus:61]: [default] [个人QQ(aiocqhttp)] Sense/3*******8: [ComponentType.Record]
[Core] [WARN] [v4.23.2] [preprocess_stage.stage:81]: Voice processing failed: not a valid file: ecfafc876dcddeac9afdad3fdfe2fc92.amr

Are you willing to submit a PR? / 你愿意提交 PR 吗？

• Yes!

Code of Conduct

• I have read and agree to abide by the project's Code of Conduct。

[dosubot]

你的分析非常准确。Record 类的 convert_to_file_path 和 convert_to_base64 方法确实只使用了 self.file，而 Image 类则采用了 url = self.url or self.file 的回退模式 [1]。在 Docker + NapCat 场景下，self.file 只是一个文件名或容器内路径，AstrBot 容器无法访问，而 self.url 通常包含可下载的 HTTP 地址，因此应该优先使用。

这个问题此前已有类似的语音处理 bug 被报告和修复过（如 PR #6869 修复了 Record 错误使用 download_image_by_url() 导致音频被存为 .jpg 的问题）[2]，但 self.url or self.file 的回退逻辑一直没有被补上。

你提出的修复方案（让 Record 与 Image 保持一致，优先使用 self.url）是正确的方向，且你已经本地验证通过。建议提交 PR 来修复此问题。

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.