Skip to content

端口规范与登记表 ​

本页是跨工具共用的端口规范。所有端口号以登记表为准,代码、.env、隧道配置均是登记表的下游。不要凭记忆报端口号——端口会漂移,唯一可信来源是登记表。

本页记录 18i(主班实例)与 8i(从班实例)两台机器的端口分配规范。新起服务、改端口、或排查端口冲突(EADDRINUSE、本机能开别人打不开、403、双绑、公网能连但空响应)时使用。

什么时候用这页 ​

  • 新起一个服务,要决定它监听哪个端口
  • 已有服务要换端口(迁移、避让、收敛编号)
  • 端口起不来 / 起来了但页面不对 / 本机能开别人打不开 / 公网能连却返回空
  • 想知道某个端口是谁的、能不能用
  • 改完端口做一遍全局体检

三条铁律 ​

  1. 一个端口只属于一个服务,且这个归属必须能在登记表里查到。没登记的端口等于没有归属。
  2. 先登记,再落地。登记表是唯一事实来源,代码、.env、隧道配置都是它的下游。
  3. 按「有没有页面」分流。有页面的进 9000–9099,没页面的进 10000–19999。这条判据能解决九成的抢端口问题。

段位表 ​

段用途归属
1024–4999动态 / 临时,不得常驻外部
5000–5999dev 已退役,不再分配—
6100–6199设备代理例外区,pcagent 固定 6186例外
8000–8999第三方与校方软件禁区,唯一例外 8999 = noVNC禁止自研
9000–9099有页面服务(prod),个位即服务位自研
9100–9199ClassIntra 第三方应用 / 插件,从 9101 起CI 插件
10000–19999无页面服务(WS / relay / 网关 / 内部 API),按 R10 推导自研
20000–20499dev(前半),2000d自研
20500–20999test / 演练 / 靶机(后半),2050d自研
21000–29999预留,9000/10000 用尽后再启用自研
49152–65535Windows 动态端口,禁止固定绑定禁止

个位是 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 或明确 IPlocalhost 可能解析到 ::1,表现不一致
R5新端口必须落在已规划段内,跨段需在登记表说明理由段被第三方占满后无号可用
R610000–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 按主服务个位对齐调试实例与生产抢端口,或误连测试库
R12CI 第三方应用独立成段 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 五进程生产部署

基于 MIT 协议 开源 · 加入 QQ 群【ClassIntra】
本项目 LOGO 来源于公共素材库,仅用于非商业教育目的,权利归其各自所有者;与其他项目 LOGO 的相似纯属巧合。
The logo is sourced from a public domain asset library and is used for non-commercial, educational purposes only.