Accounts（账号）

账号是整个系统中所有资源的顶层隔离单元。每个账号下面有自己独立的会话、角色、预设和配置。

在单账号模式下，系统会自动创建一个默认账号，不需要手动管理。在多账号模式下，可以通过这组接口来创建和管理多个账号。

这组接口只对 admin 角色开放。普通用户访问会返回 403。

什么时候需要看这页

• 你要在多账号部署下创建或管理账号
• 你要查看、启用或禁用某个账号
• 你要删除不再使用的账号

一个简单例子

# 创建一个新账号
curl -X POST http://localhost:3000/accounts \
  -H 'Content-Type: application/json' \
  -d '{"name": "dev-team", "role": "user"}'

# 列出所有账号
curl http://localhost:3000/accounts

先理解几个词

词	这里的意思
admin	管理员角色，可以管理其他账号
user	普通用户角色，只能管理自己的资源
ACCOUNT_MODE	环境变量，single 表示单账号，multi 表示多账号
disabled	账号被禁用后无法访问任何资源

• ACCOUNT_MODE=single：GET /accounts 只返回默认账号；GET /accounts/:id 只允许读取默认账号；POST / PATCH / DELETE 会返回 409 account_mode_restricted。
• ACCOUNT_MODE=multi：保留完整的账号管理语义。

Account 对象

字段	类型	说明
id	string	账号 ID
name	string	账号名称
role	string	角色：admin / user
status	string	状态：active / disabled
is_default	boolean	是否为默认账号
created_at	integer	创建时间
updated_at	integer	更新时间

列出账号

GET /accounts

响应 200

单账号模式下，这里只会返回默认账号。

{
  "data": [
    {
      "id": "acc_demo",
      "name": "Demo Workspace",
      "role": "user",
      "status": "active",
      "is_default": false,
      "created_at": 1735689600000,
      "updated_at": 1735689600000
    }
  ]
}

创建账号

POST /accounts

请求体

字段	类型	必填	说明
id	string	否	账号 ID，1-120 字符（不传则自动生成）
name	string	是	账号名称，1-120 字符
role	string	否	角色（默认 user）

响应 201

返回 { "data": Account } 。

错误

状态码	code	说明
403	account_forbidden	权限不足
409	account_mode_restricted	单账号模式下不允许创建账号
409	account_conflict	账号 ID 已存在

获取账号详情

GET /accounts/:id

路径参数

单账号模式下，只允许读取默认账号，读取其他账号 ID 会返回 404 account_not_found。

参数	类型	说明
id	string	账号 ID

响应 200

{
  "data": {
    "id": "acc_demo",
    "name": "Demo Workspace",
    "role": "user",
    "status": "active",
    "is_default": false,
    "created_at": 1735689600000,
    "updated_at": 1735689600000
  }
}

错误

状态码	code	说明
403	account_forbidden	权限不足
404	account_not_found	账号不存在

更新账号

PATCH /accounts/:id

至少提供一个字段。默认账号（is_default: true）不允许修改 role 和 status。

路径参数

参数	类型	说明
id	string	账号 ID

请求体

字段	类型	必填	说明
name	string	否	账号名称，1-120 字符
role	string	否	角色：admin / user
status	string	否	状态：active / disabled

请求示例

{
  "name": "Updated Workspace",
  "role": "admin"
}

响应 200

返回 { "data": Account } ，包含更新后的完整账号对象。

错误

状态码	code	说明
400	validation_error	请求体为空或校验失败
403	account_forbidden	权限不足
404	account_not_found	账号不存在
409	account_mode_restricted	单账号模式下不允许更新账号
409	account_protected	默认账号不允许修改 role 或 status

删除账号

DELETE /accounts/:id

硬删除。默认账号不允许删除。如果账号下仍有关联资源（用户、会话等），删除会因外键约束失败并返回 409。

路径参数

参数	类型	说明
id	string	账号 ID

响应 200

{
  "data": {
    "id": "acc_demo",
    "deleted": true
  }
}

错误

状态码	code	说明
403	account_forbidden	权限不足
404	account_not_found	账号不存在
409	account_mode_restricted / account_protected / account_has_resources	单账号模式下不允许删除账号，默认账号不允许删除，或账号下仍有关联资源