This release is a pre-release and may not be stable for production use.
PortBoard
发现和管理本地开发服务的终端仪表盘。
PortBoard 想回答一个看似简单的问题：
我的电脑上正在运行什么，又该从哪里访问它？
现代开发环境中经常同时运行前端、API、数据库、容器，以及一些早已忘记的开发服务器。PortBoard 将它们汇总到一个快速、清晰的终端界面中。
[!NOTE] PortBoard 目前仍处于早期 Alpha 阶段。核心发现能力和终端工作流已经可用，但公共接口仍可能调整。
当前功能
PortBoard 提供支持手动刷新、筛选和排序的实时终端仪表盘：
uv run portboard
仪表盘快捷键：
r：立即刷新；f/Esc：聚焦或清空筛选。p、o、n：按项目、端口或进程排序；再次按下可反向排序。Enter或d：查看所选服务的完整详情。w：查看扫描警告和完整诊断信息。c：复制所选 HTTP 服务 URL；b：在默认浏览器中打开。x：停止所选进程。PortBoard 会显示 PID、命令和端口，要求确认，并在发送终止请求前重新验证进程。q：退出。
仪表盘启动时扫描一次，之后仅在按下 r 时刷新。如需定时自动刷新，可主动指定刷新间隔：
uv run portboard --refresh-seconds 3
HTTP 监听器会显示响应状态和探测延迟。4xx 或 5xx 响应会标记为不健康，但仍会作为可复制或打开的 HTTP 端点显示。其他 TCP 监听器会保留在列表中，状态为 listening，且不显示延迟。
当 Docker 可用时，PortBoard 还会为主机监听端口标记对应的运行中容器及其内部端口。未安装 Docker 或无法访问 Docker 守护进程时，只会增加警告，不会中断服务发现。
对于绑定到局域网可访问接口的 HTTP 服务，按 l 可显示所选局域网 URL 的二维码，供同一网络中的手机或平板扫描。
脚本和问题报告也可以使用具有版本化契约的 JSON 快照：
uv run portboard --json
JSON 会报告可见的 TCP 监听器、尽力获取的进程信息、最近的 Git 项目，以及服务响应本地短探测时的 HTTP 状态。如果操作系统限制访问某个进程，命令会保留其余结果并报告警告。如果两种系统监听器发现方式都不可用，JSON 模式会以非零状态退出，避免返回具有误导性的空快照。
界面预览
┌ Project Port Status Process URL
│ my-blog 3000 healthy node http://localhost:3000
│ shop-api 8000 healthy uvicorn http://localhost:8000
│ postgres 5432 running docker localhost:5432
│ old-project 5173 unhealthy vite http://localhost:5173
└
当前 Alpha 版本可以：
- 自动发现监听端口及其进程。
- 显示进程、工作目录、命令和 Git 仓库。
- 识别 HTTP 服务并检查健康状态。
- 在 Docker 可用时显示端口映射。
- 复制或打开服务 URL，并停止不再需要的进程。
- 在 macOS、Linux 和 Windows 上提供实时终端界面。
为什么选择 PortBoard？
现有命令通常只能分别回答单个问题：lsof 查找端口，容器工具列出映射，进程管理器监管已声明的应用。PortBoard 的目标是在无需提前配置项目的情况下，提供一个真正有用的本地服务总览。
安装
curl
直接安装适用于当前平台的最新可执行文件，无需 Python 或 Node.js：
curl -fsSL https://raw.githubusercontent.com/LeonPure/portboard/main/install.sh | sh
安装器会识别 macOS/Linux 和 arm64/x64，使用 SHA256SUMS 校验发布归档，并默认安装到 ~/.local/bin。如果尚无稳定版本，会自动使用最新的预发布版本。
该 shell 安装器面向 macOS 和 Linux。Windows 用户可以使用下方的 uvx 或 npx，其中 npm 发行版会根据设备自动安装原生 x64 或 ARM64 .exe。
Homebrew
brew install LeonPure/tap/portboard
uv
无需持久安装即可运行最新版：
uvx portboard
全局安装：
uv tool install portboard
npm
无需持久安装即可运行最新版：
npx @leonpure/portboard
全局安装：
npm install -g @leonpure/portboard
npm 发行版支持 macOS 15+、兼容 Ubuntu 22.04 的 Linux 和 Windows 上的 arm64 与 x64。其他受支持环境仍可使用 Python 发行版；不支持 32 位 Windows x86。
开发
项目面向 Python 3.11+，主要使用：
本地开发命令：
uv sync
uv run portboard --json
uv run ruff check .
uv run mypy
uv run pytest
uv build
CI 会在 macOS、Linux 和 Windows 上使用 Python 3.11 与 3.13 执行相同检查。
路线图
计划中的里程碑见 ROADMAP.md，产品构想见中文说明。
目标模块边界、依赖规则和实现顺序定义在架构文档中。
参与贡献
欢迎提交想法、问题报告和拉取请求。开发流程见 CONTRIBUTING.md，安全漏洞请按照 SECURITY.md 私下报告。
版本历史记录在 CHANGELOG.md 中。
许可证
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file portboard-0.1.0a3.tar.gz.
File metadata
- Download URL: portboard-0.1.0a3.tar.gz
- Upload date:
- Size: 83.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ea91c03a251c4c75b01b8f9a1000fdf2d221ac45a339d1dd513f1c1bc02e7402
|
|
| MD5 |
4db7ca32da4fb7edf593c93d0e0e9dd5
|
|
| BLAKE2b-256 |
dd8f554ce2c5deedf963fad14ebc1a2e8357bf5d4a997d5dd3df4a135e3cfa6a
|
Provenance
The following attestation bundles were made for portboard-0.1.0a3.tar.gz:
Publisher:
release.yml on LeonPure/portboard
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
portboard-0.1.0a3.tar.gz -
Subject digest:
ea91c03a251c4c75b01b8f9a1000fdf2d221ac45a339d1dd513f1c1bc02e7402 - Sigstore transparency entry: 2185146827
- Sigstore integration time:
-
Permalink:
LeonPure/portboard@1c6d405d385103f989aec83254121cf0de50a906 -
Branch / Tag:
refs/tags/v0.1.0a3 - Owner: https://github.com/LeonPure
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@1c6d405d385103f989aec83254121cf0de50a906 -
Trigger Event:
push
-
Statement type:
File details
Details for the file portboard-0.1.0a3-py3-none-any.whl.
File metadata
- Download URL: portboard-0.1.0a3-py3-none-any.whl
- Upload date:
- Size: 32.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
78607d90842f7f0a4e41e037ba51aa608332583f16d35e39cb46d11d43cbd598
|
|
| MD5 |
36d50fceb7085a5ee176062630e566e1
|
|
| BLAKE2b-256 |
beb6e484071f0ea9440a305a9da1209b130df816e21cb8e5e90b7ed340ee3a2c
|
Provenance
The following attestation bundles were made for portboard-0.1.0a3-py3-none-any.whl:
Publisher:
release.yml on LeonPure/portboard
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
portboard-0.1.0a3-py3-none-any.whl -
Subject digest:
78607d90842f7f0a4e41e037ba51aa608332583f16d35e39cb46d11d43cbd598 - Sigstore transparency entry: 2185147037
- Sigstore integration time:
-
Permalink:
LeonPure/portboard@1c6d405d385103f989aec83254121cf0de50a906 -
Branch / Tag:
refs/tags/v0.1.0a3 - Owner: https://github.com/LeonPure
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@1c6d405d385103f989aec83254121cf0de50a906 -
Trigger Event:
push
-
Statement type:
