forked from MxOS/mirrors
feat(mirrors): initial architecture, specifications, automation tools, and canonical guide
Establish community mirror network on IPFS for Fedora and CentOS Stream 10: - Modular documentation and specifications under docs/ - Master canonical guide under README.rst with client and node operator workflows - Ingestion, upstream sync, and Cloudflare DNSLink automation scripts in bin/ - Reverse proxy configs (Nginx/Caddy) and systemd timer units in etc/ and systemd/ Signed-off-by: Rénich Bon Ćirić <renich@evalinux.com> Co-authored-by: Gemini AI <renich+gemini@evalinux.com>
This commit is contained in:
commit
0397fc8cc4
GPG key ID:
AB2A9F49384FE324
32 changed files with 1700 additions and 0 deletions
58
docs/technical/specs/arquitectura-distribucion.rst
Normal file
58
docs/technical/specs/arquitectura-distribucion.rst
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
=======================================
|
||||
Arquitectura de Distribución sobre IPFS
|
||||
=======================================
|
||||
|
||||
Identificadores Técnicos: [TECH-001], [TECH-002]
|
||||
|
||||
Diagrama de Flujo del Sistema
|
||||
=============================
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
+------------------------+ +---------------------------+
|
||||
| Upstream RHEL / Fedora | ---> | Nodo Servidor MxOS |
|
||||
+------------------------+ +---------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| Generación de UnixFS DAG |
|
||||
| (ipfs add / filestore) |
|
||||
+---------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------+
|
||||
| Actualización DNSLink |
|
||||
| _dnslink.mirrors.mx-os.mx |
|
||||
+---------------------------+
|
||||
|
|
||||
+-------------------------+-------------------------+
|
||||
| |
|
||||
v v
|
||||
+-----------------------------+ +-----------------------------+
|
||||
| Colaborador Nivel 1 (ISOs) | <== Bitswap P2P ==> | Colaborador Nivel 2 (BaseOS)|
|
||||
| ipfs pin add /.../fedora/iso| | ipfs pin add /.../BaseOS |
|
||||
+-----------------------------+ +-----------------------------+
|
||||
| |
|
||||
v v
|
||||
+-----------------------------+ +-----------------------------+
|
||||
| Gateway local (puerto 8080) | | Gateway local (puerto 8080) |
|
||||
+-----------------------------+ +-----------------------------+
|
||||
| |
|
||||
v v
|
||||
+-----------------------------+ +-----------------------------+
|
||||
| Cliente DNF (localhost) | | Cliente DNF (localhost) |
|
||||
+-----------------------------+ +-----------------------------+
|
||||
|
||||
Componentes Principales
|
||||
=======================
|
||||
|
||||
Demonio Kubo
|
||||
------------
|
||||
* **Implementación:** Kubo (Go-IPFS) versión empaquetada para Fedora/CentOS en Copr (``renich/kubo``).
|
||||
* **Almacén de bloques:** Base de datos badgerds o flatfs para alto rendimiento en lecturas aleatorias.
|
||||
* **Protocolos de transporte:** TCP y QUIC habilitados en el puerto 4001 para transversalidad óptima de NAT y firewalls residenciales.
|
||||
* **Gateway local:** Escucha en ``127.0.0.1:8080`` permitiendo acceso HTTP sin exponer la interfaz de control RPC (puerto 5001).
|
||||
|
||||
Direccionamiento UnixFS DAG
|
||||
---------------------------
|
||||
Cada repositorio se procesa como un grafo acíclico dirigido (DAG) de UnixFS v1/v2. Los archivos grandes (imágenes ISO) se fragmentan en bloques de 1 MB con funciones hash SHA-256 o BLAKE3, garantizando que si dos versiones comparten paquetes o bloques de datos idénticos, estos se dedupliquen automáticamente en el almacén global.
|
||||
31
docs/technical/specs/ingesta-repositorios.rst
Normal file
31
docs/technical/specs/ingesta-repositorios.rst
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
====================================
|
||||
Ingesta de Repositorios y Telemetría
|
||||
====================================
|
||||
|
||||
Identificadores Técnicos: [TECH-001], [TECH-004]
|
||||
|
||||
Flujo de Ingesta Upstream
|
||||
=========================
|
||||
El ciclo de actualización del nodo central de MxOS se ejecuta de manera automatizada mediante temporizadores de systemd y comprende cuatro etapas:
|
||||
|
||||
1. **Sincronización diferencial con rsync:** Se obtienen los paquetes y metadatos actualizados desde los espejos de nivel 1 (Tier-1) de Fedora y CentOS Stream hacia un directorio de preparación (staging) local.
|
||||
2. **Generación del grafo UnixFS (Filestore):** Para evitar la duplicación de cientos de gigabytes en el disco del servidor, se utiliza la función ``--nocopy`` de Kubo con el subsistema filestore habilitado:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ipfs add -r --nocopy --cid-version=1 --hash=sha2-256 /srv/mirrors/staging/
|
||||
3. **Actualización de Registros DNSLink:** El CID raíz resultante de la ingesta se publica automáticamente en el servidor de nombres de MxOS mediante actualización dinámica de DNS (RFC 2136 / nsupdate) o vía la API de gestión de zona.
|
||||
4. **Anuncio en el enjambre:** El nodo central anuncia la provisión de los nuevos CIDs a la DHT de IPFS.
|
||||
|
||||
Descubrimiento de Nodos y Telemetría Pasiva
|
||||
===========================================
|
||||
Para alimentar el tablero público en ``mirrors.mx-os.mx`` sin violar la privacidad de los colaboradores, el servicio recolector opera de la siguiente forma:
|
||||
|
||||
1. **Consulta a la DHT:** Se invoca periódicamente la interfaz RPC de Kubo o la instrucción de línea de comandos para consultar proveedores del CID raíz activo:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ipfs dht findprovs -n 0 <CID_RAÍZ>
|
||||
2. **Extracción de multiaddrs:** El comando retorna los identificadores de par (PeerID) y las direcciones de red asociadas (IPv4/IPv6 y puertos de escucha).
|
||||
3. **Geolocalización aproximada en memoria:** Las direcciones IP públicas se contrastan contra una base de datos local MaxMind GeoLite2 para extraer únicamente el país y estado o región.
|
||||
4. **Almacenamiento temporal:** Los datos agregados (número de pares, concentración geográfica y latencia de respuesta) se consolidan en una base de datos SQLite/libSQL o en memoria para ser consumidos por la interfaz web reactiva.
|
||||
68
docs/technical/specs/puente-mirrormanager.rst
Normal file
68
docs/technical/specs/puente-mirrormanager.rst
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
==================================
|
||||
Puente HTTP y Fedora MirrorManager
|
||||
==================================
|
||||
|
||||
Identificador Técnico: [TECH-005]
|
||||
|
||||
Integración con MirrorManager
|
||||
=============================
|
||||
Fedora gestiona su infraestructura de distribución global mediante MirrorManager (`mirrormanager2`). Para registrar formalmente a MxOS como el primer espejo oficial en México, se requiere:
|
||||
|
||||
1. Exposición de puntos finales HTTP y HTTPS estables y de alta velocidad.
|
||||
2. Soporte para el protocolo de verificación de sincronización (archivo ``report_mirror``).
|
||||
3. Respuesta rápida en peticiones GET y HEAD para metadatos de repositorio.
|
||||
|
||||
Topología del Puente Inverso
|
||||
============================
|
||||
En el servidor cabecera de MxOS (ejemplo: ``mirrors.mx-os.mx``), un servidor web de alto rendimiento (Caddy o Nginx) actúa como terminador TLS y proxy inverso directo hacia el gateway HTTP de Kubo:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Petición DNF Upstream (Internet)
|
||||
|
|
||||
v
|
||||
+---------------------------------------+
|
||||
| Caddy / Nginx (mirrors.mx-os.mx:443) |
|
||||
| Certificados Let's Encrypt / TLS 1.3 |
|
||||
+---------------------------------------+
|
||||
|
|
||||
| proxy_pass http://127.0.0.1:8080/ipns/mirrors.mx-os.mx/
|
||||
v
|
||||
+---------------------------------------+
|
||||
| Gateway HTTP de Kubo (IPFS Local) |
|
||||
+---------------------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------------------+
|
||||
| Enjambre P2P de Nodos Guardianes |
|
||||
+---------------------------------------+
|
||||
|
||||
Configuración de Ejemplo para Caddy
|
||||
===================================
|
||||
El servidor web delega la entrega de archivos estáticos al gateway local de IPFS:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
mirrors.mx-os.mx {
|
||||
encode zstd gzip
|
||||
|
||||
# Proxy transparente hacia el gateway de IPFS
|
||||
reverse_proxy http://127.0.0.1:8080 {
|
||||
rewrite /ipns/mirrors.mx-os.mx{path}
|
||||
header_up Host {upstream_hostport}
|
||||
}
|
||||
|
||||
log {
|
||||
output stdout
|
||||
format filter {
|
||||
wrap json
|
||||
fields {
|
||||
common_log delete
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Beneficio Operativo
|
||||
===================
|
||||
Este desacoplamiento permite que los clientes externos utilicen el espejo como si fuera un servidor web convencional, mientras que por debajo, el servidor cabecera obtiene los bloques faltantes desde la red comunitaria de nodos guardianes, reduciendo drásticamente la carga de salida del nodo central.
|
||||
32
docs/technical/specs/resolucion-dnslink.rst
Normal file
32
docs/technical/specs/resolucion-dnslink.rst
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
================================
|
||||
Resolución Inmutable con DNSLink
|
||||
================================
|
||||
|
||||
Identificador Técnico: [TECH-003]
|
||||
|
||||
Fundamento
|
||||
==========
|
||||
El direccionamiento directo por CID (ejemplo: ``/ipfs/bafy...``) es inmutable; cualquier cambio en un paquete genera un nuevo CID raíz. Por su parte, el Sistema de Nombres Interplanetario tradicional (IPNS) basado en DHT experimenta una latencia de resolución prohibitiva para las consultas rápidas de metadatos de DNF.
|
||||
|
||||
Para solventar esta limitación, el proyecto utiliza **DNSLink**. DNSLink asocia un registro TXT en el sistema de nombres de dominio convencional con el CID raíz activo de IPFS.
|
||||
|
||||
Topología de Registros DNS
|
||||
==========================
|
||||
En los servidores de nombres autoritativos para el dominio ``mx-os.mx``, se definen los siguientes registros:
|
||||
|
||||
.. code-block:: zone
|
||||
|
||||
; Registro raíz del portal de espejos
|
||||
_dnslink.mirrors.mx-os.mx. 300 IN TXT "dnslink=/ipfs/bafyrei..."
|
||||
|
||||
; Subdominios dedicados opcionales para granularidad independiente
|
||||
_dnslink.fedora.mirrors.mx-os.mx. 300 IN TXT "dnslink=/ipfs/bafyfed..."
|
||||
_dnslink.centos.mirrors.mx-os.mx. 300 IN TXT "dnslink=/ipfs/bafycen..."
|
||||
|
||||
Mecánica de Resolución en Kubo
|
||||
==============================
|
||||
1. Un cliente solicita un recurso bajo la ruta ``/ipns/mirrors.mx-os.mx/fedora/iso``.
|
||||
2. Kubo extrae el nombre de dominio y consulta el registro TXT de ``_dnslink.mirrors.mx-os.mx`` utilizando DNS sobre HTTPS (DoH) o los resolutores del sistema local.
|
||||
3. El registro TXT devuelve el prefijo ``dnslink=/ipfs/<CID_RAÍZ>``.
|
||||
4. Kubo reemplaza internamente la ruta por ``/ipfs/<CID_RAÍZ>/fedora/iso`` y procede a recuperar los bloques vía Bitswap o desde la caché local.
|
||||
5. El tiempo de vida (TTL) del registro se fija en 300 segundos (5 minutos) para permitir propagación rápida tras cada ciclo de sincronización.
|
||||
Loading…
Reference in a new issue