端口又冲突了？装上这个红绿灯看板，群晖端口一目了然

发表于 分类于 Waline： 阅读次数： 本文字数： 3.6k 阅读时长 ≈ 3 分钟
Port-Light 是一个本地 Web 看板，用红绿灯网格展示服务器端口占用情况，适合管理大量 Docker Compose 栈。

简介

什么是 Port-Light ？

Port-Light 是一个本地的 Web 看板，用「红绿灯」网格直观展示服务器上 哪些端口已被占用。它专为运行大量 Docker Compose 栈、经常忘记哪个端口被占用的 homelab 玩家设计，把三类数据源合并成一张端口占用地图。

主要特点

  • 三源合一：合并主机监听表（/proc 或 ss）、Docker API（容器名、状态、镜像、端口映射）以及 Compose 文件声明（即使栈已停止也能显示规划中的端口）。
  • 红绿灯网格：蓝色=已占用（正在监听或有容器映射）、琥珀色=已配置（Compose 声明但无监听）、绿色=搜索端口时推荐的附近空闲端口。
  • 端口搜索与冲突检测：按端口号搜索并给出附近空闲替代方案；当多个项目在同一绑定地址发布相同主机端口时发出冲突警告。
  • 常见端口内置命名：内置 SSH、Jellyfin、Postgres 等常见 homelab 端口名称，并支持本地自定义覆盖文件。
  • 多主机只读查看：一个 UI 可拉取局域网 / Tailscale 上其他 Port-Light 实例的占用地图（每台机器仍各自扫描自己）。
  • 丰富的外观与语言：设置页支持 system/dark/light 及 Gruvbox、Catppuccin、Nord 等十余种主题，UI 语言支持中文（简/繁）、日文等。
  • 可选 HTTP Basic Auth：通过 AUTH_USER / AUTH_PASSWORD 启用登录保护。
  • 开源免费：基于 MIT 协议开源，可免费使用和修改。

应用场景

  • Homelab 端口管理：同时运行几十个 Compose 栈时，一眼看清哪些端口已被占用、哪些被规划但空闲，避免重复绑定报错。
  • 新服务选址：部署新容器前，先搜索目标端口号，Port-Light 会列出附近可用的空闲端口作为备选。
  • 冲突排查：发现容器启动失败或端口冲突时，快速定位是哪个项目占用了目标端口。
  • 多机统一视图：在局域网 / Tailscale 内用单个 UI 聚合多台主机的端口占用地图，方便集中查看。

Port-Light界面截图

Port-Light 是一个 端口占用地图，而非容器管理器——它不启动/停止容器、不查看日志，也不会替代 Portainer

安装

在群晖上以 Docker 方式安装。

镜像同时发布在 Docker Hub 与 GHCR。本文以 Docker Hub 官方镜像 stepaniah/port-light:latest 为例。

在注册表中搜索 stepaniah ，选择第一个 stepaniah/port-light，版本选择 latest。

本文写作时， latest 版本对应为 v0.6.0；

由于镜像需要挂载 /var/run/docker.sock 与 /proc:/host/proc 这类系统卷，群晖 Docker 套件无法图形化完成挂载，因此只提供 docker cli 与 docker-compose 两种安装方式。

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 新建文件夹 port-light 和 子目录
mkdir -p /volume1/docker/port-light/{compose,data}

# 进入 port-light 目录
cd /volume1/docker/port-light

# 一键启动
docker run -d \
  --name=port-light \
  --restart=unless-stopped \
  -p 2100:2100 \
  -v $(pwd)/compose:/compose:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc:/host/proc:ro \
  -v $(pwd)/data:/data \
  -e COMPOSE_SCAN_DIR=/compose \
  stepaniah/port-light:latest

提示：-v /proc:/host/proc:ro 用于让容器读取宿主机进程网络命名空间，从而识别主机网络容器的端口；/var/run/docker.sock 即使只读也具备较强权限，建议通过反向代理保护 UI，或在不可信网络下使用 Docker Socket 代理。

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
version: '3.8'

services:
  port-light:
    image: stepaniah/port-light:latest
    container_name: port-light
    restart: unless-stopped
    ports:
      - "2100:2100"
    volumes:
      # 存放 compose 项目的目录（扫描其下一级子文件夹）
      - ./compose:/compose:ro
      # Docker socket（只读）
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # 宿主机进程网络命名空间，用于识别端口占用
      - /proc:/host/proc:ro
      # 数据目录：手动端口、隐藏列表、设置
      - ./data:/data
    environment:
      - COMPOSE_SCAN_DIR=/compose  # 扫描 compose 文件的目录
      - COMPOSE_SCAN_DEPTH=4       # 扫描子目录最大深度
      - COMPOSE_SCAN_MAX_FILES=400 # 每次刷新解析的 compose 文件上限
      - PORT_RANGE_START=1         # 空闲统计范围起点
      - PORT_RANGE_END=9999        # 空闲统计范围终点
      - PORT_LIGHT_DATA_DIR=/data  # 数据目录
      # - AUTH_USER=admin          # 可选 HTTP Basic Auth 用户名
      # - AUTH_PASSWORD=change-me  # 可选 HTTP Basic Auth 密码

然后通过 SSH 登录到您的群晖，执行下面的命令：

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 port-light 和 子目录
mkdir -p /volume1/docker/port-light/{compose,data}

# 进入 port-light 目录
cd /volume1/docker/port-light

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:2100 ，默认无需账号，打开即看到端口占用网格

可以对端口进行筛选

搜索时，会显示附近的端口，绿色为空闲端口

多主机场景可在「设置 → 占用图」中添加其他 Port-Light 实例地址，聚合查看

注意事项

  1. 局域网工具：默认无登录鉴权（除非设置 AUTH_USER / AUTH_PASSWORD），请勿直接暴露到公网，建议放在反向代理之后。
  2. docker.sock 权限：/var/run/docker.sock 即便只读也具备较强权限；若 UI 可能被不可信人员访问，优先使用 Docker Socket 代理。
  3. /proc 挂载：不挂载 /host/proc 时，网格只能显示 Docker 容器名，无法读取主机进程名；ss -tlnp 的进程名仍需宿主机网络 / 裸金属路径。
  4. 自定义文件先于挂载：若 bind mount custom_ports.json，需先在宿主机上创建该文件，否则 Docker 会生成同名目录导致应用读取失败。
  5. 多主机为只读：每台机器仍各自运行 Port-Light，hub 仅拉取其他实例数据；Docker 桥接容器常无法访问 Tailscale 的 100.x 网段，建议使用局域网 IP 或给 hub 设置 network_mode: host。

参考文档

StepaniaH/port-light: A web dashboard that shows your server’s port usage as a traffic-light grid.
地址：https://github.com/StepaniaH/port-light

stepaniah/port-light - Docker 镜像 | Docker Hub
地址：https://hub.docker.com/r/stepaniah/port-light

Port-Light 部署文档（Unraid / Podman / 反向代理 / 源码构建）
地址：https://github.com/StepaniaH/port-light/blob/main/docs/deployment.md