上传文件至「/」

Astro Firefly 配置 Twikoo 评论系统.md

@@ -0,0 +1,170 @@
+---
+title: 给 Astro Firefly 博客配置 Twikoo 评论系统
+created: 2026-07-20
+updated: 2026-07-20
+tags:
+  - Astro
+  - Firefly
+  - Twikoo
+  - 博客
+  - Docker
+---
+
+# 给 Astro Firefly 博客配置 Twikoo 评论系统
+
+Twikoo 是一款轻量、免费、国内友好的评论系统。相比 Giscus（需要 GitHub 账号），Twikoo 支持**匿名评论**，对普通读者更友好。
+
+## 整体架构
+
+Twikoo 分两部分：
+
+```
+你的博客页面 ← 加载 Twikoo 前端 JS
+                  ↑
+           Twikoo 后端服务（Docker / Vercel / 腾讯云）
+                  ↑
+           数据存储（文件数据库 / MongoDB）
+```
+
+Docker 部署后数据全在自己服务器上，安全性更高。
+
+## 第一步：Docker 部署 Twikoo 后端（推荐）
+
+Twikoo Docker 镜像**内置了文件数据库**，不需要额外装 MongoDB，一条命令搞定：
+
+### 创建数据目录并启动
+
+```bash
+# 创建持久化数据目录
+mkdir -p /data/twikoo
+
+# 启动 Twikoo 容器
+docker run -d \
+  --name twikoo \
+  --restart always \
+  -p 8080:8080 \
+  -v /data/twikoo:/app/data \
+  imaegoo/twikoo
+```
+
+### 验证部署
+
+访问 `http://你的服务器IP:8080`，看到以下提示即成功：
+
+```
+Twikoo 云函数运行正常
+```
+
+这个 URL（`http://你的服务器IP:8080`）就是后续配置要用的 **envId**。
+
+### 配置反向代理（可选，推荐）
+
+为了安全性，建议用 Nginx 反代配置 HTTPS：
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name twikoo.你的域名.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+配置 HTTPS 后，envId 就是 `https://twikoo.你的域名.com`。
+
+### 常用管理命令
+
+| 操作 | 命令 |
+|:---|:---|
+| 查看日志 | `docker logs -f twikoo` |
+| 重启容器 | `docker restart twikoo` |
+| 更新镜像 | `docker pull imaegoo/twikoo && docker restart twikoo` |
+| 停止容器 | `docker stop twikoo` |
+| 备份数据 | 打包 `/data/twikoo` 目录 |
+
+## 备选方案：Vercel 部署
+
+如果没有自己的服务器，也可以用 Vercel 免费部署：
+
+1. 打开 [Twikoo Vercel 模板](https://vercel.com/templates/other/twikoo)
+2. 点击 **Deploy**，用 GitHub 账号登录 Vercel
+3. 环境变量 `MONGODB_URI` 填你的 MongoDB 连接字符串（可以用 [MongoDB Atlas](https://www.mongodb.com/atlas) 免费 512MB 实例）
+4. 部署完成后得到域名 `https://xxx.vercel.app`，这就是 **envId**
+
+## 第二步：配置 Firefly
+
+编辑 Firefly 项目中的 `src/config/commentConfig.ts`：
+
+```typescript
+export const commentConfig: CommentConfig = {
+  type: "twikoo",  // 改为 twikoo
+
+  twikoo: {
+    // 你的 Twikoo 后端地址
+    // Docker 部署: "http://服务器IP:8080" 或 "https://你的域名"
+    // Vercel 部署: "https://你的项目名.vercel.app"
+    envId: "http://你的服务器IP:8080",
+
+    // 语言
+    lang: "zh-CN",
+
+    // 启用访问量统计
+    visitorCount: true,
+
+    // CDN 地址（国内用户推荐用 npmmirror）
+    jsUrl: "https://registry.npmmirror.com/twikoo/1.7.14/files/dist/twikoo.min.js",
+
+    // 自定义 CSS（可选，留空则不加载）
+    cssUrl: "/assets/css/twikoo-custom.css",
+  },
+};
+```
+
+## 第三步：文章 Frontmatter 控制
+
+每篇文章可以通过 frontmatter 控制是否开启评论：
+
+```yaml
+---
+title: 我的文章
+comment: true   # 开启评论（默认 true）
+---
+```
+
+如果某篇文章不想开评论，设为 `comment: false` 即可。
+
+## 第四步：开启管理后台
+
+评论需要管理才能删除垃圾评论：
+
+1. 在你博客任意文章底部，点击评论区的 **齿轮图标**
+2. 设置一个**管理员密码**
+3. 以后用这个密码登录管理后台，可以审核、删除、回复评论
+
+## 常见问题
+
+### 评论加载不出来？
+- 检查 `envId` 是否正确（Docker 部署记得带 `http://` 和端口号）
+- 检查 Twikoo 容器有没有在运行：`docker ps | grep twikoo`
+- 查看日志：`docker logs twikoo`
+- 打开浏览器控制台看有没有跨域报错
+
+### 国内访问慢？
+- 把 `jsUrl` 换成 `https://registry.npmmirror.com/twikoo/1.7.14/files/dist/twikoo.min.js`
+- 或者用 `https://s4.zstatic.net/npm/twikoo@1.7.14/dist/twikoo.min.js`
+
+### 数据会丢吗？
+Docker 部署的数据存在 `/data/twikoo` 目录，定期备份这个目录即可。也可以停掉容器后直接打包。
+
+---
+
+配置完成后，`pnpm build` 重新构建博客，评论功能就上线了。