企业官网建设流程全解析

Chirpy自托管完全教程：如何在自己的服务器上部署一个Disqus替代品

【免费下载链接】chirpy💬 A privacy-friendly and customizable Disqus (comment system) alternate. 注重隐私保护和定制化的评论系统。项目地址: https://gitcode.com/gh_mirrors/ch/chirpy

Chirpy 是一个注重隐私保护和高度可定制的 Disqus 替代品（评论系统），基于 Next.js + tRPC + Prisma 构建，支持富文本评论、实时通知、垃圾评论拦截和数据分析。本教程将手把手教你完成 Chirpy 自托管部署，在自己的服务器上搭建一套完全可控的评论系统，让评论数据、用户隐私都掌握在自己手中。

一、为什么选择 Chirpy 自托管？

自托管版与官方云版本是同一个产品，区别只在于：你需要自己负责安装和运维。官方自托管说明文档位于 self-hosted.mdx，项目采用 pnpm workspaces + Turbo 的 monorepo 架构，主要代码目录如下：

• 主应用（Next.js）：apps/main/
• 评论组件引导脚本：apps/bootstrapper/
• Service Worker（Web 推送）：apps/service-worker/
• 数据库模型与 tRPC 接口：packages/trpc/

二、部署前环境准备

在服务器上准备好以下三样东西即可：

1. Node.js 18+与pnpm（项目使用 pnpm workspaces 管理多个子包）
2. PostgreSQL 数据库（Chirpy 使用 Prisma ORM，官方提供现成的 Docker Compose 配置）
3. 一个已备案/可解析的域名（评论组件要求嵌入页面的域名与项目域名完全一致）

三、克隆仓库并初始化

克隆 Chirpy 代码到服务器：

git clone https://gitcode.com/gh_mirrors/ch/chirpy cd chirpy

安装依赖并执行 bootstrap 构建（该命令会构建评论引导脚本、Service Worker，并生成 Prisma 客户端）：

pnpm install pnpm run bootstrap

四、启动 PostgreSQL 数据库

项目自带数据库编排文件packages/trpc/docker-compose.yml（postgres:14-alpine 镜像，数据挂载到本地目录）。在项目根目录执行：

docker compose -f packages/trpc/docker-compose.yml up -d

启动后可在packages/trpc/postgres目录看到数据卷。数据库默认连接串为postgres://postgres:postgres@localhost:5432/postgres，请根据安全要求修改账号密码。

数据库迁移文件位于packages/trpc/prisma/migrations/，Prisma 会依据packages/trpc/prisma/schema.prisma自动管理表结构。

五、配置环境变量

项目提供了环境变量模板apps/main/.env.tmpl，参考它创建配置文件。关键变量说明：

另外还需在部署平台的数据库配置中设置 Prisma 的DATABASE_URL，指向第四步启动的 PostgreSQL。

六、构建与运行

# 本地开发模式（端口 3000） pnpm run dev # 生产构建 + 启动 pnpm run build pnpm run start

浏览器访问http://<服务器IP>:3000，能看到登录页即部署成功。⚠️ 生产环境建议用 Nginx/Caddy 做反向代理并配置 HTTPS——评论系统涉及用户会话，明文 HTTP 会导致登录异常。

七、创建项目并嵌入评论组件

部署完成后，在后台 Dashboard 点击Create project，填写名称和你的博客域名（例如blog.example.com）即可创建项目。

随后点击项目卡片上的Integrate按钮，按照集成向导操作：在博客页面的 HTML 中引入 bootstrapper 脚本（bootstrapper.js，源码见apps/bootstrapper/），并给评论容器元素加上data-chirpy-comment属性。脚本源码逻辑位于apps/bootstrapper/src/index.ts。

⚠️ 注意：只能将组件嵌入创建项目时填写的完全一致的域名页面，a.example.com与example.com不互通。

八、绑定自定义域名

如果你的域名托管在 Vercel，按如下界面在 DNS 管理页添加 A 记录/CNAME 记录，指向你的部署地址：

DNS 生效后，NEXT_PUBLIC_APP_URL指向的域名即可访问整套自托管评论系统。

九、上线后的进阶玩法

部署只是起点，Chirpy 的以下能力都可以直接用：

• 📊评论数据分析：访问量、来源、设备、趋势等图表，面板代码位于packages/analytics/src/
• 🎨主题定制：评论组件颜色、字体、明暗模式均可在后台调整，可参考 theme.mdx
• 🔔邮件 + Web Push 双通道通知：新回复实时推送到访客浏览器
• 🤐反垃圾/反毒评论：内置 TensorFlow 模型做毒性内容识别，见apps/main/src/pages/api/content-classifier/
• ✍️富文本 + Markdown 快捷语法：评论编辑器基于 tiptap

十、常见问题速查

Q1：启动报错找不到 bootstrapper.js？先确认执行过pnpm run bootstrap，该命令会构建apps/bootstrapper与apps/service-worker两个子包。

Q2：评论组件不显示？99% 是域名不匹配——请核对后台项目填写的域名与页面实际域名完全一致（含/不含 www）。

Q3：定时任务在哪里？apps/main/vercel.json中定义了每天执行的用量统计 cron（/api/cron/usage），自托管时需自行配置等价的定时触发器。

Q4：如何升级版本？重新 clone 后执行pnpm install && pnpm run bootstrap && pnpm run build，Prisma 会按packages/trpc/prisma/migrations/中的迁移文件自动演进数据库结构。

至此，你已拥有了一套数据完全归自己所有、功能与官方云版本一致的Chirpy 自托管评论系统。把评论、数据、隐私都握在自己手里，正是自托管最大的价值。

【免费下载链接】chirpy💬 A privacy-friendly and customizable Disqus (comment system) alternate. 注重隐私保护和定制化的评论系统。项目地址: https://gitcode.com/gh_mirrors/ch/chirpy