Filed
Filed 是一个 PaperMC 插件,通过 REST API 暴露服务器文件,支持令牌认证和路径白名单。
通过由您的服务器托管的 API 端点读取、创建、删除和修改明确允许的服务器文件。访问受到限制,需要包含您生成的 API 密钥才能发起所有请求。
安装
- 将 JAR 文件放入服务器的
plugins/ 目录中
- 重启服务器。
- 配置
plugins/Filed/config.yml。
配置
示例配置:
port: 9847
maximum_allowed_file_size: 1000000
auth_token_file: "tokens.json"
allowed:
files:
- "server.properties"
directories:
- "world/stats"
| 选项 |
描述 |
port |
API 的 HTTP 端口 |
maximum_allowed_file_size |
最大文件大小(字节) |
auth_token_file |
存储哈希令牌的位置 |
allowed.files |
可访问的确切文件路径 |
allowed.directories |
可访问的目录(及其内容) |
路径相对于服务器根目录(即 server.properties 所在的同一目录)。
认证
在游戏中或通过控制台生成令牌:
/filed generate <name>
需要 op 权限。令牌仅显示一次,之后无法检索。
在请求中包含 Bearer <token> 作为 Authorization 头来使用令牌。
API
读取
GET /files?path=<path>&content=<true|false>
文件的示例响应:
{
"type": "file",
"path": "server.properties",
"content": "..."
}
目录的示例响应:[不包含目录及其子目录中的文件]
{
"type": "directory",
"path": "world/stats",
"files": [
{"type": "file", "path": "player.json", "content": "..."}
]
}
设置 content=false 可省略文件内容。
写入
PUT /files?path=<path>
Content-Type: text/plain
<file content>
创建或覆盖文件。父目录必须存在。返回修改后文件的内容。仅允许写入文件。
删除
DELETE /files?path=<path>
在响应中返回已删除文件的内容。仅允许删除文件,不允许删除目录。
健康检查
GET /health
此端点无需授权即可访问,可用于确认 API 端点是否正在运行。如果一切正常,将返回 {"message": "ok"}。
错误
失败的示例响应:
{
"error": "forbidden",
"message": "path not allowed by existing configuration rules"
}
所有错误代码及其含义的完整列表:
| 错误 |
代码 |
含义 |
unauthorized |
401 |
缺少或无效的令牌 |
forbidden |
403 |
路径不在白名单中或存在符号链接逃逸 |
not_found |
404 |
文件不存在 |
invalid_path |
400 |
提供的路径无效 |
is_directory |
400 |
无法写入/删除目录 |
parent_not_found |
400 |
父目录不存在(适用于写入操作) |
too_large |
413 |
文件大小超出限制 |
安全性
- 在执行任何操作之前,路径会被标准化并根据白名单进行检查,以阻止任何
.. 遍历。
- 解析后超出服务器根目录的符号链接将被拒绝。
- 令牌在存储前会进行 SHA-256 哈希处理,并仅用于验证访问权限。
- 可配置的文件大小限制可防止内存耗尽。
- 不允许子目录遍历。如果请求了一个目录,则仅返回该目录中包含的文件。
Filed
Filed is a PaperMC plugin that exposes server files over a REST API with token auth and path whitelisting.
Read, create, delete and modify explicitly allowed server files via an API endpoint hosted by your server. Access is gated, and requires an API key that you generate to be included with all requests.
Installation
- Place the JAR in your server's
plugins/ directory`
- Restart the server.
- Configure
plugins/Filed/config.yml.
Configuration
Example config:
port: 9847
maximum_allowed_file_size: 1000000
auth_token_file: "tokens.json"
allowed:
files:
- "server.properties"
directories:
- "world/stats"
| Option |
Description |
port |
HTTP port for the API |
maximum_allowed_file_size |
Max file size in bytes |
auth_token_file |
Where hashed tokens are stored |
allowed.files |
Exact file paths that can be accessed |
allowed.directories |
Directories (and their contents) that can be accessed |
Paths are relative to the server root (the same directory where server.properties lives).
Authentication
Generate a token in-game or via console:
/filed generate <name>
Requires op permissions. The token is shown once and cannot be retrieved later.
Use the token in requests by including Bearer <token> as the Authorization header.
API
Read
GET /files?path=<path>&content=<true|false>
Example response for files:
{
"type": "file",
"path": "server.properties",
"content": "..."
}
Example response for directories: [does not include directories nor sub-directory files]
{
"type": "directory",
"path": "world/stats",
"files": [
{"type": "file", "path": "player.json", "content": "..."}
]
}
Set content=false to omit file contents.
Write
PUT /files?path=<path>
Content-Type: text/plain
<file content>
Creates or overwrites the file. Parent directory must exist. Returns the file contents of the modified file. Only files can be written to.
Delete
DELETE /files?path=<path>
Returns the deleted file's content in the response. Only files can be deleted, not directories.
Health Check
GET /health
This endpoint can be checked without authorisation, and can be used just to make sure that the API endpoint is up and running. Returns {"message": "ok"} if it's all good.
Errors
Example unsuccessful response:
{
"error": "forbidden",
"message": "path not allowed by existing configuration rules"
}
The full list of all error codes and their meaning:
| Error |
Code |
Meaning |
unauthorized |
401 |
Missing or invalid token |
forbidden |
403 |
Path not in whitelist or symlink escape |
not_found |
404 |
File doesn't exist |
invalid_path |
400 |
Provided path isn't valid |
is_directory |
400 |
Can't write/delete directories |
parent_not_found |
400 |
Parent directory doesn't exist (for writes) |
too_large |
413 |
File exceeds size limit |
Security
- Paths are normalized and checked against the whitelist before any operation, escaping any
.. traversal.
- Symlinks that resolve outside the server root are rejected.
- Tokens are SHA-256 hashed before storage, and used just to verify access.
- Configurable file size limits prevent memory exhaustion.
- Sub-directory traversal is not permitted. If a directory is requested, only the files included in that directory are returned.
评论 0
登录后参与评分
还没有评论,来抢沙发吧