Verhub 文档

Appearance

用户指南 ​

本指南面向平台管理员与运营人员。

角色说明 ​

  • 管理员：维护项目、版本、公告、反馈与日志
  • API 调用方：使用 API Key 调用对外接口

后台页面说明 ​

后台入口为 /admin，左侧菜单包含以下页面：

  1. 概览
  • 查看项目数、Token 数、版本/公告/反馈/日志统计
  • 用于发布前后快速巡检
  1. 项目管理
  • 新建、编辑、删除项目
  • 维护 project_key、名称、仓库地址、官网、作者、发布时间等
  • 在项目列表中可直接打开“项目展示页”链接（/projects/{project_key}）
  1. 版本管理
  • 选择项目后发布版本、编辑版本、删除版本
  • 维护语义化版本号、可比较版本号、里程碑、更新内容、下载地址、平台、发布时间
  • 支持 latest/preview、废弃标记等发布策略
  1. 公告管理
  • 选择项目后发布公告
  • 支持置顶、发布时间与正文内容维护
  1. 行为管理
  • 维护行为定义（动作名称、描述、扩展字段）
  • 查看客户端上报的行为记录，用于运营分析
  1. 反馈管理
  • 查看用户反馈、评分、平台信息
  • 跟进处理状态并沉淀处理结果
  1. 日志管理
  • 按项目、级别、时间范围筛选日志
  • 用于故障排查和审计复盘
  1. Token 管理
  • 创建、轮换、撤销 API Key
  • 设置权限范围、项目范围、过期时间
  1. 管理员设置
  • 修改管理员账号与密码
  • 保存后需要重新登录

常见操作流程 ​

1. 新建项目 ​

手动创建 ​

  1. 登录后台
  2. 进入项目管理
  3. 填写项目 key、名称、仓库地址等信息

从 GitHub 获取项目信息 ​

  1. 登录后台
  2. 进入项目管理
  3. 在“仓库地址”字段中输入 GitHub 仓库地址（如 https://github.com/IvanHanloth/Verhub）
  4. 点击“从 GitHub 获取项目信息”按钮，系统会自动拉取仓库信息并填充项目名称、作者、官网等字段，用户可根据需要进行编辑后保存。

2. 发布版本 ​

手动发布 ​

  1. 选择指定项目
  2. 填写版本号、发布说明、下载链接
  3. 根据需求设置 latest 或 preview

从 Github 获取版本 ​

  1. 选择指定项目，如果项目已绑定 GitHub 仓库，则会显示“从 GitHub Release 获取”按钮
  2. 如直接点击“从 GitHub Release 获取”，会自动拉取最新的 Release 作为版本草稿
  3. 如输入版本号后点击“从 GitHub Release 获取”，会尝试拉取指定版本号的 Release 作为版本草稿，若该版本不存在则会提示错误
  4. 获取到的版本草稿会自动填充版本信息与发布说明、设置 latest/preview 状态，用户可根据需要进行编辑后发布

从 Github 导入历史版本 ​

  1. 选择指定项目，如果项目已绑定 GitHub 仓库，则会显示“从 GitHub 导入历史版本”按钮
  2. 点击按钮后，将会自动拉取并入库该项目在 GitHub 上的所有 Release 版本，用户可在版本列表中查看并编辑这些版本信息。注意，如果获取到的版本号已存在则会被跳过以避免覆盖现有版本。

更新策略与判定逻辑 ​

公开更新接口：

  • GET /api/v1/public/{projectKey}/versions/by-version/{version}
  • GET /api/v1/public/{projectKey}/versions/latest-preview
  • POST /api/v1/public/{projectKey}/versions/check-update

判定核心：

  1. 比较当前版本与目标版本（按 comparable_version）
  2. 检查是否超出项目级可选更新范围
  3. 检查当前版本是否被废弃
  4. 检查是否触发里程碑拦截（必须先升到当前里程碑最新）

判定结果通过以下字段返回：

  • should_update
  • required
  • reason_codes
  • target_version

后台配置方法（重点） ​

1. 项目管理页配置“可选更新范围” ​

在项目表单中配置：

  • 可选更新范围下限（optional_update_min_comparable_version）
  • 可选更新范围上限（optional_update_max_comparable_version）

说明：

  • 当前版本在范围内：可以提示更新但不强制
  • 当前版本不在范围内：遇到新版本将触发必更

2. 版本管理页配置“版本策略” ​

在版本表单中配置：

  • version：展示版本号
  • comparable_version：用于比较的版本号
  • milestone：里程碑标识
  • is_deprecated：是否废弃（勾选后该版本必更）

建议：

  • 版本发布时同时维护 version 与 comparable_version
  • milestone 使用稳定命名（如 M1/M2）
  • 废弃版本需配合公告说明升级理由与目标版本

3. 发布公告 ​

  1. 进入公告管理
  2. 绑定项目并编辑正文
  3. 发布后前台与 API 可见

4. 处理反馈 ​

  1. 进入反馈管理
  2. 按状态筛选待处理项
  3. 更新状态并记录处理结论

API Key 使用建议 ​

  • 为不同系统生成独立 Key，便于追踪与撤销
  • 设置合理过期时间，避免长期暴露风险
  • 仅授予必要权限与项目范围
  • 定期轮换 Key 并监控使用情况

安全与审计建议 ​

  1. 定期轮换敏感凭据
  2. 监控异常请求频率
  3. 对关键管理操作保留审计记录

Released under the Apache 2.0 License.

Copyright © 2026 Verhub by IvanHanloth