# 文件管理器

> 通过 ServerBee 浏览、读取、编辑、上传、下载和管理远程文件。

URL: https://docs.serverbee.app/zh/docs/file-manager

文件管理器通过 ServerBee Agent 提供受控的远程文件系统访问能力，适合查看日志、编辑小型配置文件、传输文件等运维场景，无需打开完整终端。

文件管理器仅限 Admin 使用。除修改文件的操作外，浏览、获取元数据、读取、下载和传输管理同样需要 Admin 权限。

<Callout type="warn">
  文件管理器属于高风险功能。请仅在可信服务器上启用，并将 `root_paths` 限制到最小必要目录。
</Callout>

## 启用条件 [#启用条件]

文件管理必须在两层同时启用，且**都在 Agent 主机上配置** —— 能力由 Agent 拥有，Server 无法开启：

1. **`file` 能力**：`file` 能力默认关闭。在 Agent 的 `[capabilities]` allow 列表中加入它（或传 `--allow-cap file`）。见 [功能开关](/zh/docs/capabilities)。
2. **文件子系统策略**：设置 `[file].enabled = true`，并配置至少一个允许访问的根目录。

两层条件同时满足后，Agent 才会对外上报 `file` 能力：如果只允许了 `file` 而子系统未启用（或 `root_paths` 为空），Agent 会在启动时从上报能力中剔除 `file`，Server 和 UI 因此不会展示一个无法实际工作的文件管理器。

示例 `agent.toml`：

```toml
[capabilities]
# 为该主机开启高风险的 file 能力。
allow = ["file"]

[file]
enabled = true
root_paths = ["/home", "/var/log", "/etc/serverbee"]
max_file_size = 1073741824
# 默认值列在这里便于参考
deny_patterns = ["*.key", "*.pem", "id_rsa*", ".env*", "shadow", "passwd"]
```

等价环境变量：

```bash
SERVERBEE_CAPABILITIES__ALLOW=["file"]
SERVERBEE_FILE__ENABLED=true
SERVERBEE_FILE__ROOT_PATHS=/home,/var/log,/etc/serverbee
SERVERBEE_FILE__MAX_FILE_SIZE=1073741824
```

修改配置后需重启 Agent 才能使能力变更生效。

## 访问方式 [#访问方式]

在服务器操作菜单中点击 **Files**，或直接访问：

```
/files/{serverId}
```

当服务器的 effective capabilities 中不含 `CAP_FILE` 时，前端会隐藏 Files 按钮。

## 权限 [#权限]

文件管理器仅限 Admin 使用。所有文件 API 端点都经过 Admin 权限检查，因为即使是读取操作，也可能暴露受管主机上的敏感文件。

所有高风险文件操作都会写入审计日志，包括因 capability 关闭而被拒绝的尝试。

## 支持的操作 [#支持的操作]

| 操作   | 说明                                      |
| ---- | --------------------------------------- |
| 列目录  | 浏览允许根目录下的文件和目录                          |
| Stat | 获取单一路径的元数据                              |
| 读取   | 读取 UTF-8 文本内容，用于预览或编辑器                  |
| 写入   | 用提供的文本替换文件内容                            |
| 上传   | 上传本地文件到远程路径                             |
| 下载   | 启动经 ServerBee 中转的下载传输，再从 ServerBee 获取文件 |
| 删除   | 删除文件，或递归删除目录                            |
| 新建目录 | 创建目录                                    |
| 移动   | 重命名或移动文件/目录                             |
| 传输管理 | 查看和取消活动传输                               |

## 安全模型 [#安全模型]

Agent 在访问文件系统前会执行路径安全检查：

* `root_paths` 是允许列表；空列表会拒绝所有文件操作。
* 路径解析后必须位于某个允许根目录内。
* `deny_patterns` 会拒绝敏感名称，例如私钥、`.env*`、`shadow`、`passwd`。
* Agent 同样会检查本地 capability，因此 Server 端的改动无法覆盖 Agent 本地的拒绝策略。
* Server 在下发任何文件消息前也会检查 `CAP_FILE`。

## 限制 [#限制]

| 限制              | 默认值    | 配置位置                                                              |
| --------------- | ------ | ----------------------------------------------------------------- |
| 上传大小            | 100 MB | Server `file.max_upload_size` / `SERVERBEE_FILE__MAX_UPLOAD_SIZE` |
| Agent 读取/下载文件大小 | 1 GB   | Agent `[file].max_file_size` / `SERVERBEE_FILE__MAX_FILE_SIZE`    |
| 内联读取分块          | 384 KB | 协议限制，用于保证 WebSocket 帧小于最大消息大小                                     |

上传和下载均采用分块传输。下载会在 Server 端创建临时传输，处于 pending 或 in progress 状态时可以取消。

## API [#api]

所有文件管理端点都需要 Admin 权限，包括列目录、获取元数据、读取、下载和传输管理端点。

| 方法     | 路径                                   | 说明                               |
| ------ | ------------------------------------ | -------------------------------- |
| POST   | `/api/files/{server_id}/list`        | 列目录；请求体 `{ "path": "/var/log" }` |
| POST   | `/api/files/{server_id}/stat`        | 获取路径元数据                          |
| POST   | `/api/files/{server_id}/read`        | 读取 UTF-8 文本内容                    |
| GET    | `/api/files/download/{transfer_id}`  | 下载当前用户拥有的 ready 传输               |
| GET    | `/api/files/transfers`               | 列出当前用户拥有的传输                      |
| POST   | `/api/files/{server_id}/write`       | 替换文件内容                           |
| POST   | `/api/files/{server_id}/delete`      | 删除文件/目录；支持 `recursive`           |
| POST   | `/api/files/{server_id}/mkdir`       | 创建目录                             |
| POST   | `/api/files/{server_id}/move`        | 移动或重命名路径                         |
| POST   | `/api/files/{server_id}/download`    | 启动下载传输                           |
| POST   | `/api/files/{server_id}/upload`      | multipart 上传，字段为 `path` 和 `file` |
| DELETE | `/api/files/transfers/{transfer_id}` | 取消传输                             |

示例：

```bash
curl -X POST https://your-server/api/files/server-id/list \
  -H "X-API-Key: serverbee_..." \
  -H "Content-Type: application/json" \
  -d '{"path":"/var/log"}'
```

```bash
curl -X POST https://your-server/api/files/server-id/upload \
  -H "X-API-Key: serverbee_..." \
  -F 'path=/tmp/example.txt' \
  -F 'file=@example.txt'
```

<Cards>
  <Card title="Agent 安装配置" href="/zh/docs/agent" />

  <Card title="配置参考" href="/zh/docs/configuration" />

  <Card title="功能开关" href="/zh/docs/capabilities" />
</Cards>