> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 代码配置

> 使用 CLI 的计划、应用和导出工作流从单个 insforge.toml 声明管理 InsForge 身份验证、SMTP、存储、保留和部署设置。

## 概览

`insforge.toml` 是项目配置子集的声明性版本控制快照：身份验证策略、允许的重定向 URL、密码规则、SMTP、存储上传大小、实时和计划保留以及部署子域。CLI 提供针对此文件的三个命令：

* **`config plan`**：将 `insforge.toml` 与链接项目进行比较。显示会发生什么变化。
* **`config apply`**：将差异推送到实时项目。按更改能力门控、环境解析的秘密、干运行模式。
* **`config export`**：拉取当前项目状态并写新的 `insforge.toml`。对从现有项目引导很有用。

您在存储库中保留**一个** `insforge.toml`。要将其应用于不同环境（暂存、生产、队友的本地后端或自托管实例），请将 CLI 指向不同的项目（重新链接或使用 `--project-id`）。秘密通过 `env(...)` 引用从环境变量读取，所以文件本身保持免费的凭证并可以安全提交。

这在 InsForge Cloud 项目和自托管 OSS 部署上的工作方式相同。

<Note>
  所有示例使用 `npx @insforge/cli`。不要全局安装 CLI。
</Note>

## 命令摘要

| 命令                            | 目的                              |
| ----------------------------- | ------------------------------- |
| `config plan`                 | 显示 `insforge.toml` 和实时项目状态之间的差异 |
| `config apply`                | 将 `insforge.toml` 应用于实时项目       |
| `config apply --dry-run`      | 打印计划而不应用                        |
| `config apply --auto-approve` | 跳过交互式确认提示（在 `--json` 模式下需要）     |
| `config export`               | 拉取实时配置并写 `insforge.toml`        |
| `config export --force`       | 不确认覆盖现有 `insforge.toml`         |

`config plan` 和 `config apply` 读取 `insforge.toml`；如果它存在于其他位置，通过 `--file <path>`。`config export` 写入文件；通过 `--out <path>` 将其写入自定义位置。

## 推荐工作流程

<Steps>
  <Step title="从现有项目引导">
    如果您已通过仪表板配置项目，导出一次以获得工作文件：

    ```bash theme={null}
    npx @insforge/cli config export
    ```

    这写 `insforge.toml` 反映当前后端状态。
  </Step>

  <Step title="提交它">
    检查 `insforge.toml` 进入版本控制。秘密通过 `env(...)` 引用，所以文件很安全。
  </Step>

  <Step title="编辑和计划">
    更改 TOML，然后在应用前预览差异：

    ```bash theme={null}
    npx @insforge/cli config plan
    ```
  </Step>

  <Step title="应用">
    ```bash theme={null}
    npx @insforge/cli config apply
    ```

    审查呈现的计划并确认。在 CI 中，通过 `--auto-approve` 和 `--json`。
  </Step>

  <Step title="在其他地方应用相同的文件">
    要将相同的配置推送到暂存或自托管后端，请将 CLI 指向其他项目并重新运行应用：

    ```bash theme={null}
    npx @insforge/cli --project-id <staging-project-id> config apply
    ```

    在本地 shell 中因环境解析的不同秘密（SMTP 密码等），所以 TOML 不需要更改。
  </Step>
</Steps>

## `insforge.toml` 覆盖什么

该文件镜像项目配置的精选子集，对于以声明方式管理有用的部分。任何不在此列表中的内容仍存在于仪表板和 API 上。

| 部分                | 键                                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `[auth]`          | `allowed_redirect_urls`, `require_email_verification`, `verify_email_method`, `reset_password_method`, `disable_signup` |
| `[auth.password]` | `min_length`, `require_number`, `require_lowercase`, `require_uppercase`, `require_special_char`                        |
| `[auth.smtp]`     | `enabled`, `host`, `port`, `username`, `password`, `sender_email`, `sender_name`, `min_interval_seconds`                |
| `[storage]`       | `max_file_size_mb`                                                                                                      |
| `[realtime]`      | `retention_days`                                                                                                        |
| `[schedules]`     | `retention_days`                                                                                                        |
| `[deployments]`   | `subdomain`                                                                                                             |

因为 TOML 没有 `null` 文本，使用 `retention_days = 0` 禁用实时消息或计划执行日志的保留清理；`config apply` 为该值向后端发送 `null`。电子邮件模板、OAuth 提供商应用凭证、存储桶、实时通道、函数、部署环境变量和秘密不通过此文件管理。

完整示例：

```toml theme={null}
[auth]
require_email_verification = true
verify_email_method = "code"
reset_password_method = "code"
disable_signup = false
allowed_redirect_urls = [
  "https://app.example.com/auth/callback",
  "http://localhost:3000/auth/callback",
]

[auth.password]
min_length = 12
require_number = true
require_lowercase = true
require_uppercase = true
require_special_char = false

[auth.smtp]
enabled = true
host = "smtp.sendgrid.net"
port = 587
username = "apikey"
password = "env(SENDGRID_API_KEY)"
sender_email = "noreply@example.com"
sender_name = "Acme"

[storage]
max_file_size_mb = 100

[realtime]
retention_days = 7

[schedules]
retention_days = 0

[deployments]
subdomain = "acme-prod"
```

## `config plan`

```bash theme={null}
npx @insforge/cli config plan
npx @insforge/cli config plan --file ./config/insforge.toml
npx @insforge/cli --json config plan
```

`plan` 读取 `insforge.toml`，通过 `/api/metadata` 和存储、实时和计划的可选配置端点获取实时状态，然后打印呈现的差异。它也标记任何部分实时后端尚未公开（较旧的自托管版本等）。应用将跳过而不是失败整个运行。

在交互式会话中的每个 `apply` 之前使用 `plan`，并作为 CI 门来捕获意外漂移。

## `config apply`

```bash theme={null}
npx @insforge/cli config apply
npx @insforge/cli config apply --dry-run
npx @insforge/cli config apply --auto-approve
npx @insforge/cli --json config apply --auto-approve
```

`apply` 运行与 `plan` 相同的差异，然后遍历更改集：

1. **按更改能力门控。** 每个更改根据后端的元数据或部分的配置端点进行检查。如果后端不支持部分（例如没有 SMTP 公开的较旧自托管实例），该部分会跳过带命名警告，其余更改仍然适用。
2. **秘密解析。** TOML 中的 `env(...)` 引用在应用时从本地环境解析。如果缺少引用变量，命令在发送任何更新之前中止，所以后端不会被留下半配置。
3. **按部分调度。** 每个更改被发送到适当的后端端点（`/api/auth/config`, `/api/auth/smtp-config`, `/api/storage/config`, `/api/realtime/config`, `/api/schedules/config`, `/api/deployments/slug`, 等）。更改是独立的，所以一个部分的失败不会回滚之前成功的部分。

标志：

* `--dry-run` 打印计划并退出而不应用。
* `--auto-approve` 跳过交互式确认。当设置 `--json` 时需要，因为没有 TTY 用于提示。
* `--file <path>` 覆盖默认 `./insforge.toml` 位置。

## `config export`

```bash theme={null}
npx @insforge/cli config export
npx @insforge/cli config export --out ./config/insforge.toml
npx @insforge/cli config export --force
```

`export` 拉取实时项目的可配置表面并将其写入 TOML 文件。使用它来：

* 从您一直通过仪表板配置的项目引导 `insforge.toml`。
* 通过导出到临时文件并比较来对手编辑进行比较。
* 快照配置在危险更改之前，以便您在需要回滚时重新应用快照。

`export` 写的文件与 CLI 从 `apply` 期望的形状相同，所以往返支持。

没有 `--force`，`export` 在交互式模式中拒绝覆盖现有文件，并在 `--json` 模式中曲面 `OUTPUT_EXISTS` 错误。

## 秘密引用

`auth.smtp.password` 和任何其他敏感字段可以表示为 `env(VAR_NAME)` 而不是文字值：

```toml theme={null}
[auth.smtp]
password = "env(SENDGRID_API_KEY)"
```

在应用时，CLI 从本地环境读取 `SENDGRID_API_KEY`，验证它的存在，并向后端发送解析的值。TOML 本身从不包含秘密，所以它可以提交。

这是让一个 `insforge.toml` 清洁地应用到多个环境的原因：开发和生产后端仅在**哪个** `SENDGRID_API_KEY` 在您运行 `apply` 时范围内有所不同。

`env(...)` refs 在一个 TOML 中，是 `apply` 的目标在每次运行时重新发送解析的密码。这是 CLI 可以告诉后端"秘密可能已轮转，请更新"的唯一方式。没有 `env(...)` ref 的字段被视为保留现有。

## 何时使用这个

* **项目配置的版本控制。** 重定向 URL、注册策略、密码策略、电子邮件验证模式、SMTP、存储上传大小和保留窗口存在在您的团队通过 PR 审查的文件中。
* **多环境奇偶校验。** 一个 TOML，应用于开发、暂存和生产，保持支持的项目设置在各处对齐。环境特定值（子域、SMTP 凭证）通过 `--project-id` 覆盖和 `env(...)` refs 流。
* **CI 驱动的配置更改。** 从您的部署管道运行 `config apply --auto-approve --json`。与 `config plan` 结合作为 PR 检查，以便审查者看到合并在产品中会改变什么。
* **灾难恢复。** 提交的 `insforge.toml` 是已知好的配置快照。在恢复项目后重新应用它以在几秒钟内使身份验证、SMTP、存储、保留和部署设置回到预期形状。
* **自托管和本地 OSS 开发。** 运行 `npx @insforge/cli link --api-base-url http://localhost:7130 --api-key <local-key>` 针对 docker-compose 堆栈，然后将 CLI 的配置命令指向您的本地 OSS 实例，方式与您指向云的方式相同。

## 故障排除

**`Refusing to apply in --json mode without --auto-approve or --yes`。** CLI 从不在非交互式运行中静默应用更改。明确通过 `--auto-approve`（或 `-y`）。

**`your backend doesn't expose <section>`。** 链接后端在一个版本上，该版本还没有相关的 API。其余的更改仍然适用。升级后端（或等待下一个版本）以应用该部分。

**`env(...)` reference resolves to nothing。** 当缺少引用环境变量时，CLI 在任何 API 调用之前中止。在您的 shell 或 CI 的秘密存储中设置变量并重新运行。

**`Slug is already taken`。** `deployments.subdomain` 与同一后端上另一个项目的子域冲突。选择不同的值。

## 相关

* [CLI 工具](/agent-native/cli-harness)：代理驱动的完整命令表面
* [部署安全指南](/deployment/deployment-security-guide)：在部署后强化自托管后端