前言¶
在 DeepSeek Harness（DSH）里跑智能体或运维助手时，模型常会面对同一类问题：某个端口上是什么服务、systemd 单元或 Docker 容器谁占用了监听、Caddy 反代是否仍指向存活的上游、哪些地址对公网暴露。手工 ss、systemctl、docker ps 再对照 Caddyfile，步骤多且容易漏项。dsh-port-map 把这类信息整理成只读工具，供 DSH 调用，不打开、不关闭、不重配任何资源。
这是什么¶
dsh-port-map 是社区插件，维护者为 ozanstn1-stack，在插件目录中归类为 admin-security。简介为：Read-only port, service and Caddy route map for DeepSeek Harness。当前 npm 包版本为 0.1.0，许可证 MIT。
它面向已在主机上部署 DSH 的场景，用四个只读工具回答「谁在听哪个口」「路由是否 up」等问题，与直接 SSH 查表相比，信息被结构化后更适合交给 Harness 里的智能体做排查与说明。
核心功能¶
插件提供的工具均为 read-only，README 明确说明：Nothing is opened, closed or reconfigured.
| 工具 | 作用 |
|---|---|
listening_ports |
列出 TCP 监听：端口、绑定地址、可达范围（public / localhost / interface）、进程，以及所属的 systemd 单元或 Docker 容器。可按 scope、port 过滤。 |
service_map |
反向视图：每个单元/容器及其监听端口，并标出无人认领的端口。 |
caddy_routes |
解析 Caddyfile，得到 site → path → reverse_proxy 上游，并核对上游是否在监听套接字上存活。 |
url_check |
对配置白名单内的主机发起 HTTP 检查，返回状态码、延迟与 Content-Type；遇到重定向只报告，不跟随。 |
归属解析逻辑（资料原文）：先用 ss -tlnpH 得到套接字与 PID；再通过 /proc/<pid>/cgroup 关联 systemd 单元；docker-proxy 监听通过 docker ps 的发布端口映射到容器名（如 docker:openviking）。无法归属时报告为 unowned:<process>，不做猜测。
安装与启用¶
安装命令来自官方 README，不要使用未在资料中出现的 github:owner/repo 形式。
dsh plugin --profile web add dsh-port-map
systemctl restart dsh-web # or restart your DSH process
环境要求：
- DSH
>= 0.2.1-rc.4（Node^22.19.0 || >=24.0.0） - 端口相关工具依赖
ss（iproute2）；docker与 Caddyfile 为可选
在 DSH 配置中可挂载插件实例，示例（字段含义见下一节）：
- id: port-map
config:
caddyfile: /etc/caddy/Caddyfile
urlCheck:
hosts:
- 127.0.0.1
- localhost
- example.org
timeoutMs: 10000
docker: true
safety:
timeoutMs: 15000
maxOutputBytes: 65536
配置项¶
| Key | 默认值 | 含义 |
|---|---|---|
caddyfile |
/etc/caddy/Caddyfile |
caddy_routes 解析的文件路径。 |
urlCheck.hosts |
["127.0.0.1", "localhost"] |
url_check 允许请求的主机；其余一律拒绝。 |
urlCheck.timeoutMs |
10000 |
单次请求超时（毫秒）。 |
docker |
true |
是否为已发布端口解析 Docker 容器名。 |
safety.timeoutMs |
15000 |
命令默认超时。 |
safety.maxOutputBytes |
65536 |
单次调用输出上限。 |
典型输出示例¶
下列片段来自 README，便于对照工具返回格式。
监听端口摘要：
Listening TCP sockets (39):
port address scope owner
8790 127.0.0.1 localhost dsh-web.service
1933 127.0.0.1 localhost docker:openviking
9090 0.0.0.0 public map-service.service
Bound to all interfaces: 22, 443, 8642, 8799, 9090, 9091, 9094, 11434
Caddy 路由与上游状态：
Caddy routes (11) from /etc/caddy/Caddyfile:
example.org /panel → 127.0.0.1:8788 · up (vps-panel.service)
example.org /gone → 127.0.0.1:9999 · DOWN
适用场景与注意¶
适合谁： 在单机或 VPS 上同时跑 DSH、systemd 服务、可选 Docker 与 Caddy 的维护者；希望智能体在对话中快速回答端口占用、公网暴露面、反代是否断链，且不需要插件改防火墙或重启服务。
权限与安全： 插件以当前 DSH 进程的用户权限执行（例如能读 /proc、能否跑 docker ps 取决于运行用户）。安装前应在 GitHub 阅读源码与 MIT 许可证；url_check 仅允许 urlCheck.hosts 中的主机，避免任意 URL 探测。
已知限制（README「Honest limits」）：
- 只报告，不修复；不改防火墙、不重启服务。
- Caddyfile 解析支持 site 块、
handle/handle_path与reverse_proxy；!!js、import 片段或php_fastcgi等未建模，不会出现在结果中。 - Docker 名解析依赖当前用户可用的
docker ps；否则仍列出套接字，可能显示docker:<id>。 url_check不跟随重定向链。
DeepSeek Harness 生态采用「一切皆插件」思路；社区目录站点与 DeepSeek / 幻方无官方从属关系，本文介绍的是社区目录中的第三方插件，而非官方应用商店条目。
