添加 draft-yukinet-cn86-registry-00.md

2025-12-30 20:46:14 +08:00
commit 83b577bce7
1 changed files with 204 additions and 0 deletions
--- a/draft-yukinet-cn86-registry-00.md
+++ b/draft-yukinet-cn86-registry-00.md
@@ -0,0 +1,204 @@
+# CN86 号码资源注册数据库规范
+_草案，版本 00_
+
+[TOC]
+
+## 关于本文
+本文是一份 CN86 规范草案。
+
+本文尚未经过 CN86 社区的审议，不应作为规范使用。
+
+关于此份草案的意见和建议，欢迎在 CN86 QQ 群提出。
+
+## 维护者注册数据库
+维护者应当通过 CN86 Gitea 平台创建维护者注册数据库，以取得 CN86 号码资源分配，并通过该数据库进行后续管理和维护。
+
+维护者注册数据库的名称必须为 `.cn86registry`，并可通过其 Gitea 平台账号的命名空间（即 `git.cn86.dev/<username>/.cn86registry`）访问。
+
+该仓库可见性应当设置为公有。
+
+### `resources.yaml`
+维护者注册数据库（`.cn86registry`）必须包含文件 `resources.yaml` 文件。
+
+`resources.yaml` 文件应当符合 YAML 语法。下面给出 `resources.yaml` 文件的示例：
+
+**`resources.yaml` 文件示例**
+```yaml
+email: example@example.com
+description: Example Network Center
+auth:
+  - ssh-ed25519 AAA...
+ipv4:
+  - address: 10.86.0.0/24
+    geolocation: CHN-JS
+    description: Example IPv4 Network
+domains:
+  - name: example.cn86
+    nameservers:
+      - server: ns1.example.cn86
+        addresses: ["10.86.0.1"]
+      - server: ns2.example.cn86
+        addresses: ["10.86.0.2"]
+  - name: example-network.cn86
+    nameservers:
+      - server: ns1.example.cn86
+      - server: ns2.example.cn86
+```
+
+#### `resources.yaml` 文件的字段
+`resources.yaml` 文件中的 YAML 字段，参照下方 TypeScript 定义：
+
+```typescript
+type ALPHA = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+type DIGIT = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type ALPHADIGIT = ALPHA | DIGIT;
+
+type SSHPublicKey = `ssh-ed25519 ${string}` | `ssh-rsa ${string}` | `ssh-ecdsa ${string}`;
+type IPv4Address = `${number}.${number}.${number}.${number}`;
+type IPv4CIDR = `${IPv4Address}/${number}`;
+type ISOAlpha3CountryCode = `${ALPHA}${ALPHA}${ALPHA}`;
+type ISOSubdivisionCode = `${ALPHADIGIT}${ALPHADIGIT}`;
+
+interface CN86Maintainer {
+  // 资源持有者的描述信息，可以包含任何和 CN86 有关的信息，形式为任意文本
+  // 如果未填写，默认应使用资源持有者的 Gitea 用户名填充
+  // 注意：取决于信息消费者的具体实现，多行字符串可能会被合并成一行
+  description?: string;
+
+  // 资源持有者的电子邮箱地址，应为有效可达的电子邮箱，用于联系和身份验证
+  email: string;
+
+  // 资源持有者的 SSH 公钥列表，用于身份验证
+  auth: SSHPublicKey[];
+}
+
+interface CN86Resource extends CN86Maintainer {
+  // 资源持有者在此注册和维护的 IPv4 网络资源
+  ipv4: CN86IPv4Resource[];
+
+  // 资源持有者在此注册 CN86 域名及相关权威 DNS 服务器信息
+  domains: CN86DomainResource[];
+}
+
+interface CN86IPv4Resource {
+  // IPv4 网络地址，采用 CIDR 表示法
+  address: IPv4CIDR;
+
+  // 地理位置，采用 ISO 3166-1 alpha-3 国家代码或 ISO 3166-2 子划分代码表示
+  // 例如，中国应该表示为 CHN，中国江苏省应该表示为 CHN-JS，不使用 2 字代码是避免 YAML 解析器误将其识别为布尔值
+  geolocation: ISOAlpha3CountryCode | `${ISOAlpha3CountryCode}-${ISOSubdivisionCode}`;
+
+  // 对该 IPv4 网络的描述信息，可以包含任何和该网络有关的信息，形式为任意文本
+  // 注意：取决于信息消费者的具体实现，多行字符串可能会被合并成一行
+  description?: string;
+}
+
+interface CN86DomainResource {
+  // 域名，必须是以 .cn86 结尾的 FQDN （不含结尾根域名）
+  name: `${string}.cn86`;
+
+  // 该域名的权威 DNS 服务器列表
+  nameservers: CN86DomainNameserver[];
+}
+
+interface CN86DomainNameserver {
+  // 权威 DNS 服务器的主机名，为合法的 FQDN（不含结尾根域名）
+  server: string;
+
+  // 权威 DNS 服务器的 IP 地址列表，用于 Glue Record
+  addresses?: IPv4Address[];
+}
+```
+
+## 中心注册数据库
+中心注册数据库的应当在 `cn86` 命名空间下，并命名为 `registry`。
+
+中心注册数据库的应当可通过 `git.cn86.dev/<username>/.cn86registry` 访问。
+
+中心注册数据库的应当使用下面的文件系统结构：
+```
+cn86/index.json
+cn86/registry/ipv4/<ipv4>.json
+cn86/registry/domains/<domain>.json
+cn86/registry/maintainers/<username>.json
+```
+
+### 中心注册数据库的对象定义
+中心注册数据库的文件应当符合规范的 JSON 语法。其中对象的定义，参照以下 TypeScript 定义：
+
+#### `cn86/index.json` 文件
+```typescript
+interface CN86RegistryIndex {
+  ipv4: IPv4CIDR[];
+  domains: `${string}.cn86`[];
+  maintainers: string[];
+  source: `CN86`;
+}
+```
+
+#### `cn86/registry/ipv4/<ipv4>.json` 文件
+```typescript
+interface CN86RegistryIPv4Record {
+  address: IPv4CIDR;
+  geolocation: ISOAlpha3CountryCode | `${ISOAlpha3CountryCode}-${ISOSubdivisionCode}`;
+  description?: string;
+  maintainer: CN86Maintainer;
+  source: `CN86`;
+}
+```
+
+#### `cn86/registry/domains/<domain>.json` 文件
+```typescript
+interface CN86RegistryDomainRecord {
+  name: `${string}.cn86`;
+  nameservers: CN86DomainNameserver[];
+  maintainer: CN86Maintainer;
+  source: `CN86`;
+}
+```
+
+#### `cn86/registry/maintainers/<username>.json` 文件
+```typescript
+interface CN86RegistryMaintainersRecord extends CN86Maintainer {
+  source: `CN86`;
+}
+```
+
+
+## 聚合代理
+### 聚合代理的行为
+聚合代理应当在维护者注册数据库创建、更新和删除时，执行下文所述的聚合流程。
+
+聚合代理也应当定期执行下文所述的聚合流程。
+
+### 聚合代理的聚合流程
+ 1. 聚合代理通过 Gitea 平台提供的 API 列举所有维护者注册数据库 (`.cn86registry` 仓库)，并按本文所述规范，读取并解析仓库中的注册数据库文件。
+ 2. 聚合代理对相关文件进行 YAML 解析和字段格式验证。
+     - 如果遇到错误，聚合代理应使用 Email、Gitea Issue 或其他方式通知用户。
+     - 聚合代理应进行状态管理，对于关于同一注册数据库文件，只向同一用户通知一次。
+     - 聚合代理应该能包容单个维护者或单个文件的错误，并继续处理其他维护者或同一维护者的其他文件。
+ 3. 聚合代理检查新增号码资源是否和已有号码资源冲突。
+     - 如果遭遇错误，聚合代理应通过 Gitea Issue、电子邮件等方式，向试图新增该号码资源的用户发送通知。
+     - 对于号码资源主键的修改，聚合代理应该视为删除已存在资源，和新增号码资源两个操作。
+     - 聚合代理不应向已有号码资源的维护者发送通知。
+     - 聚合代理应进行状态管理，对于关于同一冲突资源，向同一用户只通知一次。
+     - 聚合代理应该能号码资源冲突，处理冲突后应能继续聚合流程。
+ 4. 聚合代理对号码资源的修改和删除进行身份验证。
+     - 对于已存在的号码资源，聚合代理应当拒绝非其维护者发起的修改或删除操作。
+     - 聚合代理应当基于 Gitea 平台的唯一 ID，而非用户名进行身份认证的判断。
+     - 对于失败的身份验证，聚合代理应分别向已存在资源的维护者，和试图修改或删除资源的维护者，通过 Email、Gitea Issue 或其他方式通知用户。
+ 5. 聚合代理按照本文所述的文件系统和数据结构，应用中心注册数据库的更新。
+
+## 术语表
+本文中使用的「必须 (MUST)」、「不得 (MUST NOT)」、「必需 (REQUIRED)」、「应当 (SHALL)」、「不应当 (SHALL NOT)」、「应 (SHOULD)」、「不应 (SHOULD NOT)」、「建议 (RECOMMENDED)」、「不建议 (NOT RECOMMENDED)」、「可 (MAY)」、「可选 (OPTIONAL)」词汇，应按照 [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) 中给出的定义解释。
+
+本文定义了以下术语：
+ - **号码资源**：用于网际互联和路由的标识符。在 CN86 中，特指由 CN86 分配和管理，用于 CN86 参与者网络间互联和路由的 IPv4 地址和 `.cn86` 域。
+ - **Gitea 平台**：在 git.cn86.dev 上提供服务，以供 CN86 参与者管理和维护网络资源和其他元信息的 Gitea 应用。
+ - **维护者**：在 CN86 Gitea 平台注册，以本文所述方式，对 CN86 网络号码资源进行管理和维护的 CN86 参与者。
+ - **聚合代理**：通过访问维护者注册数据库，实现特定的完整性和一致性检查、权限控制、信息存取机制，以实现对 CN86 号码资源管理维护，并产生维护者注册数据库的数据处理程序。
+ - **注册数据库**：通过 CN86 Gitea 平台上的数据存取，实现对 CN86 号码资源进行管理和维护的 Git 仓库。
+ - **中心注册数据库**：由 CN86 所有，包含所有由 CN86 已分配的号码资源信息，并通过聚合代理以自动化方式管理的注册数据库。
+ - **维护者注册数据库**：由维护者所有，仅包含维护者取得分配的号码资源信息，并由维护者自行管理的注册数据库。
+
+本文中所定义的术语，在不引起歧义的情况下，均可省略「CN86」前缀。