1 介绍
本文档旨在指定一组针对 Karaage [SRS] 的要求。
1.1 目的
此文档旨在设定 Karaage 的范围，以便其他人了解其发展方向，同时减少功能蔓延的可能性。
1.2 错误
如果本文档中有任何错误，则需要解决。错误通常分为以下三类：
- 必需但未指定的功能。应通过提交对此文档的更改来解决此问题。
- 此处描述的内容与 Karaage 的运行方式不匹配。如果 Karaage 不正确，应通过错误报告解决。如果此规范不正确，则应通过提交对此文档的更改来纠正。
- 文档中有错误。应通过提交对本文档的更改来纠正这些错误。
1.3 范围
Karaage 是一个基于 Web 的界面，用于创建超级计算机或云系统的用户管理系统。因此，它需要与各种数据库（如 LDAP）交互，以写入帐户信息。
Karaage 需要能够根据本地安装要求将某些功能委托给授权人员（例如批准账户）。
还要求能够监控超级计算机的使用信息。目前，这意味着跟踪有关超级计算机上运行的集群作业的信息。此功能需要保持可选状态，因为它可能并不适用于所有站点。
1.4 定义
请参阅 [词汇表 1]。
阅读时请注意，人员、[帐户]这些术语对于 Karaage 来说有严格的定义。
1.5 概述
在下一章“总体描述”中，我们首先定义总体系统。
然后，在具体要求章节中，我们给出了外部接口要求，然后简要描述了 Karaage 的组件和特性。
之后，在“优先级 2和发布计划”章节中讨论了发布计划。
最后，在未来方向一章中讨论了本文档的未来变化。
1.6 参考
[SRS] http://en.wikipedia.org/wiki/Software_requirements_specation
2 总体描述
这是对Karaage及其要求的总体描述。
2.1 产品视角
Karaage 采用了 Web 界面。有三个基本视图：
- 如果未经身份验证的用户看到该网站，他们可以登录或申请帐户。
- 如果管理员登录，则会看到适合管理的菜单。
- 如果其他人登录，则会看到适合非管理职责的菜单。
此外，还可以有两个独立的接口：
- karaage-admin：用户必须是管理员才能访问此网站。
- karaage-registration：即使用户具有管理权限，也会被视为非管理员。
Karaage 存储有关人员、帐户、机构、项目、软件和使用情况的信息，并将其存储在数据库中。这些信息随后根据本地要求复制到外部数据库。这些数据库可能包括 LDAP、Slurm、Gold 和 OpenStack Keystone 数据库。
2.2 产品功能
人们使用 Karaage 申请项目访问权限、登录、更改密码、重置密码、查看使用信息
有些人可能拥有允许额外访问权限的角色 3。项目负责人可以批准加入其项目的请求。研究所代表可以批准为其研究所创建新项目的请求。
管理员使用 Karaage 添加、编辑和查看有关人员、帐户、机构、项目、软件和使用情况的信息。
2.3 用户特征
Karaage 针对不同的目标用户：
管理员：应该对安装、使用的数据存储以及这些数据存储的用途有基本的了解。应该理解词汇表中使用的术语。
最终用户：应该对 Unix 帐户有基本的了解。实际上，这些用户的经验和知识可能有很大差异。
2.4 约束、假设和依赖性
本节记录了 Karaage 的所有约束、可以做出的任何假设以及所需的外部依赖关系。
2.4.1 操作系统依赖性
Karaage 使用的服务器应该能够在 Debian Wheezy 上运行，使用 Python 2.7 语言。
需要一个 MySQL 数据库来存储 Karaage 数据。
2.4.2 假设
Karaage 只是一个软件项目。项目管理旨在获取合适的硬件、安装和根据各个站点的本地需求进行定制。
3 具体要求
本节包含系统的所有功能和质量要求。它对系统及其所有功能进行了详细描述。
3.1 外部接口要求
本节提供了系统所有输入和输出的详细描述。
3.1.1 用户界面
Karaage 是基于网络的，因此预计大多数用户将通过计算机上的网络浏览器来访问它。
根据用户特征，用户界面对于 Karaage 的所有目标用户来说应该简单、易用且一目了然。
3.1.2 软件接口
Karaage 需要访问外部数据存储，目前外部数据存储包括以下一项或多项：
- OpenLDAP
- Directory Server/389
- Slurm
- Gold
其他数据存储由第三方软件提供，例如 karaage-keystore。
PBS 软件使用的提交脚本需要使用 API 来检索提交所需的信息。仅当使用 PBS 软件时才需要此 API。
如果当地有要求，API 还需要提交超级计算机使用情况信息。
3.1.2.1 上传使用数据要求
定义了以下 RPC 过程，可以进行远程调用。XMLRPC 是用于 RPC 过程调用的机制。
parse_usage (机器名称，密码，使用情况，日期，机器名称2，日志类型) 参数：
- machine_name ( str ) – 以此机器进行身份验证。
- 密码（str）–机器的密码。
- 使用情况（数组） – 要处理的日志文件。
- date（str）– 捕获日志文件的日期。
- machine_name2 ( str ) – 遗留；必须与 machine_name 匹配。
- log_type（str）–日志文件的格式。
返回：
- （摘要、输出）
返回类型：
- 元组
处理使用日志并在 Karaage 数据库中添加/替换数据。
3.1.2.2 PBS RPC 要求
定义了以下 RPC 过程，可以进行远程调用。XMLRPC 是用于 RPC 过程调用的机制。
get_disk_quota (用户名, machine_name = None ) 参数：
- username（str） – 获取配额的账户用户名。
- machine_name ( str ) – 获取配额的机器。
返回：
- 磁盘配额（以 KB 为单位）。
返回类型：
- 整数
获取该人的账户磁盘配额，以KB为单位。
get_project_members (机器,密码, pid ) 参数：
- machine_name ( str ) – 以此机器进行身份验证。
- 密码（str）–机器的密码。
- pid ( str ) – 获取成员的项目 PID。
返回：
- 给定项目 ID 中的用户名列表。
- 如果发生错误，则返回代表错误的 str。
返回类型：
- 列表
获取项目中的成员列表。
get_projects (机器,密码) 参数：
- machine_name ( str ) – 以此机器进行身份验证。
- 密码（str）–机器的密码。
返回：
- 机器的项目 PID 列表。
返回类型：
- 列表
获取机器可用的项目列表。
get_project (用户名, pid , machine_name = None ) 参数：
- username ( str ) – 提交作业的用户名。
- pid ( str ) – 请求的项目 PID。
- 机器名称（str）– 正在提交作业的机器名称。由于遗留原因，它是可选的，应始终在当前代码中提供。
返回：
- 找到项目 pid，如果失败则找到 str“None”。
返回类型：
- 字符串
尝试找出最适合这项工作的项目，如果失败则为 str“None”。
用于提交过滤器以确保用户在项目中。
get_users_projects (用户名，密码)
参数：
- 用户名（str）– 以此人的身份进行身份验证。
- password（str）– 个人密码。
返回：
- 一个元组 (0，列表 (pid，pid，…))
返回类型：
- 元组
获取此人所参与的项目列表。
project_under_quota(pid, machine_name=None):参数：
- pid ( str ) – 请求的项目 PID。
- 机器名称（str）– 正在检查的机器名称。由于遗留原因，它是可选的，应始终在当前代码中提供。
返回：
- True如果项目低于配额，否则False。
返回类型：
- 布尔值
该项目是否低于其使用配额？
showquota (用户名,机器名= None ) 参数：
- usernmame ( str ) – 正在检查的帐户的用户名。
- 机器名称（str）– 正在检查的机器名称。由于遗留原因，它是可选的，应始终在当前代码中提供。
返回：
- 元组列表 (project_id、actual_mpots、quota_mpots)
返回类型：
- 列表
检索此机器上人员的使用配额。
3.2 功能要求
本节包括指定软件系统所有基本操作的要求。
3.2.1 访问控制
本节包括指定访问控制措施的所有要求。
3.2.1.1 角色要求
用户可以将 Karaage 用作不同的角色。定义了以下角色：
- 未经身份验证的用户
- 人员
- 项目负责人
- 研究所代表
- 管理员
请注意，项目负责人、研究所代表和管理员也是人员。
不同的角色可以访问不同的功能集。
3.2.1.2 未经身份验证的用户
如果用户未登录就访问 Karaage，则他们属于未经身份验证的用户角色。这些用户可以：
- 申请账户
- 登录
3.2.1.3 人员
如果用户访问 Karaage 并登录，则他们属于人员角色。这些用户可以：
- 查看自己人的详细信息。
- 查看自己项目中人员的详细信息。
- 查看他们所属项目的详细信息。
- 查看机器和机器类别的详细信息。
- 查看软件的详细信息。
- 查看使用信息（可选）。
- 同意许可软件。
- 申请受限软件。
- 修改自己的个人信息。
- 更改密码。
- 重置密码。
- 登出
3.2.1.4 项目负责人
如果用户访问 Karaage 并以个人身份登录，则他们具有项目负责人角色，并且被标记为项目负责人。这些用户可以：
- 查看其所领导的项目人员的详细信息。
- 查看他们领导的项目的详细信息。
- 批准/拒绝以项目负责人身份加入其项目的申请。
- 跟踪他们的资源利用率和软件利用率。
- 编辑项目（受限的字段集）。
- 授予项目成员领导角色。
- 撤销项目成员领导角色。
3.2.1.5 设立代表
如果用户访问 Karaage 并以个人身份登录，则他们具有机构代表角色，并且被标记为机构代表。这些用户可以：
- 查看其委派的机构中人员的详细信息。
- 查看项目人员及其委派机构的详细信息。
- 查看其委派的机构的详细信息。
- 批准/拒绝在研究所创建新项目的申请。
- 对于他们委派的研究所所有项目：
- 查看项目人员的详细信息。
- 查看项目的详细信息。
- 跟踪他们的资源利用率和软件利用率。
- 编辑项目（受限的字段集）。
- 授予项目成员领导角色。
- 撤销项目成员领导角色。
3.2.1.6 管理员
如果用户访问 Karaage 并以管理员身份登录，则他们属于管理员角色，并且被标记为管理员。如果网站配置，可以拒绝这些用户的管理访问权限。这些用户可以：
- 查看/编辑人员的详细信息。
- 看/编辑项目的详细信息。
- 查看/编辑机构的详细信息。
- 查看/编辑机器和机器类别的详细信息。
- 查看/编辑软件的详细信息。
- 查看使用信息。
- 更改任何人的密码。
- 创建/删除/重新激活人员[ 1 ]。
- 创建/删除账户[ 2 ] .
- 创建/删除项目。
- 创建/删除机构。
- 批准/拒绝项目申请。
- 批准/拒绝软件申请。
- 锁定/解锁人员。
- 将人员的电子邮件设为退回邮件。
- 查看任何对象的日志/评论。
- 对任何对象添加评论。
- 查看数据存储中的低级（详细）信息。
3.2.1.7 对人员的额外要求
有权查看某人的详细信息意味着能够：
- 发送电子邮件允许人们重置密码
- 查看所有项目负责人的列表。
- 查看此人所属的所有项目的列表。
- 查看所有软件协议的列表。
- 查看个人所有帐户的列表。
- 查看某人的所有职位列表。
3.2.1.8 项目的额外要求
有权查看项目的详细信息意味着能够：
- 查看项目的项目上限/配额。
- 查看项目成员列表。
- 查看研究所的项目列表。
3.2.1.9 对机构的额外要求
有权查看某个机构的详细信息意味着能够：
- 查看机构的项目上限/配额。
- 查看研究所成员名单。
- 查看该学院的学院用户信息。
3.2.2 项目申请程序
本节规定了项目申请的要求
默认情况下，项目应用程序被禁用。
3.2.2.1 未经认证的请求
对于未经身份验证的用户，需要提供电子邮件地址。 系统会向该地址发送一封电子邮件，其中包含一个包含随机值的链接。用户可以点击此链接继续使用该应用程序。
3.2.2.2 按人请求
对于个人，无需额外信息，申请流程将立即开始。 将向个人注册的电子邮件地址发送电子邮件，提醒他们申请已开放。
3.2.2.3 未经认证的用户是现有人员
存在这样的风险：未经身份验证的用户在请求项目时实际上确实有一个人员。 如果用户输入了某人正在使用的电子邮件地址，则该应用程序将分配给此人。此人必须登录才能继续。 如果用户输入的电子邮件地址与系统中的任何内容都不同，他们可能会尝试注册现有人员的用户名，但该用户名将被拒绝，因为该用户名已被使用。 或者他们会选择另一个用户名，并得到两个完全不同的人。
为了减轻这种可能性，任何可以访问该应用程序的人都可以将该用户设为重复用户，以便系统管理员对其进行标记，然后系统管理员可以将该应用程序重新分配给该人并重新启动该过程。
3.2.2.4 登录者访问错误的应用程序
另一个极端情况是，如果有人访问了随机生成的链接，而该链接原本是为未经身份验证的用户和/或其他人准备的，那么会发生什么情况。 这通常意味着未经身份验证的用户已经有了一个人。因此，用户可以选择接管应用程序，或者注销以未经身份验证的用户身份访问它。
这对于 Shibboleth 步骤特别有用。Shibboleth 步骤涉及用户登录 Shibboleth。 通常，这不会让用户登录 Karaage，因为他们还没有人。 如果用户自动登录，则意味着该人已经有了人，并且他们可以选择接管该应用程序。
3.2.2.5 动作
对于加入项目（经项目负责人批准）或创建新项目（经机构代表批准）的请求：
注： 仅当未经身份验证的用户启动应用程序时才需要第一个电子邮件步骤。当经过身份验证的用户启动应用程序时，可以跳过此步骤。 注： 仅当需要新人员时才需要密码步骤。如果需要新帐户，则 可以请求该人员的密码并将其用于该帐户。如果不需要新人员或 帐户，则可以跳过此步骤。
3.2.3 软件应用程序
本节规定了软件应用程序的要求
软件申请仅适用于受限软件。当用户同意许可时，所有非受限软件都会自动获得批准。
只有人员才能访问软件应用程序。
对于加入受限制项目的请求：
3.2.3.1 动作
3.3 定制要求
本节包括设计要求，以确保可以根据当地要求定制唐扬。
必须能够在不同的站点安装 Karaage。只要符合本规范中 Karaage 的定义范围，就应该能够自定义每个站点以满足其本地要求。 应该能够使用定义良好的机制进行此自定义，这些机制不会破坏 Karaage 的次要版本，或者为 Karaage 的主要版本提供定义良好的升级路径。
3.4 性能要求
本节中的要求提供了用户与软件交互以及对系统性能的测量的详细规范。
3.5 设计约束
本节包括硬件对软件设计造成的约束。
由于 Karaage 是一个软件项目，因此这超出了范围，需要在特定站点安装 Karaage 的项目计划中设置。
任何满足操作系统依赖性且可以用作满足性能要求的 Web 服务器的可靠计算机 都适合与 Karaage 一起使用。
3.6 软件系统属性
本节中的需求指定了软件系统所要求的可靠性、可用性、安全性 4和可维护性。
由于 Karaage 是一个软件项目，因此这超出了范围，需要在特定站点安装 Karaage 的项目计划中设置。
注：
- 人员不会被删除，而是数据库条目会被标记为已删除。这是为了确保用户名永远不会被回收。
- 账户永远不会被删除，而是将数据库条目标记为已删除。这是为了确保用户名永远不会被回收。
4 优先级和发布计划
这里讨论与 Karaage 新版本和功能请求相关的主题。
4.1 增强功能
任何不需要更改这些规范的小更改或错误报告都应提交给github 问题跟踪器。 更好的是，更改可以提交给我们的gerrit。
更重大的变更可能需要创建 KEP（Karaage 变更提案）。有关详细信息，请参阅KEP 1：KEP 目的和指南。
任何 KEP 都应考虑是否需要更改这些规范以及本节中提到的发布要求。
创建 KEP 的过程涉及社区咨询。
4.2 Karaage发布要求
这讨论了制作新 Karaage 版本的要求。
4.2.1 增加版本
Karaage 版本号由三个整数组成：major.minor.patch：
major：表示 Karaage 的主要版本。主要版本可以符合 SRS 的新主要版本。
此类更改可能与以前的版本有不兼容的更改。在新的主要版本发布后，将继续支持以前的版本并修复错误。一次可能不支持多个主要版本的升级支持。 例如，版本 1 的用户可能必须先升级到版本 2，然后才能升级到版本 3。升级到主要版本
如果 Karaage 有一个主要版本而没有相应的 SRS 主要版本，这表明 SRS 尚未涵盖所需的领域，因为任何不兼容的变化都应该在规范中涵盖。
在主要版本发布之后，Karaage 将不再遵循先前发布的 SRS。
次要：次要版本的变更表示重大变更，但不是主要变更。次要版本可以符合 SRS 的新次要版本或补丁版本。
例如，升级可能涉及数据库迁移。旧版本将不再受支持，但升级应该不会出现任何问题。升级到新的次要版本可能需要少量停机时间来进行数据库迁移和/或更新配置。
如果 Karaage 有小版本发布而没有相应的策略小版本发布，这通常表明已经进行了内部更改，这些更改可能会影响部署，无需指定。
在小版本发布之后，Karaage 将继续遵循 SRS 的先前版本，因为 SRS 的小更新意味着兼容性应该得以保留。
patch：表示错误修复和/或其他小更改。补丁版本可以符合 SRS 的新补丁版本。
一些更改可能涉及修复安全问题。旧版本将不再受支持，不应再使用。除了升级软件包外，不需要进行任何更改。
修复安全问题可能会不可避免地破坏现有代码，这种情况很少见。如果需要，这种破坏将保持在最低限度。
在路径发布之后，Karaage 将继续遵守 SRS 的先前版本，因为 SRS 的补丁更新意味着兼容性应该得到保留（不包括安全问题）。
Karaage 的每个版本都将记录为符合 SRS 的 XYZ 版本。
4.2.2 发布新版本
Karaage 的新补丁发布频率最高。它们会根据需要发布，具体取决于更改的重要性以及是否修复了安全问题。
Karaage 的新次要版本是根据需求、更改的重要性以及是否修复了安全问题而发布的。目标是每月发布不超过一个。
Karaage 的新主要版本将根据需要发布，但前提是 V3 必须将其 Karaage 安装升级到至少上一个主要版本。目标是每年发布不超过一个主要版本。
我们将尽最大努力始终跟上 SRS 的最新版本，并满足此处指定的要求。
5 未来方向
只有管理员才能访问使用信息，除非 Karaage 配置为允许公众访问。这可能是 Karaage 2 的退步。请参阅人员的附加要求、 项目的附加要求和 机构的附加要求部分。
某些站点需要更多角色，以便某些用户能够获得更多数据访问权限。请参阅角色要求部分。
复制文件来创建 Karaage 的本地自定义是一种常见的做法。这会破坏升级。
RPC 需要修复。并非所有网站都需要它，而且不一致。可能需要更改的内容包括：
- 如果不需要，可以禁用它吗？
- 用现代 REST API 替换？
- 删除它？
- 所有方法都需要身份验证吗？
实施的 change_default_project RPC 规范已损坏。没有指示它应该在哪个帐户上运行。是否需要？
change_default_project (用户名,密码, pid ) 参数：
- 用户名（str）– 以此人的身份进行身份验证。
- password（str）– 个人密码。
- pid ( str ) – 默认使用的新的项目 PID。
返回：
- 成功时返回一个元组 (0, str),发生错误时返回一个元组（代码，字符串）
返回类型：
- 元组
更改由 account_username 标识的人员帐户的默认项目。
6 词汇表
- 帐户
- 一个人可以拥有一个或多个帐户。帐户允许一个人访问给定 machine_category 上的机器。一个人需要属于某个项目才能拥有帐户，尽管此规则可能有特定的例外。
- 管理员
- 可以无限制享用唐扬美食的人。
- 数据存储
- 我们应链接并自动更新的外部数据库列表。支持的数据库包括 LDAP、Gold 和 Slurm。
- 团体
- 人员列表。通常直接映射到 LDAP 组，但这取决于所使用的数据存储。
- 研究所
- 一个研究所只是一组项目。
- 设立代表
- 管理一个研究所并可以为该研究所批准新项目的人员。
- 本地安装
- 为了特定目的而在特定地点定制安装 Karaage。
- 当地要求
- 任何特定于本地安装的要求。
- 机器
- 作为独特单元进行管理的单个集群或计算机。
- 机器类别
- 一组共享相同身份验证系统的机器。
- 人员
- 有权访问 Karaage 系统的人。一个人可以拥有一个或多个帐户，可以成为管理员、项目经理或研究所代表。这些都是可选的。
- 项目
- 拥有共同目标的人的列表。
- 项目负责人
- 管理项目并可以允许新用户使用该项目的人员。
- 超级计算机
- 人们可以使用并提交作业的计算机系统。
- 未经认证的用户
- 正在使用 Karaage 的人，尚未向 Karaage 进行身份验证，甚至可能不是一个人。
- 用户
- 目前正在使用Karaage的人。