使用说明
怎么在本地把这个站跑起来、怎么部署、每日热点从哪来,以及 /my 在做什么。
本地运行
需要 Node.js 20 或更新版本。
npm install
npm run dev浏览器打开 http://localhost:3000 。
检查:
npm run lint
npm run build环境变量
名字写在 .env.example 里。本地复制成 .env.local 再填值。.env.local 不要提交。线上在 Vercel 的 Environment Variables 里设置同名变量。不要把值写进代码、仓库或聊天。
MY_PASSWORD:进入/my的密码。没设置时,密码门拒绝所有访问,这是故意的。DATABASE_URL:Neon Postgres 的池化连接串。应用代码只读这个名字。没设置时,构建和公开页面仍然可用,内容用仓库里的示例;工作室里的保存会失败,并说明原因。BLOB_READ_WRITE_TOKEN:Vercel Blob 的读写令牌,用来上传封面和区块图片。没设置时,上传会失败,其它页面照常打开。文字内容只要数据库在,仍然可以保存。
Vercel 可能还会注入 DATABASE_URL_UNPOOLED、POSTGRES_URL 这类名字。站点不用它们。
部署
站点部署在 Vercel,线上地址是 https://personal-website-aw61.vercel.app 。
仓库默认分支是 main。推送到 main 之后,Vercel 会重新构建。目前用的是 Vercel 子域名,还没有自定义域名。
预览部署开着 Vercel Authentication。生产、预览、开发都要有上面的环境变量(开发环境可以不放 MY_PASSWORD,那样本地进不了 /my)。
数据库表怎么出现
不需要在自己的电脑上跑迁移脚本。第一次有 DATABASE_URL 的请求会在 Neon 里执行 CREATE TABLE IF NOT EXISTS,建文章、首页区块、作品、关于页和一张标记表。
如果这些表还是空的,并且标记表里还没有 seeded,会把仓库里现有的示例文章、示例作品、首页原来的五段和关于页文案抄进去一份,然后写上标记。之后再删内容,不会自动填回来。
数据库暂时连不上时,公开页面改回示例内容,不返回 500。工作室的写入返回 503,页面上会写明没保存。
每日热点
首页「今日热点」读的是 data/hot.json。
更新由 GitHub Actions 做:.github/workflows/daily-hot.yml。
- 每天 UTC 00:00(北京时间 08:00)跑一次
- 也可以在 Actions 页面手动跑
workflow_dispatch - 脚本是
scripts/fetch-hot.mjs - 技术来源:Hacker News,失败时用 DEV
- 动画来源:Anime News Network 的公开 RSS
- 只保存标题和链接,不搬全文
- 某一类抓不够 3 条时,保留这一类昨天的数据,并在页面上标明是昨日数据
- 如果没有能用的旧数据,脚本不会改文件
本地想自己抓一次:
node scripts/fetch-hot.mjs历书
/almanac 读的是 data/almanac.json,不在每次打开页面时请求 GitHub。
更新由 GitHub Actions 做:.github/workflows/almanac.yml。
- 每天 UTC 00:30(北京时间 08:30)跑一次
- 也可以在 Actions 页面手动跑
workflow_dispatch - 脚本是
scripts/fetch-almanac.mjs - 数据来自 GitHub GraphQL 的公开贡献日历,只记
qihaiqianqiu777的公开贡献 - 不读取仓库名,也不把私有贡献算进去
- 工作流使用已有的
GITHUB_TOKEN。不要把令牌的值写进仓库、页面或聊天 - 某一天抓失败时,如果仓库里已经有一份可用快照,脚本不改文件
本地想自己抓一次,在已经登录 gh 或者设置了 GITHUB_TOKEN 的环境里运行:
node scripts/fetch-almanac.mjs/my 是怎么挡住的
/my 是私人工作室,不出现在导航、页脚和 sitemap 里。追剧记录还在里面的「追剧」分页,数据仍在 lib/dramas.ts,公开页面不要 import 这个文件。
proxy.ts拦住/my。没有有效会话就转到/my-gate。/my-gate把密码发给/api/my-gate,在服务器上核对。- 核对的是
MY_PASSWORD。比较用的是派生后的值,并做了常数时间比较。 - 通过之后发一个 httpOnly 的会话 cookie。关掉浏览器就失效。页面上没有登出按钮。
- 短时间里失败太多次,接口会暂时拒绝。密码不会写进日志。
/api/my/下面的保存和上传不走跳转,而是用同一份 cookie 做同样的常数时间比较。没通过就返回 401。
工作室里可以:
- 写文章:Markdown,旁边能预览。草稿不会出现在公开博客,选「发布」之后才会。可以填分类、标签和封面。封面上传到 Blob。
- 调首页:原来的五段可以排序、隐藏或删除。也可以新加文字、图片墙、链接列表、作品、时间线、嵌入,以及再加一段开场、最新文章或热点。
- 改作品和关于页。关于页用 Markdown,
##标题会变成页面上的卡片。 - 嵌入只接受 https 地址,页面里用不能跑脚本的框架装着,旁边留一个「在新页面打开」。
公开博客读数据库里已发布的文章。数据库不可用时,仍显示 lib/data.ts 里的示例。单篇有目录、阅读时间,以及较新、较旧两篇的链接。订阅地址是 /feed.xml,页脚和博客页都能打开。