xiyebot 管理后台与授权码(robotID)

更新时间:2026-09-09(新增账号类型 / 到期时间 / 付费金额 / 延长)

1. 定位

xiyebot 新增了一个内置管理后台,用于生成和管理「授权码」。授权码即 robotID,一条链路三个用途:

1. 管理员在管理后台生成授权码,发给用户。

2. 用户下载 APK 后,在 App 内输入授权码点「激活设备」——服务端把该授权码与这台设备绑定,设备才能正常注册/心跳/领任务。

3. 用户在自己的业务后台把同一串授权码配置为 robotId,FlowBot 兼容 API(/wx/api/*)据此放行并把任务钉到绑定的设备上。

绑定规则:一码一机。

• 一个授权码只能绑定一台设备;第二台设备用同一个码激活会被拒绝(AUTH_CODE_ALREADY_BOUND)。
• 换机(含卸载重装后重新注册)需要管理员在后台先「解绑」,新设备才能重新激活。
• 「禁用」立即让该 robotId 的所有 API 调用返回 401,启用后恢复。

2. 访问入口与菜单

https://flowbot.efguc.com/admin

页面为服务端内置单文件(server/admin.html),经 nginx 全量转发,无需额外部署前端。

2026-09-09 起左侧菜单分三块(URL hash #codes / #orders / #pricing,记住上次停留):

| 菜单 | 内容 |

| --- | --- |

| 授权管理 | 授权码生成 / 列表 / 延长 / 编辑 / 禁用 / 解绑 / 删除,顶部汇总卡片可点击筛选 |

| 订单管理 | 官网微信支付订单,按状态筛选;「重新查单」强制向微信查单并补发码(用户已付款但页面没刷出码时用),「关闭」关掉待支付订单(微信侧关单) |

| 价格管理 | 设备授权单价(元/台)、授权年限、单笔最多台数,保存即生效于官网首页价格卡、支付弹窗和微信下单金额;已创建订单按下单时价格结算。价格存 redis xiyebot:license:pricing,未设置时回退环境变量 LICENSE_PRICE_CENTS(默认 ¥499 / 1 年 / 50 台) |

3. 服务端配置

在 /etc/xiyebot/xiyebot.env 中新增:

# 管理后台登录密码。不配置则 /admin 接口全部返回 403(后台关闭)。
ADMIN_PASSWORD=<强密码>

# 可选:置 1 后,/devices/register 必须携带授权码,旧的 DEVICE_BIND_CODE 注册通道关闭。
# 默认 0,存量设备/模拟器流程不受影响。
REQUIRE_AUTH_CODE=0

然后应用数据库结构并重启:

cd /opt/xiyebot
set -a; . /etc/xiyebot/xiyebot.env; set +a
psql "$DATABASE_URL" -f server/schema.sql
systemctl restart xiyebot

schema.sql 是幂等的(CREATE TABLE IF NOT EXISTS / ADD COLUMN IF NOT EXISTS),可整份重放。相关表:

robot_auth_codes(robot_id PK, status unused|active|disabled, remark,
                 device_id UNIQUE 部分索引, created_at, activated_at, updated_at,
                 account_type paid|trial|saas_agentos|saas_custom (默认 trial),
                 expires_at NULL=不限期, paid_amount 累计付费(元), last_paid_at)
robot_auth_code_extensions(id PK, robot_id, unit day|month|year, count, amount,
                 before_expires_at, after_expires_at, note, created_at)   -- 延长/付费流水

3.1 账号类型、到期与付费(2026-09-09)

| 字段 | 说明 |

| --- | --- |

| 账号类型 | paid 付费 / trial 试用 / saas_agentos SaaS内赠·获客AgentOS / saas_custom SaaS内赠·定制版。升级前的存量码默认 trial,可在后台「编辑」改正。 |

| 到期时间 | 生成时选「有效期」从生成时刻起算;为空表示不限期。到期后:FlowBot 兼容 API 返回 401 robotId已到期,APK 用该码激活返回 AUTH_CODE_EXPIRED;已绑定设备不会被解绑,延长后立即恢复。 |

| 延长 | 按天 / 月 / 年顺延。未到期的码从原到期时间顺延;已到期或不限期的码从当前时刻起算(不限期码延长会变成限期,前端会二次确认)。 |

| 付费金额 | 「延长」时填写本次金额会累加到 paid_amount,同时把账号类型改为 paid;不填金额即免费延长(试用 / 内赠续期)。每次延长写一条流水,在「编辑」弹窗底部可查。 |

后台列表顶部有汇总(付费 / 试用 / 内赠 / 7 天内到期 / 已到期 / 累计付费),点击即筛选;7 天内到期的码在列表里橙色高亮,已到期红色。

4. 兼容性(存量 robotId 不受影响)

robotId 校验与设备映射的优先级:

1. robot_auth_codes 表命中 → 以表为准(禁用即拒绝;active 绑定即钉设备)。

2. 表未命中 → 回退旧环境变量 FLOWBOT_COMPAT_ROBOT_IDS / FLOWBOT_DEVICE_ROBOT_IDS,行为与之前完全一致。

因此线上现有的 wxe5da... robotId 和已配置的设备映射无需迁移,可以逐步替换为授权码。

5. 管理接口(供排障/脚本用)

登录后所有接口带 Authorization: Bearer <token>:

POST   /admin/api/login                      {password} -> {token}  (Redis 会话 7 天)
GET    /admin/api/auth-codes                 列表(含绑定设备与在线状态)
POST   /admin/api/auth-codes                 {count: 1-100, remark, accountType, validity: {unit: day|month|year, count} | null, paidAmount} 生成
POST   /admin/api/auth-codes/<id>/extend     {unit: day|month|year, count: 1-120, amount, note} 延长(带金额则累计付费并转为付费账号)
GET    /admin/api/auth-codes/<id>/extensions 延长 / 付费流水
PATCH  /admin/api/auth-codes/<id>            {accountType?, expiresAt?: ISO|null, paidAmount?, remark?} 编辑(expiresAt 传 null = 不限期)
GET    /admin/api/license-orders?status=     订单列表(含各状态计数 / 已收款合计)
POST   /admin/api/license-orders/<no>/sync   强制向微信查单,已支付则补发授权码
POST   /admin/api/license-orders/<no>/close  关闭待支付订单
GET    /admin/api/pricing                    当前价格配置(含 payEnabled)
PUT    /admin/api/pricing                    {unitPrice(元), termYears 1-10, maxQuantity 1-500, note} 保存价格,即时生效
POST   /admin/api/auth-codes/<id>/disable    禁用(robotId 立即失效)
POST   /admin/api/auth-codes/<id>/enable     启用(恢复 unused/active)
POST   /admin/api/auth-codes/<id>/unbind     解绑设备(换机前必做)
DELETE /admin/api/auth-codes/<id>            删除(仅未绑定设备的码)

授权码格式:xyb + 32 位十六进制,例如 xyb1f2a...。

6. 用户侧激活流程

1. 安装 APK,打开 Xiyebot Agent。

2. 「服务器地址」保持默认(或按需修改),在「授权码 (robotID)」输入框粘贴授权码。

3. 点「激活设备 (注册)」。成功后状态区显示「授权: 已激活 <robotId>」。

4. 在业务后台把同一串授权码配置为 robotId,然后正常调用:

curl "https://flowbot.efguc.com/wx/api/getRobotInfo?robotId=<授权码>"

7. 常见错误码

| 错误码 | 场景 | 处理 |

| --- | --- | --- |

| INVALID_AUTH_CODE | 授权码不存在(输错/被删除) | 核对授权码 |

| AUTH_CODE_DISABLED | 授权码被禁用 | 管理后台启用 |

| AUTH_CODE_ALREADY_BOUND | 码已绑定其他设备(含重装后旧绑定残留) | 管理后台解绑后重新激活 |

| AUTH_CODE_EXPIRED | 授权码已到期 | 管理后台「延长」后重新激活 |

| AUTH_CODE_REQUIRED | 服务端要求授权码但 App 未填 | 填入授权码后重试 |

| API 返回 robotId无效 | robotId 不在授权码表也不在环境变量白名单 | 检查业务后台配置的 robotId |

| API 返回 robotId已禁用 / robotId已到期,请联系管理员续期 | 授权码被禁用 / 已过到期时间 | 管理后台启用 / 延长 |