GoCode

工具教程

Waline + Vercel Postgres 部署实战

手把手教你部署 Waline 评论系统，使用 Vercel Postgres 数据库，10 分钟完成

Waline + Vercel Postgres 部署实战

本指南将手把手教你在 10 分钟内完成 Waline 评论系统的部署，使用 Vercel Postgres 数据库。

🎯 部署目标

完成本指南后，你将拥有：

✅ 一个完全免费的评论系统 ✅ 支持游客评论、点赞、回复 ✅ 自动适配亮色/暗色主题 ✅ 完整的管理后台 ✅ 数据存储在 Vercel Postgres

总耗时：约 10 分钟

📋 准备工作

需要的账号

  1. GitHub 账号（必须）

    • 用于登录 Vercel
    • 如果没有，访问 github.com 注册

  2. Vercel 账号（必须）

    • 使用 GitHub 账号登录即可
    • 完全免费

检查前端集成

确认以下文件已存在：

# 检查 Waline 组件
ls gocode-apps/site-astro/src/components/comments/WalineComments.astro

# 检查文章页面集成
grep -n "WalineComments" gocode-apps/site-astro/src/pages/wiki/[slug].astro

如果文件存在，说明前端已集成完成。✅

🚀 第一步：创建 Vercel Postgres 数据库（3 分钟）

1. 登录 Vercel

  1. 打开浏览器，访问：https://vercel.com
  2. 点击右上角 “Log In”
  3. 选择 “Continue with GitHub”
  4. 授权 Vercel 访问你的 GitHub 账号
  5. 完成登录

2. 创建数据库

  1. 在 Vercel 控制台，点击顶部导航栏的 “Storage”
  2. 点击 “Create Database” 按钮
  3. 选择 “Postgres”
  4. 配置数据库：
    • Database Name: waline-db
    • Region: 选择 “Hong Kong (hkg1)“（离中国最近）
  5. 点击 “Create” 按钮
  6. 等待数据库创建完成（约 30 秒）

3. 获取数据库连接字符串

  1. 数据库创建完成后，会自动跳转到数据库详情页
  2. 在 “Quickstart” 标签页，找到 “POSTGRES_URL”
  3. 点击右侧的 “Copy” 按钮复制连接字符串
  4. 连接字符串格式类似：
    postgres://default:AbCdEf123456@ep-cool-name-123456.us-east-1.postgres.vercel-storage.com:5432/verceldb
  5. ⚠️ 重要：将这个字符串保存到记事本，后面需要用到！

4. 验证数据库

在数据库详情页，点击 “.sql” 标签，可以看到数据库已经准备就绪。

🌐 第二步：部署 Waline 到 Vercel（5 分钟）

1. 访问一键部署链接

在浏览器中打开以下链接：

👉 https://vercel.com/new/clone?repository-url=https://github.com/walinejs/waline/tree/main/example

2. 配置仓库

  1. 如果提示登录，使用 GitHub 账号登录
  2. 在 “Create Git Repository” 部分：
    • Repository Name: waline-server（或其他你喜欢的名称）
    • Private: 保持默认（可以选择 Private）
  3. 点击 “Create” 按钮

3. 配置环境变量（重要！）

在 “Configure Project” 部分：

  1. 展开 “Environment Variables” 部分

  2. 添加以下环境变量：

    必填变量：

    NameValue
    PG_DB粘贴你刚才复制的 POSTGRES_URL

    可选变量（推荐添加）：

    NameValue说明
    SITE_NAMEGoCode网站名称
    SITE_URLhttp://localhost:4321网站地址（开发环境）
    AUTHOR_EMAILyour@email.com管理员邮箱（替换为你的邮箱）

    添加方法：

    • 在 “Name” 输入框输入变量名（如 PG_DB）
    • 在 “Value” 输入框输入变量值
    • 点击 “Add” 按钮
    • 重复以上步骤添加其他变量

4. 开始部署

  1. 确认所有环境变量已添加
  2. 点击页面底部的 “Deploy” 按钮
  3. 等待部署完成（约 2-3 分钟）
  4. 你会看到部署进度和日志

5. 获取服务器地址

  1. 部署成功后，页面会显示 “Congratulations!”
  2. 你会看到一个地址，类似：
    https://waline-server-abc123.vercel.app
  3. 点击 “Visit” 按钮访问你的 Waline 服务器
  4. 应该能看到 Waline 的欢迎页面（显示版本号和文档链接）
  5. ⚠️ 重要：将这个地址保存到记事本，后面需要用到！

🔧 第三步：更新前端配置（1 分钟）

方式一：使用配置脚本（推荐）

在终端中运行：

cd /Users/Lever/ownSpace/gocode/gocode-monorepo
./scripts/configure-waline.sh

然后输入你的 Waline 服务器地址（如 https://waline-server-abc123.vercel.app）。

方式二：手动修改

  1. 打开项目根目录下的 .env（本地）或 .env.production（生产）
  2. 写入环境变量：
    PUBLIC_WALINE_SERVER_URL=https://waline-server-abc123.vercel.app
  3. 保存文件并重启站点（开发环境重启 dev，生产环境重新构建发布）

🧪 第四步：测试评论功能（1 分钟）

1. 启动开发服务器

在终端中运行：

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

等待服务器启动，你会看到：

🚀 astro v5.16.8 started in 123ms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose

2. 访问文章页面

在浏览器中打开：

http://localhost:4321/wiki/waline-postgresql-guide

3. 测试评论

  1. 滚动到页面底部
  2. 应该能看到 Waline 评论框
  3. 输入以下信息测试：
    • 昵称：测试用户
    • 邮箱：test@example.com（可选）
    • 评论内容：这是第一条测试评论！
  4. 点击 “提交” 按钮
  5. 评论应该立即显示在页面上

4. 测试点赞

  1. 在评论下方，点击 ”👍” 图标
  2. 点赞数应该增加
  3. 再次点击可以取消点赞

5. 测试回复

  1. 点击评论下方的 “回复” 按钮
  2. 输入回复内容
  3. 点击 “提交”
  4. 回复应该显示在原评论下方

🎨 第五步：访问管理后台（可选）

1. 访问管理后台

在浏览器中打开：

https://waline-server-abc123.vercel.app/ui

（替换为你的服务器地址）

2. 设置管理员密码

  1. 首次访问会提示设置密码
  2. 输入你在环境变量中配置的 AUTHOR_EMAIL
  3. 设置一个强密码
  4. 点击 “注册”

3. 登录管理后台

  1. 使用邮箱和密码登录
  2. 你会看到管理后台界面

4. 管理功能

在管理后台，你可以：

  • 评论管理：查看、审核、删除评论
  • 用户管理：查看用户列表
  • 统计数据：查看评论数、访问量等
  • 配置设置：修改网站配置

✅ 部署检查清单

完成以下检查，确保部署成功：

  • Vercel Postgres 数据库已创建
  • 获取了数据库连接字符串（POSTGRES_URL）
  • Waline 已部署到 Vercel
  • 环境变量 PG_DB 已配置
  • 获取了 Waline 服务器地址
  • 前端配置已更新（PUBLIC_WALINE_SERVER_URL）
  • 开发服务器已启动
  • 评论框正常显示
  • 可以发表评论
  • 可以点赞评论
  • 可以回复评论
  • 管理后台可以访问

🐛 常见问题排查

问题 1：评论框不显示

可能原因：

  • 前端环境变量 PUBLIC_WALINE_SERVER_URL 不正确
  • Waline 服务器未正常运行

解决方法：

  1. 检查 .env / .env.production 中的 PUBLIC_WALINE_SERVER_URL
  2. 访问 Waline 服务器地址，确认服务正常
  3. 打开浏览器控制台（F12），查看错误信息

问题 2：评论提交失败

可能原因：

  • 数据库连接失败
  • 环境变量配置错误

解决方法：

  1. 访问 Vercel 控制台，检查部署日志
  2. 确认 PG_DB 环境变量正确
  3. 确认 Vercel Postgres 数据库正常运行

问题 3：评论提交后不显示

可能原因：

  • 启用了评论审核
  • 数据库写入失败

解决方法：

  1. 登录管理后台，检查是否有待审核的评论
  2. 检查 Vercel 部署日志
  3. 检查数据库连接

问题 4：管理后台无法访问

可能原因：

  • 服务器地址错误
  • 未设置管理员密码

解决方法：

  1. 确认访问的是 /ui 路径
  2. 首次访问需要设置密码
  3. 使用 AUTHOR_EMAIL 作为管理员邮箱

🎨 自定义配置

修改评论框样式

编辑 gocode-apps/site-astro/src/components/comments/WalineComments.astro：

<style>
  /* 修改评论框边框颜色 */
  :global(.wl-editor) {
    border-color: #3b82f6; /* 改为蓝色 */
  }

  /* 修改按钮颜色 */
  :global(.wl-btn) {
    background-color: #10b981; /* 改为绿色 */
  }

  /* 修改点赞按钮颜色 */
  :global(.wl-reaction) {
    color: #ef4444; /* 改为红色 */
  }
</style>

启用邮件通知

在 Vercel 环境变量中添加：

SMTP_SERVICE=Gmail
SMTP_USER=your@gmail.com
SMTP_PASS=your_app_password
SENDER_NAME=GoCode
SENDER_EMAIL=your@gmail.com

获取 Gmail 应用专用密码：

  1. 访问 Google 账号安全设置
  2. 启用两步验证
  3. 生成应用专用密码
  4. 使用该密码作为 SMTP_PASS

启用社交登录

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_client_id
GITHUB_SECRET=your_client_secret
  6. 重新部署 Waline

📊 数据库管理

查看数据库内容

  1. 访问 Vercel 控制台
  2. 点击 Storage → 选择 waline-db
  3. 点击 “.sql” 标签
  4. 可以执行 SQL 查询：
-- 查看所有评论
SELECT * FROM "wl_Comment" ORDER BY "createdAt" DESC LIMIT 10;

-- 查看评论统计
SELECT COUNT(*) as total FROM "wl_Comment";

-- 查看用户列表
SELECT * FROM "wl_Users";

备份数据库

Vercel Postgres 会自动备份，你也可以手动导出：

# 安装 Vercel CLI
npm install -g vercel

# 登录
vercel login

# 导出数据
vercel postgres backup

🔒 安全建议

1. 保护环境变量

  • ❌ 不要将 PG_DB 连接字符串提交到 Git
  • ❌ 不要在公开场合分享数据库凭证
  • ✅ 使用 Vercel 环境变量管理敏感信息

2. 启用评论审核

在 Vercel 环境变量中添加：

COMMENT_AUDIT=true

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

3. 配置垃圾评论过滤

在 Vercel 环境变量中添加：

AKISMET_KEY=your_akismet_key

可以在 Akismet 免费申请 API Key。

4. 限制评论频率

在 Vercel 环境变量中添加：

RATE_LIMIT=10

限制每个 IP 每 10 分钟最多发表 10 条评论。

📈 性能优化

1. 启用数据库连接池

Vercel Postgres 默认启用连接池，无需额外配置。

2. 启用评论缓存

Waline 会自动缓存评论，提升加载速度。

3. 启用 CDN

Vercel 自动为你的 Waline 服务器启用全球 CDN，无需额外配置。

🎯 部署完成后

立即可用的功能

✅ 游客评论：无需登录即可评论 ✅ 点赞功能：支持多种表情反应 ✅ 嵌套回复：支持多层回复 ✅ Markdown：支持 Markdown 语法 ✅ 表情包：内置微博、B站表情包 ✅ 暗色模式：自动适配主题 ✅ 响应式：完美适配移动端 ✅ 管理后台：完整的管理功能

下一步优化

  • 配置邮件通知
  • 添加 GitHub 登录
  • 启用评论审核
  • 配置垃圾评论过滤
  • 自定义评论样式
  • 添加评论统计

💰 成本说明

完全免费方案

  • Vercel 部署：免费

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

  • Vercel Postgres：免费

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

总成本：$0/月

升级方案（可选）

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

  • Vercel Pro：$20/月

    • 1 TB 带宽
    • 无限部署
    • 优先支持

  • Vercel Postgres Pro：$10/月

    • 10 GB 存储空间
    • 无限计算时间

🎊 恭喜你！

你已经成功部署了 Waline 评论系统！

你现在拥有

✅ 完全免费的评论系统 ✅ 数据存储在 Vercel Postgres ✅ 支持游客评论和点赞 ✅ 完整的管理后台 ✅ 自动适配主题

访问地址

相关资源

🆘 需要帮助？

如果遇到问题：

  1. 查看本指南的常见问题部分
  2. 查看 Waline 官方文档
  3. 检查 Vercel 部署日志
  4. 在 GitHub 提交 Issue

祝你使用愉快！🚀