# ServerDock

**面向个人与受控环境的自托管 MCP 工作台。**

ServerDock 将工作区文件操作、后台任务、Skills 与 MCP 上游服务整合到统一的 Web 控制台，通过工作区绑定、独立密钥和显式工具权限，为支持 MCP 的客户端提供可管理的工具入口。

**当前版本：`0.1.0-rc.1` · Node.js 22 / 24 LTS · 单用户部署**

[快速开始](#快速开始) · [界面预览](#界面预览) · [文档中心](docs/README.md) · [客户端接入](docs/CONNECTIONS.md) · [更新记录](docs/CHANGELOG.md)

> 当前版本为发布候选版。ServerDock 不是多租户平台或操作系统沙箱，建议先在独立环境中验证，再按实际权限需求部署。

## 核心能力

| 模块 | 能力 |
|---|---|
| 工作区管理 | 绑定授权目录，为各工作区分配独立 MCP 密钥与工具权限；支持持久化默认工作区 |
| 内置工具 | 提供23个文件、搜索、任务、Skills 与上游调用工具，遵循工作区权限边界 |
| 开发工具台 | 查看工具定义，使用 JSON 或表单构造参数，执行调用并检查实际响应 |
| MCP 上游 | 管理 stdio、HTTP 与 SSE 上游配置，检查连接和可用工具 |
| 客户端接入 | 提供本机直连、SSH 转发、临时公网和固定 HTTPS 的配置指引 |
| 运行与审计 | 查看后台任务、调用记录和有界聚合统计，支持时间范围筛选 |
| 交互与主题 | 四套配色、明暗模式、响应式布局与快速页面导航 |

完整功能边界见[架构与能力](docs/reference/ARCHITECTURE.md)。

## 界面预览

以下为 RC1 实际界面，使用隔离实例与演示工作区生成；路径已脱敏，不包含正式环境的密钥或工作区内容。

### 工作台总览

集中查看工作区状态、工具入口与连接状态。背景插画仅用于总览与登录等展示页面，功能页面保持清晰的信息布局。

![ServerDock桌面总览：海蓝主题、工具入口与演示工作区状态](docs/assets/previews/overview.webp)

<details>
<summary><strong>查看开发工具界面</strong></summary>

示例展示 `write_file` 的参数编辑，尚未执行；执行结果区不使用模拟成功响应。

![ServerDock开发工具：工具列表、JSON参数编辑与执行结果区域](docs/assets/previews/tools.webp)

</details>

<details>
<summary><strong>查看移动端响应式布局</strong></summary>

430像素宽浏览器视口下的总览；这是响应式预览，不代表手机实机验收。

<img src="docs/assets/previews/mobile.webp" alt="ServerDock窄屏总览：折叠导航与纵向工作区卡片" width="320">

</details>

背景图片来源：[Bilibili UP 主主页（UID 4168597）](https://space.bilibili.com/4168597)。来源由维护者提供；图片不属于代码的 MIT 许可。详见[素材与预览](docs/design/ARTWORK-LICENSE.md)。

## 快速开始

### 1. 准备环境

- Node.js **22 或 24 LTS**，推荐24。
- npm，以及可访问 npm registry 的安装环境。
- 独立的私有数据目录与工作区目录。

以下命令以 Linux / macOS 的 POSIX Shell 为例。当前完整验证环境为 Linux + Node.js24；其他平台与客户端的验证范围见[发布检查](docs/validation/RELEASE-CHECKS.md)。

### 2. 安装与构建

在解压后的项目根目录执行：

```bash
npm ci --ignore-scripts
npm --prefix frontend ci --ignore-scripts
npm run build:console
npm test
```

源码包不附带依赖目录或已构建的前端，需要先完成以上步骤。

### 3. 启动服务

```bash
export SERVERDOCK_DATA_DIR="$HOME/.local/share/serverdock"
export SERVERDOCK_WORKSPACE="$HOME/serverdock-workspaces/default"
export SERVERDOCK_ALLOW_SHELL=0

install -d -m 700 "$SERVERDOCK_DATA_DIR"
mkdir -p "$SERVERDOCK_WORKSPACE"
npm start
```

| 入口 | 默认地址 | 用途 |
|---|---|---|
| 管理控制台 | `http://127.0.0.1:20141` | 工作区、权限、工具和服务管理 |
| MCP 端点 | `http://127.0.0.1:8301/mcp` | MCP 客户端连接 |

启动前确认端口空闲。管理员令牌由服务生成，保存在私有数据目录的 `admin-token` 文件中；仅在服务器上私密读取，用于控制台登录。**管理员令牌与工作区 MCP 密钥用途不同，不可混用，也不要提交到仓库、公开问题或日志。**

### 4. 连接客户端

登录控制台后，确认当前工作区的目录与工具权限，在“连接”页面选择接入方式并生成对应配置。客户端设置和网络边界见[连接指南](docs/CONNECTIONS.md)。

远程服务器的管理控制台建议通过 SSH 转发访问：

```bash
ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:20141:127.0.0.1:20141 user@server
```

随后在本机打开 `http://127.0.0.1:20141`。该命令只转发管理端；MCP 的访问方式需要另行配置。

长期运行、systemd 与固定 HTTPS 配置请参阅[部署指南](docs/operations/DEPLOY.md)。

## 安全与部署边界

- **管理端不应直接暴露公网。** MCP 的外部访问也需要独立认证、传输保护与最小权限配置。
- Shell 默认关闭。启用 Shell 或 stdio 上游后，命令具有服务账户权限；工作区约束不能替代操作系统隔离。
- 单用户配置不适合承载互不信任的租户；敏感任务应使用额外的账户、容器或主机隔离。
- 加密状态与主密钥保存在同一服务账户下，不抵御主机账户失陷。
- 依赖审计与源码扫描是风险检查手段，不代表绝对安全保证。

更多内容见[安全模型](docs/reference/SECURITY-MODEL.md)、[安全政策与私密漏洞报告](docs/SECURITY.md)和[备份恢复](docs/operations/RECOVERY.md)。

## 文档导航

除本页与根目录 `LICENSE` 外，项目说明文档统一位于 `docs/`。

| 主题 | 文档 |
|---|---|
| 安装与日常使用 | [部署](docs/operations/DEPLOY.md) · [客户端接入](docs/CONNECTIONS.md) · [工作区](docs/WORKSPACES.md) |
| 设计与运行边界 | [架构与能力](docs/reference/ARCHITECTURE.md) · [安全模型](docs/reference/SECURITY-MODEL.md) |
| 开发与维护 | [贡献指南](docs/CONTRIBUTING.md) · [测试](docs/operations/TESTING.md) · [备份恢复](docs/operations/RECOVERY.md) |
| 版本与发布 | [更新记录](docs/CHANGELOG.md) · [发布指南](docs/RELEASING.md) · [验证记录](docs/validation/RELEASE-CHECKS.md) |
| 权利与来源 | [版权声明](docs/NOTICE.md) · [素材与预览](docs/design/ARTWORK-LICENSE.md) · [依赖清单](docs/DEPENDENCIES.json) |

发布源码时，请使用经过检查的源码包在空目录建立新仓库，不要直接推送运行目录、旧 Git 历史、私有状态或备份。

## 许可证与致谢

应用代码使用 [MIT License](LICENSE)，保留适用的第三方声明；第三方依赖的许可随其包提供，详见[版权声明](docs/NOTICE.md)。

背景图片及其在预览截图中的呈现**不适用代码 MIT 许可**。维护者已确认随本项目公开发布的权限；来源标注不等于授权证明，也不授予其他用途的图片许可。复用前请确认适用权利与条款。