NapCat Docker 端口与 1Panel 路径代理排坑笔记

目的：记录 NapCat、Docker Compose、1Panel 反向代理和 Webhook 之间的端口关系，避免以后再次把“容器端口、宿主机端口、公网路径”混在一起。

一、最终架构

当前链路：

二、必须先分清三层端口

1. NapCat 后台端口

在 NapCat 后台：

这里填写的端口，例如：

是 NapCat 容器内部监听端口。

例如：

这两个端口都属于容器内部。

2. Docker Compose 端口

当前 Compose 配置：

Docker 端口格式：

所以：

最重要的记忆方式：

例如：

3. 1Panel 反向代理端口

1Panel 运行在宿主机上，所以它访问的是宿主机端口：

当前环境中，正确关系是：

三、端口本身没有固定功能

Compose 中：

只表示开放并映射端口，不代表 3001 天生就是 HTTP、WebSocket 或其他服务。

真正决定端口功能的是 NapCat 后台的网络配置：

因此，端口的用途取决于 NapCat 中实际创建并启用的网络服务。

四、为什么两个 HTTP 服务器不能监听同一个端口

曾经出现过这种情况：

然后又创建：

结果访问：

请求始终命中已经占用 3000 的旧 HTTP 服务器，因此：

这不代表新 Token 错了，而是请求根本没有进入新 HTTP 服务器。

正确做法：

总结：

五、管理后台和 OneBot HTTP API 不是同一个服务

NapCat 有两类不同入口：

NapCat WebUI

用途：

NapCat OneBot HTTP API

用途：

如果域名反向代理到了 WebUI，却访问：

就会返回：

因为 WebUI 后端没有这个 API 路径。

所以出现 404 时，优先确认：

六、子域名不是必须的

子域名只是用来分类和隔离，不是解决多端口的唯一办法。

例如可以使用独立子域名：

也可以在同一个域名下按路径分流：

真正解决多端口问题的是：

准确理解：

七、当前 1Panel 路径代理配置

原规则

对应：

邮件 Webhook 专用规则

这里的 = 表示精确匹配：

外部请求：

会被 1Panel 改写并转发为：

NapCat 最终收到的仍然是标准接口：

八、为什么必须做路径改写

外部为了区分用途，使用：

但 NapCat 真正认识的是：

所以 1Panel 必须配置成：

作用：

如果把 /mail/send_group_msg 原样传给 NapCat，NapCat 可能返回 404。

九、当前 NapCat 网络配置建议

HTTP服务器 A

对应：

HTTP服务器 B

对应：

两个 HTTP 服务器必须使用不同容器端口。

十、Cloudflare 临时邮箱 Webhook 正式配置

URL

METHOD

HEADERS

BODY

精简版本：

包含正文版本：

正式使用建议采用 Header 传 Token，不把 Token 放在 URL 查询参数里。

十一、404 与 403 怎么判断

404 Not Found

代表：

常见原因：

403 token verify failed

代表：

常见原因：

判断方式：

通常意味着请求仍然命中了旧 HTTP 服务器。

十二、推荐的排查顺序

第一步：直接测试宿主机端口

测试宿主机 3001：

第二步：测试公网路径

结果判断

十三、curl 多行命令的坑

错误写法：

反斜杠后插入空行，会导致：

正确写法：

最稳妥的是整行执行：

十四、安全注意事项

不要长期把 Token 放在 URL：

因为 URL 容易出现在：

正式配置推荐：

如果 Token 曾经出现在截图、聊天记录或终端输出中，应立即重新生成。

十五、最终记忆口诀

十六、当前实际对应关系

最终核心：不要把 NapCat 后台端口、Docker 宿主机端口和公网 URL 当成同一层。它们是连续的三层映射关系。