基于 Number-preservation 6.3 增强的 eSIM / 实体卡保号看板，支持 Telegram Bot 交互、Cloudflare KV 配置、GitHub Actions 自动部署、Webhook 自动设置、一键续期和按钮化平台管理。
本项目基于 GeniusZeroTwo 的 Number-preservation 改造和扩展，保留原项目主体框架，并在此基础上增加 Telegram Bot 管理能力、自动化部署说明和运行时配置说明。
上游原仓库：https://github.com/GeniusZeroTwo/Number-preservation
部署过程全程在网页端完成，小白也能在 5 分钟内搞定。
Fork NumberKeeper-Telegram 后，代码、README、wrangler.toml 和 .github/workflows/deploy.yml 会复制到你的仓库里，但 GitHub Secrets、GitHub Variables 和 Cloudflare KV 数据不会复制。
这意味着你第一次 Sync Fork、push 到 main，或者 GitHub 自动运行 Deploy Worker 时，可能会看到部署失败。最常见的原因不是代码坏了，而是新仓库还没有配置 CLOUDFLARE_KV_ID、CLOUDFLARE_API_TOKEN、TG_BOT_TOKEN 和 WORKER_URL。
如果日志里看到类似下面的内容：
kv_namespaces[0] bindings should have a string "id" field but got {"binding":"ESIM_DB","id":""}
说明 CLOUDFLARE_KV_ID 没有配置，或者配置值为空。把下面步骤 3 的 Secrets / Variables 补齐后，重新运行 Actions 的 Re-run jobs 即可；也可以等你下一次 push 到 main 时自动重新部署。
- 准备一个 Cloudflare 账号。
- 准备一个 Telegram 账号，搜索 @BotFather 发送 /newbot 创建一个机器人，记录下 Bot Token。
- 搜索 @userinfobot 发送任意消息，记录下你的数字 Chat ID。
- 主动给你刚建的机器人发送任意一条消息激活它（机器人不能主动发起会话）。
- 登录 Cloudflare 控制台，左侧菜单找到 Workers & Pages -> KV。
- 点击 Create a namespace，命名为 esim_db，点击添加。
- 创建成功后，复制它旁边长长的一串 ID（比如 09fe63fac...）备用。
-
将本项目 Fork 到你自己的 GitHub 账号下。
-
在你 Fork 后的仓库中，打开 wrangler.toml 文件。
-
确认最下方的 KV 配置保持占位符形式，不要写死你的真实 KV ID：
[[kv_namespaces]] binding = "ESIM_DB" id = "${KV_ID}"
-
不要把自己的真实 KV ID 提交到代码里。真实 KV ID 后面会放到 GitHub Secrets，由 GitHub Actions 在部署前自动替换。
这样做的好处是：以后你同步原作者仓库更新时，wrangler.toml 不需要反复手动改 ID，也不会把个人配置写进公开代码。
项目使用 .github/workflows/deploy.yml 自动部署到 Cloudflare。这个文件不会保存你的真实密钥，而是从 GitHub Secrets 中读取。
新环境部署时，这一步必须重新配置。GitHub 不会把原仓库的 Secrets / Variables 复制到你的 Fork 或新仓库。
进入你自己的 GitHub 仓库页面，按下面步骤配置：
-
点击顶部的 Settings。
-
左侧找到 Secrets and variables，展开后点击 Actions。
-
点击 New repository secret，添加第一个密钥：
Name: CLOUDFLARE_KV_ID Secret: 你的 Cloudflare KV Namespace ID -
再点击 New repository secret，添加第二个密钥：
Name: CLOUDFLARE_API_TOKEN Secret: 你的 Cloudflare API Token -
再点击 New repository secret，添加第三个密钥：
Name: TG_BOT_TOKEN Secret: 你的 Telegram Bot Token -
切换到 Variables，点击 New repository variable，添加 Worker 访问地址：
Name: WORKER_URL Value: https://你的 Worker 域名示例：
https://esim-api.xxx.workers.dev
CLOUDFLARE_KV_ID 用来替换 wrangler.toml 里的 ${KV_ID}。CLOUDFLARE_API_TOKEN 用来授权 GitHub Actions 把 Worker 部署到你的 Cloudflare 账号。TG_BOT_TOKEN 和 WORKER_URL 用来在部署完成后自动设置 Telegram Webhook。
Cloudflare API Token 建议使用最小权限：能编辑 Workers，并能读取账号资源。Telegram Bot Token 和 Cloudflare API Token 都只保存到 GitHub Secrets，不要写进 README、代码或聊天记录。
配置位置对应关系：
| 配置项 | 放在哪里 | 用途 |
|---|---|---|
CLOUDFLARE_KV_ID |
GitHub Actions Secret | 部署前替换 wrangler.toml 里的 ${KV_ID}。 |
CLOUDFLARE_API_TOKEN |
GitHub Actions Secret | 授权 GitHub Actions 部署 Cloudflare Worker。 |
TG_BOT_TOKEN |
GitHub Actions Secret | 部署后自动调用 Telegram setWebhook。 |
WORKER_URL |
GitHub Actions Variable | 生成 Webhook 地址，例如 https://你的域名/api/telegram/webhook。 |
TG_BOT_TOKEN |
Cloudflare KV | Worker 运行时给 Telegram 发送消息。 |
TG_CHAT_ID |
Cloudflare KV | 限制只有你的 Telegram 账号能操作机器人。 |
.github/workflows/deploy.yml 是 GitHub Actions 自动部署脚本。你向 main 分支推送代码，或者 Sync Fork 后产生新的提交时，它会自动执行。
当前流程做了四件事：
-
拉取仓库代码：
- name: Checkout Code uses: actions/checkout@v4
-
部署前把
wrangler.toml里的${KV_ID}替换成 GitHub Secrets 里的真实 KV ID：- name: Replace KV ID Placeholder run: sed -i 's/${KV_ID}/${{ secrets.CLOUDFLARE_KV_ID }}/g' wrangler.toml
-
使用 Cloudflare 官方 wrangler-action 部署 Worker：
- name: Deploy to Cloudflare Workers uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-
部署完成后自动设置 Telegram Webhook：
- name: Set Telegram Webhook env: TG_BOT_TOKEN: ${{ secrets.TG_BOT_TOKEN }} WORKER_URL: ${{ vars.WORKER_URL }} run: | WEBHOOK_URL="${WORKER_URL%/}/api/telegram/webhook" curl --fail --show-error --silent --request POST "https://api.telegram.org/bot${TG_BOT_TOKEN}/setWebhook" \ --data-urlencode "url=${WEBHOOK_URL}" echo "Telegram webhook set to ${WEBHOOK_URL}"
所以日常更新时，你只需要把代码推送到自己的 GitHub 仓库，GitHub Actions 会自动完成 KV ID 替换、Worker 部署和 Telegram Webhook 设置。
如果 Fork 后第一次 Deploy Worker 失败，先看失败位置：
| 失败位置 | 常见原因 | 处理方式 |
|---|---|---|
Replace KV ID Placeholder 后 id = "" |
CLOUDFLARE_KV_ID 没有配置或为空 |
回到步骤 3 添加 GitHub Secret。 |
Deploy to Cloudflare Workers 报认证失败 |
CLOUDFLARE_API_TOKEN 没有配置、填错或权限不足 |
重新创建 Cloudflare API Token，并保存到 GitHub Secret。 |
Set Telegram Webhook 失败 |
TG_BOT_TOKEN 或 WORKER_URL 没有配置 |
补齐 GitHub Secret TG_BOT_TOKEN 和 Variable WORKER_URL。 |
| Telegram 机器人不回复 | Cloudflare KV 没有 TG_BOT_TOKEN 或 TG_CHAT_ID |
回到步骤 6，在 KV 中添加运行时配置。 |
补齐配置后有两种方式重新部署：
- 在 GitHub Actions 失败记录里点击
Re-run jobs。 - 向
main分支推送一次新提交，让 workflow 自动重新运行。
如果你已经确认 origin 或 Cloudflare Pages/Workers 正在部署，不需要额外重新部署，只要保证新环境的 Secrets、Variables 和 KV 已经补齐即可。
- 在 Cloudflare 左侧菜单点击 Workers & Pages -> Overview。
- 点击右上角 Create Application，选择 Workers 选项卡，然后点击 Connect to Git。
- 授权连接你的 GitHub 账号，选择你刚刚 Fork 的仓库。
- 关键配置（Setup build 区域）：
- Root directory (根目录)：留空
- Build command (构建命令)：留空
- Entry point (入口点)：手动输入 worker/worker.js
- 点击 Save and Deploy，等待系统部署完成（出现绿色对勾），点击 Continue to project。
如果你已经配置了 GitHub Actions，也可以直接向 main 分支 push 代码，让 .github/workflows/deploy.yml 自动部署。
由于 Cloudflare 的环境变量偶尔会有部署延迟的 Bug，我们直接将验证密钥存入 KV 数据库，100% 稳定触发：
- 回到 Cloudflare 左侧菜单，找到 Workers & Pages -> KV。
- 点击进入你在步骤 1 创建的 esim_db 详情页。
- 点击顶部的 KV Entries (KV 条目) 选项卡。
- 在此处手动添加两条数据：
- Key (键) 填 TG_BOT_TOKEN，Value (值) 填你的机器人 Token。点击 Add (添加)。
- Key (键) 填 TG_CHAT_ID，Value (值) 填你的数字 ID。点击 Add (添加)。
如果你已经按步骤 3 配置了 TG_BOT_TOKEN 和 WORKER_URL，GitHub Actions 会在每次部署后自动设置 Webhook，通常不用手动打开链接。
如果你想手动设置，或需要排查自动设置是否成功，可以继续使用下面的备用方法。
-
先确认 Worker 已经部署成功，并记下你的 Worker 访问地址，例如：
https://esim-api.xxx.workers.dev -
在浏览器打开下面的链接，把
<TG_BOT_TOKEN>换成你的机器人 Token，把<你的Worker域名>换成上面的 Worker 地址：https://api.telegram.org/bot<TG_BOT_TOKEN>/setWebhook?url=<你的Worker域名>/api/telegram/webhook -
如果返回类似下面的内容，就表示 Webhook 设置成功：
{"ok":true,"result":true,"description":"Webhook was set"} -
安全限制：机器人只处理
TG_CHAT_ID对应用户发来的消息。其他人就算知道机器人，也不能添加或查看你的号码数据。 -
如果要检查当前 Webhook 是否已经设置成功，可以打开：
https://api.telegram.org/bot<TG_BOT_TOKEN>/getWebhookInfo
由于密钥直接存入了数据库，配置会立即生效，无需等待！
现在访问 Cloudflare 为你分配的 Worker 域名（例如 https://esim-api.xxx.workers.dev），点击“向 TG 机器人获取验证码”，开始享受你的保号面板吧！
也可以打开 Telegram，向你的机器人发送 /start 查看欢迎说明和添加号码流程，或发送 /help 查看可用命令。
正式使用前，按下面顺序检查：
- Cloudflare KV namespace 已创建，并拿到了 KV ID。
- GitHub Secret
CLOUDFLARE_KV_ID已填写真实 KV ID。 - GitHub Secret
CLOUDFLARE_API_TOKEN已填写可部署 Worker 的 API Token。 - GitHub Secret
TG_BOT_TOKEN已填写 Telegram Bot Token。 - GitHub Variable
WORKER_URL已填写你的 Worker 访问地址。 - Cloudflare KV 已添加
TG_BOT_TOKEN。 - Cloudflare KV 已添加
TG_CHAT_ID。 - GitHub Actions 的
Deploy Worker已成功运行。 - Telegram
getWebhookInfo显示 webhook 指向<WORKER_URL>/api/telegram/webhook。 - Telegram 中
/start、/help、/list、/add、/renew、/platform可正常使用。
设置 Webhook 后，Telegram 机器人不仅能接收登录验证码和到期提醒，还可以直接管理保号数据。机器人写入的数据会保存到同一个 KV key：esim_list，所以网页端和 Telegram 端看到的是同一份号码列表。
安全规则：机器人只处理 TG_CHAT_ID 对应账号发来的消息，其他 Chat ID 会被直接忽略，不会回复，也不会写入数据。
/start 查看欢迎说明
/help 查看可用命令
/list 查看当前号码列表
/add 按步骤添加一个新号码
/renew 一键续期，使用 /renew 序号 快速操作
/skip 跳过当前选填字段
/site 显示网站访问链接
/platform 按钮化管理已注册平台
/cancel 取消当前未完成的添加流程
| 命令 | 作用 |
|---|---|
/start |
显示欢迎说明、完整添加号码流程，并含导航按钮。 |
/help |
只显示可用命令列表，并含导航按钮。 |
/list |
查看当前已保存的号码列表，包括卡片名称、号码、到期日、周期、平台和备注，并含导航按钮。 |
/add |
启动逐步添加号码流程。每步提示和错误校验都含导航按钮，方便随时跳转。 |
/renew |
一键续期，/renew（无参数）显示列表并含导航按钮；/renew 序号 直接续期，不含按钮。 |
/skip |
在选填字段中跳过当前项，只能用于手机号、已注册平台、备注 / 保号要求。 |
/site |
显示网页看板访问链接。 |
/platform |
打开按钮化平台管理入口，可新增、删除、重命名或清空某个号码的已注册平台。 |
/cancel |
取消当前未完成的添加流程，并清理临时会话。 |
发送 /start、/help、/list、/site、/renew（无参数）、/platform 或 /add 流程中，机器人回复下方都会常驻导航按钮：
[添加号码] [查看列表]
[打开网站] [帮助]
[一键续期] [修改平台]
按钮对应动作：
| 按钮 | 等同命令 |
|---|---|
| 添加号码 | /add |
| 查看列表 | /list |
| 打开网站 | /site |
| 帮助 | /help |
| 一键续期 | /renew |
| 修改平台 | /platform |
按钮只是快捷入口，不会改变原有命令。以下命令回复不带导航按钮：
/renew N续期结果/cancel取消确认
机器人每天会在授权用户首次交互时，额外显示一次底部输入框旁的 /start 按钮。这个按钮使用 Telegram 的一次性键盘，点击或使用后会自动收起；同一天不会重复显示，第二天再次交互时会重新出现一次。
发送 /start 可以查看完整添加号码流程说明。
发送 /add 后，机器人会按下面 6 步询问：
-
卡片名称：必填。
示例：KnowRoaming。
-
手机号：选填。
示例：+1 234 567 8900。
如果不想填写，发送
/skip跳过。 -
保号周期：必填，输入大于 0 的整数。
示例：180。
-
到期日：必填，格式为
YYYY-MM-DD。示例：2026-12-31。
-
已注册平台：选填。
多个平台请用空格或英文逗号分隔。
示例：Telegram Google OpenAI。
或：Telegram, Google, OpenAI。
如果不想填写，发送
/skip跳过。 -
备注 / 保号要求：选填。
示例：半年发一次短信。
如果不想填写，发送
/skip跳过。
填写完成后，机器人会发送汇总信息。回复 确认 保存，回复 取消 或发送 /cancel 放弃。
如果周期或日期格式不正确，机器人会提示错误，并停留在当前步骤，不会保存错误数据。
| 字段 | 是否必填 | 输入规则 |
|---|---|---|
| 卡片名称 | 必填 | 不能为空，例如 KnowRoaming。 |
| 手机号 | 选填 | 建议带国际区号，例如 +1 234 567 8900；不填时发送 /skip。 |
| 保号周期 | 必填 | 必须是大于 0 的整数，例如 180。 |
| 到期日 | 必填 | 必须是 YYYY-MM-DD 格式，例如 2026-12-31。 |
| 已注册平台 | 选填 | 多个平台用空格或英文逗号分隔，例如 Telegram Google OpenAI 或 Telegram, Google, OpenAI；不填时发送 /skip。 |
| 备注 / 保号要求 | 选填 | 可填写保号动作、注意事项、充值要求等；不填时发送 /skip。 |
你：/add
机器人：第 1/6 步：卡片名称
你：KnowRoaming
机器人：第 2/6 步：手机号
你：/skip
机器人：第 3/6 步：保号周期
你：180
机器人：第 4/6 步：到期日
你：2026-12-31
机器人：第 5/6 步：已注册平台
你：Telegram, Google, OpenAI
机器人：第 6/6 步：备注/保号要求
你：半年发一次短信
机器人：请确认新增号码信息
你：确认
保存成功后，新号码会立即出现在网页看板中，也会参与后续 Cron 到期提醒。
- 每次
/add会创建一个临时添加会话。 - 如果流程还没结束，再次发送
/add，机器人会提醒你先继续填写或发送/cancel取消。 - 当前流程可随时发送
/cancel或回复取消放弃。 - 周期格式错误时，机器人会要求重新输入大于 0 的整数。
- 日期格式错误时，机器人会要求重新输入
YYYY-MM-DD格式日期。 - 非授权账号发送命令时，机器人不会回复，也不会写入 KV。
一键续期命令可以快速延长到期日，以今天为基准顺延保号周期天数。
/renew— 显示号码列表，回复序号直接续期/renew 序号— 直接续期，无需二次确认
例如：
你：/renew 1
机器人：✅ KnowRoaming 已续期至 2026-12-01
你：/renew
机器人：选择要续期的号码
1. KnowRoaming | 2026-12-31 | 180 天
回复序号直接续期，例如 /renew 1
注意：
- 序号从 1 开始，对应
/list显示的列表顺序。 - 续期不会修改名称、号码、平台、备注等字段。
- 如果未设置有效保号周期（cycle），需要先在网页端编辑后使用。
/platform 用来管理某个号码已经注册过的平台。这个功能以按钮为主，不需要记复杂命令。
发送 /platform 后，机器人会先显示号码列表，并提示你点击号码进入平台管理页：
请选择要管理已注册平台的号码。
点击下面的号码进入平台管理页。
[1. KnowRoaming]
[2. Firsty]
进入某个号码后，机器人会显示当前平台和可用操作：
KnowRoaming 当前已注册平台：
1. Telegram
2. Google
3. OpenAI
你可以通过下面按钮新增、删除、重命名或清空平台。
按钮包括：
[新增平台]
[删除 Telegram] [删除 Google]
[删除 OpenAI]
[重命名平台]
[清空平台]
[返回号码列表]
新增平台时，点击 [新增平台] 后按提示输入平台名。可以一次输入一个，也可以一次输入多个：
Claude GitHub OpenRouter
多个平台请用空格或英文逗号分隔。保存后机器人会立即刷新当前平台列表，新的平台也会立刻出现在删除按钮中。
删除平台时，直接点击对应的 [删除 平台名] 按钮即可。删除后机器人会刷新列表，已删除的平台按钮会消失。
重命名平台时，点击 [重命名平台]，再点击要修改的平台，然后输入新名称。例如把 Google 改成：
Google Voice
清空平台时，点击 [清空平台] 后机器人会先二次确认，确认后才会清空，避免误触。
如果输入 /platform 1 add Claude 这类旧式命令，机器人不会执行修改，只会提示你使用按钮操作。
发送 /site 后，机器人会返回网页看板地址（你的 worker 访问地址）：
https://esim-api.xxx.workers.dev
本项目基于 MIT License 开源。您可以自由使用、修改和分发，但请保留原作者信息。如果您觉得好用，请帮忙点个 ⭐ Star！