评论系统部署文档（Waline 双项目架构）

本站由 GitHub Pages（博客）+ 两个 Vercel 项目（评论后端 / 登录中转）+ Supabase 数据库 组成。 本文档记录当前线上配置与完整部署步骤，含踩坑说明，供运维与故障排查使用。

零、当前线上地址

upcloudtech.cn 需持续续费：域名一旦过期，评论与 GitHub 登录会同时失效。

一、架构总览

访客浏览器
  │ 匿名评论 / GitHub 登录
  ▼
[项目 1] Waline 后端 (waline-blog)
  域名: waline.upcloudtech.cn
  ├─ 读写评论数据 ──> Supabase PostgreSQL
  └─ 登录跳转 ──> [项目 2] auth 中转
                    域名: auth.upcloudtech.cn
                    └─ GitHub OAuth ──> github.com

为什么要两个项目：Waline 默认走公共中转 oauth.lithub.cc，它会返回固定的 5 个社交按钮 （GitHub / 微博 / Twitter / Facebook / QQ），无法裁剪。自建 auth 后，中转按「配了哪些平台的 环境变量」动态返回服务列表——只配 GitHub 就只显示 GitHub。

二、DNS（阿里云云解析，upcloudtech.cn）

说明：

• 主机记录只填前缀，不要带 .upcloudtech.cn
• Vercel 面板的黄色「DNS Change Recommended」可忽略：它推荐的新专属 CNAME 值可能尚未上线 （实测解析为 Non-existent domain），旧值 cname.vercel-dns.com 官方承诺继续生效
• 博客必须有 docs/.vuepress/public/CNAME 文件（内容 ai.upcloudtech.cn），否则自定义域名 会返回 404「There isn't a GitHub Pages site here」

三、数据库（Supabase）

LeanCloud 国内版已停止新用户注册，改用 Supabase（免费 PostgreSQL，GitHub 账号登录即可）。

连接要点（关键坑）

• Vercel 函数只支持 IPv4 出站，必须用 Supabase 的 Transaction pooler 地址； 不能用直连地址 db.<ref>.supabase.co（仅 IPv6，会 ENOTFOUND）
• Pooler 端口 6543，用户名格式 postgres.<项目标识符>

建表 SQL

三个坑：like 和 2fa 是保留字/非法列名要加双引号；表名、字段名必须全小写（Waline 用小写查询）； wl_comment 必须有 url、status 列。

CREATE TABLE IF NOT EXISTS wl_comment (
  id BIGSERIAL PRIMARY KEY, user_id INTEGER, comment TEXT,
  insertedat TIMESTAMP DEFAULT NOW(), ip VARCHAR(100) DEFAULT '',
  link VARCHAR(255) DEFAULT '', mail VARCHAR(255) DEFAULT '',
  nick VARCHAR(255) DEFAULT '', pid INTEGER, rid INTEGER,
  sticky BOOLEAN DEFAULT FALSE, "like" INTEGER DEFAULT 0, ua VARCHAR(255),
  url VARCHAR(1024) DEFAULT '', status VARCHAR(10) DEFAULT 'approved'
);

CREATE TABLE IF NOT EXISTS wl_counter (
  id BIGSERIAL PRIMARY KEY, url VARCHAR(1024) DEFAULT '', time INTEGER DEFAULT 0,
  reaction0 INTEGER DEFAULT 0, reaction1 INTEGER DEFAULT 0,
  reaction2 INTEGER DEFAULT 0, reaction3 INTEGER DEFAULT 0,
  reaction4 INTEGER DEFAULT 0, reaction5 INTEGER DEFAULT 0,
  reaction6 INTEGER DEFAULT 0, reaction7 INTEGER DEFAULT 0,
  reaction8 INTEGER DEFAULT 0
);

CREATE TABLE IF NOT EXISTS wl_users (
  id BIGSERIAL PRIMARY KEY, display_name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL, password VARCHAR(255) NOT NULL,
  type VARCHAR(50) NOT NULL, label VARCHAR(50) DEFAULT '',
  url VARCHAR(255) DEFAULT '', avatar VARCHAR(255) DEFAULT '',
  github VARCHAR(255) DEFAULT '', twitter VARCHAR(255) DEFAULT '',
  facebook VARCHAR(255) DEFAULT '', google VARCHAR(255) DEFAULT '',
  weibo VARCHAR(255) DEFAULT '', qq VARCHAR(255) DEFAULT '',
  "2fa" VARCHAR(255) DEFAULT '', createdat TIMESTAMP DEFAULT NOW(),
  updatedat TIMESTAMP DEFAULT NOW()
);

四、项目 1：Waline 后端（waline-blog）

部署：Vercel → Import walinejs/waline 的 example 模板（官方一键部署链接见 Waline 文档）。

环境变量（数据库用 PG_*，不是 POSTGRES_*——后者不被识别，报 No valid storage found）：

改任何环境变量后必须 Redeploy 才生效。

域名：waline.upcloudtech.cn（阿里云 CNAME → cname.vercel-dns.com，再到 Vercel 项目 Domains 添加）

五、管理员注册（重要）

1. 访问 https://waline.upcloudtech.cn/ui/register 注册
2. 第一个用「邮箱 + 密码」注册的账号自动成为管理员
3. 登录 https://waline.upcloudtech.cn/ui/ 后可见「评论管理」「用户管理」等菜单

判定规则与常见坑：

• 管理员身份存在 wl_users.type 字段（值为 administrator），可查可改：

  SELECT id, display_name, email, type FROM wl_users ORDER BY id;
  UPDATE wl_users SET type = 'administrator' WHERE email = '<邮箱>';
• GitHub 社交登录 ≠ 管理员：社交登录创建的是独立 guest 身份，除非把该身份的 wl_users 行改成 administrator
• 浏览器里残留旧 token 时，会出现「明明是管理员却被跳到个人资料页」——先退出登录 （或 F12 → Application → Local Storage 清空 https://waline.upcloudtech.cn）再用邮箱密码登录
• 登录用户可删除自己的评论；匿名评论只能由管理员删除

六、项目 2：auth 中转（只保留 GitHub 登录按钮）

部署步骤：

1. GitHub 上 Fork walinejs/auth（注意是 auth 仓库，不是 waline）
2. Vercel → Add New → Project → Import 这个 fork
   • 列表里看不到：GitHub → Settings → Applications → Vercel → 调整仓库授权范围
   • Framework Preset 选 Other
3. 环境变量只配两个：
   • GITHUB_ID = GitHub OAuth Client ID
   • GITHUB_SECRET = GitHub OAuth Client Secret
4. Deploy
5. 域名：阿里云加 auth CNAME → Vercel auth 项目 Domains 添加 auth.upcloudtech.cn

GitHub OAuth App 配置（GitHub → Settings → Developer settings → OAuth Apps）：

关键：域名必须绑在 auth 项目上。若 auth.upcloudtech.cn 打开是 Waline 管理后台（fengsKB 标志 + 5 个图标），说明域名绑错到 waline-blog 了——去 waline-blog 的 Domains 移除，再到 auth 项目添加。

让 Waline 使用自建中转：waline-blog 加环境变量 OAUTH_URL = https://auth.upcloudtech.cn → Redeploy。

验证：

七、能力边界与已知限制

GitHub 登录在国内的现实：OAuth 授权必须让浏览器跳转 github.com，而国内直连常报 ERR_CONNECTION_TIMED_OUT。此时点「登录」是死路。若希望访客体验干净，可在 theme.ts 的 comment 配置里把 login 改成 "disable"，只保留匿名评论（访客不再看到登录按钮）。

八、故障排查速查