管理工具使用¶
本文档介绍 PowerCore / PE Agent 平台的两类管理入口：基于 SQLAdmin 的数据库管理后台，以及面向运维与开发的 Web 工具集。二者职责不同，通常配合使用。
| 入口 | 路径（默认） | 主要用途 |
|---|---|---|
| SQLAdmin 管理后台 | /admin |
用户、模型、智能体、任务等数据库记录的增删改查 |
| Web 工具集 | /{peagent_path}/common/tools（默认 /peagent/common/tools） |
文件/Skills 运维、日志、跨环境拷贝 Agent 等 |
路径说明
{peagent_path} 由部署配置决定，默认为 peagent。下文 URL 均以默认值举例，实际环境请替换为对应前缀。
1. 访问与权限¶
1.1 登录要求¶
- SQLAdmin（
/admin）：必须已登录，且满足管理员权限（见下表）。 - Web 工具集：未登录时可打开页面，但会弹出登录框；登录后按角色显示可用菜单。
登录态通过 Cookie 中的 token 或请求头 Authorization: Bearer <token> 传递，与 PE Agent 主站登录一致。
1.2 角色与权限¶
平台用户 role 字段决定可见功能。常见角色如下：
| 角色 | 说明 | SQLAdmin | Web 工具集 |
|---|---|---|---|
admin / super-admin |
平台管理员 | ✅ | 全部菜单 |
Lab-dev / IIL-dev 等 *-dev |
开发/实验室账号 | ✅（见 1.3） | 文件管理、更新任务、拷贝 Agent、查询日志等 |
IIL / TLT |
特定业务角色 | — | 更新任务、拷贝 Agent、查询日志 |
common（或未设置） |
普通用户 | ❌ | 文件管理、Skills 管理（沙箱目录） |
1.3 SQLAdmin 访问控制¶
访问 /admin/* 时，中间件会校验：
- 用户已登录；
- 满足以下任一条件：
role为admin或super-admin；username为Doctor-chen；- 手机号在白名单内（运维预留账号）。
不满足条件将返回 403 无权限。
2. SQLAdmin 管理后台（/admin）¶
SQLAdmin 提供对核心数据表的 Web CRUD 界面，适合日常运维、审核与批量订正。
2.1 模块一览¶
| 模块 | 数据表 | 主要字段 / 能力 |
|---|---|---|
| 用户管理 | users |
ID、用户名、手机号、角色、创建/更新时间；支持按 ID/用户名/手机号搜索 |
| 智能体管理 | agents |
名称、创建者、隐私级别、软删除标记；默认仅显示未删除（is_del = 0） |
| 任务管理 | tasks |
任务 ID、名称、创建者、时间戳 |
| 大语言模型管理 | llms |
模型名称、版本、API Key |
| 节点管理 | nodes |
节点 ID、名称、所属 Agent |
| 管家智能体管理 | butler_agents |
名称、绑定 LLM、管家类型、隐私级别 |
| 推荐管家管理 | recommend_butlers |
展示名称、排序、描述 |
| 推荐智能体管理 | recommend_agents |
入口标识、关联 Agent、排序、删除标记 |
| 默认管家管理 | default_butlers |
入口（entrance）、名称、关联管家 ID |
| 知识库分享管理 | knowledge_shares |
文件名、分类、大小、分享者、审批状态、审批人、审批时间 |
| 通用节点管理 | common_nodes |
名称、创建者、隐私级别、代码片段 |
| 系统信息管理 | sys_info |
密钥、平台标识、运行时配置 JSON、更新时间 |
2.2 典型操作¶
用户与角色¶
- 进入 用户管理，搜索目标用户（手机号或用户名）。
- 编辑记录，修改
role字段（如设为admin或Lab-dev）。 - 保存后，用户重新登录或刷新即可生效。
大语言模型配置¶
- 进入 大语言模型管理。
- 新增或编辑 LLM 记录，填写名称、版本、API Key。
- 前端 Agent / Butler 通过 LLM ID 引用该配置。
推荐与默认管家¶
- 推荐管家 / 推荐智能体：控制首页或入口页的展示顺序（
display_order）与关联资源。 - 默认管家：按
entrance（入口标识）绑定不同场景下的默认 Butler。
知识库分享审核¶
用户提交知识库共享申请后，管理员在 知识库分享管理 中处理：
approval_status |
含义 |
|---|---|
pending |
待审批 |
approved |
已通过，进入公共库 |
rejected |
已拒绝 |
操作步骤：
- 按文件名或分类名搜索待审记录（
approval_status = pending）。 - 打开详情，将状态改为
approved或rejected。 - 填写
approver_id（审批人用户 ID），保存后approval_time由系统记录。
详细共享机制见 共享方案。
系统信息（SysInfo）¶
系统信息管理 中的 config 字段为 JSON，可在不重启的情况下覆盖部分运行时参数，例如：
DOC_UNDERSTAND_MODEL_ID— 文档理解模型READ_IMAGE_MODEL_ID— 读图模型WEB_SEARCH_MODEL_ID— 联网搜索模型
服务启动时会自动加载 SysInfo 首条记录的 config。
3. Web 工具集¶
3.1 进入工具集¶
浏览器访问：
示例：https://example.com/peagent/common/tools
登录后左侧显示当前角色可用的工具菜单；点击菜单项在右侧 iframe 或新页面中打开对应功能。
3.2 菜单与角色对照¶
| 菜单 ID | 名称 | 允许角色 | 实际路径 |
|---|---|---|---|
file-manager |
文件管理 | admin、super-admin、Lab-dev、IIL-dev、common | /{peagent_path}/common/file-manager |
skills-manager |
Skills 管理 | admin、super-admin、common | /{peagent_path}/common/skills-manager |
update-task |
更新任务 | admin、super-admin、Lab-dev、IIL、TLT | /{peagent_path}/tools/update-task |
copy-agent |
拷贝 Agent | admin、super-admin、Lab-dev、IIL、TLT | 工具页内嵌表单，调用 POST /{peagent_path}/common/copy-agent |
image-manager |
图片管理 | admin、super-admin | /{peagent_path}/common/image-manage |
update-image |
更新图片 | admin、super-admin | /{peagent_path}/common/config-image |
query-log |
查询日志 | admin、super-admin、Lab-dev、IIL、TLT | /{peagent_path}/common/log-view |
rag-manager |
RAG 管理 | admin、super-admin | 预留入口（当前为占位） |
embed-nodes |
节点嵌入 | admin、super-admin | /{peagent_path}/agents/embed-nodes-page |
API 文档
静态 API 说明页位于 /{peagent_path}/common/docs，单篇文档为 /{peagent_path}/common/doc/{文件名}.html。
4. 文件与 Skills 沙箱规则¶
文件管理与 Skills 管理共用一套按角色隔离的路径解析逻辑。
4.1 根目录¶
| 类型 | 物理路径（管理员/dev） | 普通用户沙箱 |
|---|---|---|
| 文档 | documents/ |
documents/{手机号}/ |
| Skills | skills/skills/ |
documents/{手机号}/skills/ |
普通用户首次访问时，系统自动创建其沙箱目录。
4.2 权限矩阵¶
| 角色 | 文件根目录 | 路径约束 |
|---|---|---|
admin / super-admin |
全局 documents/ 或 skills/skills/ |
无额外限制；根目录列表仅显示文件夹 |
*-dev |
同上 | 进入子目录时，路径须包含本人手机号 |
common |
个人沙箱 | 不可访问他人目录；防 .. 路径遍历 |
所有读写接口均校验：解析后的绝对路径必须落在用户根目录内，否则返回 403。
4.3 文件管理功能¶
路径：/{peagent_path}/common/file-manager
支持操作：
- 浏览、新建文件夹 / 空文件、重命名、删除、拷贝
- 单文件或整文件夹上传（保留目录结构）
- 下载
- 拷贝到 Skills：将 documents 下文件复制到 skills 目录
- 在线编辑：支持 txt、md、py、json、yaml 等文本类型，单文件上限 5 MB；保存前自动备份为
.bak
4.4 Skills 管理功能¶
路径：/{peagent_path}/common/skills-manager
能力与文件管理类似，额外支持：
- 拷贝到 Documents：将 Skills 文件复制到 documents 目录
- 独立在线编辑器：
/{peagent_path}/common/skill-editor
5. 运维工具详解¶
5.1 拷贝 Agent（跨环境）¶
权限： 仅 admin / super-admin 可调用 API（菜单对 dev 角色可见，但 POST 接口仍校验管理员）。
接口： POST /{peagent_path}/common/copy-agent
请求体：
| 字段 | 类型 | 说明 |
|---|---|---|
source_db_url |
string | 源环境：2c 或 139 |
target_db_url |
string | 目标环境：2c 或 139 |
agent_id |
int | 源库中的 Agent ID |
creator_id |
int | 目标库中新 Agent 的创建者 ID，默认 1 |
agent_name_suffix |
string | 可选，追加到 Agent 名称后 |
拷贝范围：
agents表记录（生成新 ID）- 关联
nodes（维护节点 ID 映射） - 关联
node_relations（按映射重写节点引用） - 节点附件文件（通过 scp 在预设服务器间同步
documents/下文件）
返回结果包含 new_agent_id、拷贝节点数、关系数及附件迁移说明。
5.2 更新任务¶
路径：/{peagent_path}/tools/update-task
用于将已有 Task 的执行计划与节点配置，按新版 Agent 定义重新生成。适合 Agent 升级后批量刷新历史任务模板。
5.3 节点嵌入¶
路径：/{peagent_path}/agents/embed-nodes-page
管理员将通用节点或代码片段批量嵌入指定 Agent 的节点图，调用 POST /{peagent_path}/agents/embed-nodes 完成写入。
5.4 图片管理 / 更新图片¶
| 功能 | 路径 | 说明 |
|---|---|---|
| 图片管理 | /{peagent_path}/common/image-manage |
浏览与管理 img_base 等图片资源 |
| 更新图片 | /{peagent_path}/common/config-image |
更新平台配置相关图片 |
5.5 系统提示词（管理员 API）¶
虽未出现在默认工具菜单中，管理员可直接访问：
- 页面：
/{peagent_path}/common/system-prompt - 读写：
GET/POST /{peagent_path}/common/system-prompt与/api/system-prompt
配置文件：config/system_prompt.yaml，保存后立即生效。
5.6 日志查看¶
路径：/{peagent_path}/common/log-view
- 默认 tail 文件：
aipower.log - 流式接口：
GET /{peagent_path}/common/api/log-stream（Server-Sent Events，类似tail -f） - 指定路径：
GET /{peagent_path}/common/log-stream?path=xxx.log（仅允许.log后缀，防路径遍历）
允许角色：admin、super-admin、Lab-dev、IIL、TLT。
5.7 重置密码¶
- 页面：
/{peagent_path}/common/reset-password（需登录） - 规则：两次密码一致，长度至少 6 位；使用 bcrypt 哈希后写回用户表
6. 与业务功能的衔接¶
flowchart LR
subgraph 用户侧
A[上传知识库 / 申请共享]
B[维护个人 Skills / 文档]
end
subgraph 管理侧
C[SQLAdmin 知识库分享审核]
D[Web 工具集 文件 / Skills 管理]
E[SQLAdmin 用户 / LLM / 推荐位]
end
A --> C
B --> D
E --> F[PE Agent 前台体验]
C --> F
D --> F
| 业务场景 | 推荐入口 |
|---|---|
| 新用户授权为管理员 | SQLAdmin → 用户管理 |
| 配置新 LLM 供 Agent 选用 | SQLAdmin → 大语言模型管理 |
| 审核团队共享的知识库 | SQLAdmin → 知识库分享管理 |
| 运维上传批量文档 / Skill | Web 工具集 → 文件管理 / Skills 管理 |
| 从测试环境复制 Agent 到生产 | Web 工具集 → 拷贝 Agent |
| 排查线上报错 | Web 工具集 → 查询日志 |
| 调整首页推荐 Agent | SQLAdmin → 推荐智能体管理 |
7. 常见问题¶
Q：访问 /admin 返回 401 或 403？
A：确认已在 PE Agent 主站登录，且账号 role 为 admin/super-admin，或为预留白名单账号。
Q：普通用户能看到其他人的 documents 吗？
A：不能。普通用户仅可操作 documents/{自己的手机号}/ 下的内容。
Q：dev 角色在文件管理根目录为什么只看到文件夹？
A：根目录对 admin/dev 仅列出子目录；dev 用户需进入包含自己手机号的目录才能管理文件，且 API 会校验路径中必须含本人手机号。
Q：拷贝 Agent 菜单可见但提交失败？
A：POST /common/copy-agent 仅允许 admin/super-admin；dev 角色需联系管理员执行或使用管理员账号。
Q：RAG 管理菜单打不开？
A：当前为预留入口，完整 RAG 运维请参考 增强检索（RAG） 及 SQLAdmin 相关数据维护。
8. 相关文档¶
- 共享方案 — 知识库审核与公共资源发布流程
- 技能（Skill） — Skills 目录结构与使用方式
- 增强检索（RAG） — 知识库与 GraphRAG
- 系统集成 · API 参考 — OpenAPI 与 REST 接口