dsh-server-admin

Readme

# DSH 服务器管理面板 · dsh-server-admin

> **中文**（默认） · [**English**](#english-version)

一个面向 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh) Web 服务器的管理插件：在设置面板中提供「服务器管理」页，**无需 SSH** 即可完成在线重启、systemd 一键保活、在线安装插件、运行状态监控、活跃会话查看与命令终端操作。

当前托管模式、插件安装、保活配置全部可视化，危险操作带确认与倒计时。

---

## ✨ 功能特性

### 1. 运行状态监控
- DSH 进程 PID / PPID、运行时长、CPU / 内存占用
- Node 版本、DSH 版本、磁盘占用
- Web 访问地址、当前托管模式（systemd / screen）
- 自动探测当前部署环境，生成对应的重启命令
- 页面每 2 秒自动刷新，状态实时跟进

### 2. 在线重启 / 停止
- 一键重启 DSH：自动按托管模式选择执行方式
  - **systemd 托管** → `systemctl restart dsh`
  - **screen 托管** → kill 旧进程 + screen 重新拉起
- 一键停止（仅停止，不自动恢复）
- 分离式脚本：先响应页面、延迟 2 秒执行，重启过程安全可控
- 5 秒倒计时确认 + 可取消，防止误操作

### 3. systemd 一键保活（Keep-alive）
将 DSH 从临时 `screen` 会话平滑迁移到 **systemd 服务托管**：
- **崩溃自动重启**：`Restart=always`，进程异常退出 3 秒内自动拉起
- **开机自启**：`systemctl enable`，服务器重启后自动运行
- **日志可查**：`journalctl -u dsh` / `journalctl -f -u dsh`
- 配置预览：启用前先展示将写入的完整单元文件内容
- 支持一键回退到 screen 托管
- 单元覆盖保护：若 `/etc/systemd/system/dsh.service` 已存在且非本插件生成，拒绝覆盖

### 4. 在线安装插件
- 在设置面板直接执行 `dsh plugin --profile web add <包名>`，实时回显 pnpm 输出
- 支持 npm 包名、GitHub 地址
- 安装完成后提示重启 DSH 生效（可直接用本面板的重启功能）

### 5. 活跃会话
- 列出 DSH 中正在运行的对话会话（含当前对话）与运行状态
- 默认折叠，点击展开查看，不占页面空间

### 6. 命令终端
- 以 root 权限在服务器上执行命令（等同 SSH），输出实时回显
- 输出截断保护（64KB）

---

## 📦 安装

### 方式一：从 npm 安装（推荐，命令最简）

```bash
dsh plugin --profile web add dsh-server-admin
```

### 方式二：从 GitHub 安装

```bash
dsh plugin --profile web add github:sunnywangzi/dsh-server-admin
```

### 方式三：本地开发安装（源码在本地时）

```bash
dsh plugin --profile web add /path/to/dsh-server-admin
```

### 安装说明

1. 以上命令会在 `/root/.dsh/profiles/web`（即 web profile）中执行 `pnpm add`
2. `dsh` CLI 会**自动识别**包内 `dsh.bundle.patch` 声明，并将插件加入 profile 的 bundle 层——**无需手动修改任何配置**
3. 安装完成后 **重启 DSH** 生效：
   - systemd 托管：`sudo systemctl restart dsh`
   - screen 托管：`sudo pkill -f 'dsh web'; screen -dmS dsh dsh web`
   - 或安装成功后直接打开本插件面板使用「重启」按钮

### 卸载

```bash
dsh plugin --profile web rm dsh-server-admin
```

---

## 🚀 使用

1. 登录 DSH Web 界面
2. 点击左侧底部 **⚙️ 设置**
3. 在设置面板左侧导航中选择 **「服务器管理」**
4. 各卡片说明：

| 卡片 | 用途 |
|---|---|
| **保活（Keep-alive）** | 查看当前托管模式；一键启用 systemd 保活 / 回退 screen；查看将写入的 systemd 配置 |
| **在线控制** | 重启 / 停止 DSH（带 5 秒倒计时确认） |
| **运行状态** | PID、资源占用、版本、磁盘、托管模式，每 2 秒自动刷新 |
| **在线安装插件** | 输入 npm 包名或 git 地址，一键安装并回显输出 |
| **活跃会话** | 查看运行中的对话会话（默认折叠） |
| **命令终端** | 执行服务器命令并查看输出 |

---

## ⚙️ systemd 保活详解

点击「启用 systemd 保活（推荐）」后，插件会自动执行：

1. 写入 `/etc/systemd/system/dsh.service`：

```ini
[Unit]
Description=DeepSeek Harness Web (managed by dsh-server-admin)
After=network.target

[Service]
Type=simple
Environment=DSH_HOME=/root/.dsh
WorkingDirectory=<检测到的目录>
ExecStart=/usr/local/bin/dsh web
Restart=always          # 崩溃自动重启
RestartSec=3            # 3 秒后拉起
TimeoutStopSec=30
KillMode=control-group

[Install]
WantedBy=multi-user.target   # 开机自启
```

2. `systemctl daemon-reload && systemctl enable dsh`（注册 + 开机自启）
3. 关闭旧 screen 会话，`systemctl start dsh`（systemd 接管，DSH 重启一次完成迁移）

启用后常用命令：

```bash
sudo systemctl status dsh          # 查看状态
sudo journalctl -u dsh -f          # 跟随日志
sudo systemctl restart dsh         # 重启
sudo systemctl stop dsh            # 停止
```

---

## 🔒 安全边界

- **HTTP API**：`/server-admin/api/*` 仅接受回环（127.0.0.1/localhost）同源 POST 请求；方法白名单之外一律 404；请求体限制 1MB
- **root 权限**：插件运行在宿主上下文（root），具备服务器全部权限——等同 SSH 会话，仅限管理员使用
- **命令终端**：执行任意命令且不做沙箱限制，操作前请自行确认命令内容；输出截断至 64KB
- **插件安装**：安装参数经 `execFile` 数组传递（无 shell 注入），但可安装任意 npm 包——请只安装可信来源的插件
- **systemd 单元覆盖保护**：若 `/etc/systemd/system/dsh.service` 已存在且非本插件生成，启用保活会拒绝覆盖
- **网络暴露提醒**：插件默认绑定回环。若通过反向代理将 DSH Web 暴露到公网，请确保 `/server-admin/api` 不被代理放行，或另行加装认证

---

## 🩺 故障排查

| 问题 | 解决方法 |
|---|---|
| 重启后无法访问 | 查看「运行状态」的托管模式；systemd 模式下 `journalctl -u dsh` 查日志；screen 模式下检查 `screen -ls` 会话是否存活 |
| 保活卡片显示「已存在」但状态异常 | 说明单元文件存在但服务状态异常，点「回退到 screen」后重新启用，或 SSH 执行 `systemctl reset-failed dsh` |
| 面板里看不到「服务器管理」页 | 确认插件已安装并重启 DSH；浏览器强制刷新（Ctrl+Shift+R） |
| 在线装插件报错 | 检查输出信息；确认网络可达 npm registry / GitHub |
| 命令终端命令无输出 | 命令本身可能无输出（如 `touch`）；或用 `echo $?` 查看退出码 |

---

## 📄 许可证

[MIT](./LICENSE)

---

# English Version

# DSH Server Admin · dsh-server-admin

A management plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/dsh) Web server: adds a **Server Admin** page in the Settings panel, letting you **restart the server, enable systemd keep-alive, install plugins, monitor status, view active sessions, and run commands without SSH**.

Every dangerous action comes with confirmation and a countdown.

## ✨ Features

1. **Runtime Status** — PID/PPID, uptime, CPU/memory, Node/DSH versions, disk usage, hosting mode (systemd/screen), auto-detected restart command; auto-refreshes every 2 seconds.
2. **Online Restart / Stop** — one-click restart (uses `systemctl restart dsh` under systemd, or kill+screen under screen hosting) and stop, with a 5-second countdown confirmation.
3. **systemd Keep-alive (one click)** — migrates DSH from a temporary `screen` session to a systemd service: auto-restart on crash (`Restart=always`, 3s), auto-start on boot (`enable`), logs via `journalctl -u dsh`; shows the exact unit file before applying; one-click rollback to screen.
4. **Online Plugin Install** — runs `dsh plugin --profile web add <spec>` from the panel with live pnpm output.
5. **Active Sessions** — lists running conversation sessions (collapsed by default).
6. **Command Terminal** — run server commands as root with output echo (64KB cap).

## 📦 Installation

### Option 1: From npm (recommended)

```bash
dsh plugin --profile web add dsh-server-admin
```

### Option 2: From GitHub

```bash
dsh plugin --profile web add github:sunnywangzi/dsh-server-admin
```

### Option 3: Local development

```bash
dsh plugin --profile web add /path/to/dsh-server-admin
```

The `dsh` CLI auto-detects the `dsh.bundle.patch` declaration and registers the plugin into the profile bundle layer — no manual configuration needed. **Restart DSH after installing** (or use the plugin's own restart button once the panel is up).

### Uninstall

```bash
dsh plugin --profile web rm dsh-server-admin
```

## 🚀 Usage

1. Sign in to the DSH Web UI.
2. Click the **⚙️ gear icon** at the bottom of the left sidebar.
3. Choose **Server Admin** in the settings navigation.
4. Cards: **Keep-alive** (hosting mode + enable/rollback + unit preview), **Online Control** (restart/stop), **Runtime Status** (auto-refresh), **Install Plugin**, **Active Sessions** (collapsed), **Command Terminal**.

## ⚙️ systemd Keep-alive details

Enabling writes `/etc/systemd/system/dsh.service` with `Restart=always`, `RestartSec=3`, and `WantedBy=multi-user.target`, then runs `systemctl daemon-reload && systemctl enable dsh`, closes the old screen session and starts via `systemctl start dsh` (one restart to complete the migration).

Useful commands:

```bash
sudo systemctl status dsh
sudo journalctl -u dsh -f
sudo systemctl restart dsh
```

## 🔒 Security Notes

- API is loopback-only with same-origin checks; method whitelist; 1MB body limit.
- Runs with root privileges — treat it like an SSH session (admin use only).
- The command terminal executes arbitrary commands without sandboxing — verify commands before running.
- The systemd unit overwrite is blocked if an existing unit was not generated by this plugin.
- If you expose the DSH Web through a reverse proxy, make sure `/server-admin/api` is not proxied publicly.

## 🩺 Troubleshooting

| Issue | Fix |
|---|---|
| Cannot access after restart | Check hosting mode in Runtime Status; `journalctl -u dsh` under systemd; `screen -ls` under screen |
| Keep-alive card shows unit exists but odd state | Roll back to screen then re-enable, or run `systemctl reset-failed dsh` via SSH |
| No "Server Admin" page in Settings | Ensure installed and DSH restarted; hard refresh (Ctrl+Shift+R) |
| Plugin install fails | Check the echoed output; confirm network access to npm registry / GitHub |

## 📄 License

[MIT](./LICENSE)