dtonon/squalk 来源：https://github.com/dtonon/squalk

Squalk

Squalk 是一个基于 Nostr 构建的论坛，可用于管理小型或大型社区；实际上，你可以选择将其设置为“简单”或“完整”模式。简单模式展示一个单一论坛，而完整模式可以拥有任意数量的论坛。每个论坛在右侧边栏都包含一个聊天功能，方便与成员快速互动。

技术栈

Squalk 基于 Nostr 构建，并实现了 NIP-29 (https://github.com/nostr-protocol/nips/blob/master/29.md) 和 NIP-7D (https://github.com/nostr-protocol/nips/blob/master/7D.md)。它需要一个支持 NIP-29 的个人中继来托管群组，以及一个 Blossom 服务器用于文件上传；Pyramid (https://github.com/fiatjaf/pyramid) 包含了这两者，是推荐的解决方案。

配置

Squalk 完全通过环境变量进行配置（所有变量以 PUBLIC_ 为前缀，因为它们在浏览器端读取）。将 .env.example 复制为 .env 并填写相应的值；SvelteKit 也会读取 .env.development（用于 npm run dev）和 .env.production（用于 npm run build）。

自定义内容

Squalk 通过发布在同一中继上的 NIP-23 长文本事件（kind 30023）来填充其侧边栏链接，并个性化主页和联系人页面。只有由论坛管理员（其公钥列在群组 NIP-29 39001 管理员事件中）创作的事件才会被展示——中继查询是开放的，因此管理员集是信任门控。内容是纯 Markdown 格式。仓库根目录中的示例 .md 文件（about.md、guidelines.md、homepage.md、contacts.md）是你可调整并发布的起点。

资源（侧边栏链接）

资源出现在左侧边栏，并通过 /resource/ 路径提供服务。发布一个 kind 30023 事件，包含：

content 字段是 Markdown 正文。排序规则：具有 position 的资源优先显示，按升序排序；并列和未定位的资源按标题字母顺序排序。由于事件是可寻址的，使用相同 d 路径段重新发布会更新资源（最新版本生效）。

示例（从主页链接的 about 资源）：

kind: 30023
tags:
  ["t", "squalk-resource"]
  ["d", "about"]
  ["title", "About"]
  ["position", "1"]
content: |
  # About this forum
  ...

局部内容（主页和联系人）

局部内容将自定义 Markdown 注入固定插槽。正好有两个插槽：home（渲染在主页顶部）和 contacts（联系人页面）。发布一个 kind 30023 事件，包含：

对于一个插槽，最新的管理员创作的事件获胜。home 局部内容渲染在房间列表/讨论流之上；其单独一行开头的图片 URL（参见 homepage.md）将渲染为横幅图片。

开发

创建项目并使用 npm install（或 pnpm install 或 yarn）安装依赖后，启动开发服务器：

npm run dev
# 或启动服务器并在新的浏览器标签页中打开应用
npm run dev -- --open

构建

两个部署目标共享相同的代码库，通过 PUBLIC_SSR 选择：

• 静态（默认，PUBLIC_SSR=no） — npm run build（或 just build）将单页应用捆绑包写入 build/；将其从任何 Web 服务器提供服务，使用 index.html 作为未知路径的回退。所有内容由浏览器获取。
• 服务器渲染（PUBLIC_SSR=yes） — just build-ssr 将 Node 应用写入 build/。页面以可爬取的 HTML 形式到达（线程、房间、资源、联系人，带有描述/Open Graph 标签、JSON-LD、实时的 robots.txt 和 sitemap.xml，以及真实的 404 页面），然后浏览器接管，与静态构建完全一样。服务器匿名读取中继，因此它只渲染公共内容；成员在客户端运行后才能看到他们的私有房间。

使用 npm run preview（静态）或 node --env-file=.env.production build（服务器）在本地预览构建。

部署

just deploy <host> 使用 rsync 将静态捆绑包同步到主机的 ~/squalk/ 并清除 Cloudflare 缓存。 just deploy-ssr <mode> 使用 --mode <mode> 进行构建（因此 vite 会将 .env.<mode> 内置），传输 Node 构建产物、package.json/package-lock.json 和 .env.<mode>（在应用目录中作为 .env，因为服务器在运行时读取 PUBLIC_* 值），运行 npm ci --omit=dev 并重启实例的 systemd 单元。

所有特定于实例的内容都保存在 .env.<mode>.local（git 忽略，永不传输）中：DEPLOY_HOST、DEPLOY_DIR 和 DEPLOY_SERVICE（所有必需），以及用于缓存清除的 Cloudflare 凭据（CF_ZONE_ID/CF_API_TOKEN）。多个实例可以通过为每个实例分配自己的模式、目录、单元和端口来共存。

在主机上你需要：

• Node 22 或更新版本（中继客户端使用内置的 WebSocket）。
• 来自 deploy/production-example.service 的单元，将 ORIGIN 设置为公共 URL——它用于规范链接、robots.txt 和站点地图。
• 在 PORT 指定的端口前放置一个反向代理，替换之前提供静态文件的服务。使用 Caddy：

forum.example.com {
  reverse_proxy 127.0.0.1:3000
}

• 如果使用 Cloudflare，设置一个缓存规则来缓存 HTML 并尊重源站头：页面和快照使用 Cache-Control: public, max-age=0, s-maxage=<PUBLIC_SSR_CACHE_FRESH>, stale-while-revalidate=<PUBLIC_SSR_CACHE_STALE> 发送（默认提供五分钟，然后在后台刷新长达六小时），这与服务器自身内存缓存使用的时间窗口相同。just deploy-ssr 在每次发布后清除缓存。