Fly.io (flyctl) 命令行工具

使用flyctl安全且可重复地操作 Fly.io 应用

。

• 默认设置 / 安全性优先使用只读命令：fly status、fly logs、fly config show、fly releases和fly secrets list
• 。
  • 未经用户明确批准，请勿编辑/修改 Fly.io 的应用、机器、密钥、存储卷或数据库。
  • 只读操作无需批准即可执行。
• 破坏性操作（销毁/删除）始终需要明确批准。
  • 构建/打包问题（Dockerfile、Gemfile.lock平台、资源预编译）
  • 运行时问题（密钥、数据库、迁移）
  • 平台问题（区域、机器、健康检查）

快速开始（典型部署）

在应用仓库目录中：

1. 确认您目标应用

• fly app list
• fly status -a <app>
• 检查fly.toml中的app = "..."

2. 验证/检查（只读）

• fly status -a <app>
• fly logs -a <app>
• fly config show -a <app>

（部署位于高风险操作下方，需要用户明确批准。）

调试部署/构建失败

常见检查

• fly deploy --verbose（更多构建日志）
• 如果使用 Dockerfile 构建：请验证 Dockerfile 中的 Ruby 版本和 Gemfile.lock 中的平台设置是否与构建器的操作系统/架构匹配。

Rails + Docker + 原生 gem（如 nokogiri、pg 等）

症状：构建过程中 Bundler 无法找到类似以下平台特定的 gem：nokogiri-…-x86_64-linux。

修复模式：

• 确保Gemfile.lock包含 Fly 构建器使用的 Linux 平台（通常是x86_64-linux）。
  • 示例：bundle lock --add-platform x86_64-linux
• 确保 Dockerfile 中的 Ruby 版本与.ruby-version文件中的版本一致。

（参见references/rails-docker-builds.md。）

日志和配置（只读）

• 流式日志：
  • fly logs -a <应用>
• 显示配置：
  • fly config show -a <应用>
• 列出密钥（仅名称）：
  • fly secrets list -a <应用>

高风险操作（请先询问）

这些命令可以在服务器上执行任意代码或改变生产环境状态。 仅在用户明确要求时才运行它们。

• 部署：
  • fly deploy/fly deploy --remote-only
• SSH 执行 / 控制台：
  • fly ssh console -a <应用> -C "<命令>"
• 密钥更改：
  • fly secrets set -a <应用> KEY=value

参见references/safety.md。

Fly Postgres 基础

识别 Postgres 应用

• fly postgres list

将 Postgres 附加到应用

• fly postgres attach <pg-app> -a <app>

在集群内创建数据库

• fly postgres db create <db_name> -a <pg-app>
• fly postgres db list -a <pg-app>

连接 (psql)

• fly postgres connect -a <pg-app>

GitHub Actions 部署 / 预览

• 用于生产环境持续部署：使用 Fly 的 GitHub Action (superfly/flyctl-actions/setup-flyctl) 并运行flyctl deploy。
• 针对 PR 预览：
  • 建议每个 PR 对应一个预览应用和一个数据库，它们位于共享的 Fly Postgres 集群内。
  • 在 PR 上自动执行创建/部署/评论操作；在关闭时销毁。

（参见references/github-actions.md。）

捆绑资源

• references/safety.md：安全规则（默认只读；修改状态前请先询问）。
• references/rails-docker-builds.md：Rails/Docker/Fly 构建失败模式及修复方法。
• references/github-actions.md：Fly 部署 + 预览工作流。
• scripts/fly_app_from_toml.sh：从 fly.toml 中提取 Fly 应用名称的小工具（仅限 shell 环境；不依赖 ruby）。