Öffentliche Produktfreigabe (öffentlicher HTTPS-Link)

Wenn Ihr Workflow einen Bericht (.md / .html / .xlsx / .pdf) generiert und ihn an andere senden möchte, besteht der direkteste Weg darin, den Dateianhang über das Slack/Mail-Modul hochladen zu lassen. Große Dateien sind jedoch langsam, und auf Messaging-Plattformen sind die Größe einer einzelnen Datei und die Anzahl der Anhänge normalerweise begrenzt.

Öffentliche Produktfreigabe ist ein anderer Weg: Ein einzelnes Artefakt wird als HTTPS-Kurzlink ohne Login-Zwang veröffentlicht, in der Nachricht wird nur der Link gesendet, und ein Klick genügt zum Ansehen — die Datei selbst bleibt auf dem Server, was Datenverkehr spart und die direkte Vorschau im Browser ermöglicht (.md lässt sich online als HTML rendern). Wenn mehrere Dateien auf einmal zu teilen sind, lässt sich auch das gesamte Artefaktverzeichnis als ein Link veröffentlichen, siehe unten „Öffentlicher Link auf Verzeichnisebene“.

Wann verwenden

• Berichte/Dashboards müssen an Slack/Feishu/E-Mail gesendet werden, und ich möchte nicht, dass jeder eine 3 MB große XLSX-Datei speichert.
• Ein externer Mitwirkender (ohne Plattformkonto) soll einen App-Store-Daten-Snapshot sehen
• Ein .md-Fazit vorübergehend mit einem Kunden teilen, der es im Handy-Browser direkt als HTML lesen soll
• Der Link soll Ablaufzeit, Download-Limit oder Passwortschutz bekommen

Verwendung — über die Oberfläche

1. Öffnen Sie eine abgeschlossene Execution, wechseln Sie zum Tab „Artefakte“ — neben jedem Artefakt gibt es eine 🔗 Teilen-Schaltfläche
2. Klicken Sie auf 🔗 Teilen, um den Freigabedialog zu öffnen
3. Bei Bedarf konfigurieren:
   • Zugriffsbereich: öffentlich (Standard) / passwortgeschützt / teamintern / bestimmte Mitglieder, Details siehe unten „Zugriffsbereich und Zugriffsantrag“
   • Gültigkeitsdauer: läuft nie ab (Standard) / 1 Stunde / 24 Stunden / 7 Tage / 30 Tage, Ihre letzte Auswahl wird gemerkt
   • Download-Limit: 0 = unbegrenzt, >0 = der Link verfällt automatisch nach Verbrauch
   • Zugriffspasswort (im passwortgeschützten Modus): Beim Öffnen des Links erscheint im Browser ein Passwort-Eingabefeld
   • Online-HTML-Rendering (nur .md): Wenn angekreuzt, zeigt der Link formatiertes HTML statt eines .md-Downloads
4. Klicken Sie auf „Link generieren“ → Sie erhalten eine URL der Form https://braidrun.com/p/a/hN2kQ9…, klicken auf „Kopieren“ und fügen sie beliebig ein

Verwendung — automatische Veröffentlichung im Workflow (empfohlen)

Nachdem der Workflow ausgeführt wurde, wird das Produkt automatisch in einen öffentlichen Link umgewandelt und der Link dann automatisch an Slack übertragen – im gesamten Prozess sind keine manuellen Klicks zum Teilen erforderlich.

Typische Orchestrierung in drei Schritten

1. Der artefakterzeugende Schritt wird ganz normal geschrieben, ohne besondere Markierung — zum Beispiel:

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

2. Hängen Sie das eingebaute artifact-publish-Modul an und übergeben Sie den Namen des vorherigen Schritts `from_step: build_report`. Das Modul durchsucht die Artefaktliste der Execution, findet die Datei dieses Schritts und erstellt den öffentlichen Link:

   - 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. Hängen Sie dann ein eingebautes Slack-Zustellmodul an und übergeben Sie public_url → Slack erhält nur eine Textnachricht mit Link, ohne Datei-Upload:

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

Was bei mehreren Artefakten?

Wenn der Schritt build_report mehrere Dateien erzeugt hat (etwa daily.md und metrics.json zugleich), filtern Sie mit 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

Ohne artifact_name nimmt das Modul das erste passende Artefakt und vermerkt im Log, wie viele ungenutzt blieben.

Öffentlicher Link auf Verzeichnisebene: eine URL teilt das gesamte Artefaktverzeichnis

Ein Einzeldateilink kann jeweils nur ein Artefakt teilen. Wenn eine Ausführung eine Gruppe von Dateien erzeugt (Report + Daten + Bilder oder sogar eine vollständige mehrseitige statische Website), lässt sich das gesamte Artefaktverzeichnis als ein Link veröffentlichen:

• UI-Einstieg: Klicken Sie im Tab „Artefakte“ der Ausführungsdetails auf „Alle Artefakte teilen“, um einen Verzeichnislink zu erzeugen, der alle Artefakte dieser Ausführung umfasst; die Konfigurationsoptionen (Zugriffsbereich / Gültigkeitsdauer / Download-Kontingent / Passwort / Online-Rendering) sind dieselben wie bei der Einzeldatei, zusätzlich lässt sich der Anzeigename anpassen
• Die API kann auch die Artefakte eines einzelnen Schritts teilen. Um die gesamte Ausführung zu teilen: POST /api/executions/{id}/directory-public-link; um einen einzelnen Schritt zu teilen: POST /api/executions/{id}/steps/{stepName}/directory-public-link
• Der Link hat die Form https://braidrun.com/p/d/hN2kQ9…/, der Besucher benötigt kein Konto (im öffentlichen Modus)

Was der Besucher sieht

• Standardmäßig eine Dateilistenseite: Dateiname, Größe, Typ sowie die Gültigkeitsdauer und das Download-Kontingent des Links
• Liegt im Verzeichniswurzel eine index.html, wird sie direkt als statische Website geöffnet — ein vom Workflow erzeugter mehrseitiger HTML-Report lässt sich als ganze Website teilen; ein an die URL angehängtes ?listing=1 erzwingt die Rückkehr zur Dateilistenansicht
• Ist Online-Rendering aktiviert, werden .md-Dateien im Verzeichnis als fertig formatiertes HTML angezeigt
• Dateien im Verzeichnis werden stets von der Plattform mit dem korrekten Content-Type ausgeliefert (nicht über einen 302-Direktlink zum Objektspeicher), sodass HTML / CSS / JS vom Browser korrekt gerendert werden
• Das Download-Kontingent wird über das gesamte Verzeichnis kumuliert; ist es aufgebraucht, wird der Link automatisch ungültig

Zugriffsbereich und Zugriffsantrag

Einzeldateilink und Verzeichnislink teilen denselben Satz von Zugriffsbereichen:

Im Modus teamintern / bestimmte Mitglieder wird der Link zu einem „anmeldepflichtigen Deep-Link“: Ein nicht angemeldeter Zugriff wird zur Anmeldung geleitet; wer angemeldet ist, aber nicht auf der Liste steht, sieht die Seite „Kein Zugriff“.

Ablauf des Zugriffsantrags (im Modus teamintern / bestimmte Mitglieder optional aktivierbar):

1. Aktivieren Sie beim Erstellen des Links „Angemeldeten Nutzern erlauben, bei fehlendem Zugriff einen Antrag zu stellen“
2. Wer keinen Zugriff hat, öffnet den Link und füllt auf der Seite „Kein Zugriff“ ein Antragsformular aus, optional mit einer Begründung; eine erneute Einreichung aktualisiert den ursprünglichen Antrag
3. Der Teilende oder ein Link-Administrator genehmigt / lehnt unter „Konto → Freigabeverwaltung“ ab; vor der Genehmigung ist zu bestätigen, dass die Person bereits dem gewählten Team angehört
4. Nach der Genehmigung wird die Person der Zugriffsliste hinzugefügt und kann den ursprünglichen Link direkt öffnen

Verzeichnislinks verwalten

• „Konto → Freigabeverwaltung“ verwaltet Einzeldatei- und Verzeichnislinks gemeinsam: Zugriffsbereich ändern, Gültigkeitsdauer ändern, widerrufen sowie Zugriffszähler und Zugriffslog ansehen (Zeit, Konto-Identität, IP, User-Agent)
• Die zugehörige Verwaltungs-API (auflisten / ändern / widerrufen) lautet: GET /api/directory-public-links · PATCH /api/directory-public-links/{token} · DELETE /api/directory-public-links/{token}
• Der Ersteller ist standardmäßig Link-Administrator und kann weitere Administratoren benennen, die gemeinsam Zugriffsanträge und Widerrufe bearbeiten

Unterstützte Freigabemethoden

Die obige Tabelle bezieht sich auf Einzeldateilinks; bei Verzeichnislinks wird der Dateistrom stets von der Plattform ausgeliefert, sodass sie in jeder Deployment-Form nutzbar sind.

Sicherheit und Compliance

• Tokens nicht enumerierbar —— 24-Byte-SecureRandom → base62 ≈ 143 Bit Entropie; Brute-Force-Scans sind unpraktikabel
• Schutz vor Crawler-Indexierung —— Antwort-Header X-Robots-Tag: noindex, nofollow + Referrer-Policy: no-referrer; Google/Bing indexieren die Links nicht
• Ratenbegrenzung —— Gateway-Schicht: 10 Mal pro Sekunde für dieselbe IP, 20 Bursts; Serviceschicht: festes Limit basierend auf den maxDownloads des Tokens
• Passwortschutz (optional) —— Argon2id-Hash; Eingabe im Popup beim Browser-Zugriff, Skript-Clients nutzen den Header Authorization: Basic oder X-Artifact-Password. Das Passwort steht nicht im URL-Abfrageparameter, um zu vermeiden, dass es im Zugriffslog landet
• Auditlogs —— Jedes Erstellen / Zugreifen / Widerrufen schreibt einen audit_log-Eintrag mit Client-IP, User-Agent und Zeitstempel
• DSGVO-konform —— Beim Löschen des Kontos werden alle Links kaskadierend bereinigt; beim Datenexport liegt artifact_public_links.jsonl im ZIP
• Sofortiger Widerruf —— „Widerrufen“ in der Freigabeverwaltung wirkt sofort; widerrufene Links liefern 410 Gone (nicht 404, um Verwechslung mit „existiert nicht“ zu vermeiden)

Geteilte Links verwalten

Unter Konto → Freigabeverwaltung (oder direkt GET /api/public-links) sehen Sie alle erstellten Links, Zugriffszähler und Widerrufsstatus. Ein Klick auf Widerrufen macht den Link sofort ungültig.

FAQ

F: warum zeigt der Link 410 Gone?

• Der Link ist abgelaufen (Gültigkeitszeitraum endete)
• Der Link wurde vom Ersteller oder einem Administrator widerrufen
• Die Anzahl der Downloads hat die Obergrenze erreicht (nach Aufbrauchen des Kontingents wird der Link automatisch ungültig)
• Das Passwort wurde falsch eingegeben (wer noch kein Passwort eingegeben hat, sieht zunächst das Passwort-Popup des Browsers, nicht 410)

F: kann ein Link unbegrenzt gültig sein?

Ja, aber die Oberfläche verlangt eine zweite Bestätigung — ein permanenter Link bedeutet, dass ohne manuellen Widerruf jeder mit dem Link dauerhaft zugreifen kann; Vorsicht. Administratoren können permanente Links mit BRAIDRUN_PUBLIC_LINK_REJECT_PERMANENT=true global deaktivieren.

F: werden die Links von Suchmaschinen indexiert?

Nein. Die Antwort-Header erzwingen noindex, nofollow, und die nginx-Schicht ergänzt eine weitere. Wenn Sie den Link jedoch auf einer öffentlichen Seite einfügen, können Crawler die URL entdecken — veröffentlichen Sie solche Links daher niemals in einem GitHub-README oder Blogartikel.

F: welche Dateigröße ist angemessen?

Im Objektspeichermodus: Theoretisch unbegrenzt; tatsächlich durch das Browser-Timeout des Benutzers begrenzt (im Allgemeinen sind mehrere zehn MB kein Problem). Im lokalen Festplattenmodus: Die Dateilesegeschwindigkeit der Plattform ist begrenzt. Es wird nicht empfohlen, 100 MB zu überschreiten.

F: funktioniert der alte Link noch, wenn ich die zugehörige Execution lösche?

Nein. Beim Löschen einer Execution widerruft das System kaskadierend alle darauf zeigenden Links; spätere Zugriffe erhalten 410 Gone.

F: IST diese Funktion standardmäßig aktiviert?

Ein Administrator muss sie explizit über die Umgebungsvariable BRAIDRUN_PUBLIC_BASE_URL aktivieren; andernfalls ist die Teilen-Schaltfläche in der Oberfläche nicht sichtbar. Siehe PRODUCTION_GUIDE §2.4 in der Betriebsdokumentation.