Deploy Streamlit on HF Spaces via Docker (Streamlit SDK deprecated).

Add Dockerfile, .dockerignore, and updated setup guide for app_port 8501.

Co-authored-by: Cursor <cursoragent@cursor.com>

.dockerignore

@@ -0,0 +1,18 @@
+venv/
+.venv/
+.git/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.env
+.env.*
+!.env.example
+data/forecaster.db
+data/bls_cache.json
+data/kb_calibration.json
+data/kb_calibration_log.jsonl
+pending/
+=0.9
+nodeids
+CACHEDIR.TAG

Dockerfile

@@ -0,0 +1,26 @@
+# Hugging Face Spaces — Streamlit via Docker (native Streamlit SDK deprecated 2025-04)
+# https://huggingface.co/docs/hub/spaces-changelog
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd -m -u 1000 user
+
+USER user
+WORKDIR /home/user/app
+
+ENV STREAMLIT_HOME=/tmp/.streamlit
+ENV STREAMLIT_BROWSER_GATHER_USAGE_STATS=false
+ENV PYTHONUNBUFFERED=1
+ENV PATH="/home/user/.local/bin:${PATH}"
+
+COPY --chown=user:user requirements.txt requirements-dashboard.txt ./
+RUN pip install --user --no-cache-dir -r requirements.txt
+
+COPY --chown=user:user . .
+
+EXPOSE 8501
+
+HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health || exit 1
+
+ENTRYPOINT ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

README.md

@@ -153,14 +153,14 @@ See **[docs/DEPLOY.md](docs/DEPLOY.md)** for setup (Pages, `GROQ_API_KEY` secret
 
 ### Interactive dashboard (Hugging Face Spaces)
 
-Deploy the Streamlit UI (Job Radar, accuracy tabs) on HF free tier:
+> HF 已弃用原生 Streamlit SDK（2025-04）→ 创建 Space 时选 **Docker**，仓库内已含 `Dockerfile`。
 
 ```bash
-streamlit run dashboard.py    # local
-# or: streamlit run app.py     # same UI (HF Spaces entry)
+streamlit run app.py          # local
+docker build -t jobforecaster . && docker run -p 8501:8501 jobforecaster  # optional
 ```
 
-See **[docs/HUGGINGFACE.md](docs/HUGGINGFACE.md)** — connect repo `app.py` to a new Streamlit Space.
+See **[docs/HUGGINGFACE.md](docs/HUGGINGFACE.md)**.
 
 ---
 

deploy/huggingface/SPACE_README.md

@@ -0,0 +1,22 @@
+---
+title: JobForecaster Agent
+emoji: 🔮
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 8501
+license: other
+pinned: false
+short_description: Streamlit Job Radar & AI economy forecast dashboard
+tags:
+  - streamlit
+  - docker
+  - economics
+  - job-market
+---
+
+# JobForecaster Agent — Interactive Dashboard
+
+Copy this file to the **root `README.md`** of your Hugging Face Space repo, or ensure your linked GitHub Space uses **SDK: Docker** with `app_port: 8501`.
+
+Static reports: [GitHub Pages](https://lixiaowww.github.io/JobForecaster-Agent/)

docs/HUGGINGFACE.md

@@ -1,136 +1,136 @@
 # Hugging Face Spaces 部署指南
 
-把 **Streamlit 交互 Dashboard**（Job Radar、准确度、Benchmarks）部署到 [Hugging Face Spaces](https://huggingface.co/spaces) 免费档。
+把 **Streamlit 交互 Dashboard** 部署到 [Hugging Face Spaces](https://huggingface.co/spaces) 免费档。
 
-> **GitHub Pages**（[lixiaowww.github.io/JobForecaster-Agent](https://lixiaowww.github.io/JobForecaster-Agent/)）只托管**静态预测报告**。  
-> **本指南**部署的是完整 **Streamlit 前端**，两者互补。
+> **重要（2025 年起）**：Hugging Face **已移除原生 Streamlit SDK**（[changelog 2025-04-30](https://huggingface.co/docs/hub/spaces-changelog)）。  
+> 创建 Space 时请选择 **Docker**，不要找 Streamlit 选项。
 
----
-
-## 方式 A：从 GitHub 仓库连接（推荐）
+| 服务 | 内容 |
+|------|------|
+| [GitHub Pages](https://lixiaowww.github.io/JobForecaster-Agent/) | 静态每日预测报告 |
+| **HF Spaces** | 交互 Streamlit（Job Radar 等） |
 
-仓库已包含 `app.py`、`.streamlit/config.toml` 和合并后的 `requirements.txt`。
+---
 
-### 1. 创建 Space
+## 第一步：创建 Space（选 Docker）
 
 1. 打开 [huggingface.co/new-space](https://huggingface.co/new-space)
 2. 填写：
-   | 字段 | 值 |
-   |------|-----|
-   | Owner | 你的 HF 账号（如 `lixiaowww`） |
-   | Space name | `JobForecaster-Agent`（或任意名） |
-   | License | 与仓库一致 |
-   | Space SDK | **Streamlit** |
-   | Space hardware | **CPU basic**（免费） |
-3. **不要**选 Docker；选 **Link to a Git repository**（若界面有）
-4. 创建
-
-### 2. 连接 GitHub 仓库
-
-1. Space 页面 → **Settings** → **Repository**
-2. **Repository URL**：`https://github.com/lixiaowww/JobForecaster-Agent`
-3. **Branch**：`main`
-4. **App file**：`app.py`
-5. Save → 等待自动构建（约 3–8 分钟）
-
-若创建时未出现 Git 连接选项：
-
-1. 先创建空白 Streamlit Space  
-2. Settings → Repository → 填上述 URL  
-3. App file 设为 `app.py`
 
-### 3. 添加 Secrets（可选）
+| 字段 | 选择 |
+|------|------|
+| Space name | `JobForecaster-Agent` |
+| **SDK** | **Docker** ← 不是 Streamlit |
+| Hardware | **CPU basic**（免费） |
+| License | 与仓库一致 |
 
-Space → **Settings** → **Repository secrets**（或 Variables and secrets）
+3. 点 **Create Space**
 
-| Name | Value | 说明 |
-|------|-------|------|
-| `GROQ_API_KEY` | 你的 Groq key | [console.groq.com](https://console.groq.com) 免费档 |
+---
 
-- **有 key**：搜索未知岗位时可 LLM 扩 KB  
-- **无 key**：Radar / BLS / 情景滑块仍可用，仅 AI 生成岗位不可用  
+## 第二步：连接 GitHub 仓库
 
-Secrets 在 Streamlit 中通过 `os.environ` 读取（与本地 `.env` 相同）。
+### 方式 A：Space 设置里连 GitHub（推荐）
 
-### 4. 访问
+1. Space → **Settings** → **Repository**
+2. **Repository URL**：`https://github.com/lixiaowww/JobForecaster-Agent`
+3. **Branch**：`main`
+4. Save → 自动用仓库根目录的 **`Dockerfile`** 构建
 
-构建成功后：
+### 方式 B：推送到 HF Git 仓库
 
-`https://huggingface.co/spaces/<你的用户名>/JobForecaster-Agent`
+```bash
+# 在 HF Space 页面复制 git clone 地址后：
+git remote add hf https://huggingface.co/spaces/<你的用户名>/JobForecaster-Agent
+git push hf main
+```
 
-（公开 Space 可直接打开；私有 Space 需登录。）
+首次 push 若冲突，按 HF 提示 `git push --force`（仅首次）。
 
 ---
 
-## 方式 B：独立 Space 仓库
+## 仓库里已准备好的文件
 
-若不想把整个 GitHub 主仓库连到 HF：
+| 文件 | 作用 |
+|------|------|
+| `Dockerfile` | Streamlit + 依赖，`EXPOSE 8501` |
+| `app.py` | 入口（`import dashboard`） |
+| `.dockerignore` | 排除 `venv/`、`.env` 等 |
+| `requirements.txt` | 含 Streamlit 依赖 |
 
-1. 在 HF 新建 Streamlit Space（空白）
-2. 将 `deploy/huggingface/README.md` 的内容复制为 Space 根目录 `README.md`（含顶部 YAML）
-3. 用 `git clone` Space 仓库，把本项目代码 push 上去（或 GitHub Action 同步）
+`README.md` 顶部 **无需** YAML（选 Docker SDK 创建即可）。  
+若 HF 要求 metadata，把 `deploy/huggingface/SPACE_README.md` 的 YAML 块合并进 Space 的 README。
 
 ---
 
-## 文件说明
+## 第三步：Secrets（可选）
 
-| 文件 | 作用 |
+Space → **Settings** → **Repository secrets**
+
+| Name | 说明 |
 |------|------|
-| `app.py` | HF 入口，`import dashboard` |
-| `dashboard.py` | Streamlit 主界面 |
-| `requirements.txt` | 含 `-r requirements-dashboard.txt` |
-| `.streamlit/config.toml` | 云端 headless + HF 兼容设置 |
-| `data/jobs_kb.json` | 岗位知识库（已入库） |
-| `data/bls_market_seed.json` | 离线 BLS 实证层 |
+| `GROQ_API_KEY` | [Groq 免费 key](https://console.groq.com)，用于 LLM 扩岗位 KB |
+
+无 key 时 Radar / BLS / 情景滑块仍可用。
 
 ---
 
-## 与 GitHub Pages 分工
+## 构建成功标志
 
-| 服务 | 内容 | URL ��例 |
-|------|------|----------|
-| **GitHub Pages** | 每日静态预测报告 | `lixiaowww.github.io/JobForecaster-Agent/` |
-| **HF Spaces** | 交互 Dashboard | `huggingface.co/spaces/lixiaowww/JobForecaster-Agent` |
+- Logs 出现 `You can now view your Streamlit app`
+- 健康检查：`/_stcore/health` 通过
+- 访问：`https://huggingface.co/spaces/<用户名>/JobForecaster-Agent`
+
+首次或休眠唤醒后可能等 1–3 分钟。
 
 ---
 
 ## 常见问题
 
-### 构建失败 `ModuleNotFoundError`
+### 创建页没有 Streamlit？
+
+正常。请选 **Docker**，本项目已提供 `Dockerfile`（[官方说明](https://huggingface.co/docs/hub/spaces-sdks-docker)）。
 
-确认 Space 使用仓库根目录的 `requirements.txt`，且已 push 含 `-r requirements-dashboard.txt` 的版本。
+### 503 / Preparing Space 一直转
 
-### 页面空白或 502
+检查三处端口一致为 **8501**：
 
-- 查看 Space **Logs** 标签  
-- 首次冷启动可能 1–2 分钟  
-- 免费档闲置后会休眠，再次打开需等待唤醒  
+- `Dockerfile` → `EXPOSE 8501` 与 `ENTRYPOINT ... --server.port=8501`
+- Space README YAML（若有）→ `app_port: 8501`
+- 不要用 `app_port: 7860`（那是 Gradio 默认）
 
-### Accuracy 页数据为空
+### 构建失败 ModuleNotFoundError
 
-正常：Space 上默认无 `data/forecaster.db`（未提交 git）。  
-预测数据在 **GitHub Pages 报告** 或本地 `run.py once` 产生；HF 主要展示 **Job Radar**。
+确认 `main` 分支已 push 最新 `requirements.txt`（含 `-r requirements-dashboard.txt`）。
 
-### 限制免费档
+### Accuracy 页为空
 
-- CPU / 内存有限，GMM `n_bootstrap` 在侧边栏改小可加速  
-- 不适合高并发；个人 demo / donation 项目足够  
+Space 无 `forecaster.db`（未入库）。预测历史见 GitHub Pages；HF 主要用于 **Job Radar**。
 
 ---
 
-## 推送更新
+## 本地对比
 
-主仓库更新后，若 Space 已连 GitHub，**push 到 `main` 会自动重建**：
+```bash
+# 本地 Streamlit（与 HF 相同 UI）
+streamlit run app.py
+
+# 本地模拟 Docker 构建（可选）
+docker build -t jobforecaster .
+docker run -p 8501:8501 jobforecaster
+```
+
+---
+
+## 推送更新
 
 ```bash
-git add app.py docs/HUGGINGFACE.md .streamlit/config.toml requirements.txt
-git commit -m "Add Hugging Face Spaces Streamlit deploy"
-git push origin main
+git push origin main   # 若 Space 已连 GitHub，会自动重建
 ```
 
 ---
 
-## 相关文档
+## 相关
 
-- [docs/DEPLOY.md](DEPLOY.md) — GitHub Pages 零成本部署  
-- [README.md](../README.md) — 本地 `streamlit run dashboard.py`
+- [docs/DEPLOY.md](DEPLOY.md) — GitHub Pages
+- [Docker Spaces 文档](https://huggingface.co/docs/hub/spaces-sdks-docker)