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

SecuBox Streamlit Platform

Languages: English | Francais | 中文

适用于 OpenWrt 的多实例 Streamlit 托管平台，支持 LXC 容器和 Gitea 集成。

功能特性

• 多实例支持：在不同端口运行多个 Streamlit 应用
• 基于文件夹的应用：每个应用在独立目录中包含其依赖
• Gitea 集成：直接从 Gitea 仓库克隆和同步应用
• LXC 隔离：应用在隔离的 Alpine Linux 容器中运行
• 自动依赖安装：自动处理 requirements.txt

快速开始

1. 安装并启用

opkg install secubox-app-streamlit
/etc/init.d/streamlit enable
streamlitctl install

2. 创建您的第一个应用

streamlitctl app create myapp
streamlitctl instance add myapp 8502
/etc/init.d/streamlit restart

访问：http://<device-ip>:8502

从 Gitea 部署

该平台与 Gitea 集成，支持版本控制的应用部署。

配置 Gitea 凭证

# 配置 Gitea 连接
uci set streamlit.gitea.enabled=1
uci set streamlit.gitea.url='http://192.168.255.1:3000'
uci set streamlit.gitea.user='admin'
uci set streamlit.gitea.token='your-access-token'
uci commit streamlit

# 在容器中存储 git 凭证
streamlitctl gitea setup

从 Gitea 仓库克隆应用

方法 1：使用 streamlitctl（推荐）

# 使用仓库简写克隆（用户/仓库）
streamlitctl gitea clone yijing CyberMood/yijing-oracle

# 在指定端口添加实例
streamlitctl instance add yijing 8505

# 重启以应用更改
/etc/init.d/streamlit restart

方法 2：手动克隆 + UCI 配置

# 直接克隆到 apps 目录
git clone http://192.168.255.1:3000/CyberMood/yijing-oracle.git /srv/streamlit/apps/yijing

# 在 UCI 中注册
uci set streamlit.yijing=app
uci set streamlit.yijing.name='Yijing Oracle'
uci set streamlit.yijing.path='yijing/app.py'
uci set streamlit.yijing.enabled='1'
uci set streamlit.yijing.port='8505'
uci commit streamlit

# 添加实例并重启
streamlitctl instance add yijing 8505
/etc/init.d/streamlit restart

从 Gitea 更新应用

# 拉取最新更改
streamlitctl gitea pull yijing

# 重启以应用更改
/etc/init.d/streamlit restart

应用文件夹结构

每个应用位于 /srv/streamlit/apps/<appname>/：

/srv/streamlit/apps/myapp/
├── app.py              # 主入口点（或 main.py、<appname>.py）
├── requirements.txt    # Python 依赖（自动安装）
├── .streamlit/         # 可选的 Streamlit 配置
│   └── config.toml
└── ...                 # 其他文件（pages/、data/ 等）

主文件检测顺序：app.py > main.py > <appname>.py > 第一个 .py 文件

CLI 参考

容器管理

streamlitctl install      # 设置 LXC 容器
streamlitctl uninstall    # 移除容器（保留应用）
streamlitctl update       # 更新 Streamlit 版本
streamlitctl status       # 显示平台状态
streamlitctl logs [app]   # 查看日志
streamlitctl shell        # 打开容器 shell

应用管理

streamlitctl app list                    # 列出所有应用
streamlitctl app create <name>           # 创建新的应用文件夹
streamlitctl app delete <name>           # 删除应用
streamlitctl app deploy <name> <path>    # 从路径/归档部署

实例管理

streamlitctl instance list               # 列出实例
streamlitctl instance add <app> <port>   # 添加实例
streamlitctl instance remove <name>      # 移除实例
streamlitctl instance start <name>       # 启动单个实例
streamlitctl instance stop <name>        # 停止单个实例

Gitea 集成

streamlitctl gitea setup                 # 配置 git 凭证
streamlitctl gitea clone <name> <repo>   # 从 Gitea 克隆
streamlitctl gitea pull <name>           # 拉取最新更改

UCI 配置

主配置：/etc/config/streamlit

config streamlit 'main'
    option enabled '1'
    option http_port '8501'
    option data_path '/srv/streamlit'
    option memory_limit '512M'

config streamlit 'gitea'
    option enabled '1'
    option url 'http://192.168.255.1:3000'
    option user 'admin'
    option token 'your-token'

config app 'myapp'
    option name 'My App'
    option enabled '1'
    option repo 'user/myapp'

config instance 'myapp'
    option app 'myapp'
    option port '8502'
    option enabled '1'

示例：完整的 Gitea 工作流

# 1. 在 Gitea 中创建包含 Streamlit 应用的仓库
#    - app.py（主文件）
#    - requirements.txt（依赖）

# 2. 配置 streamlit 平台
uci set streamlit.gitea.enabled=1
uci set streamlit.gitea.url='http://192.168.255.1:3000'
uci set streamlit.gitea.user='admin'
uci set streamlit.gitea.token='abc123'
uci commit streamlit

# 3. 克隆并部署
streamlitctl gitea setup
streamlitctl gitea clone myapp admin/my-streamlit-app
streamlitctl instance add myapp 8502
/etc/init.d/streamlit restart

# 4. 访问应用
curl http://192.168.255.1:8502

# 5. 代码更改时从 Gitea 更新
streamlitctl gitea pull myapp
/etc/init.d/streamlit restart

HAProxy 集成

通过 HAProxy vhost 暴露 Streamlit 应用：

# 为应用添加后端
uci add haproxy backend
uci set haproxy.@backend[-1].name='streamlit_myapp'
uci set haproxy.@backend[-1].mode='http'
uci add_list haproxy.@backend[-1].server='myapp 192.168.255.1:8502'
uci commit haproxy

# 添加 vhost
uci add haproxy vhost
uci set haproxy.@vhost[-1].name='myapp_vhost'
uci set haproxy.@vhost[-1].domain='myapp.example.com'
uci set haproxy.@vhost[-1].backend='streamlit_myapp'
uci set haproxy.@vhost[-1].ssl='1'
uci commit haproxy

/etc/init.d/haproxy restart

故障排除

容器无法启动：

streamlitctl status
lxc-info -n streamlit

应用无法加载：

streamlitctl logs myapp
streamlitctl shell
# 在容器内：
cd /srv/apps/myapp && streamlit run app.py

git 克隆失败：

# 检查凭证
streamlitctl gitea setup
# 手动测试
git clone http://admin:token@192.168.255.1:3000/user/repo.git /tmp/test

许可证

Copyright (C) 2025 CyberMind.fr