# 部署配置

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

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 Cosmoe Bot 的部署与运维人员，系统化解读 wrangler.jsonc 配置文件的各项参数，说明 KV 命名空间的配置与绑定、环境变量的配置方法（尤其是 BOT_INFO 的格式与内容）、本地开发与生产部署流程，并提供配置验证与调试建议，帮助快速、稳定地完成从本地到生产的全流程部署。

## 项目结构
Cosmoe Bot 是一个基于 Cloudflare Workers 的 Telegram Bot，采用 TypeScript 编写，通过 Wrangler 进行本地开发与生产部署。项目主要由以下部分组成：
- 配置层：wrangler.jsonc 定义 Worker 名称、入口文件、兼容性日期、可观测性、定时触发器、KV 命名空间与变量等。
- 运行时层：src/index.ts 作为 Worker 入口，处理 HTTP 请求与计划任务；src/command/index.ts 注册命令与会话；src/scheduler/index.ts 处理定时任务。
- 数据层：通过 KV 命名空间 COSMOE_CREDENTIALS 存储用户凭证，COSMOE_STORAGE 存储会话与状态数据。
- 工具层：.dev.vars 提供本地开发所需的 BOT_TOKEN；package.json 提供脚本与依赖；worker-configuration.d.ts 为类型生成文件。

```mermaid
graph TB
subgraph "配置层"
WJ["wrangler.jsonc"]
DV[".dev.vars"]
PJ["package.json"]
end
subgraph "运行时层"
IDX["src/index.ts"]
CMD["src/command/index.ts"]
SCH["src/scheduler/index.ts"]
end
subgraph "数据层"
KV1["KV: COSMOE_CREDENTIALS"]
KV2["KV: COSMOE_STORAGE"]
end
subgraph "工具层"
WT["worker-configuration.d.ts"]
end
WJ --> IDX
WJ --> CMD
WJ --> SCH
WJ --> KV1
WJ --> KV2
DV --> IDX
PJ --> IDX
WT --> IDX
CMD --> KV2
SCH --> KV1
SCH --> KV2
```

**图表来源**
- [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)

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

## 核心组件
- Worker 入口与路由：src/index.ts 负责初始化 Bot、注册命令、设置命令菜单，并通过 webhookCallback 将请求交由 grammY 处理；同时实现 scheduled 回调用于定时任务。
- 命令系统与会话：src/command/index.ts 使用 @grammyjs/conversations 插件，结合 KV 命名空间 COSMOE_STORAGE 实现对话状态持久化。
- 定时任务：src/scheduler/index.ts 每分钟检查新活动并通知已注册用户。
- KV 命名空间：COSMOE_CREDENTIALS 用于存储用户的 Cosmoe 凭证（用户 ID 与令牌），COSMOE_STORAGE 用于存储会话与状态（如最新活动 ID）。
- 环境变量：BOT_INFO 为 Bot 信息（JSON 字符串），BOT_TOKEN 为 Telegram Bot 访问令牌（本地开发使用）。

**章节来源**
- [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)

## 架构总览
下图展示了从请求进入 Worker 到 KV 存取与定时任务执行的整体流程。

```mermaid
sequenceDiagram
participant TG as "Telegram"
participant WR as "Worker 入口<br/>src/index.ts"
participant CMD as "命令注册<br/>src/command/index.ts"
participant KV1 as "KV : COSMOE_CREDENTIALS"
participant KV2 as "KV : COSMOE_STORAGE"
participant SCH as "定时任务<br/>src/scheduler/index.ts"
TG->>WR : "HTTP 请求webhook"
WR->>CMD : "setupCommands(bot, env)"
CMD->>KV2 : "读取/写入会话状态"
WR-->>TG : "响应消息"
SCH->>KV2 : "读取最新活动 ID"
SCH->>KV1 : "枚举已注册用户"
SCH-->>TG : "发送新活动通知"
```

**图表来源**
- [src/index.ts](file://src/index.ts#L13-L46)
- [src/command/index.ts](file://src/command/index.ts#L20-L52)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L12-L88)

## 详细组件分析

### wrangler.jsonc 配置详解
- schema 与名称：$schema 指向 Wrangler 配置校验文件；name 为 "cosmoe-bot"。
- 入口与兼容性：main 指向 src/index.ts；compatibility_date 设为 2025-09-27，确保运行时 API 的稳定性。
- 可观测性：observability.enabled=true 开启可观测性（日志、追踪等）。
- 定时触发器：triggers.crons 设置为每分钟一次（"*/1 * * * *"），对应 Worker 的 scheduled 回调。
- 环境变量 vars：BOT_INFO 为 Bot 信息的 JSON 字符串，包含机器人元数据（如 id、username、是否支持内联查询等）。
- KV 命名空间：kv_namespaces 定义两个命名空间
  - COSMOE_CREDENTIALS：用于存储用户凭证（键为 Telegram 用户 ID，值为包含 user_id、token、timestamp 的 JSON）。
  - COSMOE_STORAGE：用于存储会话状态与系统状态（如 latestEventId）。

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

### KV 命名空间配置与绑定
- 绑定名称：COSMOE_CREDENTIALS、COSMOE_STORAGE 在 wrangler.jsonc 中定义，并在运行时通过 Env 接口暴露给 Worker。
- 使用场景：
  - 登录流程：用户输入用户名/密码后，调用 Cosmoe API 获取 token，然后以 Telegram 用户 ID 为键存入 COSMOE_CREDENTIALS。
  - 历史查询：根据 Telegram 用户 ID 从 COSMOE_CREDENTIALS 读取凭证，构造 CosmoeClient 并查询预约历史。
  - 定时通知：从 COSMOE_STORAGE 读取 latestEventId，遍历 COSMOE_CREDENTIALS 中所有已注册用户，逐个发送新活动通知，并更新最新活动 ID。

```mermaid
flowchart TD
Start(["开始"]) --> ReadLatest["读取 COSMOE_STORAGE 中的 latestEventId"]
ReadLatest --> FetchEvents["调用 Cosmoe API 获取活动列表"]
FetchEvents --> FilterNew{"筛选新活动"}
FilterNew --> |是| ListUsers["枚举 COSMOE_CREDENTIALS 所有用户"]
FilterNew --> |否| End(["结束"])
ListUsers --> Notify["逐个用户发送新活动通知"]
Notify --> UpdateId["更新 COSMOE_STORAGE 中的 latestEventId"]
UpdateId --> End
```

**图表来源**
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L24-L84)

**章节来源**
- [wrangler.jsonc](file://wrangler.jsonc#L21-L30)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L49-L65)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L13-L29)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L24-L84)

### 环境变量配置
- BOT_INFO：在 wrangler.jsonc 的 vars 中配置，为 JSON 字符串，包含机器人元数据（如 id、username、是否支持内联查询等）。运行时通过 env.BOT_INFO 读取并解析为对象传入 Bot 初始化。
- BOT_TOKEN：在 .dev.vars 中配置，用于本地开发时的 Telegram Bot 访问令牌。生产环境建议通过 Wrangler 的 secrets 或环境变量注入，避免明文保存在仓库中。

**章节来源**
- [wrangler.jsonc](file://wrangler.jsonc#L18-L20)
- [.dev.vars](file://.dev.vars#L1-L2)
- [src/index.ts](file://src/index.ts#L19-L19)

### 本地开发环境配置
- .dev.vars：包含 BOT_TOKEN=your_token，用于本地开发服务器启动时注入。
- 启动命令：package.json 提供 dev 与 start 脚本，均指向 wrangler dev，启动本地开发服务器。
- 类型生成：cf-typegen 脚本用于生成 worker-configuration.d.ts，确保 Env 接口与实际绑定一致。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Wr as "Wrangler 开发服务器"
participant Bot as "Bot 实例"
participant KV as "KV 命名空间"
Dev->>Wr : "npm run dev/start"
Wr->>Bot : "加载 .dev.vars 注入 BOT_TOKEN"
Bot->>KV : "读取/写入会话与凭证"
Wr-->>Dev : "本地可访问的 Webhook 地址"
```

**图表来源**
- [package.json](file://package.json#L5-L11)
- [.dev.vars](file://.dev.vars#L1-L2)
- [src/index.ts](file://src/index.ts#L19-L19)

**章节来源**
- [package.json](file://package.json#L5-L11)
- [.dev.vars](file://.dev.vars#L1-L2)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L10)

### 生产环境部署流程
- 代码构建：项目为纯前端/运行时代码，无需额外编译；wrangler 会自动打包 main 指向的入口文件。
- 部署命令：package.json 提供 deploy 脚本，直接执行 wrangler deploy。
- 环境变量注入：
  - BOT_INFO：已在 wrangler.jsonc 中配置。
  - BOT_TOKEN：建议通过 Wrangler secrets 或环境变量注入，避免明文提交。
- KV 命名空间：确保在 Cloudflare 控制台中创建并绑定 COSMOE_CREDENTIALS 与 COSMOE_STORAGE，且与 wrangler.jsonc 中的 id 一致。

**章节来源**
- [package.json](file://package.json#L6-L6)
- [wrangler.jsonc](file://wrangler.jsonc#L18-L30)

## 依赖关系分析
- 配置到运行时：wrangler.jsonc 决定 Worker 的入口、触发器、KV 绑定与变量；src/index.ts 作为入口文件，依赖这些配置。
- 运行时到数据：src/command/index.ts 与 src/scheduler/index.ts 通过 KV 命名空间进行数据持久化与共享。
- 类型与配置：worker-configuration.d.ts 由 wrangler types 生成，确保 Env 接口与实际绑定一致。

```mermaid
graph LR
WJ["wrangler.jsonc"] --> IDX["src/index.ts"]
WJ --> CMD["src/command/index.ts"]
WJ --> SCH["src/scheduler/index.ts"]
IDX --> CMD
CMD --> KV["KV 命名空间"]
SCH --> KV
WT["worker-configuration.d.ts"] --> IDX
```

**图表来源**
- [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)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L10)

**章节来源**
- [wrangler.jsonc](file://wrangler.jsonc#L1-L31)
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L10)

## 性能考量
- 定时任务频率：当前设置为每分钟一次，适合高频推送场景；若活动更新不频繁，可考虑降低频率以减少 KV 查询与 Telegram API 调用开销。
- KV 访问模式：登录与历史查询均按用户 ID 键访问；定时任务遍历用户列表时注意 KV list 的性能与配额限制。
- 会话存储：对话状态通过 KVAdapter 写入 COSMOE_STORAGE，建议控制单条会话数据大小，避免超限。

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

## 故障排查指南
- 配置校验
  - 使用 wrangler 的类型生成与校验：运行 cf-typegen 生成 worker-configuration.d.ts，确保 Env 接口与 KV 绑定一致。
  - 检查 wrangler.jsonc 的 compatibility_date 是否与目标运行时匹配。
- KV 读写问题
  - 登录失败：确认 COSMOE_CREDENTIALS 的键为 Telegram 用户 ID，值为包含 user_id、token、timestamp 的 JSON。
  - 历史查询失败：确认 COSMOE_CREDENTIALS 中存在该用户的凭证，且凭证有效。
  - 定时通知未发送：检查 COSMOE_STORAGE 中的 latestEventId 是否正确更新，以及 COSMOE_CREDENTIALS 中是否存在用户。
- 环境变量问题
  - BOT_INFO 解析失败：确认其为合法 JSON 字符串，字段齐全。
  - BOT_TOKEN 未生效：确认在本地开发时 .dev.vars 正确注入，在生产环境通过 secrets 注入。
- 日志与可观测性
  - 启用 observability 后，可在 Cloudflare Workers 控制台查看日志与追踪，定位异常。

**章节来源**
- [worker-configuration.d.ts](file://worker-configuration.d.ts#L1-L10)
- [wrangler.jsonc](file://wrangler.jsonc#L10-L12)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L49-L65)
- [src/command/handlers/history.ts](file://src/command/handlers/history.ts#L13-L29)
- [src/scheduler/index.ts](file://src/scheduler/index.ts#L24-L84)

## 结论
通过合理配置 wrangler.jsonc、规范使用 KV 命名空间与环境变量、遵循本地开发与生产部署流程，Cosmoe Bot 可以稳定运行于 Cloudflare Workers 平台。建议在生产环境中严格管理密钥与变量，优化定时任务频率，并持续关注可观测性输出以提升运维效率。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 配置参数速查表
- 项目基本信息
  - name：cosmoe-bot
  - main：src/index.ts
  - compatibility_date：2025-09-27
- 可观测性
  - observability.enabled：true
- 定时触发器
  - triggers.crons：*/1 * * * *
- 环境变量
  - vars.BOT_INFO：JSON 字符串，包含机器人元数据
  - vars.BOT_TOKEN：本地开发令牌（建议生产环境通过 secrets 注入）
- KV 命名空间
  - COSMOE_CREDENTIALS：存储用户凭证（键为 Telegram 用户 ID，值为 JSON）
  - COSMOE_STORAGE：存储会话与系统状态（如 latestEventId）

**章节来源**
- [wrangler.jsonc](file://wrangler.jsonc#L7-L30)
- [src/index.ts](file://src/index.ts#L6-L11)