树莓派局域网访问ZnFr60/dsh-lan-access-for-rpi-os-or-debian

适用于 RPI OS 或 Debian 的 dsh-lan-access

⚠️ 安全警告 / SECURITY WARNING
仅限可信局域网内部使用！严禁暴露公网！ 当前版本没有身份认证，局域网内任何人只要访问该网页，即可操控本机执行 shell 命令。请在可信网络内使用，并参考下方「安全说明」加固。
Trusted LAN only! Never expose to the public internet! There is no authentication in the current version — anyone on your LAN who can open the page can control the machine and run shell commands. Use only on a trusted network and follow the Security notes below.

DeepSeek Harness (dsh) LAN-access for Raspberry Pi OS / Debian (64-bit, aarch64) — a one-shot installer that opens LAN access and boot auto-start for the dsh Web UI, so any device on your trusted home network can fully control dsh from a browser (phone / computer / others), exactly like on the Pi itself.

专为 Raspberry Pi OS / Debian（64 位, aarch64） 上的 DeepSeek Harness（dsh）Web UI 提供局域网访问 + 开机自启动的一键工具，让同局域网内任意设备（手机/电脑/其他设备）都能用浏览器完整操控 dsh，与树莓派本机完全一致。

中文

这是什么

适用平台：Raspberry Pi OS / Debian（64 位, aarch64）。脚本为 Bash，面向 Linux 系（Debian）环境；
Windows 用户请使用专门的 dsh-lan-access-for-windows。

本仓库是一个 DSH 局域网访问 + 开机自启动的一键自动化脚本（配套 systemd 服务模板与特权接口修复工具）。安装后，同局域网内任意设备（电脑 / 手机 / 其他设备）都能用浏览器完整操控 dsh Web：发送指令、审批权限弹窗、查看编译日志，以及设置 / 凭据页面 —— 与树莓派本机完全一致。

只改动 DSH 自身配置 / 插件 与 用户目录下的 systemd 配置，不触碰 Raspberry Pi OS 系统核心文件，不绑定公网。

它解决什么（背景）

dsh 官方出于安全考虑（DNS rebinding / 跨站防护）默认仅允许本机回环访问：

| 现象 | 原因 |
|------|------|
| 局域网 / 手机访问 /api/ 返回 403 | browser-trust 围栏只信任回环或 --trusted-host |
| 明文 HTTP 下会话 / 模型列表空白 | crypto.randomUUID() 仅存在于安全上下文 |
| 设置 / 凭据页空白 | 特权接口（settings.、credentials. 等）被硬编码为仅回环 |

官方 CLI 还禁止 --host 0.0.0.0。本工具通过社区插件 + 一处 DSH 自身代码的最小改动，完整解决以上全部问题。

原理（技术栈）

1. dsh-web-lan-access 插件（npm 包，作者 AcidGr）—— 自包含的 DSH bundle，自动完成：
- 把 webserver 绑定改为 0.0.0.0（绕开 CLI 对 --host 0.0.0.0 的拒绝）
- 把 /api 信任围栏扩展到本机所有非内网 IPv4（局域网 / Tailscale / VPN）
- 注入 crypto.randomUUID polyfill（修复明文 HTTP 下 UI 空白）
2. 特权接口修复（src/apply-privileged-fix.sh）—— 把 DSH 自身插件里硬编码的回环门禁改为跟随部署的 trusted-hosts，使设置 / 凭据页在局域网可用。
3. systemd 用户服务（src/dsh-web.service）—— 开机自启动，linger 让其在无登录状态下运行。

快速开始

git clone https://github.com/ZnFr60/dsh-lan-access-for-rpi-os-or-debian.git
cd dsh-lan-access-for-rpi-os-or-debian

（可选）先按需改配置：cp config.env.example config.env && nano config.env

./install.sh

完成后会打印局域网访问地址，类似：

================= RESULT =================
[dsh-rpi-lan] dsh web is running: pid=... cwd=/home/pi/Desktop/dsh
[dsh-rpi-lan] listening on:  0.0.0.0:3080

手机 / 电脑 / 局域网任意设备浏览器访问：
http://192.168.1.27:3080
==========================================

在手机 / 电脑 / 其他设备浏览器打开 http://:3080 即可。

命令一览

| 命令 | 作用 |
|------|------|
| ./install.sh | 一键配置 + 安装 + 开机自启 + 重启 + 打印 URL（幂等，可重复运行） |
| ./install.sh status | 只查看当前状态，不做任何改动 |
| ./install.sh uninstall | 停止并禁用自启服务（插件保留，可按提示手动移除） |
| ./install.sh help | 显示帮助 |
兼容性

本工具针对 DSH v0.18.0 设计并实测通过。 后续版本若 DSH 内部 API / 插件机制（webserver 配置、browser-trust 篱笆、特权接口门禁）发生变动，本工具可能失效；升级 DSH 后请重新验证，或关注本仓库更新。

前置要求

- Raspberry Pi OS（Debian 系，aarch64）已安装 Node.js + npm
- 已全局安装 DeepSeek Harness：npm install -g @deepseek-ai/dsh
- 需要 sudo（用于 loginctl enable-linger，实现无登录自启动）
- 树莓派与手机等设备处于同一局域网

脚本会自动完成：安装 pnpm（用户目录，无需 sudo）、补齐 PATH / DSH_HOME 环境变量、安装插件、写 systemd 服务、启用 linger、重启服务。

配置变量（config.env，全部可用环境变量覆盖）

复制 config.env.example 为 config.env 后编辑；也可直接命令行覆盖：PORT=3080 ./install.sh

| 变量 | 默认值 | 说明 |
|------|--------|------|
| DSH_HOME | $HOME/.dsh | DSH 安装根目录 |
| PROFILE | web | 托管浏览器 UI 的 profile |
| PORT | 3080 | Web 监听端口 |
| PLUGIN_NAME | dsh-web-lan-access | npm 插件名 |
| PLUGIN_GITHUB | github:AcidGr/dsh-web-lan-access | npm 不可用时回退的 GitHub 源 |
| WORKSPACE_DIR | $HOME/Desktop/dsh | 工作目录（即 agent 的 workspace / 你的项目目录） |
| PNPM_PREFIX | $HOME/.npm-global | pnpm 用户安装前缀 |
| PNPM_VERSION | latest | pnpm 版本 |
| SERVICE_NAME | dsh-web | systemd 用户服务名 |
| SYSTEMD_USER_DIR | $HOME/.config/systemd/user | systemd 用户单元目录 |
| ENABLE_PRIVILEGED_FIX | 1 | 是否应用特权接口修复（设 0 关闭；仅影响设置/凭据页） |

目录结构

dsh-lan-access-for-rpi-os-or-debian/
├── install.sh                     # 主自动化脚本（幂等）
├── config.env.example             # 全部变量 / 环境变量说明与默认值
├── README.md                      # 双语说明（中文 / English）
├── LICENSE
├── src/
│   ├── dsh-web.service            # systemd 用户服务模板（占位符由 install.sh 替换）
│   └── apply-privileged-fix.sh    # 特权接口修复工具（on/off/status，幂等，含备份）

安全说明（请务必阅读）

- 绑定 0.0.0.0 意味着同一局域网内任何人无需登录即可访问（/api 是来源围栏，不是身份认证）。
- 仅用于可信的家庭局域网，不要做公网端口转发。
- 如需更强隔离，建议：
- 本机防火墙限制来源，例如：sudo ufw allow from 192.168.0.0/16 to any port 3080
- 或用 Tailscale / 带认证的反向代理接入。
- 本项目只修改 DSH 自身配置 / 插件，以及 ~/.config/systemd/user/ 下的服务文件，不修改系统核心文件。

故障排查

手机 / 局域网设备打不开网页或 /api 403
- 确认树莓派与设备在同一局域网。
- 确认服务在监听：systemctl --user status dsh-web.service 应为 active (running)；端口 ss -tln | grep :3080 应显示 0.0.0.0:3080。
- 局域网请求被防火墙拦截：用 ufw 放行端口（需管理员）：
sudo ufw allow from 192.168.0.0/16 to any port 3080 proto tcp
sudo ufw status

若用其他防火墙（firewalld/iptables），按同理放行 TCP 3080。
- 换用本机回环测试确认服务本身正常：curl http://127.0.0.1:3080/ 应返回 HTML。

设置 / 凭据页在手机端空白或报错
- 多为特权接口回环门禁未放行。确认 ENABLE_PRIVILEGED_FIX=1 且已应用：
bash src/apply-privileged-fix.sh status   # 应显示 fix APPLIED

DSH 升级后失效
- 见「兼容性」说明：升级后重新运行 ./install.sh 并验证；若仍异常，请提 issue 并注明 DSH 版本。

Windows 用户（另见 dsh-lan-access-for-windows）
- 端口被 Windows 防火墙拦截：需放行入站规则；PowerShell 执行策略报错：用 powershell -ExecutionPolicy Bypass -File install.ps1。

卸载（零残留）

下面步骤完整移除本工具留下的所有痕迹（服务、插件、特权修复、配置文件）：

1) 停止并禁用自启服务，删除 systemd 用户单元文件
systemctl --user stop  dsh-web.service
systemctl --user disable dsh-web.service
rm -f ~/.config/systemd/user/dsh-web.service
systemctl --user daemon-reload
2) （可选）将特权接口修复还原为官方原版
bash src/apply-privileged-fix.sh off

3) 从 DSH web profile 中移除插件依赖
dsh plugin --profile web remove dsh-web-lan-access

4) 删除本工具的本地副本（含 config.env）
rm -rf /path/to/dsh-lan-access-for-rpi-os-or-debian

说明：脚本写入 ~/.bashrc / ~/.profile 的 PATH 追加行（$HOME/.npm-global/bin）为幂等增量，如需彻底清理可手动删除该行；sudo loginctl enable-linger 如需撤销可执行 sudo loginctl disable-linger $(whoami)。

许可证

MIT

English

这是什么

支持的平台：Raspberry Pi OS / Debian（64 位，aarch64）。这是一个面向 Linux（Debian 系）系统的 Bash 安装器。Windows 用户应使用专用的 dsh-lan-access-for-windows。

本仓库是一个 DSH 局域网访问 + 开机自启动的一站式自动化安装器（外加一个 systemd 服务模板和一个特权 API 修复工具）。安装完成后，同一局域网内的任何设备——电脑、手机、其他设备——都可以通过浏览器完全控制 dsh Web UI：发送命令、批准权限弹窗、查看编译日志，并使用 Settings / credentials 页面，与在 Pi 本机上操作完全一致。

它仅修改 DSH 自身的配置/插件 以及 你主目录中的 systemd 配置——绝不触碰 Raspberry Pi OS 核心系统文件，也绝不将你的服务器暴露到公网。

背景 / 它解决的问题

出于安全考虑（DNS 重绑定和跨站防御），dsh 默认仅允许 回环（loopback） 访问：

| 现象 | 原因 |
|---------|-------|
| 从局域网 / 手机访问 /api/ 返回 403 | 浏览器信任围栏仅信任回环或 --trusted-host |
| 通过普通 HTTP 访问时会话 / 模型列表为空 | crypto.randomUUID() 仅存在于安全上下文中 |
| Settings / credentials 页面为空白 | 特权方法（settings.、credentials.、……）被硬性固定为仅回环可用 |

官方 CLI 还会 拒绝 --host 0.0.0.0。本项目通过一个社区插件以及对 DSH 自身代码的一处最小改动，修复了上述所有问题。

工作原理（技术栈）

1. dsh-web-lan-access 插件（AcidGr 的 npm 包）——一个自包含的 DSH bundle，会自动：
- 将 webserver 绑定主机切换为 0.0.0.0（绕过 CLI 对 --host 0.0.0.0 的拒绝）
- 将 /api 信任围栏放宽至主机上的每一个 非内部 IPv4（局域网 / Tailscale / VPN）
- 注入 crypto.randomUUID polyfill（修复普通 HTTP 下的空白 UI）
2. 特权 API 修复（src/apply-privileged-fix.sh）——放宽 DSH 自身插件中硬编码的回环门禁，使这些方法遵循部署的受信任主机，从而让 Settings / credentials 可通过局域网使用。
3. systemd 用户服务（src/dsh-web.service）——开机自动启动；linger 使其无需任何登录即可运行。

快速开始
bash
git clone https://github.com/ZnFr60/dsh-lan-access-for-rpi-os-or-debian.git
cd dsh-lan-access-for-rpi-os-or-debian
（可选）先复制并编辑配置：cp config.env.example config.env && nano config.env

./install.sh

完成后它会打印你的局域网地址，例如：

================= RESULT =================
[dsh-rpi-lan] dsh web is running: pid=... cwd=/home/pi/Desktop/dsh
[dsh-rpi-lan] listening on:  0.0.0.0:3080

Open in a browser from any phone / computer / LAN device:
http://192.168.1.27:3080
==========================================

然后在任意设备的浏览器中打开 http://:3080。

命令

| 命令 | 效果 |
|---------|--------|
| ./install.sh | 配置 + 安装 + 自动启动 + 重启 + 打印 URL（幂等；可安全重复运行） |
| ./install.sh status | 仅报告当前状态，不做任何更改 |
| ./install.sh uninstall | 停止并禁用自动启动服务（插件保留；如需删除请手动操作） |
| ./install.sh help | 显示帮助 |

兼容性

针对 DSH v0.18.0 设计和测试。 未来的版本可能会更改 DSH 内部 API / 插件机制（webserver 配置、浏览器信任围栏或特权方法门控），并可能导致此工具失效。升级 DSH 后请重新验证，并关注此仓库的更新。

前提条件

- Raspberry Pi OS（Debian 系，aarch64），带有 Node.js + npm
- 全局安装 DeepSeek Harness：npm install -g @deepseek-ai/dsh
- 具有 sudo 权限（用于 loginctl enable-linger，以便无需登录即可自动启动）
- Pi 和你的设备处于同一局域网

该脚本会自动：安装 pnpm（安装到你的主目录，无需 sudo）、添加 PATH / DSH_HOME 环境变量、安装插件、写入 systemd 服务、启用 linger，并重启服务。

配置（config.env，每个值都可通过环境变量覆盖）

将 config.env.example 复制为 config.env 并编辑；或内联覆盖：PORT=3080 ./install.sh

| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| DSH_HOME | $HOME/.dsh | DSH 安装根目录 |
| PROFILE | web | 承载浏览器 UI 的 profile |
| PORT | 3080 | Web 监听端口 |
| PLUGIN_NAME | dsh-web-lan-access | npm 插件名称 |
| PLUGIN_GITHUB | github:AcidGr/dsh-web-lan-access | npm 不可用时的 GitHub 源回退 |
| WORKSPACE_DIR | $HOME/Desktop/dsh | 工作目录（agent 的工作区 / 你的项目） |
| PNPM_PREFIX | $HOME/.npm-global | pnpm 的用户安装前缀 |
| PNPM_VERSION | latest | pnpm 版本 |
| SERVICE_NAME | dsh-web | systemd 用户服务名称 |
| SYSTEMD_USER_DIR | $HOME/.config/systemd/user | systemd 用户单元目录 |
| ENABLE_PRIVILEGED_FIX | 1 | 应用特权 API 修复（0 禁用；仅影响设置/凭据页面） |

目录结构

dsh-lan-access-for-rpi-os-or-debian/
├── install.sh                     # 主自动化脚本（幂等）
├── config.env.example             # 所有变量 / 环境变量
├── README.md                      # 双语（中文 / English）
├── LICENSE
├── src/
│   ├── dsh-web.service            # systemd 用户服务模板（占位符由 install.sh 填充）
│   └── apply-privileged-fix.sh    # 特权 API 修复工具（on/off/status，幂等，保留备份）

安全须知（请阅读）

- 绑定 0.0.0.0 意味着同一局域网内的任何人都可以无需登录访问（/api 只是来源限制，并非身份验证）。
- 仅在可信的家庭网络中使用；切勿将其端口转发到公网。
- 如需更强的隔离，可考虑：
- 使用主机防火墙限制来源，例如 sudo ufw allow from 192.168.0.0/16 to any port 3080
- 或使用 Tailscale / 带身份验证的反向代理。
- 本项目仅涉及 DSH 自身的配置/插件以及 ~/.config/systemd/user/ 下的文件；不会修改系统核心文件。

故障排查

手机 / 局域网设备无法打开页面，或 /api 返回 403
- 确保树莓派和你的设备处于同一局域网。
- 确认服务正在运行：systemctl --user status dsh-web.service 应显示 active (running)；端口 ss -tln | grep :3080 应显示 0.0.0.0:3080。
- 局域网请求被防火墙拦截——使用 ufw（管理员）放行该端口：
bash
sudo ufw allow from 192.168.0.0/16 to any port 3080 proto tcp
sudo ufw status
对于其他防火墙（firewalld/iptables），以相同方式放行 TCP 3080。
- 在回环地址上对服务器本身做基本检查：curl http://127.0.0.1:3080/ 应返回 HTML。

设置 / 凭据页面在手机上空白或报错
- 通常是特权 API 的回环限制未被放宽。确认已应用 ENABLE_PRIVILEGED_FIX=1：
bash
bash src/apply-privileged-fix.sh status   # 应显示 "fix APPLIED"

升级 DSH 后损坏
- 参见兼容性说明：升级后，重新运行 ./install.sh 并验证；如果仍然失败，请提交 issue 并注明你的 DSH 版本。

Windows 用户（另见 dsh-lan-access-for-windows）
- 端口被 Windows 防火墙拦截：添加入站允许规则；PowerShell 执行策略错误：运行 powershell -ExecutionPolicy Bypass -File install.ps1。

卸载（零残留）

以下步骤会移除本工具留下的所有内容（服务、插件、特权修复、配置）：
bash
1) 停止并禁用自启动服务，删除 systemd 用户单元
systemctl --user stop  dsh-web.service
systemctl --user disable dsh-web.service
rm -f ~/.config/systemd/user/dsh-web.service
systemctl --user daemon-reload

2) （可选）将特权 API 修复还原为原版 dsh
bash src/apply-privileged-fix.sh off

3) 从 dsh web 配置中移除插件依赖
dsh plugin --profile web remove dsh-web-lan-access

4) 删除本仓库的本地副本（包括 config.env）
rm -rf /path/to/dsh-lan-access-for-rpi-os-or-debian

注意：该脚本会向 ~/.bashrc / ~/.profile 追加一行幂等的 PATH 配置（$HOME/.npm-global/bin）；如果你想要一个完全干净的 shell，请手动删除该行。要撤销 linger，请运行 sudo loginctl disable-linger $(whoami)。

许可证

MIT