前言¶
在 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 / 幻方無官方從屬關係，本文介紹的是社區目錄中的第三方插件，而非官方應用商店條目。
