部署指南
本文说明如何部署自己的 OPC 站点：创建数据库、配置登录与图片存储、部署网站，再认领站主并发布内容。收款、事务邮件和分身可按需开通。
项目 README 提供快速开始，下面按操作顺序展开。
0. 部署准备
| 项 | 说明 |
|---|
| GitHub 账号 | 保存本站代码，并授权 Vercel 读取对应仓库 |
| Supabase 账号 | https://supabase.com；创建项目前以 Dashboard 显示的可用项目额度与费用为准 |
| Vercel 账号 | https://vercel.com，建议用 GitHub 登录（免配 token） |
| 域名（可选） | 无域名可先用 Vercel 分配的 *.vercel.app；先验证目标地区可达性 |
| 本机环境 | Node.js ≥ 22（与 CI 一致）、git、一个 IDE |
自查命令：
node --version # 期望 v22.x 或更高
git --version
1. 获取源码与安装工具
可通过 README 的部署按钮创建自己的仓库，也可 fork 后克隆到本机。使用指定版本的源码包时，按下面的方法创建仓库，后续在 Vercel 导入这个仓库即可。
在 GitHub 创建空白私有仓库，不要勾选自动生成 README、.gitignore 或 License。将以下 ZIP 文件名替换为实际文件名，先核对随包提供的 SHA-256；GitHub 地址替换为刚创建的仓库地址。示例使用解压后根目录直接包含 README.md 的源码包：
shasum -a 256 ./wanyouai-source.zip # 与随包提供的 SHA-256 比对
mkdir wanyou-site
unzip ./wanyouai-source.zip -d ./wanyou-site
cd ./wanyou-site
git init -b main
git add .
git commit -m "Import wanyouai source"
git remote add origin https://github.com/<YOUR_ACCOUNT>/<YOUR_REPO>.git
git push -u origin main
进入本机源码根目录，安装后续预检和图片桶配置工具需要的依赖，再复制环境模板：
npm ci
cp .env.example .env.local
.env.local 只保存在本机。数据库密码、服务端密钥、支付资料和登录链接均不提交到 Git。
仓库内 public/images/ 的三张图片只获准随本系统展示和部署，不按代码 MIT 条款开放独立复用，详见图片许可。建立自己的 OPC 品牌时，在「首页与导航」分别为浅色、深色横幅从素材库选图，在「站主名片」选择自己的头像和 Logo；不要把示例头像或 Logo 当作自己的身份。
2. Supabase 项目创建与初始化
2.1 创建项目
- Supabase Dashboard → New project；
- 选组织、起名（例如
my-opc-site）、设置数据库密码并仅在自己的密码管理器保存；不要把密码发给协作者或放进仓库；
- Region 按实际受众与合规需求选；创建前核对 Dashboard 显示的套餐与费用；
- 等待约 2 分钟初始化完成。
2.2 取连接信息（后续填 Vercel）
打开自己的 Supabase 项目，点击顶部 Connect 复制 Project URL；进入 Settings → API Keys 取得密钥：
| 页面字段 | 对应环境变量 |
|---|
| Project URL | NEXT_PUBLIC_SUPABASE_URL |
| Publishable key；旧项目可用 Legacy anon key | NEXT_PUBLIC_SUPABASE_ANON_KEY（变量名不变） |
| Secret key；旧项目可用 Legacy service_role key | SUPABASE_SERVICE_ROLE_KEY（变量名不变；只进服务端环境变量，绝不进浏览器/仓库） |
将这三项填入本机 .env.local。同一文件的基础部署组还需填写 OWNER_EMAIL、自行生成的 PUBLISH_TOKEN 和 SITE_URL；站点尚未部署时，SITE_URL 可先填 http://localhost:3000。参数获取方法见 .env.example 的逐项注释。未启用功能的可选值保持空白。
2.3 Dashboard 安全开关（必须核对）
Dashboard → Integrations → Data API：在 Overview 核对 Data API，在 Settings 核对新表自动暴露。
Enable Data API ON
Automatically expose new tables OFF
有些 Dashboard 版本不显示独立的“Enable automatic RLS”开关。可在 SQL Editor 运行只读查询确认平台自动 RLS 触发器已启用：
select e.evtname, e.evtenabled, p.proname
from pg_event_trigger e join pg_proc p on p.oid = e.evtfoid
where e.evtname = 'ensure_rls';
期望返回 ensure_rls / O / rls_auto_enable。O 代表触发器在普通会话启用。如果项目没有该触发器，仍必须继续使用安装文件对每张应用表显式启用 RLS，并在部署前确认 verify.sql 的 application_rls_enabled = true；不要为了寻找 UI 开关而跳过安装验证。自动 RLS 与 Data API 的新表自动暴露是两个不同设置。
2.4 按序执行 SQL（SQL Editor 逐个新建查询粘贴执行）
新装要求 PostgreSQL 17 或更高版本。仅在全新、未使用的项目中依次完整执行以下文件，每个文件成功后再执行下一个。结构版本与文件摘要见数据库发布清单。
supabase/install.sql
supabase/verify.sql
- install：一次性建立最终结构、权限与中性站点配置；失败整体回滚。检测到既有应用对象会停止，应改走升级路径；
- verify：返回只读验收表，所有
passed 必须为 true；出现 false 或 SQL 错误时停止部署并排查；
- 新装不开通支付 / 分身，不设置销售价格，也不创建站主；指定
OWNER_EMAIL 完成验证登录后认领；
- 站主认领后可从
/admin/setup 载入使用指南与收费方案页，无需额外执行演示 SQL；
- 禁止在实际生产执行
supabase/tests/rls-fixtures.sql；
- 已有实例按数据库升级指南操作，不执行新装文件或演示 SQL；切换到 CLI 管理升级前，先按迁移历史衔接核对实际结构与迁移记录。
保存 .env.local 后，从源码根目录运行 npm run doctor，按输出修正 error / incomplete 项。该预检只检查配置形态，不验证 Dashboard 设置或外部连通性。
后续向 Vercel 导入变量时，省略未启用的空值项。配置来源与本地环境文件加载顺序见环境契约。
2.5 配置图片存储
Dashboard → Storage → New bucket：
Name: media
Public: ON（公开只读；写入由服务端 service_role 完成）
桶名自定义时，环境变量 SUPABASE_STORAGE_MEDIA_BUCKET 同步同名（默认 media）。建议桶限制单文件 10 MiB，允许 PNG / JPEG / WebP / GIF；SVG 由服务端转成 PNG 后上传。
素材库还需一个固定名称 media-uploads 的 Private 暂存桶，10 MiB、允许上述格式及 SVG；不授予普通账户对象访问权。可用下面的工具一次配置两个桶，详见素材库说明。
也可在配置服务端环境的本地安全终端运行 npm run storage:setup 只读预检，确认目标项目后执行 npm run storage:setup -- --apply。工具通过 Storage API 初始化 / 限制桶，不改已有公开属性，不上传或删除文件。私有包桶按需增加 --packages；已有桶公开属性不符合预期时需要先检查内容再手动处理。对象写权限仍须按安全契约检查 RLS。
2.6 配置 Auth 回调地址
Dashboard → Authentication → URL Configuration。站点尚无独立部署地址时，先用本机地址；取得预发布或生产域名后，再把 Site URL 与两条精确回调同步改为对应 HTTPS 域名。避免以 /** 作为正式站点的长期回调规则：
Site URL: http://localhost:3000
Redirect URLs: http://localhost:3000/auth/callback
http://localhost:3000/login/callback
# 有独立测试或正式站点后，再为那个域名分别加入上述两个路径
- 在 Resend 验证自己的发件域，创建该域的发送权限 API Key。
- Supabase Authentication → Emails → SMTP Settings 启用自定义 SMTP。Host 填
smtp.resend.com，Port number 填 465（SSL/TLS），Username 填 resend，Password 填完整 Resend API Key（不加 Bearer）；Sender email address 使用已验证域下的发件地址，Sender name 填自己的站名，然后保存。
- 在 Email Templates 的 Confirm sign up 和 Magic link or OTP 两处，都粘贴 login.html 的完整内容并保存。保留
{{ .Token }} 和 {{ .ConfirmationURL }}，分别覆盖新用户首次与已有用户再次登录；不要只修改其中一处。
- 在 Email 设置中核对 OTP 有效期，在 Rate Limits 核对发信限额，关闭供应商链接跟踪；分别验证站主、新普通用户和已有普通用户能收到验证码并完成登录。
Supabase 默认 SMTP 只向项目组织成员发信，不能用于公开登录；新 Free 项目的默认 SMTP 还有限制模板编辑的规则，保存自定义 SMTP 后可编辑。登录邮件不由 Vercel 的 RESEND_API_KEY / EMAIL_FROM 控制，不依赖应用邮件队列。电脑发起登录、手机收信时可直接在电脑输入验证码；邮件链接须在发起登录的同一浏览器及设备打开。各项限制与官方依据见上述邮箱登录指南。
3. Vercel 部署
3.1 导入仓库
- 打开 https://vercel.com/new → Import Git Repository，选择第 1 节准备的仓库。
wanyou-site 是建议的 Vercel 项目名；仓库名称以自己的 GitHub 仓库为准。通过 README 部署按钮已创建 Vercel 项目时，进入该项目继续配置。
- Framework Preset 自动识别 Next.js，Root Directory 保持
./，不要改构建命令（package.json 已指定 webpack 构建）。核对 Production Branch 为你仓库的 main。
3.2 配置环境变量（Deploy 前的 Environment Variables 面板一次填全）
| 变量 | 值 | 说明 |
|---|
SITE_URL | https://你的项目.vercel.app（上域名后改） | 末尾不带 / |
NEXT_PUBLIC_SUPABASE_URL | 2.2 节 Project URL | 可进浏览器 |
NEXT_PUBLIC_SUPABASE_ANON_KEY | 2.2 节 Publishable / Legacy anon key | 可进浏览器 |
SUPABASE_SERVICE_ROLE_KEY | 2.2 节 Secret / Legacy service_role key | 仅服务端 |
PUBLISH_TOKEN | 自生成随机串（openssl rand -hex 32） | 发布凭据；外部调度优先单独设置 CRON_SECRET |
OWNER_EMAIL | 本站站主邮箱 | 全新部署首次认领只允许这个邮箱；验证码或链接登录前先配置 |
SUPABASE_STORAGE_MEDIA_BUCKET | media | 与 2.5 节一致才填，默认可省 |
RESEND_API_KEY + EMAIL_FROM | （可选）事务邮件 | 两值同配启用；权益邮件任务持久保存，发送还需下述调度 |
ZPAY_BASE_URL + ZPAY_PID + ZPAY_KEY | （可选）在线收款 | 三值同配且 base 必须 HTTPS；未配置前台如实显示「暂未开通在线收款」 |
CRON_SECRET | 随机密钥 | 部署者在 Vercel 环境变量中设置；配置后 Vercel Cron 才会随请求自动携带。也可让外部 cron 使用 PUBLISH_TOKEN |
各项的复制入口、自生成方法和格式见环境变量获取指南及 .env.example的逐项注释。Vercel 的 Value 不加外层引号；批量导入前删除未启用的空值行。环境入口也可从 Settings → Environments → Production → Environment Variables 进入；Preview 应使用独立测试配置。
3.3 部署与验收
- Deploy。打开 Vercel 项目 → Deployments，确认最新部署详情为 Ready / Production，Source 是自己仓库的
main 及预期提交。
- 复制该 Production 部署显示的固定站点域名；若与预填
SITE_URL 不同，先到 Settings → Environment Variables → Production 修正 SITE_URL，然后从 main 重新部署。更新 Supabase Authentication → URL Configuration 的 Site URL 和 /auth/callback、/login/callback Redirect URLs 后再发起站主登录邮件。
- 打开固定 Production 域名：尚未发布内容时，首页各栏目应显示空态。
/card 与 /card.json 可访问、/llms.txt 无付费正文。- Vercel 项目 → Settings → Crons 可见
expiry-reminder 每日任务（来自仓库 vercel.json，无需手配）。
4. 域名配置（可选）
- Vercel 项目 → Settings → Domains → Add，输入你的域名（如
www.example.com）；
- 到域名服务商，按 Vercel 页面为该域名给出的记录类型、名称和值配置 DNS；
- 等待 Vercel 签发 HTTPS 证书（通常几分钟）；
- 同步站点地址：
- Vercel 环境变量
SITE_URL → https://www.example.com，然后 Redeploy；
- Supabase → Authentication → URL Configuration：Site URL 与 Redirect URLs 换成正式域名；
- 已启用 zpay 时，新订单自动使用更新后的
SITE_URL 生成回调与返回地址。仍有待支付订单时保留旧域名可访问，直到这些订单完成处理。
- 国内受众注意：域名需备案且 Vercel 访问性不稳定时，另行评估地区可达性与部署合规要求，本指南步骤不变、仅平台替换。
5. 首次设置与功能检查
- 认领站主：用 Vercel
OWNER_EMAIL 指定的邮箱访问 https://你的域名/admin，输入邮件验证码或在同一浏览器打开登录链接。首次成功登录后，该邮箱成为唯一站主。
- 检查配置与载入示例：进入后台「部署检查」
/admin/setup，确认配置、数据库版本和图片桶。保留“载入示例内容”的勾选可创建“收费方案”和“使用指南”，取消勾选则从空站开始。导入中断时回到该页继续；遇到网址冲突或内容已修改时按提示处理。升级已有站点不会自动载入示例。
- 填写名片：在「站主名片」填写站名、站主、一句话，以及公开联系邮箱或预约页面（二选一）。服务语言用
zh-CN、en 等代码。保存后检查首页、/card 和 /card.json；发布的服务条目也会同步到机器名片。
- 发布内容与配置导航：在「内容管理 → 文章」发布一篇带图 Markdown，检查前台正文和图片。测试受限阅读时，设置访问权限，在编辑器中用
⌘/Ctrl + Shift + P 插入付费墙以划定公开预览范围。在专辑或独立页面设置中配置侧栏名称与顺序，保存后确认前台导航更新。
- 收款（可选）：配置 zpay 后，在「首页与导航 → 在线收款」勾选已开通渠道并保存，前台付费内容出现购买按钮。使用自己的测试商品完成付款，确认订单和权益。
- 事务邮件（可选）：配置 Resend 和每分钟
/api/cron/mail-outbox 调度，核对付款后的通知任务、发送收据和买家收信。每日到期提醒不负责发送此队列，详细动作与故障核对见邮件运维。
- 安全检查：在 Supabase Dashboard → Advisors 查看告警，按安全配置核对受影响对象与权限；ERROR 项处理后再开放站点。
- 到期提醒任务：在 Vercel Crons 日志确认每日
expiry-reminder 任务实际执行。手动检查可在安全终端运行 curl -H "Authorization: Bearer $PUBLISH_TOKEN" https://你的域名/api/cron/expiry-reminder，成功应返回 {"summary":...}。
检查页只有站主可见，执行只读检查，不显示密钥；远程错误明确显示为未通过。手动配置项保持「待人工验收」，本页不会持久记录手工验收结论。修改环境变量后重新部署，再点击「刷新检查」。Vercel Cron 使用 CRON_SECRET，外部调度可用 PUBLISH_TOKEN；需单独确认任务实际执行。
在无痕窗口打开固定 Production 域名，确认首页无需登录 Vercel；普通账户不能进入站主管理页面。发布一篇带图内容后，分别检查匿名预览和有权限账户的正文显示。
如果保存站点配置时显示超时或后台暂不可用，先到 Supabase → Logs 按时间和 /rest/v1/site_config 路径核对写入状态，并只读检查 site_config.updated_at。写入已成功时不要重复提交；页面报错可能发生在保存后的重新读取。若登录、公开配置和页面列表同时超时，从运行应用的环境检查到 Supabase 项目 URL 的 DNS、代理路由及出站 HTTPS，再复测 /admin/card、/card、/card.json。向维护者反馈时提供页面地址、发生时间、状态和耗时，隐藏密钥、邮箱与配置正文。
6. 更新与日常维护
首次上线前及数据库升级前，按备份与恢复指南备份数据库、Auth、Storage 对象和迁移历史，并在独立空项目验证恢复。后台内容 ZIP 用于内容复用，不包含整站恢复所需的全部材料。
- 版本更新：先查看版本说明，在测试环境确认升级步骤，再更新自己的 Git 仓库并由 Vercel 部署。自行修改代码的验证方法见贡献指南；
- 数据库升级：先备份，再按升级指南执行目标版本缺失的迁移；已有实例不重跑
install.sql / demo.sql；
- 回滚：切换应用部署不会还原数据库。先按升级说明确认旧应用兼容当前数据库，再选择 Vercel 中已验证的部署；数据库和文件恢复按备份指南执行；
- 密钥轮换：Vercel 改环境变量后 Redeploy 生效；
PUBLISH_TOKEN / zpay key 泄露时同流程轮换。