适用版本：WeBot 管理后台（webot-server）。供系统管理员、机构管理员等后台角色使用。
云主机终端用户使用的 H5 页面（我的工作台）请参阅「云主机用户 H5 使用手册」。
目录
一、系统概述
WeBot 管理后台是 SaaS 平台的 Web 管理端，用于管理：
- 客户端：运行在云主机 / 独立机器上的 WeBot Lite 微信自动化客户端
- 机构与用户：多级机构（总部/区域/门店）、后台账号与角色权限
- 内容与任务：朋友圈 / 视频号内容的 AI 生成、审批与定时分发
- 云主机：云主机配置、客户端启停、微信状态监控（仅系统超级管理员）
- 版本与升级：客户端升级包发布与部署跟踪
后台采用响应式布局（Tailwind CSS），桌面端左侧固定导航栏，移动端通过 ☰ 菜单展开/收起。页面数据通过 REST API + WebSocket 实时更新，大部分列表页带自动刷新。
二、登录与权限体系
2.1 登录方式
访问后台地址（如 http://your-server:8765/login），登录页支持两种方式：
| 方式 | 说明 |
|---|---|
| 账号密码登录 | 输入用户名 + 密码。若账号角色为管理员（system_super_admin / ai_sys_admin / org_super_admin / org_admin），登录成功后写入 admin_token，否则写入 user_token |
| 管理员密码登录 | 账号登录失败（非后台账号）时，系统自动回退使用 .env 中配置的 ADMIN_PASSWORD，登录为系统超级管理员 |
| 微信扫码登录（可选） | 登录页提供微信授权登录入口（依赖服务端微信 OAuth 配置） |
登录成功后跳转规则（路由 /）：
- 管理员角色 → 进入管理后台 Dashboard
- 终端用户角色（
cloud_host_user/standalone_user等）→ 进入 我的工作台（H5 页面）
2.2 角色体系
| 角色代码 | 名称 | 主要权限 |
|---|---|---|
system_super_admin | 系统超级管理员 | 全部功能（自动拥有全部权限码，含客户端管理、云主机管理、环境配置、VNC） |
org_super_admin | 机构超级管理员 | 机构内全部管理功能（不含客户端管理与系统级云主机菜单） |
org_admin | 机构管理员 | 机构内日常管理（用户、分组、任务、内容、审批、智能营销、内容工厂） |
content_editor | 内容编辑 | 内容生成、内容工厂相关权限 |
task_operator | 任务操作员 | 任务查看、执行相关权限 |
cloud_host_user | 云主机用户（终端） | 仅「我的工作台」H5，无管理后台 |
standalone_user | 独立用户（终端） | 仅「我的工作台」H5，无管理后台 |
cloud_host_admin | 云主机管理员 | 云主机配置与用户管理权限 |
角色可在「角色管理」中维护（内置角色只读，由系统统一维护；自定义角色可自由配置权限）。用户与角色在「用户管理」中绑定。权限管理为只读视图，用于核对系统内置权限定义。
2.3 侧边栏导航（权限驱动）
导航菜单的显示由当前用户所属角色的权限码决定，可在「角色管理 → 配置权限」中为自定义角色勾选对应权限码来控制菜单可见性。内置角色默认权限如下：
| 菜单 | 路由 | 所需权限码 | 默认可见角色 |
|---|---|---|---|
| 📊 Dashboard | / | 登录即可 | 所有管理员 |
| 👥 客户端管理 | /clients | client:view | 仅系统超级管理员 |
| 🏢 分组管理 | /groups | group:view | 机构超管、机构管理员 |
| 🏛️ 机构管理 | /organizations | organization:view | 机构超级管理员 |
| 👥 用户管理 | /users | user:view | 机构超管、机构管理员 |
| 🔑 角色管理 | /roles | role:view | 机构超级管理员 |
| 🛡️ 权限管理 | /permissions | permission:view | 机构超级管理员 |
| 📦 版本管理 | /versions | version:view | 机构超级管理员 |
| 📋 任务管理 | /tasks | task:view | 机构超管、机构管理员 |
| 🔔 审批队列 | /approvals | approval:view | 机构超管、机构管理员 |
| ✨ 智能营销 | /generator | generator:use | 机构超管、机构管理员 |
| 🏭 内容工厂 | /content-factory | content_factory:use | 机构超管、机构管理员 |
| ⚙️ 系统设置 | /settings | settings:view | 机构超级管理员 |
| 🖥️ 云主机管理 | /cloud-host | cloud_host:view | 仅系统超级管理员 |
| 🔧 环境配置 | /env-config | system:env_config | 仅系统超级管理员 |
| 🖼️ VNC | /vnc | cloud_host:vnc_connect | 仅系统超级管理员（预留入口） |
操作级权限：页面内各操作按钮（新建/编辑/删除/启停等）同样按权限码显隐，服务端接口亦做同权限校验（如 user:create、group:delete、cloud_host:stop 等），未授权请求返回 403。
底部显示当前登录用户与退出登录按钮。所有时间显示统一为北京时间（UTC+8）。
三、Dashboard 仪表盘
系统概览与实时监控，数据每 30 秒自动刷新。
3.1 统计卡片
| 卡片 | 含义 |
|---|---|
| 总客户数 | 累计注册的客户端总数 |
| 活跃客户 | 当前状态为 active 的客户数 |
| 待处理任务 | pending / assigned 状态的任务数 |
| 今日完成 | 今日成功完成的任务数 |
3.2 在线客户端
显示最近 5 分钟内有心跳的客户端列表（客户端名称、微信昵称、在线状态、最后心跳时间），每 30 秒刷新。
3.3 最近活动
系统审计日志（时间、操作类型、详情描述），每 30 秒刷新。
四、客户端管理
路径：/clients
访问权限：仅系统超级管理员可见（机构管理员、机构超级管理员等角色无此菜单与页面访问权限）。
4.1 客户端列表
展示所有已注册客户端：名称（real_name）、微信昵称、手机号、状态、最后心跳时间。
| 状态 | 标签 | 说明 |
|---|---|---|
| pending | 待审核 | 等待管理员审批 |
| active | 已激活 | 正常活跃，可执行任务 |
| disabled | 已禁用 | 已禁用，无法执行任务 |
支持按状态筛选、按昵称搜索。
4.2 客户端操作
- 审核：审批 pending 状态的客户端
- 启用 / 禁用：控制客户端可用状态
- 编辑：修改客户端信息
- 查看任务：查看该客户端关联的任务执行情况
- 删除：移除客户端（不可恢复，谨慎操作）
五、分组管理
路径：/groups。分组用于将客户端按业务维度组织（如「华东门店」「内容审核组」），任务可面向分组批量分发。
5.1 分组结构
- 支持树形父子分组，勾选父分组自动包含其所有子分组
- 分组列表展示名称、成员数、状态
5.2 常用操作
- 新建分组：填写分组名称，可选选择成员
- 编辑分组：修改名称、描述
- 成员管理：添加 / 移除分组成员（成员为用户或客户端）
- 删除分组：删除后不删除成员本身
分组与机构（Organization）为 M:N 关联，可在机构管理中绑定。
六、机构管理
路径：/organizations。机构（Organization）用于 SaaS 多租户场景下的组织架构管理。
6.1 新建机构
| 字段 | 说明 |
|---|---|
| 机构名称 | 必填，如「华东总部」 |
| 上级机构 | 可选，形成树形层级（总部 → 区域 → 门店） |
| 类型 | 门店 store / 区域 region / 总部 headquarters |
| 描述 | 可选 |
6.2 机构列表与详情
- 机构列表展示名称、类型、层级、关联分组数等
- 点击可查看机构详情：基本信息、关联分组、机构内用户
- 支持编辑、删除（删除前需确认无关联数据）
6.3 机构与分组关联
机构与分组为 M:N 关系，可在机构详情中添加 / 移除关联分组，用于按机构维度筛选任务与统计。
七、用户管理
路径：/users。管理系统账号（后台管理员、终端用户）及其角色、机构、云主机绑定。
7.1 新建用户
| 字段 | 说明 |
|---|---|
| 用户名 | 必填，登录用户名 |
| 姓名 | 真实姓名（可选） |
| 初始密码 | 必填，至少 6 位 |
| 机构 | 树形选择器，选择所属机构 |
| 邮箱 / 手机 | 可选 |
| 角色 | 下拉选择角色；选择云主机用户类角色时会联动出现「云主机」选择框 |
| 云主机 | 当角色为云主机用户时，选择绑定的云主机 |
云主机用户也可通过公开注册页 /register 自助注册（机构分享注册链接），系统自动为其分配一台可用的云主机配置。
7.2 用户列表与详情
- 左侧用户列表（支持搜索），点击查看右侧详情
- 详情包含：基本信息、所属机构、角色列表、云主机绑定、任务统计
7.3 用户操作
- 分配角色：为用户绑定 / 解绑角色
- 绑定云主机：为云主机用户指定主机
- 重置密码：管理员直接为用户设置新密码
- 启用 / 禁用：控制账号是否可登录
- 删除：移除账号（谨慎操作）
八、角色管理
路径：/roles
8.1 新建角色
| 字段 | 说明 |
|---|---|
| 角色名称 | 如「超级管理员」 |
| 角色代码 | 如 super_admin（程序内唯一标识） |
| 层级 | 系统级 system / 机构级 org |
| 描述 | 可选 |
8.2 角色列表与详情
- 左侧角色卡片列表，点击查看右侧详情
- 详情展示角色基本信息、内置标记、已分配用户数、权限清单
8.3 角色操作
- 编辑：修改名称、代码、层级、内置标记、描述
- 权限配置：勾选 / 取消角色可用的权限项
- 删除：移除自定义角色（内置角色不可删除）
九、权限管理
路径：/permissions（只读）。用于查看系统全部权限定义，便于核对角色权限配置。
- 搜索：按权限名称、代码、描述过滤
- 类别筛选：客户端管理 / 分组管理 / 任务管理 / 内容管理 / 用户管理 / 系统设置 / 通用权限
- 统计卡片：总权限数及各分类数量
十、版本管理
路径：/versions。管理客户端（webot-lite）升级包发布与部署进度。
10.1 统计卡片
| 卡片 | 含义 |
|---|---|
| 总版本数 | 已发布的版本总数 |
| 进行中部署 | 正在执行升级的部署任务数 |
| 成功升级 | 历史上成功完成的升级次数 |
| 失败升级 | 历史上失败的升级次数 |
10.2 发布新版本
- 填写版本号、版本说明
- 上传 / 选择升级包（客户端代码包）
- 选择目标主机（云主机客户端）
- 确认发布，系统自动下发并触发客户端升级
10.3 部署跟踪
版本列表展示每个版本的发布时间、状态、目标主机；点击部署记录进入 /deployments/{id} 详情页，实时查看升级进度与日志。
十一、任务管理
路径：/tasks。创建、分配、跟踪朋友圈 / 视频号发布任务。
11.1 新建任务
- 任务类型：朋友圈发布 / 视频号发布
- 调度模式：即时任务（立即分发执行）/ 周期计划（按周期规则重复执行）
- 目标分组：树形选择器选择目标客户端分组（勾选父分组自动包含子分组）
- 内容：文案 + 图片（右侧实时预览朋友圈效果）
- 发布时间 / 周期规则：即时则选执行时间，周期则配置时间窗口（支持多时段，如
09:00~10:00、20:00~21:00） - 审批模式：自动审批 / 人工审批（人工审批将进入审批队列）
11.2 任务列表
展示任务：类型、内容摘要、目标、调度、状态、创建时间；支持按状态 / 类型 / 时间范围筛选、搜索。
| 状态 | 含义 |
|---|---|
| pending_approval | 待审批 |
| approved | 已批准 |
| rejected | 已驳回 |
| dispatched | 已分发（待执行） |
| running / executing | 执行中 |
| done | 已完成 |
| failed | 执行失败 |
| cancelled | 已取消 |
11.3 任务操作
- 查看详情：进入
/tasks/{id}，查看任务完整信息、分发进度、各客户端执行状态与日志 - 编辑：修改待执行任务内容
- 取消：取消未执行任务
- 重试：对失败任务重新分发
十二、审批队列
路径：/approvals。人工审批入口（对应审批模式为「人工审批」的任务）。
12.1 任务审批
- 待审批任务卡片：内容摘要、类型（朋友圈/视频号）、目标分组、调度窗口、审批模式、创建时间
- ✅ 批准：任务进入执行队列
- ❌ 驳回：需填写驳回理由，任务退回创建方
12.2 已处理记录
折叠面板「已处理记录」，可查看已批准 / 已驳回的历史任务。
12.3 内容审批
「内容审批」标签页为 Phase 2 预留，当前展示占位提示。
十三、智能营销
路径：/generator。AI 智能内容创作工具，4 步向导式流程。
13.1 步骤 1：选择主题
- 从下拉列表选择已有主题
- 或快速创建新主题（主题名称、分类、描述）
13.2 步骤 2：生成内容
- 已选主题：顶部展示
- 话题 / 关键词：输入或点击「✨ 重新智能生成」
- 人设 / 角色：输入或按主题分类智能匹配
- 文案数量：1~10 条；图片数量：1~9 张
- 点击「生成内容」调用 LLM + 文生图服务
13.3 步骤 3：预览调整
- 文案选择器切换多条文案，文本可直接编辑
- 图片可删除或重新生成
- 右侧实时预览朋友圈效果
13.4 步骤 4：发布任务
- 确认任务摘要（文案、图片、数量）
- 选择目标客户端 / 分组（仅展示最近 5 分钟在线的客户端）
- 设置任务类型、调度模式、审批模式
- 点击「发布任务」完成
十四、内容工厂
路径：/content-factory。主题、图片、文案的批量管理。
14.1 主题管理
新建主题（向导式，逐步解锁）：
- 目标分组（主题仅供所选分组的客户端使用）
- 主题名称
- 分类
- 审批模式（自动 / 人工）
- 描述（支持「换一批」刷新建议）
- 文案 & 图片 Prompt（可「✨ 智能生成」）
- 生效日期（可选）
主题列表：查看所有主题、状态、使用统计；支持编辑、启用/禁用、删除。
14.2 图片管理
- 上传本地图片素材
- 图片列表：预览、删除
14.3 文案管理
- 查看已生成的文案库
- 编辑、删除文案
- 支持按主题 / 状态筛选
十八、系统设置
路径：/settings
18.1 服务器信息
版本号、运行状态、数据库路径、在线客户端数（每 60 秒刷新）。
18.2 LLM 配置（只读）
Provider、Base URL、Model、API Key（脱敏显示）。如需修改，直接编辑服务端 .env 中的 LLM_* 配置。
18.3 修改管理员密码
填写当前密码、新密码、确认新密码，提交后生效（对应 /api/admin/change-password）。
十九、常见问题 FAQ
Q1：登录后跳转到了「我的工作台」而不是管理后台？
A：说明当前账号角色是终端用户（cloud_host_user / standalone_user）。需使用管理员角色账号登录，或在「用户管理」中为该账号分配管理员角色。
Q2：侧边栏看不到「云主机管理 / 环境配置 / VNC」？
A：这三个菜单仅系统超级管理员（system_super_admin）可见。请确认当前登录账号角色。
Q3：云主机客户端状态一直显示「未知 / 离线」？
A：检查：① 主机配置的 SSH 信息是否正确；② 客户端是否已部署 webot-lite 并启动；③ 服务端与客户端 WebSocket 连接是否正常（可看服务端日志）；④ 客户端最近是否有心跳（>5 分钟无心跳会判离线）。
Q4：一键重启会不会影响正在发布的任务？
A：会。一键重启会滚动重启所有云主机客户端进程，正在执行的任务可能中断。建议在低峰期操作，重启完成后任务调度器会自动恢复周期计划。
Q5：任务创建后客户端没有执行？
A：检查：① 目标客户端是否在线（Dashboard 查看）；② 客户端状态是否为 active / running；③ 任务是否处于已批准或已分发状态；④ 周期任务时间窗口是否包含当前时间。
Q6：审批队列里任务状态是「待审批」，如何进入执行？
A：在「审批队列」点击「✅ 批准」，任务进入分发队列；「❌ 驳回」需填写理由，任务退回。
Q7：如何修改 LLM 配置？
A：「系统设置」中 LLM 配置为只读展示。修改需编辑服务端 .env 的 LLM_BASE_URL、LLM_MODEL、LLM_API_KEY 并重启服务，或使用「环境配置」页（若该项在白名单内）。
Q8：发布新版本后客户端没升级？
A：检查：① 版本包是否发布成功；② 目标主机是否在线；③ 部署记录（/deployments/{id}）中的进度与日志；④ 客户端版本检测间隔。
附录：状态对照表
任务状态
| 状态 | 含义 |
|---|---|
| pending_approval | 待审批 |
| approved | 已批准 |
| rejected | 已驳回 |
| dispatched | 已分发 |
| running / executing | 执行中 |
| done | 已完成 |
| failed | 失败 |
| cancelled | 已取消 |
WeBot · 后端管理使用手册（v2.0）