Proyectos (Servicio ▸ Proyectos)

Resumen — qué hace

Proyectos es un registro que reúne los metadatos de todos los proyectos que ejecuta su equipo en un único lugar compartido. De cada proyecto se registra su repositorio de código (GitHub, etc.), su canalización de CI/CD (Jenkins), los servicios web y las bases de datos que utiliza, sus destinos de copia de seguridad y —lo más importante— dónde residen sus secretos. Así, cualquier persona del equipo puede responder de un vistazo: «¿de qué está hecho este proyecto, dónde se despliega y qué secreto está en qué sitio?».

Esta pantalla no es una herramienta de despliegue. Las compilaciones y los despliegues reales ocurren en Jenkins. InfraGuard no dispara ninguna canalización desde aquí; los datos registrados son documentación compartida. Las URL, los nombres de Job y las ramas que guarde son únicamente enlaces y etiquetas de referencia: no se ejecuta nada.

Principios de diseño fundamentales:

• Los valores de los secretos nunca se guardan de forma literal. Los valores reales de contraseñas, tokens y claves no se conservan aquí. En su lugar, usted (1) referencia una clave guardada en la bóveda del inventario (infr_vault_key) o (2) anota únicamente «qué secreto está dónde» en una lista de verificación enmascarada.
• Todo se edita en una única ventana modal con pestañas (Resumen · Código · CI/CD · Enlaces · Copia de seguridad · Secretos).
• Las altas, modificaciones y bajas, así como las revelaciones de valores de la bóveda, se escriben en el registro de auditoría (infr_audit_log).

Cuándo usarla

• Al incorporar a un compañero que necesita averiguar rápidamente «¿cuál es el repositorio, la URL de despliegue y la base de datos de este proyecto?».
• Para dejar por escrito las dependencias web/db de cada proyecto y poder medir al instante el alcance del impacto durante un incidente.
• Para documentar un mapa de los secretos de los que depende un proyecto (qué clave está dónde, qué entrada de la bóveda pertenece a este proyecto).
• Para registrar los destinos y la cadencia de copia de seguridad como metadatos del proyecto, ligados a su política de copias.

Disposición

Franja de KPI

Tarjetas de proyecto

Cada tarjeta muestra:

• Icono y nombre — los proyectos accesibles desde fuera usan mdi-web; los solo internos usan mdi-folder-lock-outline.
• Enlace de URL — si es accessible y existe una URL, un enlace que abre en una pestaña nueva; en caso contrario, una insignia internal.
• Insignia de estado — active / paused / archived.
• Resumen de una línea.
• Fichas de composición — solo aparecen los elementos registrados: Código · Jenkins · Entornos N · Web N · BD N · Copias N · Secretos N.
• Etiqueta de grupo (categoría) y botones de editar/eliminar (cuando tiene permiso de escritura).

Ventana de edición (6 pestañas)

Una ventana modal ancha (.infr-modal__panel--wide) que reparte la entrada de datos por pestañas.

Cómo usarla

Registrar un proyecto

1. Pulse [Añadir proyecto] en la esquina superior derecha (se requiere permiso de escritura).
2. En la pestaña Resumen introduzca el nombre (obligatorio). La clave (slug) es opcional y debe coincidir con ^[a-z0-9_-]+$ (por ejemplo, coin-market).
3. Si el servicio es accesible desde fuera, active el conmutador Accesible desde fuera e introduzca su URL. Si es solo interno, déjelo desactivado y el campo de URL quedará deshabilitado.
4. Rellene las pestañas restantes (Código, CI/CD, Enlaces, Copia de seguridad, Secretos) según convenga: todas son opcionales.
5. [Guardar] — el servidor valida, hace un upsert en infr_project y actualiza la tarjeta.

Registrar entornos de CI/CD

En la pestaña CI/CD introduzca la URL de Jenkins y luego use [Añadir entorno] para agregar destinos de despliegue fila a fila:

{
  "env": "prod",
  "url": "https://coin.example.com",
  "branch": "main",
  "jenkins_job": "coin_market-deploy-prod",
  "note": "blue/green"
}

• env solo admite la lista blanca dev / staging / prod (cualquier otro valor lo fuerza el servidor a dev).
• Cada campo de texto se recorta por longitud (URL 255 · rama 120 · Job 191 · nota 255).
• Hasta 20 entornos.

Enlazar web/db

En la pestaña Enlaces, marque los recursos que utiliza este proyecto.

• Servicios web — elija de la lista de infr_web_service (nombre · dominio) registrados en Servicio ▸ Web. Se guarda como una matriz de id de web_service.
• BD (recolector) — la matriz de claves de los recolectores registrados con access=database (Administración ▸ Recolectores / Servicio ▸ Base de datos).

Cada enlace admite hasta 50 entradas.

Declarar destinos de copia de seguridad

Use el repetidor de la pestaña Copia de seguridad para documentar la política de copias de este proyecto (tipo · destino · programación · nota). Se trata de metadatos de referencia y no se ejecuta: los trabajos de copia reales se gestionan en el Panel de programación.

Gestionar la información confidencial (la función clave)

Los secretos emplean dos mecanismos a la vez. Ninguno de ellos guarda el valor real del secreto en infr_project.

1) Referencias a claves de la bóveda (vault_key_ids)

• En la pestaña Secretos, marque claves de la bóveda del inventario (Activos ▸ Inventario ▸ Bóveda de claves, infr_vault_key) para enlazarlas.
• La lista se entrega enmascarada (solo id · categoría · título · nombre de usuario; sin el valor).
• Al pulsar [Mostrar] sobre una clave enlazada se llama a POST /service/projects/vault-reveal, que descifra el valor solo en ese momento y lo devuelve.

Las revelaciones de valores de la bóveda se auditan. Cada revelación escribe vault_key.reveal (target=vault_key, via=project) en infr_audit_log. El valor se muestra brevemente y se copia al portapapeles al hacer clic: revélelo solo cuando lo necesite. El registro del proyecto guardado contiene únicamente la referencia al id de la clave.

2) Lista de verificación de secretos (secrets, enmascarada)

Para los secretos que no están en la bóveda (o que se custodian externamente), anote solo la ubicación. El valor nunca se guarda.

La función cleanList() del servidor conserva solo las claves permitidas (label/location/ref/note) y recorta cada una a 255 caracteres. Si los cuatro campos están vacíos, la fila se descarta.

Eliminar

Elimine desde la parte inferior izquierda de la ventana de edición o desde [Eliminar] en la tarjeta. Tras la confirmación, POST /service/projects/delete borra la fila de infr_project y registra project.delete.

Fuentes de datos

Esquema de almacenamiento (infr_project, extracto)

key            varchar(60) unique nullable   # slug
group_id       int -> infr_asset_group
name           varchar(160)                  # obligatorio
status         enum(active,paused,archived)
accessible     boolean default 1
url            varchar(255)                  # expuesta cuando accessible=1
summary        text
repo_provider  enum(github,gitlab,gitea,bitbucket,other)
repo_url / default_branch / visibility(public,private,internal)
jenkins_url    varchar(255)
environments   json  [{env,url,branch,jenkins_job,note}]
web_refs       json  -> infr_web_service id array
db_refs        json  -> infr_collector(database) key array
backup_targets json  [{kind,target,schedule,note}]
vault_key_ids  json  -> infr_vault_key id array (values stay in the vault)
secrets        json  [{label,location,ref,note}]  # lista de verificación, sin valores guardados
tags / meta    json

Esta pantalla no consulta en tiempo real. Solo recarga la lista al guardar, al eliminar o con el botón de actualizar (GET /service/projects/list). Del estado en tiempo real se ocupan Servicio ▸ Catálogo y Servicio ▸ Web.

Acceso

• La puerta de escritura comprueba infr_user_level >= 2 en la sesión (canWrite()). Si falla, devuelve 403 y project.err.forbidden.
• Al guardar, vault_key_ids se filtra hasta dejar solo id de claves de bóveda reales (comprobación de existencia con InfrVaultKey::whereIn(...)). Los id falsificados se descartan en silencio.
• Los niveles son demo=1 · staff=5 · admin=10; algunas áreas se controlan aparte mediante el middleware infr.level:N.

Resolución de problemas y preguntas frecuentes

Q. Pulso Guardar y recibo un 403. La escritura requiere nivel 2 o superior. Una cuenta de visualización (nivel 1) solo puede leer y revelar valores de la bóveda. Pida a un administrador que le suba el nivel.

Q. [Mostrar] devuelve un valor vacío. O bien esa entrada de la bóveda no contiene ningún secreto (hasSecret=false), o bien el descifrado ha fallado (por ejemplo, porque cambió APP_KEY). Vuelva a establecer el valor en Inventario ▸ Bóveda de claves. revealSecret() devuelve null cuando falla.

Q. No aparece nada en las listas de enlaces web/BD. Los servicios web deben existir primero en Servicio ▸ Web, y las opciones de BD requieren recolectores con access=database. Regístrelos, vuelva a abrir la ventana del proyecto y las opciones se rellenarán.

Q. Al guardar la clave (slug) aparece un error de formato. La clave solo admite letras minúsculas, dígitos, guiones y guiones bajos (^[a-z0-9_-]+$, máximo 60). Elimine espacios, mayúsculas y otros símbolos. La clave es opcional, así que puede dejarla en blanco.

Q. ¿Puedo lanzar un despliegue desde aquí? No. Los despliegues se ejecutan en Jenkins. Esta pantalla guarda la URL de Jenkins y los nombres de Job solo como documentación.

Q. ¿Puedo escribir el valor del secreto en una nota de secretos? Nunca. secrets es un mapa de ubicaciones que no guarda valores. Ponga el valor real en la bóveda cifrada de Inventario ▸ Bóveda de claves y haga referencia a él mediante vault_key_ids.

Relacionado

• Servicio ▸ Web — los servicios web enlazados mediante web_refs.
• Servicio ▸ Base de datos — los recolectores de BD enlazados mediante db_refs.
• Servicio ▸ Catálogo — vitalidad de los demonios por instancia (el estado en vivo vive ahí).
• Panel de programación — definición y ejecución de los trabajos de copia reales.
• Activos ▸ Inventario — la pantalla de origen de las claves de bóveda (infr_vault_key).
• Registro de auditoría — verifique los registros de project.create/update/delete y vault_key.reveal.