端口规范与登记表
本页是跨工具共用的端口规范。所有端口号以登记表为准,代码、
.env、隧道配置均是登记表的下游。不要凭记忆报端口号——端口会漂移,唯一可信来源是登记表。
本页记录 18i(主班实例)与 8i(从班实例)两台机器的端口分配规范。新起服务、改端口、或排查端口冲突(EADDRINUSE、本机能开别人打不开、403、双绑、公网能连但空响应)时使用。
什么时候用这页
- 新起一个服务,要决定它监听哪个端口
- 已有服务要换端口(迁移、避让、收敛编号)
- 端口起不来 / 起来了但页面不对 / 本机能开别人打不开 / 公网能连却返回空
- 想知道某个端口是谁的、能不能用
- 改完端口做一遍全局体检
三条铁律
- 一个端口只属于一个服务,且这个归属必须能在登记表里查到。没登记的端口等于没有归属。
- 先登记,再落地。登记表是唯一事实来源,代码、
.env、隧道配置都是它的下游。 - 按「有没有页面」分流。有页面的进
9000–9099,没页面的进10000–19999。这条判据能解决九成的抢端口问题。
段位表
| 段 | 用途 | 归属 |
|---|---|---|
1024–4999 | 动态 / 临时,不得常驻 | 外部 |
5000–5999 | — | |
6100–6199 | 设备代理例外区,pcagent 固定 6186 | 例外 |
8000–8999 | 第三方与校方软件禁区,唯一例外 8999 = noVNC | 禁止自研 |
9000–9099 | 有页面服务(prod),个位即服务位 | 自研 |
9100–9199 | ClassIntra 第三方应用 / 插件,从 9101 起 | CI 插件 |
10000–19999 | 无页面服务(WS / relay / 网关 / 内部 API),按 R10 推导 | 自研 |
20000–20499 | dev(前半),2000d | 自研 |
20500–20999 | test / 演练 / 靶机(后半),2050d | 自研 |
21000–29999 | 预留,9000/10000 用尽后再启用 | 自研 |
49152–65535 | Windows 动态端口,禁止固定绑定 | 禁止 |
个位是 0 的主服务位(如 9000)没有附属编号空间,需要附属服务时别选它。
硬性规则
| # | 规则 | 违反的典型后果 |
|---|---|---|
| R1 | 同一端口不得被两个服务分别绑定(含一个 127.0.0.1、一个 0.0.0.0) | 回环走 A、局域网走 B → 「别人能开、本机打不开」 |
| R2 | 只服务本机的组件必须显式绑 127.0.0.1,且不与对外服务共用端口 | 同 R1 |
| R3 | 端口必须来自配置(.env / ecosystem),不得硬编码 | 迁移漏改一处就断链 |
| R4 | 代理 / 探活目标不得写 localhost,要写 127.0.0.1 或明确 IP | localhost 可能解析到 ::1,表现不一致 |
| R5 | 新端口必须落在已规划段内,跨段需在登记表说明理由 | 段被第三方占满后无号可用 |
| R6 | 10000–19999 不得暴露到公网 | 未鉴权的实时通道直接可达 |
| R7 | 第三方软件端口(8000–8999 等)一律视为禁区,即使当下空闲 | 校方软件升级后自行占用,自研被动崩 |
| R8 | 临时调试端口用完即释放,不写进配置文件 | 残留进程被误认为「服务在跑」 |
| R9 | 有页面 → 9000–9099;无页面 → 10000–19999 | 无页面服务占页面段,把同端口页面服务挤成 403 |
| R10 | 附属端口 = 1 + (4−N) 个 0 + N 个主服务个位(N = 第几个附属,1–4) | 编号无规律,跨机迁移必漂移 |
| R11 | 不跨环境复用端口:dev 20000–20499、test 20500–20999、prod 9000/10000;dev/test 按主服务个位对齐 | 调试实例与生产抢端口,或误连测试库 |
| R12 | CI 第三方应用独立成段 9100–9199,从 9101 起;附属端口同段 +10(9101 → 9111),不进 10000 段 | 插件自带默认端口撞主服务 |
| R13 | 设备代理例外:pcagent 固定 6186,不套 R9 / R10 | 代理混进自研段,把「有没有页面」的判据搅乱 |
取号决策树
它是不是自研服务?
├─ 不是(市场应用 / 插件) ─→ 9100–9199,从 9101 往后取
│ 附属端口 +10:9101 → 9111
│
├─ 是,有实际页面 ─────────→ 9000–9099 找空位,记下个位 d
│ (9005–9099 已全部归还自研,9000 留给总入口)
│
├─ 是,没有页面 ───────────→ 找归属主服务,取个位 d,按序拿:
│ 第1个 1000d → 第2个 100dd → 第3个 10ddd → 第4个 1dddd
│ 例:挂 9003 → 10003 / 10033 / 10333 / 13333
│ 没有归属就挂靠最近的空主服务位
│
├─ 设备端代理 ─────────────→ 6186(R13,不再新开号)
├─ 测试 / 演习 ────────────→ 2050d(20k 后半)
└─ 本地开发 ───────────────→ 2000d(20k 前半)五步落地
bash
# ① 查:确认没人占、编号合规
port.mjs next --kind page # 有页面服务自动取号
port.mjs next --kind headless --main 9004 # 无页面服务按 R10 推导
port.mjs lookup 9002 # 这个端口是谁的
# ② 登记:登记表加条目,status 先写 "reserved"
# ③ 落地:端口写进 .env / ecosystem.config.js,源码只读配置
# ④ 复核
port.mjs check # 登记表 vs 本机监听
port.mjs validate # 只查登记表自身是否合规
# 无 ERROR、本条目无 WARN 后,status 改为 "active"
# ⑤ 同步:改端口 = 改 5 处改端口要改的 5 个地方
| 位置 | 例 |
|---|---|
| 服务配置 | server/.env → PORT |
| 进程编排 | ecosystem.config.js → env.* |
| 反向代理 / 隧道 | frpc.ini → local_port |
| 前端引用 | Browser.vue 的端口判断、书签、控制台页面 |
| 登记表 | 端口登记表 |
顺序:先改下游(前端 / 隧道),再改上游(服务),最后改文档。反过来会让线上先断一段时间。
CLI
脚本 port.mjs 用绝对路径调用(在别的工具里 cwd 不一定是仓库,相对路径会找不到文件)。支持 --json。
| 命令 | 作用 |
|---|---|
port.mjs bands | 段位总览 |
port.mjs lookup <端口|服务|项目> | 查归属、来源、绑定、附属端口 |
port.mjs attached 9001 | 推导 4 个附属端口及其登记状态 |
port.mjs next --kind <page|headless|thirdparty|dev|test> [--main 900d] [--count n] | 取下一个可用号 |
port.mjs check [--port n] | 登记表 vs 本机监听 |
port.mjs validate | 只校验登记表:段位、R10、R12、R6、R13、重复归属 |
port.mjs sync | 从仓库刷新规范与登记表快照 |
在仓库里直接干活时,等价命令可在本地运行。check / validate 有 ERROR 为退出码 1,可挂 CI 或 prestart 钩子。
排障口诀
| 症状 | 大概率病因 | 动作 |
|---|---|---|
| 端口在听,但页面 403 / 内容不对 | 被同端口另一个服务截获 | 查绑定地址,不要先查服务日志 |
服务起不来,EADDRINUSE 指向 :::port | 有通配绑定占着 | 只看 127.0.0.1:port 的进程不算冲突 |
| 同一端口两个 PID | 双绑(SO_REUSEADDR) | 只保留 PM2 / 服务托管那一份 |
| 本机能开、别人打不开 | 绑到了 127.0.0.1,或回环被另一个服务截走 | 看实际绑定地址 |
| 一万段出现陌生端口 | 多半是第三方软件 | 先套 R10;不符合 R10 就别动 |
| 公网端口能连但返回空响应 | 隧道通了、后端没通 | 查 frpc 是否有多余实例,再确认 local_port 指向的进程在听 |
| AstrBot / Syncthing 的高位端口 | 第三方,不是自研 | 不符合 R10 就不要管 |
常用排障命令
bash
# 本机监听全貌
netstat -ano -p TCP | grep LISTENING
# 某端口是谁
netstat -ano -p TCP | grep ":9002"
tasklist /FI "PID eq <pid>" /FO CSV /NH高频陷阱
pm2 restart不重读ecosystem.config.js的env。改完端口必须pm2 startOrReload ecosystem.config.js --only <app> --update-env(或 delete + start),否则进程还监听着旧端口,而你以为改成功了。frpc/pcagent这类能被手动启动两次的进程,必须只留 PM2 一份。两份实例会导致隧道注册失败(already exists)或请求随机落到旧实例。- Python
HTTPServer.allow_reuse_address在 Windows 上等价SO_REUSEADDR,双绑不会报错,只会随机分流。看到同端口两个 PID,优先怀疑它。 localhost≠127.0.0.1。代理目标写localhost时,解析到::1还是127.0.0.1取决于系统,被占用时表现不一致。- 公网
remote_port与本地local_port是两回事。改本地端口时别顺手改公网端口(如10721是公网入口,不是本地 WS)。
登记表来源
完整规范(含实测分配表、冲突案例、迁移复现步骤)与可执行的登记表 JSON 维护在技能 skill port-registry 中,登记表为唯一事实来源。改完仓库里的登记表或规范后,跑一次 port.mjs sync 刷新技能快照;只在技能里改数值是错的——那是副本,下次 sync 会被覆盖。
下一步
| 你想做 | 去哪 |
|---|---|
| 部署 ClassIntra 主服务 | 10 分钟部署上线(保姆级) |
| 查看全部环境变量(含端口) | 配置项 |
| 生产部署与 PM2 五进程 | 生产部署 |

