Uso compartido público del producto (enlace HTTPS público)

Si su flujo de trabajo genera un informe (.md / .html / .xlsx / .pdf) y desea enviarlo a otras personas, la forma más directa es dejar que el módulo Slack/mail cargue el archivo adjunto. Pero los archivos grandes serán lentos y las plataformas de mensajería suelen tener límites en el tamaño de un solo archivo y en la cantidad de archivos adjuntos.

Intercambio público de productos es otro camino: publica un solo artefacto como un enlace HTTPS corto sin necesidad de iniciar sesión; en el mensaje solo se envía el enlace y al abrirlo se puede ver — el archivo en sí permanece en el servidor, lo que ahorra tráfico y permite la vista previa directa en el navegador (los .md se pueden renderizar en línea como HTML). Cuando hay que compartir varios archivos a la vez, también se puede publicar todo el directorio de artefactos como un solo enlace; ver «Enlace público a nivel de directorio» más abajo.

Cuándo usarlo

• Los informes/paneles deben enviarse a Slack/Feishu/correo electrónico, y no quiero que todos guarden un xlsx de 3 MB cada uno.
• Un colaborador externo (sin cuenta en la plataforma) necesita ver una instantánea de datos de la app store
• Compartes temporalmente unas conclusiones .md con un cliente que debería verlas como HTML en el navegador del móvil
• Quieres que el enlace tenga caducidad, tope de descargas o contraseña

Cómo usarlo — desde la interfaz

1. Abre una execution terminada, cambia a la pestaña Artefactos y verás un botón 🔗 Compartir junto a cada artefacto
2. Haz clic en 🔗 Compartir para abrir el diálogo de compartición
3. Configuración a la carta:
   • Ámbito de acceso: público (por defecto) / acceso con contraseña / dentro del equipo / miembros concretos; ver «Ámbito de acceso y solicitud de acceso» más abajo
   • Validez: no caduca nunca (por defecto) / 1 hora / 24 horas / 7 días / 30 días; recuerda su última elección
   • Tope de descargas: 0 = ilimitado, >0 = el enlace caduca automáticamente al agotarse
   • Contraseña de acceso (modo de acceso con contraseña): al abrir el enlace, el navegador muestra un cuadro para introducir la contraseña
   • Renderizado HTML en línea (solo .md): al marcarlo, el enlace muestra HTML formateado en lugar de descargar el archivo .md
4. Pulse «Generar enlace» → obtiene una URL con la forma https://braidrun.com/p/a/hN2kQ9..., pulse «Copiar» y péguela donde quiera

Cómo usarlo — publicación automática en el flujo (recomendado)

Una vez ejecutado el flujo de trabajo, el producto se convierte automáticamente en un enlace público y luego el enlace se envía automáticamente a Slack; no se requieren clics manuales para compartir en todo el proceso.

Composición típica en tres pasos

1. El paso que genera el artefacto se escribe como siempre, sin marcas especiales — por ejemplo:

   - step: build_report
     agent: reporter
     input: |
       生成今天的业务报表,写入 /tmp/.../daily.md。
     # 这一步完成后,引擎自动注册一个产物(execution 的 artifacts 列表里会出现)

2. Conecta el módulo integrado artifact publish y pásale el nombre del paso anterior `from_step: build_report`. El módulo consulta la lista de artefactos de la execution, encuentra el archivo de ese paso y crea el enlace público:

   - step: share_report
     sub_workflow:
       name: dingyue-module-artifact-publish
       inputs:
         from_step: "build_report"          # ← 唯一必需字段:引用上一步的步骤名
         ttl_minutes: "0"                   # 永不过期；如需限时可改成分钟数
         render_markdown_as_html: "true"    # .md 直接在线 HTML 预览
       # base_url / api_token 不用填 —— 引擎自动注入运行时访问令牌
       outputs:
         share_url: public_url              # 下游可以用 {{var:share_url}} 引用
     depends_on: [build_report]

3. Luego conecta un módulo integrado de entrega a Slack y pásale public_url → Slack recibe solo un mensaje de texto con enlace, sin subir archivos:

   - step: notify
     sub_workflow:
       name: dingyue-module-slack-deliver
       inputs:
         slack_webhook_url: "{{var:slack_webhook_url}}"
         message_text: "📊 今日报表已生成"
         public_url: "{{var:share_url}}"   # ← 复用 share_report 的输出
     depends_on: [share_report]

¿Y SI hay varios artefactos?

Si el paso build_report generó varios archivos (por ejemplo daily.md y metrics.json a la vez), filtra con artifact_name:

- step: share_report
  sub_workflow:
    name: dingyue-module-artifact-publish
    inputs:
      from_step: "build_report"
      artifact_name: "daily.md"            # ← 精确挑选
      ttl_minutes: "0"
    outputs:
      share_url: public_url

Sin artifact_name, el módulo toma el primer artefacto coincidente y registra cuántos quedaron sin usar.

Enlace público a nivel de directorio: una sola URL comparte todo el directorio de artefactos

Un enlace de archivo único solo comparte un artefacto por vez. Si una ejecución produce un conjunto de archivos (informe + datos + imágenes, o incluso un sitio web estático completo de varias páginas), puede publicar todo el directorio de artefactos como un solo enlace:

• Acceso en la UI: en la pestaña «Artefactos» del detalle de la ejecución, pulse «Compartir todos los artefactos» para generar un enlace de directorio que cubre todos los artefactos de esa ejecución; las opciones de configuración (ámbito de acceso / validez / cuota de descargas / contraseña / renderizado en línea) son idénticas a las del archivo único, y además se puede personalizar el nombre visible
• La API también permite compartir los artefactos de un solo paso. Para compartir toda la ejecución: POST /api/executions/{id}/directory-public-link; para compartir un solo paso: POST /api/executions/{id}/steps/{stepName}/directory-public-link
• El enlace tiene la forma https://braidrun.com/p/d/hN2kQ9.../, y el visitante no necesita cuenta (en modo público)

Qué ve el visitante

• Por defecto, una página de lista de archivos: nombre, tamaño y tipo del archivo, además de la validez del enlace y la cuota de descargas
• Cuando la raíz del directorio tiene un index.html, se abre directamente como un sitio estático — un informe HTML de varias páginas generado por el workflow se puede compartir como un sitio entero; añadir ?listing=1 a la URL fuerza la vuelta a la vista de lista de archivos
• Cuando se ha marcado el renderizado en línea, los archivos .md del directorio se muestran como HTML bien maquetado
• Los archivos del directorio siempre los reenvía la plataforma con el Content-Type correcto (no van por un enlace directo 302 del almacenamiento de objetos), lo que garantiza que HTML / CSS / JS se rendericen con normalidad en el navegador
• La cuota de descargas se acumula sobre todo el directorio; cuando se agota, el enlace deja de ser válido automáticamente

Ámbito de acceso y solicitud de acceso

El enlace de archivo único y el enlace de directorio comparten el mismo conjunto de ámbitos de acceso:

En los modos dentro del equipo / miembros concretos, el enlace se convierte en un «enlace profundo que requiere inicio de sesión»: quien acceda sin haber iniciado sesión será dirigido a iniciar sesión; quien haya iniciado sesión pero no esté en la lista verá una página de «Sin permiso de acceso».

Flujo de solicitud de acceso (opcional, se puede activar en los modos dentro del equipo / miembros concretos):

1. Al crear el enlace, marque «Permitir que los usuarios que hayan iniciado sesión envíen una solicitud cuando no tengan acceso»
2. Quien no tenga acceso abre el enlace, rellena un formulario de solicitud en la página de «Sin permiso de acceso» y puede adjuntar una nota; volver a enviarlo actualiza la solicitud original
3. El propietario del enlace compartido o un administrador del enlace aprueba / rechaza en «Cuenta → Gestión de compartidos»; antes de aprobar hay que confirmar que la otra persona ya pertenece al equipo seleccionado
4. Tras aprobar, la persona se añade a la lista de acceso y puede abrir directamente el enlace original

Gestionar los enlaces de directorio

• «Cuenta → Gestión de compartidos» gestiona juntos los enlaces de archivo único y de directorio: cambiar el ámbito de acceso, cambiar la validez, revocar, y ver el recuento de accesos y el registro de accesos (hora, identidad de la cuenta, IP, User-Agent)
• La API de gestión correspondiente (listar / modificar / revocar) es: GET /api/directory-public-links · PATCH /api/directory-public-links/{token} · DELETE /api/directory-public-links/{token}
• El creador es por defecto administrador del enlace y puede designar administradores adicionales para tramitar juntos las solicitudes de acceso y las revocaciones

Métodos de uso compartido admitidos

La tabla anterior es para el enlace de archivo único; el enlace de directorio siempre lo reenvía la plataforma como flujo de archivos, y sirve para cualquier forma de despliegue.

Seguridad y cumplimiento

• Tokens no enumerables —— SecureRandom de 24 bytes → base62 ≈ 143 bits de entropía; el escaneo por fuerza bruta es inviable
• Protección contra indexación —— Cabeceras X-Robots-Tag: noindex, nofollow + Referrer-Policy: no-referrer; Google/Bing no indexarán los enlaces
• Límite de velocidad —— Capa de puerta de enlace: 10 veces por segundo para la misma IP, 20 ráfagas; capa de servicio: límite estricto basado en las descargas máximas del token
• Protección con contraseña (opcional) —— Hash Argon2id; al acceder desde el navegador se muestra un cuadro para introducirla, y los clientes de script usan el header Authorization: Basic o X-Artifact-Password. La contraseña no va en el parámetro de query de la URL, para que no acabe en el registro de accesos
• Logs de auditoría —— Cada creación / acceso / revocación escribe un audit_log con IP del cliente, User-Agent y marca de tiempo
• Compatible con GDPR —— Al eliminar la cuenta, todos los enlaces se limpian en cascada; al exportar datos, artifact_public_links.jsonl se incluye en el ZIP
• Revocación inmediata —— Pulsar Revocar en la gestión de compartidos surte efecto al instante; los enlaces revocados devuelven 410 Gone (no 404, para no confundir con "no existe")

Gestionar enlaces compartidos

En Cuenta → Gestión de compartidos (o directamente GET /api/public-links) verás todos los enlaces creados, su recuento de accesos y si están revocados. Al pulsar Revocar, el enlace deja de funcionar al instante.

FAQ

P: ¿POR qué el enlace muestra 410 Gone?

• El enlace caducó (terminó su periodo de validez)
• El enlace fue revocado por su creador o un administrador
• El número de descargas ha alcanzado el límite (al agotarse la cuota, deja de ser válido automáticamente)
• La contraseña es incorrecta (si aún no se ha introducido ninguna contraseña, primero se verá el cuadro de contraseña del navegador, no un 410)

P: ¿puedo hacer que un enlace no caduque nunca?

Sí, pero la interfaz pedirá una segunda confirmación — un enlace permanente significa que, salvo revocación manual, cualquiera que lo tenga podrá acceder para siempre; ten cuidado. Los administradores pueden deshabilitar los enlaces permanentes globalmente con BRAIDRUN_PUBLIC_LINK_REJECT_PERMANENT=true.

P: ¿LOS enlaces serán indexados por buscadores?

No. Las cabeceras fuerzan noindex, nofollow, y la capa nginx añade otra. Pero si pegas el enlace en una página pública, los rastreadores pueden descubrir la URL — así que nunca publiques estos enlaces en un README de GitHub o un artículo de blog.

P: ¿QUÉ tamaño de archivo es apropiado?

En modo de almacenamiento de objetos: Teóricamente ilimitado; en realidad está limitado por el tiempo de espera del navegador del usuario (generalmente decenas de MB no son un problema). En modo de disco local: limitado por la velocidad de lectura de archivos de la plataforma, no se recomienda exceder los 100 MB.

P: SI Elimino la execution del artefacto, ¿sigue funcionando el enlace antiguo?

No. Al eliminar una execution, el sistema revoca en cascada todos los enlaces que apuntan a ella; los accesos posteriores reciben 410 Gone.

P: ¿esta función está activada por defecto?

Un administrador debe activarla explícitamente con la variable de entorno BRAIDRUN_PUBLIC_BASE_URL; sin ella, el botón Compartir no aparece en la interfaz. Ver PRODUCTION_GUIDE §2.4 en la documentación de operaciones.