GoCode

工具教程

Waline 评论系统部署指南

详细的 Waline 后端部署步骤，支持 LeanCloud 和 PostgreSQL 数据库

Waline 评论系统部署指南

本指南将帮助你完成 Waline 评论系统的后端部署，实现完整的评论功能。

📋 部署概览

Waline 评论系统已经集成到你的网站中，但需要完成以下步骤才能正常使用：

  1. ✅ 前端集成（已完成）

    • Waline 客户端已安装
    • 评论组件已创建
    • 已集成到文章详情页

  2. ⏳ 后端部署（待完成）

    • 部署 Waline 服务器到 Vercel
    • 配置数据库（LeanCloud 或 PostgreSQL）
    • 更新前端配置

🗄️ 数据库选择

Waline 支持多种数据库，你可以根据需求选择：

数据库优点缺点推荐场景
LeanCloud免费额度大，零配置需要实名认证个人博客，快速上线
PostgreSQL功能强大，数据自主需要服务器或付费服务已有数据库，企业应用
MySQL广泛使用，兼容性好需要服务器已有 MySQL 环境
SQLite零配置，轻量级不适合高并发测试环境
MongoDB灵活的文档存储需要服务器已有 MongoDB 环境

推荐方案：

  • 🥇 个人博客：LeanCloud（完全免费，零配置）
  • 🥈 已有数据库：PostgreSQL（数据自主，功能强大）
  • 🥉 测试环境：SQLite（零配置，快速测试）

🚀 第一步：注册 Vercel 账号

1. 访问 Vercel

打开浏览器访问：https://vercel.com

2. 使用 GitHub 登录

  • 点击 “Sign Up” 或 “Log In”
  • 选择 “Continue with GitHub”
  • 授权 Vercel 访问你的 GitHub 账号

3. 完成注册

  • 填写基本信息（如果需要）
  • 验证邮箱（如果需要）

💾 第二步：配置 LeanCloud 数据库

1. 注册 LeanCloud 账号

访问：https://console.leancloud.cn

  • 点击”注册”
  • 使用邮箱或手机号注册
  • 完成实名认证（中国大陆用户需要）

2. 创建应用

  1. 登录后，点击”创建应用”
  2. 输入应用名称：waline-comments
  3. 选择开发版（免费）
  4. 点击”创建”

3. 获取应用凭证

  1. 进入应用控制台
  2. 点击左侧菜单”设置” → “应用凭证”
  3. 记录以下信息：
    • AppID：xxxxxxxxxxxxxxxxxxxxxxxx
    • AppKey：xxxxxxxxxxxxxxxxxxxxxxxx
    • MasterKey：xxxxxxxxxxxxxxxxxxxxxxxx
    • REST API 服务器地址：https://xxxxxx.api.lncldglobal.com

⚠️ 重要：请妥善保管这些密钥，不要泄露！

4. 配置安全域名

  1. 在 LeanCloud 控制台，点击”设置” → “安全中心”
  2. 在”Web 安全域名”中添加：
    localhost:4321
your-domain.com
  3. 点击”保存”

💾 第二步（备选）：配置 PostgreSQL 数据库

如果你已有 PostgreSQL 数据库或想使用 PostgreSQL，可以跳过 LeanCloud 配置，按以下步骤操作。

方式一：使用 Vercel Postgres（推荐）

Vercel 提供免费的 PostgreSQL 数据库服务。

1. 创建 Vercel Postgres 数据库

  1. 登录 Vercel 控制台
  2. 点击顶部导航栏的 “Storage”
  3. 点击 “Create Database”
  4. 选择 “Postgres”
  5. 输入数据库名称：waline-db
  6. 选择区域（推荐选择离你最近的区域）
  7. 点击 “Create”

2. 获取数据库连接信息

创建完成后，Vercel 会自动生成数据库连接信息：

POSTGRES_URL="postgres://default:xxxxx@xxxxx.postgres.vercel-storage.com:5432/verceldb"
POSTGRES_PRISMA_URL="postgres://default:xxxxx@xxxxx.postgres.vercel-storage.com:5432/verceldb?pgbouncer=true&connect_timeout=15"
POSTGRES_URL_NON_POOLING="postgres://default:xxxxx@xxxxx.postgres.vercel-storage.com:5432/verceldb"
POSTGRES_USER="default"
POSTGRES_HOST="xxxxx.postgres.vercel-storage.com"
POSTGRES_PASSWORD="xxxxx"
POSTGRES_DATABASE="verceldb"

⚠️ 重要：记录 POSTGRES_URL，后面部署时需要用到！

3. 免费额度

Vercel Postgres 免费版提供：

  • 256 MB 存储空间
  • 60 小时计算时间/月
  • 足够个人博客使用

方式二：使用 Supabase（推荐）

Supabase 提供免费的 PostgreSQL 数据库，功能更强大。

1. 注册 Supabase

访问：https://supabase.com

  • 点击 “Start your project”
  • 使用 GitHub 登录

2. 创建项目

  1. 点击 “New project”
  2. 选择组织（或创建新组织）
  3. 填写项目信息：
    • Name：waline-comments
    • Database Password：设置一个强密码（记住它！）
    • Region：选择离你最近的区域
  4. 点击 “Create new project”（等待 1-2 分钟）

3. 获取数据库连接信息

  1. 项目创建完成后，点击左侧菜单 “Project Settings”
  2. 点击 “Database”
  3. 在 “Connection string” 部分，选择 “URI”
  4. 复制连接字符串：
    postgresql://postgres:[YOUR-PASSWORD]@db.xxxxx.supabase.co:5432/postgres
  5. 将 [YOUR-PASSWORD] 替换为你设置的密码

⚠️ 重要：记录这个连接字符串，后面部署时需要用到！

4. 免费额度

Supabase 免费版提供：

  • 500 MB 数据库空间
  • 无限 API 请求
  • 50,000 月活跃用户
  • 足够个人博客使用

方式三：使用 Railway（推荐）

Railway 提供免费的 PostgreSQL 数据库，配置简单。

1. 注册 Railway

访问：https://railway.app

  • 点击 “Start a New Project”
  • 使用 GitHub 登录

2. 创建 PostgreSQL 数据库

  1. 点击 “New Project”
  2. 选择 “Provision PostgreSQL”
  3. 等待数据库创建完成

3. 获取数据库连接信息

  1. 点击 PostgreSQL 服务
  2. 点击 “Connect” 标签
  3. 复制 “Postgres Connection URL”：
    postgresql://postgres:xxxxx@containers-us-west-xxx.railway.app:5432/railway

⚠️ 重要：记录这个连接字符串，后面部署时需要用到！

4. 免费额度

Railway 免费版提供：

  • $5 免费额度/月
  • 500 小时运行时间/月
  • 足够个人博客使用

方式四：使用自己的 PostgreSQL 服务器

如果你已有 PostgreSQL 服务器，可以直接使用。

1. 创建数据库

CREATE DATABASE waline;

2. 创建用户（可选）

CREATE USER waline_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE waline TO waline_user;

3. 获取连接字符串

格式：

postgresql://username:password@host:port/database

示例：

postgresql://waline_user:your_password@localhost:5432/waline

🌐 第三步：部署 Waline 到 Vercel

方式一：一键部署（推荐）

  1. 访问 Waline 官网

    打开：https://waline.js.org

  2. 点击”快速开始”

    找到”一键部署”按钮

  3. 使用 Vercel 部署

    点击 “Deploy with Vercel” 按钮

    或直接访问：https://vercel.com/new/clone?repository-url=https://github.com/walinejs/waline/tree/main/example

  4. 配置项目

    • Repository Name：waline-server（或其他名称）
    • 点击 “Create”

  5. 配置环境变量

    在部署页面，点击”Environment Variables”，根据你选择的数据库添加相应的环境变量：

    选项 A：使用 LeanCloud

    变量名值说明
    LEAN_ID你的 LeanCloud AppID必填
    LEAN_KEY你的 LeanCloud AppKey必填
    LEAN_MASTER_KEY你的 LeanCloud MasterKey必填
    LEAN_SERVER你的 REST API 服务器地址必填
    SITE_NAMEGoCode网站名称
    SITE_URLhttps://your-domain.com网站地址
    AUTHOR_EMAILyour@email.com管理员邮箱

    选项 B：使用 PostgreSQL

    变量名值说明
    PG_DB你的 PostgreSQL 连接字符串必填
    SITE_NAMEGoCode网站名称
    SITE_URLhttps://your-domain.com网站地址
    AUTHOR_EMAILyour@email.com管理员邮箱

    PostgreSQL 连接字符串示例：

    # Vercel Postgres
postgres://default:xxxxx@xxxxx.postgres.vercel-storage.com:5432/verceldb

# Supabase
postgresql://postgres:your_password@db.xxxxx.supabase.co:5432/postgres

# Railway
postgresql://postgres:xxxxx@containers-us-west-xxx.railway.app:5432/railway

# 自建服务器
postgresql://username:password@host:port/database

    ⚠️ 重要：

    • 只需配置一种数据库（LeanCloud 或 PostgreSQL）
    • 如果同时配置，Waline 会优先使用 LeanCloud
    • PostgreSQL 连接字符串必须以 postgres:// 或 postgresql:// 开头

    可选环境变量

    变量名说明示例
    SMTP_SERVICE邮件服务Gmail
    SMTP_USER邮箱地址your@gmail.com
    SMTP_PASS邮箱密码/应用专用密码your_password
    SENDER_NAME发件人名称GoCode
    SENDER_EMAIL发件人邮箱your@gmail.com
    GITHUB_IDGitHub OAuth App ID（可选）
    GITHUB_SECRETGitHub OAuth App Secret（可选）
    QQ_IDQQ 互联 App ID（可选）
    QQ_SECRETQQ 互联 App Secret（可选）

  6. 开始部署

    • 点击 “Deploy”
    • 等待部署完成（约 2-3 分钟）

  7. 获取服务器地址

    部署成功后，你会得到一个地址，类似：

    https://waline-server-xxx.vercel.app

    ⚠️ 记录这个地址，后面需要用到！

方式二：手动部署

如果一键部署失败，可以手动部署：

  1. Fork Waline 仓库

    访问：https://github.com/walinejs/waline

    点击右上角 “Fork” 按钮

  2. 在 Vercel 导入项目

    • 登录 Vercel
    • 点击 “Add New…” → “Project”
    • 选择 “Import Git Repository”
    • 选择你 Fork 的 waline 仓库
    • 点击 “Import”

  3. 配置项目

    • Framework Preset：选择 “Other”
    • Root Directory：选择 example
    • Build Command：留空
    • Output Directory：留空

  4. 配置环境变量

    添加上面表格中的环境变量

  5. 部署

    点击 “Deploy” 开始部署

🔧 第四步：更新前端配置

1. 使用配置脚本（推荐）

在仓库根目录运行：

./scripts/configure-waline.sh

按提示输入你的 Waline 服务地址（示例：https://waline-server-xxx.vercel.app）。

2. 或手动设置环境变量

在 .env（本地）和 .env.production（生产）中写入：

PUBLIC_WALINE_SERVER_URL=https://waline-server-xxx.vercel.app

3. 重启并验证

  • 开发环境：重启 pnpm --filter=@gocode/site-astro dev
  • 生产环境：重新构建并发布

✅ 第五步：测试评论功能

1. 启动开发服务器

pnpm --filter=@gocode/site-astro dev

2. 访问文章页面

打开浏览器访问：http://localhost:4321/wiki/astrowind-wiki-guide

3. 测试评论

  1. 滚动到页面底部，应该能看到 Waline 评论框
  2. 输入昵称和评论内容
  3. 点击”提交”
  4. 评论应该成功发布

4. 验证数据存储

  1. 登录 LeanCloud 控制台
  2. 点击”数据存储” → “结构化数据”
  3. 应该能看到 Comment 表，里面有你刚才发布的评论

🎨 可选配置

1. 配置邮件通知

在 Vercel 环境变量中添加：

# SMTP 邮件配置
SMTP_SERVICE=Gmail
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SENDER_NAME=GoCode
SENDER_EMAIL=your-email@gmail.com

2. 配置社交登录

GitHub 登录

  1. 访问 GitHub Developer Settings
  2. 点击 “New OAuth App”
  3. 填写信息：
    • Application name：GoCode Comments
    • Homepage URL：https://your-domain.com
    • Authorization callback URL：https://your-waline-server.vercel.app/oauth/github/callback
  4. 获取 Client ID 和 Client Secret
  5. 在 Vercel 添加环境变量：
    GITHUB_ID=your_github_client_id
GITHUB_SECRET=your_github_client_secret

QQ 登录

  1. 访问 QQ 互联
  2. 创建应用
  3. 获取 App ID 和 App Key
  4. 在 Vercel 添加环境变量：
    QQ_ID=your_qq_app_id
QQ_SECRET=your_qq_app_secret

3. 配置评论审核

在 Vercel 环境变量中添加：

# 评论审核
COMMENT_AUDIT=true

启用后，所有评论需要管理员审核后才能显示。

4. 配置垃圾评论过滤

在 Vercel 环境变量中添加：

# Akismet 反垃圾评论
AKISMET_KEY=your_akismet_key

可以在 Akismet 免费申请 API Key。

🛠️ 管理评论

访问管理后台

  1. 访问：https://your-waline-server.vercel.app/ui
  2. 使用管理员邮箱登录（第一次访问会要求设置密码）
  3. 可以管理评论、用户、配置等

管理功能

  • ✅ 审核评论
  • ✅ 删除评论
  • ✅ 标记垃圾评论
  • ✅ 置顶评论
  • ✅ 查看统计数据
  • ✅ 管理用户
  • ✅ 配置网站设置

🐛 常见问题

Q1: 评论框不显示？

检查清单：

  1. ✅ Waline 服务器是否部署成功？
  2. ✅ 前端环境变量 PUBLIC_WALINE_SERVER_URL 是否正确？
  3. ✅ 浏览器控制台是否有错误？
  4. ✅ LeanCloud 安全域名是否配置？

Q2: 评论提交失败？

可能原因：

  1. LeanCloud 凭证配置错误
  2. 安全域名未配置
  3. 网络问题

解决方法：

  1. 检查 Vercel 环境变量
  2. 检查 LeanCloud 安全域名
  3. 查看浏览器控制台错误信息

Q3: 评论不显示？

可能原因：

  1. 启用了评论审核
  2. 数据库连接失败

解决方法：

  1. 登录管理后台审核评论
  2. 检查 LeanCloud 数据库连接

Q4: Vercel 部署失败？

解决方法：

  1. 检查环境变量是否正确
  2. 尝试重新部署
  3. 查看 Vercel 部署日志

Q5: 如何修改评论样式？

编辑 gocode-apps/site-astro/src/components/comments/WalineComments.astro 文件中的 <style> 部分。

📊 成本说明

免费额度

  • Vercel：

    • 100 GB 带宽/月
    • 100 次部署/天
    • 无限项目

  • LeanCloud（开发版）：

    • 1 GB 存储空间
    • 30,000 次 API 请求/天
    • 足够个人博客使用

升级方案

如果流量增长，可以考虑：

  • LeanCloud 商用版：¥18/月起
  • Vercel Pro：$20/月

🎯 下一步

完成部署后，你可以：

  1. ✅ 自定义评论样式
  2. ✅ 配置邮件通知
  3. ✅ 添加社交登录
  4. ✅ 启用评论审核
  5. ✅ 配置垃圾评论过滤

📚 相关资源

💡 总结

通过本指南，你应该已经：

✅ 注册了 Vercel 和 LeanCloud 账号 ✅ 部署了 Waline 服务器 ✅ 配置了数据库 ✅ 更新了前端配置 ✅ 测试了评论功能

现在你的网站已经拥有完整的评论系统了！🎉

如果遇到问题，可以：

  1. 查看本指南的常见问题部分
  2. 访问 Waline 官方文档
  3. 在 GitHub 提交 Issue