AniaBot

外观

Web 控制面板 ​

AniaBot 内置 Web 控制面板（Vue 3 + Tailwind CSS，构建产物通过 go:embed 嵌入二进制，单文件分发无需额外部署），用于管理配置、查看运行状态与任务日志。

启用与访问 ​

面板默认启用，由数据库中的配置键控制：

键说明默认值
bot.admin_panel.enable是否启用面板true
bot.admin_panel.listen监听地址127.0.0.1:7700

启动后访问 http://127.0.0.1:7700。如需局域网访问，将 listen 改为 0.0.0.0:7700（面板有密码保护，仍建议仅在内网暴露）；容器部署时也可直接用环境变量 ANIA_BOT_ADMIN_PANEL_LISTEN 覆盖（见 环境变量覆盖）。

在面板里把面板关了怎么办？

「启用面板」开关本身也在面板里，关闭并重启后面板不再启动，配置也就无法再通过面板修改。此时无需手动改数据库，用环境变量强制拉起面板即可（优先级高于数据库中的值，不写回数据库）：

powershell
# Windows PowerShell
$env:ANIA_BOT_ADMIN_PANEL_ENABLE = 'true'
.\AniaBot.exe
bash
# Linux / macOS
ANIA_BOT_ADMIN_PANEL_ENABLE=true ./AniaBot

启动后登录面板，把「启用面板」改回开启并重启 Bot，之后即可去掉环境变量正常启动。该机制对任意配置键都有效，规则见 环境变量覆盖。

登录 ​

首次启动时，控制台会打印一次随机初始密码：

============================================================
  Web 控制面板初始密码（仅显示一次，登录后可修改）:
    Xx9aBcDeFg
============================================================

使用该密码登录后，可在左下角「修改密码」中更换。密码以 SHA-256 加盐哈希存储在数据库中；会话为 24 小时有效的 HttpOnly Cookie（持久化在数据库中，Bot 重启后无需重新登录）。修改密码后所有会话会被销毁，各端需使用新密码重新登录。

首次设置向导 ​

全新安装的首次登录会自动进入设置向导，引导完成最基本的配置（其余配置可随时在面板中完善）：

  1. 平台接入 —— 勾选要启用的平台：QQ(NapCat，默认勾选，填写连接地址与 Access Token) 和/或 QQ 官方（填写 AppID / AppSecret，可选沙箱环境）和/或 飞书（填写 App ID / Secret 与事件订阅方式）和/或 Telegram（填写 Bot Token，可选代理）和/或 Discord（填写 Bot Token，需在 Developer Portal 开启 Message Content Intent，可选代理），以及管理员 ID（QQ 为 qq:QQ号，其他平台为带前缀的 ID）
  2. AI 对话模型 —— Base URL、API Key、模型
  3. 完成 —— 保存到数据库后一键「重启 Bot 生效」

向导只出现一次（也可随时「跳过引导」），之后登录直接进入面板。平台至少启用一个，后续也可在「配置 → 平台适配器」随时增删（见 配置详解）。

重启 Bot ​

配置修改需要重启才生效。点击左下角「重启 Bot」即可在面板内完成重启（以相同命令行参数自重启进程），恢复后页面自动刷新；当然也可以在控制台/进程管理器中手动重启。

进程管理器部署

通过 systemd / Docker 等进程管理器运行时，面板重启同样可用——进程退出后管理器会自动拉起新实例。

自动更新 ​

面板「自动更新」页可一键完成版本升级：拉取最新代码 → 拉取依赖 → 构建前端 → 编译 → 替换二进制并重启，全过程实时日志可见。

前提条件 ​

  • 以编译后的二进制方式运行（go run 开发模式下自动更新会被禁用）
  • 部署机器已安装 git、Go、Node.js（编译需要）
  • 在「配置管理 → 自动更新」分组中配置：
键说明默认值
bot.update.source_dirAniaBot 仓库的克隆路径（独立于运行目录的源码目录）；目录为空或不存在时将按 bot.update.git_url 自动克隆；留空则禁用自动更新空
bot.update.git_url非空时更新前覆盖源码目录的 origin 地址空
bot.update.branch跟踪的远端分支main

更新流程 ​

点击「开始更新」后依次执行（任一阶段失败即中止，面板显示错误分类与详情，当前运行的版本不受影响）：

  1. 环境检查 —— git / go / node / npm 可用性；源码目录为空或不存在时自动 git clone（需配置 bot.update.git_url），非空但不是 git 仓库则报错（错误分类：环境缺失 / 仓库错误）
  2. 拉取代码 —— git fetch + git reset --hard origin/<branch>（错误分类：仓库错误，检查网络 / 地址 / 认证）
  3. 拉取依赖 —— go mod tidy，新代码引入的依赖在此下载（错误分类：依赖错误）
  4. 构建前端 —— npm ci + npm run build，保证面板前端也是最新（错误分类：前端构建错误）
  5. 编译 —— go build 输出为 build/AniaBot.update，与运行中的二进制不同名，避免占用冲突（错误分类：编译错误）
  6. 替换二进制 —— 新二进制拷贝为 <程序名>.new，当前程序改名为 <程序名>.old，再改名替换（Windows 不允许覆盖运行中的 exe，但允许重命名）；旧版本保留为 .old 备份，替换失败自动回滚（错误分类：系统错误）
  7. 重启 —— 自动重启进程，面板等待恢复后自动刷新页面（会话持久化，无需重新登录）

回滚

若新版本启动异常，停止进程后将备份文件 <程序名>.old 改回原文件名即可恢复旧版本。

源码目录与运行目录要分开

bot.update.source_dir 应指向一个专门用于更新的 git 克隆目录，不要指向正在开发的仓库——更新时执行的是 git reset --hard，会丢弃该目录中的本地改动。

忘记密码？

用命令行重置（无需登录，重置后退出，再正常启动 Bot 即可）：

bash
./AniaBot -set-password 新密码

该命令会打开与正常运行一致的持久化存储并覆盖密码哈希，使用 MySQL 存储时同样生效（通过环境变量 ANIABOT_STORE_DRIVER / ANIABOT_MYSQL_DSN 引导）。建议先停止 Bot 再执行，尤其是默认的 SQLite 存储（单文件写锁）。

兜底方案：删除数据库中 ania_kv 表 __admin: 命名空间下的 password_hash 行（或直接删除整个数据库重新开始），重启后会重新生成初始密码。

功能页面 ​

状态总览 ​

  • 运行状态卡片：运行时长、适配器连接状态、插件数量、Goroutine 数（与定时任务列表一起每 5 秒自动刷新，标签页隐藏时暂停）
  • 插件列表：名称、说明、作者、版本
  • AI 定时任务：任务列表（标题、目标、Cron、下次/上次执行时间）、新建 / 编辑 / 删除与启用/停用开关，即时生效无需重启；点击任务行可展开详情（任务内容、备注、超时时间、创建者、创建时间）

任务日志 ​

AI 定时任务的执行记录，每 4 秒自动刷新（可关闭），支持按条件筛选：

  • 状态（执行中/成功/超时/出错/中断）、群聊/私聊、目标会话 ID（QQ 为 qq:数字，其他平台带前缀）、触发时间范围、任务标题关键词
  • 每条记录展示状态、目标、触发时间、耗时、LLM 轮数、工具调用次数与 Token 用量；点击记录弹出详情（任务 ID、触发/完成时间、任务内容、错误信息、工具调用明细（名称/参数/结果/耗时）、最终回复等）

操作日志 ​

面板与 AI 工具的管理操作审计（登录/密码、配置修改、定时任务/记忆/技能/知识库/团队管理、配额修改、AI 工具改配置、重启与自动更新、设置向导），按分类与时间筛选，留作安全审计与问题排查。

消息日志 ​

Bot 收发的消息流水（平台、会话、发送者、内容、时间），可筛选查看。

Query 日志 ​

每次 AI 回复的完整执行记录（触发会话、发送者、用户输入、LLM 轮数、工具调用明细、token 用量、最终回复与状态），详见 AI 对话插件。

Token 统计 ​

各会话（群/好友）的 token 消耗统计图表，直观查看 AI 用量分布。

配额管理 ​

查看并管理每日 Token 配额：按会话与全局两个维度展示用量，可查看/重置当日配额状态，启用后超限自动拒绝 AI 请求。配置见 配置详解。

技能管理 ​

查看、上传、删除 Skill（SKILL.md），改动即时热更新，无需重启。

记忆管理 ​

按会话（群/好友）查看、新增、编辑、删除 AI 长期记忆，改动即时生效。

知识库 ​

按作用域（会话库 / 全局库）管理知识库文档：查看、新增、编辑、删除，改动即时生效；全局库仅面板可管理。

Agent 团队 ​

查看、创建、编辑、删除已保存的 Agent 团队定义（成员名称与角色描述），改动即时生效。

配置管理 ​

  • 表单模式：按分组（Bot 基础 / 适配器 / 缓存存储 / AI 对话 / 各插件 / 组件）渲染的编辑表单，敏感字段（API Key、Token 等）不回显、留空表示不修改
  • 高级模式 (JSON)：全部配置键的扁平 JSON 视图，可直接编辑未列入表单的键
  • 保存后写入数据库，重启 Bot 生效（页面会提示）

文件编辑 ​

以 JSON 文本形式编辑两个原独立配置文件的内容：

  • MCP 服务器（files.mcp_json）：MCP Server 定义，格式见 配置详解
  • Prompt 覆盖（files.prompt_json）：按群/好友覆盖 AI 系统提示词

保存前会做 JSON 语法校验，同样重启生效。

通讯录 ​

按平台标签页查看 Bot 加入的群列表（群 ID、群名、成员数）与好友列表（用户 ID、昵称、备注）。各平台支持情况：

  • QQ（NapCat）：群列表 + 好友列表
  • 飞书：群列表（飞书接口不返回成员数，显示为「—」；机器人无好友概念，好友列表为空）
  • Discord：群列表（以文字/公告频道为「群」，名称形如 服务器 / #频道）；好友列表为尽力而为——仅列出本次运行以来网关中出现过私聊会话的对端用户
  • Telegram / QQ 官方：平台没有联系人枚举接口，不出现在标签页中

面板开发 ​

前端源码在 web/ 目录（Vite + Vue 3 + vue-router + Tailwind CSS v4）：

bash
make web          # 等价于 cd web && npm ci && npm run build
make windows      # 打包为单一二进制文件

构建产物输出到 bot/adminpanel/dist（被 gitignore，不提交到仓库），因此克隆后需先 make web 再 go build；面板「自动更新」会在更新流程中自动完成这一步。开发调试可用 cd web && npm run dev（已配置 /api 代理到 127.0.0.1:7700）。

基于 MIT 许可证发布

Copyright © 2026 jeanhua