From e1e1a93745f86c871093fe8d094ed541ab3db927 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 11:57:06 +0800
Subject: [PATCH 01/10] feat: add Terraria game support with installation and
 configuration documentation

---
 ...00\346\261\202\350\257\264\346\230\216.md" | 107 ++++++
 ...0\346\213\211\347\221\236\344\272\232.yml" | 346 ++++++++++++++++++
 server/data/games/installgame.json            |  22 +-
 3 files changed, 474 insertions(+), 1 deletion(-)
 create mode 100644 "docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
 create mode 100644 "server/data/gameconfig/\346\263\260\346\213\211\347\221\236\344\272\232.yml"

diff --git "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
new file mode 100644
index 00000000..e99f05c0
--- /dev/null
+++ "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -0,0 +1,107 @@
+# 泰拉瑞亚与内网穿透插件需求说明
+
+## 背景
+
+这次需求来自两个使用场景：
+
+- Steam 游戏部署列表中缺少原版泰拉瑞亚，用户需要回到文档手动下载、上传、解压和交互式配置。
+- 家用主机、NAS、宿舍网络、运营商 CGNAT 等没有公网入口的环境，游戏服务端即使启动成功，也不方便让外部玩家连接。
+
+## 已落地的最小改进
+
+### 泰拉瑞亚 Steam 部署入口
+
+在 `server/data/games/installgame.json` 中新增 `Terraria`：
+
+- 使用 Terraria Dedicated Server Tool AppID：`105610`。
+- 默认端口：`7777/TCP`。
+- 关联现有泰拉瑞亚开服文档。
+- 在提示中建议用 `serverconfig.txt` 启动，避免首次启动进入交互式建世界流程。
+
+推荐实例启动命令：
+
+```bash
+./TerrariaServer.bin.x86_64 -config serverconfig.txt
+```
+
+Windows 可改为：
+
+```powershell
+.\TerrariaServer.exe -config serverconfig.txt
+```
+
+### 泰拉瑞亚可视化配置模板
+
+在 `server/data/gameconfig/泰拉瑞亚.yml` 中新增 `serverconfig.txt` 模板：
+
+- 世界路径、自动建图、种子、世界名、难度。
+- 最大玩家数、端口、密码、MOTD。
+- 世界目录、封禁列表、作弊防护、语言、UPnP、NPC 同步、优先级。
+- 旅途模式权限项。
+
+模板使用现有 `properties` 解析器。Terraria 的 `0/1` 开关用 `select` 表达，避免保存成 `true/false` 后与服务端配置格式不一致。
+
+## 内网穿透插件候选需求
+
+### 目标
+
+提供一个可选工具，让没有公网 IP 的设备也能把游戏服务端端口暴露给外部玩家。插件应当只负责网络入口，不改变游戏实例本身的部署和启动逻辑。
+
+### 支持对象
+
+第一阶段建议支持：
+
+- frp 客户端模式：适合已有 frps 服务器的用户。
+- EasyTier 组网模式：适合希望多节点虚拟局域网互通的用户。
+
+### MVP 能力
+
+- 从实例列表选择一个游戏实例，读取实例名称、工作目录和端口信息。
+- 允许手动填写本地地址、本地端口、远端端口、远端服务器、认证 token 或组网密钥。
+- 生成 frpc 或 EasyTier 配置文件，默认保存到 `server/data/tunnels/` 下。
+- 通过实例管理创建一个独立的“穿透实例”，让用户用现有实例启停能力管理隧道进程。
+- 显示连接说明，例如 `远端地址:远端端口` 或 EasyTier 虚拟 IP。
+
+### 非目标
+
+- 不把 frp/EasyTier 变成游戏部署前置依赖。
+- 不替用户申请公网服务器或托管中继。
+- 不绕过游戏本身的账号、白名单、RCON、反作弊或服务端安全配置。
+- 不默认启用 UPnP 或自动开放所有端口。
+
+## 推荐实现方式
+
+### 插件优先
+
+先做成 `server/data/plugins/tunnel-helper` 这类可选插件：
+
+- `plugin.json` 默认 `enabled: false`，避免默认安装后自动出现网络暴露入口。
+- `index.html` 只做配置生成、实例创建和状态查看。
+- 复用 `gsm3-api.js` 的实例 API、文件 API 和终端/进程列表 API。
+
+这种方式与当前插件体系匹配，风险较低，也不会把第三方网络工具耦合进核心部署页。
+
+### 核心 API 补强
+
+如果后续要做成完整的一键体验，核心需要补一个受限的后台进程/工具管理能力：
+
+- 管理受信任工具定义：工具名称、版本、下载地址、校验和、支持平台。
+- 统一保存配置：配置文件、敏感字段、脱敏展示、备份恢复。
+- 统一管理进程：启动、停止、重启、日志、健康状态、退出码。
+- 限制命令注入：不要让插件拼接任意 shell 字符串后直接执行。
+- 与实例端口关联：从游戏配置或实例元数据中读取端口，减少重复输入。
+
+## 安全与维护约束
+
+- 所有后端接口必须加认证中间件。
+- 持久化数据放在 `server/data` 下，兼容开发和打包路径。
+- token、密钥、服务端地址等敏感字段不要出现在日志和普通列表展示中。
+- 不建议在仓库内直接提交第三方二进制；如需要下载，必须有来源、版本、哈希校验和失败回滚。
+- Windows、Linux、Docker 三种运行方式的路径、权限和停止信号要分别验证。
+
+## PR 拆分建议
+
+1. 泰拉瑞亚 Steam 安装清单与 `serverconfig.txt` 可视化模板。
+2. 内网穿透插件需求说明和界面草图。
+3. `tunnel-helper` 插件 MVP：生成配置并创建受管实例。
+4. 核心进程/工具 API 补强，完善二进制下载、校验、日志和状态检测。
diff --git "a/server/data/gameconfig/\346\263\260\346\213\211\347\221\236\344\272\232.yml" "b/server/data/gameconfig/\346\263\260\346\213\211\347\221\236\344\272\232.yml"
new file mode 100644
index 00000000..8ca9ac80
--- /dev/null
+++ "b/server/data/gameconfig/\346\263\260\346\213\211\347\221\236\344\272\232.yml"
@@ -0,0 +1,346 @@
+meta:
+  game_name: "泰拉瑞亚"
+  config_file: "serverconfig.txt"
+  parser: "properties"
+
+sections:
+  - key: "serverconfig.txt"
+    fields:
+      - name: "world"
+        display: "世界文件路径"
+        default: "Worlds/world1.wld"
+        type: "string"
+        description: "要加载的世界文件。使用相对路径时会相对于服务端工作目录解析，建议与服务端文件放在同一持久化目录中"
+      - name: "autocreate"
+        display: "自动创建世界大小"
+        default: "1"
+        type: "select"
+        description: "当 world 指定的世界不存在时自动创建世界"
+        options:
+          - value: "0"
+            label: "不自动创建"
+          - value: "1"
+            label: "小世界"
+          - value: "2"
+            label: "中世界"
+          - value: "3"
+            label: "大世界"
+      - name: "seed"
+        display: "世界种子"
+        default: ""
+        type: "string"
+        description: "自动创建世界时使用的种子，留空则随机生成"
+      - name: "worldname"
+        display: "世界名称"
+        default: "Terraria"
+        type: "string"
+        description: "自动创建世界时使用的世界名称"
+      - name: "difficulty"
+        display: "世界难度"
+        default: "0"
+        type: "select"
+        description: "自动创建世界时使用的难度"
+        options:
+          - value: "0"
+            label: "经典"
+          - value: "1"
+            label: "专家"
+          - value: "2"
+            label: "大师"
+          - value: "3"
+            label: "旅途"
+      - name: "maxplayers"
+        display: "最大玩家数"
+        default: 8
+        type: "number"
+        description: "允许加入服务器的最大玩家数量，官方配置示例范围为 1 到 255"
+      - name: "port"
+        display: "服务器端口"
+        default: 7777
+        type: "number"
+        description: "Terraria 默认使用 7777 TCP"
+      - name: "password"
+        display: "服务器密码"
+        default: ""
+        type: "string"
+        description: "加入服务器需要输入的密码，留空表示无密码"
+      - name: "motd"
+        display: "每日消息"
+        default: ""
+        type: "string"
+        description: "玩家进入服务器时显示的消息"
+      - name: "worldpath"
+        display: "世界目录"
+        default: "Worlds"
+        type: "string"
+        description: "世界文件保存目录。Terraria 配置文件中不支持 $HOME 或 ~ 展开，建议使用相对路径或绝对路径"
+      - name: "worldrollbackstokeep"
+        display: "世界回滚备份数量"
+        default: 2
+        type: "number"
+        description: "保留的滚动世界备份数量"
+      - name: "banlist"
+        display: "封禁列表路径"
+        default: "banlist.txt"
+        type: "string"
+        description: "封禁列表文件位置，默认在服务端工作目录下"
+      - name: "secure"
+        display: "作弊防护"
+        default: "1"
+        type: "select"
+        description: "启用 Terraria 服务端的额外作弊防护"
+        options:
+          - value: "1"
+            label: "启用"
+          - value: "0"
+            label: "关闭"
+      - name: "language"
+        display: "服务器语言"
+        default: "zh-Hans"
+        type: "select"
+        description: "服务端输出语言"
+        options:
+          - value: "zh-Hans"
+            label: "简体中文"
+          - value: "en-US"
+            label: "English"
+          - value: "de-DE"
+            label: "Deutsch"
+          - value: "it-IT"
+            label: "Italiano"
+          - value: "fr-FR"
+            label: "Francais"
+          - value: "es-ES"
+            label: "Espanol"
+          - value: "ru-RU"
+            label: "Русский"
+          - value: "pt-BR"
+            label: "Portugues"
+          - value: "pl-PL"
+            label: "Polski"
+      - name: "upnp"
+        display: "UPnP 自动端口转发"
+        default: "0"
+        type: "select"
+        description: "是否尝试通过 UPnP 自动转发端口。没有公网 IP 或处于 CGNAT 时仍需使用内网穿透等方案"
+        options:
+          - value: "0"
+            label: "关闭"
+          - value: "1"
+            label: "启用"
+      - name: "npcstream"
+        display: "NPC 同步频率"
+        default: 60
+        type: "number"
+        description: "降低敌怪跳跃感但会增加带宽占用，0 表示关闭"
+      - name: "priority"
+        display: "进程优先级"
+        default: "1"
+        type: "select"
+        description: "服务端进程优先级"
+        options:
+          - value: "0"
+            label: "实时"
+          - value: "1"
+            label: "高"
+          - value: "2"
+            label: "高于正常"
+          - value: "3"
+            label: "正常"
+          - value: "4"
+            label: "低于正常"
+          - value: "5"
+            label: "空闲"
+      - name: "slowliquids"
+        display: "降低液体更新量"
+        default: "0"
+        type: "select"
+        description: "可降低同一时间移动的液体上限，可能减少卡顿但液体结算更慢"
+        options:
+          - value: "0"
+            label: "关闭"
+          - value: "1"
+            label: "启用"
+
+  - key: "journey"
+    fields:
+      - name: "journeypermission_time_setfrozen"
+        display: "旅途权限：冻结时间"
+        default: "2"
+        type: "select"
+        description: "0 为所有人锁定，1 为仅主机可改，2 为所有人可改"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_time_setdawn"
+        display: "旅途权限：设置黎明"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置黎明的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_time_setnoon"
+        display: "旅途权限：设置中午"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置中午的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_time_setdusk"
+        display: "旅途权限：设置黄昏"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置黄昏的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_time_setmidnight"
+        display: "旅途权限：设置午夜"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置午夜的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_godmode"
+        display: "旅途权限：上帝模式"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中上帝模式的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_wind_setstrength"
+        display: "旅途权限：风力强度"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置风力强度的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_rain_setstrength"
+        display: "旅途权限：雨量强度"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置雨量强度的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_time_setspeed"
+        display: "旅途权限：时间速度"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中设置时间速度的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_rain_setfrozen"
+        display: "旅途权限：冻结雨天"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中冻结雨天的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_wind_setfrozen"
+        display: "旅途权限：冻结风"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中冻结风的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_increaseplacementrange"
+        display: "旅途权限：增加放置范围"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中增加放置范围的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_setdifficulty"
+        display: "旅途权限：调整难度"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中调整难度的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_biomespread_setfrozen"
+        display: "旅途权限：冻结生物群系蔓延"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中冻结腐化、猩红等蔓延的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
+      - name: "journeypermission_setspawnrate"
+        display: "旅途权限：调整生成率"
+        default: "2"
+        type: "select"
+        description: "控制旅途模式中调整敌怪生成率的权限"
+        options:
+          - value: "0"
+            label: "锁定"
+          - value: "1"
+            label: "仅主机"
+          - value: "2"
+            label: "所有人"
diff --git a/server/data/games/installgame.json b/server/data/games/installgame.json
index 17d0e0d4..da166aed 100644
--- a/server/data/games/installgame.json
+++ b/server/data/games/installgame.json
@@ -166,6 +166,26 @@
     "url": "https://store.steampowered.com/app/322330/_/",
     "docs": "https://docs.gsm.xiaozhuhouses.asia/%E6%B8%B8%E6%88%8F%E7%99%BE%E7%A7%91/Steam/%E9%A5%A5%E8%8D%92%E9%A3%9F%E7%94%A8%E8%AF%B4%E6%98%8E.html"
   },
+  "Terraria": {
+    "game_nameCN": "泰拉瑞亚",
+    "appid": "105610",
+    "tip": "默认端口：7777 TCP。建议创建实例时使用 serverconfig.txt 启动，例如 Linux 使用 ./TerrariaServer.bin.x86_64 -config serverconfig.txt，Windows 使用 .\\TerrariaServer.exe -config serverconfig.txt，可避免首次启动进入交互式配置流程。",
+    "image": "https://shared.fastly.steamstatic.com/store_item_assets/steam/apps/105600/header.jpg",
+    "url": "https://store.steampowered.com/app/105600/Terraria/",
+    "docs": "https://docs.gsm.xiaozhuhouses.asia/%E6%B8%B8%E6%88%8F%E7%99%BE%E7%A7%91/Steam/%E6%B3%B0%E6%8B%89%E7%91%9E%E4%BA%9A%E9%A3%9F%E7%94%A8%E8%AF%B4%E6%98%8E.html",
+    "system": [
+      "Windows",
+      "Linux",
+      "MacOS"
+    ],
+    "ports": [
+      {
+        "port": 7777,
+        "protocol": "tcp"
+      }
+    ],
+    "memory": 1
+  },
   "Project_Zomboid": {
     "game_nameCN": "僵尸毁灭工程",
     "appid": "380870",
@@ -836,4 +856,4 @@
       "Windows"
     ]
   }
-}
\ No newline at end of file
+}

From 49d9430d19b90dc0e9c12faede7d760638c09681 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 12:16:48 +0800
Subject: [PATCH 02/10] feat: enhance Terraria support with installation paths,
 start commands, and documentation updates

---
 client/src/pages/GameDeploymentPage.tsx       |  15 ++-
 ...00\346\261\202\350\257\264\346\230\216.md" |   4 +-
 server/data/games/installgame.json            |  12 +-
 server/src/routes/gameDeployment.ts           | 110 ++++++++++++++++--
 4 files changed, 123 insertions(+), 18 deletions(-)

diff --git a/client/src/pages/GameDeploymentPage.tsx b/client/src/pages/GameDeploymentPage.tsx
index a27a383e..4e7b7a0e 100644
--- a/client/src/pages/GameDeploymentPage.tsx
+++ b/client/src/pages/GameDeploymentPage.tsx
@@ -41,6 +41,7 @@ interface GameInfo {
   url: string
   docs?: string
   system?: string[]
+  login_anonymous?: boolean
   supportedOnCurrentPlatform?: boolean
   currentPlatform?: string
   panelCompatibleOnCurrentPlatform?: boolean
@@ -2553,7 +2554,7 @@ const GameDeploymentPage: React.FC = () => {
         : `app_update ${selectedGame.info.appid}`
 
       // force_install_dir 必须在 login 之前，否则 SteamCMD 会报错
-      const fullCommand = `steamcmd +${forceInstallDir} +${loginCommand} +${appUpdateCommand} +quit`
+      const fullCommand = `+${forceInstallDir} +${loginCommand} +${appUpdateCommand} +quit`
       setSteamcmdCommand(fullCommand)
     }
   }, [showInstallModal, selectedGame, useAnonymous, steamUsername, steamPassword, validateGameIntegrity, installPath])
@@ -2628,6 +2629,12 @@ const GameDeploymentPage: React.FC = () => {
   // 打开安装对话框的通用函数
   const openInstallModal = async (gameKey: string, gameInfo: GameInfo) => {
     const defaultInstanceName = gameInfo.game_nameCN
+    const shouldUseAnonymous = gameInfo.login_anonymous !== false
+    setUseAnonymous(shouldUseAnonymous)
+    if (shouldUseAnonymous) {
+      setSteamUsername('')
+      setSteamPassword('')
+    }
     
     // 检查是否存在同名实例
     try {
@@ -5844,18 +5851,18 @@ const GameDeploymentPage: React.FC = () => {
 
                     <div>
                       <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">
-                        SteamCMD 安装命令
+                        SteamCMD 安装参数
                       </label>
                       <textarea
                         value={steamcmdCommand}
                         onChange={(e) => setSteamcmdCommand(e.target.value)}
                         className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent bg-white dark:bg-gray-700 text-gray-900 dark:text-white font-mono text-sm"
-                        placeholder="SteamCMD 命令将在这里显示，您可以修改后执行"
+                        placeholder="SteamCMD 安装参数将在这里显示，您可以修改后执行"
                         rows={4}
                         readOnly={false}
                       />
                       <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
-                        您可以修改此命令来自定义安装参数，修改后的命令将用于实际安装
+                        面板会自动调用已配置的 steamcmd.exe 或 steamcmd.sh，请只保留 +force_install_dir、+login、+app_update 等参数
                       </p>
                     </div>
                   </div>
diff --git "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index e99f05c0..4628d2de 100644
--- "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -13,8 +13,10 @@
 
 在 `server/data/games/installgame.json` 中新增 `Terraria`：
 
-- 使用 Terraria Dedicated Server Tool AppID：`105610`。
+- 使用 SteamCMD 专用服务器列表中的 Terraria AppID：`105600`。
 - 默认端口：`7777/TCP`。
+- 默认不使用匿名登录，安装时需要填写已拥有 Terraria 的 Steam 账号。
+- 清单内提供 Windows/Linux 默认启动命令，避免实例创建后回落为 `none`。
 - 关联现有泰拉瑞亚开服文档。
 - 在提示中建议用 `serverconfig.txt` 启动，避免首次启动进入交互式建世界流程。
 
diff --git a/server/data/games/installgame.json b/server/data/games/installgame.json
index da166aed..4f3e790e 100644
--- a/server/data/games/installgame.json
+++ b/server/data/games/installgame.json
@@ -168,15 +168,19 @@
   },
   "Terraria": {
     "game_nameCN": "泰拉瑞亚",
-    "appid": "105610",
-    "tip": "默认端口：7777 TCP。建议创建实例时使用 serverconfig.txt 启动，例如 Linux 使用 ./TerrariaServer.bin.x86_64 -config serverconfig.txt，Windows 使用 .\\TerrariaServer.exe -config serverconfig.txt，可避免首次启动进入交互式配置流程。",
+    "appid": "105600",
+    "tip": "默认端口：7777 TCP。SteamCMD 安装需要使用已拥有 Terraria 的 Steam 账号登录。建议创建实例时使用 serverconfig.txt 启动，例如 Linux 使用 ./TerrariaServer.bin.x86_64 -config serverconfig.txt，Windows 使用 .\\TerrariaServer.exe -config serverconfig.txt，可避免首次启动进入交互式配置流程。",
     "image": "https://shared.fastly.steamstatic.com/store_item_assets/steam/apps/105600/header.jpg",
     "url": "https://store.steampowered.com/app/105600/Terraria/",
     "docs": "https://docs.gsm.xiaozhuhouses.asia/%E6%B8%B8%E6%88%8F%E7%99%BE%E7%A7%91/Steam/%E6%B3%B0%E6%8B%89%E7%91%9E%E4%BA%9A%E9%A3%9F%E7%94%A8%E8%AF%B4%E6%98%8E.html",
+    "login_anonymous": false,
+    "start_command": {
+      "Windows": ".\\TerrariaServer.exe -config serverconfig.txt",
+      "Linux": "./TerrariaServer.bin.x86_64 -config serverconfig.txt"
+    },
     "system": [
       "Windows",
-      "Linux",
-      "MacOS"
+      "Linux"
     ],
     "ports": [
       {
diff --git a/server/src/routes/gameDeployment.ts b/server/src/routes/gameDeployment.ts
index d04b960b..e381767c 100644
--- a/server/src/routes/gameDeployment.ts
+++ b/server/src/routes/gameDeployment.ts
@@ -20,6 +20,8 @@ enum Platform {
   MacOS = 'MacOS'
 }
 
+type StartCommandConfig = string | Partial<Record<Platform, string>>
+
 // 游戏信息接口
 interface SteamGameInfo {
   game_nameCN: string
@@ -29,6 +31,8 @@ interface SteamGameInfo {
   url: string
   system?: Platform[]
   system_info?: Platform[]  // 面板兼容的系统列表
+  login_anonymous?: boolean
+  start_command?: StartCommandConfig
 }
 
 // 获取当前平台
@@ -68,6 +72,69 @@ function isPanelCompatibleOnCurrentPlatform(game: SteamGameInfo): boolean {
   return game.system_info.includes(currentPlatform)
 }
 
+function getInstallGamePaths(): string[] {
+  const baseDir = process.cwd()
+  return [
+    path.join(baseDir, 'data', 'games', 'installgame.json'),           // 打包后的路径
+    path.join(baseDir, 'server', 'data', 'games', 'installgame.json'), // 开发环境路径
+  ]
+}
+
+async function getInstallGameFilePath(): Promise<string | null> {
+  for (const possiblePath of getInstallGamePaths()) {
+    try {
+      await fs.access(possiblePath)
+      return possiblePath
+    } catch {
+      // 继续尝试下一个路径
+    }
+  }
+
+  return null
+}
+
+async function getInstallGameInfo(gameKey: string): Promise<SteamGameInfo | null> {
+  const gamesFilePath = await getInstallGameFilePath()
+  if (!gamesFilePath) {
+    return null
+  }
+
+  const gamesData = await fs.readFile(gamesFilePath, 'utf-8')
+  const allGames: { [key: string]: SteamGameInfo } = JSON.parse(gamesData)
+  return allGames[gameKey] || null
+}
+
+function resolvePlatformStartCommand(startCommand?: StartCommandConfig): string | null {
+  if (!startCommand) {
+    return null
+  }
+
+  if (typeof startCommand === 'string') {
+    return startCommand.trim() || null
+  }
+
+  const currentPlatform = getCurrentPlatform()
+  return (
+    startCommand[currentPlatform] ||
+    startCommand[Platform.Linux] ||
+    startCommand[Platform.Windows] ||
+    startCommand[Platform.MacOS] ||
+    null
+  )
+}
+
+async function getLocalStartCommandForGame(gameKey: string): Promise<string | null> {
+  const gameInfo = await getInstallGameInfo(gameKey)
+  return resolvePlatformStartCommand(gameInfo?.start_command)
+}
+
+function normalizeSteamCMDArguments(command: string): string {
+  return command
+    .trim()
+    .replace(/^(?:"[^"]*[\\/]?steamcmd(?:\.exe|\.sh)?"|(?:[a-z]:)?[^\s"]*[\\/]steamcmd(?:\.exe|\.sh)?|steamcmd(?:\.exe|\.sh)?)(?:\s+|$)/i, '')
+    .trim()
+}
+
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
@@ -322,6 +389,15 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
       })
     }
 
+    const steamcmdArgs = normalizeSteamCMDArguments(steamcmdCommand)
+    if (!steamcmdArgs) {
+      return res.status(400).json({
+        success: false,
+        error: 'SteamCMD命令无效',
+        message: 'SteamCMD命令必须包含 force_install_dir、login、app_update 等参数'
+      })
+    }
+
     // 检查安装路径是否存在
     try {
       await fs.access(installPath)
@@ -387,7 +463,7 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
     logger.info(`开始安装游戏: ${gameName || gameKey}`, {
       installPath,
       appId,
-      command: steamcmdCommand,
+      command: steamcmdArgs,
       resetSteamManifest: resetSteamManifest || false
     })
     
@@ -434,16 +510,16 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
       
       if (platform === 'win32') {
         steamcmdExecutable = '.\\steamcmd.exe'
-        fullCommand = `${steamcmdExecutable} ${steamcmdCommand}`
+        fullCommand = `${steamcmdExecutable} ${steamcmdArgs}`
       } else {
         // Linux环境下确保使用root用户权限执行SteamCMD
         steamcmdExecutable = './steamcmd.sh'
         // 检查当前用户是否为root，如果不是则使用sudo
         const currentUser = process.env.USER || process.env.USERNAME || 'unknown'
         if (currentUser === 'root') {
-          fullCommand = `${steamcmdExecutable} ${steamcmdCommand}`
+          fullCommand = `${steamcmdExecutable} ${steamcmdArgs}`
         } else {
-          fullCommand = `sudo -u root ${steamcmdExecutable} ${steamcmdCommand}`
+          fullCommand = `sudo -u root ${steamcmdExecutable} ${steamcmdArgs}`
         }
       }
       
@@ -550,11 +626,19 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
                 startCommand = matchedInstance.command
                 logger.info(`从实例市场找到匹配的启动命令: ${gameNameToMatch} -> ${startCommand}`)
               } else {
-                logger.info(`实例市场中未找到匹配的游戏: ${gameNameToMatch}，使用默认启动命令`)
+                logger.info(`实例市场中未找到匹配的游戏: ${gameNameToMatch}，尝试使用本地清单启动命令`)
               }
             }
           } catch (error: any) {
-            logger.warn('查询实例市场失败，使用默认启动命令:', error.message)
+            logger.warn('查询实例市场失败，尝试使用本地清单启动命令:', error.message)
+          }
+
+          if (startCommand === 'none') {
+            const localStartCommand = await getLocalStartCommandForGame(gameKey)
+            if (localStartCommand) {
+              startCommand = localStartCommand
+              logger.info(`使用本地清单启动命令: ${gameKey} -> ${startCommand}`)
+            }
           }
           
           // 更新实例信息
@@ -657,11 +741,19 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
               startCommand = matchedInstance.command
               logger.info(`从实例市场找到匹配的启动命令: ${gameNameToMatch} -> ${startCommand}`)
             } else {
-              logger.info(`实例市场中未找到匹配的游戏: ${gameNameToMatch}，使用默认启动命令`)
+              logger.info(`实例市场中未找到匹配的游戏: ${gameNameToMatch}，尝试使用本地清单启动命令`)
             }
           }
         } catch (error: any) {
-          logger.warn('查询实例市场失败，使用默认启动命令:', error.message)
+          logger.warn('查询实例市场失败，尝试使用本地清单启动命令:', error.message)
+        }
+
+        if (startCommand === 'none') {
+          const localStartCommand = await getLocalStartCommandForGame(gameKey)
+          if (localStartCommand) {
+            startCommand = localStartCommand
+            logger.info(`使用本地清单启动命令: ${gameKey} -> ${startCommand}`)
+          }
         }
         
         // 创建实例（在安装开始时就创建，而不是等安装完成）
@@ -934,4 +1026,4 @@ router.post('/scan-minecraft-directory', authenticateToken, async (req: Request,
   }
 })
 
-export default router
\ No newline at end of file
+export default router

From e5fad4b57f826871d8894efca972cc7cfb0df00e Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 12:44:11 +0800
Subject: [PATCH 03/10] fix: enhance SteamCMD credential handling and improve
 user prompts

---
 client/src/pages/GameDeploymentPage.tsx       | 32 ++++++++---
 ...00\346\261\202\350\257\264\346\230\216.md" |  2 +-
 server/src/routes/gameDeployment.ts           | 54 +++++++++++++++++--
 3 files changed, 76 insertions(+), 12 deletions(-)

diff --git a/client/src/pages/GameDeploymentPage.tsx b/client/src/pages/GameDeploymentPage.tsx
index 4e7b7a0e..05105b69 100644
--- a/client/src/pages/GameDeploymentPage.tsx
+++ b/client/src/pages/GameDeploymentPage.tsx
@@ -60,6 +60,14 @@ interface Games {
   [key: string]: GameInfo
 }
 
+const quoteSteamCMDArgument = (value: string, platform?: string): string => {
+  if (platform === 'Windows') {
+    return `'${value.replace(/'/g, "''")}'`
+  }
+
+  return `'${value.replace(/'/g, "'\\''")}'`
+}
+
 // 辅助函数：判断是否为 Windows 平台
 const isWindowsPlatform = (systemInfo: any): boolean => {
   // 优先使用 rawPlatform（原始平台标识）
@@ -2544,10 +2552,17 @@ const GameDeploymentPage: React.FC = () => {
   useEffect(() => {
     if (showInstallModal && selectedGame) {
       const forceInstallDir = `force_install_dir "${installPath.trim()}"`
+      const steamLoginArgs = [
+        'login',
+        quoteSteamCMDArgument(steamUsername.trim(), selectedGame.info.currentPlatform),
+        ...(steamPassword.trim()
+          ? [quoteSteamCMDArgument(steamPassword.trim(), selectedGame.info.currentPlatform)]
+          : [])
+      ]
 
       const loginCommand = useAnonymous
         ? 'login anonymous'
-        : `login ${steamUsername.trim()} ${steamPassword.trim()}`
+        : steamLoginArgs.join(' ')
 
       const appUpdateCommand = validateGameIntegrity
         ? `app_update ${selectedGame.info.appid} validate`
@@ -2916,11 +2931,11 @@ const GameDeploymentPage: React.FC = () => {
       return
     }
 
-    if (!useAnonymous && (!steamUsername.trim() || !steamPassword.trim())) {
+    if (!useAnonymous && !steamUsername.trim()) {
       addNotification({
         type: 'error',
         title: '参数错误',
-        message: '请填写Steam账户信息'
+        message: '请填写Steam用户名'
       })
       return
     }
@@ -2953,7 +2968,7 @@ const GameDeploymentPage: React.FC = () => {
           instanceName: instanceName.trim(),
           useAnonymous,
           steamUsername: useAnonymous ? undefined : steamUsername.trim(),
-          steamPassword: useAnonymous ? undefined : steamPassword.trim(),
+          steamPassword: useAnonymous || !steamPassword.trim() ? undefined : steamPassword.trim(),
           steamcmdCommand: steamcmdCommand.trim(),
           existingInstanceId: currentExistingInstanceId || undefined,
           updateInstanceInfo: currentUpdateInstanceInfo,
@@ -5770,15 +5785,18 @@ const GameDeploymentPage: React.FC = () => {
                       </div>
                       <div>
                         <label className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">
-                          Steam密码
+                          Steam密码（可选）
                         </label>
                         <input
                           type="password"
                           value={steamPassword}
                           onChange={(e) => setSteamPassword(e.target.value)}
                           className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent bg-white dark:bg-gray-700 text-gray-900 dark:text-white"
-                          placeholder="输入Steam密码"
+                          placeholder="留空则在终端中输入"
                         />
+                        <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">
+                          留空时 SteamCMD 会在终端提示输入密码和 Steam Guard 码
+                        </p>
                       </div>
                     </div>
                   )}
@@ -5882,7 +5900,7 @@ const GameDeploymentPage: React.FC = () => {
                 disabled={
                   !installPath.trim() ||
                   !instanceName.trim() ||
-                  (!useAnonymous && (!steamUsername.trim() || !steamPassword.trim()))
+                  (!useAnonymous && !steamUsername.trim())
                 }
                 className="px-4 py-2 disabled:bg-gray-400 text-white rounded-lg transition-colors flex items-center space-x-2 bg-blue-600 hover:bg-blue-700"
               >
diff --git "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index 4628d2de..0698b839 100644
--- "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -15,7 +15,7 @@
 
 - 使用 SteamCMD 专用服务器列表中的 Terraria AppID：`105600`。
 - 默认端口：`7777/TCP`。
-- 默认不使用匿名登录，安装时需要填写已拥有 Terraria 的 Steam 账号。
+- 默认不使用匿名登录，安装时需要填写已拥有 Terraria 的 Steam 用户名。密码可留空，让 SteamCMD 在终端中交互式输入密码和 Steam Guard 码。
 - 清单内提供 Windows/Linux 默认启动命令，避免实例创建后回落为 `none`。
 - 关联现有泰拉瑞亚开服文档。
 - 在提示中建议用 `serverconfig.txt` 启动，避免首次启动进入交互式建世界流程。
diff --git a/server/src/routes/gameDeployment.ts b/server/src/routes/gameDeployment.ts
index e381767c..5c31de9c 100644
--- a/server/src/routes/gameDeployment.ts
+++ b/server/src/routes/gameDeployment.ts
@@ -135,6 +135,50 @@ function normalizeSteamCMDArguments(command: string): string {
     .trim()
 }
 
+function getSteamCMDTokenValue(token: string): string {
+  if ((token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'"))) {
+    return token.slice(1, -1)
+  }
+
+  return token
+}
+
+function redactSteamCMDCredentials(command: string): string {
+  const tokens = command.match(/"[^"]*"|'(?:''|[^'])*'|\S+/g)
+  if (!tokens) {
+    return command
+  }
+
+  const redactedTokens = [...tokens]
+
+  for (let index = 0; index < redactedTokens.length; index++) {
+    const tokenValue = getSteamCMDTokenValue(redactedTokens[index]).toLowerCase()
+    if (tokenValue !== 'login' && tokenValue !== '+login') {
+      continue
+    }
+
+    const usernameToken = redactedTokens[index + 1]
+    const passwordToken = redactedTokens[index + 2]
+    if (!usernameToken || !passwordToken) {
+      continue
+    }
+
+    const username = getSteamCMDTokenValue(usernameToken).toLowerCase()
+    if (username === 'anonymous' || passwordToken.startsWith('+')) {
+      continue
+    }
+
+    redactedTokens[index + 2] = '******'
+
+    const steamGuardToken = redactedTokens[index + 3]
+    if (steamGuardToken && !steamGuardToken.startsWith('+')) {
+      redactedTokens[index + 3] = '******'
+    }
+  }
+
+  return redactedTokens.join(' ')
+}
+
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
 
@@ -381,11 +425,11 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
       })
     }
     
-    if (!useAnonymous && (!steamUsername || !steamPassword)) {
+    if (!useAnonymous && !steamUsername) {
       return res.status(400).json({
         success: false,
         error: '缺少Steam账户信息',
-        message: '非匿名模式下需要提供Steam用户名和密码'
+        message: '非匿名模式下需要提供Steam用户名'
       })
     }
 
@@ -460,10 +504,12 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
       }
     }
     
+    const redactedSteamcmdArgs = redactSteamCMDCredentials(steamcmdArgs)
+
     logger.info(`开始安装游戏: ${gameName || gameKey}`, {
       installPath,
       appId,
-      command: steamcmdArgs,
+      command: redactedSteamcmdArgs,
       resetSteamManifest: resetSteamManifest || false
     })
     
@@ -523,7 +569,7 @@ router.post('/install', authenticateToken, async (req: Request, res: Response) =
         }
       }
       
-      logger.info(`执行SteamCMD命令: ${fullCommand}`, {
+      logger.info(`执行SteamCMD命令: ${redactSteamCMDCredentials(fullCommand)}`, {
         platform,
         workingDirectory: steamcmdDir
       })

From 3cd37ff383be4ef56c20621286c826d95248caa4 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 13:06:52 +0800
Subject: [PATCH 04/10] docs: rename Terraria documentation and add internal
 network penetration plugin requirements

---
 ...00\346\261\202\350\257\264\346\230\216.md" |  95 +++++++++++++++
 ...00\346\261\202\350\257\264\346\230\216.md" | 109 ------------------
 ...00\346\261\202\350\257\264\346\230\216.md" |  65 +++++++++++
 3 files changed, 160 insertions(+), 109 deletions(-)
 create mode 100644 "docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
 delete mode 100644 "docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
 create mode 100644 "docs/\346\263\260\346\213\211\347\221\236\344\272\232\351\203\250\347\275\262\351\234\200\346\261\202\350\257\264\346\230\216.md"

diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
new file mode 100644
index 00000000..9c5ef3b2
--- /dev/null
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -0,0 +1,95 @@
+# 内网穿透插件需求说明
+
+## 背景
+
+家用主机、NAS、宿舍网络、运营商 CGNAT 等没有公网入口的环境中，游戏服务端即使启动成功，也不方便让外部玩家连接。
+
+这个问题不是泰拉瑞亚特有的。Minecraft、Palworld、Valheim、Project Zomboid、Factorio 等游戏只要运行在不可直连的网络里，都会遇到类似的端口暴露问题。因此内网穿透能力应当作为跨游戏的可选工具实现，而不是绑定到某一个游戏部署流程。
+
+## 目标
+
+提供一个可选工具，让没有公网 IP 的设备也能把游戏服务端端口暴露给外部玩家。插件只负责网络入口，不改变游戏实例本身的部署、配置和启动逻辑。
+
+## 支持对象
+
+第一阶段建议支持：
+
+- frp 客户端模式：适合已有 frps 服务器的用户。
+- EasyTier 组网模式：适合希望多节点虚拟局域网互通的用户。
+
+后续可以扩展到其他工具，但需要满足同一套安全边界：配置可审计、启动命令受控、敏感信息脱敏、进程可停止。
+
+## MVP 能力
+
+- 从实例列表选择一个游戏实例，读取实例名称、工作目录和端口信息。
+- 支持手动填写本地地址、本地端口、远端端口、远端服务器、认证 token 或组网密钥。
+- 生成 frpc 或 EasyTier 配置文件，默认保存到 `server/data/tunnels/` 下。
+- 通过实例管理创建一个独立的“穿透实例”，让用户用现有实例启停能力管理隧道进程。
+- 显示连接说明，例如 `远端地址:远端端口` 或 EasyTier 虚拟 IP。
+- 不要求游戏实例和穿透实例同生命周期绑定，避免穿透失败影响游戏服务本身。
+
+## 非目标
+
+- 不把 frp/EasyTier 变成游戏部署前置依赖。
+- 不替用户申请公网服务器或托管中继。
+- 不绕过游戏本身的账号、白名单、RCON、反作弊或服务端安全配置。
+- 不默认启用 UPnP 或自动开放所有端口。
+- 不在仓库内提交 frp、EasyTier 等第三方二进制文件。
+
+## 推荐实现方式
+
+### 当前可复用能力
+
+项目已有插件体系和示例插件，可以直接复用：
+
+- 插件目录：`server/data/plugins/`。
+- 插件配置：`plugin.json`，支持 `enabled`、`hasWebInterface`、`entryPoint`、`category` 等字段。
+- 插件 API 客户端：`gsm3-api.js`，请求前缀为 `/api/plugin-api`。
+- 实例 API：`getInstances()`、`createInstance()`、`startInstance()`、`stopInstance()`、`restartInstance()`、`deleteInstance()`。
+- 文件 API：`mkdir()`、`writeFile()`、`readFile()`、`exists()`、`listFiles()` 等，可用于写入 `server/data/tunnels/` 下的配置文件。
+- 终端 API：可查看终端会话和活跃进程，MVP 阶段只作为状态辅助，不直接拼接任意命令。
+
+### 插件优先
+
+先做成 `server/data/plugins/tunnel-helper` 这类可选插件：
+
+- `plugin.json` 默认 `enabled: false`，避免默认安装后自动出现网络暴露入口。
+- `index.html` 只做配置生成、实例创建和状态查看。
+- 复用 `gsm3-api.js` 的实例 API、文件 API 和终端/进程列表 API。
+
+这种方式与当前插件体系匹配，风险较低，也不会把第三方网络工具耦合进核心部署页。
+
+### 核心 API 补强
+
+如果后续要做成完整的一键体验，核心需要补一个受限的后台进程/工具管理能力：
+
+- 管理受信任工具定义：工具名称、版本、下载地址、校验和、支持平台。
+- 统一保存配置：配置文件、敏感字段、脱敏展示、备份恢复。
+- 统一管理进程：启动、停止、重启、日志、健康状态、退出码。
+- 限制命令注入：不要让插件拼接任意 shell 字符串后直接执行。
+- 与实例端口关联：从游戏配置或实例元数据中读取端口，减少重复输入。
+
+## 安全与维护约束
+
+- 所有后端接口必须加认证中间件。
+- 持久化数据放在 `server/data` 下，兼容开发和打包路径。
+- token、密钥、服务端地址等敏感字段不要出现在日志和普通列表展示中。
+- 下载第三方工具必须记录来源、版本、哈希校验和失败回滚策略。
+- Windows、Linux、Docker 三种运行方式的路径、权限和停止信号要分别验证。
+- 默认生成的配置应当最小权限暴露，只映射用户明确选择的端口。
+
+## 下一步实现计划
+
+1. 创建 `server/data/plugins/tunnel-helper/`，复制示例插件的 `gsm3-api.js`，新增默认关闭的 `plugin.json`。
+2. 实现单页表单：选择已有游戏实例，选择 `frp` 或 `EasyTier`，填写本地端口、远端地址、远端端口和认证字段。
+3. 用文件 API 生成配置：frp 写入 `tunnels/<name>/frpc.toml`，EasyTier 写入 `tunnels/<name>/easytier.json` 或启动参数说明。
+4. 用实例 API 创建穿透实例：`workingDirectory` 指向隧道配置目录，`startCommand` 引用用户已安装的 `frpc` 或 `easytier-core` 可执行文件，`stopCommand` 使用 `ctrl+c`。
+5. 增加连接结果展示：保存配置路径、实例名称、远端连接地址、关联的游戏实例和端口。
+6. 增加敏感字段处理：表单默认隐藏 token，列表展示脱敏；后续如需服务端日志脱敏，再补核心 API。
+7. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
+
+## PR 拆分建议
+
+1. 通用内网穿透插件需求说明和界面草图。
+2. `tunnel-helper` 插件 MVP：生成配置并创建受管实例。
+3. 核心进程/工具 API 补强，完善二进制下载、校验、日志和状态检测。
diff --git "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
deleted file mode 100644
index 0698b839..00000000
--- "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\344\270\216\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ /dev/null
@@ -1,109 +0,0 @@
-# 泰拉瑞亚与内网穿透插件需求说明
-
-## 背景
-
-这次需求来自两个使用场景：
-
-- Steam 游戏部署列表中缺少原版泰拉瑞亚，用户需要回到文档手动下载、上传、解压和交互式配置。
-- 家用主机、NAS、宿舍网络、运营商 CGNAT 等没有公网入口的环境，游戏服务端即使启动成功，也不方便让外部玩家连接。
-
-## 已落地的最小改进
-
-### 泰拉瑞亚 Steam 部署入口
-
-在 `server/data/games/installgame.json` 中新增 `Terraria`：
-
-- 使用 SteamCMD 专用服务器列表中的 Terraria AppID：`105600`。
-- 默认端口：`7777/TCP`。
-- 默认不使用匿名登录，安装时需要填写已拥有 Terraria 的 Steam 用户名。密码可留空，让 SteamCMD 在终端中交互式输入密码和 Steam Guard 码。
-- 清单内提供 Windows/Linux 默认启动命令，避免实例创建后回落为 `none`。
-- 关联现有泰拉瑞亚开服文档。
-- 在提示中建议用 `serverconfig.txt` 启动，避免首次启动进入交互式建世界流程。
-
-推荐实例启动命令：
-
-```bash
-./TerrariaServer.bin.x86_64 -config serverconfig.txt
-```
-
-Windows 可改为：
-
-```powershell
-.\TerrariaServer.exe -config serverconfig.txt
-```
-
-### 泰拉瑞亚可视化配置模板
-
-在 `server/data/gameconfig/泰拉瑞亚.yml` 中新增 `serverconfig.txt` 模板：
-
-- 世界路径、自动建图、种子、世界名、难度。
-- 最大玩家数、端口、密码、MOTD。
-- 世界目录、封禁列表、作弊防护、语言、UPnP、NPC 同步、优先级。
-- 旅途模式权限项。
-
-模板使用现有 `properties` 解析器。Terraria 的 `0/1` 开关用 `select` 表达，避免保存成 `true/false` 后与服务端配置格式不一致。
-
-## 内网穿透插件候选需求
-
-### 目标
-
-提供一个可选工具，让没有公网 IP 的设备也能把游戏服务端端口暴露给外部玩家。插件应当只负责网络入口，不改变游戏实例本身的部署和启动逻辑。
-
-### 支持对象
-
-第一阶段建议支持：
-
-- frp 客户端模式：适合已有 frps 服务器的用户。
-- EasyTier 组网模式：适合希望多节点虚拟局域网互通的用户。
-
-### MVP 能力
-
-- 从实例列表选择一个游戏实例，读取实例名称、工作目录和端口信息。
-- 允许手动填写本地地址、本地端口、远端端口、远端服务器、认证 token 或组网密钥。
-- 生成 frpc 或 EasyTier 配置文件，默认保存到 `server/data/tunnels/` 下。
-- 通过实例管理创建一个独立的“穿透实例”，让用户用现有实例启停能力管理隧道进程。
-- 显示连接说明，例如 `远端地址:远端端口` 或 EasyTier 虚拟 IP。
-
-### 非目标
-
-- 不把 frp/EasyTier 变成游戏部署前置依赖。
-- 不替用户申请公网服务器或托管中继。
-- 不绕过游戏本身的账号、白名单、RCON、反作弊或服务端安全配置。
-- 不默认启用 UPnP 或自动开放所有端口。
-
-## 推荐实现方式
-
-### 插件优先
-
-先做成 `server/data/plugins/tunnel-helper` 这类可选插件：
-
-- `plugin.json` 默认 `enabled: false`，避免默认安装后自动出现网络暴露入口。
-- `index.html` 只做配置生成、实例创建和状态查看。
-- 复用 `gsm3-api.js` 的实例 API、文件 API 和终端/进程列表 API。
-
-这种方式与当前插件体系匹配，风险较低，也不会把第三方网络工具耦合进核心部署页。
-
-### 核心 API 补强
-
-如果后续要做成完整的一键体验，核心需要补一个受限的后台进程/工具管理能力：
-
-- 管理受信任工具定义：工具名称、版本、下载地址、校验和、支持平台。
-- 统一保存配置：配置文件、敏感字段、脱敏展示、备份恢复。
-- 统一管理进程：启动、停止、重启、日志、健康状态、退出码。
-- 限制命令注入：不要让插件拼接任意 shell 字符串后直接执行。
-- 与实例端口关联：从游戏配置或实例元数据中读取端口，减少重复输入。
-
-## 安全与维护约束
-
-- 所有后端接口必须加认证中间件。
-- 持久化数据放在 `server/data` 下，兼容开发和打包路径。
-- token、密钥、服务端地址等敏感字段不要出现在日志和普通列表展示中。
-- 不建议在仓库内直接提交第三方二进制；如需要下载，必须有来源、版本、哈希校验和失败回滚。
-- Windows、Linux、Docker 三种运行方式的路径、权限和停止信号要分别验证。
-
-## PR 拆分建议
-
-1. 泰拉瑞亚 Steam 安装清单与 `serverconfig.txt` 可视化模板。
-2. 内网穿透插件需求说明和界面草图。
-3. `tunnel-helper` 插件 MVP：生成配置并创建受管实例。
-4. 核心进程/工具 API 补强，完善二进制下载、校验、日志和状态检测。
diff --git "a/docs/\346\263\260\346\213\211\347\221\236\344\272\232\351\203\250\347\275\262\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\351\203\250\347\275\262\351\234\200\346\261\202\350\257\264\346\230\216.md"
new file mode 100644
index 00000000..c96f907d
--- /dev/null
+++ "b/docs/\346\263\260\346\213\211\347\221\236\344\272\232\351\203\250\347\275\262\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -0,0 +1,65 @@
+# 泰拉瑞亚部署需求说明
+
+## 背景
+
+Steam 游戏部署列表中缺少原版泰拉瑞亚，用户需要回到文档手动下载、上传、解压和交互式配置。
+
+本需求只覆盖泰拉瑞亚本身的部署入口、启动命令和 `serverconfig.txt` 可视化配置。没有公网入口、端口暴露、CGNAT 等问题统一放到通用的内网穿透插件需求中处理。
+
+## 已落地的最小改进
+
+### Steam 部署入口
+
+在 `server/data/games/installgame.json` 中新增 `Terraria`：
+
+- 使用 SteamCMD 专用服务器列表中的 Terraria AppID：`105600`。
+- 默认端口：`7777/TCP`。
+- 默认不使用匿名登录，安装时需要填写已拥有 Terraria 的 Steam 用户名。密码可留空，让 SteamCMD 在终端中交互式输入密码和 Steam Guard 码。
+- 清单内提供 Windows/Linux 默认启动命令，避免实例创建后回落为 `none`。
+- 关联现有泰拉瑞亚开服文档。
+- 在提示中建议用 `serverconfig.txt` 启动，避免首次启动进入交互式建世界流程。
+
+推荐 Linux 实例启动命令：
+
+```bash
+./TerrariaServer.bin.x86_64 -config serverconfig.txt
+```
+
+Windows 可改为：
+
+```powershell
+.\TerrariaServer.exe -config serverconfig.txt
+```
+
+### 可视化配置模板
+
+在 `server/data/gameconfig/泰拉瑞亚.yml` 中新增 `serverconfig.txt` 模板：
+
+- 世界路径、自动建图、种子、世界名、难度。
+- 最大玩家数、端口、密码、MOTD。
+- 世界目录、封禁列表、作弊防护、语言、UPnP、NPC 同步、优先级。
+- 旅途模式权限项。
+
+模板使用现有 `properties` 解析器。Terraria 的 `0/1` 开关用 `select` 表达，避免保存成 `true/false` 后与服务端配置格式不一致。
+
+## 使用提示
+
+### 安装命令
+
+SteamCMD 登录参数经过终端 shell 执行。包含 `$`、空格、`&`、引号等字符的密码不能直接裸写在命令行中，否则可能被 shell 解释。
+
+推荐在密码输入框留空，生成如下命令后在终端交互式输入密码和 Steam Guard 码：
+
+```powershell
+.\steamcmd.exe +force_install_dir "D:\Games\Terraria" +login xiwangly2 +app_update 105600 validate +quit
+```
+
+### 外部连接
+
+Terraria 默认监听 `7777/TCP`。外部玩家能否连接取决于防火墙、路由器端口转发、公网 IP 或内网穿透能力。跨游戏的端口暴露能力不放在泰拉瑞亚部署需求中实现，详见 `docs/内网穿透插件需求说明.md`。
+
+## PR 拆分建议
+
+1. 泰拉瑞亚 Steam 安装清单。
+2. 泰拉瑞亚 `serverconfig.txt` 可视化配置模板。
+3. SteamCMD 登录参数转义、密码可选输入、日志脱敏。

From 77d1367cd963d50191e4a532a42b88c86431b19d Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 13:18:37 +0800
Subject: [PATCH 05/10] feat: implement tunnel-helper plugin for frp and
 EasyTier configuration generation

---
 ...00\346\261\202\350\257\264\346\230\216.md" |  26 +-
 server/data/plugins/tunnel-helper/gsm3-api.js | 607 +++++++++++++
 server/data/plugins/tunnel-helper/index.html  | 829 ++++++++++++++++++
 server/data/plugins/tunnel-helper/plugin.json |  13 +
 server/src/modules/plugin/PluginManager.ts    |  21 +-
 5 files changed, 1485 insertions(+), 11 deletions(-)
 create mode 100644 server/data/plugins/tunnel-helper/gsm3-api.js
 create mode 100644 server/data/plugins/tunnel-helper/index.html
 create mode 100644 server/data/plugins/tunnel-helper/plugin.json

diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index 9c5ef3b2..4e8c6732 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -28,6 +28,18 @@
 - 显示连接说明，例如 `远端地址:远端端口` 或 EasyTier 虚拟 IP。
 - 不要求游戏实例和穿透实例同生命周期绑定，避免穿透失败影响游戏服务本身。
 
+## 已落地的 MVP
+
+新增 `server/data/plugins/tunnel-helper` 插件：
+
+- `plugin.json` 默认 `enabled: false`，作为可选工具提供。
+- 复用示例插件的 `gsm3-api.js`。
+- `index.html` 提供 frp / EasyTier 两种模式。
+- frp 模式生成 `tunnels/<name>/frpc.toml`，并创建使用 `frpc -c frpc.toml` 的独立实例。
+- EasyTier 模式生成 `tunnels/<name>/easytier-command.txt`，并创建使用命令行参数加入虚拟网络的独立实例。
+- 同步生成 `tunnels/<name>/manifest.json`，记录关联游戏实例、端口、协议、配置路径和连接地址。
+- 右侧预览会脱敏展示 `auth.token` 和 `--network-secret`。
+
 ## 非目标
 
 - 不把 frp/EasyTier 变成游戏部署前置依赖。
@@ -78,15 +90,13 @@
 - Windows、Linux、Docker 三种运行方式的路径、权限和停止信号要分别验证。
 - 默认生成的配置应当最小权限暴露，只映射用户明确选择的端口。
 
-## 下一步实现计划
+## 后续实现计划
 
-1. 创建 `server/data/plugins/tunnel-helper/`，复制示例插件的 `gsm3-api.js`，新增默认关闭的 `plugin.json`。
-2. 实现单页表单：选择已有游戏实例，选择 `frp` 或 `EasyTier`，填写本地端口、远端地址、远端端口和认证字段。
-3. 用文件 API 生成配置：frp 写入 `tunnels/<name>/frpc.toml`，EasyTier 写入 `tunnels/<name>/easytier.json` 或启动参数说明。
-4. 用实例 API 创建穿透实例：`workingDirectory` 指向隧道配置目录，`startCommand` 引用用户已安装的 `frpc` 或 `easytier-core` 可执行文件，`stopCommand` 使用 `ctrl+c`。
-5. 增加连接结果展示：保存配置路径、实例名称、远端连接地址、关联的游戏实例和端口。
-6. 增加敏感字段处理：表单默认隐藏 token，列表展示脱敏；后续如需服务端日志脱敏，再补核心 API。
-7. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
+1. 让插件从游戏部署清单或实例元数据中自动带出常见端口，减少手动输入。
+2. 增加“只生成配置”和“保存并创建实例”两个明确动作，便于只想拿配置文件的用户使用。
+3. 增加配置列表和更新能力，避免重复创建同名穿透实例。
+4. 如需服务端日志脱敏，补核心 API 层的敏感字段处理。
+5. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
 
 ## PR 拆分建议
 
diff --git a/server/data/plugins/tunnel-helper/gsm3-api.js b/server/data/plugins/tunnel-helper/gsm3-api.js
new file mode 100644
index 00000000..b1b88b88
--- /dev/null
+++ b/server/data/plugins/tunnel-helper/gsm3-api.js
@@ -0,0 +1,607 @@
+/**
+ * GSM3 插件API客户端
+ * 提供插件与主面板通信的接口
+ */
+class GSM3API {
+  constructor() {
+    this.baseURL = '/api/plugin-api'
+    this.token = null
+    this.initializeToken()
+  }
+
+  /**
+   * 初始化token获取机制
+   */
+  initializeToken() {
+    try {
+      // 检查是否已经通过脚本注入设置了全局token
+      if (window.gsm3Token) {
+        this.token = window.gsm3Token
+        console.log('Token已从全局变量获取:', this.token)
+        return
+      }
+      
+      // 检查是否已经通过脚本注入设置了token
+      if (window.gsm3 && window.gsm3.token) {
+        this.token = window.gsm3.token
+        console.log('Token已从注入脚本获取')
+        return
+      }
+      
+      // 尝试从父窗口获取token
+      if (window.parent && window.parent !== window) {
+        window.parent.postMessage({ type: 'gsm3-get-token' }, '*')
+      }
+      
+      console.log('正在初始化token...')
+    } catch (error) {
+      console.warn('Token初始化失败:', error)
+    }
+
+    // 监听token更新
+    window.addEventListener('message', (event) => {
+      if (event.data && event.data.type === 'gsm3-token-update') {
+        this.token = event.data.token
+        console.log('通过消息更新Token:', this.token)
+      }
+    })
+    
+    // 定期检查全局token变量
+    const checkGlobalToken = () => {
+      if (!this.token && window.gsm3Token) {
+        this.token = window.gsm3Token
+        console.log('从全局变量延迟获取Token:', this.token)
+      }
+    }
+    
+    // 每100ms检查一次，最多检查50次（5秒）
+    let checkCount = 0
+    const tokenChecker = setInterval(() => {
+      checkGlobalToken()
+      checkCount++
+      if (this.token || checkCount >= 50) {
+        clearInterval(tokenChecker)
+      }
+    }, 100)
+  }
+
+  /**
+   * 发送HTTP请求
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseURL}${endpoint}`
+    const config = {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Plugin-Request': 'true', // 添加插件标识
+        ...(this.token && { 'Authorization': `Bearer ${this.token}` })
+      },
+      ...options
+    }
+
+    if (config.body && typeof config.body === 'object') {
+      config.body = JSON.stringify(config.body)
+    }
+
+    try {
+      const response = await fetch(url, config)
+      const data = await response.json()
+      
+      if (!response.ok) {
+        throw new Error(data.message || `HTTP ${response.status}`)
+      }
+      
+      return data
+    } catch (error) {
+      console.error('API请求失败:', error)
+      throw error
+    }
+  }
+
+  // ==================== 系统信息API ====================
+
+  /**
+   * 获取系统状态
+   */
+  async getSystemStatus() {
+    return await this.request('/system/status')
+  }
+
+  /**
+   * 获取系统信息
+   */
+  async getSystemInfo() {
+    return await this.request('/system/info')
+  }
+
+  // ==================== 实例管理API ====================
+
+  /**
+   * 获取所有实例列表
+   */
+  async getInstances() {
+    return await this.request('/instances')
+  }
+
+  /**
+   * 获取单个实例信息
+   * @param {string} instanceId 实例ID
+   */
+  async getInstance(instanceId) {
+    return await this.request(`/instances/${instanceId}`)
+  }
+
+  /**
+   * 获取实例状态
+   * @param {string} instanceId 实例ID
+   */
+  async getInstanceStatus(instanceId) {
+    return await this.request(`/instances/${instanceId}/status`)
+  }
+
+  /**
+   * 创建新实例
+   * @param {Object} instanceData 实例数据
+   * @param {string} instanceData.name 实例名称
+   * @param {string} instanceData.description 实例描述
+   * @param {string} instanceData.workingDirectory 工作目录
+   * @param {string} instanceData.startCommand 启动命令
+   * @param {boolean} instanceData.autoStart 是否自动启动
+   * @param {string} instanceData.stopCommand 停止命令
+   */
+  async createInstance(instanceData) {
+    return await this.request('/instances', {
+      method: 'POST',
+      body: instanceData
+    })
+  }
+
+  /**
+   * 更新实例
+   * @param {string} instanceId 实例ID
+   * @param {Object} instanceData 实例数据
+   */
+  async updateInstance(instanceId, instanceData) {
+    return await this.request(`/instances/${instanceId}`, {
+      method: 'PUT',
+      body: instanceData
+    })
+  }
+
+  /**
+   * 删除实例
+   * @param {string} instanceId 实例ID
+   */
+  async deleteInstance(instanceId) {
+    return await this.request(`/instances/${instanceId}`, {
+      method: 'DELETE'
+    })
+  }
+
+  /**
+   * 启动实例
+   * @param {string} instanceId 实例ID
+   */
+  async startInstance(instanceId) {
+    return await this.request(`/instances/${instanceId}/start`, {
+      method: 'POST'
+    })
+  }
+
+  /**
+   * 停止实例
+   * @param {string} instanceId 实例ID
+   */
+  async stopInstance(instanceId) {
+    return await this.request(`/instances/${instanceId}/stop`, {
+      method: 'POST'
+    })
+  }
+
+  /**
+   * 重启实例
+   * @param {string} instanceId 实例ID
+   */
+  async restartInstance(instanceId) {
+    return await this.request(`/instances/${instanceId}/restart`, {
+      method: 'POST'
+    })
+  }
+
+  /**
+   * 获取实例市场列表
+   */
+  async getMarketInstances() {
+    return await this.request('/instances/market')
+  }
+
+  // ==================== 终端管理API ====================
+
+  /**
+   * 获取终端会话列表
+   */
+  async getTerminals() {
+    return await this.request('/terminals')
+  }
+
+   /**
+   * 获取终端会话统计信息
+   */
+  async getTerminalStats() {
+    return await this.request('/terminals/stats', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 获取终端会话详细信息
+   */
+  async getTerminalSessions() {
+    return await this.request('/terminals/sessions', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 获取活跃终端进程信息
+   */
+  async getActiveTerminalProcesses() {
+    return await this.request('/terminals/active-processes', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 更新终端会话名称
+   * @param {string} sessionId 会话ID
+   * @param {string} name 新的会话名称
+   */
+  async updateTerminalSessionName(sessionId, name) {
+    return await this.request(`/terminals/sessions/${sessionId}/name`, {
+      method: 'PUT',
+      body: { name }
+    })
+  }
+
+  /**
+   * 验证终端配置
+   * @param {string} workingDirectory 工作目录
+   * @param {string} shell Shell程序路径
+   */
+  async validateTerminalConfig(workingDirectory, shell) {
+    return await this.request('/terminals/validate-config', {
+      method: 'POST',
+      body: { workingDirectory, shell }
+    })
+  }
+
+  /**
+   * 获取系统默认Shell信息
+   */
+  async getDefaultShell() {
+    return await this.request('/terminals/default-shell', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 获取终端主题配置
+   */
+  async getTerminalThemes() {
+    return await this.request('/terminals/themes', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 获取终端字体配置
+   */
+  async getTerminalFonts() {
+    return await this.request('/terminals/fonts', {
+      method: 'GET'
+    })
+  }
+
+  /**
+   * 测试终端连接
+   * @param {string} workingDirectory 工作目录
+   */
+  async testTerminalConnection(workingDirectory) {
+    return await this.request('/terminals/test-connection', {
+      method: 'POST',
+      body: { workingDirectory }
+    })
+  }
+
+  // ==================== 游戏管理API ====================
+
+  /**
+   * 获取游戏列表
+   */
+  async getGames() {
+    return await this.request('/games')
+  }
+
+  // ==================== 文件操作API ====================
+
+  /**
+   * 读取文件内容
+   * @param {string} filePath 文件路径（相对于服务器data目录）
+   * @param {string} encoding 文件编码，默认为'utf-8'，二进制文件使用'binary'
+   */
+  async readFile(filePath, encoding = 'utf-8') {
+    return await this.request('/files/read', {
+      method: 'POST',
+      body: { filePath, encoding }
+    })
+  }
+
+  /**
+   * 写入文件内容
+   * @param {string} filePath 文件路径（相对于服务器data目录）
+   * @param {string} content 文件内容
+   * @param {string} encoding 文件编码，默认为'utf-8'
+   */
+  async writeFile(filePath, content, encoding = 'utf-8') {
+    return await this.request('/files/write', {
+      method: 'POST',
+      body: { filePath, content, encoding }
+    })
+  }
+
+  /**
+   * 删除文件
+   * @param {string} filePath 文件路径（相对于服务器data目录）
+   */
+  async deleteFile(filePath) {
+    return await this.request('/files/delete', {
+      method: 'DELETE',
+      body: { filePath }
+    })
+  }
+
+  /**
+   * 创建目录
+   * @param {string} dirPath 目录路径（相对于服务器data目录）
+   * @param {boolean} recursive 是否递归创建父目录，默认为true
+   */
+  async createDirectory(dirPath, recursive = true) {
+    return await this.request('/files/mkdir', {
+      method: 'POST',
+      body: { dirPath, recursive }
+    })
+  }
+
+  /**
+   * 删除目录
+   * @param {string} dirPath 目录路径（相对于服务器data目录）
+   * @param {boolean} recursive 是否递归删除，默认为false
+   */
+  async deleteDirectory(dirPath, recursive = false) {
+    return await this.request('/files/rmdir', {
+      method: 'DELETE',
+      body: { dirPath, recursive }
+    })
+  }
+
+  /**
+   * 列出目录内容
+   * @param {string} dirPath 目录路径（相对于服务器data目录），默认为根目录
+   * @param {boolean} includeHidden 是否包含隐藏文件，默认为false
+   */
+  async listDirectory(dirPath = '', includeHidden = false) {
+    return await this.request('/files/list', {
+      method: 'POST',
+      body: { dirPath, includeHidden }
+    })
+  }
+
+  /**
+   * 获取文件或目录信息
+   * @param {string} path 文件或目录路径（相对于服务器data目录）
+   */
+  async getFileInfo(path) {
+    return await this.request('/files/info', {
+      method: 'POST',
+      body: { path }
+    })
+  }
+
+  /**
+   * 检查文件或目录是否存在
+   * @param {string} path 文件或目录路径（相对于服务器data目录）
+   */
+  async exists(path) {
+    return await this.request('/files/exists', {
+      method: 'POST',
+      body: { path }
+    })
+  }
+
+  /**
+   * 复制文件或目录
+   * @param {string} sourcePath 源路径（相对于服务器data目录）
+   * @param {string} destPath 目标路径（相对于服务器data目录）
+   * @param {boolean} overwrite 是否覆盖已存在的文件，默认为false
+   */
+  async copy(sourcePath, destPath, overwrite = false) {
+    return await this.request('/files/copy', {
+      method: 'POST',
+      body: { sourcePath, destPath, overwrite }
+    })
+  }
+
+  /**
+   * 移动/重命名文件或目录
+   * @param {string} sourcePath 源路径（相对于服务器data目录）
+   * @param {string} destPath 目标路径（相对于服务器data目录）
+   * @param {boolean} overwrite 是否覆盖已存在的文件，默认为false
+   */
+  async move(sourcePath, destPath, overwrite = false) {
+    return await this.request('/files/move', {
+      method: 'POST',
+      body: { sourcePath, destPath, overwrite }
+    })
+  }
+
+  /**
+   * 搜索文件
+   * @param {string} pattern 搜索模式（支持通配符）
+   * @param {string} searchPath 搜索路径（相对于服务器data目录），默认为根目录
+   * @param {boolean} recursive 是否递归搜索子目录，默认为true
+   */
+  async searchFiles(pattern, searchPath = '', recursive = true) {
+    return await this.request('/files/search', {
+      method: 'POST',
+      body: { pattern, searchPath, recursive }
+    })
+  }
+
+  // ==================== 通用API ====================
+
+  /**
+   * 获取API版本信息
+   */
+  async getVersion() {
+    return await this.request('/version')
+  }
+
+  /**
+   * 健康检查
+   */
+  async healthCheck() {
+    return await this.request('/health')
+  }
+
+  // ==================== 工具方法 ====================
+
+  /**
+   * 显示通知消息（如果主面板支持）
+   * @param {string} type 消息类型: 'info', 'success', 'warning', 'error'
+   * @param {string} message 消息内容
+   */
+  showNotification(type, message) {
+    try {
+      // 尝试向父窗口发送通知消息
+      if (window.parent && window.parent !== window) {
+        window.parent.postMessage({
+          type: 'gsm3-notification',
+          data: { type, message }
+        }, '*')
+      } else {
+        // 如果无法发送到父窗口，使用浏览器原生通知
+        console.log(`[${type.toUpperCase()}] ${message}`)
+      }
+    } catch (error) {
+      console.warn('发送通知失败:', error)
+    }
+  }
+
+  /**
+   * 格式化字节大小
+   * @param {number} bytes 字节数
+   * @param {number} decimals 小数位数
+   */
+  formatBytes(bytes, decimals = 2) {
+    if (bytes === 0) return '0 Bytes'
+    
+    const k = 1024
+    const dm = decimals < 0 ? 0 : decimals
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+    
+    const i = Math.floor(Math.log(bytes) / Math.log(k))
+    
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
+  }
+
+  /**
+   * 格式化时间戳
+   * @param {string|number|Date} timestamp 时间戳
+   */
+  formatTime(timestamp) {
+    const date = new Date(timestamp)
+    return date.toLocaleString('zh-CN', {
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit'
+    })
+  }
+
+  /**
+   * 格式化运行时间
+   * @param {number} seconds 秒数
+   */
+  formatUptime(seconds) {
+    const days = Math.floor(seconds / 86400)
+    const hours = Math.floor((seconds % 86400) / 3600)
+    const minutes = Math.floor((seconds % 3600) / 60)
+    const secs = Math.floor(seconds % 60)
+    
+    const parts = []
+    if (days > 0) parts.push(`${days}天`)
+    if (hours > 0) parts.push(`${hours}小时`)
+    if (minutes > 0) parts.push(`${minutes}分钟`)
+    if (secs > 0 || parts.length === 0) parts.push(`${secs}秒`)
+    
+    return parts.join(' ')
+  }
+}
+
+// 创建全局实例
+window.gsm3 = new GSM3API()
+
+// 添加初始化状态标记
+window.gsm3.isInitialized = false
+window.gsm3.initPromise = null
+
+// 初始化API的Promise
+window.gsm3.initialize = function() {
+  if (this.initPromise) {
+    return this.initPromise
+  }
+  
+  this.initPromise = new Promise((resolve) => {
+    const checkReady = () => {
+      if (this.token) {
+        this.isInitialized = true
+        console.log('GSM3 API初始化完成，Token:', this.token)
+        resolve(true)
+      } else {
+        setTimeout(checkReady, 100)
+      }
+    }
+    checkReady()
+  })
+  
+  return this.initPromise
+}
+
+// 监听来自父窗口的消息
+window.addEventListener('message', (event) => {
+  if (event.data && event.data.type === 'gsm3-token-update') {
+    window.gsm3.token = event.data.token
+    console.log('Token已更新:', event.data.token)
+  }
+})
+
+// 插件加载完成后的初始化
+document.addEventListener('DOMContentLoaded', () => {
+  console.log('GSM3 插件API已加载')
+  
+  // 启动初始化过程
+  window.gsm3.initialize().then(() => {
+    console.log('GSM3 API准备就绪')
+    
+    // 向父窗口发送插件加载完成的消息
+    if (window.parent && window.parent !== window) {
+      window.parent.postMessage({
+        type: 'gsm3-plugin-loaded',
+        data: { timestamp: new Date().toISOString() }
+      }, '*')
+    }
+  })
+})
\ No newline at end of file
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
new file mode 100644
index 00000000..217f46dc
--- /dev/null
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -0,0 +1,829 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>内网穿透助手</title>
+  <script src="gsm3-api.js"></script>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #f6f7f9;
+      --panel: #ffffff;
+      --panel-soft: #f1f5f9;
+      --border: #d8dee8;
+      --text: #162033;
+      --muted: #64748b;
+      --primary: #2563eb;
+      --primary-strong: #1d4ed8;
+      --success: #15803d;
+      --danger: #b91c1c;
+      --warning: #a16207;
+      --code: #0f172a;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0f172a;
+        --panel: #111827;
+        --panel-soft: #1f2937;
+        --border: #334155;
+        --text: #e5e7eb;
+        --muted: #94a3b8;
+        --primary: #3b82f6;
+        --primary-strong: #60a5fa;
+        --success: #22c55e;
+        --danger: #f87171;
+        --warning: #facc15;
+        --code: #020617;
+      }
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", sans-serif;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    main {
+      max-width: 1180px;
+      margin: 0 auto;
+      padding: 24px;
+    }
+
+    header {
+      display: flex;
+      align-items: flex-start;
+      justify-content: space-between;
+      gap: 16px;
+      margin-bottom: 18px;
+    }
+
+    h1 {
+      margin: 0;
+      font-size: 24px;
+      line-height: 1.2;
+    }
+
+    h2 {
+      margin: 0 0 14px;
+      font-size: 17px;
+      line-height: 1.3;
+    }
+
+    p {
+      margin: 0;
+      color: var(--muted);
+    }
+
+    .toolbar {
+      display: flex;
+      gap: 10px;
+      flex-wrap: wrap;
+      justify-content: flex-end;
+    }
+
+    .layout {
+      display: grid;
+      grid-template-columns: minmax(320px, 420px) 1fr;
+      gap: 18px;
+      align-items: start;
+    }
+
+    .panel {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 18px;
+      box-shadow: 0 1px 2px rgb(15 23 42 / 6%);
+    }
+
+    .stack {
+      display: grid;
+      gap: 14px;
+    }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 12px;
+    }
+
+    label {
+      display: grid;
+      gap: 6px;
+      color: var(--text);
+      font-weight: 600;
+    }
+
+    input,
+    select,
+    textarea {
+      width: 100%;
+      min-height: 38px;
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 8px 10px;
+      background: var(--panel);
+      color: var(--text);
+      font: inherit;
+    }
+
+    textarea {
+      min-height: 118px;
+      resize: vertical;
+      font-family: "Cascadia Code", Consolas, monospace;
+      font-size: 12px;
+    }
+
+    .hint {
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 400;
+    }
+
+    .segmented {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 8px;
+    }
+
+    .segment {
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 10px;
+      cursor: pointer;
+      background: var(--panel);
+      color: var(--text);
+      text-align: left;
+    }
+
+    .segment.active {
+      border-color: var(--primary);
+      box-shadow: 0 0 0 2px rgb(37 99 235 / 14%);
+    }
+
+    button {
+      border: 0;
+      border-radius: 6px;
+      padding: 9px 12px;
+      cursor: pointer;
+      background: var(--primary);
+      color: #fff;
+      font-weight: 700;
+    }
+
+    button.secondary {
+      background: var(--panel-soft);
+      color: var(--text);
+      border: 1px solid var(--border);
+    }
+
+    button:disabled {
+      cursor: not-allowed;
+      opacity: .55;
+    }
+
+    button:hover:not(:disabled) {
+      background: var(--primary-strong);
+    }
+
+    button.secondary:hover:not(:disabled) {
+      background: var(--border);
+    }
+
+    .message {
+      display: none;
+      border-radius: 6px;
+      padding: 10px 12px;
+      border: 1px solid var(--border);
+      background: var(--panel-soft);
+    }
+
+    .message.show {
+      display: block;
+    }
+
+    .message.success {
+      border-color: color-mix(in srgb, var(--success), transparent 58%);
+      color: var(--success);
+    }
+
+    .message.error {
+      border-color: color-mix(in srgb, var(--danger), transparent 58%);
+      color: var(--danger);
+    }
+
+    .message.warn {
+      border-color: color-mix(in srgb, var(--warning), transparent 58%);
+      color: var(--warning);
+    }
+
+    pre {
+      margin: 0;
+      min-height: 320px;
+      max-height: 520px;
+      overflow: auto;
+      border-radius: 8px;
+      border: 1px solid var(--border);
+      background: var(--code);
+      color: #dbeafe;
+      padding: 14px;
+      font-family: "Cascadia Code", Consolas, monospace;
+      font-size: 12px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+
+    .meta {
+      display: grid;
+      gap: 8px;
+      padding: 12px;
+      border-radius: 6px;
+      background: var(--panel-soft);
+    }
+
+    .meta-row {
+      display: grid;
+      grid-template-columns: 110px 1fr;
+      gap: 8px;
+    }
+
+    .meta-row strong {
+      color: var(--muted);
+      font-weight: 600;
+    }
+
+    .hidden {
+      display: none !important;
+    }
+
+    @media (max-width: 900px) {
+      main {
+        padding: 16px;
+      }
+
+      header,
+      .layout,
+      .grid {
+        grid-template-columns: 1fr;
+      }
+
+      header {
+        display: grid;
+      }
+
+      .toolbar {
+        justify-content: flex-start;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div>
+        <h1>内网穿透助手</h1>
+        <p>为现有游戏实例生成 frp 或 EasyTier 配置，并创建独立穿透实例。</p>
+      </div>
+      <div class="toolbar">
+        <button class="secondary" id="refreshInstancesButton" type="button">刷新实例</button>
+        <button class="secondary" id="previewButton" type="button">预览配置</button>
+        <button id="createButton" type="button">保存并创建实例</button>
+      </div>
+    </header>
+
+    <div class="layout">
+      <section class="panel stack">
+        <h2>目标实例</h2>
+        <label>
+          游戏实例
+          <select id="instanceSelect"></select>
+          <span class="hint">穿透实例会独立创建，不会修改所选游戏实例。</span>
+        </label>
+        <div class="meta" id="instanceMeta">
+          <div class="meta-row"><strong>工作目录</strong><span id="instancePath">-</span></div>
+          <div class="meta-row"><strong>启动命令</strong><span id="instanceCommand">-</span></div>
+          <div class="meta-row"><strong>状态</strong><span id="instanceStatus">-</span></div>
+        </div>
+
+        <h2>穿透方式</h2>
+        <div class="segmented">
+          <button class="segment active" id="modeFrp" type="button">
+            <strong>frp</strong><br>
+            <span class="hint">映射本地端口到 frps</span>
+          </button>
+          <button class="segment" id="modeEasyTier" type="button">
+            <strong>EasyTier</strong><br>
+            <span class="hint">加入虚拟局域网</span>
+          </button>
+        </div>
+
+        <div class="grid">
+          <label>
+            配置名称
+            <input id="profileName" autocomplete="off" placeholder="terraria-7777">
+          </label>
+          <label>
+            本地地址
+            <input id="localAddress" autocomplete="off" value="127.0.0.1">
+          </label>
+          <label>
+            本地端口
+            <input id="localPort" type="number" min="1" max="65535" value="7777">
+          </label>
+          <label>
+            协议
+            <select id="protocol">
+              <option value="tcp">TCP</option>
+              <option value="udp">UDP</option>
+            </select>
+          </label>
+        </div>
+
+        <div id="frpFields" class="stack">
+          <h2>frp 参数</h2>
+          <label>
+            frpc 可执行文件
+            <input id="frpcPath" autocomplete="off" value="frpc" placeholder="frpc 或 C:\frp\frpc.exe">
+          </label>
+          <div class="grid">
+            <label>
+              frps 地址
+              <input id="frpServerAddr" autocomplete="off" placeholder="example.com">
+            </label>
+            <label>
+              frps 端口
+              <input id="frpServerPort" type="number" min="1" max="65535" value="7000">
+            </label>
+            <label>
+              远端端口
+              <input id="remotePort" type="number" min="1" max="65535" value="7777">
+            </label>
+            <label>
+              认证 token
+              <input id="frpToken" type="password" autocomplete="off" placeholder="可选">
+            </label>
+          </div>
+        </div>
+
+        <div id="easyTierFields" class="stack hidden">
+          <h2>EasyTier 参数</h2>
+          <label>
+            easytier-core 可执行文件
+            <input id="easyTierPath" autocomplete="off" value="easytier-core" placeholder="easytier-core 或 C:\EasyTier\easytier-core.exe">
+          </label>
+          <div class="grid">
+            <label>
+              网络名称
+              <input id="networkName" autocomplete="off" placeholder="game-net">
+            </label>
+            <label>
+              网络密钥
+              <input id="networkSecret" type="password" autocomplete="off">
+            </label>
+            <label>
+              节点名称
+              <input id="hostName" autocomplete="off" placeholder="gsm-node">
+            </label>
+            <label>
+              虚拟 IPv4
+              <input id="virtualIpv4" autocomplete="off" placeholder="留空使用 DHCP">
+            </label>
+          </div>
+          <label>
+            Peer 节点
+            <textarea id="peerList" placeholder="tcp://1.2.3.4:11010&#10;udp://1.2.3.4:11010"></textarea>
+            <span class="hint">每行一个 peer。未填写时只启动本地节点，通常无法自动发现其它节点。</span>
+          </label>
+        </div>
+
+        <div id="message" class="message"></div>
+      </section>
+
+      <section class="panel stack">
+        <h2>生成结果</h2>
+        <div class="meta" id="resultMeta">
+          <div class="meta-row"><strong>配置目录</strong><span id="resultDir">-</span></div>
+          <div class="meta-row"><strong>启动命令</strong><span id="resultCommand">-</span></div>
+          <div class="meta-row"><strong>连接地址</strong><span id="resultAddress">-</span></div>
+        </div>
+        <pre id="preview"></pre>
+      </section>
+    </div>
+  </main>
+
+  <script>
+    const state = {
+      mode: 'frp',
+      instances: [],
+      systemInfo: null,
+      lastPlan: null
+    }
+
+    const $ = (id) => document.getElementById(id)
+
+    const fields = [
+      'instanceSelect', 'profileName', 'localAddress', 'localPort', 'protocol',
+      'frpcPath', 'frpServerAddr', 'frpServerPort', 'remotePort', 'frpToken',
+      'easyTierPath', 'networkName', 'networkSecret', 'hostName', 'virtualIpv4', 'peerList'
+    ]
+
+    const read = (id) => $(id).value.trim()
+    const isWindows = () => {
+      const raw = state.systemInfo && state.systemInfo.rawPlatform
+      const platform = state.systemInfo && state.systemInfo.platform
+      return raw === 'win32' || String(platform || '').toLowerCase().includes('windows')
+    }
+
+    function showMessage(type, text) {
+      const message = $('message')
+      message.className = `message show ${type}`
+      message.textContent = text
+    }
+
+    function clearMessage() {
+      const message = $('message')
+      message.className = 'message'
+      message.textContent = ''
+    }
+
+    function normalizeListResponse(result) {
+      if (!result) return []
+      if (Array.isArray(result)) return result
+      if (Array.isArray(result.data)) return result.data
+      if (result.data && Array.isArray(result.data.instances)) return result.data.instances
+      return []
+    }
+
+    function sanitizeSlug(value) {
+      return value
+        .toLowerCase()
+        .replace(/[^a-z0-9\u4e00-\u9fa5_-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || `tunnel-${Date.now()}`
+    }
+
+    function tomlString(value) {
+      return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+    }
+
+    function psArg(value) {
+      return `'${String(value).replace(/'/g, "''")}'`
+    }
+
+    function shArg(value) {
+      return `'${String(value).replace(/'/g, "'\\''")}'`
+    }
+
+    function shellArg(value) {
+      return isWindows() ? psArg(value) : shArg(value)
+    }
+
+    function redactSensitiveText(text) {
+      return String(text)
+        .replace(/auth\.token\s*=\s*"[^"]*"/g, 'auth.token = "******"')
+        .replace(/('--network-secret'|--network-secret)\s+('(?:''|[^'])*'|"[^"]*"|\S+)/g, '$1 ******')
+    }
+
+    function commandPrefix(executablePath) {
+      const quoted = shellArg(executablePath)
+      return isWindows() ? `& ${quoted}` : quoted
+    }
+
+    function parsePort(value, label) {
+      const port = Number(value)
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`${label} 必须是 1 到 65535 之间的整数`)
+      }
+      return port
+    }
+
+    function getSelectedInstance() {
+      const id = read('instanceSelect')
+      return state.instances.find(instance => instance.id === id) || null
+    }
+
+    function guessPort(instance) {
+      const text = `${instance.name || ''} ${instance.description || ''}`.toLowerCase()
+      if (text.includes('terraria') || text.includes('泰拉瑞亚')) return 7777
+      if (text.includes('minecraft') || text.includes('我的世界')) return 25565
+      if (text.includes('palworld') || text.includes('幻兽帕鲁')) return 8211
+      if (text.includes('valheim') || text.includes('英灵神殿')) return 2456
+      if (text.includes('factorio')) return 34197
+      return ''
+    }
+
+    function updateInstanceMeta() {
+      const instance = getSelectedInstance()
+      $('instancePath').textContent = instance ? instance.workingDirectory || '-' : '-'
+      $('instanceCommand').textContent = instance ? instance.startCommand || '-' : '-'
+      $('instanceStatus').textContent = instance ? instance.status || '-' : '-'
+
+      if (instance && !read('profileName')) {
+        $('profileName').value = sanitizeSlug(instance.name || 'game')
+      }
+
+      if (instance && !read('localPort')) {
+        const guessed = guessPort(instance)
+        if (guessed) $('localPort').value = guessed
+      }
+    }
+
+    async function loadSystemInfo() {
+      try {
+        const result = await window.gsm3.getSystemInfo()
+        state.systemInfo = result.data || result
+      } catch (error) {
+        state.systemInfo = null
+      }
+    }
+
+    async function loadInstances() {
+      clearMessage()
+      $('instanceSelect').innerHTML = '<option value="">加载中...</option>'
+      try {
+        const result = await window.gsm3.getInstances()
+        state.instances = normalizeListResponse(result)
+        const gameInstances = state.instances.filter(instance => {
+          const description = String(instance.description || '')
+          return !description.includes('[tunnel-helper]')
+        })
+
+        $('instanceSelect').innerHTML = ''
+        if (gameInstances.length === 0) {
+          $('instanceSelect').innerHTML = '<option value="">暂无可选实例</option>'
+          updateInstanceMeta()
+          return
+        }
+
+        for (const instance of gameInstances) {
+          const option = document.createElement('option')
+          option.value = instance.id
+          option.textContent = `${instance.name} (${instance.status || 'unknown'})`
+          $('instanceSelect').appendChild(option)
+        }
+
+        updateInstanceMeta()
+        showMessage('success', `已加载 ${gameInstances.length} 个游戏实例`)
+      } catch (error) {
+        $('instanceSelect').innerHTML = '<option value="">加载失败</option>'
+        showMessage('error', `获取实例列表失败：${error.message}`)
+      }
+    }
+
+    function setMode(mode) {
+      state.mode = mode
+      $('modeFrp').classList.toggle('active', mode === 'frp')
+      $('modeEasyTier').classList.toggle('active', mode === 'easytier')
+      $('frpFields').classList.toggle('hidden', mode !== 'frp')
+      $('easyTierFields').classList.toggle('hidden', mode !== 'easytier')
+      buildPlan(false)
+    }
+
+    function buildFrpPlan(common) {
+      const serverAddr = read('frpServerAddr')
+      const serverPort = parsePort(read('frpServerPort'), 'frps 端口')
+      const remotePort = parsePort(read('remotePort'), '远端端口')
+      const frpcPath = read('frpcPath')
+
+      if (!frpcPath) throw new Error('请填写 frpc 可执行文件')
+      if (!serverAddr) throw new Error('请填写 frps 地址')
+
+      const token = read('frpToken')
+      const proxyName = `${common.slug}-${common.protocol}-${common.localPort}`
+      const configLines = [
+        `serverAddr = ${tomlString(serverAddr)}`,
+        `serverPort = ${serverPort}`
+      ]
+
+      if (token) {
+        configLines.push(`auth.token = ${tomlString(token)}`)
+      }
+
+      configLines.push(
+        '',
+        '[[proxies]]',
+        `name = ${tomlString(proxyName)}`,
+        `type = ${tomlString(common.protocol)}`,
+        `localIP = ${tomlString(common.localAddress)}`,
+        `localPort = ${common.localPort}`,
+        `remotePort = ${remotePort}`,
+        ''
+      )
+
+      const configPath = `${common.dataDir}/frpc.toml`
+      const startCommand = `${commandPrefix(frpcPath)} -c ${shellArg('frpc.toml')}`
+      const publicAddress = `${serverAddr}:${remotePort}`
+
+      return {
+        ...common,
+        tool: 'frp',
+        configPath,
+        configContent: configLines.join('\n'),
+        startCommand,
+        executablePath: frpcPath,
+        publicAddress,
+        extraFiles: [],
+        instanceDescription: `[tunnel-helper] frp ${common.protocol.toUpperCase()} ${common.localAddress}:${common.localPort} -> ${publicAddress}`
+      }
+    }
+
+    function buildEasyTierPlan(common) {
+      const executablePath = read('easyTierPath')
+      const networkName = read('networkName')
+      const networkSecret = read('networkSecret')
+      const hostName = read('hostName') || common.slug
+      const virtualIpv4 = read('virtualIpv4')
+      const peers = read('peerList')
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(Boolean)
+
+      if (!executablePath) throw new Error('请填写 easytier-core 可执行文件')
+      if (!networkName) throw new Error('请填写 EasyTier 网络名称')
+      if (!networkSecret) throw new Error('请填写 EasyTier 网络密钥')
+
+      const args = [
+        '--network-name', networkName,
+        '--network-secret', networkSecret,
+        '--hostname', hostName
+      ]
+
+      if (virtualIpv4) {
+        args.push('--ipv4', virtualIpv4)
+      } else {
+        args.push('--dhcp')
+      }
+
+      for (const peer of peers) {
+        args.push('-p', peer)
+      }
+
+      const startCommand = `${commandPrefix(executablePath)} ${args.map(shellArg).join(' ')}`
+      const publicAddress = virtualIpv4
+        ? `${virtualIpv4}:${common.localPort}`
+        : `EasyTier 虚拟 IP:${common.localPort}`
+
+      const commandContent = [
+        '# EasyTier 启动命令',
+        '# 该实例使用命令行参数启动，避免依赖不同版本配置文件字段差异。',
+        startCommand,
+        '',
+        '# 连接提示',
+        `# 其它 EasyTier 节点加入同一网络后，访问 ${publicAddress}`
+      ].join('\n')
+
+      return {
+        ...common,
+        tool: 'EasyTier',
+        configPath: `${common.dataDir}/easytier-command.txt`,
+        configContent: commandContent,
+        startCommand,
+        executablePath,
+        publicAddress,
+        extraFiles: [],
+        instanceDescription: `[tunnel-helper] EasyTier network=${networkName} target=${common.localAddress}:${common.localPort}`
+      }
+    }
+
+    function buildPlan(throwOnError = true) {
+      try {
+        const instance = getSelectedInstance()
+        if (!instance) throw new Error('请选择游戏实例')
+
+        const localPort = parsePort(read('localPort'), '本地端口')
+        const localAddress = read('localAddress') || '127.0.0.1'
+        const profile = read('profileName') || instance.name || 'game'
+        const slug = sanitizeSlug(profile)
+        const protocol = read('protocol')
+        const dataDir = `tunnels/${slug}`
+        const workingDirectory = `data/${dataDir}`
+
+        const common = {
+          instance,
+          profile,
+          slug,
+          protocol,
+          localAddress,
+          localPort,
+          dataDir,
+          workingDirectory
+        }
+
+        state.lastPlan = state.mode === 'frp' ? buildFrpPlan(common) : buildEasyTierPlan(common)
+        renderPlan()
+        clearMessage()
+        return state.lastPlan
+      } catch (error) {
+        state.lastPlan = null
+        renderPlan()
+        if (throwOnError) {
+          showMessage('error', error.message)
+        }
+        return null
+      }
+    }
+
+    function renderPlan() {
+      const plan = state.lastPlan
+      if (!plan) {
+        $('resultDir').textContent = '-'
+        $('resultCommand').textContent = '-'
+        $('resultAddress').textContent = '-'
+        $('preview').textContent = ''
+        return
+      }
+
+      $('resultDir').textContent = plan.workingDirectory
+      $('resultCommand').textContent = redactSensitiveText(plan.startCommand)
+      $('resultAddress').textContent = plan.publicAddress
+      $('preview').textContent = redactSensitiveText(plan.configContent)
+    }
+
+    function buildManifest(plan) {
+      return {
+        name: plan.profile,
+        tool: plan.tool,
+        linkedInstanceId: plan.instance.id,
+        linkedInstanceName: plan.instance.name,
+        localAddress: plan.localAddress,
+        localPort: plan.localPort,
+        protocol: plan.protocol,
+        publicAddress: plan.publicAddress,
+        workingDirectory: plan.workingDirectory,
+        configPath: plan.configPath,
+        createdAt: new Date().toISOString()
+      }
+    }
+
+    async function createTunnelInstance() {
+      const plan = buildPlan(true)
+      if (!plan) return
+
+      $('createButton').disabled = true
+      try {
+        await window.gsm3.writeFile(plan.configPath, plan.configContent, 'utf-8')
+        await window.gsm3.writeFile(`${plan.dataDir}/manifest.json`, JSON.stringify(buildManifest(plan), null, 2), 'utf-8')
+
+        const result = await window.gsm3.createInstance({
+          name: `穿透-${plan.profile}`,
+          description: plan.instanceDescription,
+          workingDirectory: plan.workingDirectory,
+          startCommand: plan.startCommand,
+          stopCommand: 'ctrl+c',
+          autoStart: false
+        })
+
+        const created = result.data || result
+        showMessage('success', `穿透实例已创建：${created.name || `穿透-${plan.profile}`}`)
+        await loadInstances()
+      } catch (error) {
+        showMessage('error', `创建穿透实例失败：${error.message}`)
+      } finally {
+        $('createButton').disabled = false
+      }
+    }
+
+    function attachEvents() {
+      $('refreshInstancesButton').addEventListener('click', loadInstances)
+      $('previewButton').addEventListener('click', () => buildPlan(true))
+      $('createButton').addEventListener('click', createTunnelInstance)
+      $('modeFrp').addEventListener('click', () => setMode('frp'))
+      $('modeEasyTier').addEventListener('click', () => setMode('easytier'))
+      $('instanceSelect').addEventListener('change', () => {
+        updateInstanceMeta()
+        buildPlan(false)
+      })
+
+      for (const id of fields) {
+        const element = $(id)
+        if (!element) continue
+        element.addEventListener('input', () => buildPlan(false))
+        element.addEventListener('change', () => buildPlan(false))
+      }
+    }
+
+    async function boot() {
+      if (!window.gsm3) {
+        showMessage('error', '插件 API 未加载')
+        return
+      }
+
+      attachEvents()
+      await loadSystemInfo()
+      await loadInstances()
+      buildPlan(false)
+    }
+
+    boot()
+  </script>
+</body>
+</html>
diff --git a/server/data/plugins/tunnel-helper/plugin.json b/server/data/plugins/tunnel-helper/plugin.json
new file mode 100644
index 00000000..66c849bc
--- /dev/null
+++ b/server/data/plugins/tunnel-helper/plugin.json
@@ -0,0 +1,13 @@
+{
+  "name": "tunnel-helper",
+  "displayName": "内网穿透助手",
+  "description": "为任意游戏实例生成 frp 或 EasyTier 穿透配置，并创建独立的穿透实例。",
+  "version": "0.1.0",
+  "author": "GSM3 Community",
+  "enabled": false,
+  "hasWebInterface": true,
+  "entryPoint": "index.html",
+  "icon": "network",
+  "category": "工具",
+  "keywords": ["内网穿透", "frp", "EasyTier", "游戏联机"]
+}
diff --git a/server/src/modules/plugin/PluginManager.ts b/server/src/modules/plugin/PluginManager.ts
index c84fc2d5..9a1a228f 100644
--- a/server/src/modules/plugin/PluginManager.ts
+++ b/server/src/modules/plugin/PluginManager.ts
@@ -1,4 +1,5 @@
 import { promises as fs } from 'fs'
+import fsSync from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import winston from 'winston'
@@ -39,8 +40,22 @@ export class PluginManager {
 
   constructor(logger: winston.Logger) {
     this.logger = logger
-    // this.pluginsDir = path.join(__dirname, '../../../data/plugins')
-    this.pluginsDir = path.join(__dirname, '../../data/plugins')
+    const baseDir = process.cwd()
+    const possiblePaths = [
+      path.join(baseDir, 'data', 'plugins'),           // 打包后的路径
+      path.join(baseDir, 'server', 'data', 'plugins'), // 开发环境路径
+      path.join(__dirname, '../../data/plugins'),      // dist/modules/plugin -> data/plugins
+      path.join(__dirname, '../../../data/plugins')    // src/modules/plugin -> server/data/plugins
+    ]
+
+    this.pluginsDir = possiblePaths[0]
+    for (const possiblePath of possiblePaths) {
+      if (fsSync.existsSync(possiblePath)) {
+        this.pluginsDir = possiblePath
+        break
+      }
+    }
+
     this.initializePluginsDirectory()
   }
 
@@ -317,4 +332,4 @@ export class PluginManager {
     this.plugins.clear()
     this.logger.info('PluginManager 已清理')
   }
-}
\ No newline at end of file
+}

From 78b1c25e893f7652cc2f618901a92abcbc20ee5d Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 13:30:11 +0800
Subject: [PATCH 06/10] feat: add support for tunnel instance creation and
 enhance plugin management UI

---
 .gitignore                                    |  4 +-
 client/src/components/Layout.tsx              |  5 +-
 client/src/pages/PluginsPage.tsx              | 39 ++++++++------
 ...00\346\261\202\350\257\264\346\230\216.md" | 15 ++++++
 server/data/plugins/tunnel-helper/index.html  | 52 ++++++++++++++++---
 server/data/plugins/tunnel-helper/plugin.json |  7 ++-
 6 files changed, 92 insertions(+), 30 deletions(-)

diff --git a/.gitignore b/.gitignore
index e75da8b9..37f90c32 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,8 +29,10 @@ favorites.json
 server/data/environment
 server/data/wallpapers/
 server/data/lib/
+server/data/tunnels/
 data/wallpapers/
 data/lib/
+data/tunnels/
 
 
 dist/
@@ -144,4 +146,4 @@ src/public/1.png
 
 .turbo
 参考文件/
-.报错.txt
\ No newline at end of file
+.报错.txt
diff --git a/client/src/components/Layout.tsx b/client/src/components/Layout.tsx
index f7b99ea5..6b3e89f8 100644
--- a/client/src/components/Layout.tsx
+++ b/client/src/components/Layout.tsx
@@ -31,6 +31,7 @@ import {
   HelpCircle,
   CheckCircle,
   Coffee,
+  Puzzle,
   ChevronLeft,
   ChevronRight
 } from 'lucide-react'
@@ -67,7 +68,7 @@ const Layout: React.FC<LayoutProps> = ({ children }) => {
     { name: '定时任务', href: '/scheduled-tasks', icon: Clock },
     { name: '文件管理', href: '/files', icon: FolderOpen },
     { name: '环境管理', href: '/environment', icon: Coffee },
-    // { name: '插件', href: '/plugins', icon: Puzzle },
+    { name: '插件', href: '/plugins', icon: Puzzle },
     { name: '设置', href: '/settings', icon: Settings },
     { name: '关于项目', href: '/about', icon: Info },
   ]
@@ -869,4 +870,4 @@ const Layout: React.FC<LayoutProps> = ({ children }) => {
   )
 }
 
-export default Layout
\ No newline at end of file
+export default Layout
diff --git a/client/src/pages/PluginsPage.tsx b/client/src/pages/PluginsPage.tsx
index bf36f22a..98ac72a0 100644
--- a/client/src/pages/PluginsPage.tsx
+++ b/client/src/pages/PluginsPage.tsx
@@ -502,13 +502,13 @@ const PluginsPage: React.FC = () => {
                   </div>
                 </div>
               </div>
-              <div className="flex items-center space-x-1">
-                {plugin.enabled ? (
-                  <div className="w-2 h-2 bg-green-500 rounded-full" title="已启用" />
-                ) : (
-                  <div className="w-2 h-2 bg-gray-400 rounded-full" title="已禁用" />
-                )}
-              </div>
+              <span className={`px-2 py-1 text-xs font-medium rounded-full ${
+                plugin.enabled
+                  ? 'bg-green-500/20 text-green-700 dark:text-green-300'
+                  : 'bg-gray-500/20 text-gray-600 dark:text-gray-300'
+              }`}>
+                {plugin.enabled ? '已启用' : '已禁用'}
+              </span>
             </div>
 
             {/* 插件信息 */}
@@ -534,10 +534,10 @@ const PluginsPage: React.FC = () => {
             <div className="flex items-center justify-between pt-4 border-t border-white/10 dark:border-gray-700/30">
               <div className="flex items-center space-x-2">
                 <motion.button
-                  whileHover={{ scale: 1.1 }}
-                  whileTap={{ scale: 0.9 }}
+                  whileHover={{ scale: 1.02 }}
+                  whileTap={{ scale: 0.98 }}
                   onClick={() => handleTogglePlugin(plugin)}
-                  className={`p-2 rounded-lg transition-colors ${
+                  className={`inline-flex items-center space-x-1.5 px-3 py-2 rounded-lg text-sm font-medium transition-colors ${
                     plugin.enabled
                       ? 'bg-green-500/20 text-green-600 hover:bg-green-500/30'
                       : 'bg-gray-500/20 text-gray-600 hover:bg-gray-500/30'
@@ -545,16 +545,23 @@ const PluginsPage: React.FC = () => {
                   title={plugin.enabled ? '禁用插件' : '启用插件'}
                 >
                   {plugin.enabled ? <Power className="w-4 h-4" /> : <PowerOff className="w-4 h-4" />}
+                  <span>{plugin.enabled ? '禁用' : '启用'}</span>
                 </motion.button>
-                {plugin.hasWebInterface && plugin.enabled && (
+                {plugin.hasWebInterface && (
                   <motion.button
-                    whileHover={{ scale: 1.1 }}
-                    whileTap={{ scale: 0.9 }}
+                    whileHover={{ scale: plugin.enabled ? 1.02 : 1 }}
+                    whileTap={{ scale: plugin.enabled ? 0.98 : 1 }}
                     onClick={() => handleOpenPlugin(plugin)}
-                    className="p-2 bg-blue-500/20 text-blue-600 rounded-lg hover:bg-blue-500/30 transition-colors"
-                    title="打开插件"
+                    disabled={!plugin.enabled}
+                    className={`inline-flex items-center space-x-1.5 px-3 py-2 rounded-lg text-sm font-medium transition-colors ${
+                      plugin.enabled
+                        ? 'bg-blue-500/20 text-blue-600 hover:bg-blue-500/30'
+                        : 'bg-gray-500/10 text-gray-400 cursor-not-allowed'
+                    }`}
+                    title={plugin.enabled ? '打开插件' : '启用后可打开插件'}
                   >
                     <ExternalLink className="w-4 h-4" />
+                    <span>打开</span>
                   </motion.button>
                 )}
               </div>
@@ -846,4 +853,4 @@ const PluginsPage: React.FC = () => {
   )
 }
 
-export default PluginsPage
\ No newline at end of file
+export default PluginsPage
diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index 4e8c6732..e424f1d2 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -39,6 +39,21 @@
 - EasyTier 模式生成 `tunnels/<name>/easytier-command.txt`，并创建使用命令行参数加入虚拟网络的独立实例。
 - 同步生成 `tunnels/<name>/manifest.json`，记录关联游戏实例、端口、协议、配置路径和连接地址。
 - 右侧预览会脱敏展示 `auth.token` 和 `--network-secret`。
+- 创建成功后会在插件内显示明确结果，并通过主面板通知提示用户到“实例管理”启动穿透实例。
+
+### 启用和禁用
+
+插件入口已加入侧边栏：
+
+1. 打开“插件”页面。
+2. 找到“内网穿透助手”。
+3. 点击卡片上的“启用”或“禁用”按钮。
+4. 启用后点击“打开”进入插件界面。
+
+### 已知排查点
+
+- 如果配置文件已经生成但界面没有明显变化，先到“实例管理”检查是否已经创建了 `穿透-<名称>` 实例。
+- Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要删除后重新创建或手动修正实例启动命令。
 
 ## 非目标
 
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
index 217f46dc..eff3d592 100644
--- a/server/data/plugins/tunnel-helper/index.html
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -437,10 +437,22 @@ <h2>生成结果</h2>
     ]
 
     const read = (id) => $(id).value.trim()
+    const selectedInstanceLooksWindows = () => {
+      const instance = getSelectedInstance()
+      const workingDirectory = String(instance && instance.workingDirectory || '')
+      const startCommand = String(instance && instance.startCommand || '')
+      return /^[a-z]:[\\/]/i.test(workingDirectory) ||
+        workingDirectory.includes('\\') ||
+        startCommand.includes('.\\') ||
+        /\.exe\b/i.test(startCommand)
+    }
+
     const isWindows = () => {
       const raw = state.systemInfo && state.systemInfo.rawPlatform
       const platform = state.systemInfo && state.systemInfo.platform
-      return raw === 'win32' || String(platform || '').toLowerCase().includes('windows')
+      return raw === 'win32' ||
+        String(platform || '').toLowerCase().includes('windows') ||
+        selectedInstanceLooksWindows()
     }
 
     function showMessage(type, text) {
@@ -463,6 +475,12 @@ <h2>生成结果</h2>
       return []
     }
 
+    function notify(type, message) {
+      if (window.gsm3 && typeof window.gsm3.showNotification === 'function') {
+        window.gsm3.showNotification(type, message)
+      }
+    }
+
     function sanitizeSlug(value) {
       return value
         .toLowerCase()
@@ -546,8 +564,11 @@ <h2>生成结果</h2>
       }
     }
 
-    async function loadInstances() {
-      clearMessage()
+    async function loadInstances(options = {}) {
+      const { showLoadedMessage = true, selectedInstanceId = read('instanceSelect') } = options
+      if (showLoadedMessage) {
+        clearMessage()
+      }
       $('instanceSelect').innerHTML = '<option value="">加载中...</option>'
       try {
         const result = await window.gsm3.getInstances()
@@ -568,11 +589,14 @@ <h2>生成结果</h2>
           const option = document.createElement('option')
           option.value = instance.id
           option.textContent = `${instance.name} (${instance.status || 'unknown'})`
+          option.selected = instance.id === selectedInstanceId
           $('instanceSelect').appendChild(option)
         }
 
         updateInstanceMeta()
-        showMessage('success', `已加载 ${gameInstances.length} 个游戏实例`)
+        if (showLoadedMessage) {
+          showMessage('success', `已加载 ${gameInstances.length} 个游戏实例`)
+        }
       } catch (error) {
         $('instanceSelect').innerHTML = '<option value="">加载失败</option>'
         showMessage('error', `获取实例列表失败：${error.message}`)
@@ -768,13 +792,23 @@ <h2>生成结果</h2>
       const plan = buildPlan(true)
       if (!plan) return
 
+      const tunnelName = `穿透-${plan.profile}`
+      const existingTunnel = state.instances.find(instance => instance.name === tunnelName)
+      if (existingTunnel) {
+        showMessage('warn', `已存在同名穿透实例：${tunnelName}，可到实例管理中启动或删除后重新创建`)
+        notify('warning', `已存在同名穿透实例：${tunnelName}`)
+        return
+      }
+
       $('createButton').disabled = true
+      const originalButtonText = $('createButton').textContent
+      $('createButton').textContent = '创建中...'
       try {
         await window.gsm3.writeFile(plan.configPath, plan.configContent, 'utf-8')
         await window.gsm3.writeFile(`${plan.dataDir}/manifest.json`, JSON.stringify(buildManifest(plan), null, 2), 'utf-8')
 
         const result = await window.gsm3.createInstance({
-          name: `穿透-${plan.profile}`,
+          name: tunnelName,
           description: plan.instanceDescription,
           workingDirectory: plan.workingDirectory,
           startCommand: plan.startCommand,
@@ -783,12 +817,16 @@ <h2>生成结果</h2>
         })
 
         const created = result.data || result
-        showMessage('success', `穿透实例已创建：${created.name || `穿透-${plan.profile}`}`)
-        await loadInstances()
+        await loadInstances({ showLoadedMessage: false, selectedInstanceId: plan.instance.id })
+        const createdName = created.name || tunnelName
+        showMessage('success', `穿透实例已创建：${createdName}。请到实例管理中启动该实例`)
+        notify('success', `穿透实例已创建：${createdName}`)
       } catch (error) {
         showMessage('error', `创建穿透实例失败：${error.message}`)
+        notify('error', `创建穿透实例失败：${error.message}`)
       } finally {
         $('createButton').disabled = false
+        $('createButton').textContent = originalButtonText
       }
     }
 
diff --git a/server/data/plugins/tunnel-helper/plugin.json b/server/data/plugins/tunnel-helper/plugin.json
index 66c849bc..8be95dab 100644
--- a/server/data/plugins/tunnel-helper/plugin.json
+++ b/server/data/plugins/tunnel-helper/plugin.json
@@ -4,10 +4,9 @@
   "description": "为任意游戏实例生成 frp 或 EasyTier 穿透配置，并创建独立的穿透实例。",
   "version": "0.1.0",
   "author": "GSM3 Community",
-  "enabled": false,
+  "enabled": true,
   "hasWebInterface": true,
   "entryPoint": "index.html",
   "icon": "network",
-  "category": "工具",
-  "keywords": ["内网穿透", "frp", "EasyTier", "游戏联机"]
-}
+  "category": "工具"
+}
\ No newline at end of file

From a34ec878ad3f8a9bd6f0faf27d21994b148d8657 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 13:45:25 +0800
Subject: [PATCH 07/10] feat: enhance configuration management with theme
 support and save options

---
 ...00\346\261\202\350\257\264\346\230\216.md" |  11 +-
 server/data/plugins/tunnel-helper/index.html  | 465 +++++++++++++++++-
 2 files changed, 466 insertions(+), 10 deletions(-)

diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index e424f1d2..991ea713 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -40,6 +40,9 @@
 - 同步生成 `tunnels/<name>/manifest.json`，记录关联游戏实例、端口、协议、配置路径和连接地址。
 - 右侧预览会脱敏展示 `auth.token` 和 `--network-secret`。
 - 创建成功后会在插件内显示明确结果，并通过主面板通知提示用户到“实例管理”启动穿透实例。
+- 支持“仅保存配置”和“保存并创建实例”两个动作，便于先保存或更新配置，再按需创建受管实例。
+- 打开插件后会读取 `server/data/tunnels/` 下已有配置，支持预览、载入表单和删除配置目录。
+- 插件页面会跟随主面板明暗主题，避免主 UI 为深色时插件 iframe 仍显示浅色页面。
 
 ### 启用和禁用
 
@@ -53,6 +56,8 @@
 ### 已知排查点
 
 - 如果配置文件已经生成但界面没有明显变化，先到“实例管理”检查是否已经创建了 `穿透-<名称>` 实例。
+- 如果只想更新已有配置，使用“仅保存配置”；“保存并创建实例”会在存在同名 `穿透-<名称>` 实例时阻止重复创建。
+- “删除配置”只删除 `server/data/tunnels/<名称>` 配置目录，不删除已经创建的穿透实例；实例仍需到“实例管理”中删除。
 - Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要删除后重新创建或手动修正实例启动命令。
 
 ## 非目标
@@ -108,10 +113,8 @@
 ## 后续实现计划
 
 1. 让插件从游戏部署清单或实例元数据中自动带出常见端口，减少手动输入。
-2. 增加“只生成配置”和“保存并创建实例”两个明确动作，便于只想拿配置文件的用户使用。
-3. 增加配置列表和更新能力，避免重复创建同名穿透实例。
-4. 如需服务端日志脱敏，补核心 API 层的敏感字段处理。
-5. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
+2. 如需服务端日志脱敏，补核心 API 层的敏感字段处理。
+3. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
 
 ## PR 拆分建议
 
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
index eff3d592..76391622 100644
--- a/server/data/plugins/tunnel-helper/index.html
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -22,6 +22,22 @@
       --code: #0f172a;
     }
 
+    :root[data-theme="dark"] {
+      color-scheme: dark;
+      --bg: #0f172a;
+      --panel: #111827;
+      --panel-soft: #1f2937;
+      --border: #334155;
+      --text: #e5e7eb;
+      --muted: #94a3b8;
+      --primary: #3b82f6;
+      --primary-strong: #60a5fa;
+      --success: #22c55e;
+      --danger: #f87171;
+      --warning: #facc15;
+      --code: #020617;
+    }
+
     @media (prefers-color-scheme: dark) {
       :root {
         --bg: #0f172a;
@@ -39,6 +55,22 @@
       }
     }
 
+    :root[data-theme="light"] {
+      color-scheme: light;
+      --bg: #f6f7f9;
+      --panel: #ffffff;
+      --panel-soft: #f1f5f9;
+      --border: #d8dee8;
+      --text: #162033;
+      --muted: #64748b;
+      --primary: #2563eb;
+      --primary-strong: #1d4ed8;
+      --success: #15803d;
+      --danger: #b91c1c;
+      --warning: #a16207;
+      --code: #0f172a;
+    }
+
     * {
       box-sizing: border-box;
     }
@@ -186,6 +218,11 @@
       border: 1px solid var(--border);
     }
 
+    button.danger {
+      background: var(--danger);
+      color: #fff;
+    }
+
     button:disabled {
       cursor: not-allowed;
       opacity: .55;
@@ -199,6 +236,10 @@
       background: var(--border);
     }
 
+    button.danger:hover:not(:disabled) {
+      background: color-mix(in srgb, var(--danger), #000 14%);
+    }
+
     .message {
       display: none;
       border-radius: 6px;
@@ -261,6 +302,55 @@
       font-weight: 600;
     }
 
+    .config-list {
+      display: grid;
+      gap: 10px;
+    }
+
+    .config-card {
+      display: grid;
+      gap: 8px;
+      padding: 12px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--panel);
+    }
+
+    .config-card.active {
+      border-color: var(--primary);
+      box-shadow: 0 0 0 2px rgb(37 99 235 / 14%);
+    }
+
+    .config-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+    }
+
+    .config-title {
+      min-width: 0;
+      font-weight: 700;
+      overflow-wrap: anywhere;
+    }
+
+    .config-actions {
+      display: flex;
+      gap: 8px;
+      flex-wrap: wrap;
+    }
+
+    .config-actions button {
+      padding: 6px 9px;
+      font-size: 12px;
+    }
+
+    .config-confirm {
+      color: var(--danger);
+      font-size: 12px;
+      font-weight: 600;
+    }
+
     .hidden {
       display: none !important;
     }
@@ -291,11 +381,12 @@
     <header>
       <div>
         <h1>内网穿透助手</h1>
-        <p>为现有游戏实例生成 frp 或 EasyTier 配置，并创建独立穿透实例。</p>
+        <p>为现有游戏实例生成和管理 frp / EasyTier 配置，可创建独立穿透实例。</p>
       </div>
       <div class="toolbar">
         <button class="secondary" id="refreshInstancesButton" type="button">刷新实例</button>
         <button class="secondary" id="previewButton" type="button">预览配置</button>
+        <button class="secondary" id="saveConfigButton" type="button">仅保存配置</button>
         <button id="createButton" type="button">保存并创建实例</button>
       </div>
     </header>
@@ -409,6 +500,23 @@ <h2>EasyTier 参数</h2>
       </section>
 
       <section class="panel stack">
+        <div class="config-head">
+          <h2>已有配置</h2>
+          <button class="secondary" id="refreshConfigsButton" type="button">刷新配置</button>
+        </div>
+        <div class="config-list" id="configList">
+          <p>正在加载配置...</p>
+        </div>
+
+        <h2>配置预览</h2>
+        <div class="meta" id="savedMeta">
+          <div class="meta-row"><strong>配置名称</strong><span id="savedName">-</span></div>
+          <div class="meta-row"><strong>工具</strong><span id="savedTool">-</span></div>
+          <div class="meta-row"><strong>关联实例</strong><span id="savedInstance">-</span></div>
+          <div class="meta-row"><strong>连接地址</strong><span id="savedAddress">-</span></div>
+        </div>
+        <pre id="savedPreview"></pre>
+
         <h2>生成结果</h2>
         <div class="meta" id="resultMeta">
           <div class="meta-row"><strong>配置目录</strong><span id="resultDir">-</span></div>
@@ -425,9 +533,15 @@ <h2>生成结果</h2>
       mode: 'frp',
       instances: [],
       systemInfo: null,
-      lastPlan: null
+      lastPlan: null,
+      savedConfigs: [],
+      selectedConfigPath: '',
+      pendingDeletePath: ''
     }
 
+    let themeSyncTimer = null
+    let themeObserver = null
+
     const $ = (id) => document.getElementById(id)
 
     const fields = [
@@ -481,6 +595,77 @@ <h2>生成结果</h2>
       }
     }
 
+    function applyPanelTheme() {
+      let theme = ''
+      try {
+        const storedTheme = window.parent && window.parent.localStorage
+          ? window.parent.localStorage.getItem('gsm3-theme')
+          : ''
+        if (storedTheme) {
+          const parsedTheme = JSON.parse(storedTheme)
+          theme = parsedTheme && parsedTheme.state && parsedTheme.state.theme
+        }
+
+        const parentRoot = window.parent && window.parent.document && window.parent.document.documentElement
+        if (!theme && parentRoot && parentRoot.classList.contains('dark')) {
+          theme = 'dark'
+        }
+      } catch {
+        // 无法访问父页面时回退到系统主题
+      }
+
+      if (!theme && window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+        theme = 'dark'
+      }
+
+      document.documentElement.dataset.theme = theme === 'dark' ? 'dark' : 'light'
+    }
+
+    function startThemeSync() {
+      applyPanelTheme()
+
+      try {
+        const parentRoot = window.parent && window.parent.document && window.parent.document.documentElement
+        if (parentRoot && !themeObserver) {
+          themeObserver = new MutationObserver(applyPanelTheme)
+          themeObserver.observe(parentRoot, { attributes: true, attributeFilter: ['class'] })
+        }
+      } catch {
+        // 父页面不可访问时由定时同步兜底
+      }
+
+      if (!themeSyncTimer) {
+        themeSyncTimer = window.setInterval(applyPanelTheme, 1000)
+      }
+    }
+
+    function dataExists(result) {
+      if (!result || result.success === false) return false
+      if (typeof result.exists === 'boolean') return result.exists
+      if (typeof result.data === 'boolean') return result.data
+      if (result.data && typeof result.data.exists === 'boolean') return result.data.exists
+      return true
+    }
+
+    function delay(ms) {
+      return new Promise(resolve => window.setTimeout(resolve, ms))
+    }
+
+    async function waitForPluginToken() {
+      if (!window.gsm3) return false
+
+      for (let i = 0; i < 30; i++) {
+        if (window.gsm3.token) return true
+        if (window.gsm3Token) {
+          window.gsm3.token = window.gsm3Token
+          return true
+        }
+        await delay(100)
+      }
+
+      return Boolean(window.gsm3.token)
+    }
+
     function sanitizeSlug(value) {
       return value
         .toLowerCase()
@@ -772,7 +957,9 @@ <h2>生成结果</h2>
       $('preview').textContent = redactSensitiveText(plan.configContent)
     }
 
-    function buildManifest(plan) {
+    function buildManifest(plan, existing = null) {
+      const now = new Date().toISOString()
+
       return {
         name: plan.profile,
         tool: plan.tool,
@@ -784,7 +971,267 @@ <h2>生成结果</h2>
         publicAddress: plan.publicAddress,
         workingDirectory: plan.workingDirectory,
         configPath: plan.configPath,
-        createdAt: new Date().toISOString()
+        createdAt: existing && existing.createdAt ? existing.createdAt : now,
+        updatedAt: now
+      }
+    }
+
+    async function writeTunnelFiles(plan) {
+      let existingManifest = null
+      try {
+        existingManifest = await readJsonFile(`${plan.dataDir}/manifest.json`)
+      } catch {
+        existingManifest = null
+      }
+
+      await window.gsm3.writeFile(plan.configPath, plan.configContent, 'utf-8')
+      await window.gsm3.writeFile(`${plan.dataDir}/manifest.json`, JSON.stringify(buildManifest(plan, existingManifest), null, 2), 'utf-8')
+    }
+
+    async function readJsonFile(filePath) {
+      const result = await window.gsm3.readFile(filePath, 'utf-8')
+      const content = result && result.data ? result.data.content : ''
+      return JSON.parse(content)
+    }
+
+    async function readTextFile(filePath) {
+      const result = await window.gsm3.readFile(filePath, 'utf-8')
+      return result && result.data ? result.data.content : ''
+    }
+
+    function setSavedPreview(config, content) {
+      $('savedName').textContent = config ? config.name || config.dirName || '-' : '-'
+      $('savedTool').textContent = config ? config.tool || '-' : '-'
+      $('savedInstance').textContent = config ? config.linkedInstanceName || '-' : '-'
+      $('savedAddress').textContent = config ? config.publicAddress || '-' : '-'
+      $('savedPreview').textContent = config
+        ? redactSensitiveText(content || '')
+        : ''
+    }
+
+    function textNode(tagName, className, text) {
+      const node = document.createElement(tagName)
+      if (className) node.className = className
+      node.textContent = text
+      return node
+    }
+
+    async function loadSavedConfigs() {
+      const list = $('configList')
+      list.innerHTML = '<p>正在加载配置...</p>'
+
+      try {
+        const exists = await window.gsm3.exists('tunnels')
+        if (!dataExists(exists)) {
+          state.savedConfigs = []
+          list.innerHTML = '<p>暂无已保存配置</p>'
+          setSavedPreview(null, '')
+          return
+        }
+
+        const result = await window.gsm3.listDirectory('tunnels')
+        const dirs = normalizeListResponse(result).filter(item => item.type === 'directory')
+        const configs = []
+
+        for (const dir of dirs) {
+          const manifestPath = `${dir.path}/manifest.json`
+          try {
+            const manifest = await readJsonFile(manifestPath)
+            configs.push({
+              ...manifest,
+              dirName: dir.name,
+              dirPath: dir.path,
+              manifestPath,
+              modified: dir.modified
+            })
+          } catch {
+            configs.push({
+              name: dir.name,
+              tool: 'unknown',
+              dirName: dir.name,
+              dirPath: dir.path,
+              manifestPath,
+              modified: dir.modified
+            })
+          }
+        }
+
+        state.savedConfigs = configs
+        renderSavedConfigs()
+      } catch (error) {
+        state.savedConfigs = []
+        list.innerHTML = ''
+        list.appendChild(textNode('p', '', `读取配置失败：${error.message}`))
+        setSavedPreview(null, '')
+      }
+    }
+
+    function renderSavedConfigs() {
+      const list = $('configList')
+      list.innerHTML = ''
+
+      if (state.savedConfigs.length === 0) {
+        list.innerHTML = '<p>暂无已保存配置</p>'
+        setSavedPreview(null, '')
+        return
+      }
+
+      for (const config of state.savedConfigs) {
+        const isPendingDelete = config.dirPath === state.pendingDeletePath
+        const card = document.createElement('div')
+        card.className = `config-card ${config.dirPath === state.selectedConfigPath ? 'active' : ''}`
+
+        const title = document.createElement('div')
+        title.className = 'config-head'
+        title.append(
+          textNode('div', 'config-title', config.name || config.dirName || '未命名配置'),
+          textNode('span', 'hint', config.tool || 'unknown')
+        )
+
+        const meta = document.createElement('div')
+        meta.className = 'hint'
+        meta.textContent = `${config.linkedInstanceName || '未关联实例'} · ${config.publicAddress || '未记录连接地址'}`
+
+        const actions = document.createElement('div')
+        actions.className = 'config-actions'
+
+        const previewButton = document.createElement('button')
+        previewButton.className = 'secondary'
+        previewButton.type = 'button'
+        previewButton.textContent = '预览'
+        previewButton.addEventListener('click', () => previewSavedConfig(config))
+
+        const loadButton = document.createElement('button')
+        loadButton.className = 'secondary'
+        loadButton.type = 'button'
+        loadButton.textContent = '载入表单'
+        loadButton.addEventListener('click', () => loadConfigIntoForm(config))
+
+        if (isPendingDelete) {
+          const confirmButton = document.createElement('button')
+          confirmButton.className = 'danger'
+          confirmButton.type = 'button'
+          confirmButton.textContent = '确认删除'
+          confirmButton.addEventListener('click', () => deleteSavedConfig(config))
+
+          const cancelButton = document.createElement('button')
+          cancelButton.className = 'secondary'
+          cancelButton.type = 'button'
+          cancelButton.textContent = '取消'
+          cancelButton.addEventListener('click', cancelDeleteConfig)
+
+          const confirmText = textNode('div', 'config-confirm', '只删除配置目录，不删除已创建的穿透实例。')
+          actions.append(confirmButton, cancelButton)
+          card.append(title, meta, confirmText, actions)
+          list.appendChild(card)
+          continue
+        }
+
+        const deleteButton = document.createElement('button')
+        deleteButton.className = 'secondary'
+        deleteButton.type = 'button'
+        deleteButton.textContent = '删除配置'
+        deleteButton.addEventListener('click', () => requestDeleteConfig(config))
+
+        actions.append(previewButton, loadButton, deleteButton)
+        card.append(title, meta, actions)
+        list.appendChild(card)
+      }
+    }
+
+    async function previewSavedConfig(config) {
+      try {
+        state.selectedConfigPath = config.dirPath
+        renderSavedConfigs()
+
+        const configPath = config.configPath || `${config.dirPath}/frpc.toml`
+        let content = ''
+        try {
+          content = await readTextFile(configPath)
+        } catch {
+          content = JSON.stringify(config, null, 2)
+        }
+
+        setSavedPreview(config, content)
+      } catch (error) {
+        showMessage('error', `预览配置失败：${error.message}`)
+      }
+    }
+
+    function loadConfigIntoForm(config) {
+      state.pendingDeletePath = ''
+      $('profileName').value = config.name || config.dirName || ''
+      $('localAddress').value = config.localAddress || '127.0.0.1'
+      $('localPort').value = config.localPort || ''
+      $('protocol').value = config.protocol || 'tcp'
+
+      if (String(config.tool || '').toLowerCase() === 'easytier') {
+        setMode('easytier')
+      } else {
+        setMode('frp')
+      }
+
+      buildPlan(false)
+      showMessage('success', `已载入配置：${config.name || config.dirName}`)
+    }
+
+    function requestDeleteConfig(config) {
+      state.pendingDeletePath = config.dirPath
+      renderSavedConfigs()
+      showMessage('warn', `确认删除配置：${config.name || config.dirName}`)
+    }
+
+    function cancelDeleteConfig() {
+      state.pendingDeletePath = ''
+      renderSavedConfigs()
+      clearMessage()
+    }
+
+    async function deleteSavedConfig(config) {
+      try {
+        await window.gsm3.deleteDirectory(config.dirPath, true)
+        if (state.selectedConfigPath === config.dirPath) {
+          state.selectedConfigPath = ''
+          setSavedPreview(null, '')
+        }
+        state.pendingDeletePath = ''
+        await loadSavedConfigs()
+        showMessage('success', `配置已删除：${config.name || config.dirName}`)
+        notify('success', `配置已删除：${config.name || config.dirName}`)
+      } catch (error) {
+        showMessage('error', `删除配置失败：${error.message}`)
+        notify('error', `删除配置失败：${error.message}`)
+      }
+    }
+
+    async function saveTunnelConfig() {
+      const plan = buildPlan(true)
+      if (!plan) return
+
+      $('saveConfigButton').disabled = true
+      const originalButtonText = $('saveConfigButton').textContent
+      $('saveConfigButton').textContent = '保存中...'
+
+      try {
+        state.pendingDeletePath = ''
+        await writeTunnelFiles(plan)
+        await loadSavedConfigs()
+
+        const saved = state.savedConfigs.find(config => config.dirPath === plan.dataDir)
+        if (saved) {
+          await previewSavedConfig(saved)
+        } else {
+          setSavedPreview(buildManifest(plan), plan.configContent)
+        }
+
+        showMessage('success', `配置已保存：${plan.profile}`)
+        notify('success', `配置已保存：${plan.profile}`)
+      } catch (error) {
+        showMessage('error', `保存配置失败：${error.message}`)
+        notify('error', `保存配置失败：${error.message}`)
+      } finally {
+        $('saveConfigButton').disabled = false
+        $('saveConfigButton').textContent = originalButtonText
       }
     }
 
@@ -804,8 +1251,7 @@ <h2>生成结果</h2>
       const originalButtonText = $('createButton').textContent
       $('createButton').textContent = '创建中...'
       try {
-        await window.gsm3.writeFile(plan.configPath, plan.configContent, 'utf-8')
-        await window.gsm3.writeFile(`${plan.dataDir}/manifest.json`, JSON.stringify(buildManifest(plan), null, 2), 'utf-8')
+        await writeTunnelFiles(plan)
 
         const result = await window.gsm3.createInstance({
           name: tunnelName,
@@ -821,6 +1267,7 @@ <h2>生成结果</h2>
         const createdName = created.name || tunnelName
         showMessage('success', `穿透实例已创建：${createdName}。请到实例管理中启动该实例`)
         notify('success', `穿透实例已创建：${createdName}`)
+        await loadSavedConfigs()
       } catch (error) {
         showMessage('error', `创建穿透实例失败：${error.message}`)
         notify('error', `创建穿透实例失败：${error.message}`)
@@ -832,7 +1279,9 @@ <h2>生成结果</h2>
 
     function attachEvents() {
       $('refreshInstancesButton').addEventListener('click', loadInstances)
+      $('refreshConfigsButton').addEventListener('click', loadSavedConfigs)
       $('previewButton').addEventListener('click', () => buildPlan(true))
+      $('saveConfigButton').addEventListener('click', saveTunnelConfig)
       $('createButton').addEventListener('click', createTunnelInstance)
       $('modeFrp').addEventListener('click', () => setMode('frp'))
       $('modeEasyTier').addEventListener('click', () => setMode('easytier'))
@@ -850,14 +1299,18 @@ <h2>生成结果</h2>
     }
 
     async function boot() {
+      startThemeSync()
+
       if (!window.gsm3) {
         showMessage('error', '插件 API 未加载')
         return
       }
 
       attachEvents()
+      await waitForPluginToken()
       await loadSystemInfo()
       await loadInstances()
+      await loadSavedConfigs()
       buildPlan(false)
     }
 

From 6aa6d29e22cfb6857d92bff76ea2a2a2f712961a Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 14:00:10 +0800
Subject: [PATCH 08/10] fix: add file path resolution and executable detection
 for improved instance management

---
 client/src/pages/InstanceManagerPage.tsx      |  29 +++-
 client/src/utils/api.ts                       |  10 ++
 ...00\346\261\202\350\257\264\346\230\216.md" |   6 +-
 server/data/plugins/tunnel-helper/gsm3-api.js |  14 +-
 server/data/plugins/tunnel-helper/index.html  | 156 +++++++++++++++++-
 server/src/routes/files.ts                    |  59 +++++++
 server/src/routes/pluginApi.ts                | 125 +++++++++++++-
 7 files changed, 384 insertions(+), 15 deletions(-)

diff --git a/client/src/pages/InstanceManagerPage.tsx b/client/src/pages/InstanceManagerPage.tsx
index b155a009..2f92197f 100644
--- a/client/src/pages/InstanceManagerPage.tsx
+++ b/client/src/pages/InstanceManagerPage.tsx
@@ -1031,13 +1031,26 @@ const InstanceManagerPage: React.FC = () => {
   }
 
   // 打开文件目录
-  const handleOpenDirectory = (instance: Instance) => {
-    navigate(`/files?path=${encodeURIComponent(instance.workingDirectory)}`)
-    addNotification({
-      type: 'success',
-      title: '跳转成功',
-      message: `已打开 "${instance.name}" 的工作目录`
-    })
+  const handleOpenDirectory = async (instance: Instance) => {
+    try {
+      const response = await apiClient.resolveFilePath(instance.workingDirectory)
+      const targetPath = response.data?.resolvedPath || instance.workingDirectory
+      navigate(`/files?path=${encodeURIComponent(targetPath)}`)
+      addNotification({
+        type: response.data?.exists === false ? 'warning' : 'success',
+        title: response.data?.exists === false ? '路径不存在' : '跳转成功',
+        message: response.data?.exists === false
+          ? `已跳转到解析后的路径，但目录不存在：${targetPath}`
+          : `已打开 "${instance.name}" 的工作目录`
+      })
+    } catch (error: any) {
+      navigate(`/files?path=${encodeURIComponent(instance.workingDirectory)}`)
+      addNotification({
+        type: 'warning',
+        title: '路径解析失败',
+        message: error.message || '已使用原始工作目录跳转'
+      })
+    }
   }
 
   // 重置表单
@@ -2513,4 +2526,4 @@ const InstanceManagerPage: React.FC = () => {
   )
 }
 
-export default InstanceManagerPage
\ No newline at end of file
+export default InstanceManagerPage
diff --git a/client/src/utils/api.ts b/client/src/utils/api.ts
index 10b00427..6436bbf0 100644
--- a/client/src/utils/api.ts
+++ b/client/src/utils/api.ts
@@ -421,6 +421,16 @@ class ApiClient {
     return this.get('/files', { params: { path } })
   }
 
+  async resolveFilePath(path: string) {
+    return this.get<{
+      originalPath: string
+      resolvedPath: string
+      isAbsolute: boolean
+      exists: boolean
+      type?: 'file' | 'directory'
+    }>('/files/resolve-path', { params: { path } })
+  }
+
   async uploadFile(file: File, path: string) {
     const formData = new FormData()
     formData.append('file', file)
diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index 991ea713..b18afe9e 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -35,7 +35,7 @@
 - `plugin.json` 默认 `enabled: false`，作为可选工具提供。
 - 复用示例插件的 `gsm3-api.js`。
 - `index.html` 提供 frp / EasyTier 两种模式。
-- frp 模式生成 `tunnels/<name>/frpc.toml`，并创建使用 `frpc -c frpc.toml` 的独立实例。
+- frp 模式生成 `tunnels/<name>/frpc.toml`，并创建带可执行文件预检的 `frpc -c frpc.toml` 独立实例。
 - EasyTier 模式生成 `tunnels/<name>/easytier-command.txt`，并创建使用命令行参数加入虚拟网络的独立实例。
 - 同步生成 `tunnels/<name>/manifest.json`，记录关联游戏实例、端口、协议、配置路径和连接地址。
 - 右侧预览会脱敏展示 `auth.token` 和 `--network-secret`。
@@ -43,6 +43,9 @@
 - 支持“仅保存配置”和“保存并创建实例”两个动作，便于先保存或更新配置，再按需创建受管实例。
 - 打开插件后会读取 `server/data/tunnels/` 下已有配置，支持预览、载入表单和删除配置目录。
 - 插件页面会跟随主面板明暗主题，避免主 UI 为深色时插件 iframe 仍显示浅色页面。
+- 插件不内置 frpc 或 EasyTier 二进制文件；可检测当前填写的可执行文件是否在本机可用。
+- 生成的穿透实例启动命令会先检查可执行文件，缺失时在终端输出明确提示后退出。
+- 实例管理的“文件”按钮会把相对工作目录解析为服务端绝对路径，避免 `data/tunnels/...` 被文件管理器当成系统根路径。
 
 ### 启用和禁用
 
@@ -58,6 +61,7 @@
 - 如果配置文件已经生成但界面没有明显变化，先到“实例管理”检查是否已经创建了 `穿透-<名称>` 实例。
 - 如果只想更新已有配置，使用“仅保存配置”；“保存并创建实例”会在存在同名 `穿透-<名称>` 实例时阻止重复创建。
 - “删除配置”只删除 `server/data/tunnels/<名称>` 配置目录，不删除已经创建的穿透实例；实例仍需到“实例管理”中删除。
+- 启动穿透实例前需要先安装对应客户端，或在插件里填写 `frpc.exe` / `easytier-core` 的绝对路径并点击“检测”确认。
 - Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要删除后重新创建或手动修正实例启动命令。
 
 ## 非目标
diff --git a/server/data/plugins/tunnel-helper/gsm3-api.js b/server/data/plugins/tunnel-helper/gsm3-api.js
index b1b88b88..9ea45613 100644
--- a/server/data/plugins/tunnel-helper/gsm3-api.js
+++ b/server/data/plugins/tunnel-helper/gsm3-api.js
@@ -458,6 +458,18 @@ class GSM3API {
     })
   }
 
+  /**
+   * 检测可执行文件是否存在
+   * @param {string} executable 可执行文件名或路径
+   * @param {string} workingDirectory 相对路径解析用工作目录，可选
+   */
+  async resolveExecutable(executable, workingDirectory = '') {
+    return await this.request('/tools/resolve-executable', {
+      method: 'POST',
+      body: { executable, workingDirectory }
+    })
+  }
+
   // ==================== 通用API ====================
 
   /**
@@ -604,4 +616,4 @@ document.addEventListener('DOMContentLoaded', () => {
       }, '*')
     }
   })
-})
\ No newline at end of file
+})
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
index 76391622..073409d1 100644
--- a/server/data/plugins/tunnel-helper/index.html
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -181,6 +181,34 @@
       font-weight: 400;
     }
 
+    .input-action {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 8px;
+    }
+
+    .input-action button {
+      min-width: 68px;
+    }
+
+    .help-link {
+      color: var(--primary);
+      text-decoration: none;
+      font-weight: 600;
+    }
+
+    .tool-status.ok {
+      color: var(--success);
+    }
+
+    .tool-status.warn {
+      color: var(--warning);
+    }
+
+    .tool-status.error {
+      color: var(--danger);
+    }
+
     .segmented {
       display: grid;
       grid-template-columns: repeat(2, minmax(0, 1fr));
@@ -443,7 +471,14 @@ <h2>穿透方式</h2>
           <h2>frp 参数</h2>
           <label>
             frpc 可执行文件
-            <input id="frpcPath" autocomplete="off" value="frpc" placeholder="frpc 或 C:\frp\frpc.exe">
+            <div class="input-action">
+              <input id="frpcPath" autocomplete="off" value="frpc" placeholder="frpc 或 C:\frp\frpc.exe">
+              <button class="secondary" id="checkFrpcButton" type="button">检测</button>
+            </div>
+            <span class="hint tool-status" id="frpcToolStatus">
+              需先在本机安装 frp 客户端，或填写 frpc.exe 绝对路径。
+              <a class="help-link" href="https://github.com/fatedier/frp/releases" target="_blank" rel="noreferrer">下载 frp</a>
+            </span>
           </label>
           <div class="grid">
             <label>
@@ -469,7 +504,14 @@ <h2>frp 参数</h2>
           <h2>EasyTier 参数</h2>
           <label>
             easytier-core 可执行文件
-            <input id="easyTierPath" autocomplete="off" value="easytier-core" placeholder="easytier-core 或 C:\EasyTier\easytier-core.exe">
+            <div class="input-action">
+              <input id="easyTierPath" autocomplete="off" value="easytier-core" placeholder="easytier-core 或 C:\EasyTier\easytier-core.exe">
+              <button class="secondary" id="checkEasyTierButton" type="button">检测</button>
+            </div>
+            <span class="hint tool-status" id="easyTierToolStatus">
+              需先在本机安装 EasyTier，或填写 easytier-core 绝对路径。
+              <a class="help-link" href="https://github.com/EasyTier/EasyTier/releases" target="_blank" rel="noreferrer">下载 EasyTier</a>
+            </span>
           </label>
           <div class="grid">
             <label>
@@ -595,6 +637,10 @@ <h2>生成结果</h2>
       }
     }
 
+    function getErrorMessage(error) {
+      return error && error.message ? error.message : String(error || '未知错误')
+    }
+
     function applyPanelTheme() {
       let theme = ''
       try {
@@ -701,6 +747,104 @@ <h2>生成结果</h2>
       return isWindows() ? `& ${quoted}` : quoted
     }
 
+    function executableLooksLikePath(executablePath) {
+      return /[\\/]/.test(executablePath) || /^[a-z]:/i.test(executablePath)
+    }
+
+    function executableMissingMessage(toolLabel, executablePath) {
+      return `未找到 ${toolLabel} 可执行文件：${executablePath}。请先安装客户端，或在插件中填写可执行文件绝对路径后重新保存实例。`
+    }
+
+    function buildExecutableCommand(executablePath, args, toolLabel) {
+      const command = `${commandPrefix(executablePath)} ${args.map(shellArg).join(' ')}`.trim()
+      const missingMessage = executableMissingMessage(toolLabel, executablePath)
+
+      if (isWindows()) {
+        const check = executableLooksLikePath(executablePath)
+          ? `Test-Path -LiteralPath ${psArg(executablePath)}`
+          : `Get-Command ${psArg(executablePath)} -ErrorAction SilentlyContinue`
+        return `if (${check}) { ${command} } else { Write-Error ${psArg(missingMessage)}; exit 1 }`
+      }
+
+      const check = executableLooksLikePath(executablePath)
+        ? `[ -x ${shArg(executablePath)} ]`
+        : `command -v ${shArg(executablePath)} >/dev/null 2>&1`
+      return `if ${check}; then ${command}; else echo ${shArg(missingMessage)} >&2; exit 1; fi`
+    }
+
+    function getToolDefinition(tool) {
+      if (tool === 'easytier') {
+        return {
+          inputId: 'easyTierPath',
+          statusId: 'easyTierToolStatus',
+          buttonId: 'checkEasyTierButton',
+          label: 'easytier-core'
+        }
+      }
+
+      return {
+        inputId: 'frpcPath',
+        statusId: 'frpcToolStatus',
+        buttonId: 'checkFrpcButton',
+        label: 'frpc'
+      }
+    }
+
+    function setToolStatus(tool, type, text) {
+      const definition = getToolDefinition(tool)
+      const status = $(definition.statusId)
+      status.className = `hint tool-status ${type || ''}`.trim()
+      status.textContent = text
+    }
+
+    async function checkToolAvailability(tool = state.mode, showPanelMessage = true) {
+      const definition = getToolDefinition(tool)
+      const executablePath = read(definition.inputId)
+      const button = $(definition.buttonId)
+
+      if (!executablePath) {
+        setToolStatus(tool, 'error', `请填写 ${definition.label} 可执行文件`)
+        return false
+      }
+
+      button.disabled = true
+      const originalText = button.textContent
+      button.textContent = '检测中...'
+
+      try {
+        const result = await window.gsm3.resolveExecutable(
+          executablePath,
+          state.lastPlan ? state.lastPlan.workingDirectory : ''
+        )
+        const data = result.data || result
+
+        if (data.found) {
+          setToolStatus(tool, 'ok', `已找到：${data.resolvedPath}`)
+          if (showPanelMessage) {
+            showMessage('success', `${definition.label} 可用`)
+          }
+          return true
+        }
+
+        const text = executableMissingMessage(definition.label, executablePath)
+        setToolStatus(tool, 'warn', text)
+        if (showPanelMessage) {
+          showMessage('warn', text)
+        }
+        return false
+      } catch (error) {
+        const text = `检测 ${definition.label} 失败：${getErrorMessage(error)}`
+        setToolStatus(tool, 'error', text)
+        if (showPanelMessage) {
+          showMessage('error', text)
+        }
+        return false
+      } finally {
+        button.disabled = false
+        button.textContent = originalText
+      }
+    }
+
     function parsePort(value, label) {
       const port = Number(value)
       if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -795,6 +939,7 @@ <h2>生成结果</h2>
       $('frpFields').classList.toggle('hidden', mode !== 'frp')
       $('easyTierFields').classList.toggle('hidden', mode !== 'easytier')
       buildPlan(false)
+      checkToolAvailability(mode, false)
     }
 
     function buildFrpPlan(common) {
@@ -829,7 +974,7 @@ <h2>生成结果</h2>
       )
 
       const configPath = `${common.dataDir}/frpc.toml`
-      const startCommand = `${commandPrefix(frpcPath)} -c ${shellArg('frpc.toml')}`
+      const startCommand = buildExecutableCommand(frpcPath, ['-c', 'frpc.toml'], 'frpc')
       const publicAddress = `${serverAddr}:${remotePort}`
 
       return {
@@ -876,7 +1021,7 @@ <h2>生成结果</h2>
         args.push('-p', peer)
       }
 
-      const startCommand = `${commandPrefix(executablePath)} ${args.map(shellArg).join(' ')}`
+      const startCommand = buildExecutableCommand(executablePath, args, 'easytier-core')
       const publicAddress = virtualIpv4
         ? `${virtualIpv4}:${common.localPort}`
         : `EasyTier 虚拟 IP:${common.localPort}`
@@ -1283,6 +1428,8 @@ <h2>生成结果</h2>
       $('previewButton').addEventListener('click', () => buildPlan(true))
       $('saveConfigButton').addEventListener('click', saveTunnelConfig)
       $('createButton').addEventListener('click', createTunnelInstance)
+      $('checkFrpcButton').addEventListener('click', () => checkToolAvailability('frp'))
+      $('checkEasyTierButton').addEventListener('click', () => checkToolAvailability('easytier'))
       $('modeFrp').addEventListener('click', () => setMode('frp'))
       $('modeEasyTier').addEventListener('click', () => setMode('easytier'))
       $('instanceSelect').addEventListener('change', () => {
@@ -1312,6 +1459,7 @@ <h2>生成结果</h2>
       await loadInstances()
       await loadSavedConfigs()
       buildPlan(false)
+      checkToolAvailability(state.mode, false)
     }
 
     boot()
diff --git a/server/src/routes/files.ts b/server/src/routes/files.ts
index 6efb7390..f52d260c 100644
--- a/server/src/routes/files.ts
+++ b/server/src/routes/files.ts
@@ -156,6 +156,13 @@ const fixWindowsPath = (filePath: string): string => {
   return decodedPath
 }
 
+const resolveFilesystemPath = (filePath: string): string => {
+  const fixedPath = fixWindowsPath(filePath)
+  return path.isAbsolute(fixedPath)
+    ? fixedPath
+    : path.resolve(process.cwd(), fixedPath)
+}
+
 type BomEncoding = 'utf-8' | 'utf-16le' | 'utf-16be' | null
 
 const normalizeTextEncoding = (encoding?: string | null): string => {
@@ -301,6 +308,58 @@ const prependEncodingBom = (buffer: Buffer, encoding: string, bomEncoding: BomEn
   return buffer
 }
 
+// 将实例工作目录等相对路径解析为文件管理器可打开的绝对路径
+router.get('/resolve-path', authenticateToken, async (req: Request, res: Response) => {
+  try {
+    const { path: rawPath } = req.query
+
+    if (!rawPath || typeof rawPath !== 'string') {
+      return res.status(400).json({
+        success: false,
+        message: '缺少路径参数'
+      })
+    }
+
+    if (rawPath.includes('\0')) {
+      return res.status(400).json({
+        success: false,
+        message: '无效的路径'
+      })
+    }
+
+    const fixedPath = fixWindowsPath(rawPath)
+    const resolvedPath = resolveFilesystemPath(rawPath)
+    let exists = false
+    let type: 'file' | 'directory' | undefined
+
+    try {
+      const stats = await fs.stat(resolvedPath)
+      exists = true
+      type = stats.isDirectory() ? 'directory' : 'file'
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        throw error
+      }
+    }
+
+    res.json({
+      success: true,
+      data: {
+        originalPath: rawPath,
+        resolvedPath,
+        isAbsolute: path.isAbsolute(fixedPath),
+        exists,
+        type
+      }
+    })
+  } catch (error: any) {
+    res.status(500).json({
+      success: false,
+      message: error.message || '路径解析失败'
+    })
+  }
+})
+
 // 获取目录列表
 router.get('/list', authenticateToken, async (req: Request, res: Response) => {
   try {
diff --git a/server/src/routes/pluginApi.ts b/server/src/routes/pluginApi.ts
index 03eab01d..74f6d333 100644
--- a/server/src/routes/pluginApi.ts
+++ b/server/src/routes/pluginApi.ts
@@ -1,4 +1,7 @@
 import { Router, Request, Response } from 'express'
+import fs from 'fs/promises'
+import { constants as fsConstants } from 'fs'
+import path from 'path'
 import { authenticateToken } from '../middleware/auth.js'
 import type { InstanceManager } from '../modules/instance/InstanceManager.js'
 import type { SystemManager } from '../modules/system/SystemManager.js'
@@ -16,6 +19,83 @@ let systemManager: SystemManager
 let terminalManager: TerminalManager
 let gameManager: GameManager
 
+const stripShellQuotes = (value: string): string => {
+  const trimmed = value.trim()
+  if (trimmed.length >= 2) {
+    const first = trimmed[0]
+    const last = trimmed[trimmed.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1)
+    }
+  }
+
+  return trimmed
+}
+
+const looksLikePath = (value: string): boolean => {
+  return value.includes('/') || value.includes('\\') || /^[A-Za-z]:/.test(value)
+}
+
+const getWindowsExecutableExtensions = (): string[] => {
+  const pathext = process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD'
+  return pathext
+    .split(';')
+    .map(ext => ext.trim())
+    .filter(Boolean)
+}
+
+const getExecutableCandidates = (executable: string, workingDirectory?: string): string[] => {
+  const command = stripShellQuotes(executable)
+  if (!command) return []
+
+  const candidates = new Set<string>()
+  const accessNames = process.platform === 'win32' && !path.extname(command)
+    ? [command, ...getWindowsExecutableExtensions().map(ext => `${command}${ext}`)]
+    : [command]
+
+  if (looksLikePath(command)) {
+    const baseDirectory = workingDirectory
+      ? path.resolve(stripShellQuotes(workingDirectory))
+      : process.cwd()
+
+    for (const accessName of accessNames) {
+      candidates.add(path.isAbsolute(accessName)
+        ? accessName
+        : path.resolve(baseDirectory, accessName))
+    }
+
+    return Array.from(candidates)
+  }
+
+  const pathEntries = (process.env.PATH || '')
+    .split(path.delimiter)
+    .map(entry => entry.trim())
+    .filter(Boolean)
+
+  for (const entry of pathEntries) {
+    for (const accessName of accessNames) {
+      candidates.add(path.join(entry, accessName))
+    }
+  }
+
+  return Array.from(candidates)
+}
+
+const findExecutable = async (executable: string, workingDirectory?: string): Promise<string | null> => {
+  const mode = process.platform === 'win32' ? fsConstants.F_OK : fsConstants.X_OK
+
+  for (const candidate of getExecutableCandidates(executable, workingDirectory)) {
+    try {
+      await fs.access(candidate, mode)
+      return candidate
+    } catch {
+      // 继续检查下一个候选路径
+    }
+  }
+
+  return null
+}
+
 export function setPluginApiDependencies(
   instManager: InstanceManager,
   sysManager: SystemManager,
@@ -576,6 +656,49 @@ router.get('/games', async (req: Request, res: Response) => {
   }
 })
 
+// ==================== 工具检测API ====================
+
+router.post('/tools/resolve-executable', async (req: Request, res: Response) => {
+  try {
+    const { executable, workingDirectory } = req.body || {}
+
+    if (!executable || typeof executable !== 'string') {
+      return res.status(400).json({
+        success: false,
+        message: '缺少可执行文件参数'
+      })
+    }
+
+    if (executable.includes('\0') || (typeof workingDirectory === 'string' && workingDirectory.includes('\0'))) {
+      return res.status(400).json({
+        success: false,
+        message: '无效的路径参数'
+      })
+    }
+
+    const resolvedPath = await findExecutable(
+      executable,
+      typeof workingDirectory === 'string' ? workingDirectory : undefined
+    )
+
+    res.json({
+      success: true,
+      data: {
+        executable: stripShellQuotes(executable),
+        found: Boolean(resolvedPath),
+        resolvedPath
+      }
+    })
+  } catch (error) {
+    logger.error('插件检测可执行文件失败:', error)
+    res.status(500).json({
+      success: false,
+      message: '检测可执行文件失败',
+      error: error instanceof Error ? error.message : '未知错误'
+    })
+  }
+})
+
 // ==================== 文件操作API ====================
 
 // 转发文件操作请求到files路由
@@ -608,4 +731,4 @@ router.get('/health', (req: Request, res: Response) => {
   })
 })
 
-export default router
\ No newline at end of file
+export default router

From 8149f3c07bcfc2c6f4366973f2b373a0dcc61488 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 14:30:00 +0800
Subject: [PATCH 09/10] feat: add download/update functionality for tunnel
 tools with automatic path resolution

---
 .gitignore                                    |   2 +
 ...00\346\261\202\350\257\264\346\230\216.md" |   6 +-
 server/data/plugins/tunnel-helper/gsm3-api.js |  16 +
 server/data/plugins/tunnel-helper/index.html  | 144 +++-
 server/src/routes/pluginApi.ts                | 623 +++++++++++++++++-
 5 files changed, 784 insertions(+), 7 deletions(-)

diff --git a/.gitignore b/.gitignore
index 37f90c32..053a7248 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,9 +30,11 @@ server/data/environment
 server/data/wallpapers/
 server/data/lib/
 server/data/tunnels/
+server/data/tools/
 data/wallpapers/
 data/lib/
 data/tunnels/
+data/tools/
 
 
 dist/
diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index b18afe9e..df601122 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -44,6 +44,7 @@
 - 打开插件后会读取 `server/data/tunnels/` 下已有配置，支持预览、载入表单和删除配置目录。
 - 插件页面会跟随主面板明暗主题，避免主 UI 为深色时插件 iframe 仍显示浅色页面。
 - 插件不内置 frpc 或 EasyTier 二进制文件；可检测当前填写的可执行文件是否在本机可用。
+- 插件提供“下载/更新”动作，从官方 GitHub Release 自动选择当前平台资产，优先通过 `releases/latest` 跳转和 `expanded_assets` 页面获取版本与资产列表，GitHub API 仅作为兜底；下载后保存到 `server/data/tools/tunnel-helper/`，并把解压后的可执行文件路径回填到表单。
 - 生成的穿透实例启动命令会先检查可执行文件，缺失时在终端输出明确提示后退出。
 - 实例管理的“文件”按钮会把相对工作目录解析为服务端绝对路径，避免 `data/tunnels/...` 被文件管理器当成系统根路径。
 
@@ -61,7 +62,8 @@
 - 如果配置文件已经生成但界面没有明显变化，先到“实例管理”检查是否已经创建了 `穿透-<名称>` 实例。
 - 如果只想更新已有配置，使用“仅保存配置”；“保存并创建实例”会在存在同名 `穿透-<名称>` 实例时阻止重复创建。
 - “删除配置”只删除 `server/data/tunnels/<名称>` 配置目录，不删除已经创建的穿透实例；实例仍需到“实例管理”中删除。
-- 启动穿透实例前需要先安装对应客户端，或在插件里填写 `frpc.exe` / `easytier-core` 的绝对路径并点击“检测”确认。
+- 启动穿透实例前需要先安装对应客户端；可以点击“下载/更新”，也可以填写 `frpc.exe` / `easytier-core` 的绝对路径并点击“检测”确认。
+- 下载/更新完成后，插件会回填可执行文件路径；已有穿透实例的旧启动命令不会自动变更，需要重新保存配置或删除后重新创建实例。
 - Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要删除后重新创建或手动修正实例启动命令。
 
 ## 非目标
@@ -118,7 +120,7 @@
 
 1. 让插件从游戏部署清单或实例元数据中自动带出常见端口，减少手动输入。
 2. 如需服务端日志脱敏，补核心 API 层的敏感字段处理。
-3. 再评估一键下载：确认工具版本、平台包、哈希校验和更新策略后，再考虑下载器和工具管理 API。
+3. 增加镜像源、代理或手动下载 URL，降低 GitHub API 限流和网络不可达对一键下载的影响。
 
 ## PR 拆分建议
 
diff --git a/server/data/plugins/tunnel-helper/gsm3-api.js b/server/data/plugins/tunnel-helper/gsm3-api.js
index 9ea45613..0d0e43d9 100644
--- a/server/data/plugins/tunnel-helper/gsm3-api.js
+++ b/server/data/plugins/tunnel-helper/gsm3-api.js
@@ -470,6 +470,22 @@ class GSM3API {
     })
   }
 
+  /**
+   * 下载并安装穿透工具，返回SSE响应流
+   * @param {'frp'|'easytier'} tool 工具名称
+   */
+  async installTunnelTool(tool) {
+    return await fetch(`${this.baseURL}/tools/install-tunnel-tool`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Plugin-Request': 'true',
+        ...(this.token && { 'Authorization': `Bearer ${this.token}` })
+      },
+      body: JSON.stringify({ tool })
+    })
+  }
+
   // ==================== 通用API ====================
 
   /**
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
index 073409d1..2a61f073 100644
--- a/server/data/plugins/tunnel-helper/index.html
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -183,7 +183,7 @@
 
     .input-action {
       display: grid;
-      grid-template-columns: minmax(0, 1fr) auto;
+      grid-template-columns: minmax(0, 1fr) auto auto;
       gap: 8px;
     }
 
@@ -474,6 +474,7 @@ <h2>frp 参数</h2>
             <div class="input-action">
               <input id="frpcPath" autocomplete="off" value="frpc" placeholder="frpc 或 C:\frp\frpc.exe">
               <button class="secondary" id="checkFrpcButton" type="button">检测</button>
+              <button class="secondary" id="installFrpcButton" type="button">下载/更新</button>
             </div>
             <span class="hint tool-status" id="frpcToolStatus">
               需先在本机安装 frp 客户端，或填写 frpc.exe 绝对路径。
@@ -507,6 +508,7 @@ <h2>EasyTier 参数</h2>
             <div class="input-action">
               <input id="easyTierPath" autocomplete="off" value="easytier-core" placeholder="easytier-core 或 C:\EasyTier\easytier-core.exe">
               <button class="secondary" id="checkEasyTierButton" type="button">检测</button>
+              <button class="secondary" id="installEasyTierButton" type="button">下载/更新</button>
             </div>
             <span class="hint tool-status" id="easyTierToolStatus">
               需先在本机安装 EasyTier，或填写 easytier-core 绝对路径。
@@ -578,7 +580,8 @@ <h2>生成结果</h2>
       lastPlan: null,
       savedConfigs: [],
       selectedConfigPath: '',
-      pendingDeletePath: ''
+      pendingDeletePath: '',
+      installingTool: ''
     }
 
     let themeSyncTimer = null
@@ -778,6 +781,7 @@ <h2>生成结果</h2>
           inputId: 'easyTierPath',
           statusId: 'easyTierToolStatus',
           buttonId: 'checkEasyTierButton',
+          installButtonId: 'installEasyTierButton',
           label: 'easytier-core'
         }
       }
@@ -786,6 +790,7 @@ <h2>生成结果</h2>
         inputId: 'frpcPath',
         statusId: 'frpcToolStatus',
         buttonId: 'checkFrpcButton',
+        installButtonId: 'installFrpcButton',
         label: 'frpc'
       }
     }
@@ -797,6 +802,12 @@ <h2>生成结果</h2>
       status.textContent = text
     }
 
+    function setToolButtonsDisabled(tool, disabled) {
+      const definition = getToolDefinition(tool)
+      $(definition.buttonId).disabled = disabled
+      $(definition.installButtonId).disabled = disabled
+    }
+
     async function checkToolAvailability(tool = state.mode, showPanelMessage = true) {
       const definition = getToolDefinition(tool)
       const executablePath = read(definition.inputId)
@@ -807,7 +818,7 @@ <h2>生成结果</h2>
         return false
       }
 
-      button.disabled = true
+      setToolButtonsDisabled(tool, true)
       const originalText = button.textContent
       button.textContent = '检测中...'
 
@@ -840,11 +851,134 @@ <h2>生成结果</h2>
         }
         return false
       } finally {
-        button.disabled = false
+        setToolButtonsDisabled(tool, false)
         button.textContent = originalText
       }
     }
 
+    function parseSseBlock(block) {
+      const event = { event: 'message', data: '' }
+      const dataLines = []
+
+      for (const rawLine of block.split(/\r?\n/)) {
+        const line = rawLine.trimEnd()
+        if (line.startsWith('event:')) {
+          event.event = line.slice('event:'.length).trim()
+        } else if (line.startsWith('data:')) {
+          dataLines.push(line.slice('data:'.length).trimStart())
+        }
+      }
+
+      event.data = dataLines.join('\n')
+      return event
+    }
+
+    async function installTool(tool) {
+      const definition = getToolDefinition(tool)
+      if (state.installingTool) return
+
+      await waitForPluginToken()
+
+      state.installingTool = tool
+      setToolButtonsDisabled(tool, true)
+      const installButton = $(definition.installButtonId)
+      const originalText = installButton.textContent
+      installButton.textContent = '安装中...'
+      setToolStatus(tool, 'warn', `正在准备下载 ${definition.label}...`)
+      clearMessage()
+
+      try {
+        const response = await window.gsm3.installTunnelTool(tool)
+        if (!response.ok) {
+          let errorText = `HTTP ${response.status}`
+          try {
+            const data = await response.json()
+            errorText = data.message || data.error || errorText
+          } catch {
+            // SSE 前的错误可能不是 JSON
+          }
+          throw new Error(errorText)
+        }
+
+        const reader = response.body && response.body.getReader()
+        if (!reader) {
+          throw new Error('无法读取下载进度')
+        }
+
+        const decoder = new TextDecoder()
+        let buffer = ''
+        let installError = null
+
+        const handleEvent = (block) => {
+          if (!block.trim()) return
+          const sse = parseSseBlock(block)
+          let data = {}
+          try {
+            data = sse.data ? JSON.parse(sse.data) : {}
+          } catch {
+            data = { message: sse.data }
+          }
+
+          if (sse.event === 'status') {
+            setToolStatus(tool, 'warn', data.status || '正在安装...')
+            return
+          }
+
+          if (sse.event === 'progress') {
+            const progress = typeof data.progress === 'number' ? data.progress : 0
+            setToolStatus(tool, 'warn', `正在安装 ${definition.label}... ${progress}%`)
+            return
+          }
+
+          if (sse.event === 'complete') {
+            const result = data.data || {}
+            if (result.executablePath) {
+              $(definition.inputId).value = result.executablePath
+            }
+            setToolStatus(tool, 'ok', `已安装 ${definition.label} ${result.version || ''}：${result.executablePath || ''}`.trim())
+            showMessage('success', `${definition.label} 安装完成，已填入可执行文件路径。请重新保存配置或重建穿透实例`)
+            notify('success', `${definition.label} 安装完成`)
+            buildPlan(false)
+            return
+          }
+
+          if (sse.event === 'error') {
+            const message = data.error || data.message || `${definition.label} 安装失败`
+            installError = new Error(message)
+          }
+        }
+
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+
+          buffer += decoder.decode(value, { stream: true })
+          const blocks = buffer.split(/\r?\n\r?\n/)
+          buffer = blocks.pop() || ''
+          for (const block of blocks) {
+            handleEvent(block)
+          }
+        }
+
+        if (buffer.trim()) {
+          handleEvent(buffer)
+        }
+
+        if (installError) {
+          throw installError
+        }
+      } catch (error) {
+        const message = `${definition.label} 安装失败：${getErrorMessage(error)}`
+        setToolStatus(tool, 'error', message)
+        showMessage('error', message)
+        notify('error', message)
+      } finally {
+        state.installingTool = ''
+        setToolButtonsDisabled(tool, false)
+        installButton.textContent = originalText
+      }
+    }
+
     function parsePort(value, label) {
       const port = Number(value)
       if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -1430,6 +1564,8 @@ <h2>生成结果</h2>
       $('createButton').addEventListener('click', createTunnelInstance)
       $('checkFrpcButton').addEventListener('click', () => checkToolAvailability('frp'))
       $('checkEasyTierButton').addEventListener('click', () => checkToolAvailability('easytier'))
+      $('installFrpcButton').addEventListener('click', () => installTool('frp'))
+      $('installEasyTierButton').addEventListener('click', () => installTool('easytier'))
       $('modeFrp').addEventListener('click', () => setMode('frp'))
       $('modeEasyTier').addEventListener('click', () => setMode('easytier'))
       $('instanceSelect').addEventListener('change', () => {
diff --git a/server/src/routes/pluginApi.ts b/server/src/routes/pluginApi.ts
index 74f6d333..9e30edfb 100644
--- a/server/src/routes/pluginApi.ts
+++ b/server/src/routes/pluginApi.ts
@@ -1,7 +1,10 @@
 import { Router, Request, Response } from 'express'
 import fs from 'fs/promises'
-import { constants as fsConstants } from 'fs'
+import { constants as fsConstants, createReadStream, createWriteStream } from 'fs'
+import https from 'https'
 import path from 'path'
+import * as tar from 'tar'
+import crypto from 'crypto'
 import { authenticateToken } from '../middleware/auth.js'
 import type { InstanceManager } from '../modules/instance/InstanceManager.js'
 import type { SystemManager } from '../modules/system/SystemManager.js'
@@ -10,6 +13,8 @@ import type { GameManager } from '../modules/game/GameManager.js'
 import filesRouter from './files.js'
 import { setupTerminalRoutes } from './terminal.js'
 import logger from '../utils/logger.js'
+import { createTarSecurityFilter } from '../utils/tarSecurityFilter.js'
+import { zipToolsManager } from '../utils/zipToolsManager.js'
 
 const router = Router()
 
@@ -19,6 +24,64 @@ let systemManager: SystemManager
 let terminalManager: TerminalManager
 let gameManager: GameManager
 
+type TunnelToolName = 'frp' | 'easytier'
+
+interface GitHubReleaseAsset {
+  name: string
+  browser_download_url: string
+  size?: number
+  digest?: string
+}
+
+interface GitHubRelease {
+  tag_name: string
+  html_url: string
+  assets: GitHubReleaseAsset[]
+}
+
+interface TunnelToolDefinition {
+  name: TunnelToolName
+  label: string
+  repo: string
+  executableNames: string[]
+}
+
+interface TunnelToolInstallResult {
+  tool: TunnelToolName
+  version: string
+  assetName: string
+  installPath: string
+  executablePath: string
+  releaseUrl: string
+}
+
+const TUNNEL_TOOL_DEFINITIONS: Record<TunnelToolName, TunnelToolDefinition> = {
+  frp: {
+    name: 'frp',
+    label: 'frp',
+    repo: 'fatedier/frp',
+    executableNames: process.platform === 'win32' ? ['frpc.exe'] : ['frpc']
+  },
+  easytier: {
+    name: 'easytier',
+    label: 'EasyTier',
+    repo: 'EasyTier/EasyTier',
+    executableNames: process.platform === 'win32' ? ['easytier-core.exe'] : ['easytier-core']
+  }
+}
+
+const getTunnelToolDefinition = (tool: string): TunnelToolDefinition => {
+  if (tool === 'frp' || tool === 'easytier') {
+    return TUNNEL_TOOL_DEFINITIONS[tool]
+  }
+
+  throw new Error(`不支持的工具: ${tool}`)
+}
+
+const getErrorMessage = (error: unknown): string => {
+  return error instanceof Error ? error.message : String(error)
+}
+
 const stripShellQuotes = (value: string): string => {
   const trimmed = value.trim()
   if (trimmed.length >= 2) {
@@ -96,6 +159,512 @@ const findExecutable = async (executable: string, workingDirectory?: string): Pr
   return null
 }
 
+const getPlatformAliases = (): string[] => {
+  switch (process.platform) {
+    case 'win32':
+      return ['windows', 'win32', 'win']
+    case 'linux':
+      return ['linux']
+    case 'darwin':
+      return ['darwin', 'macos', 'mac']
+    case 'freebsd':
+      return ['freebsd']
+    default:
+      return [process.platform]
+  }
+}
+
+const getFrpArchAliases = (): string[] => {
+  switch (process.arch) {
+    case 'x64':
+      return ['amd64', 'x86_64', 'x64']
+    case 'arm64':
+      return ['arm64', 'aarch64']
+    case 'arm':
+      return ['arm', 'arm_hf']
+    default:
+      return [process.arch]
+  }
+}
+
+const getEasyTierArchAliases = (): string[] => {
+  switch (process.arch) {
+    case 'x64':
+      return ['x86_64', 'amd64', 'x64']
+    case 'arm64':
+      return ['aarch64', 'arm64']
+    case 'arm':
+      return ['armv7', 'arm']
+    default:
+      return [process.arch]
+  }
+}
+
+const isSupportedArchive = (assetName: string): boolean => {
+  const name = assetName.toLowerCase()
+  return name.endsWith('.zip') || name.endsWith('.tar.gz') || name.endsWith('.tgz')
+}
+
+const scoreAsset = (tool: TunnelToolName, asset: GitHubReleaseAsset): number => {
+  const name = asset.name.toLowerCase()
+  if (!isSupportedArchive(name)) return -1
+
+  const platformAliases = getPlatformAliases()
+  const archAliases = tool === 'frp' ? getFrpArchAliases() : getEasyTierArchAliases()
+  const hasPlatform = platformAliases.some(alias => name.includes(alias))
+  const hasArch = archAliases.some(alias => name.includes(alias))
+  if (!hasPlatform || !hasArch) return -1
+
+  let score = 100
+  if (tool === 'frp') {
+    if (!name.startsWith('frp_')) return -1
+    if (name.includes('android')) return -1
+    if (name.includes(`_${platformAliases[0]}_${archAliases[0]}`)) score += 20
+  } else {
+    if (!name.startsWith('easytier-')) return -1
+    if (name.includes('gui') || name.includes('app-') || name.endsWith('.apk')) return -1
+    if (name.endsWith('.rpm') || name.endsWith('.dmg') || name.endsWith('.appimage')) return -1
+    if (name.includes(`${platformAliases[0]}-${archAliases[0]}`)) score += 20
+  }
+
+  if (name.endsWith('.zip')) score += process.platform === 'win32' ? 8 : 2
+  if (name.endsWith('.tar.gz') || name.endsWith('.tgz')) score += process.platform === 'win32' ? 2 : 8
+
+  return score
+}
+
+const selectTunnelToolAsset = (tool: TunnelToolName, release: GitHubRelease): GitHubReleaseAsset => {
+  const candidates = release.assets
+    .map(asset => ({ asset, score: scoreAsset(tool, asset) }))
+    .filter(item => item.score >= 0)
+    .sort((a, b) => b.score - a.score)
+
+  if (candidates.length === 0) {
+    throw new Error(`未找到适用于 ${process.platform}/${process.arch} 的 ${tool} release 资产`)
+  }
+
+  return candidates[0].asset
+}
+
+const safeVersionSegment = (version: string): string => {
+  return version.replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+const getTunnelToolsRoot = (): string => {
+  return path.resolve(process.cwd(), 'data', 'tools', 'tunnel-helper')
+}
+
+const assertInsideDirectory = (targetPath: string, rootPath: string): void => {
+  const resolvedTarget = path.resolve(targetPath)
+  const resolvedRoot = path.resolve(rootPath)
+  const relative = path.relative(resolvedRoot, resolvedTarget)
+
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`路径超出允许范围: ${targetPath}`)
+  }
+}
+
+const requestJson = async <T>(url: string): Promise<T> => {
+  return new Promise((resolve, reject) => {
+    https.get(url, {
+      headers: {
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'GameServerManager-TunnelHelper'
+      }
+    }, response => {
+      let body = ''
+
+      response.on('data', chunk => {
+        body += chunk
+      })
+
+      response.on('end', () => {
+        if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+          try {
+            const parsed = JSON.parse(body)
+            reject(new Error(parsed.message || `HTTP ${response.statusCode}`))
+          } catch {
+            reject(new Error(`HTTP ${response.statusCode}`))
+          }
+          return
+        }
+
+        try {
+          resolve(JSON.parse(body) as T)
+        } catch (error) {
+          reject(error)
+        }
+      })
+    }).on('error', reject)
+  })
+}
+
+const requestHeaders = async (url: string): Promise<{
+  statusCode?: number
+  headers: Record<string, string | string[] | undefined>
+}> => {
+  return new Promise((resolve, reject) => {
+    const request = https.request(url, {
+      method: 'HEAD',
+      headers: { 'User-Agent': 'GameServerManager-TunnelHelper' }
+    }, response => {
+      response.resume()
+      resolve({
+        statusCode: response.statusCode,
+        headers: response.headers as Record<string, string | string[] | undefined>
+      })
+    })
+
+    request.on('error', reject)
+    request.end()
+  })
+}
+
+const requestText = async (url: string, redirectCount = 0): Promise<string> => {
+  if (redirectCount > 5) {
+    throw new Error('请求重定向次数过多')
+  }
+
+  return new Promise((resolve, reject) => {
+    https.get(url, {
+      headers: { 'User-Agent': 'GameServerManager-TunnelHelper' }
+    }, response => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume()
+        requestText(new URL(response.headers.location, url).toString(), redirectCount + 1)
+          .then(resolve)
+          .catch(reject)
+        return
+      }
+
+      if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+        response.resume()
+        reject(new Error(`HTTP ${response.statusCode || 'unknown'}`))
+        return
+      }
+
+      response.setEncoding('utf8')
+      let body = ''
+      response.on('data', chunk => {
+        body += chunk
+      })
+      response.on('end', () => resolve(body))
+    }).on('error', reject)
+  })
+}
+
+const decodeHtmlEntities = (value: string): string => {
+  return value
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+}
+
+const extractTagFromReleaseLocation = (location: string): string | null => {
+  const match = location.match(/\/releases\/tag\/([^/?#]+)/)
+  return match ? decodeURIComponent(match[1]) : null
+}
+
+const fetchLatestReleaseTagWithoutApi = async (repo: string): Promise<string> => {
+  const latestUrl = `https://github.com/${repo}/releases/latest`
+  const response = await requestHeaders(latestUrl)
+  const locationHeader = response.headers.location
+  const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader
+
+  if (location) {
+    const tag = extractTagFromReleaseLocation(location)
+    if (tag) return tag
+  }
+
+  throw new Error(`无法从 ${latestUrl} 的跳转响应中获取最新版本`)
+}
+
+const extractReleaseAssetsFromHtml = (repo: string, html: string): GitHubReleaseAsset[] => {
+  const assets: GitHubReleaseAsset[] = []
+  const seen = new Set<string>()
+  const expectedPathPrefix = `/${repo.toLowerCase()}/releases/download/`
+  const hrefRegex = /href="([^"]*\/releases\/download\/[^"]+)"/g
+  let match: RegExpExecArray | null
+
+  while ((match = hrefRegex.exec(html)) !== null) {
+    const href = decodeHtmlEntities(match[1])
+    let assetUrl: URL
+
+    try {
+      assetUrl = new URL(href, 'https://github.com')
+    } catch {
+      continue
+    }
+
+    if (assetUrl.hostname !== 'github.com') continue
+    if (!assetUrl.pathname.toLowerCase().startsWith(expectedPathPrefix)) continue
+
+    const encodedName = assetUrl.pathname.split('/').pop()
+    if (!encodedName) continue
+
+    const name = decodeURIComponent(encodedName)
+    if (seen.has(name)) continue
+
+    const assetHtml = html.slice(match.index, match.index + 3000)
+    const digestMatch = assetHtml.match(/value="(sha256:[a-fA-F0-9]{64})"/)
+
+    seen.add(name)
+    assets.push({
+      name,
+      browser_download_url: assetUrl.toString(),
+      digest: digestMatch ? digestMatch[1].toLowerCase() : undefined
+    })
+  }
+
+  return assets
+}
+
+const fetchTunnelToolReleaseWithoutApi = async (definition: TunnelToolDefinition): Promise<GitHubRelease> => {
+  const tag = await fetchLatestReleaseTagWithoutApi(definition.repo)
+  const expandedAssetsUrl = `https://github.com/${definition.repo}/releases/expanded_assets/${encodeURIComponent(tag)}`
+  const assetsHtml = await requestText(expandedAssetsUrl)
+  const assets = extractReleaseAssetsFromHtml(definition.repo, assetsHtml)
+
+  if (assets.length === 0) {
+    throw new Error(`未能从 GitHub Release 页面读取 ${definition.label} 资产列表`)
+  }
+
+  return {
+    tag_name: tag,
+    html_url: `https://github.com/${definition.repo}/releases/tag/${encodeURIComponent(tag)}`,
+    assets
+  }
+}
+
+const fetchTunnelToolReleaseWithApi = async (definition: TunnelToolDefinition): Promise<GitHubRelease> => {
+  return requestJson<GitHubRelease>(`https://api.github.com/repos/${definition.repo}/releases/latest`)
+}
+
+const fetchLatestTunnelToolRelease = async (definition: TunnelToolDefinition): Promise<GitHubRelease> => {
+  try {
+    return await fetchTunnelToolReleaseWithoutApi(definition)
+  } catch (webError) {
+    logger.warn(`插件通过 GitHub 页面获取 ${definition.label} 最新版本失败，尝试 GitHub API:`, webError)
+
+    try {
+      return await fetchTunnelToolReleaseWithApi(definition)
+    } catch (apiError) {
+      throw new Error(
+        `获取 ${definition.label} 最新版本失败: 页面方式失败: ${getErrorMessage(webError)}; GitHub API 失败: ${getErrorMessage(apiError)}`
+      )
+    }
+  }
+}
+
+const downloadFile = async (
+  url: string,
+  targetPath: string,
+  onProgress?: (progress: number) => void,
+  redirectCount = 0
+): Promise<void> => {
+  if (redirectCount > 5) {
+    throw new Error('下载重定向次数过多')
+  }
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true })
+
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, {
+      headers: { 'User-Agent': 'GameServerManager-TunnelHelper' }
+    }, response => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume()
+        downloadFile(new URL(response.headers.location, url).toString(), targetPath, onProgress, redirectCount + 1)
+          .then(resolve)
+          .catch(reject)
+        return
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume()
+        reject(new Error(`下载失败: HTTP ${response.statusCode}`))
+        return
+      }
+
+      const totalSize = Number(response.headers['content-length'] || 0)
+      let downloadedSize = 0
+      const file = createWriteStream(targetPath)
+
+      response.on('data', chunk => {
+        downloadedSize += chunk.length
+        if (totalSize > 0) {
+          onProgress?.(Math.round((downloadedSize / totalSize) * 100))
+        }
+      })
+
+      response.pipe(file)
+
+      file.on('finish', () => {
+        file.close()
+        resolve()
+      })
+
+      file.on('error', error => {
+        fs.rm(targetPath, { force: true }).catch(() => { })
+        reject(error)
+      })
+    })
+
+    request.on('error', error => {
+      fs.rm(targetPath, { force: true }).catch(() => { })
+      reject(error)
+    })
+  })
+}
+
+const calculateSha256 = async (filePath: string): Promise<string> => {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256')
+    const stream = createReadStream(filePath)
+
+    stream.on('data', chunk => hash.update(chunk))
+    stream.on('end', () => resolve(hash.digest('hex')))
+    stream.on('error', reject)
+  })
+}
+
+const verifyDownloadedAsset = async (asset: GitHubReleaseAsset, archivePath: string): Promise<void> => {
+  const stats = await fs.stat(archivePath)
+  if (stats.size <= 0) {
+    throw new Error('下载的文件为空')
+  }
+
+  if (asset.digest && asset.digest.startsWith('sha256:')) {
+    const expected = asset.digest.slice('sha256:'.length).toLowerCase()
+    const actual = await calculateSha256(archivePath)
+    if (actual !== expected) {
+      throw new Error(`SHA256 校验失败: expected=${expected}, actual=${actual}`)
+    }
+  }
+}
+
+const extractTunnelToolArchive = async (archivePath: string, targetPath: string): Promise<void> => {
+  const lowerArchivePath = archivePath.toLowerCase()
+  if (lowerArchivePath.endsWith('.zip')) {
+    await zipToolsManager.extractZip(archivePath, targetPath)
+    return
+  }
+
+  if (lowerArchivePath.endsWith('.tar.gz') || lowerArchivePath.endsWith('.tgz')) {
+    await tar.extract({
+      file: archivePath,
+      cwd: targetPath,
+      filter: createTarSecurityFilter({ cwd: targetPath })
+    } as any)
+    return
+  }
+
+  throw new Error(`不支持的压缩包格式: ${path.basename(archivePath)}`)
+}
+
+const findExtractedExecutable = async (rootPath: string, executableNames: string[]): Promise<string | null> => {
+  const queue = [rootPath]
+  const expectedNames = new Set(executableNames.map(name => name.toLowerCase()))
+
+  while (queue.length > 0) {
+    const currentPath = queue.shift()!
+    const entries = await fs.readdir(currentPath, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const entryPath = path.join(currentPath, entry.name)
+      if (entry.isDirectory()) {
+        queue.push(entryPath)
+        continue
+      }
+
+      if (entry.isFile() && expectedNames.has(entry.name.toLowerCase())) {
+        if (process.platform !== 'win32') {
+          await fs.chmod(entryPath, 0o755).catch(() => { })
+        }
+        return entryPath
+      }
+    }
+  }
+
+  return null
+}
+
+const installTunnelTool = async (
+  tool: TunnelToolName,
+  onProgress: (progress: number) => void,
+  onStatusChange: (status: string) => void
+): Promise<TunnelToolInstallResult> => {
+  const definition = getTunnelToolDefinition(tool)
+  const toolsRoot = getTunnelToolsRoot()
+
+  onStatusChange(`正在获取 ${definition.label} 最新版本信息...`)
+  const release = await fetchLatestTunnelToolRelease(definition)
+  const asset = selectTunnelToolAsset(tool, release)
+
+  const version = safeVersionSegment(release.tag_name)
+  const toolRoot = path.join(toolsRoot, definition.name)
+  const installPath = path.join(toolRoot, version)
+  const downloadPath = path.join(toolRoot, 'downloads', asset.name)
+  const stagingPath = path.join(toolRoot, `.staging-${version}-${Date.now()}`)
+
+  assertInsideDirectory(toolRoot, toolsRoot)
+  assertInsideDirectory(installPath, toolsRoot)
+  assertInsideDirectory(downloadPath, toolsRoot)
+  assertInsideDirectory(stagingPath, toolsRoot)
+
+  try {
+    await fs.mkdir(path.dirname(downloadPath), { recursive: true })
+
+    onStatusChange(`正在下载 ${asset.name}...`)
+    await downloadFile(asset.browser_download_url, downloadPath, progress => {
+      onProgress(Math.min(70, Math.round(progress * 0.7)))
+    })
+
+    onStatusChange('正在校验下载文件...')
+    await verifyDownloadedAsset(asset, downloadPath)
+
+    await fs.rm(stagingPath, { recursive: true, force: true })
+    await fs.mkdir(stagingPath, { recursive: true })
+
+    onStatusChange('正在解压文件...')
+    await extractTunnelToolArchive(downloadPath, stagingPath)
+    onProgress(90)
+
+    const executablePath = await findExtractedExecutable(stagingPath, definition.executableNames)
+    if (!executablePath) {
+      throw new Error(`安装验证失败：未找到 ${definition.executableNames.join(' 或 ')}`)
+    }
+
+    await fs.rm(installPath, { recursive: true, force: true })
+    await fs.rename(stagingPath, installPath)
+    await fs.rm(downloadPath, { force: true }).catch(() => { })
+
+    const finalExecutablePath = path.join(installPath, path.relative(stagingPath, executablePath))
+    const resolvedExecutable = await findExecutable(finalExecutablePath)
+    if (!resolvedExecutable) {
+      throw new Error(`安装验证失败：${finalExecutablePath} 不可访问`)
+    }
+
+    onProgress(100)
+    onStatusChange('安装完成')
+
+    return {
+      tool,
+      version: release.tag_name,
+      assetName: asset.name,
+      installPath,
+      executablePath: finalExecutablePath,
+      releaseUrl: release.html_url
+    }
+  } catch (error) {
+    await fs.rm(stagingPath, { recursive: true, force: true }).catch(() => { })
+    await fs.rm(downloadPath, { force: true }).catch(() => { })
+    throw error
+  }
+}
+
 export function setPluginApiDependencies(
   instManager: InstanceManager,
   sysManager: SystemManager,
@@ -699,6 +1268,58 @@ router.post('/tools/resolve-executable', async (req: Request, res: Response) =>
   }
 })
 
+router.post('/tools/install-tunnel-tool', async (req: Request, res: Response) => {
+  const { tool } = req.body || {}
+
+  try {
+    const definition = getTunnelToolDefinition(String(tool || ''))
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': process.env.CORS_ORIGIN || '*',
+      'Access-Control-Allow-Headers': 'Cache-Control'
+    })
+
+    const sendEvent = (event: string, data: any) => {
+      res.write(`event: ${event}\n`)
+      res.write(`data: ${JSON.stringify(data)}\n\n`)
+    }
+
+    try {
+      const result = await installTunnelTool(
+        definition.name,
+        progress => sendEvent('progress', { progress }),
+        status => sendEvent('status', { status })
+      )
+
+      sendEvent('complete', {
+        success: true,
+        message: `${definition.label} 安装完成`,
+        data: result
+      })
+      res.end()
+    } catch (error) {
+      logger.error(`插件安装 ${definition.label} 失败:`, error)
+      sendEvent('error', {
+        success: false,
+        message: `${definition.label} 安装失败`,
+        error: error instanceof Error ? error.message : '未知错误'
+      })
+      res.end()
+    }
+  } catch (error) {
+    logger.error('插件安装穿透工具请求失败:', error)
+    if (!res.headersSent) {
+      res.status(400).json({
+        success: false,
+        message: error instanceof Error ? error.message : '安装请求无效'
+      })
+    }
+  }
+})
+
 // ==================== 文件操作API ====================
 
 // 转发文件操作请求到files路由

From 0e1a722a02dc86126d284ee47f1c23d6d1badc48 Mon Sep 17 00:00:00 2001
From: xiwangly2 <xiwangly2@gmail.com>
Date: Wed, 29 Jul 2026 14:40:13 +0800
Subject: [PATCH 10/10] fix: add data path resolution and update instance
 creation logic for tunnel tools

---
 ...00\346\261\202\350\257\264\346\230\216.md" |  8 ++--
 server/data/plugins/tunnel-helper/gsm3-api.js | 11 +++++
 server/data/plugins/tunnel-helper/index.html  | 38 +++++++++------
 .../src/modules/terminal/TerminalManager.ts   |  4 +-
 server/src/routes/pluginApi.ts                | 46 +++++++++++++++++++
 5 files changed, 88 insertions(+), 19 deletions(-)

diff --git "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md" "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
index df601122..61137d3f 100644
--- "a/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
+++ "b/docs/\345\206\205\347\275\221\347\251\277\351\200\217\346\217\222\344\273\266\351\234\200\346\261\202\350\257\264\346\230\216.md"
@@ -45,7 +45,9 @@
 - 插件页面会跟随主面板明暗主题，避免主 UI 为深色时插件 iframe 仍显示浅色页面。
 - 插件不内置 frpc 或 EasyTier 二进制文件；可检测当前填写的可执行文件是否在本机可用。
 - 插件提供“下载/更新”动作，从官方 GitHub Release 自动选择当前平台资产，优先通过 `releases/latest` 跳转和 `expanded_assets` 页面获取版本与资产列表，GitHub API 仅作为兜底；下载后保存到 `server/data/tools/tunnel-helper/`，并把解压后的可执行文件路径回填到表单。
-- 生成的穿透实例启动命令会先检查可执行文件，缺失时在终端输出明确提示后退出。
+- 生成的穿透实例启动命令会先检查可执行文件，缺失时在终端输出明确提示并保留终端窗口。
+- 生成的穿透实例使用解析后的绝对工作目录，避免不同启动 cwd 下 `data/tunnels/...` 指向错误位置。
+- “保存并创建实例”遇到同名穿透实例时会更新该实例的工作目录和启动命令，而不是阻止操作。
 - 实例管理的“文件”按钮会把相对工作目录解析为服务端绝对路径，避免 `data/tunnels/...` 被文件管理器当成系统根路径。
 
 ### 启用和禁用
@@ -60,11 +62,11 @@
 ### 已知排查点
 
 - 如果配置文件已经生成但界面没有明显变化，先到“实例管理”检查是否已经创建了 `穿透-<名称>` 实例。
-- 如果只想更新已有配置，使用“仅保存配置”；“保存并创建实例”会在存在同名 `穿透-<名称>` 实例时阻止重复创建。
+- 如果只想更新已有配置，使用“仅保存配置”；“保存并创建实例”会在存在同名 `穿透-<名称>` 实例时更新该实例。
 - “删除配置”只删除 `server/data/tunnels/<名称>` 配置目录，不删除已经创建的穿透实例；实例仍需到“实例管理”中删除。
 - 启动穿透实例前需要先安装对应客户端；可以点击“下载/更新”，也可以填写 `frpc.exe` / `easytier-core` 的绝对路径并点击“检测”确认。
 - 下载/更新完成后，插件会回填可执行文件路径；已有穿透实例的旧启动命令不会自动变更，需要重新保存配置或删除后重新创建实例。
-- Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要删除后重新创建或手动修正实例启动命令。
+- Windows 下启动命令应当带 PowerShell 调用运算符，例如 `& 'frpc' -c 'frpc.toml'`；工具缺失时只输出错误，不关闭终端，便于查看失败原因。旧版本插件生成的 `'frpc' -c 'frpc.toml'` 不会执行，需要重新保存并创建/更新实例，或手动修正实例启动命令。
 
 ## 非目标
 
diff --git a/server/data/plugins/tunnel-helper/gsm3-api.js b/server/data/plugins/tunnel-helper/gsm3-api.js
index 0d0e43d9..9564d5cc 100644
--- a/server/data/plugins/tunnel-helper/gsm3-api.js
+++ b/server/data/plugins/tunnel-helper/gsm3-api.js
@@ -470,6 +470,17 @@ class GSM3API {
     })
   }
 
+  /**
+   * 将相对服务器data目录的路径解析为绝对路径
+   * @param {string} dataPath 相对服务器data目录的路径
+   */
+  async resolveDataPath(dataPath) {
+    return await this.request('/tools/resolve-data-path', {
+      method: 'POST',
+      body: { dataPath }
+    })
+  }
+
   /**
    * 下载并安装穿透工具，返回SSE响应流
    * @param {'frp'|'easytier'} tool 工具名称
diff --git a/server/data/plugins/tunnel-helper/index.html b/server/data/plugins/tunnel-helper/index.html
index 2a61f073..78b15374 100644
--- a/server/data/plugins/tunnel-helper/index.html
+++ b/server/data/plugins/tunnel-helper/index.html
@@ -766,13 +766,13 @@ <h2>生成结果</h2>
         const check = executableLooksLikePath(executablePath)
           ? `Test-Path -LiteralPath ${psArg(executablePath)}`
           : `Get-Command ${psArg(executablePath)} -ErrorAction SilentlyContinue`
-        return `if (${check}) { ${command} } else { Write-Error ${psArg(missingMessage)}; exit 1 }`
+        return `if (${check}) { ${command} } else { Write-Error ${psArg(missingMessage)} }`
       }
 
       const check = executableLooksLikePath(executablePath)
         ? `[ -x ${shArg(executablePath)} ]`
         : `command -v ${shArg(executablePath)} >/dev/null 2>&1`
-      return `if ${check}; then ${command}; else echo ${shArg(missingMessage)} >&2; exit 1; fi`
+      return `if ${check}; then ${command}; else echo ${shArg(missingMessage)} >&2; false; fi`
     }
 
     function getToolDefinition(tool) {
@@ -1267,6 +1267,13 @@ <h2>生成结果</h2>
       await window.gsm3.writeFile(`${plan.dataDir}/manifest.json`, JSON.stringify(buildManifest(plan, existingManifest), null, 2), 'utf-8')
     }
 
+    async function resolveTunnelWorkingDirectory(plan) {
+      const result = await window.gsm3.resolveDataPath(plan.dataDir)
+      return result && result.data && result.data.absolutePath
+        ? result.data.absolutePath
+        : plan.workingDirectory
+    }
+
     async function readJsonFile(filePath) {
       const result = await window.gsm3.readFile(filePath, 'utf-8')
       const content = result && result.data ? result.data.content : ''
@@ -1520,36 +1527,37 @@ <h2>生成结果</h2>
 
       const tunnelName = `穿透-${plan.profile}`
       const existingTunnel = state.instances.find(instance => instance.name === tunnelName)
-      if (existingTunnel) {
-        showMessage('warn', `已存在同名穿透实例：${tunnelName}，可到实例管理中启动或删除后重新创建`)
-        notify('warning', `已存在同名穿透实例：${tunnelName}`)
-        return
-      }
 
       $('createButton').disabled = true
       const originalButtonText = $('createButton').textContent
-      $('createButton').textContent = '创建中...'
+      $('createButton').textContent = existingTunnel ? '更新中...' : '创建中...'
       try {
         await writeTunnelFiles(plan)
+        const workingDirectory = await resolveTunnelWorkingDirectory(plan)
 
-        const result = await window.gsm3.createInstance({
+        const instancePayload = {
           name: tunnelName,
           description: plan.instanceDescription,
-          workingDirectory: plan.workingDirectory,
+          workingDirectory,
           startCommand: plan.startCommand,
           stopCommand: 'ctrl+c',
           autoStart: false
-        })
+        }
+
+        const result = existingTunnel
+          ? await window.gsm3.updateInstance(existingTunnel.id, instancePayload)
+          : await window.gsm3.createInstance(instancePayload)
 
         const created = result.data || result
         await loadInstances({ showLoadedMessage: false, selectedInstanceId: plan.instance.id })
         const createdName = created.name || tunnelName
-        showMessage('success', `穿透实例已创建：${createdName}。请到实例管理中启动该实例`)
-        notify('success', `穿透实例已创建：${createdName}`)
+        const actionText = existingTunnel ? '已更新' : '已创建'
+        showMessage('success', `穿透实例${actionText}：${createdName}。请到实例管理中启动该实例`)
+        notify('success', `穿透实例${actionText}：${createdName}`)
         await loadSavedConfigs()
       } catch (error) {
-        showMessage('error', `创建穿透实例失败：${error.message}`)
-        notify('error', `创建穿透实例失败：${error.message}`)
+        showMessage('error', `保存穿透实例失败：${error.message}`)
+        notify('error', `保存穿透实例失败：${error.message}`)
       } finally {
         $('createButton').disabled = false
         $('createButton').textContent = originalButtonText
diff --git a/server/src/modules/terminal/TerminalManager.ts b/server/src/modules/terminal/TerminalManager.ts
index 8a154600..4c189155 100755
--- a/server/src/modules/terminal/TerminalManager.ts
+++ b/server/src/modules/terminal/TerminalManager.ts
@@ -117,7 +117,8 @@ export class TerminalManager {
    */
   public async createPty(socket: Socket, data: CreatePtyData): Promise<void> {
     try {
-      const { sessionId, name, cols, rows, workingDirectory = process.cwd(), enableStreamForward = false, programPath, autoCloseOnForwardExit = false, terminalUser } = data
+      const { sessionId, name, cols, rows, workingDirectory: rawWorkingDirectory = process.cwd(), enableStreamForward = false, programPath, autoCloseOnForwardExit = false, terminalUser } = data
+      const workingDirectory = path.resolve(rawWorkingDirectory)
       const sessionName = name || `终端会话 ${sessionId.slice(-8)}`
 
        // 获取终端配置和默认用户（提升到方法开始处）
@@ -1516,6 +1517,7 @@ export class TerminalManager {
    */
   private async createPtyFallback(sessionId: string, sessionName: string, workingDirectory: string, socket: Socket, enableStreamForward?: boolean, programPath?: string, autoCloseOnForwardExit?: boolean): Promise<void> {
     try {
+      workingDirectory = path.resolve(workingDirectory)
       this.logger.info(`使用当前用户创建PTY回退会话: ${sessionId}`)
       
       // 构建PTY命令参数，使用当前用户
diff --git a/server/src/routes/pluginApi.ts b/server/src/routes/pluginApi.ts
index 9e30edfb..15d8423e 100644
--- a/server/src/routes/pluginApi.ts
+++ b/server/src/routes/pluginApi.ts
@@ -254,6 +254,10 @@ const getTunnelToolsRoot = (): string => {
   return path.resolve(process.cwd(), 'data', 'tools', 'tunnel-helper')
 }
 
+const getPluginDataRoot = (): string => {
+  return path.resolve(process.cwd(), 'data')
+}
+
 const assertInsideDirectory = (targetPath: string, rootPath: string): void => {
   const resolvedTarget = path.resolve(targetPath)
   const resolvedRoot = path.resolve(rootPath)
@@ -264,6 +268,25 @@ const assertInsideDirectory = (targetPath: string, rootPath: string): void => {
   }
 }
 
+const resolvePluginDataPath = (dataPath: string): string => {
+  if (!dataPath || typeof dataPath !== 'string') {
+    throw new Error('缺少 dataPath')
+  }
+
+  if (dataPath.includes('\0')) {
+    throw new Error('无效的路径')
+  }
+
+  if (path.isAbsolute(dataPath)) {
+    throw new Error('dataPath 必须是相对 data 目录的路径')
+  }
+
+  const dataRoot = getPluginDataRoot()
+  const resolvedPath = path.resolve(dataRoot, dataPath)
+  assertInsideDirectory(resolvedPath, dataRoot)
+  return resolvedPath
+}
+
 const requestJson = async <T>(url: string): Promise<T> => {
   return new Promise((resolve, reject) => {
     https.get(url, {
@@ -1268,6 +1291,29 @@ router.post('/tools/resolve-executable', async (req: Request, res: Response) =>
   }
 })
 
+router.post('/tools/resolve-data-path', async (req: Request, res: Response) => {
+  const { dataPath } = req.body || {}
+
+  try {
+    const absolutePath = resolvePluginDataPath(String(dataPath || ''))
+
+    res.json({
+      success: true,
+      data: {
+        dataPath,
+        absolutePath
+      }
+    })
+  } catch (error) {
+    logger.error('插件解析 data 路径失败:', error)
+    res.status(400).json({
+      success: false,
+      message: '解析 data 路径失败',
+      error: error instanceof Error ? error.message : '未知错误'
+    })
+  }
+})
+
 router.post('/tools/install-tunnel-tool', async (req: Request, res: Response) => {
   const { tool } = req.body || {}