概念
本页解释其他页面使用的词语。每一节都很简短，并链接到完整介绍该主题的页面。单行定义请参见术语表。
安装实例及其服务
一个安装实例就是一台服务器。它在一个 PostgreSQL 数据库旁运行三个 Arkvory 服务：
| 部件 | 作用 |
|---|---|
| API | HTTP 服务器：HTTP API、Web 控制台，以及容器、Git LFS 和 npm 的注册表。它还负责执行保留规则和物理清理。 |
| 工作进程 | 后台任务：完成大文件上传并同步镜像。 |
| 备份代理 | 按计划把备份写入备份存储。 |
| PostgreSQL | 目录：制品、包、修订版本、账户、密钥和任务。 |
文件内容保存在服务器的本地目录中，而不是数据库中。所有部件都位于安装根目录（Windows 上是 C:\ProgramData\ProAnima\Arkvory，Linux 上是 /opt/proanima-arkvory）。服务无需用户登录即可启动，并会在崩溃或卡死后重启（自愈）。
安装实例不是高可用集群。如果服务器停止，客户端会等待，然后继续它们的传输。参见选择安装方式。在 Linux 上，两到三台服务器可以组成高可用集群。
仓库
仓库是内容的命名空间。它有自己的访问规则、自己的存储策略（配额和保留），以及可选的镜像源。仓库名称有 1 到 64 个字符：小写拉丁字母、数字、- 和 _，以字母或数字开头。
您无需使用单独的命令创建仓库。只要某个组被授予对其名称的访问权限，或某个服务账户策略命名了它，仓库就存在。新安装实例为第一个仓库 releases 预留了位置。参见仓库。
制品
制品是一个已存储的文件。它是不可变的：其字节永远不会改变。它有一个 UUID、一个名称（最多 240 个字符，不含 / 或 \）、一个大小和一个 SHA-256 校验和。新内容会创建新制品；它绝不会替换旧制品。
只有在服务器确认字节与声明的大小和 SHA-256 一致后，制品才可见。下载会返回相同的字节，并把校验和作为强 ETag。Arkvory 上的其他所有内容都建立在制品之上：一个包版本、一个路径修订版本、一个容器层和一个 Git LFS 对象都是制品。
上传
上传会预留一个未来的制品。您使用文件的名称、大小和 SHA-256，以及一个使请求可安全重复的 Idempotency-Key 创建上传会话。然后发送字节：
- 对中小型文件，在一个请求中发送；或
- 对大文件，按分片发送。服务器会选择分片大小：至少 8 MiB，对超大文件会翻倍，以便上传永远不需要超过 10,000 个分片。分片绝不会超过 1 GiB。每个分片带有自己的 SHA-256，重复的分片不会造成危害。
然后您完成上传。服务器会校验整个文件并发布它。对于大文件，工作进程会在客户端跟踪的完成任务中完成上传；SDK 和命令行客户端会对 16 GiB 及以上的文件选择这种方式。上传会话存活 7 天。被中断的上传会从服务器已有的分片继续。除非管理员设置更低的 ARKVORY_MAX_OBJECT_BYTES，否则最大对象为 10,000 GiB。
命令行客户端和 SDK会为您完成所有这些操作。参见传输和上传参考。
包
包是 Arkvory 已注册的 UPack 归档。它的标识是包组、名称和 SemVer 版本，例如 acme / game-server / 1.4.2。包组是标识的一部分：不同包组中同名的两个包是不同的包。已发布的版本永不改变；用其他内容发布同一版本会被拒绝。
部署代理可以通过精确版本、通过诸如 ^1.4 的版本范围，或通过某个阶段的最新版本来请求包。预发布版本只在您请求时出现。参见包。
路径文件
路径文件具有诸如 builds/game/1.4/Setup.exe 的地址，并指向一个制品。当您在该路径存储新字节时，路径会获得一个新的修订版本（1、2、3，依此类推）。较早的修订版本保留在历史记录中，您可以恢复其中一个：恢复会添加一个带有旧内容的新修订版本。再次存储相同的字节不会添加任何内容。
路径最多有 1,024 个字符，使用 / 作为分隔符，且没有空段、. 或 .. 段，也没有 :。更改会指明它期望的修订版本；如果另一个更改先到，服务器会返回 409。对于尚不存在的路径，请使用 0。参见文件与路径和原始文件。
标签、元数据、集合与附件
您可以在不触动制品字节的情况下描述它：
| 项目 | 规则 |
|---|---|
| 标签 | 最多 32 个短标签，例如 nightly 或 tested。 |
| 元数据 | 最多 32 个文本字段；键最多 64 个字符，值最多 1,024 个。 |
| 集合 | 对制品进行分组的有名集合。 |
| 附件 | 最多 32 个从构建指向同一仓库其他制品的链接：清单、SBOM、签名、报告或任何其他文件。 |
标签、元数据和集合作为一个带修订版本的集合一起更改。附件有自己的修订版本和历史记录。
阶段与晋级
阶段是构建上的受控标记，例如 qa、release 或 prod。阶段名称使用小写字母、数字、.、_ 和 -（最多 32 个字符），一个制品最多可以带有 16 个阶段。更改阶段需要其专属权限 artifact.promote，每次更改都会记录操作者、时间和注释。
晋级会把构建发布到另一个仓库，而无需再次发送字节。copy 保留源；move 还会从源仓库移除该构建。重复晋级会返回已存在的副本。解析会查找某个阶段和版本范围指向的构建。参见晋级。
账户、组与权限
人们使用账户。账户有名称（3 到 64 个字符）和密码（12 到 128 个字符）。管理员账户管理账户和组。账户属于组，组会被授予对仓库的 read 或 write（"读取和写入"）访问权限。权限会在每个请求时重新计算，因此更改会立即生效。
自动化则使用服务账户。它的策略按仓库列出精确的动作，例如 upload.create 或 content.read，而它的密钥只能收窄该策略。服务器会检查每一个动作；在控制台中隐藏按钮并不是保护措施。参见账户与访问和认证。
密钥与令牌
每个请求都携带凭据。您创建的凭据有四类，还有一类是内置的：
| 凭据 | 用途 | 有效期 |
|---|---|---|
| 控制台会话 | 使用名称和密码登录的人员 | 12 小时 |
| 个人访问令牌 | 某个人的脚本和工具 | 默认 90 天，最多 365 天 |
| 服务密钥 | CI/CD 和部署代理 | 默认 90 天，最多 365 天 |
| 下载链接 | 在没有密钥的情况下把某个制品交给他人 | 60 秒到 24 小时（默认 1 小时） |
| 恢复密钥 | 安装实例本身 | 永不过期 |
服务密钥只签发一次、只显示一次，并且只有在激活后才可用。您可以轮换它（签发新的，然后停用旧的）并永久撤销它。参见认证。
所有者与恢复密钥
所有者是第一个账户。它是管理员，也是 arkvory-owners 组的成员，该组对 releases 具有 write 访问权限。Windows 安装程序会创建它；在 Linux 和 Docker 上，您需要使用恢复密钥在控制台中创建它。
恢复密钥是安装程序写入安装根目录中 config/bootstrap-token.txt 的机密。它可以创建第一个所有者和账户、管理服务账户及其委派、运行备份并请求更新。安装工具会在服务器上读取它。它不用于 CI 或日常工作：请把它保存在服务器上，不要复制。参见选择安装方式和安全。
保留、配额与物理清理
存储策略属于仓库。它可以为每个包（或每个包和渠道）保留最近 N 个构建、保护标签和阶段不被移除、在移除任何内容前等待最短时间，并设置带有警告和严重阈值的配额。在管理员开启之前，它处于关闭状态。移除制品首先是在逻辑上进行的：字节会在磁盘上保留一个宽限期（默认 24 小时），然后物理清理会在后台以小批量方式释放空间，而不会停止服务器。
服务器还会保留一块空闲磁盘空间储备（默认 1 GiB），上传永远不会使用它。参见存储。
备份
备份代理会把数据库和所有已发布内容复制到备份存储中，即另一块磁盘或网络共享上的文件夹。一份完整副本就是一个恢复点。代理会校验每个恢复点、对恢复点应用保留规则（默认 7 个每日、4 个每周和 6 个每月），并允许您固定某个恢复点，使保留规则保留它。在管理员于 计划与保留 中开启之前，每日计划处于关闭状态。
恢复是服务器上的一个命令。它会写入空的数据库和空的存储目录。参见备份。
镜像与读取网关
镜像是仓库的只读副本，由第二个安装实例通过跟随第一个安装实例（即源）来维护。它拒绝更改并提供下载。如果源丢失，操作员会分离镜像，它就成为普通仓库；切换是手动的，不是自动故障切换。参见镜像。
读取网关是同一存储上的额外 API 进程，只响应 GET 和 HEAD。写入进程和网关共享同一份下载带宽预算。参见读取网关。
下一步
- 快速入门：安装 Arkvory 并上传第一个文件。
- 账户与访问：人员、组、令牌和服务密钥。
- HTTP API 概览：每个集成都需要的规则。
- 术语表：每个术语的简短定义。