secubox-openwrt/package/secubox/secubox-app-streamlit-launcher/README.zh.md

English | Francais | 中文

SecuBox Streamlit Launcher

带空闲关闭和内存管理的按需 Streamlit 应用启动器。

概述

Streamlit Launcher 通过以下方式优化受限设备的资源使用：

• 按需启动应用 - 首次访问时启动（延迟加载）
• 停止空闲应用 - 在可配置的超时后停止（默认：30 分钟）
• 管理内存压力 - 内存不足时停止低优先级应用
• 优先级系统 - 让关键应用运行更长时间

架构

+-------------+     +--------------+     +-----------------+
|   HAProxy   |---->|  mitmproxy   |---->| Streamlit       |
|   (vhost)   |     |  (WAF+track) |     | Launcher Daemon |
+-------------+     +--------------+     +--------+--------+
                           |                      |
                    跟踪访问               启动/停止
                           |                      |
                    +------v------+         +-----v-----+
                    | /tmp/access |         |  slforge  |
                    |   (touch)   |         |  start/   |
                    +-------------+         |   stop    |
                                            +-----------+

安装

opkg install secubox-app-streamlit-launcher

CLI 参考

# 显示状态
streamlit-launcherctl status

# 列出所有应用及详情
streamlit-launcherctl list

# 手动启动/停止应用
streamlit-launcherctl start <app>
streamlit-launcherctl stop <app>

# 设置应用优先级（越高 = 运行时间越长）
streamlit-launcherctl priority <app> <value>

# 设置始终运行（永不自动停止）
streamlit-launcherctl priority <app> 100 1

# 手动运行空闲检查
streamlit-launcherctl check

# 运行内存压力检查
streamlit-launcherctl check-memory

配置

编辑 /etc/config/streamlit-launcher：

config global 'global'
    # 启用 launcher 守护进程
    option enabled '1'

    # 启用按需启动（相对于始终运行）
    option on_demand '1'

    # 停止应用前的不活动分钟数
    option idle_timeout '30'

    # 空闲检查间隔秒数
    option check_interval '60'

    # 强制停止应用前的最小可用内存（MB）
    option memory_threshold '100'

    # 等待应用启动的最大秒数
    option startup_timeout '30'

# 应用优先级（越高 = 运行时间越长）
config priority 'control'
    option app 'control'
    option value '100'
    option always_on '1'

config priority 'ytdownload'
    option app 'ytdownload'
    option value '30'

优先级系统

优先级	行为
100 + always_on	永不自动停止
80-99	内存压力时最后停止
50（默认）	正常优先级
1-49	内存压力时最先停止

与 slforge 集成

launcher 与 slforge（Streamlit Forge）协同工作：

• slforge 管理应用配置、创建和基本启动/停止
• streamlit-launcherctl 添加按需和空闲管理

启用按需模式时：

1. 用户访问 https://app.example.com
2. HAProxy 路由到 mitmproxy
3. 如果应用已停止，mitmproxy 可通过 hook 触发启动
4. Launcher 启动应用并等待就绪
5. 请求被处理
6. 记录访问
7. 空闲超时后，应用被停止

访问跟踪

launcher 通过 /tmp/streamlit-access/ 中的 touch 文件跟踪应用访问：

# 跟踪访问（重置空闲计时器）
streamlit-launcherctl track <app>

# 或直接
touch /tmp/streamlit-access/<app>

可通过以下方式触发：

• mitmproxy 请求 hook
• HAProxy 健康检查脚本
• 解析访问日志的 cron 任务

内存管理

当可用内存低于阈值时：

1. 应用按优先级排序（最低优先）
2. 低优先级应用逐个停止
3. 当内存恢复到阈值以上时停止
4. 始终运行的应用永不停止

服务控制

# 启用/启动守护进程
/etc/init.d/streamlit-launcher enable
/etc/init.d/streamlit-launcher start

# 检查守护进程状态
/etc/init.d/streamlit-launcher status

# 查看日志
logread -e streamlit-launcher

文件

路径	描述
/usr/sbin/streamlit-launcherctl	CLI 工具
/etc/config/streamlit-launcher	UCI 配置
/etc/init.d/streamlit-launcher	Procd init 脚本
/tmp/streamlit-access/	访问跟踪文件
/usr/share/streamlit-launcher/loading.html	加载页面模板

示例：优化低内存环境

# 设置激进的超时（10 分钟）
uci set streamlit-launcher.global.idle_timeout='10'

# 降低内存阈值（150MB 可用时触发清理）
uci set streamlit-launcher.global.memory_threshold='150'

# 让 dashboard 始终运行
streamlit-launcherctl priority dashboard 100 1

# 降低重型应用的优先级
streamlit-launcherctl priority jupyter 20
streamlit-launcherctl priority analytics 30

uci commit streamlit-launcher
/etc/init.d/streamlit-launcher restart