Appearance
API 参考
MengStack v2.0 全部 API 接口文档,基于源码 app.go 路由注册整理。
基础信息
| 项目 | 说明 |
|---|---|
| 默认端口 | 2222 |
| 基础路径 | /api/v1 |
| 数据格式 | JSON |
| 认证方式 | Bearer Token (JWT HS256) |
| 租户标识 | X-Tenant-ID 请求头 |
| 请求追踪 | X-Request-ID(未提供时自动生成 UUID) |
| Swagger | /swagger/index.html(仅 debug 模式) |
统一响应格式
json
{
"code": 0,
"message": "success",
"data": {},
"trace_id": "uuid"
}code: 0成功,code: -1错误- 错误时
data字段省略
分页响应
json
{
"code": 0,
"message": "success",
"data": {
"items": [],
"total": 100,
"page": 1
}
}查询参数:page(默认 1)、page_size(默认 20,最大 100)。
错误码
| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| INVALID_PARAM | 400 | 参数错误 |
| TENANT_REQUIRED | 400 | 缺少租户标识 |
| UNAUTHORIZED | 401 | 未认证 |
| TOKEN_EXPIRED | 401 | Token 已过期 |
| TOKEN_INVALID | 401 | Token 无效 |
| PASSWORD_WRONG | 401 | 密码错误 |
| REFRESH_TOKEN_INVALID | 401 | Refresh Token 无效 |
| FORBIDDEN | 403 | 权限不足 |
| NOT_FOUND | 404 | 资源不存在 |
| USER_NOT_FOUND | 404 | 用户不存在 |
| CONFLICT | 409 | 资源冲突 |
| USER_EXISTS | 409 | 用户已存在 |
| RATE_LIMITED | 429 | 请求过于频繁 |
| BODY_TOO_LARGE | 413 | 请求体过大 |
| INTERNAL_ERROR | 500 | 服务器内部错误 |
系统端点(无需认证)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /health | 完整健康检查(DB + Redis + 版本) |
| GET | /healthz | K8s 存活探针 |
| GET | /readyz | K8s 就绪探针(DB + Redis 均连接才 200) |
| GET | /api/version | 构建版本信息 |
| GET | /api/upgrade/check | 升级检查 |
| GET | /swagger/*any | Swagger UI(仅 debug 模式) |
认证接口
公开路由(可选租户)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/auth/register | 用户注册 |
| POST | /api/v1/auth/login | 用户登录 |
| POST | /api/v1/auth/refresh | 刷新 Token |
注册
json
// POST /api/v1/auth/register
{
"username": "admin", // 3-64 字符
"email": "admin@example.com",
"password": "P@ssw0rd123", // 8-128 字符
"nickname": "管理员"
}登录
json
// POST /api/v1/auth/login
{
"email": "admin@example.com",
"password": "P@ssw0rd123"
}
// 响应
{
"code": 0,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_in": 1800
}
}受保护路由(需 Auth + Tenant)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/ping | 连通测试 |
| GET | /api/v1/profile | 获取当前用户信息 |
| POST | /api/v1/password | 修改密码 |
用户管理
需要认证 + 租户 + 对应权限。
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/users | auth.user.read |
| POST | /api/v1/users | auth.user.write |
| GET | /api/v1/users/:id | auth.user.read |
| PUT | /api/v1/users/:id | auth.user.write |
| DELETE | /api/v1/users/:id | auth.user.write |
用户 DTO
json
{
"id": 1,
"tenant_id": "uuid",
"username": "admin",
"email": "admin@example.com",
"nickname": "管理员",
"avatar": "",
"status": "active",
"last_login": "2026-10-01T00:00:00Z"
}WebSocket
| 方法 | 路径 | 认证 |
|---|---|---|
| GET | /api/v1/ws | Bearer Token |
连接后通过 16 分片 Hub 管理,支持心跳保活和在线状态追踪。
RBAC 角色权限
需要认证 + 租户。
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/rbac/permissions | rbac.permission.read |
| POST | /api/v1/rbac/roles | rbac.role.write |
| GET | /api/v1/rbac/roles | rbac.role.read |
| GET | /api/v1/rbac/roles/:id | rbac.role.read |
| PUT | /api/v1/rbac/roles/:id | rbac.role.write |
| DELETE | /api/v1/rbac/roles/:id | rbac.role.write |
| PUT | /api/v1/rbac/roles/:id/permissions | rbac.permission.assign |
| GET | /api/v1/rbac/roles/:id/permissions | rbac.permission.read |
| POST | /api/v1/rbac/users/:userId/roles | rbac.user_role.write |
| DELETE | /api/v1/rbac/users/:userId/roles/:roleId | rbac.user_role.write |
| GET | /api/v1/rbac/users/:userId/roles | rbac.role.read |
组织架构
需要认证 + 租户。
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/org/tenants | org.tenant.write |
| GET | /api/v1/org/tenants | org.tenant.read |
| GET | /api/v1/org/tenants/:id | org.tenant.read |
| PUT | /api/v1/org/tenants/:id | org.tenant.write |
| DELETE | /api/v1/org/tenants/:id | org.tenant.write |
审计日志
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/audit/logs | audit.log.read |
查询参数:user_id、action、resource、page、page_size。
系统设置
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/settings | settings.read |
| GET | /api/v1/settings/global/:key | settings.read |
| PUT | /api/v1/settings/global/:key | settings.write |
| GET | /api/v1/settings/tenant | settings.read |
| GET | /api/v1/settings/tenant/:key | settings.read |
| PUT | /api/v1/settings/tenant/:key | settings.write |
| DELETE | /api/v1/settings/tenant/:key | settings.write |
通知
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/notifications | notification.manage |
| DELETE | /api/v1/notifications/:id | notification.manage |
| GET | /api/v1/notifications/user/:userId | notification.manage |
| GET | /api/v1/notifications/:id | 任意认证用户 |
| PUT | /api/v1/notifications/:id/read | 任意认证用户 |
| PUT | /api/v1/notifications/read-all | 任意认证用户 |
| GET | /api/v1/notifications/unread-count | 任意认证用户 |
Dashboard
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/dashboard/stats | dashboard.read |
CMS 插件
公开路由(仅需租户)
| 方法 | 路径 |
|---|---|
| GET | /api/v1/cms/articles |
| GET | /api/v1/cms/articles/:id |
| POST | /api/v1/cms/articles/:id/view |
| GET | /api/v1/cms/channels |
| GET | /api/v1/cms/channels/:id |
| GET | /api/v1/cms/categories |
| GET | /api/v1/cms/categories/:id |
| GET | /api/v1/cms/tags |
| GET | /api/v1/cms/tags/:id |
| GET | /api/v1/cms/media |
| GET | /api/v1/cms/media/:id |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/cms/articles | cms.article.write |
| PUT | /api/v1/cms/articles/:id | cms.article.write |
| DELETE | /api/v1/cms/articles/:id | cms.article.write |
| GET | /api/v1/cms/article-versions | cms.article.read |
| GET | /api/v1/cms/article-versions/:id | cms.article.read |
| POST | /api/v1/cms/article-versions/:id/restore | cms.article.write |
| POST | /api/v1/cms/channels | cms.channel.write |
| PUT | /api/v1/cms/channels/:id | cms.channel.write |
| DELETE | /api/v1/cms/channels/:id | cms.channel.write |
| POST | /api/v1/cms/categories | cms.category.write |
| PUT | /api/v1/cms/categories/:id | cms.category.write |
| DELETE | /api/v1/cms/categories/:id | cms.category.write |
| POST | /api/v1/cms/tags | cms.tag.write |
| PUT | /api/v1/cms/tags/:id | cms.tag.write |
| DELETE | /api/v1/cms/tags/:id | cms.tag.write |
| POST | /api/v1/cms/media/upload | cms.media.write |
| PUT | /api/v1/cms/media/:id | cms.media.write |
| DELETE | /api/v1/cms/media/:id | cms.media.write |
评论互动插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/comments/:target_type/:target_id |
| GET | /api/v1/comments/replies/:id |
| GET | /api/v1/likes/:target_type/:target_id/count |
| GET | /api/v1/favorites/:target_type/:target_id/count |
| GET | /api/v1/shares/:target_type/:target_id/count |
| GET | /api/v1/stats/:target_type/:target_id |
| POST | /api/v1/stats/:target_type/:target_id/view |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/comments | 认证即可 |
| DELETE | /api/v1/comments/:id | 认证即可 |
| POST | /api/v1/comments/:id/approve | comment.moderate |
| POST | /api/v1/comments/:id/reject | comment.moderate |
| POST | /api/v1/likes/:target_type/:target_id/toggle | 认证即可 |
| GET | /api/v1/likes/:target_type/:target_id/check | 认证即可 |
| POST | /api/v1/favorites/:target_type/:target_id/toggle | 认证即可 |
| GET | /api/v1/favorites/:target_type/:target_id/check | 认证即可 |
| POST | /api/v1/reports | 认证即可 |
| GET | /api/v1/reports | comment.read |
| POST | /api/v1/reports/:id/handle | comment.report.manage |
| POST | /api/v1/shares | 认证即可 |
专题插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/topics |
| GET | /api/v1/topics/:id |
| GET | /api/v1/topics/:id/articles |
| POST | /api/v1/topics/:id/view |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/topics | topic.write |
| GET | /api/v1/topics/all | topic.read |
| PUT | /api/v1/topics/:id | topic.write |
| DELETE | /api/v1/topics/:id | topic.write |
| POST | /api/v1/topics/:id/articles | topic.write |
| DELETE | /api/v1/topics/:id/articles/:article_id | topic.write |
快讯插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/flash |
| GET | /api/v1/flash/timeline |
| GET | /api/v1/flash/:id |
| POST | /api/v1/flash/:id/view |
| GET | /api/v1/flash-categories |
| GET | /api/v1/flash-categories/:id |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/flash-all | flash.read |
| POST | /api/v1/flash | flash.write |
| PUT | /api/v1/flash/:id | flash.write |
| DELETE | /api/v1/flash/:id | flash.write |
| POST | /api/v1/flash-categories | flash.category.write |
| GET | /api/v1/flash-categories/all | flash.read |
| PUT | /api/v1/flash-categories/:id | flash.category.write |
| DELETE | /api/v1/flash-categories/:id | flash.category.write |
社区插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/community/boards |
| GET | /api/v1/community/boards/:id |
| GET | /api/v1/community/posts |
| GET | /api/v1/community/posts/featured |
| GET | /api/v1/community/posts/:id |
| POST | /api/v1/community/posts/:id/view |
| GET | /api/v1/community/boards/:id/posts |
| GET | /api/v1/community/posts/:id/replies |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/community/boards/list | community.board.read |
| POST | /api/v1/community/boards | community.board.write |
| PUT | /api/v1/community/boards/:id | community.board.write |
| DELETE | /api/v1/community/boards/:id | community.board.write |
| GET | /api/v1/community/posts/list | community.post.read |
| POST | /api/v1/community/posts | community.post.write |
| PUT | /api/v1/community/posts/:id | community.post.write |
| DELETE | /api/v1/community/posts/:id | community.post.write |
| POST | /api/v1/community/posts/:id/replies | community.post.write |
| DELETE | /api/v1/community/replies/:id | community.post.write |
搜索插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/search |
| GET | /api/v1/search/suggest |
| GET | /api/v1/search/hot-words |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/search/logs | search.log.read |
| GET | /api/v1/search/top-queries | search.log.read |
| POST | /api/v1/search/hot-words | search.hotword.write |
| GET | /api/v1/search/hot-words/all | search.log.read |
| DELETE | /api/v1/search/hot-words/:id | search.hotword.write |
SEO 插件
公开路由
| 方法 | 路径 |
|---|---|
| GET | /api/v1/seo/tdk |
| GET | /api/v1/seo/sitemap.xml |
| GET | /api/v1/seo/robots.txt |
| GET | /api/v1/seo/links/active |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/v1/seo/config | seo.config.write |
| PUT | /api/v1/seo/config | seo.config.write |
| POST | /api/v1/seo/sitemap | seo.sitemap.write |
| GET | /api/v1/seo/sitemap | seo.config.write |
| DELETE | /api/v1/seo/sitemap/:id | seo.sitemap.write |
| POST | /api/v1/seo/robots | seo.redirect.write |
| GET | /api/v1/seo/robots | seo.config.write |
| DELETE | /api/v1/seo/robots/:id | seo.redirect.write |
| POST | /api/v1/seo/redirects | seo.redirect.write |
| GET | /api/v1/seo/redirects | seo.config.write |
| PUT | /api/v1/seo/redirects/:id | seo.redirect.write |
| DELETE | /api/v1/seo/redirects/:id | seo.redirect.write |
| POST | /api/v1/seo/links | seo.link.write |
| GET | /api/v1/seo/links | seo.config.write |
| DELETE | /api/v1/seo/links/:id | seo.link.write |
| GET | /api/v1/seo/push-records | seo.config.write |
Example 插件
| 方法 | 路径 |
|---|---|
| POST | /api/v1/examples |
| GET | /api/v1/examples |
| GET | /api/v1/examples/:id |
| DELETE | /api/v1/examples/:id |
Media 插件
公开路由(仅需租户)
| 方法 | 路径 |
|---|---|
| GET | /api/v1/media/raw/:file_id |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/media/upload | media.write |
| POST | /api/v1/media/uploads/init | media.write |
| GET | /api/v1/media/uploads/:upload_id | media.write |
| PUT | /api/v1/media/uploads/:upload_id/chunks/:index | media.write |
| POST | /api/v1/media/uploads/:upload_id/complete | media.write |
| POST | /api/v1/media/uploads/:upload_id/abort | media.write |
| POST | /api/v1/media/batch-delete | media.delete |
| POST | /api/v1/media/batch-move | media.write |
| POST | /api/v1/media/batch-download | media.read |
| GET | /api/v1/media/styles | media.read |
| POST | /api/v1/media/styles | media.manage |
| PUT | /api/v1/media/styles/:id | media.manage |
| DELETE | /api/v1/media/styles/:id | media.manage |
| GET | /api/v1/media/audits | media.audit |
| POST | /api/v1/media/audits/:file_id | media.audit |
| GET | /api/v1/media/quota | media.read |
| PUT | /api/v1/media/quota | media.manage |
| GET | /api/v1/media/stats | media.read |
| GET | /api/v1/media/folders | media.read |
| POST | /api/v1/media/folders | media.write |
| PUT | /api/v1/media/folders/:id | media.write |
| DELETE | /api/v1/media/folders/:id | media.write |
| GET | /api/v1/media | media.read |
| GET | /api/v1/media/:id | media.read |
| PUT | /api/v1/media/:id | media.write |
| DELETE | /api/v1/media/:id | media.delete |
| POST | /api/v1/media/:id/restore | media.delete |
| DELETE | /api/v1/media/:id/force | media.manage |
| GET | /api/v1/media/:id/references | media.read |
| GET | /api/v1/media/:id/audit-logs | media.audit |
| POST | /api/v1/media/:id/signed-url | media.read |
Author 插件
公开路由(仅需租户)
| 方法 | 路径 |
|---|---|
| GET | /api/v1/authors/:id |
| GET | /api/v1/authors/:id/articles |
受保护路由
| 方法 | 路径 | 权限 |
|---|---|---|
| POST | /api/v1/authors/apply | 认证即可 |
| GET | /api/v1/authors/me | 认证即可 |
| PUT | /api/v1/authors/me | 认证即可 |
| GET | /api/v1/admin/authors | author.manage |
| PUT | /api/v1/admin/authors/:id/level | author.manage |
| GET | /api/v1/admin/authors/applications | author.manage |
| POST | /api/v1/admin/authors/applications/:id/approve | author.manage |
| POST | /api/v1/admin/authors/applications/:id/reject | author.manage |
请求头
所有受保护接口必须携带:
Authorization: Bearer <access_token>
X-Tenant-ID: <tenant_uuid>在线调试
- Swagger UI — 在线测试 API

