Quick start

Tip

The English document is being built. Please refer to the Chinese document.

Twikoo 分为云函数和前端两部分,部署时请注意保持二者版本一致。

云函数部署

部署方式
描述
一键部署[ 不建议 ] 虽然方便,但是仅支持按量计费环境——也就是说,一键部署的环境,当免费资源用尽后,将会产生费用。且按量计费环境无法切换为包年包月环境。免费额度数据库读操作数只有 500 次 / 天,无法支撑 Twikoo 的运行需求
手动部署[ 建议 ] 手动部署到腾讯云云开发环境,在中国大陆访问速度较快。需要付费购买环境才能部署。
命令行部署[ 不建议 ] 仅针对有 Node.js 经验的开发者。
Vercel 部署[ 建议 ] 适用于想要免费部署的用户,在中国大陆访问速度较慢甚至无法访问。
Railway 部署[ 建议 ] 有充足的免费额度,部署简单,适合全球访问。
Zeabur 部署[ 建议 ] 有充足的免费额度,部署简单,适合中国大陆访问。
私有部署[ 建议 ] 适用于有服务器的用户,需要自行申请 HTTPS 证书。

一键部署

  1. 点击以下按钮将 Twikoo 一键部署到云开发
    部署到云开发open in new window
  2. 进入环境-登录授权open in new window,启用“匿名登录”
  3. 进入环境-安全配置open in new window,将网站域名添加到“WEB安全域名”

手动部署

如果您打算部署到一个现有的云开发环境,请直接从第 3 步开始。

  1. 进入云开发CloudBaseopen in new window活动页面,滚动到“新用户专享”部分,选择适合的套餐,点击“立即购买”,按提示创建好环境。

提示

  • 推荐创建上海环境。如选择广州环境,需要在 twikoo.init() 时额外指定环境 region: "ap-guangzhou"
  • 环境名称自由填写
  • 推荐选择计费方式包年包月,套餐版本基础版 1,超出免费额度不会收费
  • 如果提示选择“应用模板”,请选择“空模板”
  1. 进入云开发控制台open in new window
  2. 进入环境-登录授权open in new window,启用“匿名登录”
  3. 进入环境-安全配置open in new window,将网站域名添加到“WEB安全域名”
  4. 进入环境-云函数open in new window,点击“新建云函数”
  5. 函数名称请填写:twikoo,创建方式请选择:空白函数,运行环境请选择:Nodejs 10.15,函数内存请选择:128MB,点击“下一步”
  6. 清空输入框中的示例代码,复制以下代码、粘贴到“函数代码”输入框中,点击“确定”
exports.main = require('twikoo-func').main
  1. 创建完成后,点击“twikoo"进入云函数详情页,进入“函数代码”标签,点击“文件 - 新建文件”,输入 package.json,回车
  2. 复制以下代码、粘贴到代码框中,点击“保存并安装依赖”
{ "dependencies": { "twikoo-func": "1.6.16" } }

命令行部署

注意

  • 请确保您已经安装了 Node.jsopen in new window
  • 请将命令、代码中“您的环境id”替换为您自己的环境id
  • 第 7 步会弹出浏览器要求授权,需在有图形界面的系统下进行
  • 请勿在 Termux 下操作。虽然可以部署成功,但是使用时会报错 [FUNCTIONS_EXECUTE_FAIL] Error: EACCES: permission denied, open '/var/user/index.js'

如果您打算部署到一个现有的云开发环境,请直接从第 3 步开始。

  1. 进入云开发CloudBaseopen in new window活动页面,滚动到“新用户专享”部分,选择适合的套餐(一般 0 元套餐即可),点击“立即购买”,按提示创建好环境。
  2. 进入云开发控制台open in new window
  3. 进入环境-登录授权open in new window,启用“匿名登录”
  4. 进入环境-安全配置open in new window,将网站域名添加到“WEB安全域名”
  5. 克隆本仓库
git clone https://github.com/imaegoo/twikoo.git # 或 git clone https://e.coding.net/imaegoo/twikoo/twikoo.git
cd twikoo

如果您没有安装 Git,也可以从 Releaseopen in new window 页面下载最新的 Source code
如果您所在的地区访问 Github 速度慢,也可以尝试另一个仓库地址:https://imaegoo.coding.net/public/twikoo/twikoo/gitopen in new window

  1. 安装依赖项
npm install -g yarn # 已安装 yarn 可以跳过此步
yarn install
  1. 授权云开发环境(此命令会弹出浏览器要求授权,需在有图形界面的系统下进行)
yarn run login
  1. 自动部署
yarn deploy -e 您的环境id

Vercel 部署

注意

Vercel 部署的环境需配合 1.4.0 以上版本的 twikoo.js 使用

查看视频教程open in new window

  1. 申请 MongoDBopen in new window 账号
  2. 创建免费 MongoDB 数据库,区域推荐选择 AWS / N. Virginia (us-east-1)
  3. 在 Clusters 页面点击 CONNECT,按步骤设置允许所有 IP 地址的连接(为什么?open in new window),创建数据库用户,并记录数据库连接字符串,请将连接字符串中的 <password> 修改为数据库密码
  4. 申请 Vercelopen in new window 账号
  5. 点击以下按钮将 Twikoo 一键部署到 Vercel
    open in new window
  6. 进入 Settings - Environment Variables,添加环境变量 MONGODB_URI,值为第 3 步的数据库连接字符串
  7. 进入 Deployments , 然后在任意一项后面点击更多(三个点) , 然后点击Redeploy , 最后点击下面的Redeploy
  8. 进入 Overview,点击 Domains 下方的链接,如果环境配置正确,可以看到 “Twikoo 云函数运行正常” 的提示
  9. Vercel Domains(包含 https:// 前缀,例如 https://xxx.vercel.app)即为您的环境 id

Railway 部署

注意

Railway 部署的环境需配合 1.4.0 以上版本的 twikoo.js 使用

  1. Railwayopen in new window 申请并登录账号,点击 New Project - Provision MongoDB,名称随意
  2. 打开 imaegoo/twikoo-zeaburopen in new window 点击 fork 将仓库 fork 到自己的账号下
  3. 回到 Railway 点击 New - GitHub Repo - Configure GitHub App - 授权 GitHub - 选择刚才 fork 的仓库,等待部署完成
  4. 点开环境卡片 - Variables - New Variable,左边输入 PORT 右边输入 8080 然后点 Add。
  5. 点开环境卡片 - Settings - Environment - Domains,绑定一个域名(例如 mytwikoo.up.railway.app
  6. 到博客配置文件中配置 envId 为 https:// 加域名(例如 https://mytwikoo.up.railway.app

Zeabur 部署

注意

Zeabur 部署的环境需配合 1.4.0 以上版本的 twikoo.js 使用

  1. Zeaburopen in new window 申请并登录账号,点击部署新服务 - 部署其他服务 - 部署 MongoDB,名称随意
  2. 打开 imaegoo/twikoo-zeaburopen in new window 点击 fork 将仓库 fork 到自己的账号下
  3. 回到 Zeabur 点击部署新服务 - 部署你的源代码 - 授权 GitHub - 选择刚才 fork 的仓库,名称随意

无需配置数据库连接字符串! Zeabur 已自动配置

  1. 部署好后点开环境卡片 - 设置 - 域名,绑定一个域名(例如 mytwikoo.zeabur.app
  2. 到博客配置文件中配置 envId 为 https:// 加域名(例如 https://mytwikoo.zeabur.app

私有部署

注意

私有部署的环境需配合 1.6.0 或以上版本的 twikoo.js 使用

  1. 服务端下载安装 Node.jsopen in new window
  2. 安装 Twikoo server: npm i -g tkserver
  3. 根据需要配置环境变量
名称描述默认值
TWIKOO_DATA数据库存储路径./data
TWIKOO_PORT端口号8080
TWIKOO_THROTTLEIP 请求限流,当同一 IP 短时间内请求次数超过阈值将对该 IP 返回错误250
  1. 启动 Twikoo server: tkserver
  2. 访问 http://服务端IP:8080
  3. 若能正常访问,服务端地址(包含 http:// 和端口号,例如 http://12.34.56.78:8080)即为您的环境 id

提示

  1. Linux 服务器可以用 nohup tkserver >> tkserver.log 2>&1 & 命令后台启动
  2. 强烈建议配置前置 nginx 服务器并配置 https 证书
  3. 数据在服务器上,请注意定期备份数据

私有部署 (Docker)

docker run --name twikoo -e TWIKOO_THROTTLE=1000 -p 8080:8080 -v ${PWD}/data:/app/data -d imaegoo/twikoo

前端部署

在 Hexo 中使用

Hexo Butterflyopen in new window 主题使用

请参考 Butterfly 安裝文檔(四) 主題配置-2open in new window 进行配置

Hexo Keepopen in new window 主题使用

请参考 hexo-theme-keep/_config.ymlopen in new window 进行配置

Hexo Volantisopen in new window 主题使用

请参考 hexo-theme-volantis/_config.ymlopen in new window 进行配置

Hexo Ayeropen in new window 主题使用

请参考 hexo-theme-ayer/_config.ymlopen in new window 进行配置

Hexo NexTopen in new window 主题使用

暂不支持 NexT 8 以下的版本,请先升级到 NexT 8。然后在 Hexo 项目根目录执行

# For NexT version >= 8.0.0 && < 8.4.0
npm install hexo-next-twikoo@1.0.0
# For NexT version >= 8.4.0
npm install hexo-next-twikoo@1.0.3

然后在配置中添加

twikoo:
  enable: true
  visitor: true
  envId: xxxxxxxxxxxxxxx # 腾讯云环境填 envId;Vercel 环境填地址(https://xxx.vercel.app)
  # region: ap-guangzhou # 环境地域,默认为 ap-shanghai,腾讯云环境填 ap-shanghai 或 ap-guangzhou;Vercel 环境不填

Hexo Materyopen in new window 主题使用

请参考 hexo-theme-matery/_config.ymlopen in new window 进行配置

Hexo Icarusopen in new window 主题使用

请参考 基于腾讯云,给你的 Icarus 博客配上 Twikoo 评论系统open in new window by 异次元de机智君💯

Hexo MengD(萌典)open in new window 主题使用

请参考 hexo-theme-MengD/_config.ymlopen in new window 进行配置

hexo-theme-fluidopen in new window 主题使用

请参考 配置指南-评论open in new window 进行配置

hexo-theme-cardsopen in new window 主题使用

请参考 hexo-theme-cards/_config.ymlopen in new window 进行配置

maupassant-hexoopen in new window 主题使用

请参考 maupassant-hexo/_config.ymlopen in new window 进行配置

hexo-theme-redefineopen in new window 主题使用

请参考 Redefine 官方文档 #commentopen in new window 进行配置

hugo-theme-stackopen in new window 主题使用

请参考 Comments | Stackopen in new windowhugo-theme-stack/config.yaml#L83open in new window 进行配置

通过 CDN 引入

提示

如果您使用的博客主题不支持 Twikoo,并且您不知道如何引入 Twikoo,您可以在 Github 提交适配请求open in new window

<div id="tcomment"></div>
<script src="https://cdn.staticfile.org/twikoo/1.6.16/twikoo.all.min.js"></script>
<script>
twikoo.init({
  envId: '您的环境id', // 腾讯云环境填 envId;Vercel 环境填地址(https://xxx.vercel.app)
  el: '#tcomment', // 容器元素
  // region: 'ap-guangzhou', // 环境地域,默认为 ap-shanghai,腾讯云环境填 ap-shanghai 或 ap-guangzhou;Vercel 环境不填
  // path: location.pathname, // 用于区分不同文章的自定义 js 路径,如果您的文章路径不是 location.pathname,需传此参数
  // lang: 'zh-CN', // 用于手动设定评论区语言,支持的语言列表 https://github.com/imaegoo/twikoo/blob/main/src/client/utils/i18n/index.js
})
</script>

建议使用 CDN 引入 Twikoo 的用户在链接地址上锁定版本,以免将来 Twikoo 升级时受到非兼容性更新的影响。

更换 CDN 镜像

如果遇到默认 CDN 加载速度缓慢,可更换其他 CDN 镜像。以下为可供选择的公共 CDN,其中一些 CDN 可能需要数天时间同步最新版本:

  • https://cdn.staticfile.org/twikoo/1.6.16/twikoo.all.min.js
  • https://lib.baomitu.com/twikoo/1.6.16/twikoo.all.min.js
  • https://cdn.bootcdn.net/ajax/libs/twikoo/1.6.16/twikoo.all.min.js
  • https://cdn.jsdelivr.net/npm/twikoo@1.6.16/dist/twikoo.all.min.js

开启管理面板(腾讯云环境)

  1. 进入环境-登录授权open in new window,点击“自定义登录”右边的“私钥下载”,下载私钥文件
  2. 用文本编辑器打开私钥文件,复制全部内容
  3. 点击评论窗口的“小齿轮”图标,粘贴私钥文件内容,并设置管理员密码

配置好登录私钥之后无需留存私钥文件,请勿再次下载登录私钥,否则会导致之前配置的登录私钥失效。

开启管理面板(Vercel 环境)

点击评论窗口的“小齿轮”图标,设置管理员密码

版本更新

不同部署方式的更新方式也不同,请对号入座。更新部署成功后,请不要忘记同时更新前端的 Twikoo CDN 地址中的 x.x.x 数字版本号,使之与云函数版本号相同,然后部署网站。

针对一键部署的更新方式

登录环境-我的应用open in new window,输入

  • 来源地址:https://github.com/imaegoo/twikoo/tree/main
  • 部署分支:main

应用目录无需填写,点击“确定”,部署完成。

针对手动部署的更新方式

登录环境-云函数open in new window,点击 twikoo,点击函数代码,打开 package.json 文件,将 "twikoo-func": "x.x.x" 其中的版本号修改为最新版本号,点击“保存并安装依赖”即可。

提示

如果您的云函数是 1.0.0 之前的版本,因为 1.0.0 版本修改了部署步骤,请先参考手动部署,从第 5 步开始,重新创建云函数,再按照此步骤更新。

如果升级后出现无法读取评论列表,云函数报错,请在函数编辑页面,删除 node_modules 目录(删除需要半分钟左右,请耐心等待删除完成),再点击保存并安装依赖。如果仍然不能解决,请删除并重新创建 Twikoo 云函数。

针对命令行部署的更新方式

进入 Twikoo 源码目录,执行以下命令更新现有的云函数

yarn deploy -e 您的环境id

针对 Vercel 部署的更新方式

  1. 进入 Vercel 仪表板open in new window - twikoo - Settings - Git
  2. 点击 Connected Git Repository 下方的仓库地址
  3. 打开 package.json,点击编辑
  4. "twikoo-vercel": "x.x.x" 其中的版本号修改为最新版本号。点击 Commit changes
  5. 部署会自动触发,可以回到 Vercel 仪表板open in new window,查看部署状态

针对私有部署的更新方式

  1. 停止旧版本 kill $(ps -ef | grep tkserver | grep -v 'grep' | awk '{print $2}')
  2. 拉取新版本 npm i -g tkserver@latest
  3. 启动新版本 nohup tkserver >> tkserver.log 2>&1 &

针对私有部署 (Docker) 的更新方式

  1. 拉取新版本 docker pull imaegoo/twikoo
  2. 停止旧版本容器 docker stop twikoo
  3. 删除旧版本容器 docker rm twikoo
  4. 启动新版本容器

自动更新

考虑到可用性和安全性问题,Twikoo 没有实现自动更新,也没有计划实现自动更新。如果您希望实现自动更新,可以参考 MHuiG 基于 Github 工作流的 twikoo-updateopen in new window 的实现方式。