前言¶

DeepSeek Harness（DSH）的 Web GUI 默認只監聽迴環地址（常見爲 127.0.0.1:3080），不會在局域網直接暴露管理界面。若想在同一子網裏用瀏覽器打開 GUI，簡單做端口轉發往往不夠：GUI 會校驗 Host / Origin，還要求帶啓動 token 或合法的 HMAC 會話 cookie。下面介紹的 mira_proxy 是社區插件，由 Stella-Mira 維護，分類爲 admin-security；它在 DSH 插件進程內起一個帶 TLS 與 HTTP Basic 認證的反向代理，改寫請求頭並向上遊注入簽名 cookie，使局域網可通過 HTTPS 訪問 GUI，WebSocket 隧道也可直通。

這是什麼¶

mira_proxy 的定位是：隨 DSH 加載時在插件內啓動反向代理，把只監聽迴環的 DSH Web GUI 變成局域網可訪問的 HTTPS（或可選明文 HTTP）入口。設計與同倉庫生態裏的獨立進程版 reverse-proxy 一致（同一套 cookie 復刻思路），差別在於落地方式——本插件無額外進程，配置寫在 profile 的插件行 config: 裏，證書缺失時會自動現籤（SAN 覆蓋 localhost、機器名與各網卡 IPv4）。默認監聽 8543，上游 http://127.0.0.1:3080，與獨立進程版默認 8443 錯開。

瀏覽器  https://192.168.x.x:8543 ──TLS + Basic 認證──▶ http://127.0.0.1:3080
                                                              DSH Web GUI（只監聽迴環）

插件源碼與說明見 GitHub，社區目錄頁：skillhub.cn/plugins/Stella-Mira/mira_proxy。DSH 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；安裝前請自行查看源碼與 MIT 許可證（package.json 標註版本 0.2.0）。插件以當前 DSH 進程權限運行，啓用後會在 0.0.0.0:8543（默認）對外監聽，部署前應評估本機防火牆與子網暴露範圍。

爲什麼需要 HTTP 反代而不是四層轉發¶

DSH GUI 對 /api 有兩道關卡：

1. Host/Origin 信任：Host 須爲迴環或顯式 --trusted-host；帶 Origin 時必須與 Host 同源；sec-fetch-site: cross-site 會被拒絕。
2. 瀏覽器會話：入口 URL 常帶每次啓動的 ?token=，或換用綁定 authority、約 30 天有效期的 HMAC 簽名 cookie。

netsh portproxy 一類四層轉發無法改寫 Host、也無法替瀏覽器持有合法上游 cookie。mira_proxy 則：

• 將上游請求的 Host 改寫成 127.0.0.1:3080，對本站點相關的 Origin 一併改寫；外來 Origin 原樣透傳，跨站請求仍由 GUI 拒絕。
• 從 $DSH_HOME/.credentials.yaml（及插件配置中的 auth.credentialsFile / auth.credentialsKeyId）讀取持久化簽名密鑰，每個上游請求現籤合法 dsh-auth-* cookie，無需重啓 GUI 或到終端抄啓動 token。

認證後的 WebSocket（如 /api/remote.mux）走原生 Upgrade，README 說明實測可得到 101 與隧道內雙向數據。

核心功能¶

• TLS + Basic 認證：默認 HTTPS 自簽證書；tls.enabled: false 須顯式關閉，不會自動降級爲明文。
• Host/Origin 改寫與每請求注入上游會話 cookie（復刻 Harness 的 HMAC 構造）。
• 代理自有會話 cookie（mira-proxy-auth）：Basic 通過後瀏覽器憑此訪問，可續期、可撤銷，與上游 dsh-auth-* 分層處理，代理側 cookie 不會轉發給上游。
• 配置熱重載（改 lib/ 下代碼需重啓 DSH，宿主會緩存模塊實例）。
• 只讀狀態工具 mira_proxy_status：監聽情況、證書、賬號數（不含口令）、cookie 剩餘天數、棄用配置鍵、啓動失敗原因等；刻意不提供會改運行狀態的 restart/revoke。
• 迴環健康檢查 /__proxy/health（默認僅迴環可訪問）。
• 啓動失敗可診斷：端口占用會嘗試給出 ss/lsof 線索；配置非法（明文口令、錯誤哈希等）直接拒絕啓動。

本版只支持單用戶語義：多賬號共享同一上游 authority 與同一枚代理 cookie；配置多個 auth.users 不會拒絕啓動，但會 warn 並在狀態中標記 multiUser。

安裝與啓用¶

在 DSH 會話中安裝本地 bundle（等價於 UI 裝本地包）。安裝命令以 README 爲準：

# 在 DSH 會話裏讓 agent 執行（等價於 UI 裏裝本地 bundle）：
#   plugin_manager install_bundle  target = <插件源碼目錄>/mira_proxy

插件通過 cordis.patch.yml 向 profile 插入一行（id mira-proxy，name mira_proxy）。啓用或停用直接改 profile 中對應插件行。全默認時可寫：

- id: mira-proxy
  name: 'mira_proxy'
  config: {}          # 全默認：https://0.0.0.0:8543 -> http://127.0.0.1:3080

需要改監聽或上游時使用嵌套結構，例如：

  config:
    listen:  { host: 0.0.0.0, port: 8543 }
    upstream: { host: 127.0.0.1, port: 3080 }

數據目錄（DSH_HOME 缺省爲 ~/.dsh）：

$DSH_HOME/mira_config/mira_proxy/
  data/proxy-cert.pem    自簽證書（缺失時自動現籤）
  data/proxy-key.pem     私鑰（600）
  data/webapps.htpasswd  Basic 口令表（可選）
  cookies.json           代理會話記錄（600）
  cookie-secret.key      代理 cookie HMAC 密鑰（600）
  logs/proxy.log         訪問日誌

0.1.x 曾使用 <.dsh>/plugin-data/mira_proxy/，本版不會自動搬遷；若舊目錄有數據，啓動時可能 warn 並給出 mv 建議。

典型用法¶

1. 配置 Basic 賬號¶

口令表爲 Apache $apr1$ 或 {SHA}；bcrypt 格式只識別不校驗。可將現有 htpasswd 放到默認路徑：

cp /path/to/webapps.htpasswd ~/.dsh/mira_config/mira_proxy/data/webapps.htpasswd

文件變更無需重啓，下次請求按 mtime/size 重讀。也可在配置中內聯哈希，例如 auth.users: { "dsh-user": "$apr1$xxxx$...." }；明文口令會被拒絕啓動。

若沒有任何賬號，插件會 warn：局域網訪問將一律 401（默認安全姿態）。

2. 局域網訪問 GUI¶

DSH 與插件正常啓動後，在同一子網設備瀏覽器訪問 https://<本機局域網 IP>:8543（或 https://localhost:8543）。首次會遇自簽證書告警；通過 Basic 認證後即可使用 GUI，無需手動拼接 ?token=。

僅本機使用時可將 listen.host 設爲 127.0.0.1；要對局域網開放保持默認 0.0.0.0，並建議在防火牆上限定本子網入站。

3. 查看狀態與日誌¶

• 會話中調用工具 mira_proxy_status 查看入口、上游、證書與 cookie 概況。
• 訪問日誌：$DSH_HOME/mira_config/mira_proxy/logs/proxy.log（超過 log.maxBytes 默認 5MB 輪轉爲 .1）。
• 本機迴環請求 GET /__proxy/health 可查看監聽、上游、賬號數、證書有效期等（默認不對局域網開放）。

撤銷所有代理側 cookie：改 Basic 口令、刪除 cookie-secret.key 後重啓，或調用文檔中的 generation 機制；插件不提供靜默 revoke 工具以免 agent 誤關入口。

配置要點¶

config: {} 即可運行。常用字段摘要（完整表見 README）：

舊扁平鍵（如 listenHost、listenPort）仍兼容但會記日誌與 deprecated 狀態，建議改爲新結構。上游須爲 HTTP 迴環服務；HTTPS 上游未實現。

適用場景與注意¶

適合：需要在局域網手機或另一臺電腦上操作 DSH Web GUI，且希望 TLS 與 Basic 作爲第一道門，同時避免手工處理 Host/Origin 與啓動 token 的開發者或運維。

注意：

• 能過 Basic 的人經代理注入 cookie 後就能使用 GUI；跨站請求仍受 GUI 的 Origin 檢查保護，插件不會僞造 Origin / sec-fetch-site。
• tls.enabled: false 時口令與內容明文在網絡上暴露，僅適合完全可信內網。
• $DSH_HOME 在不同工具中語義可能指數據目錄本身或其父目錄；插件通過 kit.dshHome() 與 credentialsDir() 按文件存在性定位，具體路徑以 mira_proxy_status.baseDir 與啓動日誌爲準。
• 修改 lib/ 後必須重啓 DSH；停用再啓用或重裝 bundle 可能仍執行舊模塊。
• README 註明正式跨機訪問建議用手機或另一臺電腦自測一次；換網段或機器名後刪除 data/proxy-cert.pem 與 data/proxy-key.pem 可觸發重籤。

插件倉庫提供 smoke 自檢：cd mira_proxy && node test/smoke.m（README 自檢一節）。

結尾¶

mira_proxy 把「迴環 GUI + 嚴格 Host/會話規則」收斂成一條可配置的 HTTPS 入口：隨 DSH 啓停、自動補證書、改寫頭並注入上游 cookie，Basic 與代理自有 HMAC cookie 分層管理。若你在 DSH 生態裏做遠程或局域網管理界面暴露，可在安裝前閱讀源碼，再從目錄頁或 GitHub 獲取 bundle。

• 目錄頁：https://www.skillhub.cn/plugins/Stella-Mira/mira_proxy
• GitHub：https://github.com/Stella-Mira/mira_proxy