用文件夹文件搭建资料公告板

将 Markdown 文档和图片保存到 books/guide 文件夹，并在 Webspace 中配置一个提供文件列表和所选文件内容的公告板。无需把帖子复制到数据库，即可直接将文件夹中的文件用作资料原件。

开始之前

需要部署架构和 API 的权限。
将要在公告板中提供的文件准备到 books/guide 文件夹。
先根据公开范围确定端点的读取权限。

示例中只提供 .md 和 .png，不查询子文件夹。

books/
└── guide/
    ├── getting-started.md
    ├── permissions.md
    └── permissions.png

配置目录端点

示例中 数据库标识符 使用 guide，表名使用 assets，自定义路径使用 content。

打开架构文件，选择 API 构建。
在 assets 表中选择 添加静态文件 API。
在自定义路径中输入 content。
在 公开对象 中选择 文件夹列表 · 文件内容。
在 选择文件夹 中选择 books/guide。
在 允许的扩展名 中添加 .md 和 .png。
如需连同子文件夹一起提供，打开 包含子文件夹。本示例中保持关闭。
根据公告板的公开范围设置端点权限。

设置后得到的静态文件契约如下。

{
  "mode": "directory",
  "extensions": [".md", ".png"],
  "recursive": false
}

mode 为提供单个文件的 file 或提供文件夹的 directory 之一。extensions 是允许响应的扩展名列表。recursive 为 false 时，列表只包含 books/guide 正下方的文件。如需同时提供子文件夹中的文件，请将 recursive 设为 true。

部署 API

在屏幕底部固定的部署栏中选择 部署，将面板向上展开。此步骤尚不会执行部署。
在 数据库标识符 中输入 guide，并确认 存储引擎模式 和 客户端部署路径。
在展开的面板中再次选择 部署。
部署完成后，在 /api/web/guide/assets/content 确认列表响应。

加载文件列表

不指定文件而直接请求目录端点时，会返回 JSON 列表。

{
  "items": [
    {
      "name": "getting-started.md",
      "path": "getting-started.md",
      "size": 1842,
      "mimeType": "text/markdown; charset=utf-8",
      "modifiedAt": "2026-10-02T09:30:00Z",
      "url": "/api/web/guide/assets/content?file=getting-started.md"
    }
  ],
  "total": 3,
  "offset": 0,
  "limit": 20
}

在列表界面中，以 name 作为标题显示，选择文件时使用 url。通过 total 查看结果总数，通过 offset 和 limit 查看当前区间。

可以通过以下查询参数缩小列表范围。

查询	示例	用途
`q`	`q=permission`	搜索文件名。
`order`	`order=name:asc`	按名称升序排序。
`order`	`order=modifiedAt:desc`	从最近修改的文件开始排序。
`offset`	`offset=20`	指定要跳过的文件数。
`limit`	`limit=20`	指定一次返回的文件数。

GET /api/web/guide/assets/content?q=permission&order=modifiedAt:desc&offset=0&limit=20

省略 limit 时返回 50 个，单次请求的最大值为 200。如果文件更多，请查看响应中的 total 并增大 offset 来请求下一页列表。省略 order 时应用 name:asc，q 最多 256 个字符。

显示所选文档

将列表中得到的相对路径传入 file 查询参数，即可获取该文件的内容。子文件的相对路径仅在 recursive 为 true 时可用。

GET /api/web/guide/assets/content?file=getting-started.md

.md 文件使用 Markdown 渲染器显示正文，.png 文件用作图片 URL。与其在客户端自行拼接文件路径，不如使用列表响应中的 url，这样更容易应对端点路径的变更。

注意事项

extensions 中只放入要公开的格式。示例中只允许 .md 和 .png。
扩展名最多可指定 32 个。
以点（.）开头的隐藏文件、隐藏文件夹和符号链接不会在列表和文件请求中提供。
不能使用移动到原始文件夹之外的相对路径。
列表和文件内容应用同一个端点 ACL。公开端点要明确指定 login: false，成员端点还要确认所需的角色、等级和团队条件。
为了生成准确的 total 和排序结果，服务器最多扫描 2,000 个文件和文件夹。因隐藏路径或扩展名筛选而被排除在响应之外的项目也计入扫描数。超过上限时不会返回部分列表，而是以 413 错误拒绝整个请求。
添加或修改文件后，确认列表中的 modifiedAt 和界面内容是否已更新。
在公告板界面中将 Markdown 转换为 HTML 时，确认渲染器策略不允许脚本和危险标记。