dsh-remote-panel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# dsh-remote-panel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让**手机/平板**安全地打开你这台机器上的 DeepSeek Harness —— 同一份会话、同一批工具、同一台机器。
+
+这个包只做**控制面**：部署向导、状态面板、一键配对。
+真正转发流量的 Caddy 与组网的 EasyTier 是独立进程，插件不监听任何端口。
+
+---
+
+## 快速开始（5 分钟）
+
+```bash
+dsh plugin --profile web add dsh-remote-panel
+```
+
+1. 重启 DSH，打开 **设置 → 远程访问**。
+2. 填三个字段：中继地址、网络名、网络密钥（其余用默认值）。
+3. 点「生成部署脚本」，复制整块任务，交给目标机器的 AI 执行。
+4. 脚本最后会打印 `DSH_REMOTE_OK ...`，贴回面板。
+5. 面板出二维码：手机先扫**门禁**，再扫**令牌**，然后直接开地址。
+
+之后手机重开浏览器无需再登录：门禁 Cookie 一年，DSH Cookie 30 天。
+
+---
+
+## 架构
+
+```
+手机 / 平板 ──EasyTier── 10.x.x.x:8710 ──► Caddy ──► 127.0.0.1:3080 (DSH)
+                             │  来源白名单 + 口令门禁        │  只监听回环，不对外
+                             └  用户级服务，无 root          └  通过 --trusted-host 接受该 authority
+```
+
+三个部件、一条边界：
+
+| 部件 | 职责 | 权限 |
+|---|---|---|
+| **Caddy**（用户级 systemd） | 白名单、口令门禁、转发、WS、压缩 | 无 root |
+| **EasyTier**（system systemd） | 虚拟组网，唯一需要 TUN 的部件 | root |
+| **本插件** | 检测、生成脚本、配对、状态 | 与应用同权限 |
+
+### 为什么不做成一个插件
+
+- EasyTier 要建 TUN、改路由，**必须** root，进不了用户态插件。
+- 插件生命周期等于应用生命周期 —— 而你在应用崩了/重启时**最需要**远程访问。
+- 若把反代也塞进进程，就得自己实现 TLS/WS/门禁，等于把成熟的 Caddy 换成几百行自研代码。
+
+---
+
+## 安全模型
+
+三层，从外到内：
+
+1. **虚拟网**：只有入网设备可达。
+2. **来源白名单**：Caddyfile 里的 `@lan remote_ip`，其余一律 `403 source not allowed`。
+3. **口令门禁**：`?k=` 换一张一年期 Cookie，缺了返回 `401 access key required`。
+
+再往里才是 DSH 自己的令牌与 30 天签名 Cookie。
+
+> ⚠️ 会话默认 `danger-full-access` 且不弹审批：**拿到入口就等于能在这台机器上执行任意命令**。口令不要外发。
+
+面板自身的 API 另有一道独立令牌：每进程随机生成，随 index 注入，请求必须带 `x-dsh-remote-panel` 头。
+
+---
+
+## 故障速查
+
+四段状态码，四个方向：
+
+| 现象 | 含义 | 处置 |
+|---|---|---|
+| 连接被拒绝 | 网络层或 Caddy 没起 | `systemctl --user status dsh-proxy`、`easytier-cli peer` |
+| `403 source not allowed` | 来源不在白名单 | 面板「来源白名单」加设备，或在家连 Wi-Fi |
+| `401 access key required` | 缺门禁 Cookie | 用 `?k=` 那条链接重开一次 |
+| `401 dsh web authentication required` | 已到 DSH，缺令牌 | 用 `?token=` 那条链接重开一次 |
+| `/healthz` 返回 200 | 链路本身健康 | 问题在认证层，不在网络层 |
+| 手机「一直连接中」 | 系统浏览器会周期性切断 WebSocket | 换 Chrome |
+| 能 ping 通但页面转圈 | 代理软件（如 Karing）抢走了 EasyTier 流量 | 给中继地址加「直连」规则 |
+| 面板报 `no route: GET /doctor` | Host 侧代码在内存里，加路由后没重启 | `systemctl --user restart dsh-web` |
+| 面板报「面板令牌不匹配」 | 页面是重启前打开的（令牌已持久化，理论上不该再出现） | 硬刷新；仍不行就删 `~/.dsh/remote-panel-token` 让两边都换新 |
+
+面板「自检」里的**布局 canary** 用来发现 DSH 升级导致的选择器失配；「复制诊断包」导出的 JSON 已剔除口令与密钥。
+
+---
+
+## 兼容性
+
+| 项 | 范围 |
+|---|---|
+| DSH | `>= 0.2.1-rc.3`（`engines.dsh`） |
+| 系统 | Linux + systemd（v1 只做这一种） |
+| 架构 | x86_64 / aarch64 |
+| 反代端口 | 非特权端口（默认 8710），因此 Caddy 无需 root |
+| EasyTier | 固定 `2.6.4`，`--tcp-whitelist` 走运行时探测 |
+
+---
+
+## 卸载
+
+```bash
+# 数据面
+sudo bash dsh-remote-panel.sh --uninstall
+# 控制面
+dsh plugin --profile web remove dsh-remote-panel
+```
+
+`--uninstall` 会停并删两个单元与配置，**不删**二进制（可能被别的用途复用）。
+
+---
+
+## v1 不做
+
+Windows / macOS 服务管理 · 从零搭建 EasyTier 共享节点 · 多机集中管理 · TLS/PWA · 消息推送。
+
+---
+
+## 开发
+
+```bash
+npm test          # node --test，81 条（80 通过 + 1 条未设置 CADDY_BIN 时跳过）
+```
+
+提交约定：一个功能点一个 commit，清单见 [docs/checklist.md](docs/checklist.md)。
+
+浏览器里才能确认的部分（移动端外壳、三层门禁）见 [docs/verify.md](docs/verify.md)。
+
+```bash
+CADDY_BIN=/path/to/caddy npm test   # 额外跑真实 Caddy 的门禁语义测试
+```
+
+## 许可
+
+Apache-2.0

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-remote-panel bundle patch.
+#
+# 由 `dsh plugin --profile <name> add dsh-remote-panel` 挂载，无需手改 profile。
+# insert[].id 同时是本插件的「设置命名空间 id」，必须与 lib/index.js 的
+# `export const name` 保持一致，否则设置页找不到对应分区。
+- insert:
+    - id: remote-panel
+      name: dsh-remote-panel

package/deploy/templates/Caddyfile.tmpl

@@ -0,0 +1,50 @@
+# dsh-remote-panel: 反代与门禁（用户级 Caddy，独立配置，不碰系统 Caddy）
+# 生成者：dsh-remote-panel @@VERSION@@
+{
+	# admin API 保持默认（仅本机 2019）：白名单热重载依赖 `caddy reload`
+	auto_https off
+}
+
+:@@PORT@@ {
+	# 访问日志进 journal，供面板「最近拒绝」使用
+	log {
+		output stderr
+		format json
+		level INFO
+	}
+
+	# 第一层：来源白名单
+	@lan remote_ip 127.0.0.1 ::1 @@LAN_CIDR@@ @@VIRTUAL_IP@@
+	handle @lan {
+		# 诊断用：不经过任何认证
+		handle /healthz {
+			respond "ok" 200
+		}
+
+		# 第二层：口令门禁
+		@key query k=@@ACCESS_KEY@@
+		handle @key {
+			# Cookie 值就是口令本身（24 位随机），而不是常量：常量能被手工伪造
+			header Set-Cookie "dsh_gate=@@ACCESS_KEY@@; Max-Age=31536000; Path=/; HttpOnly; SameSite=Lax"
+			# 显式写 * 匹配器：否则开头的 / 会被当成路径匹配器，
+			# 变成 Location: 303 的怪响应
+			redir * / 303
+		}
+
+		# Caddy 默认没有 cookie 匹配器，用 Header 通配匹配替代
+		@paired header Cookie "*dsh_gate=@@ACCESS_KEY@@*"
+		handle @paired {
+			# 关键：不重写 Host/Origin。DSH 通过 --trusted-host 接受这个 authority，
+			# Cookie 因此天然同源，不需要任何注入或伪造。
+			reverse_proxy 127.0.0.1:@@UPSTREAM_PORT@@
+		}
+
+		handle {
+			respond "dsh-remote: access key required" 401
+		}
+	}
+
+	handle {
+		respond "dsh-remote: source not allowed" 403
+	}
+}

package/deploy/templates/dsh-proxy.service.tmpl

@@ -0,0 +1,15 @@
+# dsh-remote-panel: 反代（用户级 systemd 服务，无 root）
+# 生成者：dsh-remote-panel @@VERSION@@
+[Unit]
+Description=DSH remote proxy (Caddy, user)
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/caddy run --config %h/.config/caddy/Caddyfile --adapter caddyfile
+ExecReload=/usr/bin/caddy reload --config %h/.config/caddy/Caddyfile --adapter caddyfile
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target

package/deploy/templates/easytier.env.tmpl

@@ -0,0 +1,7 @@
+# dsh-remote-panel: EasyTier 身份（0600，仅 root 可读）
+# 生成者：dsh-remote-panel @@VERSION@@
+ET_NETWORK='@@NETWORK_NAME@@'
+ET_SECRET='@@NETWORK_SECRET@@'
+ET_IPV4='@@VIRTUAL_IP@@'
+ET_HOSTNAME='@@HOSTNAME@@'
+ET_DEV_NAME='@@DEV_NAME@@'

package/deploy/templates/easytier.service.tmpl

@@ -0,0 +1,24 @@
+@ Unit: EasyTier 节点（system 级，唯一需要 root 的部件）
+@ 生成者：dsh-remote-panel @@VERSION@@
+[Unit]
+Description=EasyTier node for dsh-remote-panel
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/easytier/dsh-remote.env
+ExecStart=/usr/local/bin/easytier-core \
+	--network-name "${ET_NETWORK}" \
+	--network-secret "${ET_SECRET}" \
+	--ipv4 "${ET_IPV4}" \
+	--dev-name "${ET_DEV_NAME}" \
+	--hostname "${ET_HOSTNAME}" \
+	@@PEERS_FLAGS@@ \
+	@@TCP_WHITELIST@@
+Restart=always
+RestartSec=3
+LimitNOFILE=1048576
+
+[Install]
+WantedBy=multi-user.target

package/deploy/templates/install.sh.tmpl

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# dsh-remote-panel 部署脚本（由插件渲染，版本 @@VERSION@@）
+#
+# 幂等：重复执行不会重复写入，也不会覆盖已有的 Caddy 站点配置。
+# 卸载：本脚本 --uninstall
+#
+# 只做两件事：装一个用户级 Caddy（数据面），装一个 system 级 EasyTier（网络面）。
+set -euo pipefail
+
+TARGET_USER='@@USER@@'
+TARGET_HOME='@@HOME@@'
+PROXY_PORT='@@PORT@@'
+UPSTREAM_PORT='@@UPSTREAM_PORT@@'
+VIRTUAL_IP='@@VIRTUAL_IP@@'
+RELAY_HOST='@@RELAY_HOST@@'
+ET_VERSION='@@ET_VERSION@@'
+PANEL_VERSION='@@VERSION@@'
+ACCESS_KEY='@@ACCESS_KEY@@'
+ET_SHA_X86_64='@@ET_SHA_X86_64@@'
+ET_SHA_AARCH64='@@ET_SHA_AARCH64@@'
+
+# 路径可覆盖：便于在临时目录里做端到端演练，生产环境用默认值
+ETC_DIR="${ETC_DIR:-/etc}"
+UNIT_DIR="${UNIT_DIR:-/etc/systemd/system}"
+BIN_DIR="${BIN_DIR:-/usr/local/bin}"
+
+ET_UNIT='easytier-dsh-remote'
+USER_UNIT='dsh-proxy'
+ENV_FILE="$ETC_DIR/easytier/dsh-remote.env"
+UNIT_FILE="$UNIT_DIR/$ET_UNIT.service"
+CADDY_DIR="$TARGET_HOME/.config/caddy"
+USER_UNIT_DIR="$TARGET_HOME/.config/systemd/user"
+
+log() { printf '\033[1;34m[deploy]\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31m[deploy]\033[0m %s\n' "$*" >&2; exit 1; }
+
+[ "$(id -u)" -eq 0 ] || die "请用 sudo 运行本脚本"
+
+if [ "${1:-}" = "--uninstall" ]; then
+	log "停止并移除服务"
+	systemctl disable --now "$ET_UNIT" 2>/dev/null || true
+	rm -f "$UNIT_FILE"
+	systemctl daemon-reload
+	rm -f "$ENV_FILE"
+	runuser -u "$TARGET_USER" -- env XDG_RUNTIME_DIR="/run/user/$(id -u "$TARGET_USER")" \
+		systemctl --user disable --now "$USER_UNIT" 2>/dev/null || true
+	rm -f "$USER_UNIT_DIR/$USER_UNIT.service"
+	rm -rf "$CADDY_DIR"
+	log "已移除。二进制未删除（可能被其他用途复用）。"
+	exit 0
+fi
+
+case "$(uname -m)" in
+	x86_64) ET_ARCH=x86_64; ET_SHA="$ET_SHA_X86_64" ;;
+	aarch64|arm64) ET_ARCH=aarch64; ET_SHA="$ET_SHA_AARCH64" ;;
+	*) die "不支持的架构：$(uname -m)（v1 仅提供 x86_64 / aarch64）" ;;
+esac
+command -v systemctl >/dev/null || die "未找到 systemd"
+command -v curl >/dev/null || die "缺少 curl：apt install curl"
+
+# ---------------------------------------------------------------- EasyTier
+if command -v easytier-core >/dev/null; then
+	log "easytier-core 已存在：$(easytier-core --version 2>/dev/null | head -1)"
+else
+	log "下载 EasyTier ${ET_VERSION} (${ET_ARCH})"
+	tmp="$(mktemp -d)"
+	trap 'rm -rf "$tmp"' EXIT
+	url="https://github.com/EasyTier/EasyTier/releases/download/v${ET_VERSION}/easytier-linux-${ET_ARCH}-v${ET_VERSION}.zip"
+	curl -fsSL "$url" -o "$tmp/et.zip" || die "下载失败：$url（请检查网络或代理）"
+	if [ -n "$ET_SHA" ]; then
+		echo "$ET_SHA  $tmp/et.zip" | sha256sum -c - >/dev/null 2>&1 \
+			|| die "sha256 校验失败：$url（下载被篡改或版本不匹配）"
+		log "sha256 校验通过"
+	else
+		log "警告：这个版本没有收录 sha256，跳过校验"
+	fi
+	( cd "$tmp" && unzip -q et.zip ) || die "解压失败：$tmp/et.zip"
+	core="$(find "$tmp" -name easytier-core -type f | head -1)"
+	cli="$(find "$tmp" -name easytier-cli -type f | head -1)"
+	[ -n "$core" ] || die "压缩包内未找到 easytier-core"
+	install -d -m 755 "$BIN_DIR"
+	install -m 755 "$core" "$BIN_DIR/easytier-core"
+	[ -n "$cli" ] && install -m 755 "$cli" "$BIN_DIR/easytier-cli"
+	log "安装完成：$("$BIN_DIR/easytier-core" --version 2>/dev/null | head -1)"
+fi
+
+# tcp-whitelist 在旧版本不存在，探测后再决定是否加
+TCP_WL=""
+if easytier-core --help 2>&1 | grep -q 'tcp-whitelist'; then
+	TCP_WL="--tcp-whitelist ${PROXY_PORT}"
+fi
+
+install -d -m 755 "$ETC_DIR/easytier" "$UNIT_DIR"
+umask 077
+cat > "$ENV_FILE" <<'DSH_ENV_EOF'
+@@ENV_BODY@@
+DSH_ENV_EOF
+chmod 600 "$ENV_FILE"
+
+cat > "$UNIT_FILE" <<'DSH_UNIT_EOF'
+@@UNIT_BODY@@
+DSH_UNIT_EOF
+sed -i "s#@@TCP_WHITELIST@@#${TCP_WL}#" "$UNIT_FILE"
+chmod 644 "$UNIT_FILE"
+systemctl daemon-reload
+systemctl enable --now "$ET_UNIT"
+log "EasyTier 已启动"
+
+# ---------------------------------------------------------------- Caddy
+if ! command -v caddy >/dev/null; then
+	if command -v apt-get >/dev/null; then
+		log "安装 Caddy（apt）"
+		apt-get update -qq
+		DEBIAN_FRONTEND=noninteractive apt-get install -y -qq caddy >/dev/null
+	elif command -v dnf >/dev/null; then
+		log "安装 Caddy（dnf）"
+		dnf install -y -q 'dnf-command(copr)' >/dev/null 2>&1 || true
+		dnf copr enable -y '@caddy/caddy' >/dev/null 2>&1 || true
+		dnf install -y -q caddy >/dev/null
+	else
+		die "无法自动安装 Caddy：请手动安装后重跑（https://caddyserver.com/docs/install）"
+	fi
+
+	# apt/dnf 的 caddy 包会顺手起一个系统级实例，占住 127.0.0.1:2019 管理端口，
+	# 导致我们的用户级实例无限重启。这里把它停掉——本项目固定用用户级实例。
+	if systemctl list-unit-files caddy.service >/dev/null 2>&1; then
+		if systemctl is-enabled --quiet caddy 2>/dev/null || systemctl is-active --quiet caddy 2>/dev/null; then
+			log "停用系统级 caddy.service（改用用户级实例，避免 2019 端口冲突）"
+			systemctl disable --now caddy >/dev/null 2>&1 || true
+		fi
+	fi
+fi
+
+install -d -m 700 -o "$TARGET_USER" -g "$(id -gn "$TARGET_USER")" "$CADDY_DIR"
+install -d -m 700 -o "$TARGET_USER" -g "$(id -gn "$TARGET_USER")" "$USER_UNIT_DIR"
+
+cat > "$CADDY_DIR/Caddyfile" <<'DSH_CADDY_EOF'
+@@CADDY_BODY@@
+DSH_CADDY_EOF
+cat > "$USER_UNIT_DIR/$USER_UNIT.service" <<'DSH_PROXY_EOF'
+@@PROXY_UNIT_BODY@@
+DSH_PROXY_EOF
+chown "$TARGET_USER":"$(id -gn "$TARGET_USER")" \
+	"$CADDY_DIR/Caddyfile" \
+	"$USER_UNIT_DIR/$USER_UNIT.service"
+chmod 644 "$CADDY_DIR/Caddyfile" "$USER_UNIT_DIR/$USER_UNIT.service"
+
+loginctl enable-linger "$TARGET_USER" >/dev/null 2>&1 || true
+runuser -u "$TARGET_USER" -- env XDG_RUNTIME_DIR="/run/user/$(id -u "$TARGET_USER")" \
+	systemctl --user daemon-reload
+runuser -u "$TARGET_USER" -- env XDG_RUNTIME_DIR="/run/user/$(id -u "$TARGET_USER")" \
+	systemctl --user enable --now "$USER_UNIT"
+log "反代已启动（用户级服务，无 root 权限）"
+
+# ---------------------------------------------------------------- 验收
+log "等待虚拟 IP ${VIRTUAL_IP}"
+for _ in $(seq 1 60); do
+	ip -4 -o addr show 2>/dev/null | grep -q " ${VIRTUAL_IP}/" && break
+	sleep 1
+done
+ip -4 -o addr show 2>/dev/null | grep -q " ${VIRTUAL_IP}/" \
+	|| die "虚拟 IP 未就绪：检查 $ENV_FILE 与中继 ${RELAY_HOST}"
+
+for _ in $(seq 1 30); do
+	ss -ltn 2>/dev/null | grep -q ":${PROXY_PORT} " && break
+	sleep 1
+done
+ss -ltn 2>/dev/null | grep -q ":${PROXY_PORT} " || die "反代未监听 :${PROXY_PORT}"
+
+health="$(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1:${PROXY_PORT}/healthz" || true)"
+[ "$health" = "200" ] || die "healthz 未返回 200（实际 ${health}）"
+
+PAYLOAD="$(printf '{"version":"%s","port":%s,"ip":"%s","upstream":%s,"health":"%s","key":"%s"}' \
+	"$PANEL_VERSION" "$PROXY_PORT" "$VIRTUAL_IP" "$UPSTREAM_PORT" "$health" "$ACCESS_KEY" | base64 -w0)"
+
+cat <<EOF
+
+部署完成。
+
+  手机 / 平板： http://${VIRTUAL_IP}:${PROXY_PORT}/
+  家里局域网：  http://<本机局域网IP>:${PROXY_PORT}/
+
+回填码（复制到「远程访问」面板）：
+DSH_REMOTE_OK ${PAYLOAD}
+EOF