lightning-artifacts
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLightning AI Artifacts (durable shareable file links)
Lightning AI Artifacts(持久化可分享文件链接)
Publish any file to a teamspace and get back a durable public URL —
— that anyone can open with no Lightning
login, renders inline in the browser (HTML/PDF/images), and never expires.
The control plane streams the bytes from storage on every request, so unlike a
presigned S3 URL there is no ~1h cap. Great for agent-generated one-pagers,
reports, dashboards, dataset samples, or build artifacts.
https://lightning.ai/artifacts/<id>This whole flow runs through the CLI (from the package):
/ / handle the files, and — a
-style raw HTTP client — makes the two publish calls around them. No
Python, no SDK code, not even a .
lightninglightning-sdklightning cplsrmlightning apigh apicurl将任意文件发布到 teamspace 后,你将获得一个持久化公开URL——
——任何人无需登录 Lightning
账号即可打开,支持在浏览器内联渲染(HTML/PDF/图片),且永不过期。
控制平面会在每次请求时从存储中流式传输文件字节,因此与预签名 S3 URL 不同,它没有约1小时的有效期限制。非常适合分享 Agent 生成的单页文档、报告、仪表盘、数据集样本或构建产物。
https://lightning.ai/artifacts/<id>整个流程完全通过 CLI 完成(来自 包):
/ / 用于处理文件,而 ——一个
类似 的原生HTTP客户端——负责执行前后的两次发布调用。无需编写Python代码,无需调用SDK,甚至不用写 命令。
lightninglightning-sdklightning cplsrmlightning apigh apicurlSetup & auth
安装与认证
bash
undefinedbash
undefinedUse the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18
Use the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18
v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p')
[ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ]
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here
v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p')
[ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ]
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here
|| uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk lightning --version # must print "Lightning CLI version …"; if not, see the table below lightning login # interactive browser sign-in — enough for everything here
or: export LIGHTNING_API_KEY=... # non-interactive alternative (CI, agents)
or: export LIGHTNING_API_KEY=... # non-interactive alternative (CI, agents)
Either credential works for **every call in this skill** — no token minting or
extra auth steps. Get a key from lightning.ai → user/org settings, or
`lightning api-key create --org <org> --name artifacts`. **Never hardcode the
key** — read it from the environment. To target a non-prod control plane, set
`LIGHTNING_CLOUD_URL` (default `https://lightning.ai`).
This uses, and if needed installs into, the environment the agent runs in (the user's project
venv, a conda env, …). Then call plain `lightning …` everywhere. If setup doesn't go cleanly:
| Symptom | Fix |
|---|---|
| Both installs fail: no active env, or pip refuses with `externally-managed-environment` | Install it on its own instead: `uv tool install lightning-sdk` (or `pipx install lightning-sdk`), then call `"$(uv tool dir --bin)/lightning"` if that dir isn't on `PATH` |
| `lightning --version` still prints no `Lightning CLI version` line after installing | `command -v lightning` shows which one runs. Another tool owns the name (PyTorch Lightning also installs a `lightning` command), or the env you installed into isn't on `PATH`: activate it (`source .venv/bin/activate`) or call its `bin/lightning` by full path |
| `No such command`, `No such option` or `unexpected extra argument` | The CLI is older than this skill expects: `uv pip install -U lightning-sdk` (or `pip install -U lightning-sdk`) in the env `command -v lightning` points into; `uv tool upgrade lightning-sdk` for a uv tool install |
| The upgrade fails on a version conflict with the project's own pins | Don't fight the pins: install it outside the project with `uv tool install lightning-sdk` and call `"$(uv tool dir --bin)/lightning"` |
| Installing is blocked (read-only env or home, agent sandbox) | Skip it and run each command as `UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" uvx lightning-sdk …` |
| Every call fails on SSL/certificates, even `lightning --version` (`Could not find a suitable TLS CA certificate bundle`), only inside an agent sandbox | A `**/*.pem` read-deny rule is hiding certifi's public CA bundle (`site-packages/certifi/cacert.pem`). Allow that one path; don't disable the sandbox |
`lightning api` flags: `-X` method, `-f key=val` string field, `-F key=val`
typed field, `-H` header, `--input <file>` request body (`--input -` to pipe
one), `-q` jq filter (needs the `jq` binary for `-q`), `-i` include response
headers, `--silent` no output. Fields with no `-X` make it a POST. Fields are JSON body for POST/PUT-with-body and **query
params** when the request also has `--input` or is a GET.
两种凭证都可用于**本skill中的所有调用**——无需生成token或额外的认证步骤。你可以从 lightning.ai 的用户/组织设置中获取密钥,或者通过命令 `lightning api-key create --org <org> --name artifacts` 创建。**切勿硬编码密钥**——请从环境变量中读取。如果要指向非生产环境的控制平面,请设置 `LIGHTNING_CLOUD_URL`(默认为 `https://lightning.ai`)。
本skill会使用Agent运行环境(用户的项目venv、conda环境等)中的Lightning CLI,若环境中没有则会安装到该环境中。之后所有地方都直接调用 `lightning …` 即可。如果安装过程不顺利,请参考下表:
| 症状 | 解决方法 |
|---|---|
| 两种安装方式都失败:没有激活的环境,或者 pip 以 `externally-managed-environment` 为由拒绝安装 | 改为单独安装:`uv tool install lightning-sdk`(或 `pipx install lightning-sdk`),如果该目录不在 `PATH` 中,则调用 `"$(uv tool dir --bin)/lightning"` |
| 安装后 `lightning --version` 仍然没有输出 `Lightning CLI version` 行 | 用 `command -v lightning` 查看当前运行的是哪个程序。可能是其他工具占用了这个命令名(PyTorch Lightning 也会安装 `lightning` 命令),或者你安装的环境不在 `PATH` 中:激活环境(`source .venv/bin/activate`)或者通过完整路径调用其 `bin/lightning` |
| 出现 `No such command`、`No such option` 或 `unexpected extra argument` 错误 | CLI版本低于本skill的要求:在 `command -v lightning` 指向的环境中执行 `uv pip install -U lightning-sdk`(或 `pip install -U lightning-sdk`);如果是uv tool安装的,则执行 `uv tool upgrade lightning-sdk` |
| 升级因与项目自身的依赖版本冲突而失败 | 不要强行修改依赖:用 `uv tool install lightning-sdk` 安装到项目外部,并调用 `"$(uv tool dir --bin)/lightning"` |
| 安装被阻止(只读环境或home目录、Agent沙箱) | 跳过安装,将每个命令改为 `UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" uvx lightning-sdk …` 的形式运行 |
| 即使是 `lightning --version` 也会因SSL/证书问题失败(`Could not find a suitable TLS CA certificate bundle`),且仅在Agent沙箱中出现 | 是 `**/*.pem` 读取拒绝规则隐藏了certifi的公共CA包(`site-packages/certifi/cacert.pem`)。允许该路径即可;不要禁用沙箱 |
`lightning api` 常用参数:`-X` 指定请求方法,`-f key=val` 传递字符串字段,`-F key=val` 传递类型化字段,`-H` 指定请求头,`--input <file>` 指定请求体(`--input -` 表示从管道读取),`-q` 指定jq过滤规则(`-q` 需要安装 `jq` 二进制文件),`-i` 包含响应头,`--silent` 不输出内容。如果没有指定 `-X` 但有字段参数,则默认是POST请求。对于POST/PUT且有请求体的情况,字段会作为JSON请求体;如果是GET请求或同时指定了 `--input`,则字段会作为**查询参数**。Resolve the teamspace (do this first)
解析 teamspace(请先执行此步骤)
Artifacts live in a teamspace (a "project" in the REST API). You need three
values: the owner name and teamspace name (for upload URLs)
and the project id (for the REST calls). Never guess. List memberships
and, if more than one fits and none is configured, ask the user which to
use:
lit://bash
lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'Capture the row's and resolve the owner's name. The membership
only carries the owner's id, and the lookup depends on :
projectIdownerTypebash
PID=<projectId-from-above>
TSNAME=<name-from-above>
OWNER_ID=<ownerId-from-above>
if [ "<ownerType-from-above>" = organization ]; then
OWNER=$(lightning api "/v1/orgs/$OWNER_ID" | jq -r .name)
else # a personal teamspace: yours, or another user's you were added to
OWNER=$(lightning api /v1/users/search -X GET -f "query=$OWNER_ID" \
| jq -r --arg id "$OWNER_ID" '.users[] | select(.id==$id) | .username')
fi
[ -n "$OWNER" ] && [ "$OWNER" != null ] || echo "could not resolve the owner of $TSNAME — ask the user" >&2Search by id and match on exactly (the search is fuzzy); this is the lookup
the SDK itself uses. Never fall back to your own username: a wrong owner in the
path uploads into a different teamspace.
.idlit://Teamspaces you can access through org-level permissions (rather than direct
membership) don't appear in — if the user names one you
can't find, ask them for the pair and the project id.
There is no list-projects-by-name endpoint ( isn't in the
API), so don't try to look it up.
/v1/memberships<owner>/<teamspace>/v1/projects?name=…Artifacts 存储在 teamspace 中(即 REST API 中的“project”)。你需要三个值:所有者名称和teamspace名称(用于 上传URL)以及项目ID(用于REST调用)。切勿猜测。 列出你拥有的成员身份,如果有多个符合条件且没有配置默认值,询问用户要使用哪一个:
lit://bash
lightning api /v1/memberships -q '.memberships[] | [.name, .projectId, .ownerType, .ownerId] | @tsv'获取对应行的 ,并解析所有者的名称。成员身份信息只包含所有者ID,查找方式取决于 :
projectIdownerTypebash
PID=<projectId-from-above>
TSNAME=<name-from-above>
OWNER_ID=<ownerId-from-above>
if [ "<ownerType-from-above>" = organization ]; then
OWNER=$(lightning api "/v1/orgs/$OWNER_ID" | jq -r .name)
else # a personal teamspace: yours, or another user's you were added to
OWNER=$(lightning api /v1/users/search -X GET -f "query=$OWNER_ID" \
| jq -r --arg id "$OWNER_ID" '.users[] | select(.id==$id) | .username')
fi
[ -n "$OWNER" ] && [ "$OWNER" != null ] || echo "could not resolve the owner of $TSNAME — ask the user" >&2通过ID搜索并精确匹配 (搜索是模糊的);这也是SDK自身使用的查找方式。切勿回退到使用你自己的用户名: 路径中的所有者错误会导致文件上传到错误的 teamspace 中。
.idlit://通过组织级权限访问的 teamspace(而非直接成员身份)不会出现在 中——如果用户指定了一个你找不到的 teamspace,请向用户询问 对和项目ID。目前没有按名称列出项目的接口(API中不存在 ),所以不要尝试这样查找。
/v1/memberships<owner>/<teamspace>/v1/projects?name=…Publish a durable link (the CLI flow)
发布持久化链接(CLI 流程)
A public link (, the default below) needs the user's say-so in this request.
"Publish this" or "get me a public link" is authorization — don't ask twice. "Send this to the
team" is not: say what the link exposes and get a yes, or use .
private=false-F private=trueThree calls: the file into the drive, read back
which storage cluster it landed on, then register the object as a shared
artifact. Copy-paste function:
lightning cpartifacts/bash
undefined公开链接(,即下文的默认值)需要用户在本次请求中明确同意。 “发布这个”或者“给我一个公开链接”就算是授权——不需要重复询问。“把这个发给团队”则不算:需要说明链接会暴露什么内容并获得用户同意,或者使用 。
private=false-F private=true总共三次调用:用 将文件上传到 驱动器,读取文件落地的存储集群,然后将该对象注册为共享artifact。可直接复制使用的函数:
lightning cpartifacts/bash
undefinedshare <local-file> [remote-name] [content-type]
share <local-file> [remote-name] [content-type]
Pretty status goes to stderr; the bare URL is the only thing on stdout, so
Pretty status goes to stderr; the bare URL is the only thing on stdout, so
URL=$(share file.html) captures cleanly while interactive use looks like:
URL=$(share file.html) captures cleanly while interactive use looks like:
✅ Published report.html (text/html; charset=utf-8)
✅ Published report.html (text/html; charset=utf-8)
share() {
local FILE="$1" NAME="${2:-$(basename "$1")}" CT="${3:-$(file -b --mime-type "$1")}"
local KEY="artifacts/${NAME#artifacts/}" # publish only finds objects under artifacts/
1. upload; the server picks where to store it (see Gotchas)
lightning cp "$FILE" "lit://$OWNER/$TSNAME/$KEY" >&2 || return 1
2. the blob's clusterId from the listing is the storage cluster the
publish call needs (see Gotchas — it is not always the cluster the
upload went through)
local CLUSTER; CLUSTER=$(lightning ls --json "lit://$OWNER/$TSNAME/$KEY" | jq -r '.[0].clusterId')
3. register it -> durable, no-expiry lightning.ai/artifacts/<id>
local LINK; LINK=$(lightning api "/v1/projects/$PID/shared-artifacts" -X POST
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
share report.html # -> https://lightning.ai/artifacts/art_...
share dashboard.html reports/dash.html text/html # custom remote name + explicit type
When you publish something for the user, always show them the full URL on its
own line (terminals make it clickable) — never just say "done".
The upload path and the publish `filename` must point at the same object — the
`KEY` variable keeps them identical. The server confines shares to the
`artifacts/` folder; if you pass a bare `filename` (no `artifacts/` prefix) to
publish it prepends one, but matching the two explicitly is clearest.
Set `-F private=true` to require an authorized project reader to open the link
(good for internal-only shares); the default `false` is genuinely public.share() {
local FILE="$1" NAME="${2:-$(basename "$1")}" CT="${3:-$(file -b --mime-type "$1")}"
local KEY="artifacts/${NAME#artifacts/}" # publish only finds objects under artifacts/
1. upload; the server picks where to store it (see Gotchas)
lightning cp "$FILE" "lit://$OWNER/$TSNAME/$KEY" >&2 || return 1
2. the blob's clusterId from the listing is the storage cluster the
publish call needs (see Gotchas — it is not always the cluster the
upload went through)
local CLUSTER; CLUSTER=$(lightning ls --json "lit://$OWNER/$TSNAME/$KEY" | jq -r '.[0].clusterId')
3. register it -> durable, no-expiry lightning.ai/artifacts/<id>
local LINK; LINK=$(lightning api "/v1/projects/$PID/shared-artifacts" -X POST
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
-f clusterId="$CLUSTER" -f filename="$KEY" -f contentType="$CT" -F private=false -q .url | tr -d '"') echo "✅ Published $NAME ($CT)" >&2 printf '🔗 ' >&2 echo "$LINK" }
share report.html # -> https://lightning.ai/artifacts/art_...
share dashboard.html reports/dash.html text/html # custom remote name + explicit type
当你为用户发布内容时,一定要单独占一行显示完整的URL(终端中会自动变成可点击链接)——不要只说“完成了”。
上传路径和发布时的 `filename` 必须指向同一个对象——`KEY` 变量保证了两者一致。服务器会将共享限制在 `artifacts/` 文件夹内;如果你给发布接口传递的是裸 `filename`(没有 `artifacts/` 前缀),它会自动加上,但显式保持两者一致是最清晰的做法。
设置 `-F private=true` 可以要求链接必须由授权的项目读者才能打开(适合内部共享);默认值 `false` 表示完全公开。Content types that render inline
可内联渲染的内容类型
file -b --mime-typecontentType| File | Content-Type |
|---|---|
| |
| |
| |
| |
| |
| anything to force-download | |
file -b --mime-typecontentType| 文件类型 | Content-Type |
|---|---|
| |
| |
| |
| |
| |
| 任何需要强制下载的文件 | |
List, see what's published, unpublish, delete
列出、查看已发布内容、取消发布、删除
List what's in the drive with — one level by default,
for every file underneath, for entries with and the
the publish call needs. Listings follow the server's pages
automatically, so folders with many thousands of files come back complete:
lightning ls-r--jsonsizeclusterIdbash
lightning ls "lit://$OWNER/$TSNAME/artifacts/" # one level; folders end in /
lightning ls -r "lit://$OWNER/$TSNAME/artifacts/reports" # full relative file paths
lightning ls --json "lit://$OWNER/$TSNAME/artifacts/reports"List every published link in the project (,
newest first — id, filename, content type, public/private, download count, URL):
GET /v1/projects/{pid}/shared-artifactsbash
undefined用 列出驱动器中的内容——默认只显示一级, 递归显示所有子文件, 输出包含 和发布调用所需的 的条目。列表会自动处理服务器的分页,因此包含数千个文件的文件夹也能完整返回:
lightning ls-r--jsonsizeclusterIdbash
lightning ls "lit://$OWNER/$TSNAME/artifacts/" # one level; folders end in /
lightning ls -r "lit://$OWNER/$TSNAME/artifacts/reports" # full relative file paths
lightning ls --json "lit://$OWNER/$TSNAME/artifacts/reports"列出项目中所有已发布的链接(,按最新排序——包含ID、文件名、内容类型、公开/私有、下载次数、URL):
GET /v1/projects/{pid}/shared-artifactsbash
undefinedshares -> one block per published artifact
shares -> one block per published artifact
shares() {
lightning api "/v1/projects/$PID/shared-artifacts" | jq -r '.artifacts // [] | .[] |
"(if .private then "🔒" else "🌐" end) (.filename) · ⬇ (.downloads // 0) · (.createdAt // "")
id: (.id)
🔗 (.url)"'
}
**Unpublish** (revoke the link; the file itself stays in the drive):
```bashshares() {
lightning api "/v1/projects/$PID/shared-artifacts" | jq -r '.artifacts // [] | .[] |
"(if .private then "🔒" else "🌐" end) (.filename) · ⬇ (.downloads // 0) · (.createdAt // "")
id: (.id)
🔗 (.url)"'
}
**取消发布**(撤销链接;文件本身仍保留在驱动器中):
```bashunshare <artifact-id>
unshare <artifact-id>
unshare() {
lightning api "/v1/projects/$PID/shared-artifacts/$1" -X DELETE --silent
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
unshare art_01kxgaep54zzs84arfns1j21wd
**Delete the file itself** (after unpublishing, or to clean up an abandoned
upload) — no cluster id needed; the server removes it wherever it is stored:
```bash
lightning rm "lit://$OWNER/$TSNAME/artifacts/report.html"
lightning rm -r "lit://$OWNER/$TSNAME/artifacts/reports" # a folder and everything under itrm-f-rRe-publish the same object later (new id, new URL) by repeating the publish call
with the same . Update the contents behind an existing link by
re-running to the same — published ids keep
serving the new bytes. To change the served Content-Type, publish again.
filenamelightning cpartifacts/<name>unshare() {
lightning api "/v1/projects/$PID/shared-artifacts/$1" -X DELETE --silent
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
&& echo "🗑️ Unpublished $1 — link is dead, file kept in the drive" >&2 }
unshare art_01kxgaep54zzs84arfns1j21wd
**删除文件本身**(取消发布后,或者清理废弃的上传文件)——不需要集群ID;服务器会从存储它的任何位置删除:
```bash
lightning rm "lit://$OWNER/$TSNAME/artifacts/report.html"
lightning rm -r "lit://$OWNER/$TSNAME/artifacts/reports" # a folder and everything under it如果路径不存在, 会失败(传 可忽略错误),并且如果没有 参数,它会拒绝删除文件夹。
rm-f-r之后可以通过重复使用相同 调用发布接口来重新发布同一个对象(会生成新的ID和URL)。如果要更新现有链接背后的内容,只需重新执行 到同一个 路径——已发布的ID会继续提供新的文件内容。如果要修改提供的Content-Type,重新发布一次即可。
filenamelightning cpartifacts/<name>Example workflows
示例工作流
Prompts this skill handles: "share this HTML report as a permanent link",
"give me a public URL for output.pdf", "publish this one-pager so I can send
it", "drop this file somewhere CI can curl it".
Share an agent-generated HTML one-pager (renders in the browser, no login):
bash
share summary.html # hand the printed URL to anyonePublish a folder of reports, one link each ( prints each name + URL):
sharebash
for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; doneHand a file to another service / CI job:
bash
URL=$(share model-metrics.json)本skill可处理的提示词示例:"share this HTML report as a permanent link",
"give me a public URL for output.pdf", "publish this one-pager so I can send
it", "drop this file somewhere CI can curl it".
分享Agent生成的HTML单页文档(在浏览器中渲染,无需登录):
bash
share summary.html # hand the printed URL to anyone发布一整个文件夹的报告,每个文件一个链接( 会打印每个文件名和对应的URL):
sharebash
for f in out/*.html; do share "$f" "reports/$(basename "$f")" "text/html; charset=utf-8"; done把文件交给其他服务/CI任务使用:
bash
URL=$(share model-metrics.json)elsewhere: curl -sL "$URL" -o metrics.json
elsewhere: curl -sL "$URL" -o metrics.json
undefinedundefinedGotchas
注意事项
- Publish wants the blob's storage cluster, not the cluster the upload
went through. A teamspace can be bound to compute clusters that store
their files under a parent cluster's bucket; publishing with such a compute
cluster's id fails with HTTP 500. The artifacts tree listing reports each
blob's real — always read it from there (the
clusterIdfunction does). Deletes don't take a cluster at all.share - needs no cluster flag — the server picks the storage. Only if it rejects the upload for a missing cluster does
lightning cpchoose one itself (cpfirst, which is set inside a Studio, then the teamspace's only or default cloud account) and warnLIGHTNING_CLUSTER_IDPassNo cloud account specified. Using cloud account: <id>.only to steer placement deliberately, and pick a cluster whose--cloud-account <id>isstatus.phase(CLUSTER_STATE_RUNNING) — bound-but-unusable clusters make the upload fail with a drive error that says nothing about cluster health./v1/projects/$PID/clusters - Unpublish reports success for links that don't exist.
returns
DELETE /v1/projects/{pid}/shared-artifacts/{id}withHTTP 200for an id that was already revoked or simply mistyped — do not treat exit code 0 as proof; verify by checking the public URL 404s. ({}, by contrast, fails on a missing path unless you passlightning rm.)-f - The served HTML is not byte-identical to what you uploaded. Cloudflare injects a
Browser-Insights RUM beacon () into HTML responses — a ~350-byte delta. Harmless for viewing, but don't promise a bit-exact document, and don't checksum the response against the source file.
static.cloudflareinsights.com/beacon.min.js - Shares are confined to the folder. Publish only finds objects under
artifacts/, so the upload must targetprojects/{pid}/artifacts/.... Files underlit://<owner>/<teamspace>/artifacts/...oruploads/are reachable withlightning_storage/too, but publish won't find them there.lightning cp - Content-Type is set at publish time, not upload time — the serving handler
uses the shared-artifact record's , overriding the stored object. Set it on the publish call so HTML/PDF render inline.
contentType - The public link is genuinely open — anyone with it can fetch the file with no
auth, and revoking later doesn't recall a link someone already opened. Use
for anything you don't want world-readable, and confirm a public one with the user first.
-F private=true - (jq filtering) and the
-q/sharehelpers need thesharesbinary installed; without it, parse the JSON yourself.jq - The list endpoint is newer than the rest. returns HTTP 501 "Method Not Allowed" on control planes built before mid-July 2026 — publish/unpublish still work there; only
GET /v1/projects/{pid}/shared-artifactsis affected.shares
- 发布需要的是blob的存储集群ID,而不是上传经过的集群ID。 一个 teamspace 可以绑定到多个计算集群,这些计算集群的文件存储在父集群的存储桶下;如果使用计算集群的ID进行发布,会返回HTTP 500错误。Artifacts目录列表会返回每个blob的真实 ——一定要从那里读取(
clusterId函数就是这么做的)。删除操作完全不需要集群ID。share - 不需要指定集群参数——服务器会自动选择存储位置。只有当服务器因缺少集群而拒绝上传时,
lightning cp才会自己选择一个(优先使用cp,Studio中会自动设置这个变量,否则使用teamspace的唯一或默认云账户),并发出警告LIGHTNING_CLUSTER_ID。只有当你需要主动控制存储位置时才传No cloud account specified. Using cloud account: <id>.,并且要选择--cloud-account <id>为status.phase的集群(可通过CLUSTER_STATE_RUNNING查询)——绑定但不可用的集群会导致上传失败,并返回一个完全不提及集群健康状态的驱动器错误。/v1/projects/$PID/clusters - 取消发布对不存在的链接也会返回成功。 对于已经撤销的ID或者打错的ID,会返回
DELETE /v1/projects/{pid}/shared-artifacts/{id}和空对象HTTP 200——不要把退出码0当作成功的证明;可以通过检查公开URL返回404来验证。(相比之下,{}在路径不存在时会失败,除非你传了lightning rm。)-f - 返回的HTML内容和你上传的不是字节完全一致的。 Cloudflare会在HTML响应中注入Browser-Insights RUM信标()——大约有350字节的差异。对于查看来说没有影响,但不要承诺文件是逐位完全一致的,也不要用响应的校验和与源文件对比。
static.cloudflareinsights.com/beacon.min.js - 共享文件仅限于 文件夹内。 发布接口只会查找
artifacts/下的对象,因此上传必须指向projects/{pid}/artifacts/...路径。lit://<owner>/<teamspace>/artifacts/...或uploads/下的文件也可以用lightning_storage/访问,但发布接口找不到它们。lightning cp - Content-Type是在发布时设置的,而非上传时——服务处理程序使用共享artifact记录中的 ,覆盖存储对象的原有类型。请在发布调用时设置它,这样HTML/PDF才能内联渲染。
contentType - 公开链接是完全开放的——任何拿到链接的人都可以无需认证获取文件,而且之后撤销链接也无法收回已经被人打开过的文件。对于不想让全世界都能读取的内容,请使用 ,并且公开链接一定要先和用户确认。
-F private=true - (jq过滤)和
-q/share辅助函数需要安装shares二进制文件;如果没有,请自己解析JSON。jq - 列表接口比其他接口更新。 在2026年7月中旬之前构建的控制平面上,会返回HTTP 501 "Method Not Allowed"——发布和取消发布功能仍然可用,只有
GET /v1/projects/{pid}/shared-artifacts列表功能受影响。shares