Pages API

面向 CICD、脚本和 AI 工具的项目与文件接口。基址：https://pages.taoliya.cn/api/v1

认证与权限

登录管理台，在“开发者接入”创建 key。格式固定为 taoliya-pages- 加 16 位随机字母数字；完整 key 仅显示一次，服务端保存哈希。

Authorization: Bearer $PAGES_API_KEY
# 也支持 X-API-Key 请求头。请不要把 key 放在 URL 中。

read 允许查询和下载，write 允许创建、改名、签名上传与发布，delete 允许删除。key 只能操作所属用户；管理员 key 也遵守此限制。撤销、过期或账号停用后立即失效。脚本 key 独立于登录密码，请在不再使用时手动撤销。

端点

方法	路径	权限	内容
GET	`/projects`	read	返回 `{projects:[{name,fileCount,size,entry,updatedAt}]}`
POST	`/projects`	write	JSON `{"project":"demo"}`，创建空项目
GET	`/projects/:project`	read	返回 `{files:[{path,size,updatedAt}]}`
GET	`/projects/:project/files`	read	同上，列出文件
POST	`/projects/:project/rename-challenge`	write	先提交 `{"name":"new-name"}` 获取 2 分钟一次性确认值
PATCH	`/projects/:project`	write	提交 `{"name":"new-name","challenge":"...","confirmation":"RENAME_PROJECT"}`，返回新项目名
DELETE	`/projects/:project`	delete	项目移入回收区，公开地址失效
POST	`/projects/:project/files`	write	multipart 文件/文件夹/ZIP 上传
DELETE	`/projects/:project/files?path=assets/app.js`	delete	删除指定文件，path 必须 URL 编码
GET	`/projects/:project/content?path=index.html`	read	以附件下载一个文件
GET	`/projects/:project/download`	read	下载 ZIP，合并项目文件
POST	`/projects/:project/uploads/sign`	write	JSON `{"path":"assets/app.js","size":123}`
POST	`/projects/:project/uploads/commit`	write	JSON `{"intent":"update","files":[{"key":"staging/...","path":"assets/app.js","size":123}]}`

快速发布

在 CI 密钥管理器配置 PAGES_API_KEY。创建与更新明确区分：新建同名项目返回 409；更新会合并覆盖同路径文件，保留其他文件。

BASE=https://pages.taoliya.cn/api/v1
# 第一次发布：ZIP 无需先创建空项目
curl --fail-with-body -H "Authorization: Bearer $PAGES_API_KEY" \
  -F "files=@dist.zip" -F "mode=zip" -F "intent=create" \
  "$BASE/projects/demo/files"
# 后续发布：更换 intent 为 update
curl --fail-with-body -H "Authorization: Bearer $PAGES_API_KEY" \
  -F "files=@dist.zip" -F "mode=zip" -F "intent=update" \
  "$BASE/projects/demo/files"
# 下载归档
curl --fail-with-body -H "Authorization: Bearer $PAGES_API_KEY" \
  "$BASE/projects/demo/download" -o demo.zip

ZIP 自动移除单一包装目录，例如 dist/index.html 发布为 index.html。多根目录不会移除。ZIP 无法保留加密文件或链接。

文件与文件夹

重复提交 files。可选 paths 是与文件一一对应的 JSON 路径数组；省略时使用文件名。mode 为 files / folder / zip，默认 files；intent 默认 update；destination 是项目内目标目录前缀。

curl --fail-with-body -H "Authorization: Bearer $PAGES_API_KEY" \
  -F "files=@dist/index.html" -F "files=@dist/assets/app.js" \
  -F 'paths=["index.html","assets/app.js"]' -F "intent=update" \
  "$BASE/projects/demo/files"
# 成功返回 {"uploaded":["index.html","assets/app.js"],"existing":[...]}

资源与发布

网页资源使用相对路径即可，目录结构会原样保留。HTML 地址为 https://pages.taoliya.cn/用户名/项目/index.html，公开 HTML 在 sandbox 下运行，不能读取管理台身份或 storage。

调用 uploads/sign，得到 key、path、size、url、method、headers、expiresIn。地址 10 分钟有效，只允许上传对应 staging 对象，不能上传 HTML。
管理台上传统一经服务器校验并发布。API 自动化场景可以使用签名 URL 暂存文件。
调用 uploads/commit 发布，files 填返回的 key、path、size；服务端校验所属项目、真实大小、路径及冲突后写入正式对象。新项目使用 intent=create。

API 直传资源也可与页面文件同批发布：multipart files 放文件，directEntries 字段填直传记录的 JSON 数组，paths 只对应 files，统一提交到 /projects/:project/files。ZIP 始终通过服务器校验并解压发布。

名称、限制与错误

用户名和项目名使用小写字母数字，可含点、下划线、短横线，最长 64 字符，首位必须是字母数字。保留名称（api、docs、assets、sites 等）、Windows 设备名、隐藏文件、ADS、尾部点、符号链接和大小写歧义路径会被拒绝。

每次最多 1000 个文件，上传或 ZIP 解压总量不超过 100 MB。项目 ZIP 下载最大 512 MB，更大项目请按文件下载。改名会改变公开 URL 与资源基址；已写死旧地址的 HTML/CSS 需重新构建发布。

错误返回 JSON {"error":true,"message":"..."}。400 输入错误，401 key 无效，403 权限不足，404 项目/文件不存在，409 名称或目录冲突，413 超出限制，503 文件服务未启用。操作日志包含动作、项目、来源、key 名称及 HTTP 状态码，不保存请求中的密钥。