# 部署与运维

<cite>
**本文引用的文件列表**
- [wrangler.jsonc](file://wrangler.jsonc)
- [package.json](file://package.json)
- [.dev.vars](file://.dev.vars)
- [src/index.ts](file://src/index.ts)
- [src/command/index.ts](file://src/command/index.ts)
- [src/scheduler/index.ts](file://src/scheduler/index.ts)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts)
- [worker-configuration.d.ts](file://worker-configuration.d.ts)
- [test/index.spec.ts](file://test/index.spec.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与成本优化](#性能与成本优化)
8. [CI/CD 流水线配置](#cicd-流水线配置)
9. [监控与日志](#监控与日志)
10. [故障排除指南](#故障排除指南)
11. [结论](#结论)

## 简介
本文件面向运维与开发团队，系统化梳理 Cosmoe Bot 在 Cloudflare Workers 平台上的部署与运维实践，覆盖配置文件、环境变量、域名与证书、生产最佳实践（版本管理、回滚、监控告警）、CI/CD 自动化、性能与成本优化、日志与故障排查等主题。文档以仓库现有配置与源码为依据，避免臆测，确保可操作性与可追溯性。

## 项目结构
Cosmoe Bot 是一个基于 Cloudflare Workers 的 Telegram 机器人，采用 TypeScript 编写，通过 Wrangler 进行本地开发与部署。核心目录与职责如下：
- src/index.ts：Worker 入口，定义 fetch 与 scheduled 处理逻辑，初始化 Bot 并注册命令与定时任务。
- src/command/index.ts：命令与对话处理入口，集成 @grammyjs/conversations 与 @grammyjs/storage-cloudflare，使用 KV 存储会话状态。
- src/scheduler/index.ts：定时任务处理器，周期性拉取活动并推送通知给已注册用户。
- src/client/cosmoe.ts：封装对 Cosmoe API 的调用，统一响应结构与认证参数。
- wrangler.jsonc：Wrangler 配置文件，定义 Worker 名称、兼容日期、可观测性、计划任务、KV 绑定与环境变量。
- package.json：脚本与依赖，包含 wrangler、grammy、@grammyjs/conversations、@grammyjs/storage-cloudflare。
- .dev.vars：本地开发时的环境变量示例（如 BOT_TOKEN）。
- worker-configuration.d.ts：由 Wrangler 生成的类型声明，提供运行时类型支持。
- test/index.spec.ts：基于 @cloudflare/vitest-pool-workers 的单元/集成测试样例。

```mermaid
graph TB
A["wrangler.jsonc<br/>配置与计划任务"] --> B["src/index.ts<br/>入口与调度器"]
B --> C["src/command/index.ts<br/>命令与对话处理"]
B --> D["src/scheduler/index.ts<br/>定时任务"]
C --> E["src/client/cosmoe.ts<br/>外部 API 客户端"]
A --> F["KV 命名空间<br/>COSMOE_CREDENTIALS/COSMOE_STORAGE"]
A --> G[".dev.vars<br/>本地环境变量"]
A --> H["worker-configuration.d.ts<br/>类型声明"]
I["package.json<br/>脚本与依赖"] --> A
J["test/index.spec.ts<br/>测试样例"] --> B
```

图表来源
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L800)
- [package.json](file://package.json#L1-L24)
- [.dev.vars](file://.dev.vars#L1-L2)
- [test/index.spec.ts](file://test/index.spec.ts#L1-L25)

章节来源
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [package.json](file://package.json#L1-L24)

## 核心组件
- Worker 入口与路由
  - 初始化 Bot，解析环境变量中的 BOT_INFO 与 BOT_TOKEN，并设置命令菜单。
  - 使用 cloudflare-mod 模式回调适配 Telegram Webhook。
- 命令与对话
  - 注册 start、login、events、event_详情、book_预约、history、cancel、logout 等命令与回调。
  - 使用 @grammyjs/conversations 提供交互式对话；使用 @grammyjs/storage-cloudflare 将会话状态持久化到 KV。
- 定时任务
  - 每分钟触发一次，从 Cosmoe API 拉取活动列表，对比最新事件 ID，向已注册用户发送 Markdown 通知。
- 外部 API 客户端
  - 统一封装 getToken、getEvents、getEventDetail、getMyBookings、bookEvent、cancelBooking 等接口，统一响应结构。
- 配置与类型
  - wrangler.jsonc 定义名称、兼容日期、可观测性、计划任务、KV 绑定与 vars；worker-configuration.d.ts 提供运行时类型。

章节来源
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L800)

## 架构总览
下图展示从 Telegram 请求到 Worker、命令处理、KV 存储与外部 API 调用的整体流程。

```mermaid
sequenceDiagram
participant U as "用户"
participant T as "Telegram"
participant W as "Worker 入口(src/index.ts)"
participant CMD as "命令模块(src/command/index.ts)"
participant S as "定时模块(src/scheduler/index.ts)"
participant KV as "KV 命名空间"
participant API as "Cosmoe API 客户端(src/client/cosmoe.ts)"
U->>T : 发送命令/回调
T->>W : Webhook 请求
W->>CMD : 分发命令/对话
CMD->>KV : 读取/写入会话与用户凭证
CMD->>API : 调用外部 API
API-->>CMD : 返回数据
CMD-->>W : 处理结果
W-->>T : 回复消息
Note over S,KV : 每分钟触发
S->>API : 拉取活动列表
S->>KV : 读取/更新最新事件ID
S-->>T : 推送新活动通知
```

图表来源
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)

## 详细组件分析

### 配置文件与环境变量
- wrangler.jsonc 关键项
  - name：Worker 名称，用于在 Cloudflare 控制台识别与部署。
  - main：入口文件路径。
  - compatibility_date：运行时兼容日期，影响可用 API 与行为。
  - observability.enabled：开启可观测性（日志、度量、追踪）。
  - triggers.crons：计划任务表达式，当前为每分钟触发。
  - vars：环境变量绑定，例如 BOT_INFO 字符串。
  - kv_namespaces：KV 命名空间绑定，COSMOE_CREDENTIALS 用于存储用户凭证，COSMOE_STORAGE 用于会话与元数据。
- .dev.vars 与本地开发
  - 包含 BOT_TOKEN 示例，用于本地 wrangler dev 启动。
- worker-configuration.d.ts
  - 由 wrangler types 生成，提供运行时类型与上下文接口，便于在 IDE 中获得类型提示。

章节来源
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [.dev.vars](file://.dev.vars#L1-L2)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L800)

### Worker 入口与路由
- fetch 处理
  - 解析 BOT_INFO 与 BOT_TOKEN，初始化 Bot。
  - 注册命令菜单 setMyCommands。
  - 使用 webhookCallback("cloudflare-mod") 适配 Cloudflare 环境。
- scheduled 处理
  - 每分钟执行一次，初始化 Bot 并调用定时任务处理函数。

章节来源
- [src/index.ts](file://src/index.ts#L1-L47)

### 命令与对话处理
- 会话存储
  - 使用 @grammyjs/storage-cloudflare 的 KvAdapter，将对话状态存入 COSMOE_STORAGE。
  - 对读写异常进行捕获与日志输出。
- 命令与回调
  - start：显示帮助与可用命令。
  - login：交互式对话，输入用户名与密码，调用 CosmoeClient 获取 token 并保存至 COSMOE_CREDENTIALS。
  - events：列出活动。
  - event_详情：根据 /event_{id} 打开详情页。
  - book_预约：根据 /book_{event_id}_{slot_id} 下单。
  - history：查看预约历史。
  - cancel：根据 /cancel_{booking_id} 取消。
  - logout：清理账户信息。

章节来源
- [src/command/index.ts](file://src/command/index.ts#L1-L110)

### 定时任务
- 触发频率：每分钟一次。
- 逻辑要点
  - 从 COSMOE_STORAGE 读取 latestEventId。
  - 调用 CosmoeClient.getEvents 获取活动列表。
  - 过滤大于 latestEventId 的新活动。
  - 遍历 COSMOE_CREDENTIALS 中的用户键，逐个发送 Markdown 通知。
  - 更新最新事件 ID。

章节来源
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)

### 外部 API 客户端
- 统一响应结构 ApiResponse<T>，包含 code、msg、data。
- 支持的方法
  - getToken、getEvents、getEventDetail、getMyBookings、bookEvent、cancelBooking、updatePaymentOrder、updateBookingNote、selfReschedule、selfTransfer、register 等。
- 认证与参数
  - 多数接口需要 user_id 与 token，可通过 setCredentials 或 getToken 设置。
  - 参数使用 URLSearchParams 或 FormData 组装。

章节来源
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)

### 类型与上下文
- worker-configuration.d.ts 提供 ExportedHandler、ExecutionContext、KVNamespace 等类型，确保在本地与线上一致的类型体验。
- src/index.ts 与 src/command/index.ts 中的 Env 接口与 KV 命名空间绑定保持一致。

章节来源
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L800)
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)

## 依赖关系分析
- 组件耦合
  - src/index.ts 依赖 src/command/index.ts 与 src/scheduler/index.ts。
  - 命令模块依赖 KV 命名空间与 CosmoeClient。
  - 定时模块依赖 KV 与 CosmoeClient。
- 外部依赖
  - @grammyjs/conversations：对话插件。
  - @grammyjs/storage-cloudflare：KV 存储适配器。
  - grammy：Telegram Bot SDK。
  - wrangler：本地开发与部署工具。
- 运行时接口
  - KVNamespace、ExecutionContext、ExportedHandler 等类型来自 worker-configuration.d.ts。

```mermaid
graph LR
IDX["src/index.ts"] --> CMD["src/command/index.ts"]
IDX --> SCH["src/scheduler/index.ts"]
CMD --> KV["KV 命名空间"]
CMD --> API["src/client/cosmoe.ts"]
SCH --> KV
SCH --> API
WRG["wrangler.jsonc"] --> IDX
PKG["package.json"] --> WRG
```

图表来源
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [package.json](file://package.json#L1-L24)

章节来源
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L1-L503)
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [package.json](file://package.json#L1-L24)

## 性能与成本优化
- 计划任务频率
  - 当前每分钟一次，建议结合业务峰值与通知频率评估是否需要降低频率，减少不必要的请求与 KV 查询。
- KV 访问
  - 会话读写与用户列表遍历均走 KV，建议：
    - 合理分页与批量操作（若后续扩展）。
    - 对频繁访问的数据进行缓存策略设计（注意 KV 无内置 TTL，需自行实现过期机制）。
- API 调用
  - 外部 API 采用 GET/POST，建议：
    - 对返回数据进行必要的本地缓存（如活动列表），避免重复拉取。
    - 对错误与超时进行指数退避与重试。
- 日志与观测
  - 开启 observability.enabled 后，可在 Cloudflare Logs、Metrics 与 Tracing 中查看 Worker 行为，定位慢请求与异常。
- 成本控制
  - 控制计划任务频率与 KV 写入次数。
  - 使用 Cloudflare Analytics Engine（如启用）记录关键指标，避免冗余日志导致成本上升。

[本节为通用指导，不直接分析具体文件]

## CI/CD 流水线配置
以下为基于仓库现状的可落地实践建议（概念性说明，非仓库内现有配置）：
- 触发条件
  - 主分支保护：仅允许合并请求（MR）合并主分支。
  - 代码变更：任何对 src、wrangler.jsonc、package.json 的修改触发构建。
- 构建步骤
  - 安装依赖：npm ci
  - 类型生成：npm run cf-typegen
  - 单元测试：npm test
- 部署策略
  - 开发环境：自动部署到预发布命名空间（如 staging）。
  - 生产环境：手动批准后部署到 prod 命名空间。
- 版本与回滚
  - 使用 Git 标签作为版本号，部署时指定 --branch=标签名。
  - 回滚：通过 Wrangler 切换到上一个版本的部署记录。
- 监控与告警
  - 结合 Cloudflare Logs Insights 与 Metrics 设置阈值告警（如错误率、P95 延迟）。

[本节为通用指导，不直接分析具体文件]

## 监控与日志
- 日志采集
  - 使用 console.* 输出日志，配合 Wrangler 与 Cloudflare 控制台查看。
  - 定时任务与命令处理中均有日志输出点，便于定位问题。
- 指标与追踪
  - 开启 observability.enabled 后，可查看：
    - 请求量、错误率、响应时间分布。
    - Tail Traces 与 Tail Logs，定位慢请求与异常堆栈。
- 建议
  - 对关键路径（API 调用、KV 读写、消息发送）增加结构化日志字段（如 user_id、event_id、booking_id）。
  - 使用 Cloudflare Analytics Engine（如启用）记录自定义指标。

章节来源
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [wrangler.jsonc](file://wrangler.jsonc#L10-L12)

## 故障排除指南
- 部署失败
  - 检查 wrangler.jsonc 的 name、main、compatibility_date 是否正确。
  - 确认 KV 命名空间绑定与 id 是否匹配。
- 认证失败
  - 检查 .dev.vars 或生产环境中的 BOT_TOKEN 是否有效。
  - 确认 CosmoeClient.getToken 返回的 code 与 data 字段。
- 会话存储异常
  - 检查 COSMOE_STORAGE 的读写权限与键名格式。
  - 关注命令模块中的 KV 异常日志。
- 定时任务未触发
  - 检查 triggers.crons 表达式是否符合预期。
  - 查看 scheduled 处理器日志，确认执行路径。
- 命令菜单未生效
  - 确认 setMyCommands 的调用是否被拦截或抛错。
- 日志与观测
  - 通过 Cloudflare 控制台查看 Tail Logs 与 Tail Traces，定位异常。

章节来源
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [src/index.ts](file://src/index.ts#L1-L47)
- [src/command/index.ts](file://src/command/index.ts#L1-L110)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L1-L88)

## 结论
本文件基于仓库现有配置与源码，系统化梳理了 Cosmoe Bot 在 Cloudflare Workers 上的部署与运维要点。建议在现有基础上进一步完善 CI/CD、监控告警与成本优化策略，并持续关注 KV 与外部 API 的性能瓶颈，以提升稳定性与可维护性。