YG_FT/docs/governance-user-guide.md

平台治理功能使用指南

版本：v1.3 日期：2026-08-19 适用版本：YG Fine-Tune Platform v1.0+ 更新说明：合并组织权限、审批和运行日志入口；取消项目空间菜单但保留旧接口兼容

---

目录

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

---

1. 快速入门

1.1 平台治理是什么？

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

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

1.2 三种内置角色

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

1.3 入口在哪里？

治理、组织和运维功能按职责分布在左侧导航栏的 「平台治理」、「系统设置」 和 「算力资源」 分组下：

平台治理
├── 组织与权限      ← 用户与角色、租户与配额（仅 admin）
├── 资源授权        ← 数据集、模型等资源授权（仅 admin）
└── 审批中心        ← 待审批请求与审批策略（仅 admin）

系统设置
├── 平台性能        ← 系统资源监控
└── 运行日志        ← 运行日志、审计记录、操作诊断

算力资源
└── 算力节点        ← GPU 分配与管理（仅 admin）

⚠️ 平台治理、资源授权、审批中心和算力节点菜单仅 admin 用户能看到。运行日志入口继续沿用原权限，普通用户可查看系统/训练日志；审计记录和操作诊断页签仅 admin 可见。

重要变更（v1.2）：非 admin 用户默认可以访问所有业务功能菜单（模型训练、评测、推理、数据集、数据处理等），无需管理员单独分配权限；治理和资源管理入口仍仅 admin 可见。

当前菜单调整（v1.3）：平台不再提供项目空间菜单和项目级操作入口。历史项目表、接口和旧地址仅作为兼容层保留，当前资源访问以用户所有权、租户边界（如启用）和资源 ACL 为准；新建业务资源不再要求项目字段。

---

2. 用户与权限管理

2.1 权限模型概述（v1.1 更新）

平台采用基于角色的简化权限模型：

用户类型	可见菜单	说明
admin（管理员）	全部菜单	包括组织权限、审批、运行日志、平台治理和算力节点等管理功能
非 admin 用户	除管理功能外的所有业务菜单	模型训练/评测/推理、数据集、数据处理等

核心原则：

• 非 admin 用户默认拥有所有业务功能的访问权限，无需单独分配
• 仅以下功能仅管理员可见：
  • 平台治理 - 组织与权限（用户、角色、租户与配额）
  • 平台治理（资源授权、审批中心）
  • 算力节点（GPU 分配）
  • 运行日志中的审计记录和操作诊断

资源级别的访问控制通过 ACL（访问控制列表） 实现，详见第 4 章。

2.2 创建用户

路径：平台治理 → 组织与权限 → 用户与角色 → 创建用户

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

创建后用户可以立即用该账号登录，无需额外分配页面权限。

2.3 管理员专属功能

以下功能仅 admin 角色可见，对其他用户隐藏：

功能分组	包含菜单	路由前缀
平台治理 - 组织与权限	用户、角色、租户与配额	/organization
平台治理 - 资源授权	数据集、模型等资源 ACL	/resource-acl
平台治理 - 审批中心	待审批请求、审批历史与策略	/approval-instances
系统设置 - 运行日志	系统/训练日志；管理员可查看审计记录、操作诊断	/logs
算力资源 - 算力节点	GPU 分配与管理	/compute

2.4 重置用户密码

两种方式：

方式一：管理员重置

1. 在用户列表中找到目标用户
2. 点击「重置密码」
3. 输入新密码，确认

方式二：用户自行修改

1. 用户登录后在「组织与权限」页面的「用户与角色」页签点击「修改密码」按钮
2. 输入旧密码 + 新密码（至少 6 位）
3. 确认修改

2.5 删除用户

路径：组织与权限 → 用户与角色 → 用户列表 → 操作列「删除」

⚠️ 删除用户时会级联清理其所有关联数据：

• 该用户创建的数据集、基座模型、微调产物、评测任务
• 该用户的 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 看到	普通用户看到
基座模型（容器内注册的本地模型）	全部	全部（共享资源）
数据集	全部	自己创建的 + 被 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 直接操作：

# 授予 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
动作类型	使用中文动作选择，例如创建数据集、删除模型、授予资源权限
目标资源类型	使用中文资源类型选择，例如数据集、模型、训练任务
关键词	模糊搜索目标 ID 或审计详情
目标 ID	对指定资源 ID 进行精确查询
时间范围	开始时间 ~ 结束时间

项目筛选已移除。底层接口仍兼容历史 project_id 参数，但当前平台不再提供项目菜单。

6.3 导出审计日志

运行日志的「审计记录」页签提供「导出 CSV」按钮；「操作诊断」页签用于检索失败操作和接口耗时，可用于问题追溯。

6.4 日志保留策略

审计日志受留存策略控制（平台治理 → 组织与权限 → 租户与配额）。默认保留 30 天，超期自动清理。

---

7. 常见问题与排查

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

根据 v1.1 权限模型：

1. 业务菜单（训练、评测、推理、数据集等）：普通用户默认全部可见，无需分配
2. 管理菜单（组织与权限、资源授权、审批中心、算力节点，以及运行日志中的审计/诊断页签）：仅 admin 可见，这是设计如此

如果普通用户看不到业务菜单，请检查：

• 用户是否正常登录（token 是否有效）
• 用户状态是否为 active（未被停用）

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

说明该用户没有被分配所选择的 GPU 卡。解决方法：

1. admin 进入「算力节点」→「GPU 分配」标签页
2. 为该用户分配对应的 GPU
3. 用户刷新页面重新选择 GPU

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

正常情况下 delete_user 会级联清理关联数据。如果仍有残留：

• 训练任务：设计上保留不删（避免算力节点物理数据不一致），这是预期行为
• 登录时长排行：可能来自旧的 session 记录（已修复：改用 INNER JOIN 过滤已删除用户）

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

审批实例需要 admin 在「审批中心」手动处理。如果长时间无人处理：

• 可以在数据库中直接将 approval_instances.status 改为 rejected
• 或者由 admin 直接以自身身份执行该操作（admin 有旁路权限）

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

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

返回格式：

{
  "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 重置。

Q7: 为什么移除了「页面权限」功能？（v1.1 变更说明）

旧版本要求管理员为每个用户单独分配页面权限码，这导致：

• 新用户创建后需要额外操作才能使用系统
• 权限配置复杂，容易出错
• 与实际使用场景不匹配（大多数用户需要访问大部分功能）

**新模型（v1.1）**简化为：

• 非 admin 用户默认拥有所有业务功能的访问权限
• 仅管理员专属功能（用户管理、平台治理、算力节点）受角色限制
• 资源级别控制通过 ACL 实现，更灵活

---

附录：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	审批人