在本地或雲端執行 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 路徑字首下提供服務。