Octop 用户与管理 API：管理账户与设置

使用 Octop 的 /api/users 和 /api/admin 端点管理用户账户、角色、审计日志以及平台设置（仅限管理员）。

管理团队账号、邀请和平台设置。需要「管理用户」权限（管理员默认具备）。

设置页权限和对话是分开的：新账号已经可以和专家聊天，但不能改通道、连接器或知识库，除非你在管理 → 用户里授予。页面邀请表单可以预勾这些选项；用 API 创建用户则不会自动授予。

​

用户管理

方法	路径	描述
GET	/users/permissions	本地化权限目录
GET	/users	列出所有用户
POST	/users	创建新用户
GET	/users/{id}	获取用户详情
PATCH	/users/{id}	更新角色、显示名、邮箱、启用状态或 permissions
DELETE	/users/{id}	删除用户
POST	/users/{id}/reset-password	重置用户密码
POST	/users/{id}/unlock-login	解除用户登录锁定
GET	/users/invites	列出邀请
POST	/users/invites	创建邀请
POST	/users/invites/{invite_id}/revoke	撤销待使用邀请

在页面中打开管理 → 用户，点击邀请用户。把链接发给对方，默认 7 天过期（可设 1–90 天）。对方兑换后会得到普通用户账号和默认助手。

也可以用上面的接口创建和撤销邀请。

​

创建用户

curl -X POST http://127.0.0.1:8088/api/users \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "alice",
    "password": "TempPass123",
    "role": "user",
    "display_name": "Alice Chen",
    "workspace_root_dir": "/data/alice",
    "token_quota": 1000000
  }'

成功时返回 201 Created。可选 workspace_root_dir 限制该用户专家可写入的存储根目录。可选 token_quota 限制该账号的 token 用量（创建时即生效）。

​

更新用户

curl -X PATCH http://127.0.0.1:8088/api/users/5 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"role": "admin", "display_name": "Alice Chen (管理员)"}'

可更新字段包括 role、display_name、enabled 和 locale。通过设置 "enabled": false 可禁用账户，而无需删除。

​

重置密码

curl -X POST http://127.0.0.1:8088/api/users/5/reset-password \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"new_password": "NewTempPass123"}'

返回 204 No Content。

​

解除用户锁定

curl -X POST http://127.0.0.1:8088/api/users/5/unlock-login \
  -H 'Authorization: Bearer <token>'

连续多次登录失败后（默认阈值由 OCTOP_LOGIN_MAX_ATTEMPTS 控制），账户会自动锁定。管理员可以通过此端点在锁定期结束前提前解除锁定。

​

管理员概览

获取平台级汇总信息：

curl http://127.0.0.1:8088/api/admin/overview \
  -H 'Authorization: Bearer <token>'

响应：

{"user_count": 12, "agent_count": 5, "...": "..."}

​

审计日志

获取最近的审计日志记录：

curl http://127.0.0.1:8088/api/admin/audit-log \
  -H 'Authorization: Bearer <token>'

​

轮换 JWT 密钥

JWT 密钥轮换仅支持通过 CLI 操作，无法通过 API 进行：

octop admin rotate-jwt-secret

轮换 JWT 密钥会立即使所有正在进行的会话失效，包括管理员自己的会话。轮换后所有人都必须重新登录。