YG_FT/docs/governance-user-guide.md

# 平台治理功能使用指南

> 版本：v1.0
> 日期：2026-08-10
> 适用版本：YG Fine-Tune Platform v1.0+

---

## 目录

1. [快速入门](#1-快速入门)
2. [用户与权限管理](#2-用户与权限管理)
3. [GPU 算力分配](#3-gpu-算力分配)
4. [资源可见性与隔离](#4-资源可见性与隔离)
5. [审批流程管理](#5-审批流程管理)
6. [审计日志查询](#6-审计日志查询)
7. [常见问题与排查](#7-常见问题与排查)

---

## 1. 快速入门

### 1.1 平台治理是什么？

平台治理是一套**多租户、多角色、细粒度权限控制**体系，用于在多人协作使用 AI 微调平台时，确保：

- 每个用户只能看到和操作自己有权限的资源
- GPU 算力按需分配，避免资源争抢
- 高风险操作（删除、停止任务）有审批记录可追溯
- 所有操作都有审计日志

### 1.2 三种内置角色

| 角色 | 能做什么 | 不能做什么 |
|---|---|---|
| **超级管理员 (admin)** | 全部操作；管理用户、分配 GPU、审批、查看全部资源 | — |
| **操作员 (operator)** | 创建数据集/模型、训练/评测/推理任务 | 管理用户、分配 GPU、修改他人权限 |
| **观察员 (viewer)** | 查看被授权的资源 | 创建或修改任何资源 |

### 1.3 入口在哪里？

所有治理功能集中在左侧导航栏的 **「系统设置」** 分组下：

```
系统设置
├── 用户设置        ← 用户 CRUD + 角色权限 + 密码管理
├── 租户管理        ← 组织/团队（可选）
├── 项目空间        ← 项目级资源隔离（可选）
├── 审批模板        ← 定义哪些操作需要审批
├── 审批中心        ← 处理待审批请求
└── 审计日志        ← 查看所有操作记录
```

> ⚠️ 以上菜单**只有 admin 用户能看到**。普通用户登录后不会出现这些入口。

---

## 2. 用户与权限管理

### 2.1 创建用户

**路径**：`用户设置` → `创建用户`

1. 以 admin 身份登录平台
2. 进入「用户设置」页面
3. 点击右上角「创建用户」按钮
4. 填写信息：
   - **账号**：登录用户名（如 `zhangsan`）
   - **显示名称**：如 `张三`
   - **密码**：初始密码（默认 `Platform@123`）
   - **角色**：选择 `admin` / `operator` / `viewer`
5. 点击保存

创建后用户可以立即用该账号登录。

### 2.2 管理用户权限

**路径**：`用户设置` → 用户列表 → 操作列「页面权限」

#### 给普通用户分配业务模块权限

点击某用户的「页面权限」按钮，弹出对话框：

```
为 张三 分配可访问的页面模块：

☑ 服务看板      ☑ 模型训练      ☑ 模型评测
☑ 模型推理      ☑ 模型管理      ☑ 数据集管理
☐ 数据处理      ☐ 数据类型转换  ☐ 算力节点    ← 不勾选则不可见
☑ 平台性能      ☑ 查看日志

[取消]  [保存]
```

勾选需要的模块，点「保存」即可。

> **注意**：
> - 「用户与权限」这个选项**只有 admin 能看到**，其他用户即使被赋权也不会显示
> - admin 用户的权限**不可更改**，始终是全选状态且只读

#### 限制说明

| 权限码 | 说明 | 谁能拥有 |
|---|---|---|
| `user-settings` | 用户设置、租户管理、项目空间、审批、审计日志 | **仅 admin** |
| `compute` | 算力节点、GPU 分配 | **仅 admin** |
| 其他业务权限 | 训练、评测、推理、模型、数据集等 | admin 可分配给任何人 |

### 2.3 重置用户密码

**两种方式**：

**方式一：管理员重置**
1. 在用户列表中找到目标用户
2. 点击「重置密码」
3. 输入新密码，确认

**方式二：用户自行修改**
1. 用户登录后在「用户设置」页面点击「修改密码」按钮
2. 输入旧密码 + 新密码（至少 6 位）
3. 确认修改

### 2.4 删除用户

**路径**：`用户设置` → 用户列表 → 操作列「删除」

> ⚠️ 删除用户时会**级联清理**其所有关联数据：
> - 该用户创建的数据集、基座模型、微调产物、评测任务
> - 该用户的 ACL 授权记录、GPU 分配记录
> - 该用户的审批实例、审计日志、项目成员关系
> - **训练任务保留不删**（避免算力节点上的物理任务数据不一致）

---

## 3. GPU 算力分配

### 3.1 为什么需要 GPU 分配？

当服务器有多张 GPU 卡（如 8×A800）时，需要指定**哪个用户能用哪张卡**：

- 避免两个人同时选同一张卡导致训练冲突
- 按团队/项目隔离算力资源
- 控制每个用户的 GPU 配额

### 3.2 分配 GPU（仅 admin）

**路径**：`算力节点` → `GPU 分配` 标签页

1. 以 admin 登录，进入「算力节点」页面
2. 点击顶部的 **「GPU 分配」** 标签（只有 admin 可见）
3. 点击 **「分配 GPU」** 按钮
4. 填写：
   - **算力节点**：选择节点（如 `gpu-node-01`）
   - **GPU 序号**：卡号（0, 1, 2, ... 7）
   - **用户**：选择要分配给谁
5. 点「确认分配」

示例：把节点 `gpu-node-01` 的第 0、1 号卡分配给用户 `zhangsan`：

```
┌─────────────────────────────────────┐
│  分配 GPU                    [×]  │
├─────────────────────────────────────┤
│  算力节点:  [gpu-node-01 ▼]         │
│  GPU 序号:  [0          ▲]         │
│  用户:      [zhangsan    ▼]         │
│                                     │
│       [取消]     [确认分配]         │
└─────────────────────────────────────┘
```

分配后的效果：

| 用户 | 可用 GPU |
|---|---|
| admin | 全部 GPU（不需要显式分配） |
| zhangsan | gpu-node-01 的 0、1 号卡 |
| lisi | （未分配，不可用） |

### 3.3 撤销分配

在 GPU 分配列表中，每条记录右侧有「撤销」按钮，点击后确认即可移除该分配。

### 3.4 用户视角：创建训练任务时的 GPU 选择

- **admin**：下拉列表显示全部可用 GPU
- **被分配了 GPU 的用户**：只显示被分配给自己的卡
- **未分配任何 GPU 的用户**：显示提示「未分配 GPU，请联系管理员」，无法提交训练任务

---

## 4. 资源可见性与隔离

### 4.1 自动生效的隔离规则

无需手动配置，以下规则自动生效：

| 资源类型 | admin 看到 | 普通用户看到 |
|---|---|---|
| **基座模型**（容器内注册的本地模型） | 全部 | **全部**（共享资源，有 model-manage 权限即可见） |
| **数据集** | 全部 | **自己创建的** + 被 ACL 授权的 |
| **微调产物**（训练输出的模型） | 全部 | **自己训练的** + 被 ACL 授权的 |
| **评测任务** | 全部 | **自己创建的** + 被 ACL 授权的 |
| **推理/对比任务** | 全部 | **自己创建的** + 被 ACL 授权的 |

### 4.2 实际场景示例

假设有三个用户：**admin**、**zhangsan**（算法工程师）、**lisi**（标注员）

```
zhangsan 上传了数据集 ds_alpaca、ds_sharegpt
zhangsan 训练出了模型 ft_qwen_001
lisi 上传了数据集 ds_label
admin 注册了基座模型 Qwen3-1.7B
```

各用户看到的资源：

| 用户 | 数据集 | 基座模型 | 微调产物 |
|---|---|---|---|
| **admin** | ds_alpaca, ds_sharegpt, ds_label (3个) | Qwen3-1.7B | ft_qwen_001 |
| **zhangsan** | ds_alpaca, ds_sharegpt (2个) | Qwen3-1.7B | ft_qwen_001 |
| **lisi** | ds_label (1个) | Qwen3-1.7B | (无) |

### 4.3 ACL 资源授权（高级用法）

如果 zhangsan 想让 lisi 也能看到自己的数据集 `ds_alpaca`：

> 此功能需要在资源详情页提供「资源授权」按钮（前端已预留接口），当前可通过 API 直接操作：

```bash
# 授予 lisi 对 ds_alpaca 的读权限
curl -X PUT /modelTF/resources/dataset/ds_alpaca_id/acl \
  -H "Authorization: Bearer platform-token-admin" \
  -d '{
    "acls": [
      {"principal_type": "user", "principal_id": "lisi_id", "permission": "read"}
    ]
  }'
```

---

## 5. 审批流程管理

### 5.1 哪些操作会触发审批？

| 操作 | 触发条件 | 处理方式 |
|---|---|---|
| 删除他人的数据集 | 非 admin 删除别人创建的数据集 | 创建审批实例 或 admin 直接执行 |
| 删除他人的模型 | 非 admin 删除别人创建的模型 | 同上 |
| 停止他人的训练任务 | 非 admin 停止别人发起的任务 | 同上 |
| 归档/删除项目空间 | 存在待审批变更时 | 拒绝执行 |

**核心规则**：admin 做任何操作都直接执行（旁路）；普通用户操作他人资源时进入审批流程。

### 5.2 审批流程示意

```
普通用户 lisi 尝试删除 zhangsan 的数据集
                │
                ▼
    ┌───────────────────────┐
    │ 后端检查：是 admin 吗？ │
    └──────┬────────────────┘
           │ 否
           ▼
    ┌───────────────────────┐
    │ 创建审批实例            │
    │ status = pending       │
    │ 返回 202（待审批）     │
    └──────────┬────────────┘
               │
               ▼
    ┌───────────────────────┐
    │ admin 在「审批中心」看到 │
    │ 这条待审批请求           │
    │ 点击「通过」或「拒绝」   │
    └──────────┬────────────┘
           │
     ┌─────┴─────┐
     │           │
  通过        拒绝
     │           │
     ▼           ▼
 执行删除    不执行
+审计日志   +审计日志
```

### 5.3 管理审批

**路径**：`系统设置` → `审批中心`

1. 查看待审批列表（status=pending）
2. 点击某条记录查看详情
3. 决策：「通过」或「拒绝」
4. 决策结果自动执行对应操作并记录审计日志

**审批模板**（`系统设置` → `审批模板`）：定义每种操作需要几步审批、每步谁来审。默认模板都是单步（admin 审批即可）。

---

## 6. 审计日志查询

### 6.1 什么是审计日志？

平台上所有**写操作**和**敏感操作**都会自动记录审计日志，包括：

- 用户创建/删除/修改
- 权限变更
- GPU 分配/撤销
- 资源上传/删除
- 训练任务启动/停止
- 审批决策

### 6.2 查询审计日志

**路径**：`系统设置` → `审计日志`

支持筛选条件：

| 筛选项 | 说明 |
|---|---|
| 操作人 | 按用户 ID 过滤 |
| 动作类型 | 如 `user.create`, `dataset.delete`, `gpu.assign` 等 |
| 目标资源类型 | dataset / model / fine_tune_task 等 |
| 时间范围 | 开始时间 ~ 结束时间 |

### 6.3 导出审计日志

审计日志页面底部有「导出 CSV」按钮，导出的文件包含当前筛选条件下的全部记录，可用于合规审计或问题追溯。

### 6.4 日志保留策略

审计日志受**留存策略**控制（`系统设置` → 租户管理 → 绑定留存策略）。默认保留 30 天，超期自动清理。

---

## 7. 常见问题与排查

### Q1: 普通用户看不到某个菜单？

检查两件事：
1. 该用户是否有对应的**权限码**（admin 在「用户设置」→「页面权限」中分配）
2. 该菜单是否属于 **admin 专属**（如「用户设置」「算力节点」——这些对非 admin 永远不可见）

### Q2: 用户创建训练任务时报错"无权使用所选 GPU"

说明该用户没有被分配所选择的 GPU 卡。解决方法：
1. admin 进入「算力节点」→「GPU 分配」标签页
2. 为该用户分配对应的 GPU
3. 用户刷新页面重新选择 GPU

### Q3: 删除用户后看板还显示残留数据？

正常情况下 `delete_user` 会级联清理关联数据。如果仍有残留：
- **训练任务**：设计上保留不删（避免算力节点物理数据不一致），这是预期行为
- **登录时长排行**：可能来自旧的 session 记录，不影响功能，新登录后会更新

### Q4: 审批实例一直 pending 没人处理？

审批实例需要 admin 在「审批中心」手动处理。如果长时间无人处理：
- 可以在数据库中直接将 `approval_instances.status` 改为 `rejected`
- 或者由 admin 直接以自身身份执行该操作（admin 有旁路权限）

### Q5: 如何查看当前所有 GPU 分配情况？

```bash
# admin 调用接口
curl -H "Authorization: Bearer platform-token-admin" \
  /modelTF/compute/gpu-assignments
```

返回格式：
```json
{
  "data": [
    {
      "id": "ga_xxx",
      "node_name": "A800 训练节点",
      "gpu_index": 0,
      "display_name": "张三",
      "assigned_at": "2026-08-10T10:00:00"
    }
  ]
}
```

### Q6: 用户忘记密码怎么办？

两种方案：
1. **admin 重置**：在「用户设置」→ 用户列表 →「重置密码」
2. **用户自助修改**：用户登录后点击「修改密码」（需知道旧密码）

如果是完全忘记且不是 admin，只能由 admin 重置。

---

## 附录：API 快速参考

| 功能 | 方法 | 路径 | 鉴权 |
|---|---|---|---|
| 查看我的 GPU | GET | `/compute/my-gpus` | 登录用户 |
| 查看 GPU 分配 | GET | `/compute/gpu-assignments` | admin |
| 分配 GPU | POST | `/compute/gpu-assignments` | admin |
| 撤销 GPU 分配 | DELETE | `/compute/gpu-assignments/{id}` | admin |
| 修改自己的密码 | POST | `/users/me/password` | 登录用户 |
| 查看审计日志 | GET | `/system/audit-logs` | admin |
| 导出审计日志 | GET | `/system/audit-logs/export` | admin |
| 查看审批列表 | GET | `/approvals` | 登录用户 |
| 审批决策 | POST | `/approvals/:id/steps/:idx/decision` | 审批人 |