内容接口与应用商店接口

路径前缀为什么不能写 /api/v1、返回结构长什么样、只读与写入接口的边界。

路径前缀：只能是 /api/open/v1

/api/v1/ 是被服务器组件（面板）保留的地址，请求会被它先截走， PHP 根本收不到。/api/admin/、/api/vhost/ 同理。所以本程序的内容接口一律挂在 /api/open/v1/ 下。

返回结构

{
  "code": 0,           // 0 = 成功，非 0 = 失败
  "msg": "ok",
  "data": { }          // 失败时为 null
}

成功返回 code: 0；失败同时给 HTTP 状态码与非 0 的 code，两者语义一致（400 参数错 / 403 无权 / 404 不存在 / 405 方法不对 / 429 太频繁）。

只读接口（默认开放）

地址	取什么
`GET /api/open/v1/site`	站点信息
`GET /api/open/v1/navs`	导航
`GET /api/open/v1/categories`	栏目树
`GET /api/open/v1/category/别名`	单个栏目
`GET /api/open/v1/contents`	内容列表（支持 `cid` / `num` / `page` / `q` 等参数）
`GET /api/open/v1/content/别名或id`	内容详情
`GET /api/open/v1/tags`	标签
`GET /api/open/v1/banners`	轮播（可用 `group` 指定分组）
`GET /api/open/v1/links`	友情链接
`GET /api/open/v1/docs`	文档目录；`/docs/<slug>` 取单篇

内容与前台页面共用同一套取数层，所以后台能看到什么、接口就能取到什么，不存在两套过滤规则。未发布的内容不会出现在接口里。

限流与跨域

按 IP 限流，阈值在站点设置里配置。超了返回 429。
跨域默认关闭。要给小程序或第三方前端用，在站点设置里填来源白名单，只对你明确列出的来源发 CORS 头。

写入接口

POST /api/open/v1/form/<表单名>
Header: X-APP-KEY: 你的AppKey      （也可以用 ?appkey= 或表单字段 appkey）

Content-Type: application/x-www-form-urlencoded
name=张三&phone=13800000000

用于让外部程序提交自定义表单（留言、报名、询价）。

没配 AppKey 就等于没锁门：当站点设置里的 AppKey 为空时，接口视为开放，任何人都能提交。蜜罐与频率限制仍然生效，但要真正限制调用方，请一定配一个 AppKey 并只发给自己的程序。

应用商店接口（只有官方商店宿主提供）

地址	说明
`GET /api/open/v1/store/items`	商品目录（支持 `cat` / `q`）
`GET /api/open/v1/store/pkg?slug=&lic=&domain=`	凭域名授权码取安装包

授权码本身就是凭据（官方私钥签发、绑定了域名、带有效期），所以这个接口不需要账号体系；反过来，付费商品没有有效授权码就拿不到包（返回 403）。免费商品不需要授权码。

客户站装插件/主题时走的正是这条链路：客户站保存着本机的授权码 → 用授权码去官方换包 → 校验包指纹 → 落地安装。这也是"客户站本机不存别人的安装包"的原因。

调试接口时可以用浏览器直接开只读地址（它们是公开的）。写入接口请用 curl 或 Postman，并注意 /api/open/v1/form/... 只接受 POST。