Skip to content

README_zh.md

Latest commit

 

History

History
370 lines (264 loc) · 13 KB

README_zh.md

File metadata and controls

370 lines (264 loc) · 13 KB
Raw

Flashduty CLI

English | 中文

License Release CI Go Report Card

Flashduty 平台的命令行工具。在终端中管理故障、值班、状态页等。

安装

macOS / Linux

curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh

Windows (PowerShell)

irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex

手动下载

从 GitHub Releases 下载适合您平台的最新版本。

选项

变量 说明 默认值
FLASHDUTY_VERSION 安装指定版本（如 v0.1.2） 最新版
FLASHDUTY_INSTALL_DIR 自定义安装目录 /usr/local/bin（Shell）、~\.flashduty\bin（PowerShell）
MIRROR_URL 覆盖安装脚本使用的 release 资源镜像 https://static.flashcat.cloud/flashduty-cli
FLASHDUTY_UPDATE_BASE_URL 覆盖 flashduty update 和自动更新检查的 base URL https://static.flashcat.cloud/flashduty-cli

快速开始

1. 认证

flashduty login

系统会提示输入 Flashduty APP Key。获取方式：登录 Flashduty 控制台，进入 账户设置 > APP Key。

也可以通过环境变量设置：

export FLASHDUTY_APP_KEY=your_app_key

2. 使用

# 列出最近的故障
flashduty incident list

# 查看故障详情
flashduty incident get <incident_id>

# 列出团队成员
flashduty member list

# 查看协作空间
flashduty channel list

认证方式

CLI 按以下优先级解析凭证（优先级从高到低）：

  1. --app-key 参数（隐藏参数，用于脚本）
  2. FLASHDUTY_APP_KEY 环境变量
  3. ~/.flashduty/config.yaml（由 flashduty login 写入）

配置文件

存储在 ~/.flashduty/config.yaml，权限为 0600：

app_key: your_app_key
base_url: https://api.flashcat.cloud

配置命令

flashduty config show              # 查看当前配置（密钥已脱敏）
flashduty config set app_key KEY   # 设置 APP Key
flashduty config set base_url URL  # 覆盖 API 地址

全局参数

参数 说明
--json 以 JSON 格式输出
--no-trunc 表格输出时不截断长字段
--base-url 覆盖 API 地址

可用命令

incident - 故障生命周期管理（9 个命令）

flashduty incident list [flags]        # 列出故障（默认最近 24 小时）
flashduty incident get <id> [<id2>]    # 查看故障详情（单个 ID 时显示详细视图）
flashduty incident create [flags]      # 创建故障（缺少参数时进入交互模式）
flashduty incident update <id> [flags] # 更新故障字段
flashduty incident ack <id> [<id2>]    # 认领故障
flashduty incident close <id> [<id2>]  # 关闭故障
flashduty incident timeline <id>       # 查看故障时间线
flashduty incident alerts <id>         # 查看故障告警
flashduty incident similar <id>        # 查找相似故障

列表参数：

参数 说明 默认值
--progress 筛选：Triggered、Processing、Closed 全部
--severity 筛选：Critical、Warning、Info 全部
--channel 按协作空间 ID 筛选 -
--title 按标题关键字搜索 -
--since 开始时间（时长、日期、日期时间或 Unix 时间戳） 24h
--until 结束时间 now
--limit 最大结果数 20
--page 页码 1

时间格式示例： 5m、1h、24h、168h、2026-04-01、2026-04-01 10:00:00、1712000000

change - 变更记录查询（1 个命令）

flashduty change list [flags]    # 列出变更记录（部署、配置等）

支持 --channel、--since、--until、--type、--limit、--page。

member - 成员查询（1 个命令）

flashduty member list [flags]    # 列出成员

支持 --name、--email、--page。

team - 团队查询（1 个命令）

flashduty team list [flags]      # 列出团队及成员

支持 --name、--page。

channel - 协作空间查询（1 个命令）

flashduty channel list [flags]   # 列出协作空间

支持 --name。

escalation-rule - 分派策略查询（1 个命令）

flashduty escalation-rule list --channel <id>          # 按协作空间 ID 查询
flashduty escalation-rule list --channel-name <name>   # 按协作空间名称查询（自动解析）

field - 自定义字段查询（1 个命令）

flashduty field list [flags]     # 列出自定义字段定义

支持 --name。

status-page - 状态页管理（28 个命令）

命令组名是 status-page（带连字符），不是 statuspage。嵌套对象、数组类字段没有 对应的 flag，必须通过 --data 传 JSON；--data - 表示整个请求体从 stdin 读取。 位置参数和显式设置的 flag 会覆盖 --data 里的同名字段。

状态页、组件、分组

flashduty status-page list                                     # 列出状态页（JSON 形如 {"items":[...]}）
flashduty status-page info <page-id>                           # 状态页详情，含组件 ID 和分组 ID
flashduty status-page create --name <name> --url-name <slug> --type <public|internal> \
    --date-view <calendar|list> --display-uptime-mode <chart_and_percentage|chart|none>
flashduty status-page update <page-id> [--name <name>] [--url-name <slug>] ...   # 更新状态页
flashduty status-page delete <page-id>                         # 删除状态页
flashduty status-page component-upsert <page-id> --data '{"components":[{"name":"API","section_id":"<section-id>"}]}'
flashduty status-page component-delete <component-id> [<id2>...] --page-id <page-id>
flashduty status-page section-upsert <page-id> --data '{"sections":[{"name":"核心服务"}]}'
flashduty status-page section-delete <section-id> [<id2>...] --page-id <page-id>

事件（故障 / 维护）与时间线

flashduty status-page change-active-list <page-id> --type <incident|maintenance>   # 只列进行中的事件
flashduty status-page change-list <page-id> --type <incident|maintenance> --status <status>
flashduty status-page change-info --page-id <page-id> --change-id <change-id>
flashduty status-page change-create <page-id> --type <incident|maintenance> --title <title> \
    --status <status> --description <text> --data '{"updates":[...]}'
flashduty status-page change-update --page-id <page-id> --change-id <change-id> [--title <title>]
flashduty status-page change-delete --page-id <page-id> --change-id <change-id>
flashduty status-page change-timeline-create --page-id <page-id> --change-id <change-id> \
    --status <status> --description <text> [--data '{"component_changes":[...]}']
flashduty status-page change-timeline-update --page-id <page-id> --change-id <change-id> --update-id <update-id> [--description <text>]
flashduty status-page change-timeline-delete --page-id <page-id> --change-id <change-id> --update-id <update-id>

change-create 的 <page-id> 是必填位置参数；必填的 updates 数组（以及嵌套在里面的 component_changes）没有对应的 flag，所以真实的 change-create 调用一定带 --data：

flashduty status-page change-create 5750613685214 --type incident \
  --title "API 延迟升高" --status investigating \
  --description "正在排查延迟升高问题。" \
  --data '{"updates":[{"status":"investigating","description":"团队正在排查。","component_changes":[{"component_id":"01KC3GAZ6ZJE40H55GM31RPWZE","status":"degraded"}]}]}'

整个请求体也可以用 --data - 从 stdin 读：

cat change.json | flashduty status-page change-create 5750613685214 --data -

关闭事件走 change-timeline-create，并且事件涉及的每个组件都要改回 operational：

flashduty status-page change-timeline-create --page-id 5750613685214 --change-id 5821693893131 \
  --status resolved --description "已恢复。" \
  --data '{"component_changes":[{"component_id":"01KC3GAZ6ZJE40H55GM31RPWZE","status":"operational"}]}'

订阅者与模板

flashduty status-page subscriber-list <page-id> [--component-ids <ids>] [--page <n>] [--limit <n>]
flashduty status-page subscriber-import <page-id> --method <email|im> --data '{"subscribers":[...]}'
flashduty status-page subscriber-export <page-id> [--component-ids <ids>]
flashduty status-page template-list <page-id> --type <pre_defined|message>
flashduty status-page template-upsert <page-id> --type <pre_defined|message> --data '{"template":{...}}'
flashduty status-page template-delete --page-id <page-id> --template-id <template-id> --type <pre_defined|message>

从 Atlassian Statuspage 迁移

flashduty status-page migrate-structure <source-page-id> --api-key <key> [--url-name <slug>]   # 迁移结构与历史
flashduty status-page migrate-email-subscribers --source-page-id <id> --target-page-id <id> --api-key <key>
flashduty status-page migration-status <job-id>                # 查询迁移任务状态
flashduty status-page migration-cancel <job-id>                # 取消正在跑的迁移任务

迁移任务是异步的。启动 migrate-structure 或 migrate-email-subscribers 之后， 用返回的 job_id 轮询：

flashduty status-page migration-status <job-id>

典型流程：

flashduty status-page migrate-structure page_123 --api-key $ATLASSIAN_STATUSPAGE_API_KEY
flashduty status-page migration-status <structure_job_id>
flashduty status-page migrate-email-subscribers --source-page-id page_123 \
  --target-page-id <target_page_id> --api-key $ATLASSIAN_STATUSPAGE_API_KEY
flashduty status-page migration-status <subscriber_job_id>

template - 通知模板管理（4 个命令）

flashduty template get-preset --channel <channel>                    # 获取预设模板代码
flashduty template validate --channel <channel> --file <path>        # 验证并预览模板
flashduty template variables [--category <category>]                 # 列出模板变量
flashduty template functions [--type custom|sprig|all]               # 列出模板函数

支持的通知渠道：dingtalk、dingtalk_app、feishu、feishu_app、wecom、wecom_app、slack、slack_app、telegram、teams_app、email、sms、zoom。

工具命令

flashduty login          # 交互式认证
flashduty config show    # 查看当前配置
flashduty config set     # 设置配置项
flashduty version        # 打印版本信息
flashduty completion     # 生成 Shell 自动补全（bash/zsh/fish/powershell）

输出格式

表格（默认）： 人类可读，列对齐，长字段自动截断。

ID           TITLE                    SEVERITY   PROGRESS     CHANNEL       CREATED
inc_abc123   DB connection timeout    Critical   Triggered    Production    2026-04-10 10:23
inc_def456   High memory usage        Warning    Processing   Staging       2026-04-10 09:15
Showing 2 results (page 1, total 2).

JSON（--json）： 机器可解析，完整数据，不截断。

flashduty incident list --json | jq '.[].title'

不截断（--no-trunc）： 表格显示完整字段内容。

开发

前置条件

  • Go 1.24+
  • golangci-lint（Makefile 自动安装）

构建

make build       # 构建二进制文件到 bin/flashduty
make test        # 运行测试（启用竞态检测）
make lint        # 运行代码检查
make check       # 运行所有检查（格式化、检查、测试、构建）
make help        # 显示所有可用目标

依赖

包 用途
flashduty-sdk Flashduty API 客户端
cobra CLI 框架
yaml.v3 配置文件解析
x/term 密码输入脱敏

参与贡献

欢迎贡献代码！提交 Pull Request 前请阅读 CONTRIBUTING.md，并遵守我们的行为准则。

许可证

本项目基于 MIT 许可证开源 - 详见 LICENSE 文件。