将一个 Streamlit 项目部署到极空间（ZimaSpace）的 Docker 中，主要分为三个阶段：**准备项目文件**、**构建镜像**、**在极空间上运行**。
由于极空间的 Docker 管理界面主要支持从 Docker Hub 拉取镜像，因此最推荐的方式是先将镜像上传到 Docker Hub。
以下是详细步骤：
### 第一阶段：准备项目文件
在你的本地项目根目录下，确保有以下几个核心文件：
#### 1. `requirements.txt`
列出所有 Python 依赖库。
```text
streamlit
# 如果还有其他库，比如 PIL, pandas 等，也写上
pillow
pandas
```
#### 2. `Dockerfile`
这是构建镜像的核心指令。
```dockerfile
# 使用轻量级的 Python 镜像
FROM python:3.9-slim
# 设置工作目录
WORKDIR /app
# 安装必要的系统依赖（如果涉及图像处理，可能需要这些）
RUN apt-get update && apt-get install -y \
build-essential \
curl \
software-properties-common \
&& rm -rf /var/lib/apt/lists/*
# 复制项目文件到容器
COPY . .
# 安装 Python 依赖
RUN pip3 install -r requirements.txt
# 暴露 Streamlit 的默认端口
EXPOSE 8501
# 配置健康检查
HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
# 启动命令
ENTRYPOINT ["streamlit", "run", "main.py", "--server.port=8501", "--server.address=0.0.0.0"]
```
(注意：将 `main.py` 替换为你程序的主入口文件名)
---
### 第二阶段：构建并发布镜像
你可以选择以下两种方式之一：
#### 方法 A：发布到 Docker Hub (推荐，极空间拉取最方便)
1. 在电脑上安装 Docker Desktop。
2. 在终端执行：
```bash
# 登录 Docker Hub
docker login
# 构建镜像 (替换 username 为你的 Docker Hub 账号名)
docker build -t username/lingtu-pod:v1 .
# 推送镜像
docker push username/lingtu-pod:v1
```
#### 方法 B：打包成离线包 (如果不想公开代码)
1. 在本地构建镜像：`docker build -t lingtu-pod:v1 .`
2. 导出镜像：`docker save -o lingtu-pod.tar lingtu-pod:v1`
3. 将 `lingtu-pod.tar` 上传到极空间的文件夹里。
---
### 第三阶段：在极空间部署
#### 1. 获取镜像
* 如果是方法 A： 打开极空间“Docker” -> “镜像” -> “仓库” -> 搜索你的镜像 `username/lingtu-pod` -> 下载。
* 如果是方法 B： 打开极空间“Docker” -> “镜像” -> “镜像库” -> 点击“本地导入”，选择你上传的 `.tar` 文件。
#### 2. 创建容器
在“镜像”列表中找到刚才下载/导入的镜像，点击**“添加到容器”**：
1. 基础设置：
* 容器名称：`lingtu-pod`
* 自动重启：开启（建议）
2. 端口转发：
* 本地端口：填写一个没被占用的端口（如 `8501`）。
* 容器端口：必须填 `8501`（对应 Dockerfile 里的暴露端口）。
3. 存储卷 (路径设置)：
* 如果你需要持久化存储上传的文件或生成的报告，点击“添加文件/文件夹”。
* 极空间路径：选择一个极空间上的文件夹。
* 装载路径：对应程序里保存数据的目录（例如 `/app/data`）。
4. 网络：
* 默认使用 `bridge` 模式即可。
#### 3. 启动并访问
* 完成后启动容器。
* 在浏览器输入：`极空间的本地IP:8501` (例如 `192.168.1.100:8501`)。
---
### 针对 Streamlit 项目的特别提示
1. 宽屏适配： 你的代码中已经写了 `layout="wide"`，在 Docker 中运行后，在大屏幕显示器上会自动填充。
2. 文件上传限制： Streamlit 默认上传限制为 200MB。如果你需要处理大图或视频，可以在启动命令中增加参数：
`--server.maxUploadSize=500`
3. 远程访问：
如果你想在公司或户外访问这个系统，可以使用极空间的*“远程访问”**功能，将刚才设置的 8501 端口进行内网穿透映射，或者使用极空间的内置域名访问。
报错排查：
如果容器启动失败，请点击极空间 Docker 界面里的**“日志”**，查看是否有 Python 模块缺失或路径错误的信息。
