bncfbb/natmap-ui repository overview

⁠natmap-ui

natmap-ui 是一款专为 natmap 打造的高性能可视化管理面板。它不仅能实时监控 NAT 映射状态，还提供了极其强大的自动化 Hook 链式调用系统，帮助您在复杂的网络环境下（如 iKuai、OpenWrt）轻松维护公网服务。

⁠✨ 核心特色

• 可视化管理：Web 界面直观展示公网 IP、端口映射状态及 tcping 连通性检测 结果。
• 自动化 Hook 系统：支持自定义 Python 脚本，在映射变动时触发自动化逻辑。
• WebHook 链式调用：支持多个 WebHook 按顺序执行。
• 变量模板引擎：支持静态/动态变量模板，可从上一步骤的返回结果中提取数据，实现复杂的逻辑联动。
• 同 Host 共享 Cookies：在链式调用中，后续步骤可共享先前的 Cookies 状态。
• Nginx Proxy Manager (NPM) 集成：支持自动上报映射信息至 NPM，配合域名实现无端口访问。
• Host 网络支持：原生支持 --net=host 模式，确保探测流量直达公网，避免容器 NAT 干扰。

⁠🛠️ 快速部署

在 Linux 环境中使用以下命令启动：

docker run -d \
  --name=natmap-ui \
  --restart=always \
  --net=host \
  -v config:/config \
  -v scripts:/scripts \
  bncfbb/natmap-ui:latest

⁠📂 挂载点说明

• /config: 存储面板配置文件、映射规则及持久化数据
• /scripts: 存储自定义 Python 脚本

⁠🐍 自定义脚本实例 (Python)

您可以编写 Python 脚本处理映射后的逻辑。将"实例名称.py"脚本放入 /scripts 目录即可在面板中调用：

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
import logging

# 配置日志输出
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s %(filename)s[line:%(lineno)d] %(levelname)s %(message)s',
)

def hook_func(public_ip, public_port, ip4p, local_port, protocol, local_ip):
    """
    当 natmap 状态更新时，此函数将被触发
    """
    logging.info(f'测试 {public_ip}:{public_port}')
    # 示例：此处可添加发送请求或同步状态的逻辑

⁠💡 使用建议

• 解决透明代理劫持 如果您的网络中存在 PassWall 等透明代理，建议在代理插件的“直连列表”中添加运营商 CGNAT 的公网出口 IP 段，以确保面板自带的 tcping 连通性检测 能够获取真实状态，避免被代理代答。

• API 请求技巧 在使用 WebHook 链时POST数据提交表单字符串（如 a=1&b=2）时，请务必手动设置请求头，以避免后端返回 400 错误： {"Content-Type": "application/x-www-form-urlencoded"}

⁠🔓 访问信息

• 访问地址：http://服务器IP:8010
• 默认账号：admin
• 默认密码：admin