一、PortNote介绍

1.1 PortNote简介

PortNote 是一个专为管理和记录网络端口使用情况而设计的工具，帮助用户清晰、有序地掌握整个基础设施中的端口分布。通过其简洁直观的网页界面，用户可以轻松添加服务器和虚拟机，分配并文档化各服务所使用的端口，从而有效预防端口冲突问题。PortNote 由 CoreControl 的开发者打造，致力于为运维中常被忽视的端口管理提供结构化、清晰且可控的解决方案。

1.2 PortNote主要特点

• 可视化端口管理：以清晰的界面展示所有服务器和虚拟机的端口使用情况。
• 支持多系统集中管理：可统一管理多个服务器与 VM 的端口信息。
• 避免端口冲突：通过提前规划和记录，防止不同服务之间出现端口冲突。
• 内置文档功能：允许用户为每个端口使用情况添加注释和说明，便于团队协作。
• 简洁易用的 Web 界面：操作简单，无需复杂配置即可快速上手。
• 端口使用历史追踪：记录端口变更历史，方便审计与回溯。
• 标签与分类功能：支持对端口和服务进行标签化管理，提升查找效率。
• 权限控制与协作支持：支持多用户访问与权限设置，适合团队使用。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为Ubuntu 22.04.1。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署PortNote端口自动检测工具。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven01:~#  systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2025-07-02 14:16:57 UTC; 21h ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 878 (dockerd)
      Tasks: 28
     Memory: 1.2G
        CPU: 1min 50.356s
     CGroup: /system.slice/docker.service
             ├─  878 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

3.2 检查Docker版本

检查Docker版本

root@jeven01:~# docker -v
Docker version 27.1.1, build 6312585

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven01:~# docker compose version
Docker Compose version v2.19.1

四、拉取PortNote镜像

拉取PortNote容器镜像，如下所示：

docker pull registry.cn-hangzhou.aliyuncs.com/jeson/postgres:17
docker pull registry.cn-hangzhou.aliyuncs.com/jeson/portnote-agent:latest
docker pull registry.cn-hangzhou.aliyuncs.com/jeson/portnote:latest

五、部署PortNote服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/portnote   &&  cd /data/portnote

5.2 编辑部署文件

在部署目录下，创建docker-compose.yaml文件。注意修改LOGIN_USERNAME和LOGIN_PASSWORD值，此为PortNote的登录账号和密码。

vim docker-compose.yaml

services:
  web:
    image: registry.cn-hangzhou.aliyuncs.com/jeson/portnote:latest
    ports:
      - "3000:3000"
    environment:
      JWT_SECRET:  3sXtLm9kQaRbVn7c8qWxYp2e5rTmZu6hLvBnKjPw=   # Replace with a secure random string
      USER_SECRET: aFg0Gz7FqXtJpNcR9vLmWs2dThnPqYwBeKxVrMc=  # Replace with a secure random string
      LOGIN_USERNAME: admin # Replace with a username
      LOGIN_PASSWORD: admin # Replace with a custom password
      DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"
    depends_on:
      db:
        condition: service_started

  agent:
    image: registry.cn-hangzhou.aliyuncs.com/jeson/portnote-agent:latest
    environment:
      DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"
    depends_on:
      db:
        condition: service_started

  db:
    image: registry.cn-hangzhou.aliyuncs.com/jeson/postgres:17
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

5.3 创建PortNote容器

执行以下命令，创建PortNote容器。

docker compose up -d

5.4 查看PortNote容器状态

检查PortNote容器运行状态，确保PortNote容器正常启动。

root@jeven01:/data/portnote#  docker ps
CONTAINER ID   IMAGE                                                           COMMAND                  CREATED          STATUS          PORTS                                    NAMES
ca21815924a5   registry.cn-hangzhou.aliyuncs.com/jeson/portnote:latest         "docker-entrypoint.s…"   27 seconds ago   Up 26 seconds   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp   portnote-web-1
dcc07ce0e1bc   registry.cn-hangzhou.aliyuncs.com/jeson/portnote-agent:latest   "./app"                  27 seconds ago   Up 26 seconds                                    portnote-agent-1
d9b6370a5a6f   registry.cn-hangzhou.aliyuncs.com/jeson/postgres:17             "docker-entrypoint.s…"   27 seconds ago   Up 27 seconds   5432/tcp                                    portnote-db-1

5.5 查看PortNote容器日志

检查PortNote容器运行日志，确保PortNote服务正常运行。

docker compose logs

六、访问PortNote服务

6.1 访问初始页

浏览器地址： http://<个人的服务器IP>:3000，访问PortNote的初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 登录PortNote

默认账号密码为我们在部署文件中自定义设置的，这里设置的为admin/admin。

七、PortNote基本使用

7.1 随机端口功能

点击点 Generate random port图标按钮，即可生成当前还未使用的随机端口。

7.2 端口自动扫描

点击“+”图标选项，进行添加服务器。填写服务器的IP地址和描述信息，可参考如下设置：

添加服务器完毕后，点击旁边的扫描图标，进行自动扫描服务器上的所有在使用的端口。

扫描完毕后，点击“Refresh Data”选项，即可显示所有扫描出正在使用的端口。

八、总结

通过本次使用 Docker 部署 PortNote 的实践，我们成功搭建了一个高效、可视化的端口管理工具，显著提升了基础设施中端口使用的透明度与可控性。整个部署过程简洁明了，借助 Docker 容器化技术实现了快速启动和隔离运行，保障了环境的一致性。PortNote 提供了清晰的 Web 界面，使用户能够轻松添加服务器信息并记录端口使用情况，有效避免了端口冲突问题。此次实战不仅展示了 Docker 在应用部署中的便捷性，也体现了 PortNote 作为一款轻量级端口管理工具在运维工作中的实用价值。