使用说明

怎么在本地把这个站跑起来、怎么部署、每日热点从哪来,以及 /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 这个文件。

  1. proxy.ts 拦住 /my。没有有效会话就转到 /my-gate。
  2. /my-gate 把密码发给 /api/my-gate,在服务器上核对。
  3. 核对的是 MY_PASSWORD。比较用的是派生后的值,并做了常数时间比较。
  4. 通过之后发一个 httpOnly 的会话 cookie。关掉浏览器就失效。页面上没有登出按钮。
  5. 短时间里失败太多次,接口会暂时拒绝。密码不会写进日志。
  6. /api/my/ 下面的保存和上传不走跳转,而是用同一份 cookie 做同样的常数时间比较。没通过就返回 401。

工作室里可以:

  • 写文章:Markdown,旁边能预览。草稿不会出现在公开博客,选「发布」之后才会。可以填分类、标签和封面。封面上传到 Blob。
  • 调首页:原来的五段可以排序、隐藏或删除。也可以新加文字、图片墙、链接列表、作品、时间线、嵌入,以及再加一段开场、最新文章或热点。
  • 改作品和关于页。关于页用 Markdown,## 标题会变成页面上的卡片。
  • 嵌入只接受 https 地址,页面里用不能跑脚本的框架装着,旁边留一个「在新页面打开」。

公开博客读数据库里已发布的文章。数据库不可用时,仍显示 lib/data.ts 里的示例。单篇有目录、阅读时间,以及较新、较旧两篇的链接。订阅地址是 /feed.xml,页脚和博客页都能打开。

文件和主题约定见手册。改动记录见修改日志。