Partilha de Artefactos Públicos (Links HTTPS Públicos)

Se seu workflow gera um relatório (.md / .html / .xlsx / .pdf) e quer enviá-lo para outros, a maneira mais direta é deixar o módulo Slack/mail carregar o anexo do arquivo. Mas arquivos grandes serão lentos, e plataformas de mensagens geralmente têm limites sobre o tamanho de um único arquivo e o número de anexos.

Partilha de Artefactos Públicos é outra rota: publicar um único artefato como um link HTTPS livre de login, enviar apenas o link em uma mensagem, e ele abre para cima — o próprio arquivo permanece no servidor, que economiza largura de banda e permite que o navegador visualizá-lo diretamente (. md pode ser renderizado para HTML online). Para compartilhar vários arquivos ao mesmo tempo, você também pode publicar um diretório de artefato inteiro como um link; veja abaixo "Links públicos de nível diretoria".

Quando usar

• Relatórios / painéis precisam ser enviados para Slack / Feishu / email, e eu não quero que todos salvem um xlsx 3MB cada.
• Um colaborador externo (sem conta na plataforma) precisa de ver um instantâneo de dados da app store
• Partilha temporariamente conclusões em .md com um cliente que deve lê-las como HTML no navegador do telemóvel
• Quer dar à ligação uma expiração, um limite de transferências ou proteção por palavra-passe

Como usar — a partir da interface

1. Abra uma execution terminada, mude para o separador Artefactos e verá um botão 🔗 Partilhar junto a cada artefacto
2. Clique em 🔗 Partilhar para abrir a caixa de diálogo de partilha
3. Configurar conforme necessário:
   • Âmbito de acesso: público (padrão) / senha / equipe / membros especificados; veja "Acesso escopo e pedidos de acesso" abaixo
   • Vida útil: nunca expira (padrão) / 1 hora / 24 horas / 7 dias / 30 dias; ele se lembra de sua última escolha
   • Limite de transferências: 0 = ilimitado, >0 = a ligação expira automaticamente quando esgotado
   • Senha de acesso (modo password): o navegador pede uma senha quando o link é aberto
   • Renderização HTML online (apenas .md): quando assinalado, a ligação mostra HTML formatado em vez de descarregar o ficheiro .md
4. Clique em "Generate link" → obter uma URL como https://braidrun.com/p/a/hN2kQ9..., em seguida, clique em "Copiar" e cole-o em qualquer lugar

Como usar — publicação automática no fluxo (recomendado)

Depois que o workflow é executado, o produto é automaticamente transformado em um link público, e então o link é automaticamente empurrado para Slack - não são necessários cliques manuais para compartilhar em todo o processo.

Orquestração típica em três passos

1. O passo que gera o artefacto escreve-se normalmente, sem marcas especiais — por exemplo:

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

2. Ligue o módulo integrado artifact publish e passe o nome do passo anterior `from_step: build_report`. O módulo consulta a lista de artefactos da execution, encontra o ficheiro desse passo e cria a ligação pública:

   - 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. Depois ligue um módulo integrado de entrega no Slack e passe-lhe public_url → o Slack recebe apenas uma mensagem de texto com a ligação, sem carregar ficheiros:

   - 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]

E SE houver vários artefactos?

Se o passo build_report gerou vários ficheiros (por exemplo daily.md e metrics.json ao mesmo tempo), filtre com 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

Sem artifact_name, o módulo usa o primeiro artefacto correspondente e regista quantos ficaram por usar.

Links públicos de nível de diretório: um URL para compartilhar um diretório de artefato inteiro

Um link de arquivo único pode compartilhar apenas um artefato de cada vez. Se uma execução produz um conjunto de arquivos (um relatório + dados + imagens, ou mesmo um site estático multi-páginas completo), você pode publicar todo o diretório artefato como um link:

• Entrada UI: na página "Artifacts" detalhes de execução, clique em "Compartilhar todos os artefatos" para gerar um link de diretório cobrindo todos os artefatos desta execução; as opções (acesso escopo / vida / download quota / senha / renderização online) são as mesmas que para um único arquivo, além de que você pode definir um nome de exibição personalizado
• The API can also share the artifacts of a single step. To share the whole run: POST /api/executions/{id}/directory-public-link; to share a single step: POST /api/executions/{id}/steps/{stepName}/directory-public-link
• O link se parece com https://braidrun.com/p/d/hN2kQ9.../, e visitantes não precisam de conta (no modo público)

O que os visitantes vêem

• Por padrão, uma página de lista de arquivos: nome do arquivo, tamanho e tipo, além da vida útil do link e quota de download
• Quando há um index.html na raiz do diretório, ele abre como um site estático — um relatório HTML de várias páginas gerado por um workflow pode ser compartilhado como um site inteiro; adicione ?listing=1 à URL para forçar a visualização de lista de arquivos
• Quando a renderização online está ativada, os arquivos .md no diretório são mostrados como HTML formatado
• Os arquivos no diretório são sempre encaminhados pela plataforma com o Tipo de Conteúdo correto (não através de um redirecionamento 302 para armazenamento de objetos), para que o navegador possa renderizar HTML / CSS / JS corretamente
• A quota de download se acumula em todo o diretório, e o link expira automaticamente uma vez que seja usado

Âmbito de acesso e pedidos de acesso

Links de arquivo único e links de diretório compartilham o mesmo conjunto de escopos de acesso:

No modo equipe ou membro especificado, o link torna-se um "link profundo sign-in-required": acessá-lo enquanto desliga os redirecionamentos para login; login mas não na lista mostra uma página "sem acesso".

Fluxo de solicitação de acesso (opcional no modo equipe ou membro especificado):

1. Ao criar o link, verifique "Permitir aos usuários conectados enviar uma solicitação quando não tiverem acesso"
2. Um visitante sem acesso abre o link, preenche um formulário de solicitação na página "sem acesso" (uma nota pode ser anexada); enviando novamente atualiza o pedido original
3. O compartilhamento ou um administrador de link aprova / rejeita sob "Conta → Share management"; antes de aprovar, confirme que a pessoa já pertence à equipe selecionada
4. Uma vez aprovada, a pessoa é adicionada à lista de acesso e pode abrir o link original diretamente

Gerenciando links de diretório

• "Conta → Gerenciamento de compartilhamento" gerencia links de arquivo único e diretório juntos: alterar o escopo de acesso, alterar a vida útil, revogar e visualizar contagens de acesso e logs de acesso (tempo, identidade de conta, IP, usuário-agente)
• The corresponding management API — list / update / revoke — is: GET /api/directory-public-links · PATCH /api/directory-public-links/{token} · DELETE /api/directory-public-links/{token}
• O criador é o administrador de link por padrão e pode designar administradores adicionais para lidar conjuntamente com pedidos de acesso e revogações

Métodos de partilha suportados

A tabela acima é para links de arquivo único; links de diretório sempre têm a plataforma para encaminhar o fluxo de arquivos, então eles trabalham em qualquer forma de implantação.

Segurança e conformidade

• Tokens não enumeráveis —— SecureRandom de 24 bytes → base62 ≈ 143 bits de entropia; a pesquisa por força bruta é inviável
• Proteção contra indexação por crawlers —— Cabeçalhos X-Robots-Tag: noindex, nofollow + Referrer-Policy: no-referrer; o Google/Bing não indexará as ligações
• Limitação de débito —— Camada Gateway: 10 vezes por segundo para o mesmo IP, 20 rajadas; camada de serviço: limite rígido baseado no token’s maxDownloads
• Proteção por palavra-passe (opcional) —— Argon2id hashing; o navegador solicita acesso, e os clientes de script usam o cabeçalho Autorização: Basic ou X-Artifact-Password. A senha não é colocada na string de pesquisa URL, para mantê-la fora dos logs de acesso
• Logs de auditoria —— Cada criação / acesso / revogação escreve um audit_log com IP do cliente, User-Agent e carimbo temporal
• Compatível com o RGPD —— Ao eliminar a conta, todas as ligações são limpas em cascata; na exportação de dados, artifact_public_links.jsonl é incluído no ZIP
• Revogação imediata —— Clicar em Revogar na gestão de partilhas tem efeito imediato; as ligações revogadas devolvem 410 Gone (não 404, para evitar confusão com "não existe")

Gerir ligações partilhadas

Em Conta → Gestão de partilhas (ou diretamente GET /api/public-links) vê todas as ligações que criou, o número de acessos e se estão revogadas. Ao clicar em Revogar, a ligação deixa de funcionar de imediato.

FAQ

P: porque é que a ligação mostra 410 Gone?

• A ligação expirou (terminou o período de validade)
• A ligação foi revogada pelo criador ou por um administrador
• A contagem de transferências atingiu o seu limite (o link expira automaticamente uma vez que a quota é utilizada)
• A senha estava errada (antes de inserir uma, você verá o prompt de senha do navegador ao invés de um 410)

P: posso fazer uma ligação que nunca expire?

Sim, mas a interface pedirá uma segunda confirmação — uma ligação permanente significa que, salvo revogação manual, quem a tiver poderá aceder para sempre; cuidado. Os administradores podem desativar globalmente as ligações permanentes com BRAIDRUN_PUBLIC_LINK_REJECT_PERMANENT=true.

P: AS Ligações serão indexadas pelos motores de busca?

Não. Os cabeçalhos impõem noindex, nofollow, e a camada nginx acrescenta outro. Mas se colar a ligação numa página pública, os crawlers podem descobrir o URL — por isso nunca publique estas ligações num README do GitHub ou num artigo de blog.

P: QUE tamanho de ficheiro é adequado?

No modo de armazenamento de objetos: Teoricamente ilimitado; realmente limitado pelo tempo limite do navegador do usuário (geralmente dezenas de MB não é problema). No modo de disco local: limitado pela velocidade de leitura do arquivo da plataforma, não é recomendado exceder 100MB.

P: SE Eliminar a execution do artefacto, a ligação antiga continua a funcionar?

Não. Ao eliminar uma execution, o sistema revoga em cascata todas as ligações que apontam para ela; os acessos seguintes recebem 410 Gone.

P: esta funcionalidade vem ativada por predefinição?

Um administrador tem de a ativar explicitamente através da variável de ambiente BRAIDRUN_PUBLIC_BASE_URL; sem isso, o botão Partilhar não aparece na interface. Ver PRODUCTION_GUIDE §2.4 na documentação de operações.