管理后台操作指南
PicoAide 管理后台完整操作手册 — 用户、容器、镜像、技能和组管理
管理后台是 PicoAide 的核心管理界面，超管通过 /admin/* 页面完成所有运维操作。本文档按功能模块逐一说明。
管理后台概览
登录超管账号后自动进入管理后台。左侧边栏包含以下导航项：
| 菜单 | 说明 |
|---|---|
| 仪表盘 | 系统概览：用户统计、容器状态、镜像信息 |
| 超管账户 | 管理系统管理员 |
| 用户管理 | 创建/删除用户，查看用户列表 |
| 用户组管理 | 创建/删除组，管理组成员，绑定技能 |
| 镜像管理 | 拉取、删除、升级和迁移镜像 |
| 渠道策略 | 管理 Picoclaw 渠道的启用/禁用 |
| 模型配置 | 配置 AI 模型参数 |
| 技能管理 | 导入、安装和部署技能 |
| 认证配置 | LDAP/OIDC 配置、认证模式切换 |
| 团队空间 | 共享文件夹管理 |
| 系统设置 | 全局系统配置 |
用户管理
用户列表
用户列表页面显示所有用户及其容器状态。列表包含：
- 用户名、角色（超管/普通用户）
- 认证来源（local/ldap/oidc）
- 容器状态（运行中/已停止/不存在）
- 容器 IP 地址
- MCP Token
支持分页显示和用户名关键词搜索。
创建用户
在本地认证模式下，超管可以手动创建用户：
- 点击「创建用户」按钮
- 输入用户名（遵循
^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$格式，最长 64 字符） - 设置初始密码
- 确认创建
创建成功后系统会自动初始化该用户的容器目录。
在统一认证模式下（LDAP/OIDC），用户由认证源自动同步，不允许手动创建。
删除用户
删除用户时：
- 点击对应用户的「删除」按钮
- 确认删除操作
- 系统会：停止并删除容器、归档用户目录到
archive/、删除数据库记录
删除后，用户的工作区会被移动到 archive/<username>-<timestamp>/ 目录，数据不会立即丢失。
批量导入
支持通过 CSV 文件批量导入用户：
- 点击「批量导入」
- 上传包含用户名列表的 CSV 文件
- 系统创建异步任务处理导入
- 通过「任务状态」查询导入进度
容器管理
容器列表
在用户管理页面可以看到每个用户的容器状态。主要状态包括：
- 运行中：容器正常运行，AI Agent 可用
- 已停止：容器已停止，需要手动启动
- 不存在：用户首次登录时自动创建，或已被删除
容器操作
| 操作 | 说明 |
|---|---|
| 启动 | 创建并启动用户容器，分配 IP |
| 停止 | 停止用户容器（保留数据目录） |
| 重启 | 重启用户容器（配置修改后常用） |
容器操作支持单用户和批量模式：
# 批量启动所有容器
POST /api/admin/container/start
容器资源限制
创建容器时可以设置资源限制：
- CPU 限制：以 NanoCPUs 为单位（例如 1 CPU = 1000000000）
- 内存限制：以字节为单位（例如 1GB = 1073741824）
在全局配置中通过 image.cpu_limit 和 image.memory_limit 设置默认值。
容器日志
可以通过管理后台查看指定用户的容器日志，用于排查 AI Agent 运行问题。
镜像管理
本地镜像列表
显示本机已拉取的所有 PicoClaw 镜像，包括：
- 镜像名和标签
- 镜像 ID 和创建时间
- 使用该镜像的用户列表
拉取镜像
支持从配置的远程仓库拉取镜像：
- 进入镜像管理页面
- 点击「拉取镜像」
- 系统从远程仓库获取最新版本
- 拉取进度通过 SSE 流式实时显示
远程仓库标签
查看远程仓库可用的版本标签列表，按版本号降序排列，方便选择要拉取的版本。
镜像升级
升级流程：
- 查看「可升级用户」— 运行旧版本镜像的用户列表
- 选择目标版本
- 执行升级操作
- 系统自动：拉取新镜像、停止旧容器、检查配置迁移规则、创建新容器、启动
镜像迁移
从旧版本镜像向新版本迁移时，系统使用 Picoclaw Adapter 的迁移规则自动转换配置格式。如果迁移链不支持直接升级，系统会提示需要中间版本。
技能管理
技能来源
PicoAide 支持三种导入技能的方式：
| 方式 | 适用场景 |
|---|---|
| Git 仓库 | 团队维护的技能代码库，支持版本管理 |
| ZIP 上传 | 单次部署或从外部获取的技能包 |
| 从仓库安装 | 从已添加的 Git 仓库中选择技能安装 |
添加 Git 仓库
# 仓库配置示例
name: company-skills
url: https://git.example.com/ai/company-skills.git
ref: main
ref_type: branch
public: false
credentials:
- name: gitlab-token
provider: gitlab
mode: https
username: oauth2
secret: <gitlab-personal-access-token>
支持的 Git 地址协议：https://、http://、git@、ssh://。
添加完成后，系统会自动 clone 仓库到工作目录下的 skill-repos/。
安装技能
从已添加的仓库中安装技能：
- 在技能管理页面查看已添加的仓库
- 展开仓库查看包含的技能列表
- 点击「安装」将技能复制到
skill/目录
部署技能
技能安装后需要部署到用户才能生效：
部署到单个用户：
选择技能名称和目标用户名，部署操作会将技能目录复制到用户的 workspace/skills/ 下。
部署到用户组：
选择技能名称和目标用户组，系统会遍历组内所有成员逐一部署。
按组绑定技能（推荐）：
将技能绑定到用户组后，组内所有现有成员会立即获得该技能，后续加入组的成员也会自动部署。
更新技能
- 在仓库管理页面点击「拉取」更新代码
- 重新安装需要更新的技能
- 重新部署到用户或用户组
用户组管理
用户组结构
用户组支持树形结构，可以建立父子关系。例如：
所有员工
├── 研发部
│ ├── 前端组
│ └── 后端组
├── 市场部
└── 运维部
创建和删除组
- 创建组：指定组名和可选的父组
- 删除组：删除组时其成员关系也会清除
组成员管理
- 添加成员：选择目标组，从用户列表中选择成员加入
- 移除成员：从组中移除用户，不影响用户的技能目录
技能绑定
将技能绑定到组后，组内所有成员会自动部署该技能。解绑技能只解除绑定关系，不会删除已经复制到用户工作区的技能目录。
LDAP 组同步
在 LDAP 认证模式下，可以：
- 测试 LDAP 组查询连接
- 手动触发 LDAP 组同步
- 设置定时同步间隔（例如
30m、1h）
同步时系统会自动创建 LDAP 中的组并添加成员。
团队空间
团队空间是共享文件夹功能，超管可以创建对所有用户可见的共享目录。适合存放团队共用的配置文件、模板或数据。
渠道策略
渠道策略管理界面列出所有可用的 Picoclaw 渠道及其全局状态：
- 查看渠道列表（如
web_search、image_gen等） - 设置全局允许/禁止
- 用户的个人设置会与全局策略合并
全局设置
全局设置页面是 web.*、ldap.*、image.* 等配置项的管理入口。修改后即时生效，无需重启服务。