Skip to content

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_PARAM400参数错误
TENANT_REQUIRED400缺少租户标识
UNAUTHORIZED401未认证
TOKEN_EXPIRED401Token 已过期
TOKEN_INVALID401Token 无效
PASSWORD_WRONG401密码错误
REFRESH_TOKEN_INVALID401Refresh Token 无效
FORBIDDEN403权限不足
NOT_FOUND404资源不存在
USER_NOT_FOUND404用户不存在
CONFLICT409资源冲突
USER_EXISTS409用户已存在
RATE_LIMITED429请求过于频繁
BODY_TOO_LARGE413请求体过大
INTERNAL_ERROR500服务器内部错误

系统端点(无需认证) ​

方法路径说明
GET/health完整健康检查(DB + Redis + 版本)
GET/healthzK8s 存活探针
GET/readyzK8s 就绪探针(DB + Redis 均连接才 200)
GET/api/version构建版本信息
GET/api/upgrade/check升级检查
GET/swagger/*anySwagger 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/usersauth.user.read
POST/api/v1/usersauth.user.write
GET/api/v1/users/:idauth.user.read
PUT/api/v1/users/:idauth.user.write
DELETE/api/v1/users/:idauth.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/wsBearer Token

连接后通过 16 分片 Hub 管理,支持心跳保活和在线状态追踪。

RBAC 角色权限 ​

需要认证 + 租户。

方法路径权限
GET/api/v1/rbac/permissionsrbac.permission.read
POST/api/v1/rbac/rolesrbac.role.write
GET/api/v1/rbac/rolesrbac.role.read
GET/api/v1/rbac/roles/:idrbac.role.read
PUT/api/v1/rbac/roles/:idrbac.role.write
DELETE/api/v1/rbac/roles/:idrbac.role.write
PUT/api/v1/rbac/roles/:id/permissionsrbac.permission.assign
GET/api/v1/rbac/roles/:id/permissionsrbac.permission.read
POST/api/v1/rbac/users/:userId/rolesrbac.user_role.write
DELETE/api/v1/rbac/users/:userId/roles/:roleIdrbac.user_role.write
GET/api/v1/rbac/users/:userId/rolesrbac.role.read

组织架构 ​

需要认证 + 租户。

方法路径权限
POST/api/v1/org/tenantsorg.tenant.write
GET/api/v1/org/tenantsorg.tenant.read
GET/api/v1/org/tenants/:idorg.tenant.read
PUT/api/v1/org/tenants/:idorg.tenant.write
DELETE/api/v1/org/tenants/:idorg.tenant.write

审计日志 ​

方法路径权限
GET/api/v1/audit/logsaudit.log.read

查询参数:user_id、action、resource、page、page_size。

系统设置 ​

方法路径权限
GET/api/v1/settingssettings.read
GET/api/v1/settings/global/:keysettings.read
PUT/api/v1/settings/global/:keysettings.write
GET/api/v1/settings/tenantsettings.read
GET/api/v1/settings/tenant/:keysettings.read
PUT/api/v1/settings/tenant/:keysettings.write
DELETE/api/v1/settings/tenant/:keysettings.write

通知 ​

方法路径权限
POST/api/v1/notificationsnotification.manage
DELETE/api/v1/notifications/:idnotification.manage
GET/api/v1/notifications/user/:userIdnotification.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/statsdashboard.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/articlescms.article.write
PUT/api/v1/cms/articles/:idcms.article.write
DELETE/api/v1/cms/articles/:idcms.article.write
GET/api/v1/cms/article-versionscms.article.read
GET/api/v1/cms/article-versions/:idcms.article.read
POST/api/v1/cms/article-versions/:id/restorecms.article.write
POST/api/v1/cms/channelscms.channel.write
PUT/api/v1/cms/channels/:idcms.channel.write
DELETE/api/v1/cms/channels/:idcms.channel.write
POST/api/v1/cms/categoriescms.category.write
PUT/api/v1/cms/categories/:idcms.category.write
DELETE/api/v1/cms/categories/:idcms.category.write
POST/api/v1/cms/tagscms.tag.write
PUT/api/v1/cms/tags/:idcms.tag.write
DELETE/api/v1/cms/tags/:idcms.tag.write
POST/api/v1/cms/media/uploadcms.media.write
PUT/api/v1/cms/media/:idcms.media.write
DELETE/api/v1/cms/media/:idcms.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/approvecomment.moderate
POST/api/v1/comments/:id/rejectcomment.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/reportscomment.read
POST/api/v1/reports/:id/handlecomment.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/topicstopic.write
GET/api/v1/topics/alltopic.read
PUT/api/v1/topics/:idtopic.write
DELETE/api/v1/topics/:idtopic.write
POST/api/v1/topics/:id/articlestopic.write
DELETE/api/v1/topics/:id/articles/:article_idtopic.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-allflash.read
POST/api/v1/flashflash.write
PUT/api/v1/flash/:idflash.write
DELETE/api/v1/flash/:idflash.write
POST/api/v1/flash-categoriesflash.category.write
GET/api/v1/flash-categories/allflash.read
PUT/api/v1/flash-categories/:idflash.category.write
DELETE/api/v1/flash-categories/:idflash.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/listcommunity.board.read
POST/api/v1/community/boardscommunity.board.write
PUT/api/v1/community/boards/:idcommunity.board.write
DELETE/api/v1/community/boards/:idcommunity.board.write
GET/api/v1/community/posts/listcommunity.post.read
POST/api/v1/community/postscommunity.post.write
PUT/api/v1/community/posts/:idcommunity.post.write
DELETE/api/v1/community/posts/:idcommunity.post.write
POST/api/v1/community/posts/:id/repliescommunity.post.write
DELETE/api/v1/community/replies/:idcommunity.post.write

搜索插件 ​

公开路由 ​

方法路径
GET/api/v1/search
GET/api/v1/search/suggest
GET/api/v1/search/hot-words

受保护路由 ​

方法路径权限
GET/api/v1/search/logssearch.log.read
GET/api/v1/search/top-queriessearch.log.read
POST/api/v1/search/hot-wordssearch.hotword.write
GET/api/v1/search/hot-words/allsearch.log.read
DELETE/api/v1/search/hot-words/:idsearch.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/configseo.config.write
PUT/api/v1/seo/configseo.config.write
POST/api/v1/seo/sitemapseo.sitemap.write
GET/api/v1/seo/sitemapseo.config.write
DELETE/api/v1/seo/sitemap/:idseo.sitemap.write
POST/api/v1/seo/robotsseo.redirect.write
GET/api/v1/seo/robotsseo.config.write
DELETE/api/v1/seo/robots/:idseo.redirect.write
POST/api/v1/seo/redirectsseo.redirect.write
GET/api/v1/seo/redirectsseo.config.write
PUT/api/v1/seo/redirects/:idseo.redirect.write
DELETE/api/v1/seo/redirects/:idseo.redirect.write
POST/api/v1/seo/linksseo.link.write
GET/api/v1/seo/linksseo.config.write
DELETE/api/v1/seo/links/:idseo.link.write
GET/api/v1/seo/push-recordsseo.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/uploadmedia.write
POST/api/v1/media/uploads/initmedia.write
GET/api/v1/media/uploads/:upload_idmedia.write
PUT/api/v1/media/uploads/:upload_id/chunks/:indexmedia.write
POST/api/v1/media/uploads/:upload_id/completemedia.write
POST/api/v1/media/uploads/:upload_id/abortmedia.write
POST/api/v1/media/batch-deletemedia.delete
POST/api/v1/media/batch-movemedia.write
POST/api/v1/media/batch-downloadmedia.read
GET/api/v1/media/stylesmedia.read
POST/api/v1/media/stylesmedia.manage
PUT/api/v1/media/styles/:idmedia.manage
DELETE/api/v1/media/styles/:idmedia.manage
GET/api/v1/media/auditsmedia.audit
POST/api/v1/media/audits/:file_idmedia.audit
GET/api/v1/media/quotamedia.read
PUT/api/v1/media/quotamedia.manage
GET/api/v1/media/statsmedia.read
GET/api/v1/media/foldersmedia.read
POST/api/v1/media/foldersmedia.write
PUT/api/v1/media/folders/:idmedia.write
DELETE/api/v1/media/folders/:idmedia.write
GET/api/v1/mediamedia.read
GET/api/v1/media/:idmedia.read
PUT/api/v1/media/:idmedia.write
DELETE/api/v1/media/:idmedia.delete
POST/api/v1/media/:id/restoremedia.delete
DELETE/api/v1/media/:id/forcemedia.manage
GET/api/v1/media/:id/referencesmedia.read
GET/api/v1/media/:id/audit-logsmedia.audit
POST/api/v1/media/:id/signed-urlmedia.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/authorsauthor.manage
PUT/api/v1/admin/authors/:id/levelauthor.manage
GET/api/v1/admin/authors/applicationsauthor.manage
POST/api/v1/admin/authors/applications/:id/approveauthor.manage
POST/api/v1/admin/authors/applications/:id/rejectauthor.manage

请求头 ​

所有受保护接口必须携带:

Authorization: Bearer <access_token>
X-Tenant-ID: <tenant_uuid>

在线调试 ​

下一步 ​

Released under the Apache 2.0 License.