Webot 技术开发介绍（从零到全栈）

本文档面向开发者，系统性地讲解 Webot 的整体架构、模块职责、关键技术实现与二次开发方式。读者对象：希望读懂代码、开发插件、部署或二次开发本项目的工程师。

目录

1. 项目概述
2. 技术栈与运行环境
3. 总体架构
4. 目录结构一览
5. 启动与主进程模型
6. 配置系统
7. 数据库抽象层（多数据库兼容）
8. 认证、权限与授权
9. 微信接入（iLink Bot）
10. QQ 机器人接入（WebSocket）
11. 插件系统
12. AI 能力与故障转移
13. 路由层与 API
14. 服务层（支付 / 算力计费）
15. 用户画像与长期记忆
16. 定时任务与 cron
17. 前端架构
18. 核心数据表 schema
19. 二次开发：编写插件
20. 部署与打包
21. 关键技术坑与经验

1. 项目概述

Webot（旧品牌名 LoveBot）是一个 AI 聊天机器人 SaaS 平台，核心理念是：

• 一个站点（多用户） 托管多个机器人实例（bot）；
• 每个用户可以绑定自己的微信机器人（通过 iLink 协议），或接入 QQ 官方机器人；
• 通过 插件系统 给机器人挂载能力（智能对话、热搜、知识库、生图、定时推送、群管理等）；
• 平台提供会员 / 积分 / 算力（Token）计费、插件市场等商业能力。

它既不是单纯的「微信机器人框架」，也不是单纯的「AI 聊天网站」，而是把渠道接入 + 插件编排 + AI 调用 + 多用户 SaaS 计费整合在一起的一套完整服务。

一句话定位：一个支持微信 + QQ 双渠道、可插拔插件、自带 AI 调度与会员计费的多用户机器人平台。

2. 技术栈与运行环境

后端

维度	选型
运行时	Node.js（建议 ≥ 18，使用 node:sqlite/better-sqlite3）
Web 框架	Express 5
视图	EJS 服务端渲染（少量后台页面 + 安装向导）
数据库	三选一：SQLite（默认，零配置）/ MySQL / PostgreSQL
进程管理	PM2（ecosystem.config.js，fork 模式 + 自动重启）
WebSocket	ws（QQ 机器人接入）
加解密	node:crypto + bcryptjs（密码）
HTTP 客户端	axios

架构演进：早期是 UniApp 前端 + 后端；现已演进为「Express + EJS 后台」+「React/Vite 前端（web/dist）」。前端源码在 web/，构建产物 web/dist 由 Express 托管。

前端

维度	选型
框架	React 18 + TypeScript
构建	Vite
路由	react-router-dom（按路由懒加载）
UI 组件	shadcn/ui（Radix + Tailwind）+ lucide-react 图标
状态	React Context（auth / site / theme）+ 自研 logStore
提示	sonner（Toaster）

3. 总体架构

                         ┌─────────────────────────────────────────┐
   微信用户/群  ◄──────► │            iLink 协议 (lib/ilink.js)       │
                         │         （微信机器人长连接 + 加解密）        │
                         └───────────────────┬─────────────────────┘
                                             │ onMessage
                         ┌───────────────────┴─────────────────────┐
   QQ 用户/群  ◄──WS───► │            QQ 机器人 (plugins/qqbot)       │
                         │      （腾讯官方 WebSocket 网关协议复刻）      │
                         └───────────────────┬─────────────────────┘
                                             │ 统一的消息对象
         ┌───────────────────────────────────┼───────────────────────────────────┐
         ▼                                   ▼                                   ▼
 ┌───────────────┐                  ┌────────────────┐                  ┌────────────────┐
 │  消息归一化    │ ──dispatch──►    │   插件系统       │ ──onMessage──►   │  smart 智能助手  │
 │ msg-events.js │                  │ lib/plugins.js │                  │ (AI 调度/记忆)  │
 └───────────────┘                  └────────────────┘                  └───────┬────────┘
         ▲                                   ▲                                │ callAssistant
         │                                   │                                ▼
         │                          ┌────────┴─────────┐            ┌────────────────────┐
         │                          │  数据库抽象层      │            │  lib/ai_url.js      │
         └──────────────────────────│   lib/db.js       │            │ (多端点故障转移)     │
                                    │ (Sqlite/Mysql/Pg) │            └────────────────────┘
                                    └────────┬─────────┘
                                             │
                                    ┌────────┴─────────┐
                                    │  Express 路由层    │  ◄────  React 前端 (web/dist)
                                    │  routes/*.js      │         admin / market / profile
                                    └──────────────────┘

核心设计思想：

1. 消息归一化：无论来自微信还是 QQ，都收敛为统一的「消息对象」，再交给插件系统处理，插件无需关心渠道差异。
2. 插件优先于业务：几乎所有可扩展能力都实现为插件（包括内置的 smart、memory、qqbot）。
3. 配置即数据库：插件配置、站点配置、机器人配置全部落在数据库（或 data/settings），避免硬编码。

4. 目录结构一览

webot/
├── server.js              # 主进程入口：启动 Express + 初始化各子系统
├── worker.js              # 长轮询 / CLI 消息处理进程（进程 Bot 模式）
├── config/index.js        # 统一配置聚合（env + db-config.json）
├── ecosystem.config.js    # PM2 部署配置
├── pkg.bat               # Windows 打包脚本（规避中文路径坑）
├── lib/                  # 核心库
│   ├── db.js             # 数据库抽象（SQLite/MySQL/PG + 迁移 + SQL 改写）
│   ├── plugins.js        # 插件加载 / 派发 / 渠道解析
│   ├── auth.js           # 注册 / 登录 / 权限
│   ├── license.js        # 站点授权（License 校验）
│   ├── settings.js       # 站点设置读写
│   ├── bot.js            # 机器人实体（显示名、token 派生）
│   ├── ilink.js          # 微信 iLink 长连接协议
│   ├── ai_url.js         # AI 端点调度 + 故障转移
│   ├── ai_health.js      # AI 健康检查
│   ├── cron.js           # 轻量 cron 解析（无第三方依赖）
│   ├── mailer.js         # 邮件发送（验证码）
│   └── msg-events.js     # 微信消息事件归一化
├── plugins/              # 插件目录
│   ├── smart/            # 内置智能助手（AI 对话核心）
│   ├── memory/           # 用户画像 / 长期记忆
│   ├── qqbot/            # QQ 机器人 WebSocket 接入
│   ├── hot-search/       # 微博+抖音热搜
│   ├── weibo-hot/        # 微博热搜（独立版）
│   ├── image-gen/        # AI 生图
│   ├── group-manager/    # 群管理
│   ├── knowledge/        # 知识库（RAG，对接 IMA）
│   ├── market/           # 插件市场交互
│   └── ...               # 更多插件
├── routes/              # Express 路由
│   ├── admin.js          # 后台管理 + 安装向导
│   ├── api.js            # 通用 Web API（发消息、配置）
│   ├── qqbot.js          # QQ 机器人相关（扫码、回调、菜单）
│   ├── market.js         # 插件市场接口
│   ├── pluginAssistant.js# 插件开发助手（AI 生成插件）
│   ├── push.js           # 推送
│   └── license-server.js # License 校验服务
├── services/            # 业务服务
│   ├── pay.js            # 支付（充值→积分）
│   └── worker.js         # 后台任务
├── views/               # EJS 模板（后台/安装向导）
├── public/              # 静态资源（CSS/JS/图片）
├── data/                # 运行期数据（库文件、画像、schema）
│   ├── schema.sql       # SQLite 建表脚本
│   └── schema.mysql.sql # MySQL 建表脚本
├── web/                 # 前端源码（React/Vite/TS）
│   └── src/             #   pages/ components/ lib/
│   └── dist/            #   构建产物（Express 托管）
└── docs/                # 文档

5. 启动与主进程模型

入口 server.js

server.js 是 PM2 启动的脚本（见 ecosystem.config.js：script: 'server.js'）。启动顺序（见 server.js）：

1. 加载配置 loadConfig()（config/index.js）。
2. 初始化数据库 initDb() → lib/db.js 建立连接 + 执行建表（runSchemaSync/Mysql/Pg）。
3. 启动迁移 runSchemaMigrations()：对旧库补列 / 补表（如 bot_names、qqbot_groups.msg_receive）。
4. 加载插件 plugins.loadAllDefinitions()。
5. 启动微信连接 ilink 模块（startAllBots 之类，绑定机器人长连接）。
6. 启动 QQ 连接 qqbot 插件 startAll()（WebSocket 接入）。
7. 启动 Express，挂载 routes/，托管 web/dist 静态资源与 public/。
8. 启动定时任务（cron / 画像生成 / 推送）。

配合 worker.js（processBotMessages 共享函数）支持「长轮询模式」或 CLI 模式，复用消息处理逻辑。

PM2（ecosystem.config.js）

apps: [{
  name: 'webot',
  script: 'server.js',
  instances: 1,
  exec_mode: 'fork',          // 单实例 fork（共享内存态连接，不适合 cluster）
  max_memory_restart: '1024M',
  autorestart: true,
}]

注意：fork 模式是因为微信/QQ 长连接、内存态连接池在 cluster 下会冲突。

6. 配置系统

config/index.js 是唯一配置聚合点，优先级（见代码）：

命令行 > 环境变量 (.env) > data/db-config.json > 默认值

配置项	来源	说明
PORT	env / 默认 4000	HTTP 端口（多用户版用 4000；2568/3000 被 Windows Hyper-V 排除）
DB_TYPE	db-config	sqlite / mysql / pg
DB_NAME	db-config / env	数据库名（如 webot）；注意部署时填错会导致库名异常
DB_HOST/DB_PORT/DB_USER/DB_PASS	同上	远程库连接
JWT_SECRET	env	session 签名密钥
AI_*	站点设置 / env	默认 AI 端点、密钥
SITE_*	站点设置	站点名称、公告、2FA 等

数据库配置读取逻辑（见 lib/db.js）：

const m = dbConfigFile || {}; // data/db-config.json
const database = m.database || process.env.DB_NAME || 'webot';

经验：data/db-config.json 与 .env 都不在打包产物内，部署机必须自己生成；库名只来自这两处，代码无硬编码 lovebot 等字样。

7. 数据库抽象层（多数据库兼容）

lib/db.js 是项目最关键的「底座」之一，实现了同一份业务代码跑在三种数据库。

适配器模式

根据 DB_TYPE 选择底层驱动：

• sqlite：node:sqlite（Node 18+ 内置）或回退 better-sqlite3
• mysql：mysql2
• pg：pg

对外暴露统一的异步 API（db.exec / db.row / db.rows / db.all / db.run / db.lastInsertId / db.transaction），业务层完全不感知底层数据库。

SQL 跨库兼容改写

不同数据库 SQL 方言差异巨大，lib/db.js 提供：

• rewriteSqlForMysql(sql)：把 SQLite 的 AUTOINCREMENT → MySQL AUTO_INCREMENT；strftime('%s','now') → UNIX_TIMESTAMP()；TEXT 默认值（MySQL 不允许 TEXT 有默认值）→ 转 VARCHAR(255) 等。
• rewriteSqlForPg(sql)：类似处理（如 INTEGER PRIMARY KEY AUTOINCREMENT → SERIAL）。

建表（schema）

启动时按数据库类型读取 data/schema.sql 或 data/schema.mysql.sql（fs.readFileSync 硬读取，缺失即启动失败），执行建表。

迁移 runSchemaMigrations()

对已存在旧库补列/补表（而不是删库重建），例如：

• bot_names（机器人显示名表，原仅由 Bot.ensureBotNames() 异步建，后固化为启动迁移）
• qqbot_groups.msg_receive（群消息接收开关）

迁移用 ensureTable / ensureColumn 幂等执行。

核心数据表

表	职责
users	站点用户（密码 hash、会员、积分、邀请码）
bots	机器人实例（微信 token / qrcode / 绑定状态）
bot_names	机器人显示名
messages	微信消息流水（direction/peer_id/content/type）
plugin_settings	插件配置（按 bot+qq 维度）
plugins	已安装插件清单
plugin_market	市场插件元数据（价格/免费/可见性）
qqbot_groups	QQ 群配置（备注/计数/开关/黑白名单）
qq_messages	QQ 对话流水（独立表，避免污染微信记忆）
cards	卡密
pay_orders	支付订单
points_log / token_log	积分/算力流水
custom_skills	用户自定义技能（跨 bot）
announcements	站点公告
user_memory_consent / user_facts	记忆授权 + 结构化事实

完整字段见 data/schema.sql（第 1-369 行）。

8. 认证、权限与授权

lib/auth.js

• Auth.register()：用户名 ≥3、密码 ≥8 且含字母+数字（强密码策略）；支持邮箱验证码校验（mailer.verifyCode）；bcrypt.hash。
• Auth.login()：bcrypt.compare 校验；返回用户数据，session 由路由层写。
• 权限维度：is_admin（后台）、member_type/member_until（会员）、points/ai_tokens_*（算力）。

授权 lib/license.js

• 站点需要 License 才能启用完整功能；User-Agent: 'LoveBot-License/3.0' 用于向授权服务器校验（品牌旧名残留）。
• routes/license-server.js 提供校验端点。

2FA

后台支持两步验证（AdminGate 前端守卫 + admin2fa 状态）。

9. 微信接入（iLink Bot）

lib/ilink.js 实现微信机器人长连接（iLink 协议）：

• 通过扫码登录（qrcode / qr_content），拿到 bot_token / context_token 等；
• 维护长连接接收消息，回调业务层 onMessage；
• 消息经过 lib/msg-events.js 归一化为统一消息对象（peer_id / content / msg_type / direction）；
• 发送消息：sendText / sendMedia（含 -14 session timeout 重试、消息加密 tryDecrypt）；
• 加解密：用 node:crypto 派生 bot key，消息体可能加密，tryDecrypt 直接尝试解密（替代旧的 isEncrypted 长度判断，修复短密文误判）。

微信消息写入 messages 表，是生成用户画像的基础。

10. QQ 机器人接入（WebSocket）

plugins/qqbot/index.js 复刻腾讯官方 @tencent-connect/qqbot-nodejs 协议（纯 WS 实现，无官方 SDK 依赖）：

• Token：POST https://bots.qq.com/app/getAppAccessToken
• Gateway：GET https://api.sgroup.qq.com/gateway（返回 wss 地址）
• 鉴权：IDENTIFY 的 token = "QQBot {accessToken}"
• op 码：DISPATCH(0)/HEARTBEAT(1)/IDENTIFY(2)/RESUME(6)/RECONNECT(7)/INVALID(9)/HELLO(10)/ACK(11)
• 事件：GROUP_AT_MESSAGE_CREATE（群 @）、C2C_MESSAGE_CREATE（私聊）、GROUP_MEMBER_ADD/REMOVE 等

关键实现点

• 每个 (bot, qq) 一个连接，存于 connections Map；
• 群信息每 5 分钟刷新（GROUP_REFRESH_INTERVAL）；
• @ 处理：实测发送 <qqbot-at-user> / <@openid> 标签不渲染（平台限制），改用 message_reference（引用回复）达到提醒效果；点名某人用纯文本「@昵称」；
• QQ 消息不写入 messages 表（避免污染微信记忆画像），独立存 qq_messages，但回答时 AI 系统提示会附带微信侧生成的画像（memory.getCombinedPrompt，按 bot 维度共享）；
• 入站事件通过 plugins.dispatchToPlugins 交给插件管线（smart/keyword/hot-search 等可同时服务微信与 QQ）。

11. 插件系统

lib/plugins.js 是插件引擎，设计目标是「市场插件在前、内置模块在后、smart 兜底」。

插件定义结构（meta）

每个插件目录 plugins/<id>/index.js 导出一个对象：

module.exports = {
  meta: {
    id: 'hot-search',
    name: '热搜',
    version: '1.0.0',
    description: '...',
    channels: ['wechat', 'qq'],   // 微信/QQ 支持说明
    settingsSchema: [ /* 配置表单定义 */ ],
  },
  // 关键词 / 指令匹配
  shouldHandle(ctx) { ... },
  // 消息处理（返回 true 表示已消费）
  async onMessage(ctx, { reply, sendText, sendMedia }) { ... },
  // 可选：对外 AI 工具
  aiTools: { get_weibo_hot: {...}, get_douyin_hot: {...} },
};

加载机制（lib/plugins.js）

• loadAllDefinitions()：扫描 plugins/ + 市场安装目录，require 每个 index.js，透传 channels 字段；
• resolveChannels(plugin)：根据 channels 字段 + QQ_SUPPORTED 白名单，判断插件是否支持微信/QQ；
• dispatchToPlugins(ctx, handlers)：把归一化消息派发给所有匹配插件的 onMessage，按优先级执行；
• executePlugin(id, ...)：定向执行某个插件；
• 内置 smart 作为兜底（没有插件消费时交给 AI 智能助手）。

代表性插件

插件	功能
smart	智能助手核心：AI 对话、调用 AI 工具、记忆注入
memory	用户画像 / 长期记忆（自动分析聊天记录生成画像）
qqbot	QQ 官方机器人接入（WS 网关协议）
hot-search	微博+抖音热搜（合并版，含 AI 工具 get_weibo_hot/get_douyin_hot）
weibo-hot	微博热搜（独立版）
image-gen	AI 生图
group-manager	群管理（入群审核、踢人、禁言）
knowledge	知识库（对接 IMA OpenAPI：搜索/导入/写入）
market	插件市场浏览/安装交互
customer-service	在线客服（访客消息→微信，支持知识库自动回复）

插件还支持 settingsSchema：前端 PluginConfigPanel 据此自动渲染配置表单，无需单独写配置页。

12. AI 能力与故障转移

lib/ai_url.js

负责实际调用 AI 接口：

• 支持 chatgpt / 通义 / 自定义 OpenAI 兼容端点；
• 多端点轮询 + 故障转移：维护端点列表与权重/健康度，主端点失败自动切下一个；
• ai_health.js 做健康检查（标记不可用端点，冷却后重试）。

plugins/smart

• callAssistant(ctx, prompt, tools)：组装系统提示（含 memory 画像、插件 AI 工具定义），调用 lib/ai_url；
• 支持 function calling：插件通过 aiTools 声明工具（如热搜查询），AI 可主动调用；
• 算力计费：每次对话按 token 计入 token_log，超额度拦截。

13. 路由层与 API

routes/ 下每个文件是一个 Express Router：

路由文件	职责
admin.js	后台管理（用户/机器人/卡密/公告）+ 安装向导（/setup/db 写 db-config.json）
api.js	通用 Web API（发消息、读写配置、上传）
qqbot.js	QQ 机器人（扫码 source 标记、回调、菜单、群认领）
market.js	插件市场（/list 返回插件含 channels 徽章）
pluginAssistant.js	AI 辅助生成插件代码
push.js	推送接口
license-server.js	License 校验

前端 React 通过统一 api 客户端（封装 fetch + 鉴权头）调用这些路由；公共页面用 EJS 渲染，复杂后台用 React。

14. 服务层（支付 / 算力计费）

services/pay.js

• 充值流程：用户下单 → 生成 pay_orders（待支付）→ 支付成功回调 → 人民币转积分（points）+ 流水 points_log；
• 支持卡密（cards 表）兑换。

算力（Token）计费

• 每次 AI 调用按 token 计入 token_log；
• users.ai_tokens_used / ai_tokens_limit 限制额度；
• 会员（member_type）享受更高额度。

15. 用户画像与长期记忆

plugins/memory/index.js 实现「隐私优先（opt-out）」的长期记忆：

• user_memory_consent(bot_id, consent)：用户可发「拒绝画像」关闭；默认自动生成；
• 画像文件：data/memory/profile_<botId>.md（按机器人维度，单 bot 单记忆——解绑重绑不改变 bot_id）；
• user_facts(bot_id, fkey, fvalue)：结构化事实（城市/生日/偏好），由 AI 主动 save_user_fact 写入；
• getCombinedPrompt(botId)：把画像 + 事实注入 AI 系统提示，实现「聊天时自动检索记忆」；
• 后台任务每 2 小时扫描，仅当用户未拒绝且新增 ≥50 条消息时增量生成。

QQ 聊天不进 messages 表，因此不参与画像生成，但 QQ 回答时引用微信侧画像作为参考。

16. 定时任务与 cron

lib/cron.js 是零依赖的 cron 解析器：

• 支持 5 字段标准 cron（分 时 日 月 周）：* /5 * * * *（每 5 分钟）、0 9 * * 1-5（工作日 9 点）；
• parseField 解析单字段（* ? , - / 步长）；
• nextCronTime(expr, afterEpochSec) 计算下次触发时间；
• 日/周同时指定时按 cron 惯例「或」匹配。

用于：画像生成、推送、群统计等。

17. 前端架构

web/src/ 是 React + TS + Vite 项目：

• 路由（App.tsx）：react-router-dom，全部页面 lazy 懒加载（首屏只加载当前路由 JS）；
• 守卫：AdminGate（后台需管理员）、SetupGate（首次安装强制跳 /admin/setup）、GlobalErrorCapture（全局错误捕获写入 logStore）；
• 状态：useAuth（登录态）、SiteProvider（站点设置）、ThemeProvider（明暗主题）；
• UI：shadcn/ui（Radix + Tailwind）+ sonner Toaster + lucide-react 图标；
• API 客户端：web/src/lib/api.ts（或 lib/api）封装 fetch、自动带 token、统一错误处理；
• 页面（37 个）：Home / Console / Market / Profile / Mall / Smart / Automation / Mcp / Invite / Admin 等；
• 构建：npm --prefix web run build → web/dist，由 Express 静态托管。

构建警告：需先 set NODE_OPTIONS=（清掉 shim），否则 vite 清空 dist 被拦截。

18. 核心数据表 schema

完整定义在 data/schema.sql（SQLite）与 data/schema.mysql.sql（MySQL）。以下为关键表：

users

id, username, password_hash, email, email_verified, is_admin, points, member_type, member_until, user_code, invited_by, invite_count, created_at

bots

id, user_id, bot_code, name, login_status, bot_token, qrcode, qr_content, base_url, wechat_uin, context_token, binding 时间戳...

bot_names

bot_id (PK), display_name —— 机器人显示名

messages（微信流水）

id, bot_id, direction(in/out), peer_id, content, msg_type, context_token, status, created_at

索引：(bot_id, direction)、(bot_id, peer_id)、(bot_id, context_token)、(bot_id, created_at)

plugin_settings

(bot_id, plugin_id, qq_id, config_key) 唯一 → config_value

qqbot_groups

(bot_id, qq_id, group_openid) PK + remark / msg_count / use_bot / plugins / owners / blacklist / msg_receive / push_join / push_leave / word_filter...

qq_messages（独立，不污染画像）

id, bot_id, sender_id, content, reply, direction, scope, scope_id, tokens, ts

计费相关

cards, pay_orders, points_log, token_log, mall_exchange_log, image_gen_log

记忆相关

user_memory_consent, user_facts（data/memory/profile_<botId>.md 文件）

其他

announcements, admin_login_log, verify_codes, checkins, custom_skills, invite_log, invite_tier_reward, user_log

重要：data/schema.sql 和 data/schema.mysql.sql 是启动时硬读取的文件（缺失即启动失败），schema 改动必须同步这两文件 + lib/db.js 迁移。

19. 二次开发：编写插件

最小插件

在 plugins/my-plugin/index.js：

module.exports = {
  meta: {
    id: 'my-plugin',
    name: '我的插件',
    version: '1.0.0',
    description: '示例',
    channels: ['wechat', 'qq'],
    settingsSchema: [
      { key: 'keyword', label: '触发词', type: 'text', default: '你好' },
    ],
  },
  shouldHandle(ctx) {
    return ctx.text.includes(this.meta.settingsSchema[0].default);
  },
  async onMessage(ctx, { reply }) {
    await reply('你触发了我的插件！');
    return true; // 已消费，不再派发给后续插件/smart
  },
};

声明 AI 工具（让智能助手能调用你）

aiTools: {
  get_weather: {
    description: '查询天气',
    parameters: { type: 'object', properties: { city: { type: 'string' } } },
    async handler({ city }) { return `晴 28℃`; },
  },
}

配置表单自动渲染

只要 meta.settingsSchema 写好，前端 PluginConfigPanel 自动渲染表单，值存 plugin_settings。

执行顺序

插件（市场 > 内置）按优先级执行 onMessage，返回 true 即短路；都不处理则交给 smart 兜底。

详细开发规范见 docs/插件开发指南.md（v3）。

20. 部署与打包

打包（pkg.bat）

Windows 下用 pkg.bat（内部 set ROOT=... 变量规避中文路径编码坑）：

1. robocopy 复制源码（排除 node_modules/web/node_modules/data/logs 等运行期目录）；
2. 复制根级文件（server.js/package.json 等）；
3. 删除 data/ 运行期数据，但保留 data/schema.sql + data/schema.mysql.sql（启动硬读取）；
4. tar -a -cf 压缩到 ngbot-8SK5n-YYYY-MM-DD.zip（约 1.43MB / 290 条目，含 web/dist）。

产物排除 node_modules、.env、data/ 运行期、app.db、.codebuddy。

部署

1. 解压到服务器（如 /www/wwwroot/bot.webot.app）；
2. npm install --production；
3. node server.js 首次访问 → 安装向导 /admin/setup 配置数据库（库名填 webot 或你的库名）；
4. PM2 启动：pm2 start ecosystem.config.js；
5. 反向代理（Nginx/宝塔）到 PORT（如 4000）。

启动迁移

解压后首次启动，runSchemaMigrations() 自动建表/补列，无需手动执行 SQL。

21. 关键技术坑与经验

1. 中文路径编码（Windows）：PowerShell 传含中文（如 ai编程）的绝对路径给 robocopy/tar 会被编码破坏。pkg.bat 用 set ROOT=... 变量 + cmd /c chcp 65001 规避；验证 zip 用解包到临时目录 + dir 而非 findstr/find 管道。
2. 数据库名来源：库名只来自 data/db-config.json / .env（代码无硬编码），部署报 Table 'xxx.bot_names' 必然是部署机配置问题。
3. QQ @ 不渲染：官方 <qqbot-at-user> 标签全部不渲染，改用 message_reference 引用回复实现提醒。
4. 消息加密：短密文（如 "hi" 加密仅 40 字符）旧 content.length<60 判断误判为明文；改用 tryDecrypt 直接尝试解密。
5. -14 session 超时：发送接口检测到 ret===-14 自动重取 token 重试一次。
6. schema 三处一致性：任何建表改动须同步 lib/db.js 迁移 + data/schema.sql + data/schema.mysql.sql，否则新部署启动失败。
7. fork 模式：WebSocket 连接与内存态不适合 cluster，PM2 用 exec_mode: 'fork'。
8. 前端构建：先 set NODE_OPTIONS= 清 shim，否则 vite 清空 dist 被拦截。

结语

Webot 是一套「渠道接入 + 插件编排 + AI 调度 + 多用户 SaaS 计费」四位一体的机器人平台。其架构的核心优势在于：

• 多数据库透明兼容（SQLite/MySQL/PG 一行切换）；
• 插件化彻底（连智能助手、记忆、QQ 接入都是插件）；
• 双渠道归一（微信 iLink + QQ 官方 WS 收敛为统一消息对象）；
• 开箱即用的商业能力（会员/积分/算力/市场/卡密）。

对于二次开发者，最值得关注的是 lib/plugins.js + 插件目录 这套可插拔机制，几乎任何新能力都可以通过写一个 plugins/<id>/index.js 来完成，无需改动核心代码。