fly-io

Fly.io 部署与管理

核心概念

• Fly App：属于同一组织的一组已命名 Machine（VM）及其配置、网络和密钥
• Fly Machine：快速启动的 VM（启动时间不到一秒）。根文件系统是临时的。生命周期：创建 -> 启动 -> 停止 -> 销毁
• Fly Volume：由 NVMe 提供支持的持久存储，与 Machine 一对一绑定，固定在特定区域，默认静态加密
• Fly Proxy：边缘代理，负责 TLS 终止、负载均衡、自动停止／自动启动和 HTTP 路由
• flyctl (fly)：用于所有 Fly.io 操作的 CLI。安装：brew install flyctl 或 curl -L https://fly.io/install.sh | sh
• fly.toml：应用配置文件。完整参考请参阅 references/fly-toml-config.md

快速入门工作流

# 1. Create app + fly.toml
fly launch

# 2. Set secrets
fly secrets set DATABASE_URL=postgres://... SECRET_KEY=...

# 3. Deploy
fly deploy

# 4. Check status
fly status
fly logs

fly.toml 基础

最简 Web 应用配置：

app = 'my-app'
primary_region = 'ord'

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 1

  [http_service.concurrency]
    type = "requests"
    soft_limit = 200
    hard_limit = 250

[[vm]]
  memory = '512mb'
  cpu_kind = 'shared'
  cpus = 1

包含所有部分的完整 fly.toml 参考请参阅 references/fly-toml-config.md。

Machine 管理

# Scale horizontally
fly scale count 3                          # 3 Machines in primary region
fly scale count 3 --region ord,iad         # Across regions

# Scale vertically
fly scale vm performance-1x --vm-memory 2048

# Direct Machine control
fly machine run <image> --region ord
fly machine clone <machine-id> --region iad
fly machine update <machine-id> --vm-memory 512
fly machine stop <machine-id>
fly machine start <machine-id>
fly machine destroy <machine-id>

Machine 规格：shared-cpu-1x（默认 256MB）、shared-cpu-2x、shared-cpu-4x、shared-cpu-8x、performance-1x 至 performance-16x。GPU 选项：a10、l40s、a100-pcie-40gb、a100-sxm4-80gb。

卷

fly volumes create mydata --region ord --size 10   # 10GB
fly volumes list
fly volumes extend <vol-id> --size 20              # Extend to 20GB (cannot shrink)
fly volumes snapshots list <vol-id>
fly volumes fork <vol-id>                          # Copy a volume

在 fly.toml 中配置：

[mounts]
  source = "mydata"
  destination = "/data"
  initial_size = "10gb"
  auto_extend_size_threshold = 80
  auto_extend_size_increment = "1GB"
  auto_extend_size_limit = "50GB"

重要：卷与 Machine 一对一绑定，固定在特定区域，且不会自动复制。为确保冗余，务必至少配置 2 台带卷的 Machine。应用必须处理卷之间的数据复制。

密钥

fly secrets set KEY=value OTHER_KEY=other_value
fly secrets set KEY=value --stage               # Stage without restarting
fly secrets deploy                               # Deploy staged secrets
fly secrets list                                 # Names only, no values
fly secrets unset KEY OTHER_KEY

密钥在静态时经过加密，并在启动时注入为环境变量。使用 fly.toml 中的 [[files]] 将密钥挂载为文件（值必须经过 base64 编码）：

[[files]]
  guest_path = "/etc/ssl/private/key.pem"
  secret_name = "TLS_PRIVATE_KEY"

日志

fly logs                                     # Continuous tail (default, streams indefinitely)
fly logs --no-tail                           # Output recent logs once and exit
fly logs --machine <machine-id>              # Filter to a specific machine
fly logs --machine <machine-id> --no-tail    # Recent logs for one machine, then exit
fly logs --region iad                        # Filter by region
fly logs --json                              # JSON-formatted output

重要：flyctl logs 不支持 -n、--tail <count> 或 --lines 标志。若要限制输出，请通过管道传递给标准工具：

fly logs --no-tail | head -50                # Last 50 lines
fly logs --no-tail | tail -20                # Most recent 20 lines
fly logs --machine <id> --no-tail | grep -i error   # Search for errors

可用标志：

标志	说明
--no-tail (-n)	输出日志一次后退出（不持续输出）
--machine <id>	筛选特定 machine ID
--region <code>	按区域筛选（例如 iad、ord）
--json (-j)	JSON 输出格式
--app <name> (-a)	指定应用名称（当前目录中没有 fly.toml 时）

网络

有关详细的网络配置模式（公共服务、私有网络、Flycast、自定义域名、DNS），请参阅 references/networking.md。

快速参考

fly ips list                                 # List allocated IPs
fly ips allocate-v6                          # Dedicated IPv6 (free)
fly ips allocate-v4 --shared                 # Shared IPv4 (free)
fly ips allocate-v4                          # Dedicated IPv4 (paid)
fly certs create mydomain.com                # Add custom domain + TLS cert

私有网络：组织中的所有应用共用一个 WireGuard 网状网络（6PN）。使用 <appname>.internal DNS 进行应用间通信。绑定到 fly-local-6pn 或 [::]:port 以接受私有连接。

健康检查

服务级检查会影响 Fly Proxy 路由。顶层 [checks] 仅用于监控。

# In [http_service] or [[services]]
[[http_service.checks]]
  grace_period = "10s"
  interval = "30s"
  timeout = "5s"
  method = "GET"
  path = "/health"

# Top-level (monitoring, no routing impact)
[checks.my_check]
  type = "http"
  port = 8080
  path = "/health"
  interval = "30s"
  timeout = "5s"

自动扩缩

自动停止／自动启动（基于 Fly Proxy，适用于 Web 服务）：

[http_service]
  auto_stop_machines = "stop"      # "off", "stop", or "suspend"
  auto_start_machines = true
  min_machines_running = 1

  [http_service.concurrency]
    type = "requests"
    soft_limit = 200               # Used for excess capacity calculation

基于指标的自动扩缩：在组织中部署自动扩缩应用。它会轮询 Prometheus 指标并创建／销毁 Machine。设置方法请参阅 Fly.io 文档。

部署策略

[deploy]
  strategy = "rolling"              # "rolling" (default), "immediate", "canary", "bluegreen"
  max_unavailable = 0.33            # For rolling: fraction or integer
  release_command = "bin/migrate"   # One-off command before deploy (e.g., DB migrations)

• rolling：逐个替换（默认）
• immediate：一次性全部替换，跳过等待健康检查
• canary：启动一台 Machine，验证健康状态，然后执行滚动部署（不支持卷）
• bluegreen：与旧 Machine 并行启动一组新 Machine，在健康检查通过后迁移流量（需要健康检查，不支持卷）

使用 GitHub Actions 进行 CI/CD

有关完整的 CI/CD 设置，包括部署令牌、预览应用和多应用部署，请参阅 references/cicd-github-actions.md。

快速设置：

# .github/workflows/fly.yml
name: Fly Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency: deploy-group
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

生成部署令牌：fly tokens create deploy -x 999999h

数据库与存储

有关详细的数据库和存储配置模式，请参阅 references/databases-storage.md。

• 托管 Postgres：fly mpg create —— 全托管，自动备份
• Tigris 对象存储：兼容 S3，fly storage create
• Upstash Redis：托管 Redis，fly redis create

生产环境检查清单

1. 安全性：启用 SSO，使用密钥保存敏感数据，从私有应用中释放不必要的公共 IP，内部服务使用 Flycast
2. 性能：生产环境 Web 应用使用高性能 CPU，合理配置内存，启用交换空间（swap_size_mb）以应对流量峰值
3. 可用性：运行 2 台或更多 Machine（最好分布在不同区域），配置自动停止／自动启动，并设置运行状况检查
4. 网络：设置自定义域名和 TLS 证书；如有需要，可考虑使用专用 IPv4
5. 监控：配置 Prometheus 指标导出，设置 Sentry，并将日志导出到外部服务
6. CI/CD：通过 GitHub Actions 使用部署令牌进行部署，并设置审查应用预览

进程组

在一个应用中运行多个进程（例如，Web + worker）：

[processes]
  web = "bin/rails server -b 0.0.0.0 -p 8080"
  worker = "bin/sidekiq"

[http_service]
  internal_port = 8080
  processes = ["web"]

[[vm]]
  processes = ["web"]
  memory = "1gb"

[[vm]]
  processes = ["worker"]
  memory = "512mb"

实用命令速查表

命令	说明
fly launch	创建应用和 fly.toml
fly deploy	构建并部署
fly deploy --remote-only	在 Fly.io 构建器上构建
fly status	查看应用和 Machine 状态
fly logs	实时跟踪日志（持续输出）
fly logs --no-tail	输出近期日志一次后退出
fly logs --machine <id>	筛选特定 Machine 的日志
fly logs --machine <id> --no-tail	输出某台 Machine 的近期日志后退出
fly logs --region iad	按区域筛选日志
fly logs --json	以 JSON 格式输出日志
fly ssh console -s	SSH 连接到 Machine（选择一台）
fly proxy 5432:5432	将本地端口代理到应用
fly dashboard	打开 Web 控制面板
fly scale show	显示当前扩缩容配置
fly checks list	查看运行状况检查状态
fly releases	列出发布版本
fly config show	显示当前的 fly.toml
fly apps restart	重启所有 Machine