在本地或云端运行 Potato

Potato 在你自己的机器上用两条命令就能运行，potato deploy 再多一条命令就能把同一份配置放到云主机上。本页把每种常见情形对应到一个主机，并给出相应的命令。下文的云端目标需要 Potato 2.10.0 或更高版本：2.9 已经支持 DigitalOcean、Render 和 HuggingFace，2.10.0 又加入了 AWS、Heroku、Fly、Railway、Hetzner、Vultr、Linode 和 OpenStack。

选择在哪里运行任务

合适的主机取决于任务需要在线多久，以及由谁付费。表中的费用是 Potato 2.10.0 为每个目标的默认规格打印的估算值，--dry-run 会打印你所选规格的估算。

在 AWS 上请使用 Lightsail，--provider aws 创建的就是它。它的固定价格包含 IPv4 地址和 60 GB 磁盘，而且只需要 lightsail:* 权限，所以在受限的 IAM 角色下也能使用。EC2 目标（aws-ec2）用于关闭了 Lightsail 的账号。

Jetstream2 是由 NSF 资助的科研云。有 ACCESS 分配额度时它不收费，而且每个实例都有一个 DNS 名称，所以标注者看到的是普通的主机名和普通的证书。默认实例每小时消耗 2 个服务单位（service unit），一年约 17,500 个，所以研究结束后请销毁它。

在你自己的机器上运行 Potato

Potato 需要 Python 3.9 或更新版本。安装后启动一个任务：

pip install potato-annotation
potato start myproject/config.yaml -p 8000

任务地址是 http://localhost:8000，其他人无法访问。potato start 直接读取原位置的配置和数据文件，所以重启后就能用上修改，编写任务期间应当用这条命令。快速入门会带你写出第一份配置，安装介绍可选依赖（extra）和虚拟环境。

官方发布的 Docker 镜像不需要主机上装有 Python。镜像里包含 Potato 及其依赖，你的项目文件夹（含 config.yaml 和数据）挂载到 /app：

docker run -p 8000:7860 -v "$PWD/myproject:/app" ghcr.io/davidjurgens/potato:latest

容器在 7860 端口提供服务，这条命令把它映射到你机器上的 8000 端口。生产部署介绍镜像的标签、环境变量，以及 Linux 主机上会报的文件所有权错误。

用 potato share 获得临时公开链接

potato share 运行任务，并在命令运行期间把它放到一个公开的 HTTPS 链接上。它需要一个隧道客户端，会按 cloudflared、Tailscale、ngrok 的顺序使用已安装的那一个：

brew install cloudflared
potato share myproject/config.yaml

按下 Ctrl-C、笔记本休眠或网络发生变化时，链接就会失效，标注始终保存在你自己的磁盘上。打开隧道之前，potato share 会打印出哪些人能够登录并请你确认，因为此后配置中的登录规则将适用于任何拿到链接的人。有些大学网络会屏蔽 trycloudflare.com 链接，用 --backend tailscale 可以避开这种屏蔽。试点或组会用 potato share；参与者可能第二天还要回来继续的任务，请用云主机。

用一条命令部署到云端

potato deploy up 使用你现有的配置，创建服务器、获取 HTTPS 证书、上传项目、启动任务并打印 URL。先安装目标对应的 extra，然后在运行之前查看部署计划：

pip install 'potato-annotation[deploy]'            # most targets
pip install 'potato-annotation[deploy-aws]'        # the three AWS targets
pip install 'potato-annotation[deploy-openstack]'  # Jetstream2 and other OpenStack clouds
 
potato deploy up myproject/config.yaml --provider aws --dry-run
potato deploy up myproject/config.yaml --provider aws

--dry-run 不需要账号。它会打印这次部署将要创建的每一项资源、每月费用，以及配置中在公共服务器上有风险的设置。不加 --dry-run 时，Potato 会显示同样的计划，等你确认之后才创建任何东西。对同一份配置再次运行 up 会更新现有的部署；第一次 up 之后，status、logs、pull 和 destroy 都不再需要 --provider。

十三个云端目标

Potato 2.10.0 可以部署到十三个云端目标。它们最大的区别在于磁盘能否在重启后保留，这决定了一次部署是否需要下一节介绍的备份。

七个虚拟机目标（aws、aws-ec2、openstack、hetzner、vultr、linode 和 digitalocean）的设置方式相同。每个都会得到一把为该部署单独生成的部署密钥、一个只开放 22、80 和 443 端口的防火墙、带 Let's Encrypt 证书的 Caddy，以及作为 systemd 服务运行的 Potato，potato deploy logs 和 pull 在它们上面都能用。Fly、Railway、Render 和 ECS Express 运行官方发布的镜像，并在容器启动时下载你的项目。Railway、Render 和 ECS Express 从备份存储中获取项目，所以这三个都需要 --backup，带磁盘的 Railway 或 Render 服务同样需要。在 Fly 上，小于 512 KB 的项目随 Machine 的配置一起传送，不需要存储。

Google Cloud Run、Azure Container Apps 和 AWS App Runner 不在目标之列。Cloud Run 和 Azure Container Apps 提供的存储无法安全地存放 SQLite 数据库，App Runner 已于 2026 年 4 月 30 日停止接受新客户。在 Azure 上，可以用一台运行 Docker 镜像的虚拟机。

为会清空磁盘的主机做备份

在 Heroku、ECS Express、Render 免费版和 HuggingFace Spaces 上，服务器重启时磁盘会被清空。--backup 每五分钟把标注输出和项目数据库的快照复制到一个 HuggingFace 数据集或 S3 存储桶，并在服务器以空磁盘启动时恢复它们：

potato deploy up myproject/config.yaml --provider heroku --backup hf --hf-token hf_...
potato deploy up myproject/config.yaml --provider heroku --backup s3 --s3-bucket my-bucket

没有 --backup 时，Heroku 和 ECS Express 会拒绝部署，除非用 --demo 声明这些标注可以丢弃。恢复时账号列表会和标注一起恢复，所以标注者用原来的密码登录，从中断的地方继续；恢复也从不覆盖磁盘上已有的标注。--s3-endpoint 可以把 S3 备份发送到 Cloudflare R2、Backblaze B2、MinIO 或大学的对象存储。备份在虚拟机目标上同样可用，在那里它会在服务器之外另存一份数据副本。

在 potato deploy 之外，配置中的 backup 块可以在你自己运行的服务器上完成同样的工作。安装提供 HuggingFace 和 S3 客户端的 hosting extra，在服务器环境中设置 HF_TOKEN，然后把下面这个块加到现有配置里：

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: huggingface
      repo_id: lab/pilot-annotations

在 destroy 之前拉取标注

potato deploy pull 把一个部署收集到的全部内容下载到一个带时间戳的目录中，并检查收到了什么；potato deploy destroy 删除服务器。请按这个顺序运行：

potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroy 会拒绝删除从未拉取过的部署，返回零个文件的拉取不算数。拉取时通过 SQLite 的备份命令复制 project.sqlite，而不是直接复制文件，因为对 WAL 模式下的数据库做文件复制可能会漏掉最近的工作。在 Fly 和 Railway 上，销毁应用会删除它的卷，所以除非你还运行了备份，否则拉取下来的就是唯一的副本。

面向他人账号的部署按钮

potato deploy button 写出托管平台读取的文件，让平台能够从你的 git 仓库提供一键部署，并打印 README 徽章。如果合作者、学生或其他实验室需要在他们自己的账号里运行你的任务，就用这条命令：

potato deploy button studies/pilot/config.yaml --target heroku \
    --backup hf --hf-backup-repo lab/pilot-annotations

可选的目标是 heroku、render、aws 和 railway。aws 目标会写出一个用来创建 Lightsail 实例的 CloudFormation“Launch Stack”模板；对于 railway，命令会打印操作步骤，因为 Railway 是从它的控制台发布模板的。你的 config.yaml 保持不变，命令会在它旁边写一份应用了部署设置的副本 potato.deploy.yaml。仓库里不会放入任何密钥。Heroku、Render 和 AWS 模板会在部署时生成会话密钥和管理员密钥。Heroku、Render 和 AWS 按钮都要求 --backup，其凭据由执行部署的人提供。

延伸阅读

每个目标在 Potato 文档中都有单独的页面：

• 安装和运行 Potato 和部署任务：完整的 potato deploy 生命周期
• AWS：Lightsail、EC2 和 ECS Express，以及各自所需的 IAM 权限
• Jetstream2 和 OpenStack，包括如何申请分配额度
• Hetzner、Vultr 和 Linode 以及 DigitalOcean
• Fly.io、Railway、Render、Heroku 和 HuggingFace Spaces
• 备份、取回标注 和部署按钮
• 用临时 URL 分享任务

在本站，生产部署介绍如何在你自己管理的服务器上用 gunicorn 和 Docker 运行 Potato，反向代理介绍如何在某个 URL 路径前缀下提供服务。