介绍
# Fly.io (flyctl) CLI
使用 `flyctl` 安全且可重复地操作 Fly.io 应用。
## 默认设置 / 安全性
- 优先使用 **只读** 命令：`fly status`、`fly logs`、`fly config show`、`fly releases`、`fly secrets list`。 - **未经人类明确批准，请勿编辑/修改 Fly.io 应用、机器、密钥、卷或数据库。** - 未经批准的只读操作是可以的。 - 破坏性操作（destroy/drop）始终需要明确批准。 - 调试构建时，捕获确切的错误输出并确定它是： - 构建/打包问题（Dockerfile、Gemfile.lock 平台、assets 预编译） - 运行时问题（secrets、数据库、迁移） - 平台问题（区域、机器、健康检查）
## 快速入门（典型部署）
在应用仓库目录中：
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 + 原生扩展 (nokogiri, pg 等) 症状：构建期间 Bundler 找不到平台扩展，例如 `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 <app>` - 显示配置： - `fly config show -a <app>` - 列出密钥（仅名称）： - `fly secrets list -a <app>`
## 高风险操作（请先询问）
这些命令可以在服务器上执行任意代码或更改生产状态。 仅在用户明确要求时运行它们。
- 部署： - `fly deploy` / `fly deploy --remote-only` - SSH 执行 / 控制台： - `fly ssh console -a <app> -C "<command>"` - 密钥更改： - `fly secrets set -a <app> 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 部署 / 预览
- 对于生产环境 CD：使用 Fly 的 GitHub Action (`superfly/flyctl-actions/setup-flyctl`) 并运行 `flyctl deploy`。 - 对于 PR 预览： - 优先在每个 PR 使用一个 **预览应用**，在共享的 Fly Postgres 集群内为每个 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）。