文件管理器
通过 ServerBee 浏览、读取、编辑、上传、下载和管理远程文件。
文件管理器通过 ServerBee Agent 提供受控的远程文件系统访问能力，适合查看日志、编辑小型配置文件、传输文件等运维场景，无需打开完整终端。
文件管理器仅限 Admin 使用。除修改文件的操作外，浏览、获取元数据、读取、下载和传输管理同样需要 Admin 权限。
文件管理器属于高风险功能。请仅在可信服务器上启用，并将 root_paths 限制到最小必要目录。
启用条件
文件管理必须在两层同时启用，且都在 Agent 主机上配置 —— 能力由 Agent 拥有，Server 无法开启：
file能力：file能力默认关闭。在 Agent 的[capabilities]allow 列表中加入它（或传--allow-cap file）。见 功能开关。- 文件子系统策略：设置
[file].enabled = true，并配置至少一个允许访问的根目录。
两层条件同时满足后，Agent 才会对外上报 file 能力：如果只允许了 file 而子系统未启用（或 root_paths 为空），Agent 会在启动时从上报能力中剔除 file，Server 和 UI 因此不会展示一个无法实际工作的文件管理器。
示例 agent.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"]等价环境变量：
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
所有文件管理端点都需要 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} | 取消传输 |
示例：
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"}'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'