docs/huggingface_deployment.md

Hugging Face 部署与维护 / Deployment and operations

中文

部署结构

• GitHub 仓库 IsaacHuo/maptoposter 的 main 是唯一源码来源。
• .github/workflows/publish-hugging-face.yml 先运行 Python、前端和 Docker 检查。
• 所有检查通过后，官方 huggingface/hub-sync Action 将文件镜像到 isaachwf/MapToPoster。
• Hugging Face 根据 README 元数据以 Docker SDK 构建，并暴露容器的 7860 端口。

hub-sync 是文件镜像而不是 Git 强推。它会同步删除 GitHub 已移除的文件，同时排除 .git/ 和 .github/，因此两个仓库不需要共享 Git 历史。

首次配置凭据

1. 打开 https://huggingface.co/settings/tokens。
2. 创建一个单独的 fine-grained Token，只授予 isaachwf/MapToPoster 写权限。
3. 打开 GitHub 仓库的 Settings → Secrets and variables → Actions。
4. 新建 Repository Secret，名称必须是 HF_TOKEN，值为刚创建的 Token。
5. 不要把 Token 写入代码、.env、提交记录、Issue 或聊天消息。

Token 只用于 GitHub Actions 发布。删除或轮换 Token 后，应立即更新同名 GitHub Secret。

发布

正常发布只需要将已验证的提交推送到 GitHub main：

git push origin main

工作流的 validate job 失败时，publish job 不会运行，线上 Space 保持原版本。工作流也支持在 GitHub Actions 页面手动运行。

环境和存储

容器默认使用：

MAPTOPOSTER_CACHE_DIR=/data/cache
MAPTOPOSTER_OUTPUT_DIR=/data/posters
MPLCONFIGDIR=/tmp/matplotlib

CPU Basic 的磁盘是临时磁盘。Factory reboot、重新部署或平台重启可能清除 /data。当前应用只把可重新生成的 OSM/地理编码缓存放在那里，因此无需数据迁移。

验证

发布完成后检查：

1. Space 设置仍显示 cpu-basic，运行阶段为 RUNNING，SDK 为 Docker。
2. GET https://isaachwf-maptoposter.hf.space/api/v1/health 返回 status: ok。
3. 首页加载 React 编辑器，样式缩略图和交互地图正常。
4. 搜索“北京”，用小范围视口完成地图准备和预览。
5. 分别下载 PNG、SVG 和 PDF，确认文件非空且 Content-Type 正确。

回滚

GitHub main 是源码真相，不直接修改 Space 仓库进行长期修复。

1. 使用 git revert <bad-commit> 创建回滚提交，不重写 main 历史。
2. 在本地运行完整检查。
3. 将回滚提交推送到 main，等待自动镜像完成。

如果 Space 构建失败，旧容器通常仍会保留或显示构建错误。不要删除或重新创建 Space；先从构建日志修复 Docker 问题，再推送修复提交。

English

Deployment model

GitHub IsaacHuo/maptoposter main is the single source of truth. The publish workflow validates Python, the frontend, and the Linux container before the official huggingface/hub-sync Action mirrors repository files to isaachwf/MapToPoster. Hugging Face then builds the Docker Space and exposes port 7860.

The sync action mirrors files rather than force-pushing Git history. It propagates deletions and excludes .git/ and .github/, so the GitHub repository and Space can retain independent histories.

One-time credentials

Create a fine-grained token at https://huggingface.co/settings/tokens with write access limited to isaachwf/MapToPoster. Save it as a GitHub Actions repository secret named HF_TOKEN. Never store the token in source files, environment files, commits, issues, or chat messages.

Release and rollback

A push to GitHub main starts validation and publishes only after every check succeeds. To roll back, revert the faulty GitHub commit and push the revert to main; do not rewrite main or maintain a manual fork of the Space source.

Free CPU Basic storage is ephemeral. /data/cache and /data/posters contain only reproducible runtime files and may be cleared during rebuilds or restarts.