NapCat Docker 端口与 1Panel 路径代理排坑笔记
2026-07-23
杂乱的知识
type
Post
status
Published
date
Jul 23, 2026
slug
NapCat-Docker-1panel
summary
记录 NapCat、Docker Compose、1Panel 反向代理和 Webhook 之间的端口关系，避免以后再次把“容器端口、宿主机端口、公网路径”混在一起。
tags
记录
category
杂乱的知识
icon
password
NapCat Docker 端口与 1Panel 路径代理排坑笔记
目的：记录 NapCat、Docker Compose、1Panel 反向代理和 Webhook 之间的端口关系，避免以后再次把“容器端口、宿主机端口、公网路径”混在一起。
一、最终架构
当前链路：
二、必须先分清三层端口
1. NapCat 后台端口
在 NapCat 后台：
这里填写的端口，例如：
是 NapCat 容器内部监听端口。
例如：
这两个端口都属于容器内部。
2. Docker Compose 端口
当前 Compose 配置：
Docker 端口格式：
所以：
Compose 配置 | 实际含义 |
3002:3000 | 宿主机 3002 → NapCat 容器 3000 |
3001:3001 | 宿主机 3001 → NapCat 容器 3001 |
6099:6099 | 宿主机 6099 → NapCat 容器 6099 |
最重要的记忆方式：
例如：
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：第二步：测试公网路径
结果判断
本地端口 | 公网路径 | 结论 |
成功 | 成功 | 全部正常 |
成功 | 404 | 1Panel 路径或代理规则错误 |
成功 | 403 | 公网请求命中错误后端或 Header 未正确传递 |
403 | 403 | NapCat Token 或 HTTP服务器配置错误 |
连接失败 | 任意 | NapCat 没监听该端口，或 Docker 没映射 |
十三、curl 多行命令的坑
错误写法：
反斜杠后插入空行，会导致：
正确写法：
最稳妥的是整行执行：
十四、安全注意事项
不要长期把 Token 放在 URL：
因为 URL 容易出现在：
正式配置推荐：
如果 Token 曾经出现在截图、聊天记录或终端输出中，应立即重新生成。
十五、最终记忆口诀
十六、当前实际对应关系
最终核心：不要把 NapCat 后台端口、Docker 宿主机端口和公网 URL 当成同一层。它们是连续的三层映射关系。
Loading...
