企业官网建设流程全解析

OpenStock 如何用迁移脚本把存量用户导入 ConvertKit 标签？

【免费下载链接】OpenStockOpenStock is an open-source alternative to expensive market platforms. Track real-time prices, set personalized alerts, and explore detailed company insights — built openly, for everyone, forever free.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenStock

OpenStock 的用户数据存放在 MongoDB 的user集合里，而邮件广播走 Kit（ConvertKit）。如果你已经有一批注册用户，想让这些人进入某个 Kit 标签、后续可以按标签群发，仓库提供了迁移脚本 scripts/migrate-users-to-kit.mjs：它从数据库逐批读取尚未迁移的用户，调用 ConvertKit 的POST https://api.convertkit.com/v3/tags/{tag_id}/subscribe接口把订阅者加入指定标签，并在数据库里打标记防止重复迁移。前提是你在项目根目录的.env中配置好三个环境变量，然后一条node命令完成导入。

脚本会做什么、不会做什么

先明确边界，再执行：

• 只处理user集合中有email字段且email非空、同时没有kitMigratedAt标记的用户（见 scripts/migrate-users-to-kit.mjs 中的查询条件）。
• 成功调用订阅接口后，脚本会写库：对应用户执行$set: { kitMigratedAt: new Date() }。也就是说运行脚本会修改你的 MongoDB 数据，并且会向 ConvertKit 实际写入订阅者。请确认MONGODB_URI指向的目标库是你打算迁移的库。
• 脚本内置限流保护：每批 5 个用户（BATCH_SIZE = 5），批间等待 2 秒（DELAY_MS = 2000），源码注释说明这是按 10 req/s 的安全余量设置的。遇到 429 或Retry later错误时会冷却 10 秒，该用户本次不写标记，留给下一次运行重试。
• API 返回 "already subscribed" 被视为成功。
• 用户没有name时，first_name自动用"Subscriber"兜底。

脚本还强制使用 IPv4 并把 DNS 指定为8.8.8.8（dns.setServers(['8.8.8.8'])），源码注释说明目的是避免连接错误，你的运行环境需要能访问8.8.8.8和api.convertkit.com。

准备条件

1. 已克隆仓库并完成基础安装（npm install），Node 环境满足脚本对fetch的要求——源码注释说明 Node 18+ 已自带全局 fetch，脚本仍显式引入了node-fetch以防版本较旧。
2. 在项目根目录创建.env（位置与 README 的 Environment Variables 章节一致），至少包含脚本启动时强制检查的三个变量：

MONGODB_URI=<你的 MongoDB 连接串> KIT_API_KEY=<你的 Kit API key> KIT_WELCOME_FORM_ID=<你的 Kit 表单 ID>

三者任一缺失，脚本会直接输出❌ Missing required env vars: MONGODB_URI, KIT_API_KEY, or KIT_WELCOME_FORM_ID并退出。KIT_WELCOME_FORM_ID只在此处做存在性检查，标签订阅请求本身不使用它；不知道表单 ID 时可以先跑只读的scripts/list-kit-forms.mjs，它会打印ID: ... | Name: ...的表单列表供你挑选。

3. 确认目标标签 ID。迁移脚本里标签 ID 是硬编码常量：

const TAG_ID = "15119471"; // OpenStock Users

这个值对应 OpenStock 项目自己的 "OpenStock Users" 标签。如果要把用户导入你自己账户下的标签，用仓库提供的 scripts/create-kit-tag.mjs 创建：它向POST https://api.convertkit.com/v3/tags提交一个名为 "OpenStock Users" 的标签，成功后打印✅ Created Tag ID: <新标签 ID>（此脚本只读KIT_API_KEY）。拿到 ID 后，把它替换进迁移脚本的TAG_ID常量再运行。沿用项目默认的15119471则是导入到 OpenStock 的标签。

执行迁移

在项目根目录运行：

node scripts/migrate-users-to-kit.mjs

运行期间观察控制台输出的判断逻辑：

• 🔌 Connecting to MongoDB...→✅ Connected.：数据库连接成功。
• Processing batch of N users...：开始处理一批，N 不超过 5。
• 每处理完一个用户输出一个字符：.表示成功并已写kitMigratedAt标记，x表示本次失败（不中断，继续下一个）。
• ⚠️ Rate Limit Hit. Cooling down for 10s...：触发限流，脚本自动等待后跳过该用户，等下次运行重试。
• 🎉 No more users to migrate!：没有待迁移用户了（首次运行就出现这条，说明库里所有用户都已有kitMigratedAt标记或没有带 email 的用户）。
• 结束时输出✅ Migration Complete. Total migrated: N，N 为本次运行成功迁移的总人数。

验证结果

• 看最终输出：Total migrated数值应接近你库中未标记用户的数量；出现x或有用户被限流跳过时，数字会偏小。
• 重跑一次验证幂等性：再次执行同一条命令，预期直接走到🎉 No more users to migrate!，不再产生新的迁移；如果失败用户较多，这次运行会重试那些未写标记的用户。
• 查数据库：迁移成功的用户文档上会多一个kitMigratedAt时间戳字段，用它可以在 MongoDB 中核对哪些用户已完成导入。
• 在 ConvertKit 后台确认标签下的订阅者数量与Total migrated相符（已存在的订阅者会被计为成功，不产生重复）。

限制与注意

• 标签 ID 硬编码在脚本里，换标签必须改代码中的TAG_ID常量；脚本不存在命令行参数来指定标签。
• 迁移的粒度是"用户 → 标签订阅者"，只传email和first_name（缺失时为Subscriber），不会迁移用户资料里的其他字段。
• 脚本失败不抛错、只输出x并继续，所以不能只看进程是否正常结束来判断全部成功，要结合x的数量和kitMigratedAt字段核对。
• 可选的前置连通性测试scripts/test-kit.mjs会向POST https://api.convertkit.com/v3/broadcasts发一封public: true的测试广播——它真的会给现有订阅者发送邮件，副作用明确，谨慎执行；lib/kit.ts 中的listSubscribers接口（GET /v3/subscribers）则需要KIT_API_SECRET，属于运行时功能，迁移脚本本身不需要。
• 项目对 Kit 的集成说明见 API_DOCS.md 的 "Email & Marketing: Kit (ConvertKit)" 章节，其中把POST /v3/tags/{tag_id}/subscribe标注为 User Migration 端点，鉴权使用KIT_API_KEY。

完成迁移后，后续新注册用户走的是应用内的运行时链路（lib/kit.ts的addSubscriber按表单订阅），而存量用户则通过本次脚本一次性进入标签，两条路径互不干扰。

【免费下载链接】OpenStockOpenStock is an open-source alternative to expensive market platforms. Track real-time prices, set personalized alerts, and explore detailed company insights — built openly, for everyone, forever free.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenStock