name: flyio-cli
description: "使用 Fly.io 的 flyctl 命令行工具来部署和管理 Fly.io 上的应用。默认执行只读的诊断操作（状态/日志/配置/发布）。只有在获得用户明确批准后，才执行会改变状态的操作（部署、SSH 执行、密钥管理、扩缩容、机器管理、卷管理、Postgres 变更）。当被要求部署到 Fly.io、调试 fly deploy/build/runtime 故障、设置 GitHub Actions 部署/预览，或安全地管理 Fly 应用和 Postgres 时使用。"

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 <应用名>
- 检查 fly.toml 中的 app = "..."

2) 验证与检查（只读）
- fly status -a <应用名>
- fly logs -a <应用名>
- fly config show -a <应用名>

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

调试部署/构建失败

常见检查项

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

Rails + Docker + 原生 Gems（如 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 <应用名>

在集群内创建数据库

• fly postgres db create <数据库名> -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 创建一个数据库。
• 自动化 PR 的创建/部署/评论；在 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）。