# WarRoom 多角色权限

最后更新：2026-07-19

## 权限矩阵

| 角色 | 审计读取 | 模拟开平仓 | 自动策略开关 | 账户重置 | 系统管理 |
| --- | --- | --- | --- | --- | --- |
| `viewer` | 是 | 否 | 否 | 否 | 否 |
| `trader` | 是 | 是 | 是 | 否 | 否 |
| `admin` | 是 | 是 | 是 | 是 | 是 |

公共行情、信号和模拟账户状态继续保持只读公开。受保护接口在未登录时返回 401，在角色权限不足时返回 403，并写入 `authorization_denied` 审计事件。

## 配置文件

默认配置文件为 `/etc/btcapp/auth-users.json`。文件存在时优先于旧的 `PAPER_ADMIN_USER` 和 `PAPER_ADMIN_PASSWORD_HASH`；文件不存在时，旧管理员配置自动映射为 `admin`，保证升级不中断。

```json
{
  "version": 1,
  "users": {
    "ops-viewer": {
      "role": "viewer",
      "password_hash": "pbkdf2_sha256$..."
    },
    "trade-desk": {
      "role": "trader",
      "password_hash": "pbkdf2_sha256$..."
    },
    "admin": {
      "role": "admin",
      "password_hash": "pbkdf2_sha256$..."
    }
  }
}
```

配置目录保持 `0750 root:www-data`，配置文件保持 `0640 root:www-data`，使以 `www-data` 运行的 API 只能读取哈希；其他用户无权读取。不得写入明文密码。

## 创建与轮换

交互方式不会把密码放入 shell 历史：

```bash
sudo warroom-auth-users set --user ops-viewer --role viewer
sudo warroom-auth-users set --user trade-desk --role trader
sudo warroom-auth-users set --user admin --role admin
```

自动化可通过标准输入传入一次性秘密：

```bash
printf '%s\n' "$NEW_PASSWORD" | sudo warroom-auth-users set \
  --user trade-desk --role trader --password-stdin
```

每次创建、轮换或删除后重启对应 API 服务，使旧会话立即失效：

```bash
sudo systemctl restart btc-dca-api.service
sudo systemctl restart btc-dca-node.service
```

查看账号与角色不会输出哈希：

```bash
sudo warroom-auth-users list
```

删除账号时，工具拒绝删除最后一个用户：

```bash
sudo warroom-auth-users remove --user ops-viewer
```

## 验证

`/api/auth/status` 返回当前会话的 `role` 和 `permissions`。`/api/health` 只公开已启用角色和用户数量，不公开用户名或密码哈希。

部署验收至少覆盖：

- 未登录读取 `/api/audit` 返回 401。
- `viewer` 读取审计返回 200，写交易返回 403。
- `trader` 可执行开平仓和自动开关，重置账户返回 403。
- `admin` 可进入账户重置逻辑。
- 登录、退出、写操作和越权尝试均包含角色审计字段。