managing-streamlit-apps

管理 Streamlit 应用

Streamlit 应用是在 PostHog 内部隔离沙箱中运行的 Python 数据应用。 每个应用的代码版本都是不可变的；其中一个版本处于活动状态；沙箱进程为活动版本提供服务。 整个生命周期由 streamlit-apps-* MCP 工具驱动。

标准流程：创建 → 设置源代码 → 启动 → 分享

1. 使用 streamlit-apps-create，并提供 name（可选提供 description、cpu_cores 0.25–8、memory_gb 0.5–16，默认值为 0.5 / 1）。 应用已创建，但尚无代码。
2. 使用 streamlit-apps-set-source，并将完整的 app.py 源代码作为一个字符串传入。 额外文件也可在同一次调用中一并传入：files 将项目相对路径映射到文本（辅助模块、CSV、JSON），assets 将路径映射到 base64（Parquet、图像）。 这会创建版本 1 并将其设为活动版本。 请按照 writing-streamlit-apps 技能编写源代码——尤其要使用 posthog_apps.query() 查询 PostHog 数据，绝不要 import posthog。
3. 使用 streamlit-apps-start。 它会立即返回；沙箱随后异步启动。
4. 轮询 streamlit-apps-status，直到 status 为 running（通常不到一分钟）。 如果状态变为 error，请查看 last_error——参见下文的故障排除。
5. 分享应用：create/get/start 返回的 _posthogUrl（/streamlit-apps/{short_id}）是应用在 PostHog 中的页面。 将此链接分享给其他人。 查看者需要登录 PostHog 并拥有项目访问权限（应用会在经过身份验证的 iframe 中呈现；没有公开 URL）。

应用读取谁的数据

应用查询使用活动版本作者的数据访问权限运行——由你设置源代码，应用就能读取你能读取的数据。 任何能查看应用的人都能看到查询结果，因此发布应用就意味着与项目中的所有人共享这些数据。 如果版本作者后来被删除，该应用便无法启动；请上传新版本以解决此问题。

更新代码

分两步修改现有应用，避免用旧副本覆盖较新的工作：

1. streamlit-apps-get-source 会读取活动版本（也可通过 version_number 指定较旧版本）。 它会返回 version_number、所有文件的清单，以及每个文本文件的内容。 二进制文件不会显示内容。 对于大型应用，可传入 paths（逗号分隔）以仅读取所需文件。
2. 使用 streamlit-apps-edit-source，并将 base_version 设置为该 version_number。 file_edits 保存每个文件中精确的 old → new 文本替换，create_files 添加新的文本文件，delete_files 删除文件。 每个 old 都必须恰好匹配一次，因此请包含足够的上下文行，确保匹配结果唯一。 未修改的文件在新版本中会逐字节保持不变。

如果读取后活动版本发生变化，edit-source 会返回 409 和 current_version。 如果另一个会话发布了新版本，或者有人将应用回滚到了较旧版本，就会出现这种情况。 请重新读取 current_version，并在此版本上重做编辑。 不要改用 set-source 强行覆盖。

对于新应用或完全重写，请使用 streamlit-apps-set-source。 它会替换所有文件，因此也要再次传入 files 和 assets；一个版本只包含本次调用传入的内容。

这两种工具都会创建并激活下一个版本。 运行中的沙箱会被停止，以免继续提供过期代码——之后请调用 streamlit-apps-start 来运行新版本。 版本不可变，但并非永久保留：streamlit-apps-versions 会列出最新的 50 个版本，超过 30 天的非活动版本及其代码会被删除。 没有回滚工具：要回滚，请使用 streamlit-apps-get-source 读取旧版本，再使用 set-source 设置其文件。 二进制资源不会内联在其中，因此回滚带有资源的应用时，还需要保存这些文件的副本。

停止、闲置和删除

• streamlit-apps-stop 会停止沙盒；代码和版本不会受到影响。之后重新启动的成本很低。
• 闲置沙盒在一段时间没有活动后会自动停止 — 应用已停止是正常现象，并非错误。需要时重新启动即可。
• streamlit-apps-delete 会停止任何沙盒并软删除应用。删除本次对话中不是由你创建的内容前，请先向用户确认。

故障排除

• status: error 且 last_error: "Start failed: ..." — 沙盒预配或启动失败。重试一次 streamlit-apps-start；如果问题仍然存在，请向用户说明 last_error（预配失败通常是平台端问题，而非应用端问题）。
• 工具调用返回 403 "Streamlit apps is not available." — 此组织的 streamlit-apps 功能标志已关闭。这是发布门槛，无法通过修复解决；请告知用户。
• 应用可以运行，但其中的查询失败 — 这是应用代码问题；请参阅 writing-streamlit-apps（桥接限制：每个查询执行时间为 30s，内存为 256 MB）。
• 执行 set-source 后应用仍显示旧代码 — 你跳过了“set-source 后启动”这一步；沙盒已停止，需要重新启动。

重命名和调整大小

streamlit-apps-update 可以更改应用的名称、描述、cpu_cores（0.25–8）或 memory_gb（0.5–16）；只会更改你传入的字段。 新的规格会在下次启动沙盒时生效，因此调整正在运行的沙盒后，请先停止再启动。 默认配置（0.5 CPU / 1 GB）适用于常见的仪表板应用。 仅当应用本身会在内存中保存大型 DataFrame 时才提高 memory_gb — HogQL 桥接查询的上限为 256 MB，由服务器端限制，且不会随沙盒规格变化，因此更大的沙盒无法解决查询失败问题。