从 LeanCloud 迁移 | Artitalk.js

迁移说明

Artitalk 4.0.0 使用部署在 Vercel 上的服务端和 Neon Postgres 数据库，不再直接连接 LeanCloud。本页说明如何将旧版 Artitalk 中的说说和评论迁移到新服务端。

迁移过程只导入以下两个 Class：

LeanCloud Class	内容	导出文件
`shuoshuo`	已发布的说说	`shuoshuo.0.jsonl`
`atComment`	说说评论	`atComment.0.jsonl`

旧 LeanCloud _User 中的账号、密码和会话不会迁移。新服务端的管理员账户需要通过 Vercel 环境变量重新创建。

迁移前请注意

迁移入口用于全新的 Neon 数据库。不要先在新服务端发布正式数据，否则可能出现数据混合或同一 objectId 的记录被覆盖。

迁移完成并验证无误前，不要删除 LeanCloud 应用。请保留原始导出压缩包和 JSONL 文件作为备份。

一、迁移前准备

开始前请准备：

可以访问旧 Artitalk LeanCloud 应用的账号。
一个 GitHub 账号和一个 Vercel 账号。
一个用于 Artitalk 的 Neon Postgres 数据库。
新管理员的用户名和密码。
旧站点中使用的 LeanCloud shuoshuo 和 atComment Class。

建议先记录旧站点中的说说数量和评论数量，迁移后用于核对：

登录 LeanCloud 控制台并进入旧 Artitalk 应用。
打开 数据存储。
分别查看 shuoshuo 和 atComment Class 中的记录数量。
截图或记录数量。

如果不存在 atComment Class，说明旧站点没有启用评论或没有评论数据，后续可以创建一个空的 atComment.0.jsonl 文件。

二、从 LeanCloud 导出数据

LeanCloud 不同控制台版本的菜单名称可能略有差异，一般可以按以下步骤操作：

登录 LeanCloud 控制台。
选择旧 Artitalk 使用的应用。
在应用设置或数据存储相关页面中找到 导入导出、数据导出 或类似入口。
创建一次数据导出任务，导出应用数据。
等待导出任务完成，然后通过控制台或通知邮件下载导出压缩包。
解压下载的文件，并找到：
- shuoshuo.0.jsonl
- atComment.0.jsonl

Tips

导出压缩包中可能包含 _User、_Role 等其他文件。Artitalk 迁移页面只需要 shuoshuo.0.jsonl 和 atComment.0.jsonl，不要上传整个压缩包。

如果导出的文件名带有不同的数字分片，例如 shuoshuo.1.jsonl，说明数据可能被拆分为多个文件。当前网页迁移入口一次只接收一个说说文件和一个评论文件，应先确认主要数据是否都在 .0.jsonl 中，避免遗漏分片。

没有评论数据

迁移页面要求选择两个文件。如果旧应用没有 atComment Class 或导出包中没有评论文件，请新建一个空文本文件，并命名为：

atComment.0.jsonl

文件内容保持为空，不要写入 []、{} 或其他占位内容。

三、部署 Vercel 服务端

可以使用一键部署：

也可以 Fork ArtitalkServer，然后在 Vercel 中导入仓库。

在 Vercel 项目的 Environment Variables 中配置：

变量名	必填	说明
`ADMIN_USERNAME`	是	迁移后创建的新管理员用户名。
`ADMIN_PASSWORD`	是	新管理员密码。
`ADMIN_IMG`	否	管理员头像 URL。
`ADMIN_IMG_Token`	否	S.EE 图床 Token；不配置时无法上传文件。
`ALLOW_ORIGIN`	建议	允许访问服务端的站点来源，例如 `https://blog.example.com`。

敏感信息只能保存在 Vercel 环境变量中，不要写入博客页面、Artitalk 前端配置或 Git 仓库。

四、连接 Neon 数据库

推荐在 Vercel 的 Storage 页面创建或连接 Neon 数据库：

打开 Vercel 团队或账号的 Storage 页面。
创建或选择一个 Neon Postgres 数据库。
将数据库连接到刚部署的 Artitalk 服务端项目。
至少勾选 Production 环境。
将 Custom Prefix 设置为 ARTITALK。
完成连接后，确认项目环境变量中存在 ARTITALK_DATABASE_URL。
重新部署 Vercel 项目，使数据库环境变量进入新的 Production 部署。

Caution

Custom Prefix 必须为 ARTITALK。如果服务端提示 ARTITALK_DATABASE_URL is required，通常是数据库未连接到正确的项目、前缀错误，或者连接后没有重新部署。

详细的 Neon 图文配置步骤见使用文档。

五、执行数据迁移

完成 Vercel 和 Neon 配置后：

访问 Vercel 服务端根地址，例如：
```
https://your-vercel-app.vercel.app
```
确认页面显示数据库为空，可以初始化或从 LeanCloud 导入。
点击 从 LeanCloud 迁移。
在 shuoshuo.0.jsonl 输入框中选择 LeanCloud 导出的说说文件。
在 atComment.0.jsonl 输入框中选择评论文件；没有评论时选择前面创建的空文件。
点击 开始迁移。
保持页面打开，等待迁移完成。
记录页面返回的说说和评论导入数量。

迁移程序会保留数据中的 objectId、createdAt 和 updatedAt，其他字段会作为兼容数据写入 Neon。评论中用于关联说说的原始字段也会一并保留。

Warning

迁移期间不要重复点击提交按钮，也不要同时在多个浏览器窗口执行迁移。

六、初始化管理员账户

迁移完成后，服务端会创建数据库表，但不会迁移 LeanCloud _User 账号。

返回或刷新 Vercel 服务端根页面。
点击 初始化管理员账户。
服务端会读取 Vercel 中的 ADMIN_USERNAME、ADMIN_PASSWORD、ADMIN_IMG 和 ADMIN_IMG_Token。
初始化成功后刷新页面，确认服务端显示数据库和管理员状态正常。

数据库中只能通过初始化页面创建第一个管理员。数据库已有管理员后，单纯修改 Vercel 环境变量不会替换现有账号。

七、修改站点配置

删除旧版 Artitalk 配置中的 LeanCloud appId、appKey 和 API 域名，改为连接新服务端：

<script src="https://unpkg.com/@hclonely/artitalk"></script>
<div id="artitalk_main"></div>
<script>
new Artitalk({
  backend: 'vercel',
  serverURL: 'https://your-vercel-app.vercel.app'
})
</script>