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

# 接入 Flashduty 状态页

> 了解如何从零创建或从 Atlassian Statuspage 迁移到 Flashduty 状态页

首次接入 Flashduty 状态页时，你可以从零创建一个新状态页，也可以从 Atlassian Statuspage 迁移到 Flashduty 状态页。本文分别说明这两种接入路径的必要步骤。

状态页创建或迁移完成后，组件、分组、事件模板、订阅和事件发布都属于后续配置。你可以在本文末尾跳转到对应文档。

如果你还不了解状态页的基本概念，先阅读[什么是状态页](/zh/on-call/statuspage/statuspage)。

***

## 选择接入方式

| 当前情况                      | 推荐方式               | 本文对应章节                                                  |
| ------------------------- | ------------------ | ------------------------------------------------------- |
| 还没有正式状态页                  | 从零创建 Flashduty 状态页 | [从零创建状态页](#从零创建状态页)                                     |
| 已经使用 Atlassian Statuspage | 迁移结构、历史事件和订阅者      | [从 Atlassian Statuspage 迁移](#从-atlassian-statuspage-迁移) |

如果你正在评估是否替换 Atlassian Statuspage，可以先阅读[状态页对比](/zh/on-call/statuspage/comparison)。

***

## 从零创建状态页

从零创建只需要先建立一个状态页实体，并确认页面名称、访问标识和页面类型。创建后的品牌、域名、组件、订阅和事件发布配置，请在后续文档中完成。

<Steps>
  <Step title="确认状态页类型">
    选择创建**公开状态页**或**内部状态页**。公开状态页面向客户、合作伙伴和外部访客；内部状态页面向组织成员，需要登录 Flashduty 后访问。
  </Step>

  <Step title="进入状态页管理">
    登录 [Flashduty 控制台](https://console.flashcat.cloud)，在左侧导航进入 **状态页**，点击 **创建状态页**。
  </Step>

  <Step title="填写创建信息">
    按页面提示填写以下字段：

    | 字段         | 说明                              |
    | ---------- | ------------------------------- |
    | **名称**     | 状态页的显示名称，通常使用公司名、产品名或服务名        |
    | **URL 标识** | 用于生成状态页访问地址的唯一标识，仅允许小写字母、数字和连字符 |
    | **类型**     | 选择 **公开** 或 **内部**              |
  </Step>

  <Step title="完成创建">
    点击 **确认** 完成创建。页面创建后，再按实际需要配置基础信息、组件、订阅、模板和事件发布流程。
  </Step>
</Steps>

***

## 从 Atlassian Statuspage 迁移

如果你已经在使用 Atlassian Statuspage，可以使用 Flashduty CLI 将**组件、分组、历史事件和邮件订阅者**迁移到 Flashduty 状态页。迁移分为两个独立步骤：

1. **迁移结构与历史**：导入组件、分组、历史事件、维护记录和通知模板。
2. **迁移邮件订阅者**：导入订阅者列表及其订阅偏好。

两步分离的原因是：迁移结构时**不会**向订阅者发送通知。你可以先检查导入内容是否正确，再决定是否导入订阅者。导入的订阅者会直接变为活跃状态，无需重新邮件验证。

<Tip>
  如果你使用 Codex、Claude Code、Cursor 等 AI 编程代理，也可以先按 [flashduty-cli README](https://github.com/flashcatcloud/flashduty-cli/blob/main/README_zh.md) 中的 Agent Skills 指引安装技能。安装后，`flashduty-statuspage` skill 会向代理提供 Atlassian Statuspage 迁移命令和注意事项，你可以让代理在本地终端协助执行迁移。
</Tip>

### 准备工作

#### 安装 Flashduty CLI

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex
    ```
  </Tab>

  <Tab title="手动下载">
    访问 [CDN 最新版本指针](https://static.flashcat.cloud/flashduty-cli/releases/latest) 获取最新版本号，然后从 `https://static.flashcat.cloud/flashduty-cli/releases/download/<version>/<asset>` 下载对应平台的二进制包，解压后放入 `PATH` 即可。
  </Tab>
</Tabs>

更多安装方式请参考 [CLI 文档](/zh/developer/cli)。

#### 登录 Flashduty

```bash theme={null}
flashduty login
```

按提示输入 APP Key。获取方式：登录 [Flashduty 控制台](https://console.flashcat.cloud)，进入 **个人中心 > 个人信息**，复制 APP Key。

#### 获取 Atlassian Statuspage API Key

1. 登录 [Atlassian Statuspage 管理面板](https://manage.statuspage.io/)
2. 进入 **User icon > API info**，复制 API Key
3. 设置环境变量：

```bash theme={null}
export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here"
```

#### 获取 Atlassian Statuspage Page ID

在 Atlassian Statuspage 管理面板中，**Page ID** 显示在页面 URL 或页面设置中。格式类似 `0db0rq26tg1l`。

### 迁移步骤

建议先迁移结构和历史，再迁移订阅者，最后切换域名。这样可以先检查导入结果，再让订阅者开始接收 Flashduty 状态页通知。

<Steps>
  <Step title="迁移结构与历史">
    执行以下命令导入 Atlassian Statuspage 的组件、分组、历史事件、维护记录和通知模板。此步骤会创建或复用 Flashduty 目标状态页，但不会通知订阅者。

    ```bash theme={null}
    flashduty statuspage migrate structure \
      --from atlassian \
      --source-page-id <your_atlassian_page_id> \
      --api-key "$ATLASSIAN_STATUSPAGE_API_KEY"
    ```

    | 参数                 | 必填 | 说明                             |
    | ------------------ | -- | ------------------------------ |
    | `--from`           | 是  | 迁移来源，目前仅支持 `atlassian`         |
    | `--source-page-id` | 是  | Atlassian Statuspage 的 Page ID |
    | `--api-key`        | 是  | Atlassian Statuspage 的 API Key |
    | `--url-name`       | 否  | 新创建的 Flashduty 公开状态页的 URL 名称   |

    <Warning>
      `--url-name` 仅在本次迁移**创建新的目标状态页**时生效。如果同一个 `--source-page-id` 已经在历史迁移中映射到一个已存在的目标状态页：

      * 省略 `--url-name`，或传入与已存在目标状态页完全一致的值，迁移会复用该目标页继续执行。
      * 传入与已存在目标页不同的值，迁移会在预检阶段失败。如需更改 URL 名称，请在 Flashduty 控制台直接编辑目标状态页。
    </Warning>

    `--url-name` 的格式与唯一性要求：

    * 经 `MakeSlug` 规范化：转换为小写、用连字符连接、长度不超过 255 个字符；纯符号或规范化后为空的输入会被拒绝，错误信息为 `url_name must not be empty after normalization`。
    * 在账号下的公开状态页范围内全局唯一，重复时会以 `url_name must be unique` 拒绝。
  </Step>

  <Step title="查询迁移进度">
    迁移任务为异步执行，命令会立即返回一个 **Job ID**。使用以下命令查询进度：

    ```bash theme={null}
    flashduty statuspage migrate status --job-id <job_id>
    ```

    迁移会依次导入 `components`、`sections`、`history` 和 `templates`。任务完成后，输出中会包含 Flashduty 状态页 ID（`target-page-id`），后续迁移订阅者时需要使用。

    如果需要取消正在运行的迁移任务，执行：

    ```bash theme={null}
    flashduty statuspage migrate cancel --job-id <job_id>
    ```
  </Step>

  <Step title="验证导入内容">
    在进行下一步之前，建议检查导入的内容：

    ```bash theme={null}
    # 查看新状态页信息
    flashduty statuspage list --id <target_page_id>

    # 查看导入的事件
    flashduty statuspage changes --page-id <target_page_id> --type incident
    ```

    你也可以登录 [Flashduty 控制台](https://console.flashcat.cloud)，在状态页管理界面中检查组件、分组和历史事件是否完整。
  </Step>

  <Step title="迁移邮件订阅者">
    确认结构和历史导入正确后，执行订阅者迁移：

    ```bash theme={null}
    flashduty statuspage migrate email-subscribers \
      --from atlassian \
      --source-page-id <your_atlassian_page_id> \
      --target-page-id <flashduty_page_id> \
      --api-key "$ATLASSIAN_STATUSPAGE_API_KEY"
    ```

    | 参数                 | 必填 | 说明                             |
    | ------------------ | -- | ------------------------------ |
    | `--from`           | 是  | 迁移来源，`atlassian`               |
    | `--source-page-id` | 是  | Atlassian Statuspage 的 Page ID |
    | `--target-page-id` | 是  | 结构与历史迁移完成后输出的 Flashduty 状态页 ID |
    | `--api-key`        | 是  | Atlassian Statuspage 的 API Key |

    导入的订阅者会直接变为活跃状态，无需邮件验证。已在 Atlassian 端被标记为隔离（quarantined）的邮箱地址会被自动跳过。订阅者迁移可以安全地多次执行，已存在的订阅者不会被重复导入。
  </Step>

  <Step title="切换域名和 RSS/Atom">
    如果原 Atlassian Statuspage 使用自定义域名，将 CNAME 记录切换到 Flashduty 提供的状态页地址。Flashduty 兼容 `history.rss` 和 `history.atom` 链接格式，原 RSS/Atom 订阅可继续生效。

    自定义域名配置请参考[配置状态页基础信息](/zh/on-call/statuspage/create-manage-page)。RSS/Atom 订阅规则请参考[订阅管理](/zh/on-call/statuspage/subscriptions)。
  </Step>
</Steps>

### 完整迁移示例

```bash theme={null}
# 设置 Atlassian API Key
export ATLASSIAN_STATUSPAGE_API_KEY="your_api_key_here"

# 1. 迁移结构与历史
flashduty statuspage migrate structure \
  --from atlassian \
  --source-page-id 0db0rq26tg1l \
  --api-key "$ATLASSIAN_STATUSPAGE_API_KEY"
# 输出: Job ID: str_abc

# 2. 查询进度，等待完成
flashduty statuspage migrate status --job-id str_abc
# 重复执行直到 Status: completed
# 记录输出中的 target-page-id

# 3. 验证导入结果
flashduty statuspage list --id <target_page_id>

# 4. 迁移邮件订阅者
flashduty statuspage migrate email-subscribers \
  --from atlassian \
  --source-page-id 0db0rq26tg1l \
  --target-page-id <target_page_id> \
  --api-key "$ATLASSIAN_STATUSPAGE_API_KEY"
# 输出: Job ID: sub_xyz

# 5. 查询进度，等待完成
flashduty statuspage migrate status --job-id sub_xyz
```

***

## 继续配置

完成创建或迁移后，按目标进入对应文档。这里不再重复展开每个功能的配置步骤。

| 目标                                     | 文档                                                     |
| -------------------------------------- | ------------------------------------------------------ |
| 配置品牌、域名和显示设置                           | [配置状态页基础信息](/zh/on-call/statuspage/create-manage-page) |
| 设计服务组件、分组结构和可见性                        | [组件与分组管理](/zh/on-call/statuspage/components-sections)  |
| 发布故障或维护事件，并更新时间线                       | [发布与管理事件](/zh/on-call/statuspage/publish-events)       |
| 准备故障、维护和恢复通知话术                         | [事件模板](/zh/on-call/statuspage/templates)               |
| 管理邮件、RSS/Atom、IM 订阅和订阅者导入导出            | [订阅管理](/zh/on-call/statuspage/subscriptions)           |
| 对比 Flashduty 状态页与 Atlassian Statuspage | [状态页对比](/zh/on-call/statuspage/comparison)             |