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

English | Francais | 中文

Streamlit Forge

SecuBox 的 Streamlit 应用发布平台。

概述

Streamlit Forge 是一个用于创建、管理和发布 Streamlit 应用的综合平台。从模板创建应用、管理实例、通过 HAProxy 使用 SSL 暴露服务，并发布到 SecuBox mesh 目录。

功能特性

• 应用模板 - Basic、Dashboard、Data-Viewer 入门模板
• 实例管理 - 启动、停止、重启应用实例
• 端口分配 - 自动端口分配
• HAProxy 集成 - 一条命令完成 vhost + SSL 暴露
• Mesh 发布 - 在 SecuBox mesh 网络中共享应用
• UCI 配置 - 持久化应用设置

安装

opkg install secubox-app-streamlit-forge

CLI 使用方法

# 应用管理
slforge create <name> [options]
  --from-template <tpl>   # 使用模板 (basic, dashboard, data-viewer)
  --from-upload <zip>     # 从 ZIP 文件创建
  --from-git <url>        # 从 Git 仓库克隆

slforge list              # 列出所有应用
slforge info <app>        # 显示应用详情
slforge delete <app>      # 删除应用

# 实例控制
slforge start <app>       # 启动应用实例
slforge stop <app>        # 停止应用实例
slforge restart <app>     # 重启应用
slforge status [app]      # 显示状态
slforge logs <app> [-f]   # 查看日志

# 配置
slforge config <app> list         # 列出配置
slforge config <app> get <key>    # 获取值
slforge config <app> set <k> <v>  # 设置值

# 发布
slforge expose <app> [--domain <d>]  # 创建 vhost + SSL
slforge hide <app>                   # 移除公共访问
slforge publish <app>                # 添加到 mesh 目录
slforge unpublish <app>              # 从 mesh 移除

# Launcher 集成（按需启动）
slforge launcher status              # 显示 launcher 状态
slforge launcher priority <app> <n>  # 设置应用优先级 (1-100)
slforge launcher always-on <app>     # 标记为始终运行

# 模板
slforge templates         # 列出可用模板

示例工作流

# 1. 从 dashboard 模板创建应用
slforge create mydashboard --from-template dashboard

# 2. 启动应用
slforge start mydashboard
# URL: http://192.168.255.1:8501

# 3. 使用 SSL 暴露
slforge expose mydashboard --domain mydashboard.gk2.secubox.in

# 4. 发布到 mesh 目录
slforge publish mydashboard

模板

Basic

带侧边栏和两列布局的最小 Streamlit 应用。

Dashboard

多页面仪表板，包含：

• 带增量指示器的指标卡片
• 折线图和面积图
• 带 CSV 导出的数据表
• 设置页面

Data-Viewer

CSV/Excel 数据浏览器，包含：

• 文件上传（CSV、XLSX）
• 动态列过滤
• 直方图和散点图
• 统计摘要
• 相关性矩阵

配置

UCI 配置：/etc/config/streamlit-forge

config forge 'main'
    option enabled '1'
    option gitea_url 'http://127.0.0.1:3000'
    option gitea_org 'streamlit-apps'
    option apps_dir '/srv/streamlit/apps'
    option previews_dir '/srv/streamlit/previews'
    option base_domain 'apps.secubox.in'
    option default_port_start '8501'
    option default_memory '512M'

config app 'myapp'
    option name 'myapp'
    option enabled '1'
    option port '8501'
    option entrypoint 'app.py'
    option memory '512M'
    option domain 'myapp.gk2.secubox.in'

应用目录结构

/srv/streamlit/apps/<app>/
|-- src/                  # 应用源代码
|   |-- app.py           # Streamlit 主入口
|   |-- requirements.txt # Python 依赖
|   +-- ...
|-- data/                # 持久化数据
+-- config.json          # 运行时配置

LuCI 界面

安装 luci-app-streamlit-forge 获取 服务 > Streamlit Forge 的 Web 界面。

功能：

• 状态仪表板（运行中/总应用数、LXC 状态）
• 带模板选择的创建应用对话框
• 应用表格，支持启动/停止/打开/暴露/发布/删除
• 自动刷新轮询

运行时

应用在 streamlit LXC 容器内运行：

• 应用挂载在容器内的 /srv/apps/
• 预装 Streamlit 的 Python virtualenv
• 端口转发到主机网络

依赖

• python3, python3-pip
• lxc, lxc-common
• jsonfilter

文件位置

路径	描述
/etc/config/streamlit-forge	UCI 配置
/usr/sbin/slforge	CLI 工具
/srv/streamlit/apps/	应用源目录
/srv/streamlit/previews/	生成的预览
/usr/share/streamlit-forge/templates/	应用模板
/var/run/streamlit-*.pid	PID 文件
/var/log/streamlit-*.log	应用日志

Mesh 目录清单

发布的应用会在 /usr/share/secubox/plugins/catalog/ 创建清单：

{
  "id": "streamlit-myapp",
  "name": "myapp",
  "type": "streamlit-app",
  "version": "1.0.0",
  "category": "apps",
  "runtime": "streamlit",
  "actions": {
    "start": "slforge start myapp",
    "stop": "slforge stop myapp"
  }
}

按需 Launcher

安装 secubox-app-streamlit-launcher 进行资源优化：

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

Launcher 命令

# 检查 launcher 状态
slforge launcher status

# 设置应用优先级（越高 = 运行时间越长，最大 100）
slforge launcher priority myapp 75

# 标记为始终运行（永不自动停止）
slforge launcher always-on dashboard

优先级级别

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

工作原理

1. 用户访问 https://app.example.com
2. 如果应用已停止，launcher 按需启动
3. 记录应用访问时间
4. 空闲超时后，应用自动停止
5. 内存压力触发低优先级应用关闭

完整配置请参阅 secubox-app-streamlit-launcher README。

模块清单 (NFO)

应用可以包含 README.nfo 清单文件，包含以下元数据：

• 身份 - 名称、版本、作者、许可证
• 分类 - 类别、关键词、标签
• 运行时 - 端口、内存、依赖
• 动态 - 用于生成内容集成的 AI 上下文

NFO 命令

# 为现有应用生成 README.nfo
slforge nfo init myapp

# 查看 NFO 摘要
slforge nfo info myapp

# 编辑清单
slforge nfo edit myapp

# 验证清单
slforge nfo validate myapp

# 导出为 JSON（用于 API）
slforge nfo json myapp

# 从带 NFO 的目录安装应用
slforge nfo install /path/to/myapp

NFO 文件结构

[identity]
id=myapp
name=My Application
version=1.0.0
author=CyberMind

[description]
short=系统指标仪表板
long=<<EOF
多行详细描述...
EOF

[tags]
category=administration
keywords=dashboard,monitoring,metrics

[runtime]
type=streamlit
port=8501
memory=512M

[dynamics]
prompt_context=<<EOF
此应用显示系统指标。
用户可以请求图表或数据导出。
EOF
capabilities=data-visualization,export
input_types=api,json
output_types=charts,tables,csv

捆绑安装器

应用可以包含读取 NFO 的 install.sh：

# 从目录安装
cd /path/to/myapp
./install.sh

# 或使用 slforge
slforge nfo install /path/to/myapp

完整规范请参阅 /usr/share/streamlit-forge/NFO-SPEC.md。

生成式 AI 集成

[dynamics] 部分为 AI 助手提供上下文：

[dynamics]
prompt_context=<<EOF
此应用是数据可视化仪表板。
它可以显示图表、表格并导出数据。
可用数据：CPU、内存、网络指标。
EOF

capabilities=data-visualization,real-time-updates,export
input_types=json,api,prometheus
output_types=charts,tables,csv,pdf

AI 系统可以读取此上下文以了解应用的功能以及如何协助用户。

文件位置

路径	描述
/etc/config/streamlit-forge	UCI 配置
/usr/sbin/slforge	CLI 工具
/srv/streamlit/apps/	应用源目录
/srv/streamlit/apps/<app>/README.nfo	应用清单
/srv/streamlit/previews/	生成的预览
/usr/share/streamlit-forge/templates/	应用模板
/usr/share/streamlit-forge/lib/nfo-parser.sh	NFO 解析器库
/usr/share/streamlit-forge/nfo-template.nfo	NFO 模板
/usr/share/streamlit-forge/install.sh	捆绑安装器
/var/run/streamlit-*.pid	PID 文件
/var/log/streamlit-*.log	应用日志