端口映射原理与使用说明

它把这台 Mac 上只能本机访问的测试网页，通过一条独立的加密中转链路，临时变成外网可打开的网址。它适合演示和联调，不是生产发布系统。

一眼看懂

假设你的测试页面运行在 Mac 的 127.0.0.1:3000。创建时系统从新加坡专用测试池选择一个空闲端口，例如 19100；成功后，其他人访问 http://47.79.226.31:19100/，请求会沿独立加密链路回到这台 Mac 的 3000 端口。

因此，Mac 必须开机、联网，本地服务也必须持续运行。任意一段断开，公网网址都会失效，但原来的本地服务不会被修改。

1. Mac 本地服务例如 127.0.0.1:3000
你的测试项目实际运行处

→

2. SSH + FRPMac 主动连出
传输经过加密通道

→

3. 新加坡 FRP 控制端127.0.0.1:7001
公网无法直接登录

→

4. 公网入口FRP 直接监听 19100–19999
不经过 WAF/Nginx

完整链路是怎么工作的

外部浏览器 → 新加坡服务器 FRP 公网端口 → 独立 frps → SSH 本地转发 → 独立 frpc → Mac 的 127.0.0.1:本地端口

公网入口：FRP 直接映射

公网测试端口由新加坡服务器上的独立 frps 直接监听，不读取或修改服务器上的 WAF、Nginx、80/443 站点配置。FRP 控制端仍只绑定回环地址，公网访问者不能直接登录控制端。

FRP：负责反向代理

Mac 上的 frpc 主动连接云端 frps，给每条映射分配一个 19100–19999 范围内的公网测试端口。因为连接由 Mac 主动发起，所以 Mac 不需要公网 IP，也不需要在路由器上做端口转发。

SSH：负责保护 FRP 控制连接

云端 frps 只绑定 127.0.0.1:7001，公网无法直接访问。Mac 先建立 SSH 本地转发，把本机 127.0.0.1:17001 接到云端 127.0.0.1:7001，frpc 再通过这个入口登录 frps。FRP 本身同时启用了令牌认证和 TLS。

这套映射有独立的配置、凭据、进程和云端服务，不会改动原有 ~/.frp/frpc.toml，也不会重启脑图现有的 FRP 链路或 18124 / 18125 服务。

“实际配置盘点”是怎么得出结果的

页面不会只看这个控制台自己保存的记录。每次盘点会读取本机正式 FRP 配置和本控制台的专用配置，再通过严格 SSH 配置只读获取新加坡云端 FRP 配置与实际监听端口。页面不会读取 WAF/Nginx 配置。

本机 FRP读取 ~/.frp/*.toml 与专用配置，确认代理名称、本地端口、云端端口，以及哪份配置正被 frpc 进程使用。

云端 FRP读取云服务器 /data/frp 下的 FRP 配置，核对对应端口是否被允许、服务是否运行、端口是否实际监听。

公网监听核对新加坡服务器上对应 FRP 公网端口是否实际监听，不读取其他站点或代理配置。

汇总与标记本机、FRP 控制链路和公网监听都对齐时显示“链路正常”；少一段就保留线索并指出缺口。

什么时候会同步

系统每天北京时间 08:00 自动盘点一次。若这台 Mac 当时关机或服务没有运行，当天在 08:00 之后重新启动时会补跑一次；同一天补跑成功后不会反复执行。页面里的“立即同步”会当场重新读取本机与新加坡 FRP 状态。

盘点是只读的：原有 FRP 映射会显示为“现有配置·只读”，不会被这个控制台启停或删除。只有“本控制台创建的映射”才提供管理按钮。若某个数据源暂时读不到，页面会保留上次成功结果并标为旧数据，避免一次网络波动把所有链路错误显示为空。

链路卡片的名称可以单独修改，也支持中文和其他字符。页面显示名只保存在本机专用设置中，不会回写 FRP 代理名或触碰正式映射；清空后恢复默认名称。

盘点快照只保存端口、配置路径、服务状态和核对结果，不保存或展示 FRP 令牌、SSH 密钥等凭据。当前汇总 TCP + HTTP / WebSocket 的 FRP 直连路径；UDP 和非 HTTP 服务不在这张网页链路表里。

新建一条映射时发生了什么

校验本地服务左侧每个端口都可以先“检测”，或直接点“创建映射”。后一种会先检测网页响应，再把端口和进程名称带入右侧表单。

选择公网端口默认从 19100 到 19999 中自动挑选：排除本控制台已有记录，再读取新加坡服务器实际监听端口，取第一个真正空闲的端口。手动指定也只能使用该范围。

生成独立 FRP 配置把“新加坡公网端口 → Mac 本地端口”的关系写进专用 frpc 配置，并确保专用 SSH 和 FRP 进程正常。

检查进程与端口系统等待独立 frpc 启动，并检查新加坡公网端口是否已经监听。启动等待上限是 5 秒。

实际访问公网网址系统从外部入口请求一次生成的网址，成功后在列表里显示 HTTP 状态和测试时间。

自动发现和手动检测有什么区别

自动发现

读取 macOS 当前的 TCP LISTEN 快照，列出端口、监听地址和进程名。它不扫描全部 65535 个端口，也不会逐个访问发现的服务，所以速度快、干扰小。

列表是瞬时结果。服务刚启动或刚停止时，点右上角刷新按钮重新读取。点某一行的“创建映射”会自动检测并把可用网页端口带入创建表单。

手动检测

只检查你填写的一个端口：先尝试连接 127.0.0.1，连通后再发送一次 HTTP HEAD / 请求。即使返回 404 或 405，也说明它确实会说 HTTP，可以继续映射。

TCP 能连通但识别不到 HTTP 时会给出警告。这通常是数据库、SSH 或其他非网页协议，不适合公开映射。

自动发现只能看到正在监听的 TCP 端口。只绑定其他网卡地址、只使用 UDP、已停止、运行在另一台机器或容器里但没有暴露到 Mac 回环地址的服务，不会被判定为可用网页服务。

已映射列表里的操作

操作	会发生什么	本地服务会怎样
打开	在新标签页访问公网网址。	不改动。
测试	由系统实际请求公网网址，记录 HTTP 状态、耗时和时间。	会收到一次普通网页请求。
停用	移除对应 FRP 代理并关闭公网测试端口，但保留记录，之后可用同一端口恢复。	不停止、不重启。
恢复	重新生成该条 FRP 配置，并再次开放公网测试端口。	不停止、不重启。
删除	永久移除映射记录和公网入口。原网址立即失效。	不停止、不删除项目。

安全、权限和明确边界

生成的公网网址本身没有登录保护。拿到网址的人都可能访问，所以不要映射数据库、系统后台、带真实客户数据的页面、开发调试面板或任何正式服务。

谁能管理本机访问者，或拥有 xmind 脑图“全权”权限的账号。只读、资料协作、其他项目的全权账号都不能调用控制接口。

本地端口允许 1–65535，包含两端。必须能从这台 Mac 的 127.0.0.1 访问；非法文字、0、负数和 65536 以上都会拒绝。

公网端口自动和手动指定都只允许 19100–19999，包含两端。端口池占满时会停止创建并明确提示，不会覆盖正式映射或已有服务。

支持的协议面向 HTTP 和 WebSocket。它不是任意 TCP / UDP 转发器，也不自动提供 HTTPS 证书。

可用性依赖 Mac 开机联网、本地服务运行、SSH、FRP 和新加坡云服务器同时正常。这里没有生产级可用性承诺。

隔离范围专用文件位于正式运行目录的 port-maps；专用云端服务名为 tentamind-portmap-frps，与正式 FRP 服务分离。

超时数字从哪里来

手动 TCP 检测 0.5 秒、HTTP 识别 0.8 秒、公网连通测试 8 秒、进程启动等待 5 秒。这些是当前实现里的工程默认值，不是网络实测后得出的服务承诺；慢服务可能出现“实际能开，但自动检测超时”的情况。

看到异常时怎么判断

页面状态	通常说明	先检查什么
未发现端口	本地服务没启动，或没有在 Mac 可见的 TCP 地址上监听。	先在 Mac 浏览器打开 `http://127.0.0.1:端口/`，再重新扫描。
TCP 开，非 HTTP	端口存在，但没有返回标准 HTTP 响应，也可能只是响应超过 0.8 秒。	确认这是网页服务；若是数据库或其他协议，不要映射。
SSH + FRP 异常	Mac 到云端的专用隧道或 frpc 没有正常运行。	检查 Mac 网络是否正常；停用后恢复，系统会重建专用链路。
云端未就绪	专用 frps 或云端状态检查失败。	这不是阿里云安全组的唯一问题，还要检查云端服务进程。
公网测试失败	公网端口尚未监听、链路中断，或本地服务拒绝请求。	依次看整体链路四段，再确认本地端口仍能访问。
HTTP 404 / 405	链路通常已经通，只是根路径或 HEAD 方法不是该应用支持的页面。	直接打开完整业务路径验证，不要只凭 404 判定映射失败。