常用业务接口清单,按应用归类。接口是否可用取决于系统版本、登录身份和相应权限。通用约定见 12 API 与路由,错误处理见 27 常见问题与错误处理。
文档中的 /admin/ 是示例前缀,自定义后台路径后应使用站点当前配置的前缀。真实密码、令牌和 API Key 不应出现在公开示例或日志中。
通用约定
- 路径:
/{app}/{控制器}/{动作}(控制器名转蛇形,如 ThemeTpl → theme_tpl)
- 响应:
{ "status": 200, "msg": "...", "data": ... }
- 鉴权:需登录的接口带
Authorization: Bearer <JWT>(开放 API 兼容 JWT <token>)
- 列表分页:
data: { list: [], total: N }
一、前台公开接口(/home,无需登录)
Content 内容
| 方法 |
路径 |
说明 |
| GET |
/home/content/siteConfig |
站点 + 主题 bundle(站名、导航、SEO、主题配置) |
| GET |
/home/content/maintenance |
维护公告 |
| GET |
/home/content/affClick |
推广链接点击记录 |
| GET |
/home/content/banners |
轮播图 |
| GET |
/home/content/announcements |
公告列表 |
| GET |
/home/content/announcement?id= |
公告详情 |
| GET |
/home/content/kb |
知识库分类+文章树 |
| GET |
/home/content/kbArticle?id= |
知识库文章详情 |
Store 商店
| 方法 |
路径 |
说明 |
| GET |
/home/store/catalog |
商品组树 + 商品 + 最低价 |
| GET |
/home/store/group?id= |
单商品组及其商品 |
| GET |
/home/store/product?id= |
商品详情(定价 + 可配置选项;上游商品可能返回跳转) |
| GET |
/home/store/redirect?id= |
上游代理商品 301 跳转 |
主题 SSR(魔方 .tpl)
| 方法 |
路径 |
说明 |
| GET |
/tpl/home、/tpl/cart |
美化路由,转发到 theme_tpl/page |
| GET |
/home/theme_tpl/render?type=&page= |
渲染指定模板(HTML 或 format=json) |
| GET |
/home/theme_tpl/page?path= |
SSR 首页/购物车入口 |
二、会员中心接口(/home,需登录)
说明
鉴权:UserAuth 中间件校验 Authorization: Bearer <JWT>(type=user)。
Auth 账户
| 方法 |
路径 |
说明 |
| POST |
/home/auth/register |
注册 |
| POST |
/home/auth/login |
登录换 JWT |
| GET |
/home/auth/me |
当前用户信息 |
| POST |
/home/auth/logout |
登出 |
| POST |
/home/auth/realname |
提交实名认证 |
| GET |
/home/auth/realnameQuery |
查询实名结果 |
Console 控制台
| 方法 |
路径 |
说明 |
| GET |
/home/console/summary |
概览统计 |
| GET |
/home/console/services |
我的服务实例列表 |
| GET |
/home/console/service?id= |
服务实例详情 |
| GET |
/home/console/invoices |
我的账单 |
| POST |
/home/console/updateProfile |
修改资料 |
| POST |
/home/console/changePassword |
修改密码 |
Order 下单
| 方法 |
路径 |
说明 |
| POST |
/home/order/create |
创建订单(生成账单) |
| POST |
/home/order/checkPromo |
校验优惠码 |
| GET |
/home/order/index |
我的订单 |
Invoice 账单 / 支付
| 方法 |
路径 |
说明 |
| GET |
/home/invoice/read?id= |
账单详情 |
| GET |
/home/invoice/methods |
可用支付方式 |
| POST |
/home/invoice/pay |
发起在线支付 |
| POST |
/home/invoice/payCredit |
余额支付 |
| GET |
/home/invoice/status?id= |
支付状态轮询 |
Ticket 工单
| 方法 |
路径 |
说明 |
| GET |
/home/ticket/departments |
工单部门 |
| GET |
/home/ticket/index |
工单列表 |
| POST |
/home/ticket/create |
新建工单(可携带附件) |
| GET |
/home/ticket/read?id= |
工单详情(含附件) |
| POST |
/home/ticket/reply |
回复工单(可携带附件) |
| POST |
/home/ticket/close |
关闭工单 |
| POST |
/home/ticket/upload |
上传工单附件(≤500MB,最多 20 个) |
Affiliate 推广
| 方法 |
路径 |
说明 |
| GET |
/home/affiliate/index |
推广概况 |
| GET |
/home/affiliate/commissions |
佣金明细 |
| POST |
/home/affiliate/withdraw |
申请提现 |
| GET |
/home/affiliate/withdrawals |
提现记录 |
三、开放 API v1(/api/v1,上下游对接)
供下游系统代理本系统商品。下游用「本系统账号 + API 密钥」换 JWT(2 小时),后续请求带 Authorization: JWT <token>(兼容 Bearer)。下单计入该账号名下并用账号余额实时结算。
| 方法 |
路径 |
说明 |
| POST |
/api/v1/login |
username + password(API密钥) → JWT(含 IP 白名单校验) |
| GET |
/api/v1/products |
商品目录 |
| GET |
/api/v1/productsconfig?id= |
商品详情(可配置选项 + 定价) |
| POST |
/api/v1/order |
下单并用余额结算,返回开通凭据 |
| GET |
/api/v1/host?id= |
服务实例详情(状态轮询/凭据) |
| POST |
/api/v1/renew?id= |
续费并用余额结算 |
| GET |
/api/v1/credit |
余额查询 |
示例:登录 + 下单
# 1. 换取 JWT
curl -X POST https://你的域名/api/v1/login \
-d "username=downstream@x.com&password=<API密钥>"
# → { "status":200, "data": { "jwt":"...", "expire":7200 } }
# 2. 下单(余额结算)
curl -X POST https://你的域名/api/v1/order \
-H "Authorization: JWT <jwt>" \
-d "product_id=18&billing_cycle=monthly&qty=1"
# → { "status":200, "data": { "order_num":"...","hosts":[{...凭据}] } }
API 密钥在后台 上下游 → API 密钥(/admin/api_key/*)管理,可设 IP 白名单。
四、支付回调(/api)
支付通知地址使用网关配置页生成的结果,服务端请求方式以所选驱动约定为准。浏览器同步返回仅用于展示,付款结果以服务器核验后的账单为准。详见支付网关。
五、后台接口
后台接口数量较多,按权限模块组织,操作语义见 25 管理员操作文档。统一前缀 /admin/{控制器}/{动作},需 AdminAuth + 模块权限。常见模式:index(列表)、read(详情)、create/update/delete(增改删)。
下一篇:25 管理员操作文档